File Format Questions + General 4.1 Planning

[evamaxfield]

• pyramidal ome-tiff (the same file as the czi just exported as ome tiff)
• pyramidal czi
• RGB pyramidal ome-tiff (the same file as the czi just exported as ome tiff)
• RGB pyramidal czi
• RGB ome-tiff

[evamaxfield]

• Add get a new variable scene shape LIF (thats small)

See #174 for more info.

This should be like scene 1 has shape (1, 2, 3, 4, 5) and scene 2 has shape (2, 3, 4, 5, 6)

[evamaxfield]

Hey @sebi06 hoping I can pick your thoughts / knowledge of CZI files.

Is it possible to have a multi-scene pyramid CZI file? And if so what dimensions names are attached?

My mental model of a pyramid file was that each pyramid level basically acted as a different scene but that may be incorrect.

[evamaxfield]

Can bfconvert the existing RGB CZI from aicspylibczi test resources

[zeissmicroscopy]

Hi @JacksonMaxfield

I know that the scene concept is not really "super-easy" .... :-)

• inside a CZI a scene basically is a TileRegion (any shape is possible) --> this is what we call a scene
• Example, one acquired a 10x10 Tileregion in well A1 and and a 1x1 TileRegion (aka a single position) inside well A2
• this would yield in one CZI file with two distinct scenes S=0,1
• such scenes can be obviously split later on demand

The pyramid concept is something else for use. Let's focus on the 1st scene (S=0) from the example above:

• the 10x10 region might be quite large and ZEN automatically generated pyramid levels with lower resolution (number depends on the size of the image)
• those pyramid levels belong to the scene S=0

Sidenote: When opening a CZI via BioFormats, BF (because of the limitations of OME-TIFF) somewhat "interprets" the pyramid levels of a individual scene as "BF Series"

Regarding the bfconvert question, I am not sure. But BF can read RGB CZIs with scenes for sure. But usually it gives you a 3CH image afterwards. So I would assume, yes this works.

What type of images with which dimensions do you need? I can get you basically everything with my "simulated microscope" or dig a bit insider our image storage. I am happy to help here.

Feel free to contact me or even ask for a call, if you need info about the CZI (sebastian.rhode@zeiss.com)

[sbesson]

My mental model of a pyramid file was that each pyramid level basically acted as a different scene but that may be incorrect.

Seconding @zeissmicroscopy's #175 (comment), I think the concept of scenes/positions should be kept orthogonal to the concept of resolutions/pyramidal levels.

Using another public example (and another file format) from the Whole Slide Imaging domain, this public Leica SCN file from the OpenSlide project contains mutiple whole slide images acquired at separate positions where each position is itself a pyramid.

Sidenote: When opening a CZI via BioFormats, BF (because of the limitations of OME-TIFF) somewhat "interprets" the pyramid levels of a individual scene as "BF Series"

I think this will happen when the Bio-Formats API is set to flatten the resolutions. This was introduced during the early work on the multi-resolution and is still the default API mostly because changing it requires a breaking version increment. Calling setFlattenedResolutions(false) should allow the reader to do the right thing i.e. map each scene as a Bio-Formats series and each pyramidal level as a resolution.

Is it possible to have a multi-scene pyramid CZI file? And if so what dimensions names are attached?

I have been quickly browsing through the public data available in IDR as several lightsheet studies have been submitted as Zeiss CZI files e.g. idr0038 or idr0077. However it looks like none of these are are both multi-position and pyramidal CZI files.

@zeissmicroscopy can I use the occasion to clarify a scenario in the use case of lightsheet data? In the example of https://idr.openmicroscopy.org/webclient/?show=image-9836847, the CZI file contains acquisitions at two different orientations of the sample. So these images are related to each other via a 3D transformation which includes a rotation. Are these also be included in the scenes in the CZI vocabulary or is this another concept?

[evamaxfield]

Thanks for the replies!

I think the concept of scenes/positions should be kept orthogonal to the concept of resolutions/pyramidal levels.

After this discussion, I totally agree. Now it will just be about how to expose these to the readers and writers of aicsimageio.... We have already planned to talk about it in our next dev meeting 😂 My immediate thought would be that we mirror the planned 4.0 API and make level stateful to the image container, i.e.:

img.levels  # returns tuple of level ids specific to active scene
img.set_level("2x")  # update current level for active scene
img.current_level  # returns current level for active scene

Defaulting to level 0?

img.set_scene("Image:0")
img.levels  # levels for scene 0
img.set_scene("Image:1")
img.levels  # levels for scene 1

Fortunately, considering a proposal like this isn't a breaking change we could simply introduce this function in 4.1 instead of holding off on 4.0 even longer.

Calling setFlattenedResolutions(false) should allow the reader to do the right thing i.e. map each scene as a Bio-Formats series and each pyramidal level as a resolution.

