VolRenApp¶

class controllers.VolRenApp¶

Bases: handle

VOLRENAPP - Controller for the 3D volume rendering viewer.

Syntax:

obj.startController('controllers.VolRenApp');

Example 1 - launch as interactive GUI tool:

obj.startController('controllers.VolRenApp');

Example 2 - launch in batch mode:

BatchOpt.Parameter = 'test';
BatchOpt.Checkbox = true;
BatchOpt.Popup = {'value'};
BatchOpt.Radio = {'Radio1'};
BatchOpt.showWaitbar = true;
obj.startController('controllers.VolRenApp', [], BatchOpt);

Example 3 - trigger return of available options via syncBatch event:

obj.startController('controllers.VolRenApp', [], NaN);

Constructor Summary

VolRenApp(mibModel, varargin)¶

VOLRENAPP - Class constructor for the VolRenApp controller.

Syntax:

obj = VolRenApp(mibModel)
obj = VolRenApp(mibModel, options)

Input Arguments:

• mibModel - [handle] handle to the MibModel instance

• options (optional) - struct with initialization parameters:

  • .Settings - settings for initialization of the volume viewer

Property Summary

BatchOpt¶

a cell array with handles to listeners

Settings¶

tform to scale the dataset upon loading to have its units in um

alphaPlotHandle¶

a cell array with names of initialized child controllers

animationFilename¶

handle to the alpha plot

animationPath¶

template for the animation filename

animationPreviewRunning¶

a structure with animation path:

• .CameraPosition - matrix of camera positions [keyFrame, x, y, z]

• .CameraUpVector - matrix of camera up vectors [keyFrame, x, y, z]

• .CameraTarget - matrix of camera target positions [keyFrame, x, y, z]

childControllers¶

a structure compatible with batch operation; field names should match widget Tags in the GUI:

• .Parameter - [editbox], char/string

• .Checkbox - [checkbox], logical true or false

• .Dropdown{1} - [dropdown], cell string for the dropdown

• .Dropdown{2} - (optional) array with possible options

• .Radio - [radiobuttons], cell string 'Radio1' or 'Radio2' etc.

• .ParameterNumeric{1} - [numeric editbox], cell with a number

• .ParameterNumeric{2} - (optional) vector with limits [min, max]

• .ParameterNumeric{3} - (optional) 'on' to round the value, 'off' to not round

childControllersIds¶

list of opened subcontrollers

defaultView¶

logical switch defining whether the animation is previewed

figPosStored¶

a structure with the default camera position

keyFrameTableIndex¶

a structure with stored positions of the widgets for making snapshots:

• .mibVolRenAppFigure - position of the main figure

• .mainGridLayoutRowHeights - heights of rows in obj.view.handles.mainGridLayout

listener¶

handle to the view / mibVolRenAppGUI

liveUpdateListener¶

material index last loaded into the overlay (NaN = all materials); used by the live overlay refresh

liveUpdatePending¶

one-shot timer debouncing live overlay refreshes so a burst of edits collapses into one refetch

liveUpdateTimer¶

cell array of listeners that drive live overlay updates during segmentation (empty/{} when off): SetData on the model (moveLayers) and SetData on the active dataset (core setData2D/3D/4D)

matlabVersion¶

index of the selected key frame

maxIntValue¶

current version of MATLAB

mibModel¶

modelTableIndex¶

a vector of material indices rendered in the 'Selected materials' mode

noOverlayMaterials¶

max integer value of the loaded volume

overlayAlpha¶

a vector of shown (true) or hidden (false) materials in the model overlay

overlayMaterialId¶

1-based pyramid level currently loaded into the viewer (1 = full resolution)

Type:¶

for BigData datasets

overlayMaterialsMode¶

a cell array; for each row of the model table, the OverlayAlphamap rows it controls

overlayMaterialsSelection¶

'All materials' or 'Selected materials'

Type:¶

for models with 256 materials and more

overlayRowColors¶

a cell array with names shown in the model table

overlayRowMap¶

a matrix [row, R G B] with background colors of the model table

overlayRowMaterials¶

a vector with alpha values for overlay materials

overlayRowNames¶

real material index behind each row of the model table; empty in the cycled color mode

overlayShownMaterials¶

number of materials shown in the overlay

pyramidLevel¶

scale factor to downsample the datasets, below 1

scalingTransform¶

index of the selected material in the modelTable

surfList¶

a structure with settings, initialized from obj.mibModel.preferences.VolRen:

• .volumeAlphaCurve.x - default [0 .3 .7 1]

• .volumeAlphaCurve.y - default [1 1 0 0]

• .markerSize - marker size for the alpha plot

• .BackgroundColor - color for the background

• .colormapName - default colormap name, or 'custom' (not yet implemented)

• .colormapInvert - true/false, whether to invert the colormap

• .animationPath - a structure with animation path

• .noFramesPreview - number of frames for the animation preview

surfListAlpha¶

a cell array of generated surfaces

surfListShown¶

an array of alpha values for the generated surfaces

surfaceTableIndex¶

[logical] per-surface show/hide intent, one entry per surfList surface. Kept beside the surfaces rather than read back from their Visible property, because “hide all” has to be able to turn every surface off and then put each one back the way the user left it - Visible can only hold one of those two answers at a time. Same split as overlayShownMaterials against the model’s hide-all checkbox.

