File format

npy2bdv writes the BigDataViewer HDF5/XML format. You don’t need to know it to use the library, but it helps when inspecting files with other tools, e.g. h5py or HDFView.

The H5 file

dataset.h5
├── s00/                      setup 0
│   ├── resolutions           (nlevels, 3) float: subsampling factors, (x, y, z) order
│   ├── subdivisions          (nlevels, 3) int: block sizes, (x, y, z) order
│   └── @dataType             only for uint8 / float32: "uint8" or "float32"
├── s01/ ...                  one group per setup
├── t00000/                   time point 0
│   ├── s00/                  setup 0
│   │   ├── 0/cells           full resolution, (z, y, x)
│   │   ├── 1/cells           resolution level 1
│   │   └── ...
│   └── s01/ ...
└── t00001/ ...

  • uint16 data is stored as int16, the original BigDataViewer convention, and reinterpreted as unsigned on reading. There is no dataType attribute.

  • Other types are stored natively, and the setup group carries a dataType string attribute, as written by BigDataViewer’s own exporter.

  • Missing views have no group in the H5 file.

Inspecting a file with h5py:

import numpy as np
import h5py
import npy2bdv

writer = npy2bdv.BdvWriter("inspect.h5", subsamp=((1, 1, 1), (2, 2, 2)))
writer.append_view(np.zeros((8, 32, 32), dtype=np.uint16))
writer.write_xml()
writer.close()

with h5py.File("inspect.h5", "r") as f:
    f.visit(print)
    print(f["s00/resolutions"][()])          # [[1. 1. 1.] [2. 2. 2.]]
    print(f["t00000/s00/1/cells"].shape)     # (4, 16, 16)

The XML file

The XML file describes the dataset and points to the H5 file by relative path:

  • <SequenceDescription>: the ImageLoader (format bdv.hdf5 and the H5 file name), ViewSetups with size, voxel size and attribute values of each setup, the attribute names, the Timepoints range and the MissingViews.

  • <ViewRegistrations>: the list of affine transformations of each view, applied bottom to top. npy2bdv always writes a calibration transform, plus the m_affine passed to append_view.

  • <generatedBy>: npy2bdv version, microscope name and version, and user name.

Because the XML file only refers to the H5 file, several XML files can point to the same data, e.g. before and after registration in BigStitcher.