MibLabels¶

class core.MibLabels¶

Bases: core.@MibImage.MibImage

MIBLABELS - a base label class of MIB3.

The class inherits properties and function of the parent class (core.MibImage). Constructor requires initialization as “obj = obj@core.MibImage(img, meta); % Call parent constructor”

Constructor Summary

MibLabels(img, meta)¶

MIBLABELS - Constructor of MibLabels - segmentation label storage.

Syntax:

obj = MibLabels()
obj = MibLabels(img)
obj = MibLabels(img, meta)

Initializes a segmentation label container with up to 255 (or 65535 / 4294967295) materials. Inherits all properties and methods from core.MibImage.

Data layout: [H, W, Z, 1, T] - single color channel, with depth in dimension 3. MibLabels does NOT apply the [H,W,C]→[H,W,1,C] permutation that MibImage uses for colour images.

Input Arguments:

img - (optional) [numeric array] 2-D to 5-D uint8/uint16/uint32, or []. Dimension 3 is always treated as depth (Z), never as color:
- [] - empty placeholder; obj.exists = false
- [H, W] - single 2-D label map
- [H, W, Z] - 3-D label volume (Z slices)
- [H, W, Z, 1, T] - full 5-D form (preferred for clarity)
meta - (optional) [dictionary] metadata from core.MibImage.initializeImgInfo(). Pass [] to use defaults.

After construction, ALL dimension properties are set from the actual array size: obj.height, obj.width, obj.depth, obj.colors, obj.time, obj.dim_yxzct, obj.maxInt, obj.dataClass.

Example 1 - create 3-D label volume:

rawLabels = uint8(zeros(254, 378, 3));
meta = core.MibImage.initializeImgInfo( ...
    'pixSize', obj.image.pixSize, ...
    'Height', 254, 'Width', 378, 'Depth', 3, 'Time', 1, 'Colors', 1);
lbl = core.MibLabels(rawLabels, meta);
% lbl.depth == 3, lbl.colors == 1

Example 2 - create empty placeholder:

lbl = core.MibLabels();
% lbl.exists == false

Example 3 - create and set large model type:

lbl = core.MibLabels(rawLabels, meta);
lbl.maxMaterials = 65535;

Property Summary

labelsVariable¶

materialColors¶

‘labelsVariable’

Type:¶: @em labelsVariable is a variable name in the mat-file to keep the ‘Labels’ layer’; default

materialNames¶: a matrix of colors [0-1] for materials of the ‘Model’, [materialIndex, R G B]

materialsCount¶: an array of strings to define names of materials of Labels

maxMaterials¶: number of materials currently in the model. For small models (63/255) this equals numel(materialNames). For large models (65535/4294967295) this is the highest material index that has been assigned - used by MibDataset.addMaterial to determine the next available index without scanning the full dataset. Updated by addMaterial (+1), removeMaterial (-N or recount), squeezeMaterialLabels (recount), and createModel (initial value).

objects3D¶: maximal number of materials available in this model type

Method Summary

countMaterials()¶

COUNTMATERIALS - Calculate and update obj.materialsCount from the current model state.

Syntax:

result = obj.countMaterials()

For small model types (255) the count is taken from numel(materialNames) when available. For large model types (65535/4294967295) materialNames always contains only two placeholder entries, so the method scans the pixel data across all time-points to find the highest non-zero label index.

This method should be called after loading or importing a model to ensure that materialsCount is synchronised with the actual data.

Input Arguments:

Output Arguments:

result - double, the updated materialsCount value.

Usage:

Example 1

n = obj.mibModel.I{obj.mibModel.id}.labels.countMaterials();% recount after load/import

insertMaterial(index, name, wb)¶

INSERTMATERIAL - Insert a material at the specified position.

Syntax:

obj.insertMaterial(index, name, wb)