view¶

handles to mibModel

viewer¶

index of the selected row in the surfaceTable

volume¶

handle to the main viewer widget

volumeAlphaCurve¶

main image volume

volumeColormap¶

a structure with alpha curve details:

• .x - vector of intensity points [0..1]

• .y - alpha value for each intensity point [0..1]

• .alphamap - calculated alpha map used in volshow

• .activePoint - index of the currently selected point

volumeScaleFactor¶

vector with the colormap

Method Summary

static ViewListner_Callback(src, evnt)¶

addAnimationKeyFrame(posIndex)¶

ADDANIMATIONKEYFRAME - Add or insert an animation key frame at the current view.

Syntax:

obj.addAnimationKeyFrame()
obj.addAnimationKeyFrame(posIndex)

Input Arguments:

• posIndex (optional) - [numeric] insertion position; 1 inserts at the beginning

addCurrentMaterialToList()¶

ADDCURRENTMATERIALTOLIST - Append the material selected in MIB to the rendered list.

Syntax:

obj.addCurrentMaterialToList()

Callback target for the addCurrentMaterialButton button. For large models core.MibDataset.getSelectedMaterialIndex resolves the selected table slot to the real material index, so the index appended here is the one shown in the 2D view.

addSurfaceFromMask(mask, surfaceName, surfaceColor, cropOriginYXZ)¶

ADDSURFACEFROMMASK - Append a surface generated from a binary mask to the viewer.

Syntax:

obj.addSurfaceFromMask(mask, surfaceName, surfaceColor)
obj.addSurfaceFromMask(croppedMask, surfaceName, surfaceColor, cropOriginYXZ)

The mask is cropped to the object before meshing. Marching cubes costs the whole array it is handed, while one object of an instance segmentation occupies a thousandth of it: on a 792x804x863 model the median object fills 0.03% of the volume, and the Surface call drops from 0.60 s to 0.038 s once the box is all it sees.

Finding that box is the expensive half, which is why the fourth argument exists. Reducing a full-size mask with any costs 0.44 s - it eats almost the whole saving, leaving the crop worth only about 1.2x. A caller with many objects should instead compute every box in one pass over the label volume (regionprops3, ~1 s for the lot), cut each object straight out of its box and pass the origin here: 0.015 s per object rather than 0.52 s, which is 4 minutes against 8 seconds over 489 objects. generateAllObjectSurfaces() does that.

Cropping moves the vertices into the crop’s own coordinates, so the offset is put back through the transform rather than the data: the viewer’s scalingTransform is a pure diagonal scale, and the same matrix with the crop origin in its translation column lands the surface exactly where the uncropped one sat. isosurface orders vertices (x, y, z) = (column, row, page), which is why the translation is built in that order and not in MIB’s [y x z].

Input Arguments:

• mask - [logical] 3-D binary mask of the object; the whole dataset unless cropOriginYXZ says otherwise

• surfaceName - [char] name shown in the surface table

• surfaceColor - [numeric] [R G B] color of the surface

• cropOriginYXZ (optional) - [1x3 numeric] 1-based [row col page] that mask was already cut at. Supplying it skips the search. The block must keep a one-voxel background margin wherever the object does not reach the dataset edge, or the surface is left open on that side.

alphaAxesButtonDown(event)¶

ALPHAAXESBUTTONDOWN - Handle mouse button-down event on the alpha axes.

Syntax:

obj.alphaAxesButtonDown(event)

Input Arguments:

• event - [event] MATLAB UI callback event from obj.view.handles.alphaAxes

alphaCurveOperations(event)¶

ALPHACURVEOPERATIONS - Callback for alpha curve control buttons.

Syntax:

