Pixel types

All views in a file share one pixel type, chosen with the dtype argument of BdvWriter:

dtype	Range	Use for
'uint16' (default)	0 … 65535	Raw data from most scientific cameras.
'uint8'	0 … 255	8-bit data, e.g. many confocal microscopes; half the size of uint16.
'float32'	any real value	Processed data: filtered, deconvolved, normalized, or sums that exceed 65535.

import numpy as np
import npy2bdv

rng = np.random.default_rng(0)
processed = rng.normal(0, 100, (32, 128, 128)).astype(np.float32)   # has negative values

writer = npy2bdv.BdvWriter("processed.h5", dtype='float32', subsamp=((1, 1, 1), (2, 2, 2)))
writer.append_view(processed)
writer.write_xml()
writer.close()

editor = npy2bdv.BdvEditor("processed.xml")
data = editor.read_view()
print(editor.dtype, data.dtype)    # float32 float32
assert np.array_equal(data, processed)
editor.finalize()

Casting

Input arrays are cast to the writer’s dtype with numpy rules. If the cast changes values (out of range, fractions lost, or float32 precision exceeded), a UserWarning is issued, and the data is written anyway. Casts that cannot lose anything, such as uint16 data into a uint16 file, are not checked, so they cost no extra time. Scale data yourself when changing the type:

stack16 = rng.integers(0, 65535, (32, 128, 128), dtype=np.uint16)
stack8 = (stack16 / 65535 * 255).astype(np.uint8)       # rescale to 0..255 first

writer = npy2bdv.BdvWriter("eight_bit.h5", dtype='uint8')
writer.append_view(stack8)        # writer.append_view(stack16) would warn: values > 255
writer.write_xml()
writer.close()

To turn the warning into an error, e.g. in a pipeline that must not alter data:

import warnings

writer = npy2bdv.BdvWriter("strict.h5", dtype='uint8')
with warnings.catch_warnings():
    warnings.simplefilter("error")
    try:
        writer.append_view(stack16)
    except UserWarning as e:
        print("refused:", e)
writer.close()

Downsampled levels are averages cast back to the file’s type, so for integer types they are rounded down.

Fiji compatibility

• uint16 files open in every Fiji version. They are stored as int16, the original BigDataViewer convention, and read back as uint16.

• uint8 and float32 are stored natively, with a dataType attribute that BigDataViewer reads (see File format). This needs BigDataViewer-core 10.4.6 or newer, included in any Fiji updated since 2023 (Help › Update…). Older versions ignore the attribute and read the data as 16-bit integers: float32 values then lose their fractions and negative values are wrong.