Repository navigation
DOC: Unclear how to use Zarr3 ArrayBytesCodec #4159
Description
Describe the issue linked to the documentation
I got really stuck trying to figure out how to use imagecodecs's (relatively) new zarr3-compatible codecs, where I specifically wanted to use the JPEG-XL codec.
After cursorily reading the zarr and imagecodecs documentations a few times, I still got stuck and started backtracking through my code until I finally realised that because imagecodecs.zarr.Jpegxl is an ArrayBytesCodec, it should not be passed in as a compressor, but as a serializer. I think this could be covered better in the documentation and doc-strings of zarr3, and perhaps also in the error messages.
I am not confident enough in my zarr3 knowledge yet to submit a PR myself, but hopefully you can see where I went wrong in this little example:
import numpy as np
import zarr
import imagecodecs.zarr
imagecodecs.zarr.register_codecs()
compressor = imagecodecs.zarr.Jpegxl(level=5)
ds = np.zeros(shape=(64, 256, 256))
z = zarr.create_array(
store=COMPRESSION_TESTS_DIR / "out.zarr",
shape=ds.shape,
dtype=ds.dtype,
chunks=(16, 128, 128),
compressors=compressor,
overwrite=True,
zarr_format=3,
)
z[:] = dsWhich gives:
...
TypeError: Expected a BytesBytesCodec. Got <class 'imagecodecs.zarr.Jpegxl'> instead.
I ran into this: #1943, so clearly this transition was on your mind!
Activity
d-v-b commentedon Jul 20, 2026
quoting myself from the related imagecodecs issue:
In terms of improvements we should make, I think if if we expose a function that talks about "filters", "serializer", "compression", that function should emit error messages that use the same terms. So the error message should probably say "Expected an instance of
BytesBytesCodecfor thecompressorparameter, but got Got <class 'imagecodecs.zarr.Jpegxl'> instead."