RoiRegion

class core.RoiRegion

Bases: matlab.mixin.Copyable

ROIREGION - Container for regions of interest (ROI) data and visualization.

Ported from MIB2 mibRoiRegion class, adapted for the MIB3 package namespace. This class manages ROI data storage and visualization options. Interactive drawing of new ROIs is handled by controllers.MibRoi; this class is data-only and does not hold references to any controller.

Supported ROI types:

  • 'rectangle' - rectangular ROI (MIB2 equivalent: 'imrect')

  • 'ellipse' - elliptical ROI (MIB2 equivalent: 'imellipse')

  • 'polygon' - polygonal ROI (MIB2 equivalent: 'impoly')

  • 'freehand' - freehand ROI (MIB2 equivalent: 'imfreehand')

Data structure - Each element of obj.Data struct array contains:

  • .label - [string or cellstr] user-visible label

  • .type - [char] ROI type: 'rectangle', 'ellipse', 'polygon', or 'freehand'

  • .X - [numeric vector] X-coordinates of vertices

  • .Y - [numeric vector] Y-coordinates of vertices

  • .orientation - [numeric] orientation when created: 1 = zx, 2 = zy, 3 = yx; .X/.Y are the horizontal/vertical axes of that view: X/Z for zx, Z/Y for zy. .roi files keep zx ROIs in the legacy MIB2 frame (X = Z, Y = X), see core.RoiRegion.swapZXAxes()

  • .BoundingBox - [struct] bounding box with subfields .x = [xmin, xmax] and .y = [ymin, ymax]

Constructor Summary
RoiRegion(mibDataset)

ROIREGION - Constructor for the RoiRegion class.

Syntax:
obj = RoiRegion(mibDataset)

Create a new instance of the class with default parameters. The class is typically instantiated inside core.MibDataset.initialize and stored as obj.hROI.

Input Arguments:

  • mibDataset - (optional) handle to core.MibDataset (the parent dataset that owns this ROI collection). When omitted or empty, the class still works but methods that need orientation or image dimensions require explicit arguments.

Output Arguments:
Usage:

Example 1

hROI = core.RoiRegion(obj);% call from MibDataset.initialize; create ROI handler attached to this dataset

Example 2

hROI = core.RoiRegion();% create a standalone ROI handler (no dataset reference)

Example 3

obj.mibModel.I{obj.mibModel.id}.hROI = core.RoiRegion(obj.mibModel.I{obj.mibModel.id});% call from mibController; re-create ROI handler
Property Summary
Data
LegacyTypeMap
Options
mibDataset
Method Summary
addROIsToPlot(axesHandle, ~, orientation, convertFcn, selectedROI, showLabel)

ADDROISTOPLOT - Plot stored ROIs as line/marker overlays on the given axes.

Syntax:
obj.addROIsToPlot(axesHandle, ~, orientation, convertFcn, selectedROI, showLabel)

This method replaces the MIB2 version that required a mibController handle. Instead it receives the axes handle and a coordinate-conversion function handle directly, keeping the class independent of any controller.

The conversion function convertFcn must accept two numeric vectors (X, Y) in data coordinates and return the corresponding axes (screen) coordinates: [Xaxes, Yaxes] = convertFcn(Xdata, Ydata);

Input Arguments:

  • axesHandle - handle to the target matlab.ui.control.UIAxes or matlab.graphics.axis.Axes where ROIs will be drawn.

  • mode - char - rendering mode, either ‘shown’ (default view) or ‘full’ (used during panning).

  • orientation - numeric - current dataset orientation (3 = yx, 1 = zx, 2 = zy). Only ROIs matching this orientation are plotted.

  • convertFcn - function_handle - @(X,Y) ... that converts data coordinates to axes coordinates. Typically @(x,y) obj.mibModel.convertDataToMouseCoordinates(x, y, mode).

  • selectedROI - (optional) numeric - controls which ROIs are drawn:

    • 0 - draw all ROIs matching the current orientation (default).

    • >0 - draw only the ROI at that index in obj.Data.

  • showLabel - (optional) logical - whether to display ROI labels as text annotations next to each shape. Default = false.

Output Arguments:

Usage:

Example 1 - Full example from controllers.MibController.showImage

% Full example from controllers.MibController.showImage:
ds = obj.mibModel.I{datasetId};
ax = obj.cImageDoc{selectedSet}.handles.imViewAxes;
convertFcn = @(x,y) obj.mibModel.convertDataToMouseCoordinates(x, y, 'shown');
ds.hROI.addROIsToPlot(ax, 'shown', ds.orientation, convertFcn, 0, true);

Example 2

