Zarr2VirtualSetupLoader

class io.loaders.Zarr2VirtualSetupLoader

Bases: io.loaders.BaseImageLoader

ZARR2VIRTUALSETUPLOADER - Setup loader for OME-Zarr v2 datasets - handles all dataset modes.

Metadata is parsed directly from the v2 JSON sidecar files (.zattrs/.zgroup/.zarray, pure MATLAB jsondecode - no engine involved just to discover shape/dtype/pyramid structure), while pixel data is read through io.zarr.Array, so the engine follows io.zarr.Config exactly as it does for v3. The bundled zarrMex reads zarr v2, so python is optional, needed only when the python backend is explicitly selected in Preferences -> Input/output -> Zarr library.

This loader runs ONCE when the user opens a zarr v2 file and handles all four MIB3 loading contexts:

Standard : loadImages() prompts a pyramid level and loads it fully into memory as pixel data. Virtual : loadImages() returns the zarr root path only + pyramid metadata; pixels are read on demand by Zarr2VirtualLoader. BigData : identical to Virtual mode (image reads are pyramid-aware and on-demand either way; BigData additionally gets a disk-backed editable label pyramid, which MIB creates in whichever zarr format the store path asks for. An EXISTING labels array that MIB did not write is displayed read-only, via core.MibBigDataLabelsZarr2). Model : loadImages() loads the full labels array into memory (same full-array contract every MibDataset.loadModel loader uses), and resolves material names/colors from the store’s metadata.

The dataset mode is passed via options.datasetMode (set by LoaderFactory from loaderInfo.mode).

Supported formats:

  • OME-Zarr v2 (.zattrs/.zgroup/.zarray metadata) - local folders and HTTP/HTTPS URLs

  • Single-array zarr v2 (no multiscales metadata) - treated as 1 level

  • Nested containers where the image group sits below the selected root, e.g. the OpenOrganelle / MoBIE layout <name>.zarr/recon-1/em/fibsem-uint8 or an OME-Zarr label container. Local roots are searched recursively; when several image groups are found the user picks one, and options.ZarrGroupPath skips the dialog in batch mode.

Example 1 - Virtual mode (typical usage via MibModel.loadImages):

opts.datasetMode = 'Virtual';
loader = io.loaders.Zarr2VirtualSetupLoader(opts);
[imginfo, files] = loader.loadMetadata({'C:\data\stack.zarr2'}, opts);
[img, imginfo] = loader.loadImages(files, imginfo, opts);
% img = {'C:\data\stack.zarr2'} and imginfo{"Pyramid"} holds the struct

Example 2 - Standard mode (prompts user to select pyramid level, returns pixel data):

opts.datasetMode = 'Standard';
opts.ParentFigure = gcf;
loader = io.loaders.Zarr2VirtualSetupLoader(opts);
[imginfo, files] = loader.loadMetadata({'C:\data\stack.zarr2'}, opts);
[img, imginfo] = loader.loadImages(files, imginfo, opts);
% img{1} is a [y,x,z,c,t] uint16 array
Constructor Summary
Zarr2VirtualSetupLoader(options)

ZARR2VIRTUALSETUPLOADER - Create a setup loader for OME-Zarr v2 datasets.

Syntax:
obj = Zarr2VirtualSetupLoader()
obj = Zarr2VirtualSetupLoader(options)
Input Arguments:

  • options - (optional) [struct] options including:

    • .datasetMode - [char] 'Standard', 'Virtual', 'BigData', or 'Model' (set by LoaderFactory from loaderInfo.mode; default: 'Virtual')

    • .ParentFigure - [handle] parent figure handle for dialogs

Output Arguments:

  • obj - [Zarr2VirtualSetupLoader] new loader instance

Method Summary
loadImages(files, imginfo, options)

LOADIMAGES - Mode-dependent image/model setup for zarr v2 datasets.

Syntax:
[img, imginfo] = obj.loadImages(files, imginfo, options)

Standard mode: prompts the user to select a pyramid level, then loads the full level into memory as a [y,x,z,c,t] array. Model mode: loads the full (level 0) array into memory and resolves material names/colors from the store’s metadata. Virtual / BigData mode: returns the zarr root path and populates imginfo{“Pyramid”} and imginfo{“Virtual”} for on-demand reading.

Input Arguments:

  • files - [struct] from loadMetadata

  • imginfo - [dictionary] from loadMetadata

  • options - [struct] relevant field: .ParentFigure (for dialogs)

Output Arguments:

  • img - Standard/Model mode: [1x1 cell] holding [y,x,z,c,t] numeric array; Virtual/BigData mode: [1x1 cell] holding the zarr root path string

  • imginfo - [dictionary] updated; Virtual mode adds "Pyramid" and "Virtual" keys; Model mode adds "numEntries" and, when found, "modelMaterialNames"/"modelMaterialColors"

loadMetadata(filenames, options)

LOADMETADATA - Parse OME-Zarr v2 metadata from the zarr root.

Syntax:
[imginfo, files] = obj.loadMetadata(filenames, options)

Confirms the selected zarr backend is usable (fails fast, once, at open time - a no-op for the native engine, which has no external dependency), then reads .zattrs/.zarray (works for local paths and HTTP/HTTPS URLs). Extracts pyramid levels, axis order, shapes, chunk sizes, and pixel sizes from the OME-Zarr multiscales attribute. Falls back to a single-level read if no multiscales found.

Input Arguments:

  • filenames - [1x1 cell] path to the zarr root folder or URL

  • options - (optional) [struct] unused; present for interface compatibility

Output Arguments:

  • imginfo - [dictionary] image metadata (Height, Width, Depth, etc.)

  • files - [struct] parsed metadata for use by loadImages

static zarrV2TypeToMatlabClass(zarrType)

ZARRV2TYPETOMATLABCLASS - Convert a zarr v2 numpy typestring to a MATLAB class string.

Syntax:
matlabClass = obj.zarrV2TypeToMatlabClass(zarrType)

Strips the endian marker (</>/|) and maps the numpy single-character-code + byte-width typestring (e.g. 'u1', 'f4') to a MATLAB class, mirroring MIB2’s readZarrMetadata.m.