MibImageDocument¶

class controllers.MibImageDocument¶

Bases: handle

MIBIMAGEDOCUMENT - Controller for a single image document (FigureDocument + ImageViewDocument component).

This class encapsulates a single image document view in MIB, managing the FigureDocument container, ImageViewDocument component, and all associated callbacks including mouse interactions and brush cursor visualization.

Example 1 - create new image document:

doc = controllers.MibImageDocument(obj.mibController, obj.view, ...
    'Dataset 1', docGroupTag, 1, obj.mibModel);

Example 2 - add to document group:

obj.view.gui.add(doc.figureDoc);

Example 3 - update description:

doc.setDescription('Buffer 1: myimage.tif');

Example 4 - update brush cursor:

doc.updateBrushCursor([100, 100], ':');

Example 5 - access the class:

obj.mibController.cImageDoc{obj.mibModel.Sets.selectedSet}

Notes - the brushSelection property holds state for the Brush tool as a 3-element cell array, scaled with respect to magFactor and the image crop within the viewing window at the time of computation:

brushSelection{1} - painting state

.selection - contains brush selection during drawing

.travelPathInPixels - distance the brush travelled during painting

brushSelection{2} - labels of the superpixels (SLIC) and related info

.slic - a label image with superpixels

.selectedSlic - a bitmap image of the selected superpixels

.selectedSlicIndices - indices of the selected SLIC superpixels

.selectedSlicIndicesNew - freshly selected SLIC indices when moving the brush, used for the undo with Ctrl+Z

.CData - a copy of the shown image in imageAxes, used for the undo

brushSelection{3} - state for the adaptive mode

.meanVals - array of mean intensity values for each superpixel

.mean - mean intensity value for the initial selection

.std - standard deviation of intensities for the initial selection

.factor - factor defining the allowed STD variation

Constructor Summary

MibImageDocument(mainCtrl, view, title, docGroupTag, setOfDatasetsIndex, model)¶

MIBIMAGEDOCUMENT - Create a new MibImageDocument controller.

Syntax:

function obj = MibImageDocument(mainCtrl, view, title, docGroupTag, setOfDatasetsIndex, model)

Creates a FigureDocument with an embedded ImageViewDocument component, configures axes properties, and sets up all necessary callbacks for mouse interactions and navigation controls.

Input Arguments:

mainCtrl - controllers.MibController, main MIB controller
view - MibView, main MIB view
title - char, title for the document tab
docGroupTag - char, document group tag for MDI grouping
setOfDatasetsIndex - double, index of this document (typically current set number)
model - models.MibModel, main MIB model

Output Arguments:

obj - controllers.MibImageDocument, the created controller instance

Usage:

docCtrl = controllers.MibImageDocument(obj.mibController, obj.view, ‘Buffer 1’, ‘imageViewGroup’, 1, obj.mibModel);

Property Summary

UIFigure¶: handle to underlying UIFigure

axesDecorationSize¶

4); cached in controllers.MibController.listener_updateDatasetAxes and used by obj.gui_SizeChangedFcn

Type:¶