obj.mibModel.I{obj.mibModel.id}.hROI.addROIsToPlot(ax, 'shown', 3, @(x,y) deal(x,y), 0, false);% plot all ROIs with identity conversion

Example 3

obj.mibModel.I{obj.mibModel.id}.hROI.addROIsToPlot(ax, 'shown', 3, convertFcn, 2, true);% plot only ROI #2

Example 4

obj.mibModel.I{obj.mibModel.id}.hROI.addROIsToPlot(ax, 'full', ds.orientation, convertFcn);% plot all, no labels
clearContents()

CLEARCONTENTS - Set all elements of the class to default values.

Syntax:
obj.clearContents()

Resets both the display Options (via setDefaultOptions) and the stored Data (via clearData) to their initial empty/default state.

Input Arguments:

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.hROI.clearContents();% call from mibController; clear all ROIs and reset options

Example 2

clearContents(obj);% call within the class
clearData()

CLEARDATA - Remove all values from the Data structure, resetting it to an.

Syntax:
obj.clearData()

empty single-element struct with the correct field names.

Input Arguments:

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.hROI.clearData();% call from mibController; remove all stored ROIs

Example 2

clearData(obj);% call within the class
convertLegacyTypes()

CONVERTLEGACYTYPES - Convert MIB2 ROI type-name strings to MIB3 equivalents.

Syntax:
obj.convertLegacyTypes()

Iterates through obj.Data and replaces any legacy type names (‘imrect’, ‘imellipse’, ‘impoly’, ‘imfreehand’) with their MIB3 equivalents (‘rectangle’, ‘ellipse’, ‘polygon’, ‘freehand’) using the LegacyTypeMap dictionary.

This method should be called after loading a .roi file that was saved by MIB2.

Input Arguments:

Output Arguments:

Usage:

Example 1 - typical usage after loading an old .roi file

% typical usage after loading an old .roi file:
res = load(fullfile(path, filename), '-mat');
obj.mibModel.I{obj.mibModel.id}.hROI.Data = res.Data;
obj.mibModel.I{obj.mibModel.id}.hROI.convertLegacyTypes();% convert old type names

Example 2

convertLegacyTypes(obj);% call within the class
crop(cropF)

CROP - Recalculate ROI positions after the image has been cropped.

Syntax:
obj.crop(cropF)

Shifts each ROI’s X, Y coordinates and BoundingBox by the crop origin, depending on the ROI’s orientation. Supports both MIB2 (4 = yx) and MIB3 (3 = yx) orientation values.

Input Arguments:

  • cropF - [numeric vector] crop parameters in pixels [x1, y1, dx, dy, z1, dz]:

    • cropF(1) - starting X coordinate

    • cropF(2) - starting Y coordinate

    • cropF(3) - width of the crop region

    • cropF(4) - height of the crop region

    • cropF(5) - starting Z slice

    • cropF(6) - number of Z slices

Example 1 - define crop parameters:

cropF = [100, 50, 200, 200, 1, 10];

Example 2 - adjust ROI positions after crop:

obj.mibModel.I{obj.mibModel.id}.hROI.crop(cropF);

Example 3 - call within the class:

crop(obj, [1, 1, 512, 512, 5, 20]);
findIndexByLabel(labelStr)

FINDINDEXBYLABEL - Find the index of a ROI whose Data.label matches the.

Syntax:
index = obj.findIndexByLabel(labelStr)

given string. When labelStr is ‘All’, returns the indices of every ROI visible in the current orientation.

Input Arguments:

  • labelStr - char/string - the label to search for. Use ‘All’ to retrieve all ROIs for the current dataset orientation.

Output Arguments:

  • index - numeric vector - index (or indices) of matching ROI(s) in the obj.Data array. Empty if no match is found.

Usage:

Example 1

index = obj.mibModel.I{obj.mibModel.id}.hROI.findIndexByLabel('ROI 1');% call from mibController; find the ROI labelled 'ROI 1'

Example 2

indices = obj.mibModel.I{obj.mibModel.id}.hROI.findIndexByLabel('All');% call from mibController; get all ROI indices for the current orientation

Example 3

index = findIndexByLabel(obj, 'MyROI');% call within the class
getBoundingBox(index)

GETBOUNDINGBOX - Return the combined bounding box for one or more ROIs.

Syntax:
bb = obj.getBoundingBox(index)

When index is 0 the bounding box is the union of all ROIs visible in the current orientation. A label string can be passed instead of a numeric index.

Input Arguments:

  • index - numeric or char/string - index of the ROI. Use 0 to get a combined bounding box for all visible ROIs. A label string (e.g. ‘ROI 1’) is also accepted.