For small models (maxMaterials < 256): - When appending at the end (index == nMats+1): only adds the name and a colour entry, no pixel shift is needed. - When inserting in the middle: shifts all pixel values >= index upward by 1 across every time-point in obj.data, then inserts the name at the correct position and appends a colour if the colour array is shorter than the name list.

For large models (maxMaterials >= 256): Shifts pixel values >= index upward by 1, then increments obj.materialsCount. No name/colour changes (large models use only placeholder names).

Input Arguments:

index - double, 1-based position where the new material is inserted.
name - char, name of the new material (used for small models; ignored for large models).
wb - (optional) handle to a uiprogressdlg for progress display; when empty no progress is reported.

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.labels.insertMaterial(3, 'Nucleus');% insert at position 3

Example 2

obj.mibModel.I{obj.mibModel.id}.labels.insertMaterial(5, 'New', wb);% with progress bar

renameMaterial(index, newName)¶

RENAMEMATERIAL - Rename one or all materials in the model metadata.

Syntax:

obj.renameMaterial(index, newName)

For small models (maxMaterials < 256) the material name at position index is replaced with newName. When index is 0, all materials are renamed at once using a comma-separated list in newName.

For large models (maxMaterials >= 256) the name is set at the given index; the caller is responsible for supplying a numeric string.

Input Arguments:

index - double, 1-based material index to rename. Use 0 to rename all materials at once (newName must then be a comma-separated list of names matching the number of existing materials).
newName - char, new material name (single name) or comma-separated list (when index == 0).

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.labels.renameMaterial(3, 'Nucleus');% rename material 3

Example 2

obj.mibModel.I{obj.mibModel.id}.labels.renameMaterial(0, 'A,B,C');% rename all three materials

reorderMaterials(newOrder)¶

REORDERMATERIALS - Reorder material names and colours according to newOrder.

Syntax:

obj.reorderMaterials(newOrder)

The caller is responsible for remapping the corresponding pixel values beforehand (see MibDataset.reorderMaterials).

Input Arguments:

newOrder - double vector, permutation of 1:numel(materialNames) specifying the new arrangement. For example [3 1 2] moves material 3 to position 1, material 1 to position 2, material 2 to position 3.

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.labels.reorderMaterials([3 1 2]);% rotate materials

save(filename, options)¶

SAVE - Save label/segmentation data from a MibLabels object to a file.

Syntax:

fnOut = obj.save(filename, options)

This method OVERRIDES core.MibImage.save() to inject label-specific metadata (material names, material colours, labels variable name) into the metadata struct before dispatching to io.SaverFactory.

MibLabels (and its sibling MibLabels63) stores multi-material segmentation data:

data{1} is a uint8/uint16 array where each voxel value indicates the material index (0 = exterior/background, 1..N = materials)

materialNames - cell array of strings naming each material

materialColors - [N x 3] matrix of per-material RGB colours (0..1)

labelsVariable - name used as the variable in .model/.mat files

Supported formats (from io.SaverFactory.getFormats('labels'))

'Matlab format (*.model)' - MIB3 native model file

'Matlab format 2D sequence (*.model)' - one file per Z-slice

'Matlab format for MIB ver. 1 (*.mat)' - legacy MIB v1 compatibility

'Matlab categorical format (*.mibCat)' - MATLAB categorical array

'Amira mesh binary (*.am)' - Amira binary mesh

'Amira mesh binary RLE compression SLOW (*.am)' - Amira RLE

'Amira mesh ascii (*.am)' - Amira ASCII mesh

'Hierarchical Data Format (*.h5)' - HDF5

'Hierarchical Data Format with XML header (*.xml)' - HDF5 + XML

'NRRD for 3D Slicer (*.nrrd)' - NRRD (3D Slicer)

'MRC Volume for IMOD (*.mrc)' - IMOD MRC volume

'Contours for IMOD (*.mod)' - IMOD model contours

'PNG format (*.png)' - PNG 2D sequence

