The Surface data type represents a cloud of points in a three-dimensional space. The represented point cloud is organized in a precisely defined way. The X coordinate values of the points create an arithmetic progression, and the same goes for the Y coordinate values. Therefore the whole Surface object has a grid structure, which enables to spare a lot of memory in the point cloud representation. It also allows to define regions of interest for a Surface object.
The aforementioned grid structure is described by four values: offsets and scales on X and Y axes, named: XOffset, XScale, YOffset, YScale. The values denotes that the cloud points in the first row of the grid have the Y coordinate equal to YOffset, in the second row the Y coordinate is: YOffset + YScale, in the third row it is: YOffset + 2 * YScale and so on. Similarly, the points in the consecutive columns of the grid have the X coordinate equal to XOffset, XOffset + XScale, XOffset + 2 * XScale and so on.
The Z coordinate values are stored in the same way as the values in an Image object. Just as in there, the Surface values are represented in a one of 6 possible primitive types: sint8, uint8, sint16, uint16, sint32 and real. To obtain the resulting value of the Z coordinate, the value stored has to be multiplied by ZScale and ZOffset has to be added. For every point in the cloud however it is possible that it does not exist. In this case a special value of Z is stored to mark that the point is missing.
- Single Surface object can allocate no more than 2GB of memory.
- Maximum Surface single dimension should not exceed 65535 (because regions use 16-bit integers for performance reasons).
int Width()- returns number of grid columns
int Height()- returns number of grid rows
int Pitch()- returns byte-distance between consecutive rows
PlainType Type()- returns type used for representing Z values
double XOffset()- returns X axis offset
double XScale()- returns X axis step
double YOffset()- returns Y axis offset
double YScale()- returns Y axis step
double ZOffset()- returns Z axis offset
double ZScale()- returns Z axis step
double X( int xIndex )- returns X coordinate of points in the xIndex column
double Y( int yIndex )- returns Y coordinate of points in the yIndex row
double Z( int xIndex, int yIndex )- returns Z coordinate of the point defined by given indices
void* Data()- returns pointer to point cloud data buffer
T* RowBegin<T>( int i )- returns pointer to first point in grid row
T* RowEnd<T>( int i )- returns pointer to first after last point in grid row
T* Ptr<T>( int x, int y )- returns pointer to point at specified coordinates
T& Value<T>( int i )- allows to access Z coordinate value at specified coordinates
T Infinity<T>()- returns the value used for representing a missing point