Output Arguments:

  • bb - numeric vector [xmin, xmax, ymin, ymax]

Usage:

Example 1

bb = obj.mibModel.I{obj.mibModel.id}.hROI.getBoundingBox(1);% call from mibController; bounding box of ROI #1

Example 2

bb = obj.mibModel.I{obj.mibModel.id}.hROI.getBoundingBox(0);% call from mibController; combined bounding box of all visible ROIs

Example 3

bb = obj.mibModel.I{obj.mibModel.id}.hROI.getBoundingBox('MyROI');% call from mibController; bounding box by label

Example 4

bb = getBoundingBox(obj, 3);% call within the class
getNumberOfROI(orientation)

GETNUMBEROFROI - Get the count and indices of stored ROIs, optionally filtered by orientation.

Syntax:
[number, indices] = obj.getNumberOfROI(orientation)

Returns the number of ROIs matching the specified orientation criteria, and optionally returns the indices into obj.Data of the matching ROIs.

Input Arguments:

  • orientation - (optional) [numeric] filter ROIs by plane:

    • 1 - ZX plane

    • 2 - ZY plane

    • 3 - YX plane (default in MIB3)

    • 0 - all ROIs regardless of orientation

    When omitted or empty, uses obj.mibDataset.orientation.

Output Arguments:

  • number - [numeric] count of ROIs matching the filter

  • indices - [numeric vector] indices into obj.Data of the matching ROIs

Example 1 - get ROIs for the current orientation:

[number, indices] = obj.mibModel.I{obj.mibModel.id}.hROI.getNumberOfROI();

Example 2 - get ROIs for the YX orientation:

[number, indices] = obj.mibModel.I{obj.mibModel.id}.hROI.getNumberOfROI(3);

Example 3 - get total count of all ROIs:

number = obj.mibModel.I{obj.mibModel.id}.hROI.getNumberOfROI(0);

Example 4 - call within the class:

[n, idx] = getNumberOfROI(obj, 0);
removeROI(index)

REMOVEROI - Remove one or more ROIs from the class.

Syntax:
obj.removeROI(index)

When index is 0, empty, or omitted all ROIs are removed (equivalent to clearData). When index equals the total number of ROIs, clearData is also called to avoid leaving an empty struct array.

Input Arguments:

  • index - (optional) numeric - index of the ROI to remove. Use 0 or omit to remove all ROIs.

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.hROI.removeROI(3);% call from mibController; remove the 3rd ROI

Example 2

obj.mibModel.I{obj.mibModel.id}.hROI.removeROI(0);% call from mibController; remove all ROIs

Example 3

obj.mibModel.I{obj.mibModel.id}.hROI.removeROI();% call from mibController; remove all ROIs (same as 0)

Example 4

removeROI(obj, 5);% call within the class; remove 5th ROI
resample(resampledRatio)

RESAMPLE - Recalculate ROI positions after the image has been resampled.

Syntax:
obj.resample(resampledRatio)

Each ROI’s X, Y coordinates and BoundingBox are scaled by the appropriate ratio depending on the ROI’s orientation. Supports both MIB2 orientation values (4 = yx) and MIB3 values (3 = yx).

Input Arguments:

  • resampledRatio - numeric vector [ratioW, ratioH, ratioZ] - ratio of new/old dimensions after resampling. For example [0.5, 0.5, 1] bins XY by 2.

Output Arguments:

Usage:

Example 1

resampledRatio = [0.5, 0.5, 1];% bin XY dimensions by 2

Example 2

obj.mibModel.I{obj.mibModel.id}.hROI.resample(resampledRatio);% call from mibController; resample all ROIs

Example 3

obj.mibModel.I{obj.mibModel.id}.hROI.resample([2, 2, 2]);% call from mibController; double all dimensions

Example 4

resample(obj, [1, 1, 0.5]);% call within the class; bin Z by 2
returnMask(index, Height, Width, orient, blockModeSwitch)

RETURNMASK - Generate a binary (uint8) mask image for the specified ROI(s).

Syntax:
mask = obj.returnMask(index, Height, Width, orient, blockModeSwitch)

For ‘rectangle’ ROIs the mask is filled directly. For ‘ellipse’ ROIs inpolygon is used. For ‘polygon’ and ‘freehand’ ROIs poly2mask is used.

When blockModeSwitch is 1 the ROI coordinates are shifted by the current axes limits so that the mask aligns with the visible viewport.

