image_name parameter in OmeTiffWriter should be clearly accessible with BioImage

[TimMonko]

Feature Description

One very useful feature of bioio is that multi-scene formats allow easy access to each scene. When a multi-scene format (such as .czi) is converted to ome_metadata, the scene information is stored in name of ome_metadata.images, then this name is equivalent to the scene name for use with the various .scene related functions.

It would be useful if the image_name parameter was easily accessible when using BioImage (or OmeTiffReader). Currently, the OmeTiffWriter.save(image_name=) is only accessible when reading back the image via

img = BioImage(uri=...)
img.ome_metadata.images[0].name

But I would expect it to be under img.scenes and consistent with reading other multi-scene formats

czi example:

img_def = BioImage(r'.\\_tests\resources\test_czis\3T-4C-3Z-2pos.czi')

print(f'plugin: {img_def._plugin}')
print(f'scene: {img_def.scenes}')
print(f'name: {img_def.ome_metadata.images[0].name}')
print(img_def.ome_metadata.images)

outputs:

plugin: PluginEntry(entrypoint=EntryPoint(name='bioio-czi', value='bioio_czi', group='bioio.readers'), metadata=<class 'bioio_czi.reader_metadata.ReaderMetadata'>, timestamp=1713553846.0845451)
scene: ('P5', 'P1')
name: P5
[Image(
   id='Image:0',
   name='P5',
   acquisition_date='2024-09-03T15:48:43.466831+00:00',
.....

but saving with OmeTiffWriter does not return the image_name in a useful way

from bioio.writers import OmeTiffWriter

img_array = np.array([np.random.rand(10, 10), np.random.rand(10, 10), np.random.rand(10, 10), np.random.rand(10, 10)])

OmeTiffWriter.save(data=img_array, uri=r'.\\_tests\resources\test_czis\test.ome.tiff', dim_order='CYX', image_name='T5', channel_names=['C1', 'C2', 'C3', 'C4'])

img_ome = BioImage(r'.\\_tests\resources\test_czis\test.ome.tiff')
print(img_ome._plugin)
print(f'scenes: {img_ome.scenes}')
print(f'ome name: {img_ome.ome_metadata.images[0].name}')
print(f'channels: {img_ome.channel_names}')
print(img_ome.ome_metadata.images)

outputs:

PluginEntry(entrypoint=EntryPoint(name='bioio-ome-tiff', value='bioio_ome_tiff', group='bioio.readers'), metadata=<class 'bioio_ome_tiff.reader_metadata.ReaderMetadata'>, timestamp=1713207524.2728326)
scenes: ('Image:0',)
ome name: T5
channels: ['C1', 'C2', 'C3', 'C4']
[Image(
   id='Image:0',
   name='T5',
   pixels={'channels': [{'annotation_refs': [], 'id': 'Channel:0:0', 'name': 'C1', 'samples_per_pixel': 1, 'color': Color('white', rgb=(255, 255, 255))}, {'annotation_refs': [], 'id': 'Channel:0:1', 'name': 'C2', 'samples_per_pixel': 1, 'color': Color('white', rgb=(255, 255, 255))}, {'annotation_refs': [], 'id': 'Channel:0:2', 'name': 'C3', 'samples_per_pixel': 1, 'color': Color('white', rgb=(255, 255, 255))}, {'annotation_refs': [], 'id': 'Channel:0:3', 'name': 'C4', 'samples_per_pixel': 1, 'color': Color('white', rgb=(255, 255, 255))}], 'bin_data_blocks': [], 'tiff_data_blocks': [{'plane_count': 4}], 'planes': [], 'id': 'Pixels:0:0', 'dimension_order': <Pixels_DimensionOrder.XYCZT: 'XYCZT'>, 'type': <PixelType.DOUBLE: 'double'>, 'size_x': 10, 'size_y': 10, 'size_z': 1, 'size_c': 4, 'size_t': 1},
)]

Use Case

1. Passing scene info down through saved files is useful in many cases. It is often useful to split multi-scene files into individual scene image files for processing, labeling, etc. But this would also be useful in passing this info down into multi-scene ome tiffs
2. Image filenames could be easily blinded to manual review, whilst image_name could be a useful place to save the actual metadata (filename and/or scene name). Then, image_name would be easily accessible with OmeTiffWriter with image.scenes programmatically (or an alternative like image.name)

Solution

It might be easiest just to create a new attribute for BioImage like .name which returns the image_name. This is likely useful with other formats which may have valuable information in both the 'id' and 'name'.

Alternatives

Use the 'name' from the ome_metadata for determining the 'scene' value when reading ome_tiff images. I would suspect this would be a bold breaking change... Perhaps the 'id' ome_metadata is preferred for ome tiff files, for a reason I don't know.