MatlabSaver

class io.savers.MatlabSaver

Bases: io.savers.BaseSaver

MATLABSAVER - Saver for MIB native MATLAB-based binary formats.

Handles all native serialisation formats used by MIB:

‘Matlab format (*.model)’ - MIB2/MIB3 native segmentation model. Variables saved: <modelVariable>, modelMaterialNames, modelMaterialColors, BoundingBox, modelVariable, modelType, [labelText, labelValue, labelPosition if annotations present]

‘Matlab format 2D sequence (*.model)’ - one .model file per Z-slice; useful for very large datasets where a full 3-D .model is too large.

‘Matlab format for MIB ver. 1 (*.mat)’ - legacy format for MIB v1 compatibility. Variables: <modelVariable>, material_list, color_list, bounding_box, model_var.

‘Matlab categorical format (*.mibCat)’ - saves labels as a MATLAB categorical array, 3-D stack or 2-D sequence. Variables: imgOut (categorical), imgVariable, options.

‘Matlab format (*.mask)’ - binary mask in a MAT-file. Variable saved: maskImg (logical [H W D]).

DATA DIMENSIONS Input data : [H, W, D, C, T] - C=1 expected for all Matlab formats (labels/masks are always single channel)

METADATA FIELDS USED .materialNames - cell array of material name strings (labels formats) .materialColors - [M x 3] material RGB colours (labels formats) .labelsVariable - (char) variable name to use inside the .model file, default ‘mibModel’ .modelType - (integer) model type (e.g. 255, 63) .pixSize - struct with voxel dimensions .boundingBox - [xmin xmax ymin ymax zmin zmax] .annotations - (optional) struct with .labelText, .labelValue, .labelPosition from obj.annotations.getLabels()

USAGE EXAMPLES

%% 1. Save a segmentation model (MIB native format)
saver = io.SaverFactory.create('Matlab format (``*.model``)');

opts.Format      = 'Matlab format (``*.model``)';
opts.showWaitbar = true;
opts.silent      = true;
opts.overwrite   = true;

meta.filename       = 'myImage.tif';
meta.materialNames  = {'Nucleus'; 'ER'; 'Mitochondria'};
meta.materialColors = [0 0 1; 0 1 0; 1 0 0];  % R, G, B per material
meta.labelsVariable = 'mibModel';
meta.modelType      = 255;        % uint8 labels
meta.dataClass      = 'uint8';
meta.pixSize        = struct('x',0.065,'y',0.065,'z',0.2,'units','um','t',1,'tunits','s');
meta.boundingBox    = [0 41.6 0 41.6 0 6];

labels = uint8(rand(256,256,30,1,1) * 3);  % values 0,1,2,3
fnOut = saver.save(labels, meta, '/output/Labels_myImage.model', opts);

%% 2. Save mask in native MIB mask format
saver = io.SaverFactory.create('Matlab format (``*.mask``)');

opts.Format      = 'Matlab format (``*.mask``)';
opts.showWaitbar = false;
opts.overwrite   = true;

meta.filename    = 'myImage.tif';
meta.dataClass   = 'uint8';
meta.pixSize     = struct('x',0.065,'y',0.065,'z',0.2,'units','um','t',1,'tunits','s');

mask = uint8(rand(256,256,30,1,1) > 0.8);  % binary mask
fnOut = saver.save(mask, meta, '/output/Mask_myImage.mask', opts);

%% 3. Save as categorical format (for deep learning pipelines)
saver = io.SaverFactory.create('Matlab categorical format (``*.mibCat``)');

opts.Format         = 'Matlab categorical format (``*.mibCat``)';
opts.Saving3DPolicy = '3D stack';   % or '2D sequence'
opts.FilenamePolicy = 'Use existing name';
opts.showWaitbar    = false;
opts.overwrite      = true;

meta.materialNames  = {'Exterior'; 'Nucleus'; 'Background'};
meta.materialColors = [0.5 0.5 0.5; 0 0 1; 0 1 0];
meta.labelsVariable = 'imgOut';
meta.dataClass      = 'uint8';
meta.modelType      = 255;
meta.pixSize        = struct('x',0.065,'y',0.065,'z',0.2,'units','um','t',1,'tunits','s');

labels = uint8(rand(256,256,30,1,1) * 3);
fnOut = saver.save(labels, meta, '/output/Labels.mibCat', opts);

%% 4. Via MibModel (recommended for GUI/batch workflows)
BatchOpt.LayerType       = {'labels'};
BatchOpt.Format          = {'Matlab format (``*.model``)'};
BatchOpt.OutputDirectoryPolicy = {'Same as image'};
BatchOpt.FilenamePolicy  = {'Use existing name'};
BatchOpt.showWaitbar     = true;
BatchOpt.mibBatchTooltip.LayerType = '';
model.save('labels', [], BatchOpt);

SEE ALSO io.SaverFactory, io.savers.BaseSaver, core.MibLabels.save, core.MibDataset.save, models.MibModel.save

Constructor Summary
MatlabSaver(options)

MATLABSAVER - Constructor for MatlabSaver class.

Syntax:
saver = io.savers.MatlabSaver(options)
Input Arguments:

  • options - (optional) struct, saver-level options (usually empty; per-save options are passed to save() instead)

Output Arguments:

  • obj - instance of the MatlabSaver class

Method Summary
getSupportedFormats(~)

GETSUPPORTEDFORMATS - Return format strings handled by MatlabSaver.

Syntax:
formats = obj.getSupportedFormats()
Input Arguments:

(none)

Output Arguments:

  • formats - cell array of format strings for MATLAB-based output

save(data, metadata, filename, options)

SAVE - Serialise data to one of the MIB MATLAB-native formats.

Syntax:
fnOut = obj.save(data, metadata, filename, options)

The active format is selected by options.Format:

  • 'Matlab format (``*.mask)’`` → saveMask()

  • 'Matlab format (``*.model)’`` → saveModel3D()

  • 'Matlab format 2D sequence (``*.model)’`` → saveModel2DSeq()

  • 'Matlab format for MIB ver. 1 (``*.mat)’`` → saveModelV1()

  • 'Matlab categorical format (``*.mibCat)’`` → saveModelCat()

Input Arguments:

  • data - [H, W, D, C, T] label/mask array

  • metadata - struct with image metadata (see class-level docs)

  • filename - full output path for the serialized file

  • options - struct with format selection and save options

Output Arguments:

  • fnOut - [char] or [cell] path(s) of saved file(s), [] on failure

See Also - class-level documentation for detailed parameter descriptions.

saveStream(provider, metadata, filename, options)

SAVESTREAM - Memory-bounded save from a SliceProvider.

Streams the native .model (3-D) format slice-by-slice via a writable matfile (the label volume is grown on disk, never held whole). All other Matlab formats fall back to the gather-based default (bounded by the selected pyramid level).

See io.savers.BaseSaver.saveStream.

Example - stream a BigData model level to a native .model file:

labels   = mibModel.I{mibModel.getActiveId()}.labels;   % MibBigDataLabels
numZ     = labels.modelLevelSizes(1,3);
zScale   = labels.modelScaleFactors(1,3);
provider = io.savers.MibImageSliceProvider(labels,'labels',1,[],numZ,1,zScale);
saver    = io.savers.MatlabSaver(struct());
meta.materialNames = labels.materialNames; meta.materialColors = labels.materialColors;
meta.modelType = labels.maxMaterials; meta.boundingBox = [0 1 0 1 0 1];
saver.saveStream(provider, meta, 'C:\out\Labels_stack.model', ...
    struct('Format','Matlab format (*.model)','silent',true,'showWaitbar',false));