Zarr3VirtualSetupLoader

class io.loaders.Zarr3VirtualSetupLoader

Bases: io.loaders.BaseImageLoader

ZARR3VIRTUALSETUPLOADER - Setup loader for OME-Zarr v3 datasets - handles all dataset modes.

This loader runs ONCE when the user opens a .zarr3 file and handles all three MIB3 dataset modes:

Standard : loadImages() loads the full selected pyramid level into memory and returns pixel data. Virtual : loadImages() returns the zarr root path only + pyramid metadata; pixels are read on demand by Zarr3VirtualLoader. BigData : identical to Virtual mode.

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

Relationship to Zarr3VirtualLoader

Zarr3VirtualSetupLoader - runs ONCE when the user opens a file. Phase : dataset initialisation (MibModel.loadImages) Job : parse OME-Zarr metadata, build pyramid struct, return path. Reads pixels? Yes (Standard mode) / No (Virtual/BigData mode). Lifetime: discarded after open; implements BaseImageLoader. Created by: LoaderFactory (case “OmeZarr”)

Zarr3VirtualLoader - runs on EVERY slice request during the session. Phase : on-demand pixel reading (MibVirtualImage.getDataZarr) Job : read sub-region via ZarrArray.read(bbox). Reads pixels? Yes. Lifetime: cached in MibVirtualImage.loaders{1} for the session. Created by: MibVirtualImage.getDataZarr / getOrCreateLoader

Supported formats:

  • OME-Zarr v3 (zarr.json metadata) - local folders and HTTP/HTTPS URLs

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

  • Nested containers where the image group sits below the selected root (label containers, MoBIE / OpenOrganelle style trees). Local roots are searched recursively; when several image groups are found the user picks one, and options.ZarrGroupPath skips the dialog in batch mode.

  • NOT zarr v2 (.zattrs / .zgroup) - clear error message is shown

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

opts.datasetMode = 'Virtual';
loader = io.loaders.Zarr3VirtualSetupLoader(opts);
[imginfo, files] = loader.loadMetadata({'C:\data\stack.zarr3'}, opts);
[img, imginfo] = loader.loadImages(files, imginfo, opts);
% img = {'C:\data\stack.zarr3'} 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.Zarr3VirtualSetupLoader(opts);
[imginfo, files] = loader.loadMetadata({'C:\data\stack.zarr3'}, opts);
[img, imginfo] = loader.loadImages(files, imginfo, opts);
% img{1} is a [y,x,z,c,t] uint16 array
Constructor Summary
Zarr3VirtualSetupLoader(options)

ZARR3VIRTUALSETUPLOADER - Create a setup loader for OME-Zarr v3 datasets.

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

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

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

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

Output Arguments:

  • obj - [Zarr3VirtualSetupLoader] new loader instance

Method Summary
loadImages(files, imginfo, options)

LOADIMAGES - Mode-dependent image setup - Standard loads pixels, Virtual returns path.

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

Example - Virtual mode:

opts.datasetMode = 'Virtual';
loader = io.loaders.Zarr3VirtualSetupLoader(opts);
[info, f] = loader.loadMetadata({'C:\data\vol.zarr3'}, opts);
[img, info] = loader.loadImages(f, info, opts);
% img = {'C:\data\vol.zarr3'}, info{"Pyramid"}.levelNames = {'0','1',...}
loadMetadata(filenames, options)

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

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

Reads zarr.json via ZarrGroup / ZarrNode (works for local paths and HTTP/HTTPS URLs). Extracts pyramid levels, axis order, shapes, chunk/shard sizes, and pixel sizes from the OME-Zarr multiscales attribute. Falls back to single-level 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

Example - load metadata and print dimensions:

loader = io.loaders.Zarr3VirtualSetupLoader();
[info, files] = loader.loadMetadata({'C:\data\vol.zarr3'}, struct());
fprintf('Height=%d Width=%d Depth=%d\n', info{"Height"}, info{"Width"}, info{"Depth"});