RoiManager

scanimage.components.RoiManager, reachable as hSI.hRoiManager, decides what is scanned. It holds the ROI groups used for imaging and derives the resulting timing.

Default ROI properties

When mroiEnable is false ScanImage scans a single scanfield derived from the properties below. They are the programmatic equivalent of the main acquisition controls.

Property	Description
`pixelsPerLine`	Horizontal resolution. Default 512.
`linesPerFrame`	Vertical resolution. Default 512.
`scanZoomFactor`	Zoom. Must be >= 1.
`scanRotation`	Counter-clockwise rotation of the scanned area about Z, in degrees.
`scanAngleMultiplierFast`, `scanAngleMultiplierSlow`	Scale the fast and slow scanner output.
`scanAngleShiftFast`, `scanAngleShiftSlow`	Shift the fast and slow scanner output, in field-of-view coordinates.
`forceSquarePixelation`	When true, `linesPerFrame` follows `pixelsPerLine`.
`forceSquarePixels`	When true, `scanAngleMultiplierSlow` is constrained so that pixels stay square.

hSI.hRoiManager.pixelsPerLine  = 1024;
hSI.hRoiManager.scanZoomFactor = 2;
hSI.hRoiManager.scanRotation   = 15;

ROI groups

Property	Description
`mroiEnable`	When false, scan the single default scanfield. When true, scan `roiGroupMroi`. Cannot be changed while focusing.
`scanType`	`'frame'` or `'line'`. Selects frame scanning or arbitrary line scanning.
`roiGroupMroi`	The `scanimage.mroi.RoiGroup` used for MROI focus / grab / loop.
`roiGroupLineScan`	The ROI group used for arbitrary line scanning.
`currentRoiGroup`	Dependent, read-only. The ROI group that will actually be scanned given the current settings - the default single-scanfield group when `mroiEnable` is false.
`currentRoiGroup_`	Same, but the getter skips regenerating the default ROI group. Use it in code that runs at frame rate; use `currentRoiGroup` everywhere else.

hRoiGroup = scanimage.mroi.RoiGroup();
% ... add Rois and scanfields ...

hSI.hRoiManager.roiGroupMroi = hRoiGroup;
hSI.hRoiManager.mroiEnable   = true;

Derived timing and geometry

All read-only.

Property	Description
`scanFrameRate`	Frames per second.
`scanFramePeriod`	Seconds per frame.
`linePeriod`	Seconds per line.
`scanVolumeRate`	Volumes per second.
`imagingFovDeg`	Corner points of the scanned area, in optical degrees.
`imagingFovUm`	Corner points of the scanned area, in microns.

fprintf('%.2f fps, %.1f x %.1f um\n', hSI.hRoiManager.scanFrameRate, ...
    range(hSI.hRoiManager.imagingFovUm(:,1)), range(hSI.hRoiManager.imagingFovUm(:,2)));

Methods

Method	Description
`hSI.hRoiManager.saveRoiGroupMroi(filename)`	Save `roiGroupMroi` to a `.roi` file. Opens a file dialog when `filename` is omitted.
`hSI.hRoiManager.loadRoiGroupMroi(filename)`	Load a ROI group from file into `roiGroupMroi`.
`hSI.hRoiManager.backupRoiGroup()`	Snapshot the current ROI group so it can be restored after an acquisition.
`hSI.hRoiManager.resetTransforms()`	Reset the scanner-relative transforms applied to ROIs.
`hSI.hRoiManager.normalizeScannerAspectRatio(hScanner,aspectRatio)`	Adjust a scanner’s field of view so that its aspect ratio matches `aspectRatio`.
`hSI.hRoiManager.saveScan2DProps()` / `restoreScan2DProps()`	Cache and restore the `Scan2D` properties the ROI manager overrides for the current scan type. Used internally when switching between frame and line scanning.

Events

pixPerLineChanged and imagingRoiGroupChanged fire when the resolution or the imaging ROI group changes. Both are hidden but usable by GUI code that needs to invalidate a cache.