MibVirtualImage¶

class core.MibVirtualImage¶

Bases: core.@MibImage.MibImage

MIBVIRTUALIMAGE - Virtual image class for MIB3 - reads slices from disk on demand.

Subclass of core.MibImage that defers image data loading to disk. Data is accessed slice-by-slice from external files (HDF5, BioFormats, Zarr) without pre-loading the entire dataset into memory.

Data storage:

obj.filePaths{} stores file references (not pixel data):

• File-path strings (HDF5 / BioFormats mode)

• loci.formats.Memoizer reader handles (BioFormats mode, when opened)

• Zarr pyramid path string in obj.filePaths{1} (Zarr/pyramid mode)

Dispatch logic in getData():

• When ~isempty(obj.pyramid.levelNames) → calls getDataZarr()

• Otherwise → calls getDataVirt() (BioFormats / HDF5)

Key differences from MIB2:

Property	MIB3	MIB2
Dimension order	[y, x, z, c, t]	[y, x, c, z, t]
YX orientation	3	4
Image data	obj.data{}	obj.img{}
Image class	obj.dataClass	obj.meta('imgClass')

Constructor Summary

MibVirtualImage(data, meta)¶

MIBVIRTUALIMAGE - obj = MibVirtualImage(data, meta).

Syntax:

obj = MibVirtualImage(data, meta)

Constructor - delegates to MibImage then initialises Virtual struct.

Input Arguments:

• data - ignored (virtual images are not pre-loaded); pass [] or omit

• meta - metadata dictionary / struct, passed to MibImage constructor

Property Summary

Virtual¶

{1 x nFiles} cell array of file-path strings (or loci.formats.Memoizer handles in legacy BioFormats mode) used by virtual loader dispatch. Replaces the earlier pattern of storing paths in obj.data{}.

bioFormatsMemoizerMemoDir¶

a structure describing the virtual stack layout:

• .readerId - [1 x depth] index into obj.Virtual.filenames for each slice

• .objectType - {1 x nReaders} cell of reader type strings: 'bioformats', 'matlab.hdf5', 'hdf5_image'

• .seriesName - {1 x nReaders} series name / HDF5 dataset path per reader; for 'bioformats' this is a 1-based numeric series index

• .slicesPerFile - [1 x nReaders] number of z-slices contributed by each file

• .filenames - {1 x nReaders} full file paths

filePaths¶

loaders¶

[char] path to the directory used by the BioFormats Memoizer for memo files. Mirrors MibDataset.bioFormatsMemoizerMemoDir - set from there when a virtual dataset is initialised so that getOrCreateLoader can access it.

Method Summary

closeVirtualDataset()¶

CLOSEVIRTUALDATASET - Close open virtual readers and loader objects to release file handles.

Syntax:

obj.closeVirtualDataset()

Closes any BioFormatsVirtualLoader readers held in obj.loaders, then clears the loaders cache. Also handles the legacy case where BioFormats Memoizer handles were stored directly in obj.data{}.

Input Arguments:

Output Arguments:

% Updates

getData(layerType, orient, colChannel, options)¶

GETDATA - Override of MibImage.getData for virtual (disk-resident) datasets.

Syntax:

dataset = obj.getData(layerType, orient, colChannel, options)

Dispatches to getDataZarr when a pyramid is present, otherwise to getDataVirt (BioFormats / HDF5 virtual stack).

Only the ‘image’ layer is supported in virtual mode; requests for ‘labels’, ‘mask’, ‘selection’ or ‘everything’ return a zero-filled array of the appropriate size.

Input Arguments:

• layerType - char, layer to retrieve - only ‘image’ is functional; ‘labels’, ‘mask’, ‘selection’, ‘everything’ return zeros

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

  • 1 - ZX view: [y,x,z,c,t] → [z,x,y,c,t] (rows = Z, columns = X)

  • 2 - YZ view: [y,x,z,c,t] → [y,z,x,c,t]

  • 3 - YX view: [y,x,z,c,t] (default, no permutation)

• colChannel - [optional, can be []], vector of colour indices; [] means all channels

• options - (optional), struct with optional fields:

  • .y, .x, .z, .t - [min, max] coordinate ranges

  • .level - pyramid level index (for zarr, default 1)

  • .magFactor - magnification factor (for zarr, default 1)

  • .showWaitbar - show / suppress the progress waitbar

Output Arguments:

• dataset - 5D array [y, x, z, c, t] (MIB3 convention)

Usage:

Example 1

dataset = obj.getData([], [], [], struct());% full YX image

Example 2

dataset = obj.getData('image', 3, 2, options);% channel 2, YX view

getDataVirt(type, orient, colChannel, options)¶

GETDATAVIRT - Read a virtual dataset (BioFormats or HDF5) from disk on demand.

Syntax:

dataset = obj.getDataVirt(type, orient, colChannel, options)

Input Arguments:

• type - [char] layer type to retrieve; only 'image' is supported

• orient - (optional) [numeric] orientation of returned dataset:

  • 1 - zx plane: output [z, x, y, c, t] (rows = Z, columns = X)

  • 2 - yz plane: output [y, z, x, c, t]

  • 3 - yx plane: output [y, x, z, c, t] (default)

• colChannel - (optional) [numeric vector] colour channel indices; [] = all channels

