CoordinateSystems Component

scanimage.components.CoordinateSystems, reachable as hSI.hCoordinateSystems, owns the root of ScanImage’s coordinate system tree and is responsible for persisting every node’s calibration to disk.

It is a ScanImage component that also implements most.HasClassDataFile, most.HasMachineDataFile and dabs.resources.configuration.HasConfigPage.

Root coordinate systems

Property	Description
`hCSWorld`	`CSLinear`, 3D. The root of the tree. Everything in ScanImage is ultimately a descendant of World.
`hCSReference`	`CSLinear`, 3D, child of World. The common space that scanners, cameras and the stage are all aligned to. Its origin is the focal point of the objective when FastZ is at zero.
`hCSFocus`	`CSLinear`, 3D, child of Reference. The focal point including the current FastZ defocus. ScanImage keeps its `toParentAffine` equal to a pure z translation by `hSI.hFastZ.position`, updated by a listener. The node is locked, so it is never loaded from or reset by the class data file.
`hCSSampleAbsolute`	Dependent, forwards to `hSI.hMotors.hCSSampleAbsolute`.
`hCSSampleRelative`	Dependent, forwards to `hSI.hMotors.hCSSampleRelative`.

hSI.hCoordinateSystems.hCSWorld
hSI.hCoordinateSystems.hCSReference
hSI.hCoordinateSystems.hCSFocus
hSI.hCoordinateSystems.hCSSampleRelative   % same object as hSI.hMotors.hCSSampleRelative

Note

hCSSampleAbsolute and hCSSampleRelative are created and owned by hSI.hMotors, because the chain that leads to them describes the stage. hCoordinateSystems only re-exports them for convenience.

Other properties

Property	Description
`tfObjectivePointingDown`	Logical, default `true`. Whether the objective points down towards the sample. This is used for display purposes. Persisted in the machine data file.
`classDataFileName`	Full path of the `.mat` file the coordinate system definitions are stored in. Read-only from user code; see below.

Methods

Method	Description
`hSI.hCoordinateSystems.plot()`	Open a window visualizing the entire coordinate system tree. The quickest way to see which nodes exist on a given system.
`hSI.hCoordinateSystems.reset()`	Walk the tree and call `reset()` on every node. Locked nodes are skipped. This discards all alignments - scanner-to-reference, stage, cameras, SLM.
`hSI.hCoordinateSystems.save()`	Write the current tree to the class data file. Runs automatically when ScanImage exits.
`hSI.hCoordinateSystems.load()`	Reload the tree from the class data file, discarding unsaved changes.
`hCS = hSI.hCoordinateSystems.getCoordinateSystemByName(name)`	Look a node up by its `name` (case-insensitive). Useful for nodes that are not exposed as a named property, for example `'Motor Alignment'`.
`hSI.hCoordinateSystems.showConfig()`	Open the configuration page for the component.

hCS = hSI.hCoordinateSystems.getCoordinateSystemByName('Motor Alignment');
disp(hCS.toParentAffine);

Warning

reset() invalidates every alignment on the microscope at once. Save a copy of the class data file before calling it.

Persistence

Coordinate system definitions are stored in a MATLAB .mat class data file rather than in the machine data file, because they are calibration data rather than configuration.

The machine data file heading Coordinate System holds classDataFileName and tfObjectivePointingDown.
Only the bare file name is persisted. The file is always resolved inside <classDataDir>\CoordinateSystems\, so a machine data file that was copied from another system cannot pull in an unrelated folder’s alignment.
The default file name is default-CoordinateSystems_classData.mat.

Because the file is selectable, one microscope can keep several sets of alignments - for example one per objective - and switch between them from the SI Coordinate Systems configuration page.

Serialization walks the tree and calls toStruct on every node; loading matches stored structs to live nodes by name. A node that is present on disk but missing from the tree is skipped, and a node that is locked ignores the stored value entirely.

% which file is the current alignment stored in?
hSI.hCoordinateSystems.classDataFileName

Component behavior

CoordinateSystems is not an acquisition-active component - componentStart and componentAbort do nothing, and no properties are restricted during an acquisition.

reinit() is called by scanimage.SI after the Scan2D components have been constructed, so that scanner nodes already exist in the tree when the class data file is applied. It also installs listeners that

rebuild the FastZ listener set whenever hSI.hScan2D changes, and
update hCSFocus whenever hSI.hFastZ.position changes.