Reading and editing

BdvEditor opens an existing dataset, written by npy2bdv, Fiji, BigStitcher or any other tool using the BigDataViewer HDF5 format. First, a dataset to work with:

import numpy as np
import npy2bdv

rng = np.random.default_rng(0)
writer = npy2bdv.BdvWriter("to_edit.h5", nchannels=2, ntiles=2, subsamp=((1, 1, 1), (2, 4, 4)))
for ch in range(2):
    for tile in range(2):
        writer.append_view(rng.integers(0, 4000, (32, 128, 128), dtype=np.uint16),
                           channel=ch, tile=tile, voxel_size_xyz=(0.5, 0.5, 2), voxel_units='um')
writer.write_xml()
writer.close()

Reading views

Open with mode='r' when you only read, so the files cannot be changed by accident.

editor = npy2bdv.BdvEditor("to_edit.xml", mode='r')
print(editor.ntimes, editor.nchannels, editor.ntiles)     # 1 2 2

stack = editor.read_view(channel=1, tile=0)               # (z, y, x) array
preview = editor.read_view(channel=1, tile=0, ilevel=1)   # downsampled level
plane = editor.read_view(channel=1, tile=0, z=10)         # one plane only, fast

print(editor.get_view_property('voxel_size'))   # (0.5, 0.5, 2.0), in (x, y, z) order
print(editor.get_view_property('view_shape'))   # (128, 128, 32), in (x, y, z) order
editor.finalize()

Either file of the pair can be given. With the XML file, the H5 file it refers to is used, so several XML files can share one H5 file, e.g. different registrations of the same data.

Transformations

Read the transformations of a view, or add new ones. Added transformations go on top of the list, so BigDataViewer applies them last; the XML file is updated immediately.

editor = npy2bdv.BdvEditor("to_edit.xml")
print(editor.read_affine(tile=1))     # the 'calibration' transform written by BdvWriter

shift = np.eye(3, 4)
shift[0, 3] = 112                     # move tile 1 by 112 px in x
for ch in range(2):
    editor.append_affine(shift, name_affine="tile position", channel=ch, tile=1)
print(editor.read_affine(channel=0, tile=1))    # index 0 is the newest
editor.finalize()

Cropping

crop_view() crops a view in place, at all time points. Each axis takes (start, stop) like a Python slice, or None to keep it whole:

editor = npy2bdv.BdvEditor("to_edit.xml")
editor.crop_view(bbox_xyz=((10, -10), None, (0, 16)), channel=0, tile=0)
editor.finalize()                     # writes the new size to the XML file

editor = npy2bdv.BdvEditor("to_edit.xml", mode='r')
print(editor.read_view(channel=0, tile=0).shape)   # (16, 128, 108)
editor.finalize()

Warning

Cropping cannot be undone. finalize keeps the previous XML file as to_edit.xml~1, but the H5 data is changed for good. Only the given resolution level is cropped (default 0).