MibLabels63

class core.MibLabels63

Bases: core.@MibImage.MibImage

MIBLABELS63 - memory optimized label class of MIB3 capable to encode 63 materials,.

mask and selection layers within the same 8-bit container. 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
MibLabels63(img, meta)

MIBLABELS63 - Constructor of MibLabels63 - memory-optimised label storage.

Syntax:
obj = MibLabels63()
obj = MibLabels63(img)
obj = MibLabels63(img, meta)

Initializes a memory-optimised segmentation label container that packs up to 63 materials, mask, and selection into a single uint8 array: bits 1-6 = material index, bit 7 = mask, bit 8 = selection. Inherits all properties and methods from core.MibImage.

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

Input Arguments:

  • img - (optional) [uint8 array] 2-D to 5-D packed data, or []. Dimension 3 is always treated as depth (Z), never as color:

    • [] - empty placeholder; obj.exists = false

    • [H, W] - single 2-D packed label map

    • [H, W, Z] - 3-D packed 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 (always 1), obj.time, obj.dim_yxzct, obj.maxInt, obj.dataClass.

Example 1 - create 3-D packed label volume from data:

rawModel = uint8(zeros(254, 378, 3));  % [H,W,Z]
meta = core.MibImage.initializeImgInfo( ...
    'pixSize', obj.image.pixSize, ...
    'Height', 254, 'Width', 378, 'Depth', 3, 'Time', 1, 'Colors', 1);
lbl = core.MibLabels63(rawModel, meta);
% lbl.depth == 3, lbl.colors == 1

Example 2 - create fresh empty allocation matching current image:

dims = [obj.image.height, obj.image.width, obj.image.depth, 1, obj.image.time];
meta = core.MibImage.initializeImgInfo( ...
    'pixSize', obj.image.pixSize, ...
    'Height', dims(1), 'Width', dims(2), 'Depth', dims(3), 'Time', dims(5));
lbl = core.MibLabels63(zeros(dims, 'uint8'), meta);

Example 3 - create empty placeholder:

lbl = core.MibLabels63();
% lbl.exists == false
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; equals numel(materialNames). Updated by addMaterial (+1), removeMaterial (-N), and createModel (initial value).

Method Summary
countMaterials()

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

Syntax:
result = obj.countMaterials()

When materialNames is available (non-empty), the count is taken from numel(materialNames). Otherwise the method scans the pixel data across all time-points, extracts the model bits (bits 1-6, mask 0x3F = 63) from the packed uint8 container, and finds the highest non-zero material 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
getData63(type, orient, materialIndex, options)

get complete 5D dataset GETDATA63 - Get dataset from MibLabels63 class.

Syntax:
dataset = obj.getData63(type, orient, materialIndex, options) % get complete 5D dataset
Input Arguments:

  • type - char with the type of layer to obtain, ‘labels’, ‘mask’, ‘selection’, or ‘everything’ to get all layers at once

  • orient - (optional), can be []; default 3:

    • 1 - returns transposed dataset in ZX configuration: [y,x,z,c,t] → [z,x,y,c,t] (rows = Z, columns = X)

    • 2 - returns transposed dataset in ZY configuration: [y,x,z,c,t] → [y,z,x,c,t]

    • 3 - returns original dataset in YX configuration: [y,x,z,c,t]

  • materialIndex - (optional), can be []:

    • for type = 'labels': integer material index (returned as binary 0/1); [] = all materials

    • for type = 'mask', 'selection', 'everything': not used

  • options - (optional), a structure with extra parameters

    • .y (optional), [ymin, ymax] coordinates of the dataset to take after transpose, can be a single number

    • .x (optional), [xmin, xmax] coordinates of the dataset to take after transpose, can be a single number

    • .z (optional), [zmin, zmax] coordinates of the dataset to take after transpose, can be a single number

    • .t (optional), [tmin, tmax] coordinates of the dataset to take after transpose, can be a single number

Output Arguments:

  • dataset - 5D stack, [1:height, 1:width, 1:depth, 1:colors, 1:time]

Usage:

Example 1

dataset = obj.getData('mask', 3, []);% get mask for the complete dataset in the YX orientation

Example 2

options.x = [100 200];
options.y = [100 200];
options.z = 100;
options.t = 1;
materialIndex = 2;
dataset = obj.getData('labels', [], materialIndex, options);% get labels, subvolume = [100:200, 100:200] at slice 100, material 2
insertMaterial(index, name, wb)

