Although values can be retrieved from any location in a manifold, values actually only exist at a finite set of sample locations. Programmers must have access to the sample locations in order to set values and construct scanning operations. Direct access to the sample locations can also be used for more efficient retrieval of values, because it circumvents the interpolation, scaling, and offset required to retrieve values at arbitrary points in the domain. Finally, it prevents potential numerical instabilities when the sheet's scaling and/or offset are not integers.
Operations using samples include
A sample is a direct pointer into a sheet. Its internal representation contains the sheet and the coordinates of the sample. These coordinates are raw locations in the storage array, without scaling or offset. The coordinates may lie outside the bounds of the storage array: references outside the storage array will return a missing value.
Because the sheet abstraction protects the user from the raw coordinates in the storage array, particularly for manifolds, the user cannot directly specify a sample's coordinates. In particular, because coordinates in the domain may be offset by a floating point number, the samples may not lie at integer locations. Samples must be created by a snap-to-grid process:
Samples on the extreme corners of the sheet or focus area can be retrieved using sheet-min-sample, sheet-max-sample, focus-min-sample, and focus-max-sample. These are described on the sheets page
Once a sample has been extracted, it can be used as a guidepost for moving around the sheet's sample grid. For example, a typical scanner must enumerate all the samples in a sheet's focus area. Topological algorithms such as edge tracking and extraction of connected components must be able to move from a sample to the immediately adjacent samples.
Adjacent or nearby samples can be found using shift-sample, which produces a new sample at the specified displacement in the sample grid. The displacement must be an exact integer point (or equivalent coordinates) and is in sample units not the normal sheet units.
The function sample-offset computs the vector displacement of sample1 relative to sample2, in sample coordinates.
The sample inequality functions, allow one to compare the locations of two samples along one of the coordinate axes (n).
It should probably be an error to apply the sample inequalities to sheets of different dimensionality. However, the current implementation does not check for this.
In some cases, it is possible to emulate the behavior of these operations by extracting the corresponding points and using normal arithmetic operations. However, this is extremely bad practice as the code may be longer, less efficient, more prone to errors (such as incorrectly adjusting for difference in sheet domain scalings), and/or numerically unstable.
Sample-offset and the sample inequalities can be applied to two samples associated with different sheets. However, the results may be meaningless unless you first establish how the sample locations in the two sheets are related. There is no guarantee that the sample at location (0.0,1.0) in one manifold has the same sample coordinates as the sample at location (0.0, 1.0) in another manifold. You must first establish corresponding sample locations in the two sheets.
For example, suppose that you are scanning through one sheet and would like to efficiently extract corresponding sample locations in a second sheet. First, extract two samples sa and sb in the first sheet (e.g. the extreme corners of the focus area). Then extract two samples SA and SB from the second sheet in a similar way. Use sample-offset to calculate the displacement from the first to the second sample in the two sheets. That is, d=(sb-sa) and D=(SB-SA).
If the vector D is not an integer multiple of the vector d, stop. You have a problem with incompatible scalings and must use point references. Otherwise, compute the (exact integer) change in scaling between the sheets, call it M, as
Now, suppose that you produce a sample sx inside your loop. The corresponding sample SX in the second sheet can be computed as
Ownership, Maintenance and Disclaimers
Last modified