HDF5¶

HDF5 write utilities.

io.HDF5.image2hdf5(filename, imageS, options)¶

IMAGE2HDF5 - Save image into hdf5 format.

Syntax:

result = io.HDF5.image2hdf5(filename, imageS)
result = io.HDF5.image2hdf5(filename, imageS, options)

Input Arguments:

• filename - filename for the HDF5 file

• imageS - dataset [height, width, colors, depth] or [height, width, depth]

• options - (optional) struct with additional parameters:

  • .ChunkSize - [y, x, z] matrix of chunk size

  • .Deflate - [numeric] gzip compression level 0-9 (default: 0)

  • .overwrite - 1 = do not check whether file already exists

  • .showWaitbar - 1 = show the progress bar, 0 = hide it

  • .ParentFigure - (optional) handle to the main MIB UIFigure; when provided, the progress bar is shown as a uiprogressdlg attached to that window; when absent or empty, the legacy waitbar is used as a fallback

  • .lutColors - not yet implemented

  • .pixSize - not yet implemented

  • .ImageDescription - cell string with dataset description

  • .DatasetName - cell string or dictionary with metadata

  • .order - (char) axis order string, e.g. 'yxzct' (default) or 'yxczt'

  • .height - height of the full dataset (required for initialisation, i.e. when options.t == 1)

  • .width - width of the full dataset (required for initialisation)

  • .colors - number of colour channels (required for initialisation)

  • .depth - depth of the full dataset (required for initialisation)

  • .time - number of time points (required for initialisation)

  • .x - minimal X coordinate for data to store

  • .y - minimal Y coordinate for data to store

  • .z - minimal Z coordinate for data to store

  • .t - minimal T index for data to store

  • .DatasetType - (char) type of the dataset: 'image', 'model', or 'mask'

  • .DatasetClass - (char) image class of the dataset, e.g. 'uint8', 'uint16'

Output Arguments:

• result - 1 = success, 0 = failure

io.HDF5.saveBigDataViewerFormat(filename, I, options)¶

SAVEBIGDATAVIEWERFORMAT - Save a dataset in Fiji BigDataViewer (BDV) HDF5 format.

Syntax:

result = io.HDF5.saveBigDataViewerFormat(filename, I)
result = io.HDF5.saveBigDataViewerFormat(filename, I, options)

Format description: http://fiji.sc/BigDataViewer#About_the_BigDataViewer_data_format

DATA CONVENTION Input I must be [W, H, C, D, T] - i.e. X/Y already swapped by the caller (HDF5Saver permutes [H,W,D,C,T] → [W,H,C,D,T] before calling). Each colour channel is stored separately under /t{T}/s{C}/{level}/cells as a 3-D dataset [newW, newH, newZ].

NOTES * BDV requires int16 data; uint8 is promoted to uint16 first, then all non-int16 types are reinterpreted via typecast. * Pyramid downsampling uses imresize3 (Image Processing Toolbox R2017a+). * An XML header is NOT written here; call io.HDF5.saveXMLheader with options.Format = ‘bdv.hdf5’ after this function returns.

Input Arguments:

• filename - full path to the output .h5 file

• I - [W, H, C, D, T] image array (X/Y pre-swapped by caller)

• options - (optional) struct with fields:

  • .ChunkSize - [3×L] chunk sizes per pyramid level (or [3×1] replicated to all levels); default [64; 64; 64]

  • .Deflate - compression level 0-9; default 0

  • .SubSampling - [3×L] downsampling factors per level, e.g. [1 2 4; 1 2 4; 1 2 4]; default [1; 1; 1]

  • .ResamplingMethod - 'nearest', 'bicubic', or 'bilinear' (default: 'bicubic')

  • .t - time-point start index for multi-time writing (default: 1)

  • .showWaitbar - [logical] (default: true)

  • .ParentFigure - handle to the main MIB UIFigure (for uiprogressdlg)

  • .ImageDescription - (char) BoundingBox metadata string

  • .lutColors - [C×3] LUT colours (0-1) per channel

Output Arguments:

• result - 1 = success, 0 = failure

Example 1 - minimal, single resolution level:

opts.SubSampling = [1;1;1];
opts.ChunkSize   = [64;64;64];
opts.Deflate     = 0;
opts.showWaitbar = false;
opts.t           = 1;
dataBDV = permute(data_HWDCT, [2 1 4 3 5]);   % [H,W,D,C,T]→[W,H,C,D,T]
io.HDF5.saveBigDataViewerFormat('out.h5', dataBDV, opts);
io.HDF5.saveXMLheader('out.h5', opts);         % writes out.xml

Example 2 - three-level pyramid:

opts.SubSampling = [1 2 4; 1 2 4; 1 2 4];     % [x;y;z] per level
opts.ChunkSize   = [64 64 64; 64 64 64; 64 64 64]';  % [3 x 3]

See also

io.HDF5.saveXMLheader, io.savers.HDF5Saver

io.HDF5.saveXMLheader(filename, options)¶

SAVEXMLHEADER - Save XML header for the HDF5 formats (for example, Fiji Big Data Viewer).

Syntax:

result = io.HDF5.saveXMLheader(filename, options)

Input Arguments:

• filename - name of the file: myfile.xml

• options - a structure with parameters:

  • .Format - (char) template for storing data; 'bdv.hdf5' | 'ilastik.hdf5' | 'matlab.hdf5'

  • .height - height of the dataset

  • .width - width of the dataset

  • .colors - number of color channels in the dataset

  • .depth - number of z-stacks

  • .time - number of time points

  • .pixSize - struct with pixel size fields .x, .y, .z, .units

  • .lutColor - (optional) matrix with color channel definitions [1:colorChannel, R G B] (0-1)

  • .ImageDescription - (optional) string with description of the dataset

  • .DatasetName - (optional) name of the dataset in the H5 file (not used with Big Data Viewer)

  • .ModelMaterialNames - (optional) cell array with names of materials

Output Arguments:

• result - 1 = success, 0 = failure

Example - save XML header for a BigDataViewer HDF5 file:

io.HDF5.saveXMLheader('c:\data\mydataset.xml', options);