obj.alphaCurveOperations(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the action:

  • 'resetAlphaCurve' - reset the alpha curve to the default

  • 'invertAlphaCurve' - invert the alpha curve along the x-axis

applyOverlayAlphamap()¶

APPLYOVERLAYALPHAMAP - Rebuild obj.volume.OverlayAlphamap from the material table state.

Syntax:

obj.applyOverlayAlphamap()

The alphamap of volshow is a fixed 256-entry vector. Each row of the material table controls the entries listed in obj.overlayRowMap - one entry per material in the normal case, and all 255 color bins for the single row of the cycled mode. Row 1 is the background and always stays transparent.

applyOverlayMaterialsList()¶

APPLYOVERLAYMATERIALSLIST - Parse the material index list and refresh the overlay.

Syntax:

obj.applyOverlayMaterialsList()

Callback target for the overlayMaterialsList edit field. The text is parsed with str2num, so indices and ranges can be mixed: 1:10, 45, 900:5:1000. Indices outside the model are dropped and the list is capped at the 255 colors that volshow provides.

applySurfaceVisibility()¶

APPLYSURFACEVISIBILITY - Push show state onto the surfaces.

Syntax:

obj.applySurfaceVisibility()

A surface is visible when its own row is ticked and “hide all” is off. The two are kept apart so that either can change without losing the other; this is the single place they are combined.

buildOverlayIndexVolume(overlayData, overlayType)¶

BUILDOVERLAYINDEXVOLUME - map an overlay layer onto the 255 colour slots available in volshow.

Syntax:

[overlayIdx, overlayInfo] = obj.buildOverlayIndexVolume(overlayData, overlayType)

MATLAB keeps the overlay colour and alpha maps of volshow in fixed 256-entry lookup tables (OverlayColormap_I is uint8 [3 256] and OverlayAlphamap_I is uint8 [256 1]), so no more than 255 materials plus the background can ever be displayed at once. This function converts an arbitrary label volume into a uint8 index volume that fits those tables and returns the matching 256-row colormap. The caller must pair it with OverlayDisplayRangeMode = 'manual' and OverlayDisplayRange = [0 255] so that index N always lands on colormap row N+1.

Behaviour depends on the model type and on the mode selected in the overlayMaterialsMode dropdown:

• 'mask' / 'selection' layers, or a single material fetched as a binary mask: one row, using the layer or material colour

• models with fewer than 256 materials: the label values are used directly

• large models (65535 / 4294967295) in 'All materials' mode: labels are cycled into 255 colour bins with mod(index-1, 255)+1, the same trick models.MibModel.getRGBimage() uses for the 2D view

• large models in 'Selected materials' mode: only the indices listed in obj.overlayMaterialsSelection are shown, each with its exact colour

Input Arguments:

• overlayData - [numeric] 3-D overlay volume as returned by getData3D, already resized to match the rendered image volume

• overlayType - [char] layer type: 'labels', 'mask' or 'selection'

Output Arguments:

• overlayIdx - [uint8] index volume; 0 = background, 1..N = colormap row minus 1

• overlayInfo - struct describing the generated rows:

  • .colormap - [256 x 3] colormap; row 1 is the background, unused tail rows are zero

  • .rowMaterials - real material index behind each table row; [] in the cycled mode

  • .rowNames - cell array with the name shown in the material table

  • .rowColors - [N x 3] background colours for the material table

  • .rowMap - cell array; for each table row, the alphamap rows it controls

Usage:

Example 1

[overlayIdx, overlayInfo] = obj.buildOverlayIndexVolume(overlay, 'labels');
obj.volume.OverlayData = overlayIdx;
obj.volume.OverlayColormap = overlayInfo.colormap;

static cameraListner_Callback(src, evnt)¶

listener callback for camera moving

changeSlice(sourceWidget, value)¶

CHANGESLICE - Update a slice plane position from a slider or edit box.

Syntax:

obj.changeSlice(sourceWidget, value)

Input Arguments:

• sourceWidget - [char] tag of the source widget: 'xSliderEdit', 'ySliderEdit', or 'zSliderEdit'

• value - [numeric] new slice index

closeWindow()¶

CLOSEWINDOW - Close the VolRenApp window and release resources.

Syntax:

obj.closeWindow()

cropMaskToObject(~, mask)¶

CROPMASKTOOBJECT - Tight bounding box of a binary mask, with a one-voxel margin.

Syntax:

[croppedMask, cropOriginYXZ] = obj.cropMaskToObject(mask)

The margin is what keeps the mesh identical to one built from the full array: marching cubes needs a ring of background around the object to close the surface, and a box cut exactly at the object would leave it open wherever it touched the edge. Where the object already reaches the array border there is no margin to add and the surface is open there either way, so nothing changes.

Input Arguments:

• mask - [logical] 3-D binary mask

Output Arguments:

• croppedMask - [logical] the bounding box plus margin; the input itself when the mask is empty, so a caller still gets an array of the expected rank

• cropOriginYXZ - [1x3 numeric] 1-based [row col page] the crop starts at; [1 1 1] when nothing was cropped

delete()¶

DELETE - Destructor: release live-update listeners/timer.

Safety net for the case where the controller is destroyed without closeWindow running - the live-update listeners live on the persistent mibModel and would otherwise keep firing on a stale handle.

deleteAllAnimationKeyFrames()¶

DELETEALLANIMATIONKEYFRAMES - Delete all animation key frames after user confirmation.

Syntax:

obj.deleteAllAnimationKeyFrames()

disableLiveUpdate()¶

DISABLELIVEUPDATE - Remove the live-update listeners and stop the debounce timer.

Syntax:

obj.disableLiveUpdate()

enableLiveUpdate()¶

ENABLELIVEUPDATE - Register the debounced listeners that drive live overlay updates.

Syntax:

obj.enableLiveUpdate()

Registers SetData listeners that funnel into the debounced liveUpdateRequest(). SetData (not ShowImage) is used because it fires only when the data actually changes, whereas ShowImage also fires on every pan / zoom / slice change and would trigger needless refetches:

• SetData on mibModel - fired by models.MibModel.moveLayers() (e.g. add/subtract to model).

• SetData on the active dataset (mibModel.I{id}) - fired by the core setData2D/3D/4D whenever a listener exists (event.hasListener guard), which is how a brush selection commit is caught (it goes through setData2D and emits no mibModel notification).

fetchOverlayMask(overlayType, materialIndex)¶

FETCHOVERLAYMASK - Read one material from MIB and match it to the rendered volume.

Syntax:

overlayMask = obj.fetchOverlayMask(overlayType, materialIndex)

Uses the same pyramid level and downsample factor as modelUpdateOverlay(), so the returned mask is aligned with obj.volume.Data voxel for voxel.

Input Arguments:

• overlayType - [char] layer type, normally 'labels'

• materialIndex - [numeric] material index to fetch, or NaN for every material at once - which returns the layer’s own values rather than a binary map, and is how generateAllObjectSurfaces() gets at the object ids (the rendered overlay holds cycled bin numbers, not indices)

Output Arguments:

• overlayMask - binary uint8 map of the requested material, or the label volume itself when materialIndex is NaN

generateAllObjectSurfaces()¶

GENERATEALLOBJECTSURFACES - One surface per object, for the cycled-colour mode.

Syntax:

generated = obj.generateAllObjectSurfaces()

In the 'All materials' mode a large model has a single table row standing for every material, because the overlay colours cycle through 255 slots. Generating from that row used to be refused; it now means what it says, one surface for each object present.

The prompt comes first and names the count, because this is the one action in the table whose cost scales with the model rather than with the selection: each object is meshed separately and each becomes its own images.ui.graphics3d.Surface, so a few hundred objects is a wait and several thousand is a long one. Cancelling stops at the object in progress and keeps the surfaces already made - they are complete in themselves, unlike a half-read volume.

Output Arguments:

• generated - [logical] true when at least one surface was added

generateColorMap()¶

GENERATECOLORMAP - Build obj.volumeColormap from current colormap settings.

Syntax:

obj.generateColorMap()

Constructs the colormap vector from obj.Settings.Volume.colormapName and obj.Settings.Volume.colormapInvert, then applies it to the volume and axes.

generateFusedInstancesSurface()¶

GENERATEFUSEDINSTANCESSURFACE - One surface over every object of a fused instance model.

Syntax:

generated = obj.generateFusedInstancesSurface()

Confirms first, because the result is not what “generate surface” means anywhere else in this table: one mesh spanning every object, with touching objects joined into single connected components and no way to pick one of them apart afterwards. The count is named in the prompt so the scale of that is visible before the wait, and the alternative is named too, since “Generate surface by index…” reads the store’s own ids and is unaffected by the fusing.

Output Arguments:

• generated - [logical] false when cancelled or when nothing was found to surface; the caller refreshes the table only on true

generatePositionsForKeyFramesAnimation(noFrames, options)¶

GENERATEPOSITIONSFORKEYFRAMESANIMATION - Interpolate camera positions from key frames.

Syntax:

positions = obj.generatePositionsForKeyFramesAnimation(noFrames)
positions = obj.generatePositionsForKeyFramesAnimation(noFrames, options)

Input Arguments:

• noFrames - [numeric] total number of interpolated frames

• options (optional) - struct with additional parameters:

  • .back_and_forth - [logical] when 1, animate forward then reverse

Output Arguments:

• positions - struct with per-frame camera data:

  • .CameraPosition - [N x 3] interpolated camera positions

  • .CameraUpVector - [N x 3] interpolated camera-up vectors

  • .CameraTarget - [] (target is fixed; reserved for future use)

generatePositionsForSpinAnimation(noFrames, options)¶

GENERATEPOSITIONSFORSPINANIMATION - Generate camera positions for a spin animation.

Syntax:

positions = obj.generatePositionsForSpinAnimation(noFrames)
positions = obj.generatePositionsForSpinAnimation(noFrames, options)

Input Arguments:

• noFrames - [numeric] number of frames (default: 120)

• options (optional) - struct with rotation parameters:

  • .back_and_forth - [logical] animate forward then reverse (default: 0)

  • .clockwise - [numeric] 1 for clockwise, 0 for anticlockwise (default: 0)

  • .rotAxis - [char] rotation axis: 'X-axis', 'Y-axis', or 'Z-axis'

Output Arguments:

• positions - struct with per-frame camera data:

  • .CameraPosition - [N x 3] array of camera positions

  • .CameraUpVector - [1 x 3] fixed up-vector for the chosen spin axis

  • .CameraTarget - [1 x 3] fixed camera target (centre of volume)

generateSurfaceByMaterialIndex()¶

GENERATESURFACEBYMATERIALINDEX - Generate a surface for a material given by its index.

Syntax:

obj.generateSurfaceByMaterialIndex()

Asks for a material index and refetches that material from MIB as a binary mask, so it works for any material of a large model, including those that are not currently listed in the material table.

grabFrame(width, height, options)¶

GRABFRAME - Capture a frame image from the volume viewer panel.

Syntax:

imgOut = obj.grabFrame(width, height)
imgOut = obj.grabFrame(width, height, options)

The getframe call below costs close to a second because the pixels have to be read back out of the WebGL canvas that viewer3d renders into; the volume rendering itself takes about 20 ms. That is a MATLAB limitation with no faster public API - see development/notes/volren_movie_capture_speed.md for the measurements and the routes already ruled out, before trying to optimise it.

Input Arguments:

• width - [numeric] snapshot width in pixels; [] uses the current panel width

• height - [numeric] snapshot height in pixels; [] uses the current panel height

• options (optional) - struct with extra parameters:

  • .resizeWindow - [numeric] 1 resize window before capture, 0 skip (default: 1)

  • .showWaitbar - [logical] show a progress waitbar (default: true)

  • .hWaitbar - [handle] handle to an existing waitbar dialog

  • .waitbarProgress - [numeric] waitbar fill fraction (default: 0.5)

Output Arguments:

• imgOut - [uint8] [height x width x 3] RGB image array

Errors:

• MIB:VolRenApp:grabFrame:frameTooLarge - the requested width/height exceeds the visible area of the screen, so the viewer window cannot be resized to fit the frame. The window is restored before the error is thrown; callers are expected to catch it and show utils.dlgs.showErrorDialog. When options.resizeWindow is 0 restoring the window is left to the caller.

Example 1 - capture frames inside an animation loop:

obj.prepareWindowForGrabFrame(width, height);
options.resizeWindow = 0;
for i = 1:100
    % change view
    imgOut = obj.extraController.grabFrame(width, height, options);
end
obj.extraController.restoreWindowAfterGrabFrame();

Example 2 - single snapshot (e.g., from mibSnapshotController):

imgOut = obj.extraController.grabFrame(width, height);

grabVolume(volumeType, colorChannel)¶

GRABVOLUME - Fetch the current MIB dataset volume into the 3D viewer.

Syntax:

status = obj.grabVolume()
status = obj.grabVolume(volumeType, colorChannel)

For BigData datasets a pyramid-level picker dialog is shown rather than the downsample-factor dialog. Each entry lists the spatial dimensions of that level and an estimated in-memory footprint (budget cap: 512 MB). The selected level is stored in obj.pyramidLevel; the read options come from levelReadOptions(), which retrieves the full pyramid level rather than just the current viewport block - and translates the level for a label pyramid that is not the image’s own. obj.volumeScaleFactor is set to 1 because the pyramid already provides the downsampling. The voxel size at the chosen level is taken from image.pyramid.levelVoxelSizes ([y x z]) - directly when that array holds a per-level row, otherwise the full-resolution base row scaled by image.pyramid.levelScaleFactors(obj.pyramidLevel, :) - to preserve physical (µm) units in the 3D viewer. Note BioFormats-backed BigData leaves image.pixSize empty, so the voxel size is always sourced from the pyramid.

For Standard datasets the original user-entered downsample-factor dialog is used.

For models with 256 materials and more the material dropdown is replaced by a spinner for the material index, because labels.materialNames only keeps two renameable slots for those model types and cannot list the materials.

Input Arguments:

• volumeType (optional) - [char] volume layer to load (default: 'image'):

  • 'image' - intensity image data

  • 'labels' - segmentation labels

  • 'selection' - selection layer

  • 'mask' - mask layer

• colorChannel (optional) - [numeric] color channel or material index (default: 1)

Output Arguments:

• status - [numeric] 1 on success, 0 if cancelled

groupDigits(~, value)¶

GROUPDIGITS - Thousands separators, so a seven-digit face count can be read at a glance.

Syntax:

text = obj.groupDigits(value)

Input Arguments:

• value - [numeric] non-negative integer

Output Arguments:

• text - [char] the number with a space every three digits

keyFrameTable_CellSelection(indices)¶

KEYFRAMETABLE_CELLSELECTION - Handle cell selection in the key-frame table.

Syntax:

obj.keyFrameTable_CellSelection(indices)

Input Arguments:

• indices - [numeric] selected cell indices [row, col]

keyFrameTable_cm_Callback(event)¶

KEYFRAMETABLE_CM_CALLBACK - Callback for the key-frame table context menu.

Syntax:

obj.keyFrameTable_cm_Callback(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the action:

  • 'keyFrameTable_cm_jumpToKeyFrame' - jump to the selected key frame

  • 'keyFrameTable_cm_insertKeyFrame' - insert a key frame at the current position

  • 'keyFrameTable_cm_replaceKeyFrame' - replace the selected key frame with the current view

  • 'keyFrameTable_cm_removeKeyFrame' - remove the selected key frame

levelReadOptions(layerType)¶

LEVELREADOPTIONS - getData3D options that read one layer at the level picked in the dialog.

Syntax:

getOptions = obj.levelReadOptions(layerType)

obj.pyramidLevel indexes the image pyramid, which is the only list the level dialog shows. Passing it straight through as options.pyramidLevel is right for every layer served from that same pyramid, and wrong for a core.MibBigDataLabelsIndex overlay, which is served from a pyramid of its own that starts coarser and has fewer levels: jrc_mus-kidney’s nuc has 5 levels from 128 nm where the EM has 12 from 8 nm, so image level 5 means the labels’ level 5 - two levels past the end of the store, clamped to its coarsest - and the overlay arrives 16x too coarse, then stretched onto the volume by the imresize3 fallback.

For that layer the level is therefore expressed as a magnification instead: the scale factor of the chosen image level, in the shared scale space core.MibBigDataLabelsIndex.imageScaleFactors registers both pyramids into. getData then picks the nearest label level itself and gathers it onto the image level’s grid, so the overlay comes back at the image level’s dimensions - aligned rather than resized, which is the distinction the class exists for.

Input Arguments:

• layerType - [char] layer about to be read: 'image', 'labels', 'mask' or 'selection'

Output Arguments:

• getOptions - [struct] options for getData3D; empty for a Standard dataset, which downsamples with obj.volumeScaleFactor after the read instead

liveUpdateFire()¶

LIVEUPDATEFIRE - Debounce-timer callback that performs the queued overlay refresh.

Syntax:

obj.liveUpdateFire()

liveUpdateRequest()¶

LIVEUPDATEREQUEST - Queue a debounced overlay refresh in response to a SetData event.

Syntax:

obj.liveUpdateRequest()

Called on every SetData notification while live update is on. Restarts a one-shot timer so a burst of segmentation strokes collapses into a single overlay refetch after the user pauses (~0.2 s).

loadAnimationPath()¶

LOADANIMATIONPATH - Load an animation path from a .animation file.

Syntax:

obj.loadAnimationPath()

makeAnimation(mode)¶

MAKEANIMATION - Open the MakeMovie dialog for recording an animation.

Syntax:

obj.makeAnimation(mode)

Input Arguments:

• mode - [char] animation type:

  • 'spin' - rotate camera around the selected axis

  • 'animation' - animate the scene using stored key frames

makeSnapshop()¶

MAKESNAPSHOP - Open the Snapshot dialog for the current viewer state.

Syntax:

obj.makeSnapshop()

materialsSelectionAsText()¶

MATERIALSSELECTIONASTEXT - Format obj.overlayMaterialsSelection for the edit field.

Syntax:

materialsText = obj.materialsSelectionAsText()

Output Arguments:

• materialsText - [char] comma separated list of the rendered material indices, without spaces, for example 1,2,3,4

menuChangeView(event)¶

MENUCHANGEVIEW - Callback for standard orthogonal view menu items.

Syntax:

obj.menuChangeView(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the view:

  • 'menuDefaultView' - restore the saved default view

  • 'menuXYview' - show the XY (top-down) view

  • 'menuXZview' - show the XZ (front) view

  • 'menuYZview' - show the YZ (side) view

modelHideAllMaterials(hideMaterialsSwitch)¶

MODELHIDEALLMATERIALS - Hide or show all overlay materials at once.

Syntax:

obj.modelHideAllMaterials()
obj.modelHideAllMaterials(hideMaterialsSwitch)

Input Arguments:

• hideMaterialsSwitch (optional) - [logical] true to hide, false to show (default: reads obj.view.handles.modelHideAllCheckBox.Value)

modelHideAllSurfaces(hideSurfacesSwitch)¶

MODELHIDEALLSURFACES - Hide every surface at once, or restore them individually.

Syntax:

obj.modelHideAllSurfaces()
obj.modelHideAllSurfaces(hideSurfacesSwitch)

Callback of the surfacesHideAll checkbox. true hides every surface; false puts each one back to its own show state from the surface table rather than turning all of them on, so a surface the user had unticked stays unticked.

That is only possible because the per-surface intent lives in surfListShown. Reading it back from each surface’s Visible would not work: hiding everything overwrites exactly the answer that would have to be restored.

Input Arguments:

• hideSurfacesSwitch (optional) - [logical] true to hide all, false to restore (default: reads the checkbox)

modelTableCellEdit(event)¶

MODELTABLECELLEDIT - Handle in-place edits in the model/overlay material table.

Syntax:

obj.modelTableCellEdit(event)

modelTable_CellSelection(indices)¶

MODELTABLE_CELLSELECTION - Handle cell selection in the model/overlay table.

Syntax:

obj.modelTable_CellSelection(indices)

Input Arguments:

• indices - [numeric] selected cell indices [row, col]

modelTable_cm_Callback(event)¶

MODELTABLE_CM_CALLBACK - Callback for the model table context menu.

Syntax:

obj.modelTable_cm_Callback(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the action:

  • 'modelTable_cm_generateSurface' - generate a surface mesh from the selected rows

  • 'modelTable_cm_generateSurfaceByIndex' - ask for a material index and generate its surface; the only option in the cycled color mode, where a table row stands for 255 materials rather than one

  • 'modelTable_cm_removeMaterials' - drop the selected rows from the 'Selected materials' list and refresh the overlay

modelUpdateOverlay(overlayType, materialId)¶

MODELUPDATEOVERLAY - Fetch an overlay layer from MIB and apply it to the volume.

Syntax:

obj.modelUpdateOverlay()
obj.modelUpdateOverlay(overlayType, materialId)

For BigData datasets the overlay is read at the level chosen in the grabVolume dialog, through levelReadOptions() - which is also what keeps a core.MibBigDataLabelsIndex overlay at the right resolution, since its pyramid is not the image’s and the level indices do not correspond. If the returned overlay dimensions still differ from the in-memory image volume (obj.volume.Data), a nearest-neighbour imresize3 is applied so the overlay aligns pixel-for-pixel with the rendered volume. For Standard datasets the same downsample path as grabVolume is used (obj.volumeScaleFactor resize via imresize3).

The fetched layer is passed through buildOverlayIndexVolume(), which packs it into the 255 colour slots that volshow provides. That is what makes models with 65535 or 4294967295 materials renderable: they are either cycled through 255 colours or reduced to the material indices listed in the overlayMaterialsList widget.

Input Arguments:

• overlayType (optional) - [char] overlay layer type:

  • 'labels' - segmentation labels (model) layer

  • 'mask' - mask layer

  • 'selection' - selection layer

• materialId (optional) - [numeric] material index; NaN to load all materials

overlayIsFusedInstances()¶

OVERLAYISFUSEDINSTANCES - Is the shown overlay an instance model collapsed to one material?

Syntax:

isFused = obj.overlayIsFusedInstances()

True for a core.MibBigDataLabelsIndex overlay read with core.MibBigDataLabelsIndex.renderPerObject off. That layer declares maxMaterials = 65535, so the material table takes the cycled-colour branch and calls the single row “255 materials” - but the values were fused to 1 on read, so the row really is one material. The two disagree, and every per-material action has to ask which is true.

Only meaningful for the 'labels' source; a mask or selection overlay is a single material already and never reaches the cycled branch.

Output Arguments:

• isFused - [logical] true when the row stands for every object fused into one material rather than for 255 cycled ones

overlayMaterialsModeChanged()¶

OVERLAYMATERIALSMODECHANGED - Switch between the cycled and the selected materials mode.

Syntax:

obj.overlayMaterialsModeChanged()

Callback target for the overlayMaterialsMode dropdown. When the 'Selected materials' mode is entered with an empty list, the list is seeded from the material selected in the main MIB window so that something is rendered.

plotAlphaPlot()¶

PLOTALPHAPLOT - Redraw the alpha curve plot in obj.view.handles.alphaAxes.

Syntax:

obj.plotAlphaPlot()

prepareWindowForGrabFrame(width, height)¶

PREPAREWINDOWFORGRABFRAME - Resize and prepare the viewer window for frame capture.

Syntax:

obj.prepareWindowForGrabFrame(width, height)

Stores current window geometry, hides the toolbar, and sets the viewer panel to exactly width × height pixels ready for grabFrame.

Input Arguments:

• width - [numeric] desired capture width in pixels

• height - [numeric] desired capture height in pixels

Usage example:

obj.extraController.prepareWindowForGrabFrame(width, height);
imgOut = obj.extraController.grabFrame(width, height);
obj.extraController.restoreWindowAfterGrabFrame();

previewAnimation(noFrames)¶

PREVIEWANIMATION - Preview the key-frame animation in the viewer.

Syntax:

obj.previewAnimation()
obj.previewAnimation(noFrames)

Input Arguments:

• noFrames (optional) - [numeric] number of interpolated frames (default: obj.Settings.Animation.noFrames)

recalculateAlphamap(transparentVolume)¶

RECALCULATEALPHAMAP - Recalculate and apply the volume alpha map.

Syntax:

obj.recalculateAlphamap()
obj.recalculateAlphamap(transparentVolume)

Input Arguments:

• transparentVolume (optional) - [logical] when true, set alphamap to 0 making the volume fully transparent (default: false)

refreshOverlay()¶

REFRESHOVERLAY - Pull the latest segmentation into the overlay (manual Refresh button).

Syntax:

obj.refreshOverlay()

Callback target for refreshOverlayButton (ButtonPushedFcn). On the first call (no overlay yet) it does a full modelUpdateOverlay() so the colormap, alphamap and material table are initialised; afterwards it does the lightweight refreshOverlayData() that preserves per-material visibility.

refreshOverlayData()¶

REFRESHOVERLAYDATA - Lightweight overlay re-fetch for live updates.

Syntax:

obj.refreshOverlayData()

Re-reads the active overlay layer at the current pyramid level, passes it through buildOverlayIndexVolume() and updates only obj.volume.OverlayData - material visibility, colormap, alphamap and the material table are left untouched (unlike modelUpdateOverlay which re-initialises them). Used as the manual “Refresh overlay” action and the debounced live-update refetch.

restoreWindowAfterGrabFrame()¶

RESTOREWINDOWAFTERGRABFRAME - Restore viewer window geometry after frame capture.

Syntax:

obj.restoreWindowAfterGrabFrame()

Reverses the changes made by prepareWindowForGrabFrame, restoring the original panel size and toolbar visibility.

saveAnimationPath()¶

SAVEANIMATIONPATH - Save the current animation path to a .animation file.

Syntax:

obj.saveAnimationPath()

showHelp()¶

SHOWHELP - Open the MIB 3D viewer help page in the system browser.

Syntax:

obj.showHelp()

showVolume(showSwitch)¶

SHOWVOLUME - Toggle visibility of the main volume object.

Syntax:

obj.showVolume()
obj.showVolume(showSwitch)

Input Arguments:

• showSwitch (optional) - [logical] true to show, false to hide (default: reads obj.view.handles.showVolumeCheckBox.Value)

spinDataset()¶

SPINDATASET - Preview a camera spin animation around the dataset.

Syntax:

obj.spinDataset()

stopLiveUpdateTimer()¶

STOPLIVEUPDATETIMER - Stop and delete the live-update debounce timer if present.

Syntax:

obj.stopLiveUpdateTimer()

surfaceTableCellEdit(event)¶

SURFACETABLECELLEDIT - Handle in-place edits in the surface table.

Syntax:

obj.surfaceTableCellEdit(event)

surfaceTable_CellSelection(indices)¶

SURFACETABLE_CELLSELECTION - Handle cell selection in the surface table.

Syntax:

obj.surfaceTable_CellSelection(indices)

Input Arguments:

• indices - [numeric] selected cell indices [row, col]

surfaceTable_cm_Callback(event)¶

SURFACETABLE_CM_CALLBACK - Callback for the surface table context menu.

Syntax:

obj.surfaceTable_cm_Callback(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the action:

  • 'surfaceTable_cm_saveSurface' - save the selected surface to an STL file

  • 'surfaceTable_cm_removeSurface' - delete the selected surface from the viewer

surfacesHiddenAll()¶

SURFACESHIDDENALL - State of the “hide all surfaces” checkbox.

Syntax:

hideAll = obj.surfacesHiddenAll()

Behind an accessor because the checkbox is the newest widget on the Surfaces tab: a view built before it was added has no such handle, and every surface would then be invisible rather than the feature simply being absent.

Output Arguments:

• hideAll - [logical] false when the checkbox does not exist

toggleLiveUpdate()¶

TOGGLELIVEUPDATE - Enable or disable live overlay updates from the GUI checkbox.

Syntax:

obj.toggleLiveUpdate()

Callback target for liveUpdateCheckBox (ValueChangedFcn). When checked, debounced SetData listeners re-fetch the model overlay as the user segments in the main MIB window; when unchecked the listeners and the debounce timer are removed.

toggleViewerSettings(event)¶

TOGGLEVIEWERSETTINGS - Toggle viewer display settings on or off.

Syntax:

obj.toggleViewerSettings(event)

Input Arguments:

• event - [event] UI callback event from the toggled widget

transparentVolume(transparentSwitch)¶

TRANSPARENTVOLUME - Make the volume transparent to reveal the overlay model.

Syntax:

obj.transparentVolume()
obj.transparentVolume(transparentSwitch)

Input Arguments:

• transparentSwitch (optional) - [logical] true to make transparent, false to restore (default: reads obj.view.handles.transparentVolumeCheckBox.Value)

updateAnimationNumberOfFrames(noFrames)¶

UPDATEANIMATIONNUMBEROFFRAMES - Update the stored animation frame count.

Syntax:

obj.updateAnimationNumberOfFrames(noFrames)

Input Arguments:

• noFrames - [numeric] new frame count stored in obj.Settings.Animation.noFrames

updateBackgroundColor(event)¶

UPDATEBACKGROUNDCOLOR - Update the viewer background colour settings.

Syntax:

obj.updateBackgroundColor(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the operation:

  • 'menuBackgroundColor' - update the primary background colour

  • 'menuBackgroundGradientColor' - update the gradient background colour

updateCameraPosition(event)¶

updateCameraWidgets()¶

UPDATECAMERAWIDGETS - Refresh camera position and orientation widgets.

Syntax:

obj.updateCameraWidgets()

updateColormap(event)¶

UPDATECOLORMAP - Update the volume colormap from a widget selection event.

Syntax:

obj.updateColormap(event)

Input Arguments:

• event - [event] UI callback event; event.Source.Tag selects the field to update:

  • 'colormapName' - name of the selected colormap

  • 'colormapInvert' - logical flag to invert the colormap

  • 'colormapBlackPoint' - black-point adjustment value

  • 'colormapWhitePoint' - white-point adjustment value

updateIsovalue(newIsovalue)¶

UPDATEISOVALUE - Update the isosurface or gradient opacity value of the volume.

Syntax:

obj.updateIsovalue(newIsovalue)

Input Arguments:

• newIsovalue - [numeric] new isovalue or gradient opacity value [0..1]

updateKeyFrameTable()¶

UPDATEKEYFRAMETABLE - Refresh the key-frame table widget.

Syntax:

obj.updateKeyFrameTable()

updateModelTable()¶

UPDATEMODELTABLE - Refresh the model/overlay material table widget.

Syntax:

obj.updateModelTable()

The rows come from the mapping generated by buildOverlayIndexVolume(), so a model with 65535 materials produces either a single row (cycled colors) or one row per selected material index, never one row per material.

updateOverlayMaterialWidgets()¶

UPDATEOVERLAYMATERIALWIDGETS - Enable the large-model overlay widgets when they apply.

Syntax:

obj.updateOverlayMaterialWidgets()

The materials mode, the index list and the “Add current” button only make sense for the 'labels' overlay of a model with 256 materials or more; for everything else the material table already lists every material.

updateOverlayRenderingStyle()¶

UPDATEOVERLAYRENDERINGSTYLE - Update the overlay rendering style.

Syntax:

obj.updateOverlayRenderingStyle()

updateScalingTransform(pixSize)¶

UPDATESCALINGTRANSFORM - Generate the affine scaling transform for the volume.

Syntax:

obj.updateScalingTransform(pixSize)

Builds obj.scalingTransform (an affinetform3d) from the pixel size so that the dataset is displayed with units in µm.

Input Arguments:

• pixSize - [struct] MIB pixel-size structure:

  • .x - pixel size in X (µm/pixel)

  • .y - pixel size in Y (µm/pixel)

  • .z - slice thickness in Z (µm/slice)

updateSurfaceTable()¶

UPDATESURFACETABLE - Refresh the surface table widget with current surface data.

Syntax:

obj.updateSurfaceTable()

updateVolumeRenderingStyle()¶

UPDATEVOLUMERENDERINGSTYLE - Update the volume rendering style.

Syntax:

obj.updateVolumeRenderingStyle()

Reads obj.view.handles.rendererDropDown.Value and updates widget states and obj.volume.RenderingStyle accordingly. Supported styles: 'VolumeRendering', 'MaximumIntensityProjection', 'MinimumIntensityProjection', 'GradientOpacity', 'Isosurface', 'SlicePlanes'.

updateWidgets()¶

UPDATEWIDGETS - Refresh all widgets in the VolRenApp panel.

Syntax:

obj.updateWidgets()