Input Arguments:

  • index - numeric or char/string - ROI index. Use 0 to combine masks of all ROIs visible in the current orientation. A label string is also accepted.

  • Height - (optional) numeric - height of the output mask. Default: image height from obj.mibDataset.

  • Width - (optional) numeric - width of the output mask. Default: image width from obj.mibDataset.

  • orient - (optional) numeric - orientation filter (1/2/3). Default: obj.mibDataset.orientation.

  • blockModeSwitch - (optional) numeric - override the block-mode flag (0 or 1). Default: value from obj.mibDataset.blockModeSwitch.

Output Arguments:

  • mask - uint8 matrix [Height x Width] - binary mask where 1 indicates pixels inside the ROI.

Usage:

Example 1

mask = obj.mibModel.I{obj.mibModel.id}.hROI.returnMask(1);% call from mibController; get mask for ROI #1

Example 2

mask = obj.mibModel.I{obj.mibModel.id}.hROI.returnMask(0);% call from mibController; combined mask of all visible ROIs

Example 3

mask = obj.mibModel.I{obj.mibModel.id}.hROI.returnMask('MyROI');% call from mibController; mask by label

Example 4

mask = obj.mibModel.I{obj.mibModel.id}.hROI.returnMask(0, 512, 512, 3, 0);% call from mibController; explicit height, width, orient, block mode

Example 5

mask = returnMask(obj, 2);% call within the class
setDefaultOptions()

SETDEFAULTOPTIONS - Set all values of the Options structure to their default state.

Syntax:
obj.setDefaultOptions()

Default values match the original MIB2 mibRoiRegion defaults.

Input Arguments:

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.hROI.setDefaultOptions();% call from mibController; reset display options to defaults

Example 2

setDefaultOptions(obj);% call within the class
storeROI(newData, index)

STOREROI - Add or insert ROI information into the obj.Data struct.

Syntax:
obj.storeROI(newData, index)

array.

If index is less than or equal to the current number of ROIs, the new entry is inserted at that position (existing entries shift forward). Otherwise the entry is appended.

Input Arguments:

  • newData - struct - a single element whose fields match those of obj.Data (.label, .type, .X, .Y, .orientation, .BoundingBox).

  • index - (optional) numeric - position at which to store the ROI. Default is obj.getNumberOfROI(0) + 1 (append).

Output Arguments:

Usage:

Example 1

newData.label = cellstr('1');
newData.type  = cellstr('rectangle');
newData.X = [10; 200];
newData.Y = [20; 150];
newData.orientation = 3;
newData.BoundingBox.x = [10; 200];
newData.BoundingBox.y = [20; 150];
obj.mibModel.I{obj.mibModel.id}.hROI.storeROI(newData);% call from mibController; append a new rectangle ROI

Example 2

obj.mibModel.I{obj.mibModel.id}.hROI.storeROI(newData, 3);% call from mibController; insert a ROI at position 3

Example 3

storeROI(obj, newData, 5);% call within the class; insert at position 5
static swapZXAxes(Data)

SWAPZXAXES - Swap the X/Y axes of ROIs drawn in the ZX orientation.

Syntax:
Data = core.RoiRegion.swapZXAxes(Data)

ZX slices are [z, x] (rows = Z, columns = X, see core.MibImage.getData()), so in memory a ZX ROI keeps dataset X in .X and Z in .Y. MIB2 and earlier MIB3 versions showed ZX transposed (rows = X, columns = Z), and .roi files store ZX ROIs in that legacy frame. This conversion is its own inverse: it is applied to the data read from a .roi file (controllers.MibRoi.roiLoad) and to the data written to one (controllers.MibRoi.roiSave), so files stay compatible in both directions. Only entries with .orientation == 1 change.

Input Arguments:

  • Data - [struct array] ROI data, see the class header for fields

Output Arguments:

  • Data - [struct array] the same ROIs with .X/.Y and .BoundingBox.x/.BoundingBox.y swapped for ZX entries

Usage:

Example 1 - load a .roi file:

res = load(filename, '-mat');
obj.mibModel.I{obj.mibModel.id}.hROI.Data = core.RoiRegion.swapZXAxes(res.Data);
updateOptions(parentFigure)

UPDATEOPTIONS - Show an interactive dialog to update the display Options.

Syntax:
obj.updateOptions(parentFigure)

Opens utils.dlgs.inputUniversalDlg with the current option values as defaults. If the user cancels the dialog no changes are made.

Input Arguments:

  • parentFigure - handle to the parent window used for dialog centering. Can be an AppContainer handle, a uifigure handle, or [] for automatic placement.

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.hROI.updateOptions(obj.mibController.view.gui);% call from mibController; open options dialog parented to the main window

Example 2

obj.mibModel.I{obj.mibModel.id}.hROI.updateOptions([]);% call from a plugin; let MATLAB place the dialog