Zarr Sink Frame Values

[annehaley]

Resolves #1325. This PR adds frame values to the Zarr sink, which allows a user to specify true values for each index of a frame axis. This can be done with addTile or by setting frameValues directly. Additionally, the user may set a dictionary of frameUnits to describe the units used by each frame axis and/or a list of frameAxes to assert an ordering to the frame axes.

For example:

import large_image_source_zarr
import numpy as np

sink = large_image_source_zarr.new()
sink.frameAxes = ['z', 't', 'm']
sink.frameUnits = dict(z='cm', t='ms', m='mm')
for z, z_value in enumerate([2, 4, 6, 8]):
    for t, t_value in enumerate([10.0, 20.0, 30.0]):
        t_value += 0.01 * z
        for m, m_value in enumerate(['r', 'g', 'b']):
            random_tile = np.random.random((300, 400, 3))
            sink.addTile(
                random_tile,
                0, 0,
                z=z, t=t, m=m,
                z_value=z_value, t_value=t_value, m_value=m_value
            )
print(sink.getMetadata())

This PR also uses the frame values in the slider labels shown in the Frame Selector component. The following video demonstrates the value labels on axis sliders for a randomly-generated image using the new Zarr sink API.
C and Z have uniform values, while T has non-uniform values. (This image was generated with the code in testFrameValues in test/test_sink.py.)
https://github.com/user-attachments/assets/4b41bcd3-8164-46f8-b78b-9d919cecefa0

[manthey]

If you have a multi-band tile and specify a c_value, it doesn't work as expected. That is

ts = large_image.new()
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=0, z=0, z_value=1, c_value='DAPI')
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=1, z=0, z_value=1, c_value='CD4')

fails, but without the c_value succeeds.

And, if this is a 1 band tile, then when I try to print the metadata, it fails:

ts = large_image.new()
ts.addTile(np.zeros((100, 100, 1)), x=0, y=0, c=0, z=0, z_value=1, c_value='DAPI')
ts.addTile(np.zeros((100, 100, 1)), x=0, y=0, c=1, z=0, z_value=1, c_value='CD4')
pprint.pprint(ts.metadata)

[manthey]

Another use case I was expecting to work:

ts = large_image.new()
ts.addTile(np.zeros((100, 100, 1)), x=0, y=0, z=0, z_value=1)
ts.addTile(np.zeros((100, 100, 1)), x=0, y=0, z=1, z_value=3.2)
ts.addTile(np.zeros((100, 100, 1)), x=0, y=0, z=2, z_value=6.4)
ts.addTile(np.zeros((100, 100, 1)), x=0, y=0, z=2, z_value=6.3, c=1)

[annehaley]

The first two snippets you provided have been added as a pytest and fixed in c85ebf0.
The third snippet you provide is a use case that is already not supported by the addTile function. The current implementation of addTile requires that all axes are declared upon the first call, and a user cannot add new axes later. While outside the scope of this PR, this use case is reasonable and should be addressed in another PR. I have created #1674 to track this.

[manthey]

I had another example that had been failing during addTile, but with the latest changes now fails when getting the metadata:

ts = large_image.new()
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=0, z=0, z_value=1, c_value='DAPI')
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=0, z=1, z_value=3.2, c_value='DAPI')
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=0, z=2, z_value=6.3, c_value='DAPI')
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=1, z=2, z_value=6.4, c_value='CD4')
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=1, z=1, z_value=3.1, c_value='CD4')
ts.addTile(np.zeros((100, 100, 3)), x=0, y=0, c=0, z=1, z_value=1.1)
pprint.pprint(ts.metadata)

My guess is that this is due to unpopulated values in some combinations.

[manthey]

Currently, the metadata entries for Value<axis> is in the zarr source code. I think it would be better to move it to the _addMetadataFrameInformation method in the base class so if these values are populated in frames in non-zarr sources, the aggregated values will still be added to the metadata.

[manthey]

Should we cast the values stored in each frame to native python float or int datatypes rather than leave them as numpy data types? As long as the native numpy data types serialize to json, it probably doesn't matter, but for consistency between sources, we may want to do the cast.

[manthey]

I'd like to have issues for two follow ups to this PR:

• Setting values in multiple processes doesn't appear in the final result. That is, I think only the last process to white the zarr has sets values.

• The display precision should probably be limited to some number of significant digits. For instance, in a test example I get
  

[annehaley]

@manthey Since the value precision for the labels is a quick fix, I added that change in e41e125. We can address the multiprocessing case in a follow-up PR as you suggested. I made this issue to track it: #1698.

[manthey]

@manthey Since the value precision for the labels is a quick fix, I added that change in e41e125. We can address the multiprocessing case in a follow-up PR as you suggested. I made this issue to track it: #1698.

Great. When CI passes, merge away.