-----

Sheets

-----

Sheets are the primary data structure used to represent bulk data. Therefore, Envision supports a wide variety of functions for manipulating sheets.

Creation

Sheets are created using the functions make-manifold, make-real-grid, and make-integer-grid.

If internal missing values are allowed, the initial-value argument may be omitted. In this case, values in the sheet are initialized to a missing value.

The domain-spec and codomain-spec have the following form, where topological-type = 'flat, 'circle, 'tube, or 'torus. (For a tube, the first coordinate is circular.) The current implementation allows the domain to be flat 1D, flat 2D, a circle, a tube, or a torus. It allows the codomain to be flat 1D, flat 2D, flat 3D, or a circle.

The high and low bounds on the ranges, as well as the precision, must match the type of sheet: integer or real as appropriate.

In each range list, (high1 - low1) must be a multiple of precision. When the numbers involved are real (e.g. the sheet is a manifold), the difference must be no more than 10% of the precision.

The label required by the creation functions is a string describing the contents of the sheet. It can be freely chosen by the user.

Accessing a sheet's description

Basic information about a sheet can be retrieved using the accessors

Operations such as scanners must be able to create samples on the extreme edges of the sheet, and on the extreme edges of its focus area. The following operations return samples on the extreme corners of these regions: the sample with minimum position on all coordinate axes and the sample with maximum position on all coordinate axes. These two samples are sufficient for testing whether a position lies within the sheet or focus area. Samples at other extreme positions (e.g. at other corners of the sheet) can be constructed from them.

A primitive is also provided for testing whether a sample lies in the focus area of its sheet.

Storage groups and modification of sheets

The focus area of a newly created sheet covers the entire sheet. A new sheet can be created by defining a smaller focus area:

Both of the samples must come from the same sheet, which is how restrict-sheet know what sheet to restrict. The new sheet that is created has a focus area that is just big enough to contain both the argument samples. The new sheet shares storage with the old sheet. That is, it belongs to the same storage group.

Storage groups do not have access to all their associated sheets (for obvious practical reasons). However, they retain access to one representative sheet, the first one created. Storage groups, but not sheets, are registered in a central table. Thus, all currently allocated storage groups can be listed. By inspecting (e.g. displaying) a representative from each storage group, the user can analyze his or her space usage.

Distinct sheets in the same storage group can also be created by shifting or rescaling the sheet's domain or codomain. This affects how locations and stored values appear to the user, but not the actual data stored in the sheet.

Extracting values

Values are retrieved from sheets using the function sheet-ref.

(Because a single number is considered a point, the syntactic variation does not create ambiguity.)

It is an error to reference an integer-grid or a real-grid at a point that is not a grid location. Thus, the input coordinates, or the coordinates of the input point, must be exact integers. Furthermore, the distance from the location to the location in the sheet with minimum coordinates must be a multiple of the sheet's precision. (Use the function sheet-domain to retrieve the information required to create coordinates satisfying this constraint.)

There is no function sheet-set! because one cannot, in general, set an arbitrary location in a sheet. This is done using samples.

-----

Ownership, Maintenance and Disclaimers

Manual Top Page

Last modified