DOC: Unclear how to use Zarr3 ArrayBytesCodec

[JeppeKlitgaard]

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[:] = ds

Which gives:

...
TypeError: Expected a BytesBytesCodec. Got <class 'imagecodecs.zarr.Jpegxl'> instead.

I ran into this: #1943, so clearly this transition was on your mind!