• options - (optional) [struct] with optional fields:

  • .y - [numeric] [ymin ymax] pixel range

  • .x - [numeric] [xmin xmax] pixel range

  • .z - [numeric] [zmin zmax] slice range

  • .t - [numeric] [tmin tmax] time-point range

  • .level - [numeric] pyramid level index (default: 1 = full resolution)

  • .showWaitbar - [logical or []] override waitbar display; [] = auto

Output Arguments:

• dataset - [numeric array] 5D data in MIB3 order:

  • [y, x, z, c, t] for orient==3 (default)

  • [z, x, y, c, t] for orient==1 (rows = Z, columns = X)

  • [y, z, x, c, t] for orient==2

Example 1 - read full YX dataset:

dataset = obj.getDataVirt('image');

Example 2 - read channel 2 in YX orientation:

dataset = obj.getDataVirt('image', 3, 2, options);

getDataZarr(type, orient, colChannel, options)¶

GETDATAZARR - Read a subvolume from a Zarr pyramid dataset with optional slicing.

Syntax:

dataset = obj.getDataZarr( type, orient, colChannel, options)

Input Arguments:

• type - type of layer - only ‘image’ is functional in virtual mode

• orient - (optional), orientation of returned dataset; default 3:

  • 1 - ZX: output [z, x, y, c, t] (rows = Z, columns = X)

  • 2 - YZ: output [y, z, x, c, t]

  • 3 - YX: output [y, x, z, c, t] (default)

• colChannel - (optional), vector of 1-based colour channel indices; [] = all channels

• options - (optional), struct with optional fields:

  • .y, .x, .z - [min, max] coordinate ranges (1-based, full resolution)

  • .t - [tmin, tmax] time-point range

  • .magFactor - magnification factor used to select pyramid level (default 1 = full resolution); ignored when pyramidLevel provided

  • .pyramidLevel - explicit pyramid level index (1-based); overrides magFactor

Output Arguments:

• dataset - 5D array [y, x, z, c, t] for orient==3; [z, x, y, c, t] for orient==1 (rows = Z, columns = X); [y, z, x, c, t] for orient==2

Usage:

Example 1

dataset = obj.getDataZarr('image');% full YX image

Example 2

dataset = obj.getDataZarr('image', 3, [1 2], options);% channels 1+2

getOrCreateLoader(fileIdx)¶

GETORCREATELOADER - Return the virtual loader for the given file index, creating it if needed.

Syntax:

loader = obj.getOrCreateLoader(fileIdx)

Loaders are created lazily on first access and cached in obj.loaders{fileIdx}. The loader type is determined by obj.Virtual.objectType{fileIdx}: ‘matlab.hdf5’ / ‘hdf5_image’ io.loaders.HDF5VirtualLoader ‘bioformats’ io.loaders.BioFormatsVirtualLoader ‘zarr3’ io.loaders.Zarr3VirtualLoader ‘zarr2’ io.loaders.Zarr2VirtualLoader

Input Arguments:

• fileIdx - [numeric] 1-based index into obj.filePaths{} / obj.Virtual arrays

Output Arguments:

• loader - loader object (HDF5VirtualLoader or BioFormatsVirtualLoader)

initialize(data, meta)¶

INITIALIZE - Initialize MibVirtualImage with a dummy placeholder or provided file paths.

Syntax:

obj.initialize(data, meta)

Overrides MibImage.initialize for virtual (disk-resident) datasets. Unlike the base class, dimensions are derived from ‘meta’ rather than from the data array, and obj.data{} stores file-path strings rather than pixel arrays.

Input Arguments:

• data - (optional):

  • [] (default) - placeholders are set using assets/images/default.h5

  • cell array of file-path strings - stored directly in obj.data{}

  • numeric array - treated as a standard image (unusual; calls parent)

• meta - (optional), a dictionary with dataset metadata (same fields as MibImage.initialize)

Output Arguments:

(none - modifies obj in place)

Usage:

Example 1

obj.initialize();% blank virtual placeholder

Example 2

obj.initialize({'/data/file.h5'}, meta);% load file paths

insertSlice(img, insertPosition, dim, virtMeta, options)¶

INSERTSLICE - Insert virtual file references into the virtual dataset along the depth dimension.

Syntax:

obj.insertSlice(img, insertPosition, dim, virtMeta, options)

Overrides MibImage.insertSlice for virtual (MibVirtualImage) datasets. Instead of manipulating pixel arrays, this method splices cell arrays of file paths (obj.data) and the Virtual metadata struct (obj.Virtual).

Input Arguments:

• img - cell array of file-path strings to insert (one entry per slice)

• insertPosition - 1-based insertion index; 0 or NaN means append to the end

• dim - ‘depth’ (default); ‘time’ is not supported for virtual datasets

• virtMeta - struct with fields matching obj.Virtual:

  • .filenames, .objectType, .readerId, .seriesName, .slicesPerFile

• options - (optional) struct with fields:

  • .sliceNames - cell array of names for the inserted slices (default {})

  • .sliceSizes - [N×2] double matrix of [height, width] for the inserted slices (default [])

Output Arguments:

none

After the call the following properties are updated: obj.data, obj.Virtual, obj.depth, obj.dim_yxzct, obj.sliceName, obj.sliceSize (when applicable)

Usage:

Example 1

obj.image.insertSlice(newFilePaths, 1, 'depth', meta{'Virtual'});