[width, height] in pixels, fixed margin between UIFigure.Position(3

Type:¶

and imViewAxes.InnerPosition(3

brushCursor¶: matlab.graphics.chart.primitive.Line, handle to brush cursor plot

brushCursorMagFactor¶: scalar double, magFactor used when brushCursorOffset was last computed

brushCursorOffset¶: 2×N double array, [X offsets; Y offsets] for brush cursor circle

brushPrevXY¶: coordinates of the previous pixel for the Brush tool, [x, y] or []

brushSelection¶: selection layer during the brush tool movement, see class docstring for the cell layout

centralMarker¶: marker for the center of the axes

figureDoc¶: matlab.ui.internal.FigureDocument, the document container

gui¶: views.components.ImageViewDocument, the ImageViewDocument component

handles¶: struct with ImageDocument component handles (axes, buttons, etc.)

imageHandle¶: handle to the rendered image

isInsideAxes¶: switches that are updated within obj.gui_WinMouseMotionFcn

isInsideImage¶: indicating the cursor inside the image frames

lastSliderRenderTime¶: tic id of the last throttled slider redraw (wall-clock throttle)

listeners¶: cell array with handles to listeners

mibController¶: controllers.MibController, handle to main controller

mibModel¶: models.MibModel, handle to the main model

quickMeasure¶

.roi .textH .datasetId .lastPos; or []

Type:¶: struct with active quick measurement

setOfDatasetsIndex¶: double, index of this document in the Sets

sliderDebounceTimer¶: timer used to debounce rapid slider dragging (Zarr virtual datasets);

sliderDragging¶: true while the user is actively dragging a slice/frame slider

sliderTShiftStep¶: t-slider step with shift pressed obj.sliceNumberSlider_ContextMenu

sliderTStep¶: t-slider step, can be updated in obj.sliceNumberSlider_ContextMenu

sliderThrottleInterval¶: min seconds between slider-driven redraws (~25 fps)

sliderZShiftStep¶: z-slider step with shift pressed obj.sliceNumberSlider_ContextMenu

sliderZStep¶: z-slider step, can be updated in obj.sliceNumberSlider_ContextMenu

trackerYXZ¶: [y; x; z] coordinates for the Membrane ClickTracker tool starting point

view¶: MibView, handle to the main view

wasInsideAxes¶: mouse was inside the image axes

Method Summary

axesCenterPointerLocation(cursorOverAxes)¶

AXESCENTERPOINTERLOCATION - Screen-pixel location of this document’s image axes centre.

Syntax:

[pointerX, pointerY] = obj.axesCenterPointerLocation()
[pointerX, pointerY] = obj.axesCenterPointerLocation(cursorOverAxes)

Returns the value to assign to groot().PointerLocation so that the OS mouse cursor lands at the centre of this document’s imViewAxes.

Two strategies are used:

Runtime self-calibration (preferred) - when cursorOverAxes is true (the caller knows the cursor is currently over this document’s axes, e.g. zoom or middle-click recenter), the target is computed from the live offset between groot().PointerLocation and the figure’s CurrentPoint. Only a small in-axes displacement is converted, so this needs no window/monitor/chrome geometry and works identically docked, floating, on any monitor and (for small displacements) any scaling.
Geometric reconstruction (fallback) - used when the cursor is not over the axes (e.g. ribbon-triggered orientation switch). Derives the absolute screen position from the docked main window or the floating document window; relies on the AppContainer chrome insets +9 / +31 for the docked case.

Input Arguments:

cursorOverAxes (optional) - [logical] whether the OS cursor is currently over this document’s axes (default: false)

Output Arguments:

pointerX - [double] horizontal pointer location in screen pixels
pointerY - [double] vertical pointer location in screen pixels

See also

listener_updateDatasetAxes, showImage, updateBrushCursor

gui_WinMouseMotionFcn()¶

GUI_WINMOUSEMOTIONFCN - Callback for mouse movement over the figure window.

Syntax:: function gui_WinMouseMotionFcn(obj)

This function is called on every mouse movement. It: - Updates cursor position display in the status bar - Tracks mouse movement distance for user statistics - Retrieves and displays pixel values under cursor - Manages brush cursor visibility based on axes boundaries

Uses persistent variables to prevent callback re-entrance and improve performance during rapid mouse movements.

Input Arguments:: none
Output Arguments:: none

gui_WindowBrushMotionFcn(structElement)¶

GUI_WINDOWBRUSHMOTIONFCN - Draw the brush trace during use of the brush tool.

Syntax:

obj.gui_WindowBrushMotionFcn(structElement)

Called on every mouse movement while the brush tool is active. Rasterizes the line from previous cursor position to current one, dilates it with the structural element, and updates the selection overlay on displayed image. Supports both normal brush and superpixel-assisted (SLIC/Watershed) modes.

Input Arguments:

structElement - [double matrix] circular structural element for brush dilation (generated in segmentationBrush.m)

Output Arguments:

(none)

Usage note - typically called as a callback, not directly:

hFig.WindowButtonMotionFcn = @(~,~)obj.gui_WindowBrushMotionFcn(structElement);

gui_WindowButtonDownFcn()¶

GUI_WINDOWBUTTONDOWNFCN - Callback for mouse button press in the image view.

Syntax:

obj.gui_WindowButtonDownFcn()

Linked via:

hFig.WindowButtonDownFcn = @(~, ~)obj.gui_WindowButtonDownFcn();

Input Arguments:

(none)

Output Arguments:

(none)

Behavior:

Dispatches to either 'pan' or 'interact' mode depending on SelectionType + modifier keys and “swap mouse buttons” state
'Pan' mode temporarily disables other callbacks and attaches motion/up callbacks to implement click-and-drag panning
'Interact' mode triggers segmentation/annotation tools depending on selected segmentation tool

gui_WindowButtonUpDragAndDropFcn(mode, diffX, diffY, BatchOptIn)¶

GUI_WINDOWBUTTONUPDRAGANDDROPFCN - Commit the drag-and-drop shift on mouse button release.

Syntax:

obj.gui_WindowButtonUpDragAndDropFcn(mode)
obj.gui_WindowButtonUpDragAndDropFcn(mode, diffX, diffY)
obj.gui_WindowButtonUpDragAndDropFcn(mode, diffX, diffY, BatchOptIn)

Input Arguments:

mode - [char] mode for drag-and-drop action:
- '2D, Slice' - drag all selection on current slice
- 'Object2D' - drag selected object only on current slice
- '3D, Stack' - drag all selection for all slices
- 'Object3D' - drag selected 3D object
diffX (optional) - [double] shift in X direction (pixels); when empty, calculated from mouse position
diffY (optional) - [double] shift in Y direction (pixels); when empty, calculated from mouse position
BatchOptIn (optional) - [struct] batch processing mode:
- .Target - [char] layer to be moved
- .Mode - [char] part of dataset to be moved
- .shiftX - [numeric] X-shift in pixels
- .shiftY - [numeric] Y-shift in pixels
- .showWaitbar - [logical] show progress bar

Output Arguments:

(none)

Example - shift 5px right, 3px up:

obj.gui_WindowButtonUpDragAndDropFcn('2D, Slice', 5, -3);

gui_WindowButtonUpFcn(brush_switch)¶

GUI_WINDOWBUTTONUPFCN - Callback for release of the mouse button.

Syntax:

obj.gui_WindowButtonUpFcn()
obj.gui_WindowButtonUpFcn(brush_switch)

Linked via:

hFig.WindowButtonUpFcn = @(~,~)obj.gui_WindowButtonUpFcn();

Performs three tasks in order:

If brush data exists (obj.brushSelection is a cell), commits drawn brush stroke to selection layer, applying fill-holes, material/mask restriction, and add/subtract mode
Clears brush state and updates ROI screen positions
Restores all figure callbacks and pointer disabled during panning or brush operation, then triggers full image refresh

Input Arguments:

brush_switch (optional) - [char] brush mode: when 'subtract', brush stroke is removed from current selection instead of being added (needed for eraser mode); default: '' (add mode)

Output Arguments:

(none)

gui_WindowDragAndDropMotionFcn(brushSelection)¶

GUI_WINDOWDRAGANDDROPMOTIONFCN - Visual feedback during drag-and-drop: brightens displaced pixels.

Syntax:

obj.gui_WindowDragAndDropMotionFcn(brushSelection)

Input Arguments:

brushSelection - [uint8 matrix] image of selected layer area

Output Arguments:

(none)

gui_WindowKeyPressFcn_BrushSuperpixel(eventdata)¶

GUI_WINDOWKEYPRESSFCN_BRUSHSUPERPIXEL - Handle key callbacks during brush superpixel mode.

Syntax:: function gui_WindowKeyPressFcn_BrushSuperpixel(obj, eventdata)

Currently supports Ctrl+Z to undo the last selected superpixel during an active superpixel brush stroke.

Input Arguments:

eventdata - KeyData structure with fields: - .Key - name of the key pressed, in lower case - .Character - character interpretation of the key - .Modifier - cell array of modifier key names (‘control’, ‘shift’, ‘alt’)

Output Arguments:

(none)

Usage:

@code % typically set as a callback, not called directly: hFig.WindowKeyPressFcn = @(hWidget, hData)obj.gui_WindowKeyPressFcn_BrushSuperpixel(hData); @endcode

gui_panAxesFcn(xy, imgXLim, imgYLim)¶

GUI_PANAXESFCN - Move the image in obj.handles.imViewAxes during a pan gesture.

Syntax:

obj.gui_panAxesFcn(xy, imgXLim, imgYLim)

This is the WindowButtonMotionFcn callback active while the mouse button is held during panning. Installed by gui_WindowButtonDownFcn:

hFig.WindowButtonMotionFcn = @(~,~)obj.gui_panAxesFcn(xy2, imgXLim, imgYLim);

Input Arguments:

xy - [1×2 double] axes data-unit coordinates of mouse at moment button was first pressed (from gui_WindowButtonDownFcn)
imgXLim - [1×2 double] [xMin, xMax] data-coord boundaries of displayed image (left and right edges); [1, imgWidth] for full image, [paddedX(1), paddedX(2)] for padded region
imgYLim - [1×2 double] [yMin, yMax] data-coord boundaries of displayed image (top and bottom edges)

Output Arguments:

(none)

listener_frameChanged()¶

LISTENER_FRAMECHANGED - Listener callback for the MibModel ‘FrameChanged’ event.

Syntax:

obj.listener_frameChanged()

Synchronises the frame-number edit box and slider of this image document with the current time point stored in the model (slices{5}), then redraws the image.

Called automatically when:

notify(obj.mibModel, 'FrameChanged');

Important notes:

The caller must update mibModel.I{id}.slices{5} to the new frame value BEFORE firing the event
This method guards against changes from different documents in split-panel mode (selectedSet ~= setOfDatasetsIndex)
Updates widgets DIRECTLY; does NOT delegate to frameNumber_Callback or frameNumberSlider_Callback (which would create an infinite loop by firing FrameChanged themselves)

Input Arguments:

(none - called via @(~,~) obj.listener_frameChanged())

Output Arguments:

(none)

Example - wired in setupCallbacks:

obj.listeners{end+1} = addlistener(obj.mibModel, 'FrameChanged', ...
    @(~,~) obj.listener_frameChanged());

listener_sliceChanged()¶

LISTENER_SLICECHANGED - Listener callback for the MibModel ‘SliceChanged’ event.

Syntax:

obj.listener_sliceChanged()

Synchronises the slice-number edit box and slider of this image document with the current z-slice stored in the model, then redraws the image.

Called automatically when:

notify(obj.mibModel, 'SliceChanged');

Important notes:

This method guards against changes from different documents in split-panel mode (selectedSet ~= setOfDatasetsIndex)
Updates widgets DIRECTLY; does NOT delegate to sliceNumber_Callback or sliceNumberSlider_Callback (which would create an infinite loop by firing SliceChanged themselves)

Input Arguments:

(none - called via @(~,~) obj.listener_sliceChanged())

Output Arguments:

(none)

Example - wired in setupCallbacks:

obj.listeners{end+1} = addlistener(obj.mibModel, 'SliceChanged', ...
    @(~,~) obj.listener_sliceChanged());

recalculateObjects()¶

RECALCULATEOBJECTS - Recalculate objects for Mask or Model layer for Object Picker tool in 3D.

Syntax:

obj.recalculateObjects()

Populates the maskStats structure of the active dataset with connected component information (label matrix and bounding boxes, or PixelIdxList for models with >65535 materials).

Input Arguments:: (none)
Output Arguments:: (none)

Example - recalculate object stats:

obj.recalculateObjects();

renderSlider(sliderType, value)¶

RENDERSLIDER - Commit a slider value to the model and redraw the image.

Syntax:

obj.renderSlider(sliderType, value)

Thin wrapper that records the render time (for throttling) and delegates to the matching slider callback, which updates the model slice/frame and redraws. Used both for direct (throttled) renders during dragging and as the TimerFcn of the Zarr debounce timer, so it guards against the document being torn down.

Input Arguments:

sliderType - [char] 'slice' or 'frame'
value - [numeric] slider position value to commit

Output Arguments:

(none)

See also

sliderDragCallback, sliceNumberSlider_Callback, frameNumberSlider_Callback

segmentBlackWhiteThreshold(BatchOptIn)¶

SEGMENTBLACKWHITETHRESHOLD - Perform black and white thresholding for the BW Threshold tool.

Syntax:

obj.segmentBlackWhiteThreshold()
obj.segmentBlackWhiteThreshold(BatchOptIn)

Tool from the Segmentation panel.

Input Arguments:

BatchOptIn (optional) - [struct|NaN] batch processing mode; when NaN, returns default structure via “syncBatch” event:
- .Mode - [char] '2D', '3D', or '4D' - apply thresholding for current slice, stack, or whole dataset
- .MinValue - [numeric] minimum intensity or Sensitivity value for thresholding
- .MaxValue - [numeric] maximum intensity or Width value for thresholding
- .ColorChannel - [numeric] color channel for thresholding
- .FixSelectionToMask - [logical] apply thresholding only to masked area
- .FixSelectionToMaterial - [logical] apply thresholding only to selected material area
- .Adaptive - [logical] enable adaptive thresholding (use MinValue for Sensitivity, MaxValue for Width)
- .AdaptiveInvert - [logical, adaptive only] invert dataset before adaptive thresholding
- .AdaptiveForegroundPolarity - [char, adaptive only] determine which pixels are foreground
- .Target - [char] 'selection' or 'mask' - destination layer for thresholding
- .showWaitbar - [logical] show progress bar during execution

Output Arguments:

(none)

Example 1 - apply thresholding with current widget settings:

obj.segmentBlackWhiteThreshold();

Example 2 - batch mode with provided options:

obj.segmentBlackWhiteThreshold(BatchOpt);

segmentationAnnotation(y, x, z, t, modifier, options)¶

SEGMENTATIONANNOTATION - Add or remove a text annotation at the given dataset coordinate.

Syntax:

obj.segmentationAnnotation(y, x, z, t, modifier)
obj.segmentationAnnotation(y, x, z, t, modifier, options)

Adds a new annotation (empty modifier), removes the closest annotation (Ctrl), or interpolates annotations along Z between the last and the current position (Shift).

Input Arguments:

y - [double] y-coordinate of annotation point in full-dataset pixels
x - [double] x-coordinate of annotation point in full-dataset pixels
z - [double] z-coordinate (slice index) of annotation point
t - [double] t-coordinate (time point) of annotation point
modifier - [char|cell] modifier keys held during click:
- '' or {} - add annotation to list
- 'control' or {'control'} - remove closest annotation
- 'shift' or {'shift'} - interpolate annotations between last and current position along Z
options (optional) - [struct] additional settings:
- .samInteractiveModel - [logical] when true, triggers segmentationSAM after adding annotation (default: false)

Output Arguments:

(none)

Example 1 - add annotation:

obj.segmentationAnnotation(50, 75, 10, 1, {});

Example 2 - remove closest annotation:

obj.segmentationAnnotation(50, 75, 10, 1, {'control'});

Example 3 - interpolate annotations:

obj.segmentationAnnotation(50, 75, 10, 1, {'shift'});

segmentationBall3D(y, x, z, modifier, BatchOptIn)¶

SEGMENTATIONBALL3D - Do segmentation using the 3D ball tool.

Syntax:

obj.segmentationBall3D(y, x, z, modifier)
obj.segmentationBall3D(y, x, z, modifier, BatchOptIn)

Places an ellipsoidal 3D ball in the dataset at the given coordinate. The ball is anisotropy-corrected: radii along each axis are scaled by the voxel size ratio so the ball appears physically spherical.

Input Arguments:

y - [double] y-coordinate of ball centre in full-dataset pixels
x - [double] x-coordinate of ball centre in full-dataset pixels
z - [double] z-coordinate (slice index) of ball centre
modifier - [char|cell] modifier keys held during click:
- '' - add ball to selection/mask layer
- 'control' - subtract ball from selection/mask layer
BatchOptIn (optional) - [struct|NaN] batch processing mode; when NaN, returns default options via 'SyncBatch' event:
- .Radius - [char] ball radius in pixels (raw spinner value)
- .X - [char] vector or single X coordinate of ball centre
- .Y - [char] vector or single Y coordinate of ball centre
- .Z - [char] vector or single Z coordinate of ball centre; empty = current slice
- .Mode - [char] 'add' or 'erase' - add or subtract ball
- .restrictSelectionToMask - [logical] paint only within mask
- .restrictSelectionToMaterial - [logical] paint only within selected material
- .Target - [char] 'selection' or 'mask' - destination layer
- .showWaitbar - [logical] show progress bar
- .id (optional) - [numeric] dataset index 1-9 (default: obj.mibModel.getActiveId())

Output Arguments:

(none)

Example 1 - add 3D ball at [y,x,z]=[50,75,10]:

obj.segmentationBall3D(50, 75, 10, '');

Example 2 - erase 3D ball:

obj.segmentationBall3D(50, 75, 10, 'control');

Example 3 - batch processing:

BatchOpt.Radius = ‘6’; BatchOpt.X = ‘75’; BatchOpt.Y = ‘50’; BatchOpt.Z = ‘10’; BatchOpt.Mode = {‘add’}; BatchOpt.Target = {‘selection’}; BatchOpt.showWaitbar = false; obj.segmentationBall3D(50, 75, 10, ‘’, BatchOpt); // batch / scripted call

segmentationBrush(y, x, modifier)¶

SEGMENTATIONBRUSH - Start segmentation using the brush tool.

Syntax:

obj.segmentationBrush(y, x, modifier)

This method initializes the brush tool for interactive painting on the image. It creates a structural element based on the brush radius, performs an undo backup, and sets up mouse callbacks for brush motion and button release. Supports normal brush, eraser (Ctrl), and superpixel-assisted (SLIC/Watershed) modes.

Input Arguments:

y - [double] y-coordinate of the mouse cursor at the starting point (in shown image coords)
x - [double] x-coordinate of the mouse cursor at the starting point (in shown image coords)
modifier - [char|cell] modifier keys held during click:
- empty string '' - add selection
- 'control' - subtract selection (eraser mode)
- 'shift' - add selection with a standard brush, ignoring the SLIC/Watershed clustering mode for this stroke

Output Arguments:

(none)

Example 1 - start brush from shown position:

obj.segmentationBrush(50, 75, '');  % start from [y,x]=50,75

Example 2 - start eraser from shown position:

obj.segmentationBrush(50, 75, 'control');  % start in eraser mode

Example 3 - start a standard brush while the clustering mode is on:

obj.segmentationBrush(50, 75, 'shift');  % no superpixels for this stroke

segmentationClickTracker(yxzCoordinate, yx, modifier)¶

SEGMENTATIONCLICKTRACKER - Trace membranes and draw straight lines in 2D and 3D.

Syntax:

output = obj.segmentationClickTracker(yxzCoordinate, yx, modifier)

Uses the Membrane Click Tracker tool to connect two user-clicked points either by tracing along minimum intensity gradients (fast marching) or by drawing a straight line segment. In 3D mode only straight lines are supported.

Input Arguments:

yxzCoordinate - [vector] [y, x, z] coordinates of starting point (voxel coordinates of dataset)
yx - [vector] [y, x] coordinates of clicked point in display coordinate system (before magnification)
modifier - [char] specify action with generated selection:
- '' - trace membrane from starting to selected point
- 'control' - define starting point of membrane (2D mode)
- 'shift' - define starting point of membrane (3D straight-line mode)

Output Arguments:

output - [char] define next action in gui_WindowButtonDownFcn:
- 'continue' - continue with script
- 'return' - stop execution and return

Example 1 - define starting point (2D mode, Ctrl+click):

output = obj.segmentationClickTracker([50, 75, 1], [25, 38], {'control'});

Example 2 - trace to endpoint:

output = obj.segmentationClickTracker([50, 75, 1], [25, 38], '');

segmentationDragAndDrop(y, x, modifier)¶

SEGMENTATIONDRAGANDDROP - Initiate drag-and-drop of materials, selection, or mask layer.

Syntax:

obj.segmentationDragAndDrop(y, x, modifier)

Captures the initial selection under the mouse, sets up motion and button-up callbacks for interactive dragging.

Input Arguments:

y - [double] y-coordinate of mouse cursor at starting point
x - [double] x-coordinate of mouse cursor at starting point
modifier - [char] modifier key held during click:
- 'shift' - drag all objects on slice
- 'control' - drag only single object under cursor

Output Arguments:

(none)

Example - drag object at [y,x]=[50,75]:

obj.segmentationDragAndDrop(50, 75, 'control');

segmentationLasso(modifier)¶

SEGMENTATIONLASSO - Do segmentation using the lasso tool.

Syntax:

obj.segmentationLasso()
obj.segmentationLasso(modifier)

Draws an interactive shape (Lasso, Rectangle, Ellipse, or Polyline) on the image axes and converts the enclosed area into a selection mask. Uses modern MATLAB ROI drawing functions (drawfreehand, drawrectangle, drawellipse, drawpolygon).

Input Arguments:

modifier (optional) - [char] specify action on generated selection:
- '' - make new selection (add to existing)
- 'control' - remove selection from existing

Output Arguments:

(none)

Example 1 - draw lasso and add to selection:

obj.segmentationLasso();

Example 2 - draw lasso and subtract from selection:

obj.segmentationLasso('control');

segmentationLassoManual(BatchOptIn)¶

SEGMENTATIONLASSOMANUAL - Do manual segmentation using the lasso tool in manual mode.

Syntax:

obj.segmentationLassoManual()
obj.segmentationLassoManual(BatchOptIn)

Uses coordinate values from the lasso panel edit fields (X1, Y1, Width, Height) to define a rectangular or elliptical selection area. Lasso and Polyline types are not supported in manual mode.

Input Arguments:

BatchOptIn (optional) - [struct|char|NaN] batch processing control or modifier key; when NaN, returns default structure via “syncBatch” event:
- .Shape - [char] 'Rectangle' or 'Ellipse' - shape for manual selection
- .Mode - [char] 'Slice' (2D, current) or 'Stack' (3D, whole stack)
- .X1 - [numeric] X coordinate: top-left for Rectangle, center for Ellipse
- .Y1 - [numeric] Y coordinate: top-left for Rectangle, center for Ellipse
- .Width - [numeric] half-width of selection area (semi-axis for Ellipse)
- .Height - [numeric] half-height of selection area (semi-axis for Ellipse)
- .Action - [char] 'Add' or 'Subtract' - action on generated selection
- .FixSelectionToMask - [logical] apply selection only to masked area
- .FixSelectionToMaterial - [logical] apply selection only to selected material area
- .showWaitbar - [logical] show progress bar during execution

Output Arguments:

(none)

Example 1 - select area and add to selection:

obj.segmentationLassoManual();

Example 2 - select area and subtract from selection:

obj.segmentationLassoManual('control');

Example 3 - batch mode with provided options:

obj.segmentationLassoManual(BatchOpt);

segmentationLines3D(y, x, z, modifier)¶

SEGMENTATIONLINES3D - Handle mouse clicks for 3D line skeleton annotation.

Syntax:

obj.segmentationLines3D(y, x, z, modifier)

Reads the action from the Lines3D segmentation-panel dropdowns (click / shift-click / ctrl-click / alt-click) and delegates to the corresponding method of core.Lines3D.

Input Arguments:

y - [double] y-coordinate of clicked point in full-dataset pixels
x - [double] x-coordinate of clicked point in full-dataset pixels
z - [double] z-coordinate (slice index) of clicked point
modifier - [char|cell] modifier key held during click:
- '' or {} - use default click action
- 'shift' - use shift-click action
- 'control' - use ctrl-click action
- 'alt' - use alt-click action

Output Arguments:

(none)

Example 1 - default click action:

obj.segmentationLines3D(50, 75, 10, {});

Example 2 - shift-click action:

obj.segmentationLines3D(50, 75, 10, {'shift'});

segmentationMagicWand(yxzCoordinate, BatchOptIn)¶

SEGMENTATIONMAGICWAND - Do segmentation using the Magic Wand tool.

Syntax:

obj.segmentationMagicWand(yxzCoordinate)
obj.segmentationMagicWand(yxzCoordinate, BatchOptIn)

Selects pixels connected to the clicked point whose intensity falls within the specified threshold range. Supports 2D and 3D modes, optional radius limit, and connectivity filtering.

Input Arguments:

yxzCoordinate - [vector] coordinates of the starting point: [y, x] for 2D or [y, x, z] for 3D
BatchOptIn (optional) - [struct|char] batch processing mode structure, or modifier key for interactive calls When NaN, returns default structure via “syncBatch” event:
- .Coordinate - [char] seed point as 'y; x' (2D) or 'y; x; z' (3D)
- .Mode - [char] 'Slice' (2D, current slice) or 'Stack' (3D, whole stack)
- .ThresholdLow - [numeric] low threshold shift from seed intensity
- .ThresholdHigh - [numeric] high threshold shift from seed intensity
- .ColorChannel - [numeric] color channel to use for thresholding
- .Radius - [numeric] effective radius limit (0 = no limit)
- .Connectivity - [char] connectivity: '8/26', '4/6', or 'None'
- .Action - [char] 'Add', 'Subtract', or 'Replace'
- .FillHoles - [logical] fill holes in resulting selection
- .FixSelectionToMask - [logical] apply selection only to masked area
- .FixSelectionToMaterial - [logical] apply selection only to selected material area
- .showWaitbar - [logical] show progress bar during execution

Output Arguments:

(none)

Example 1 - interactive magic wand with shift modifier:

obj.segmentationMagicWand([50, 75], 'shift');  % wand from [y,x]=50,75 and add to selection

Example 2 - batch processing mode:

obj.segmentationMagicWand([50, 75], BatchOpt);  % batch mode with options

segmentationObjectPicker(yxzCoordinate, modifier)¶

SEGMENTATIONOBJECTPICKER - Select 2D/3D objects from the Mask or Model layers.

Syntax:

obj.segmentationObjectPicker(yxzCoordinate, modifier)

Picks connected objects from the Mask or Model layer and copies them to the Selection layer. Supports multiple sub-modes: Click (direct object selection), Lasso/Rectangle/Ellipse/Polyline (ROI-based), and Mask within Selection (AND operation).

Input Arguments:

yxzCoordinate - [vector] [y, x, z] coordinates of starting point; [y, x] is sufficient for 2D case
modifier - [char] specify action with generated selection:
- '' - make new selection (add to existing)
- 'control' - remove selection from existing
- 'shift' - used for 3D mode in Mask within Selection; returns union of mask and selection

Output Arguments:

(none)

Example 1 - select object at [y,x,z]=50,75,1:

obj.segmentationObjectPicker([50, 75, 1], '');

Example 2 - subtract object from selection:

obj.segmentationObjectPicker([50, 75, 1], 'control');

segmentationRegionGrowing(yxzCoordinate, BatchOptIn)¶

SEGMENTATIONREGIONGROWING - Do segmentation using the Region Growing method.

Syntax:

obj.segmentationRegionGrowing(yxzCoordinate)
obj.segmentationRegionGrowing(yxzCoordinate, BatchOptIn)

Based on Fast 3D/2D Region Growing (MEX), written by Christian Wuerslin, Stanford University. Requires: compiled RegionGrowing_mex.cpp

Input Arguments:

yxzCoordinate - [vector] coordinates of starting point: [y, x] for 2D or [y, x, z] for 3D
BatchOptIn (optional) - [struct|char] batch processing mode structure or modifier key; when NaN, returns default structure via “syncBatch” event:
- .Coordinate - [char] seed point as 'y; x' (2D) or 'y; x; z' (3D)
- .Mode - [char] 'Slice' (2D, current slice) or 'Stack' (3D, whole stack)
- .IntensityVariation - [numeric] maximum intensity variation for region growing
- .ColorChannel - [numeric] color channel to use
- .Radius - [numeric] effective radius limit (0 = no limit)
- .Action - [char] 'Add', 'Subtract', or 'Replace'
- .FillHoles - [logical] fill holes in resulting selection
- .FixSelectionToMask - [logical] apply selection only to masked area
- .FixSelectionToMaterial - [logical] apply selection only to selected material area
- .showWaitbar - [logical] show progress bar during execution

Output Arguments:

(none)

Example 1 - region growing from [y,x]=50,75 with shift modifier:

obj.segmentationRegionGrowing([50, 75], 'shift');

Example 2 - batch mode:

obj.segmentationRegionGrowing([50, 75], BatchOpt);

segmentationSAM(extraOptions, BatchOptIn)¶

SEGMENTATIONSAM - Perform segmentation using Segment Anything Model (SAM).

Syntax:

obj.segmentationSAM()
obj.segmentationSAM(extraOptions)
obj.segmentationSAM(extraOptions, BatchOptIn)

Perform segmentation using Segment Anything Model. See https://segment-anything.com

Input Arguments:

extraOptions (optional) - [struct] structure with additional options:
- .addNextMaterial - [logical] switch to add next material for “add, +next material” mode
BatchOptIn (optional) - [struct|NaN] batch processing mode; when NaN, returns default structure via “syncBatch” event. See Declaration of BatchOpt structure below for details; function variables are preferred over BatchOptIn variables:
- .Method - [char] specify how SAM should execute:
  - 'Interactive' - add points interactively
  - 'Landmarks' - process placed points all at once
  - 'Automatic everything' - automatically segment all objects on image
- .Dataset - [char] segment current slice ('2D, Slice'), stack ('3D, Stack'), or whole dataset ('4D, Dataset')
- .Destination - [char] MIB layer for results: 'selection', 'mask', or 'labels'
- .showWaitbar - [logical] show progress bar during execution

Output Arguments:

(none)

Example - perform segmentation:

obj.segmentationSAM(extraOptions);

segmentationSAM2(extraOptions, BatchOptIn)¶

SEGMENTATIONSAM2 - Perform segmentation using Segment Anything Model 2 (SAM2).

Syntax:

obj.segmentationSAM2()
obj.segmentationSAM2(extraOptions)
obj.segmentationSAM2(extraOptions, BatchOptIn)

Perform segmentation using Segment Anything Model 2. See https://github.com/facebookresearch/segment-anything-2

Input Arguments:

extraOptions (optional) - [struct] structure with additional options:
- .addNextMaterial - [logical] switch to add next material for “add, +next material” mode
BatchOptIn (optional) - [struct|NaN] batch processing mode; when NaN, returns default structure via “syncBatch” event. See Declaration of BatchOpt structure below for details; function variables are preferred over BatchOptIn variables:
- .Method - [char] specify how SAM2 should execute:
  - 'Interactive' - add points interactively
  - 'Interactive 3D' - add points for 3D video segmentation
  - 'Landmarks' - process placed points all at once
  - 'Automatic everything' - automatically segment all objects on image
- .Dataset - [char] segment current slice ('2D, Slice'), stack ('3D, Stack'), or whole dataset ('4D, Dataset')
- .Destination - [char] MIB layer for results: 'selection', 'mask', or 'labels'
- .showWaitbar - [logical] show progress bar during execution

Output Arguments:

(none)

Example - perform segmentation:

obj.segmentationSAM2(extraOptions);

segmentationSAM_requirements(samVersionName)¶

SEGMENTATIONSAM_REQUIREMENTS - Check for files required to run SAM segmentation.

Syntax:

status = obj.segmentationSAM_requirements()
status = obj.segmentationSAM_requirements(samVersionName)

Check for files required to run segmentation using Segment Anything Model. See https://segment-anything.com and https://github.com/facebookresearch/segment-anything-2

Input Arguments:

samVersionName (optional) - [numeric|char] SAM version to check:
- 1 or 'SAM1' - first version SAM (https://segment-anything.com)
- 2 or 'SAM2' - second version SAM-2 (default; https://github.com/facebookresearch/segment-anything-2)

Output Arguments:

status - [logical] indicates success of the function

Example - check SAM requirements:

status = obj.segmentationSAM_requirements('SAM1');  % check SAM1 requirements
status = obj.segmentationSAM_requirements('SAM2');  % check SAM2 requirements
status = obj.segmentationSAM_requirements(2);  % check SAM2 requirements

segmentationSpot(y, x, modifier, BatchOptIn)¶

SEGMENTATIONSPOT - Do segmentation using the spot tool.

Syntax:

obj.segmentationSpot(y, x, modifier)
obj.segmentationSpot(y, x, modifier, BatchOptIn)

Places a circular or square spot (selection or mask) at the given image coordinate. Supports 2D and 3D modes, restriction to mask/material, and batch scripting.

Input Arguments:

y - [double] y-coordinate of spot centre in full-dataset pixels
x - [double] x-coordinate of spot centre in full-dataset pixels
modifier - [char|cell] modifier keys held during click:
- '' - add selection
- 'control' - subtract selection (eraser mode)
BatchOptIn (optional) - [struct|NaN] batch processing mode; when NaN, returns default options via 'SyncBatch' event:
- .Shape - [char] 'circle' or 'square' - shape of spot
- .Radius - [char] spot radius in pixels; two numbers separated by ; for independent half-width/half-height
- .X - [char] vector or single X coordinate of spot centre
- .Y - [char] vector or single Y coordinate of spot centre
- .Z - [char] vector or single Z slice index; empty = current slice
- .Mode - [char] 'add' or 'erase' - add or subtract spot
- .Check3D - [logical] apply spot across all z-slices (3D sphere); default from obj.mibModel.applySegmentationIn3D
- .restrictSelectionToMask - [logical] paint only within mask
- .restrictSelectionToMaterial - [logical] paint only within selected material
- .Orientation - [char] 'XZ', 'YZ' or 'YX' - dataset orientation when computing the spot. A legacy 'not available' (MIB2 numbered YX as 4 and left slot 3 unused) is accepted on input and read as 'YX'.
- .Target - [char] 'selection' or 'mask' - destination layer
- .showWaitbar - [logical] show progress bar
- .id (optional) - [numeric] dataset index 1-9 (default: obj.mibModel.getActiveId())

Output Arguments:

(none)

Example 1 - add spot at dataset [y,x]=[50,75]:

obj.segmentationSpot(50, 75, '');

Example 2 - erase spot:

obj.segmentationSpot(50, 75, 'control');

Example 3 - batch/scripted processing:

BatchOpt.Shape = {'circle'};
BatchOpt.Radius = '5';
BatchOpt.X = '75'; BatchOpt.Y = '50'; BatchOpt.Z = '';
BatchOpt.Mode = {'add'};
BatchOpt.Check3D = false;
BatchOpt.Target = {'selection'};
BatchOpt.showWaitbar = false;
obj.segmentationSpot(50, 75, '', BatchOpt);

selectDocument()¶

SELECTDOCUMENT - Select this document in the document group.

Syntax:

obj.selectDocument()

Makes this document the active/selected document in the MDI interface. This updates the UI to show this document’s tab as selected.

Input Arguments:: (none)
Output Arguments:: (none)

Example 1 - select document by index:

obj.mibController.cImageDoc{2}.selectDocument();

Example 2 - select document after finding it:

for i = 1:numel(obj.mibController.cImageDoc)
    if strcmp(obj.mibController.cImageDoc{i}.getTitle(), 'MyDataset')
        obj.mibController.cImageDoc{i}.selectDocument();
        break;
    end
end

setDescription(description)¶

SETDESCRIPTION - Update the description text of this document.

Syntax:

obj.setDescription(description)

The description appears below the document title and typically shows buffer number and filename information.

Input Arguments:

description - [char] description text to display

Output Arguments:

(none)

Example - set description with buffer number and filename:

obj.setDescription(sprintf('Buffer %d: %s', 1, 'myimage.tif'));

setTitle(title)¶

SETTITLE - Set the title of this image document.

Syntax:

obj.setTitle(title)

Updates the title displayed in the document tab. This is useful when renaming datasets or updating document identification.

Input Arguments:

title - [char] new title for the document

Output Arguments:

(none)

Example 1 - set simple title:

obj.mibController.cImageDoc{1}.setTitle('Dataset_001');

Example 2 - set title based on filename:

[~, fname] = fileparts(obj.mibModel.I{1}.image.filename);
obj.mibController.cImageDoc{1}.setTitle(fname);

Example 3 - update title when buffer changes:

selectedSet = obj.mibModel.Sets.selectedSet;
newTitle = sprintf('Buffer %d', selectedSet);
obj.mibController.cImageDoc{selectedSet}.setTitle(newTitle);

setupCallbacks()¶

SETUPCALLBACKS - Setup all callbacks for this image document.

Syntax:: function setupCallbacks(obj)

Configures callbacks for: - Slice and frame navigation buttons and sliders - Mouse movement tracking - Mouse scroll wheel interactions - Window resize events

Input Arguments:: none
Output Arguments:: none

sliceNumberSlider_Callback(sliderValue)¶

SLICENUMBERSLIDER_CALLBACK - Change the currently displayed slice using the slice-number slider.

Syntax:

obj.sliceNumberSlider_Callback()
obj.sliceNumberSlider_Callback(sliderValue)

Triggered when the user changes the slice number slider in the Image View panel. The function:

Reads the slider value (or uses provided value)
Rounds to integer slice index (slider maximum may be stored as float with +0.001)
Updates current slice range in model for active dataset by orientation
Refreshes displayed image
Notifies app that slice has changed

For orientation == 3 (YX), if slice names are available, the Image View axes title is updated to include the slice/layer name.

Input Arguments:

sliderValue (optional) - [numeric] slider position value; if omitted, reads from obj.handles.sliceNumberSlider.Value

Output Arguments:

(none)

Side effects:

Updates GUI edit field: obj.handles.sliceNumber.Value = sliceNumber
Updates model slice selection by orientation:
- orientation == 1 (XZ): obj.mibModel.I{datasetId}.slices{1} = [N, N]
- orientation == 2 (YZ): obj.mibModel.I{datasetId}.slices{2} = [N, N]
- orientation == 3 (YX): obj.mibModel.I{datasetId}.slices{3} = [N, N]
Triggers redraw: obj.mibController.showImage()
Emits event: notify(obj.mibModel, 'SliceChanged')
In DeveloperMode, prints diagnostic message to stdout

Important notes:

sliceNumber computed as round(sliderValue) to avoid fractional indices from float slider limits
Slice-name title update only attempted when dataset.image.sliceName is not empty; indices clamped to available names

See also

showImage, notify

sliceNumberSlider_ContextMenu(menuEntry, selectedData)¶

SLICENUMBERSLIDER_CONTEXTMENU - Callbacks for the context menu of slice/frame slider.

Syntax:

obj.sliceNumberSlider_ContextMenu(menuEntry, selectedData)

Context menu for:

obj.mibController.cImageDoc{obj.mibModel.Sets.selectedSet}.handles.sliceNumberSlider
obj.mibController.cImageDoc{obj.mibModel.Sets.selectedSet}.handles.frameNumberSlider

Input Arguments:

menuEntry - [matlab.ui.container.Menu] handle to pressed context menu entry
selectedData - [matlab.ui.eventdata.MenuSelectedData] event data; use selectedData.ContextObject to find owning button

Output Arguments:

(none)

Available menu options (via menuEntry.Tag):

'sliceNumberSliderContextDefault' - reset Z slider settings to default values
'sliceNumberSliderContextSetStep' - update Z slider settings with new values
'frameNumberSliderContextDefault' - reset T slider settings to default values
'frameNumberSliderContextSetStep' - update T slider settings with new values

sliceNumber_Callback(parameter, BatchOptIn)¶

SLICENUMBER_CALLBACK - Callback for changing the slices of a 3D dataset by entering a new slice number.

Syntax:

obj.sliceNumber_Callback()
obj.sliceNumber_Callback(parameter)
obj.sliceNumber_Callback(parameter, BatchOptIn)

Input Arguments:

parameter (optional) - [numeric] slice number; when provided:
- 0 - set dataset to last slice (also used as callback for handles.lastSlice)
- 1 - set dataset to first slice (also used as callback for handles.firstSlice)
- other numeric value - slice number to display
BatchOptIn (optional) - [struct|NaN] batch processing control When NaN, returns structure with default options via 'SyncBatch' event:
- .SliceNumber - [char] slice number to show (use '0' for last slice)
- .mibBatchSectionName - [char] UI section label: 'Panel -> Image view'
- .mibBatchActionName - [char] batch action label: 'Change slice number'
- .mibBatchTooltip - [struct] tooltips for each field

Output Arguments:

(none)

sliderDragCallback(sliderType, value, isFinal)¶

SLIDERDRAGCALLBACK - Handle slice/frame slider dragging with a throttle + final render.

Syntax:

obj.sliderDragCallback(sliderType, value, isFinal)

Keeps slider dragging interactive. The numeric readout is updated on every tick, but the expensive showImage redraw is rate-limited:

In-memory datasets, and native (zarrMex) zarr datasets - redraws are throttled by wall-clock time (at most once per obj.sliderThrottleInterval seconds) while dragging and rendered live; intermediate ticks only update the numeric box. On release (isFinal) the exact final position is always rendered (trailing edge). Native zarr reads (~5-10 ms) are fast enough to render live, so they share this path for smooth scrolling.

Python-backend zarr datasets - out-of-process reads are slower (~15-30 ms+), so the disk read is deferred with a singleShot debounce timer until the user pauses (100 ms).

While dragging, obj.sliderDragging is set so that listener_sliceChanged / listener_frameChanged do not write the model value back onto the slider thumb (which would fight the user’s drag and make the thumb appear to lag/jump).

Input Arguments:

sliderType - [char] 'slice' or 'frame'
value - [numeric] current slider position value
isFinal - [logical] true when called from the slider ValueChanged (release) event; false for live ValueChanging drag events

Output Arguments:

(none)

See also

renderSlider, gui_Callbacks, sliceNumberSlider_Callback, frameNumberSlider_Callback

syncActiveSet()¶

SYNCACTIVESET - Lightweight sync of mibModel’s active set to this document’s setOfDatasetsIndex.

Syntax:

changed = obj.syncActiveSet()

In split-panel mode the model keeps a single “active set” (Sets.selectedSet + mibModel.id), but multiple MibImageDocument panels are simultaneously visible and can receive callbacks (scroll, motion). This function ensures the model reflects the set that owns the currently-active document before any data access via obj.mibModel.id or obj.mibModel.I{...}.

Important note: This method updates model fields ONLY (no events, no ShowImage). Callers that need full UI refresh (dropdown, buffer buttons, re-render) should call the setsOps_Callbacks path instead; see gui_WindowButtonDownFcn.

Input Arguments:

(none)

Output Arguments:

changed - [logical] true if the active set was actually changed

Example - sync at start of frequent callback (mouse motion, scroll):

obj.syncActiveSet();
dataset = obj.mibModel.I{obj.mibModel.id};

updateBrushCursor(xyCoordinate, lineStyle, resetOffset)¶

UPDATEBRUSHCURSOR - Update brush cursor position and visibility.

Syntax:

obj.updateBrushCursor(xyCoordinate, lineStyle, resetOffset)

Creates or updates a circular cursor overlay that visualizes the current brush size. The cursor follows the mouse and changes style based on painting state.

With preferences.Colors.CursorMaterialColor on (the default), the cursor is drawn in the color of the target of the brush stroke, i.e. the 'AddTo' column of the materials table: a material takes its color from labels.materialColors, Mask from preferences.Colors.MaskColor. It falls back to dark green ([0, 0.5, 0]) when the preference is off, when Exterior is selected, when no model exists, or when the material index falls outside the palette.

The color is re-evaluated on every call, so the cursor follows a change of the selected material. Because the call is normally driven by mouse motion, a change made from the keyboard or from the materials table has to trigger it - see MibSegmentation.materialsTable_CellSelectionCallback.

Input Arguments:

xyCoordinate (optional) - [double] [x, y] cursor position in axes coordinates; if empty, uses CurrentPoint
lineStyle (optional) - [char] line style for cursor (default: ':'):
- ':' - dashed line (hover mode)
- '-' - solid line (painting mode)
resetOffset (optional) - [logical] reset cursor offset when true, needed when magnification changes (default: false)

Output Arguments:

(none)

Example 1 - update cursor at specific position with dashed style:

obj.updateBrushCursor([100, 150], ':', true);

Example 2 - use solid line during painting:

obj.updateBrushCursor([], '-');

updateBrushCursorOffset()¶

UPDATEBRUSHCURSOROFFSET - Update brush cursor offset based on current brush radius and magnification.

Syntax:

obj.updateBrushCursorOffset()

Calculates the circle points for the brush cursor based on the current brush radius setting and image magnification factor. The offset is stored as a 2×N array with X and Y offsets.

Input Arguments:: (none)
Output Arguments:: (none)

Example - called automatically when brush size changes:

obj.updateBrushCursorOffset();

updateMeasureText(pos)¶

UPDATEMEASURETEXT - Refresh the quick-measurement text label for this document’s active ROI.

Syntax:

obj.updateMeasureText()
obj.updateMeasureText(pos)

Called from MovingROI listener (pos provided) and from model event listeners (pos omitted; position read from roi.Position).

If the currently displayed dataset differs from the one the ROI was drawn on (e.g. after buffer/dataset change), the ROI is deleted silently via clearQuickMeasure instead of updating.

Input Arguments:

pos (optional) - [N×2 numeric] position in physical (XData) coordinates; when [] or omitted, position is read from quickMeasure.roi.Position

Output Arguments:

(none)