HDF5VirtualSetupLoader

class io.loaders.HDF5VirtualSetupLoader

Bases: io.loaders.BaseImageLoader

HDF5VIRTUALSETUPLOADER - Virtual-mode setup loader for HDF5/XML datasets.

Wraps either HDF5HeaderLoader (XML+H5) or HDF5NoHeaderLoader (bare H5) and adapts them for virtual stacking mode: loadMetadata delegates entirely to the inner loader (XML parsing, pixel-size extraction, dataset selection dialog, etc.) loadImages does NOT read pixel data; instead returns the H5 file path(s) as a cell array and stores the Virtual struct in imginfo{“Virtual”} so that MibVirtualImage.initialize can wire it up.

The objectType field is normalised to 'matlab.hdf5' for all plain HDF5 variants so that MibVirtualImage.getDataVirt dispatches correctly to io.loaders.HDF5VirtualLoader.

Relationship to HDF5VirtualLoader

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.HDF5VirtualSetupLoader(options, true);  % XML+H5
loader = io.loaders.HDF5VirtualSetupLoader(options, false); % bare H5
[imginfo, files] = loader.loadMetadata({'stack.xml'}, options);
[img, imginfo] = loader.loadImages(files, imginfo, options);
% img is {'C:\data\stack.h5'} and imginfo{"Virtual"} holds the struct
Constructor Summary
HDF5VirtualSetupLoader(options, hasHeader)

HDF5VIRTUALSETUPLOADER - Create a virtual-mode HDF5/XML setup loader.

Syntax:
obj = HDF5VirtualSetupLoader()
obj = HDF5VirtualSetupLoader(options)
obj = HDF5VirtualSetupLoader(options, hasHeader)
Input Arguments:

  • options - (optional) [struct] options passed to the inner loader

  • hasHeader - (optional) [logical] true = XML+H5 (HDF5HeaderLoader), false = bare H5 (HDF5NoHeaderLoader); default: true

Output Arguments:

  • obj - [HDF5VirtualSetupLoader] new loader instance

Property Summary
innerLoader
Method Summary
loadImages(files, imginfo, options)

LOADIMAGES - Virtual-mode image setup - does NOT load pixel data.

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

Returns the H5 file path(s) as a cell array (consumed by MibVirtualImage.initialize as obj.data{}) and populates imginfo{“Virtual”} with the struct fields required by MibVirtualImage.

Input Arguments:

  • files - [struct array] per-file metadata from loadMetadata

  • imginfo - [dictionary] image metadata from loadMetadata

  • options - (optional) [struct] unused in virtual mode

Output Arguments:

  • img - [nFiles x 1 cell] cell array of H5 file paths

  • imginfo - [dictionary] updated dictionary; imginfo{"Virtual"} is added with fields:

    • .objectType - [cell] normalised type string per file ('matlab.hdf5' or 'bdv.hdf5')

    • .seriesName - [cell] HDF5 internal dataset path per file

    • .slicesPerFile - [numeric] z-slice count per file

    • .filenames - [cell] H5 file paths

    • .transMatrix - [cell] per-file axis permutation from SelectHDFSeries; [] when not set

    • .readerId - [totalZ x 1 numeric] maps each slice index to its source file index

loadMetadata(filenames, options)

LOADMETADATA - Delegate metadata loading to the inner loader unchanged.

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

For XML+H5, parses the XML header and resolves the H5 dataset path and pixel sizes. For bare H5, runs the dataset-selection dialog and reads dimensions.

Input Arguments:

  • filenames - [cell] cell array of file paths to load

  • options - [struct] loader options

Output Arguments:

  • imginfo - [dictionary] image metadata dictionary

  • files - [struct array] per-file metadata; each element has fields:

    • .filename - [char] path to the actual H5 file

    • .seriesName - [char] HDF5 internal dataset path

    • .objecttype - [char] 'matlab.hdf5', 'bdv.hdf5', or 'hdf5image'

    • .noLayers - [numeric] number of z-slices in this file