INSERTMATERIAL - Insert a material at the specified position (type-63 bit-packed model).

Syntax:
obj.insertMaterial(index, name, wb)

For the bit-packed format (maxMaterials = 63), the model occupies bits 1-6 of each uint8 element. When inserting in the middle, all model values >= index are incremented by 1 while preserving mask (bit 7) and selection (bit 8) bits. When appending at the end, only the name and colour are added.

Input Arguments:

  • index - double, 1-based position where the new material is inserted.

  • name - char, name for the new material.

  • 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 MibLabels63 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.

MibLabels63 packs model (bits 1-6), mask (bit 7), and selection (bit 8) into a single uint8 array. This override calls getData63() to correctly unpack the model layer before saving - whereas the base MibImage.save() would write the raw packed bytes.

Supported formats: same as core.MibLabels.save (see io.SaverFactory.getFormats(‘labels’))

NOTE ON pixSize: MibLabels63 does not store pixel size. Supply options.pixSize, or it defaults to 1x1x1 um.

Input Arguments:

  • obj - MibLabels63 instance

  • filename - (char) full output path including extension

  • options - (optional) struct with saving options:

    • .Format - (char) format string; inferred from extension when absent

    • .Saving3DPolicy - (char) '3D stack' | '2D sequence'; default '3D stack'

    • .showWaitbar - (logical) default true

    • .silent - (logical) suppress dialogs; default false

    • .overwrite - (logical) default true

    • .MaterialIndex - (double|[]) 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.saveImage()

    • .boundingBox - ([1×6]) injected by MibDataset.saveImage()

    • .annotations - (struct) injected by MibDataset.saveImage() when present

Output Arguments:

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

Usage:

Example 1 - Save type-63 model via MibDataset (recommended: pixSize injected)

opts.Format      = 'Matlab format (*.model)';
opts.showWaitbar = false;
opts.silent      = true;
opts.overwrite   = true;
fnOut = obj.mibModel.I{obj.mibModel.id}.saveImage('labels', '/output/model.model', opts);

Example 2 - Direct call (standalone, no MibDataset)

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 = labels63.save('/output/model63.model', opts);
setData63(dataset, type, orient, materialIndex, options)

SETDATA63 - Set dataset to MibLabels63 class.

Syntax:
result = obj.setData63(dataset, type, orient, materialIndex, options)
Input Arguments:

  • dataset - matrix with the dataset to update MibBaseImage.img

  • type - char with the type of layer to obtain, ‘labels’, ‘mask’, ‘selection’, or ‘everything’ to get all layers at once

  • orient - (optional), can be []; default 3:

    • 1 - updates transposed dataset from ZX configuration: [z,x,y,c,t] → [y,x,z,c,t] (rows = Z, columns = X)

    • 2 - updates transposed dataset from ZY configuration: [y,z,x,c,t] → [y,x,z,c,t]

    • 3 - updates original dataset from YX configuration: [y,x,z,c,t]

  • materialIndex - (optional), can be []:

    • for type = 'labels': integer material index (returned as binary 0/1); [] = all materials

    • for type = 'mask', 'selection', 'everything': not used

  • options - (optional), a structure with extra parameters

    • .y (optional), [ymin, ymax] coordinates of the dataset to set after transpose, can be a single number

    • .x (optional), [xmin, xmax] coordinates of the dataset to set after transpose, can be a single number

    • .z (optional), [zmin, zmax] coordinates of the dataset to set after transpose, can be a single number

    • .t (optional), [tmin, tmax] coordinates of the dataset to set after transpose, can be a single number

Output Arguments:

  • result - 1 - success, 0 - error

Usage:

Example 1

obj.setData63(dataset, 'labels', 3, []);% set the complete model in the YX orientation

Example 2

options.x = [100 200];
options.y = [100 200];
options.z = 100;
options.t = 1;
colChannel = 2;
obj.setData63(dataset, 'labels', [], colChannel, options);% set subvolume = [100:200, 100:200] at slice 100, color channel 1
swapMaterials(index1, index2)

SWAPMATERIALS - Swap material names and colours between two positions.

Syntax:
obj.swapMaterials(index1, index2)

The caller is responsible for swapping the corresponding pixel values beforehand (see MibDataset.swapMaterials).

Input Arguments:

  • index1 - double, 1-based index of the first material.

  • index2 - double, 1-based index of the second material.

Output Arguments:

Usage:

Example 1

obj.mibModel.I{obj.mibModel.id}.labels.swapMaterials(1, 3);% swap materials 1 and 3