HDF5VirtualLoader

class io.loaders.HDF5VirtualLoader

Bases: handle

HDF5VIRTUALLOADER - On-demand slice reader for MIB3 HDF5 virtual datasets.

Wraps a single HDF5 file and its internal dataset path. The full axis order is resolved from the HDF5 JSON attribute on the first readRegion call and cached - h5info() is never called more than once per file per session.

Any axis order is supported (e.g. 'yxzct', 'yxczt', 'zyxct', etc.). readRegion always returns data in MIB3 order [y, x, z, c, t].

Unlike the batch loaders in +io/+loaders/ this class does NOT implement BaseImageLoader - it is stateful and designed for repeated sub-region reads rather than single full-dataset loads.

Relationship to HDF5VirtualSetupLoader

These two classes serve different phases of the virtual dataset lifecycle and should not be confused:

HDF5VirtualSetupLoader - runs ONCE when the user opens a file. Phase : dataset initialisation (MibModel.loadImages) Job : parse metadata, build the Virtual struct, return H5 paths. Reads pixels? No. Lifetime: discarded immediately after open; implements BaseImageLoader. Created by: LoaderFactory

HDF5VirtualLoader - runs on EVERY slice request during the session. Phase : on-demand pixel reading (MibVirtualImage.getDataVirt) Job : call h5read for the requested sub-region; cache axis order. Reads pixels? Yes - one h5read call per z-group per getDataVirt call. Lifetime: cached in MibVirtualImage.loaders{} for the session; does NOT implement BaseImageLoader. Created by: MibVirtualImage.getOrCreateLoader (lazily, per file)

Usage example:

loader = io.loaders.HDF5VirtualLoader('/data/stack.h5', '/MIB/images');
block = loader.readRegion([1 512], [1 512], 1, 10, 3, [1 1], 'uint16');
% block is [512, 512, 10, 3, 1] in [y,x,z,c,t] order
Constructor Summary
HDF5VirtualLoader(filename, datasetPath, transMatrix)

HDF5VIRTUALLOADER - Create an on-demand HDF5 slice reader.

Syntax:
obj = HDF5VirtualLoader(filename, datasetPath)
obj = HDF5VirtualLoader(filename, datasetPath, transMatrix)
Input Arguments:

  • filename - [char] full path to the HDF5 file

  • datasetPath - [char] internal HDF5 dataset path

  • transMatrix - (optional) [1 x 5 numeric] permutation from SelectHDFSeries dialog; [] or NaN = not available

Output Arguments:

  • obj - [HDF5VirtualLoader] new loader instance

Property Summary
axisOrder

[1 x 5] permutation from SelectHDFSeries dialog (may be [] or NaN). transMatrix(k) = native HDF5 dimension position for MIB axis k where MIB axes are ordered [y, x, z, c, t]. Passed in from Virtual.transMatrix{fileIdx} by getOrCreateLoader. When non-empty and not NaN, takes priority over axis-tag parsing.

datasetPath

[char] full path to the HDF5 file

filename
toMIB3perm

[char] MATLAB dimension order resolved from transMatrix or the HDF5 JSON/axistags attribute, e.g. ‘yxczt’ means h5read returns [y, x, c, z, t] in native order. Empty ([]) until resolveAxisOrder() is called on the first readRegion.

transMatrix

[char] internal HDF5 dataset path (Virtual.seriesName{fileIdx})

Method Summary
readRegion(Ylim, Xlim, z1In, zCount, nColors, Tlim, dataClass)

READREGION - Read a contiguous z-block from the HDF5 file.

Syntax:
block = obj.readRegion(Ylim, Xlim, z1In, zCount, nColors, Tlim, dataClass)

The axis order is resolved and cached on the first call. Always returns data in MIB3 order [y, x, z, c, t].

Input Arguments:

  • Ylim - [1x2 numeric] pixel row range [ymin ymax] (1-based, inclusive)

  • Xlim - [1x2 numeric] pixel column range [xmin xmax] (1-based, inclusive)

  • z1In - [numeric] first z-slice index within this file (1-based)

  • zCount - [numeric] number of z-slices to read

  • nColors - [numeric] total number of colour channels in the dataset

  • Tlim - [1x2 numeric] time-point range [tmin tmax] (1-based, inclusive)

  • dataClass - [char] output class, e.g. 'uint8' or 'uint16'

Output Arguments:

  • block - [nY x nX x zCount x nColors x nT numeric] array in [y,x,z,c,t] order