Points API

scanimage.mroi.coordinates.Points is the value class that ScanImage® uses to move coordinates around. A Points object is an N x dimensions numeric array plus the coordinate system that array is expressed in. Nothing in the coordinate system API accepts a bare numeric array of positions - wrapping the numbers is what makes a transformation unambiguous.

Note

Points is a value class, not a handle class. Every method returns a new object; none of them modify the original. hPts.append(...) without capturing the result does nothing.

Construction

hPts = scanimage.mroi.coordinates.Points(hCoordinateSystem,points);
hPts = scanimage.mroi.coordinates.Points(hCoordinateSystem,points,UserData);

hCoordinateSystem - a scalar, valid scanimage.mroi.coordinates.CoordinateSystem.
points - numeric N x dimensions array. The column count must match hCoordinateSystem.dimensions or the constructor throws.
UserData - optional payload carried along with the points.

hCSRef = hSI.hCoordinateSystems.hCSReference;

% three points in reference space
pts = [0 0 0; 1 0 0; 0 1 5];
hPts = scanimage.mroi.coordinates.Points(hCSRef,pts);

Properties (all immutable)

Property	Description
`hCoordinateSystem`	The coordinate system the points are expressed in.
`points`	The `N x dimensions` numeric array.
`numPoints`	`N`.
`dimensions`	Number of columns of `points`.
`UserData`	Whatever was passed to the constructor.

Transforming

hPtsOut = hPts.transform(hCoordinateSystem);

Returns a new Points object expressed in hCoordinateSystem. transform works on arrays of Points as well, transforming each element. It is equivalent to hCoordinateSystem.transform(hPts).

% a point at the center of the field of view, in several spaces
hPt = scanimage.mroi.coordinates.Points(hSI.hCoordinateSystems.hCSFocus,[0 0 0]);

hPtRef    = hPt.transform(hSI.hCoordinateSystems.hCSReference);      % optical degrees, um in z
hPtSample = hPt.transform(hSI.hCoordinateSystems.hCSSampleRelative); % um
hPtScan   = hPt.transform(hSI.hScan2D.hCSZAffineLut);                % current scanner space

fprintf('sample-relative position: %.2f %.2f %.2f um\n',hPtSample.points);

Transforming into the coordinate system a Points object already lives in is a no-op and returns the object unchanged, so it is cheap to call defensively.

Warning

A transform fails if the two coordinate systems are not in the same tree, or if a node along the path cannot be traversed in the required direction (see forwardable and reversible in Coordinate System Classes). Both cases raise an error naming the offending coordinate systems.

Manipulating point sets

Method	Description
`hPts.subset(idxs)`	Select rows `idxs`. Works on arrays of `Points`, applying the same indices to every element.
`hPts.filter(idxs)`	Select rows `idxs` of a scalar `Points` object.
`hPts.remove(idxs)`	Delete rows `idxs`.
`hPts.append(pts)`	Append rows. `pts` may be a numeric array or another `Points` object, in which case it is transformed into this object’s coordinate system first.
`hPts.insert(pts,idx)`	Insert rows before row `idx`, with the same conversion rule as `append`.

hPts = hPts.append([2 2 0]);          % numeric, assumed to be in hPts.hCoordinateSystem
hPts = hPts.append(hOtherPts);        % transformed automatically
hPts = hPts.remove(1);                % drop the first point

Arithmetic

plus and minus are overloaded:

hPtSum  = hPtA + hPtB;   % hPtB transformed into hPtA's coordinate system, then added
hPtSum  = hPtA + [0 0 5];
hPtDiff = hPtA - hPtB;

The result is always expressed in the coordinate system of the left operand. A numeric right operand is taken to be in that same coordinate system.

Note

+ and - operate on the raw coordinates. Adding two points that live in spaces with different units is meaningless even though the transform makes it legal - the left operand decides the units.

Display

disp is overloaded to print the coordinate system, the point count and the coordinates, truncating the middle for sets larger than 50 points:

>> hPt = hSI.hMotors.getPosition(hSI.hCoordinateSystems.hCSSampleRelative)

Coordinate System: Sample Relative (scanimage.mroi.coordinates.CSLinear)
     Number Of Points: 1

        0    0   12.5