Package for writing/reading 3d numpy arrays to/from HDF5 files (for Fiji/BigDataViewer/BigStitcher).

bigdataviewer, h5, hdf5, numpy
pip install npy2bdv==1.0.8



A library for writing/reading HDF5/XML datasets of Fiji BigDataViewer/BigStitcher format as numpy arrays.

Python 3.6 License: GPL v3


Run pip install npy2bdv in the command line. Use import npy2bdv in the code.


For a quick start, see examples in the Jupyter notebook.

API documentation.

Supported H5/XML writing options

  • compression methods None, gzip, lzf (None by default).
  • downsampling options:
    • any number of mipmap levels
    • computed via averaging, compatible with BigDataViewer/BigStitcher convention.
  • user-defined block sizes for H5 storage (default 4,256,256)
  • any number of time points, illuminations, channels, tiles, angles.
  • arbitrary affine transformation for each individual view (e.g. translation, rotation, shear).
  • arbitrary voxel calibration for each view, to account for spatial anisotropy.
  • individual views can differ in dimensions, voxel size, voxel units, exposure time, and exposure units.
  • missing views are labeled in XML automatically.
  • support of additional meta-information:
    • camera properties: name, exposureTime, exposureUnits
    • microscope (name and version), user
  • writing virtual stacks of arbitrary size, by plane or sub-stack. Handy when your stack is larger than your RAM.
    • virtual stacks can be written with multiple subsampling levels and compression.

New features

See Recent changes

Writing speed

Writing speeds up to 2300 MB/s can be achieved on a PC with SSD drive. The speed of writing for long time series (>100 stacks) is typically about 700-900 MB/s. This is in the range of full-speed camera acquisition of Hamamatsu Orca Flash4, e.g. 840 MB/s (2048x2048 px at 100 Hz).


This code was inspired by Talley Lambert's code and further input from Adam Glaser, VolkerH, Doug Shepherd and Peter H.

To report issues or bugs please use the issues tool.


If you find this library useful, please cite it. Thanks!