'TIF format (*.tif)' - TIFF (stack or sequence)

'STL isosurface as binary (*.stl)' - STL mesh per material

NOTE ON pixSize: Like MibImage, MibLabels does not store pixel size. Supply options.pixSize, or it defaults to 1×1×1 µm.

Input Arguments:

obj - [MibLabels or MibLabels63] instance
filename - [char] full output path including extension, e.g. '/data/Labels_stack.model'
options - (optional) [struct] with saving options:
- .Format - [char] format string (see list above); inferred from file extension when absent
- .Saving3DPolicy - [char] '3D stack' | '2D sequence' (default: '3D stack')
- .showWaitbar - [logical] display progress bar (default: true)
- .silent - [logical] suppress dialogs (default: false)
- .overwrite - [logical] silently overwrite files (default: true)
- .MaterialIndex - [numeric or []] which material to export:
  - [] or NaN - all materials
  - integer - single material (returned as binary 0/1)
- .FilenameGenerator - [char] filename policy for 2D sequences: 'Use original filename' | 'Use sequential filename'
- .imageSliceNames - [cell of char] (optional) per-slice source filenames from the parent image layer, injected by MibDataset.saveImage(). When present and the labels object has no own sliceName, these names are forwarded to metadata.sliceName so that 2-D sequence savers can apply the 'Use original filename' policy.
- .pixSize - [struct] injected by MibDataset.save()
- .boundingBox - [1 x 6 numeric] injected by MibDataset.save()
- .annotations - [struct] (optional) injected by MibDataset.save():
  - .labelText - text label
  - .labelValue - numeric value
  - .labelPosition - coordinate position

Output Arguments:

fnOut - [char or cell of char] saved filename(s); [] on failure

Example 1 - save labels in MIB native format (standalone, no MibDataset needed):

labels = core.MibLabels(uint8(zeros(256,256,50,1,1)));
 labels.materialNames  = {'Nucleus'; 'ER'; 'Mitochondria'};
 labels.materialColors = [0 0 1; 0 1 0; 1 0 0];
 labels.labelsVariable = 'mibModel';

 opts.Format      = 'Matlab format (*.model)';
 opts.showWaitbar = false;
 opts.silent      = true;
 opts.overwrite   = true;
 opts.pixSize     = struct('x',0.065,'y',0.065,'z',0.2,'units','um','t',1,'tunits','s');
 opts.boundingBox = [0 16.6 0 16.6 0 10];

 fnOut = labels.save('/output/Labels_stack.model', opts);

Example 2 - export only one material as TIFF sequence:

opts.Format         = 'TIF format (*.tif)';
 opts.Saving3DPolicy = '2D sequence';
 opts.MaterialIndex  = 2;   % export material 2 (ER) only; voxels → 1
 opts.showWaitbar    = true;
 opts.silent         = true;
 opts.overwrite      = true;
 opts.pixSize        = struct('x',0.065,'y',0.065,'z',0.2,'units','um','t',1,'tunits','s');
 fnOut = labels.save('/output/Labels_ER.tif', opts);

Example 3 - save labels as Amira mesh (binary):

opts.Format      = 'Amira mesh binary (*.am)';
 opts.showWaitbar = true;
 opts.silent      = true;
 opts.overwrite   = true;
 opts.pixSize     = struct('x',0.065,'y',0.065,'z',0.2,'units','um','t',1,'tunits','s');
 opts.boundingBox = [0 16.6 0 16.6 0 10];
 opts.layerType   = 'labels';  % required for AmiraMeshSaver to choose correct writer
 fnOut = labels.save('/output/Labels_stack.am', opts);

Example 4 - via MibDataset (recommended: pixSize and boundingBox are injected):

opts.Format      = 'Matlab format (*.model)';
 opts.showWaitbar = false;
 opts.silent      = true;
 opts.overwrite   = true;
 fnOut = dataset.save('labels', '/output/Labels_stack.model', opts);