Do you happen to know if this command is available in the CLI bfconvert tool? My Java is a bit rusty...

the CZI file contains acquisitions at two different orientations of the sample. So these images are related to each other via a 3D transformation which includes a rotation.

I will let @zeissmicroscopy answer but my first thought would that that is the "Rotation" dimension that we have encountered in aicspylibczi

[sbesson]

Hi @JacksonMaxfield

Fortunately, considering a proposal like this isn't a breaking change we could simply introduce this function in 4.1 instead of holding off on 4.0 even longer.

The resolution API as you drafted it above largely mirrors the way it is implemented in Bio-Formats - see IPyramidHandler so it makes sense to me.
Do you have a rough idea for the ideal 4.0.0 timeline?

Do you happen to know if this command is available in the CLI bfconvert tool? My Java is a bit rusty...

Yes bfconvert -noflat should ensure the resolution levels are not flattened during the conversion.

[evamaxfield]

The resolution API as you drafted it above largely mirrors the way it is implemented in Bio-Formats - see IPyramidHandler so it makes sense to me.

Well that is wonderful to see. Will work with @AllenCellModeling/aicsimageio-core-devs to see if we need to do anything more than that (with Reader changes accordingly).

Yes bfconvert -noflat should ensure the resolution levels are not flattened during the conversion.

Thank you so much! Will give this a quick go over the weekend just to get a feel for the data.

Do you have a rough idea for the ideal 4.0.0 timeline?

Oof. Well, I was originally planning and still aiming for the end of this month, ~Feb 2 would be ideal imo but likely looking like mid Feb. I really don't know as all of this is in my free time since I no longer work at AICS 😅

A long and probably too-much-info version full rundown of what's left on the todo list:

• CziReader (requires aicspylibczi==3.0.0, @heeler is there an update on that?) -- expect about a week of time to implement
• LifReader (hoping to use readlif==0.4.0 to allow for mosaic LIFs, @nimne do you have a schedule for release?) -- expect about a week of time to implement, could also push reading mosaic LIFs to 4.1
• ZarrReader / OmeZarrReader -- "easy" considering da.from_zarr and ome-zarr lib already exist, planned for dev next week
• ArrayLikeReader -- easy, likely done over this upcoming weekend
• Finalizing Writers module -- expect about a week to implement, planned for dev next week
• Admin cleanup and final branch merging to main

Cutting dev / beta releases:

• dev_release0 planned as soon as: feature/add-aicsimage-obj #185 is merged, needs a patch to numcodecs. This release will include only functionality for DefaultReader (imageio), TiffReader, OmeTiffReader, and the AICSImage object.
• dev_release1 planned for after ArrayLikeReader and Writers get added.
• dev_release2 planned for after ZarrReader + OmeZarrReader get added.
• dev_release3 planned for after CziReader + LifReader get added.
• 4.0.0 planned for after above.

This is also just a call to anyone reading this issue that if you want to see aicsimageio==4.0.0 faster, any help on the above list would be greatly appreciated. The active branch is feature/update-to-4.0-api 🙏 .

[nimne]

I'll push a 0.4.0 of readlif this weekend (next day or two) - finishing up a few big projects today!

[sebi06]

Hi all,

to my knowledge we use the following inside our CZI format:

Information CZI Dimension Characters:
    
- '0': 'Sample'  # e.g. RGBA
- 'X': 'Width'
- 'Y': 'Height'
- 'C': 'Channel'
- 'Z': 'Slice'
- 'T': 'Time'
- 'R': 'Rotation'
- 'S': 'Scene' # contiguous regions of interest in a mosaic image (TileRegion)
- 'I': 'Illumination' # direction
- 'B': 'Block' # acquisition block form Multiblock experimente´s
- 'M': 'Mosaic' # index of single tiles from a TileRegion
- 'H': 'Phase' # e.g. Airy detector fibers
- 'V': 'View' # e.g. for SPIM

And this is orthogonal with the actual pyramid levels in case of larger Tileregions. I am just collecting some test CZI image. Would it be OK to share them with you via Dropbox?

[evamaxfield]

I am just collecting some test CZI image. Would it be OK to share them with you via Dropbox?

Totally fine and would be much appreciated!

[nimne]

@JacksonMaxfield reaflif 0.4.0 with mosaic support is up on pypi! As far as I can tell, it works as expected. There are no image stitching utilities, but data access works.

[evamaxfield]

Thanks @nimne! I will get started on LifReader as soon as possible. I think because we at this point have (or plan to support) multiple readers that can return mosaic images, I may just write a utility function to stitch tiles together in this repo / pull it from aicspylibczi so no worries there!

Thanks again. Really appreciate the work you put in 🙂