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

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

- (make-manifold label domain-spec codomain-spec internal-missing-values? initial-value)
- (make-manifold label domain-spec codomain-spec internal-missing-values?)
- (make-real-grid label domain-spec codomain-spec internal-missing-values? initial-value)
- (make-real-grid label domain-spec codomain-spec internal-missing-values?)
- (make-integer-grid label domain-spec codomain-spec internal-missing-values? initial-value)
- (make-integer-grid label domain-spec codomain-spec internal-missing-values?)

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.

- (topological-type precision (low1 high1) (low2 high2) ...)

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.

Basic information about a sheet can be retrieved using the accessors

- (sheet-domain sheet) returns an output whose format is similar to the specification input to the sheet creation functions
- (sheet-codomain sheet) is similar
- (sheet-label sheet) returns a string
- (sheet-supports-missing-values? sheet) returns a boolean
- (sheet-storage-group sheet) returns the sheet's storage group (good up to eq)

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.

- (sheet-min-sample sheet)
- (sheet-max-sample sheet)
- (focus-min-sample sheet)
- (focus-max-sample sheet)

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

- (in-focus-area sample)

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

- (restrict-sheet min-sample max-sample)

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.

- (storage-group-representative storage-group) returns a sheet
- (list-storage-groups) returns a list of storage groups
- (remove-sheet sheet) deallocates a sheet (and all other sheets in its storage group)

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.

- (rescale-domain sheet multiplier)
- (offset-domain sheet point-offset)
- (offset-domain sheet coord1-offset coord2-offset ...)
- (rescale-codomain sheet multiplier)
- (offset-codomain sheet point-offset)
- (offset-codomain sheet coord1-offset coord2-offset ...)

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

- (sheet-ref sheet point)
- (sheet-ref sheet coord1 coord2 ...)

(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

Last modified