Convert mesoSPIM Output to OME-Zarr¶

This task converts mesoSPIM microscopy acquisitions into an OME-Zarr dataset. It supports mesoSPIM .h5, .tiff, and .raw files and generates a full-resolution OME-Zarr with multiscale levels, metadata integration, and channel labeling.

The task can be used in two ways:

On the Fractal platform – as part of a workflow.
Locally – by running the task directly as a Python function or CLI command.

Overview¶

The converter performs the following steps:

Detects all files in zarr_dir matching pattern and extension
Loads mesoSPIM metadata (auto-detected or user-provided)
Assembles channels and tiles depending on your dataset
Writes an OME-Zarr dataset with multiscale pyramids
Assigns channel names and colors based on user-defined JSON file

Parameters¶

Below is a detailed explanation of important parameters.

Pattern¶

In case there are several files with the same suffix (e.g. "h5") in the same analysis directory, you can specify a pattern to select the specific files you want to convert. This pattern needs to be uniquely present in the image file name and its metadata file.

For example:

    Analysis Directory= `C:/path_to_directory/IENFD25-X-X`

    Files with the same suffix: `IENFD25-X-X.h5`, `IENFD25-X-X_restained.h5`, `IENFD25-X-X_lectin.h5`

    Pattern = `restained` if you want to convert only the `IENFD25-X-X_restained.h5` file.

Zarr Name¶

It is recommended to set a name for the new OME-Zarr that will be created. This name will be used as the root of the new Zarr hierarchy. If nothing is provided, the task will use the name of the analysis directory.

For example if nothing is provided:

    Analysis Directory= `C:/path_to_directory/IENFD25-X-X`

    Zarr Name = `IENFD25-X-X.zarr`

Image Name¶

The OME-Zarr is a hierarchical structure. It can contain multiple related images, each with its own metadata. The task is converting the raw data to a single image in the OME-Zarr structure. By default, the task will give it the name raw_image. This parameter allows you to change the name of the image.

For example if nothing is provided:

    Analysis Directory= `C:/path_to_directory/IENFD25-X-X`

    Image Name = `raw_image`

    New OME-Zarr structure:

        IENFD25-X-X.zarr
            - raw_image
                - chunks of the image

Metadata File¶

The task will try to load the metadata based on the name of the source file (e.g. \<source_filename\>_meta.txt). In case the metadata filename has a different name than its source file, you can provide the path to the metadata file using this parameter.

For example:

    Analysis Directory= `C:/path_to_directory/IENFD25-X-X`

    Source File = `C:/path_to_directory/IENFD25-X-X/IENFD25-X-X.h5`

    Expected Metadata File = `C:/path_to_directory/IENFD25-X-X/IENFD25-X-X.h5_meta.txt`

Channel Color Settings¶

This parameter allows you to specify which channel color settings to use to properly view your OME-Zarr image using visualisation tool like napari. A channel color setting is a JSON file that lists the label, color and laser wavelength of the channels. You can provide either provide the path to the JSON file or use the name of a default settings provided with the package:

    Name of a channel settings:        Channel Color File = `default` or `v0` or ...

    Path to a channel settings file:   Channel Color File = `path_to/my_custom_channels.json`

In case you want to view or edit the default channel settings, you can use the following procedure depending on your use case:

If you are running the task locally, you can follow the procedure detailed HERE to view the available channel settings and/or register a new channel settings among the default ones.
If you are using the user interface, refer to its documentation for more information on how to set channel settings.
If running the task on Fractal, you can see the default settings HERE. The name of the settings is in the name of the JSON file. There is no possibility to add a new default setting on Fractal. You can however provide the path to a compatible JSON file saved with your specific channel color definitions. To obtain a JSON file template, you can download it from the package directory.

Chunksize¶

The OME-Zarr stores image data in chunks and at several resolution levels in a so-called pyramid of multi-resolution. The chunksize parameter allows you to set the size of the chunks in pixels. It is recommended to keep the size of the chunks small to avoid memory issues, but not too small to reduce the overhead of storing the data in OME-Zarr. The size should be around 100Mb-1Gb, see this article for more infos. You can compute the size of the chunksize by multiplying their values and by the byte size (for mesoSPIM image data it is typically 2, but it is recommended to use 4 due to the analysis tasks that internally uses a bigger byte size).

Furthermore, the chunksize should be set to a value that is a power of 2, e.g. 64, 128, 512... The chunksize impacts how fast the OME-Zarr can be viewed but also the memory requirements to process it. There are three required numbers to provide, one for each axis in the order Z, Y, and X. The Z axis is often smaller than the other two, so it is recommended to provide a smaller chunksize for it.

Here is a video with a good visual explanation about the OME-Zarr structure such as the pyramid of resolution and the chunks (first 15min): Handling huge imaging data with OME-Zarr

Typical values examples:

128x512x512 => 128*512*512*4 = 136Mb
32x1024x1024 => 32*1024*1024*4 = 136Mb
64x1024x1024 => 64*1024*1024*4 = 268Mb

Num Levels¶

The core idea of the OME-Zarr file format is to store the image data in a pyramid of multi-resolution. This allows to view large images without loading the entire dataset in memory. The pyramid is built progressively, starting from the highest resolution (raw data) and decreasing the resolution by a factor of two or more at each level. Often when viewing the full size image (raw data), we do not need a high level of details for the full image at once (the display cannot even handle so many pixels). Therefore, the pyramid allows us to display the image at different levels of detail, each one corresponding to a different resolution, depending on the zoom into the image. It is similar to the google maps experience.

This parameter allows you to specify explicitly how many pyramid levels to build. By default, the task will try to estimate the optimal number of levels based on the size of the image so that it can be viewed in 3D on a normal computer. If you have a more performant computer, you can decrease the number of levels to have a better 3D experience.

Here is a video with a good visual explanation about the OME-Zarr structure such as the pyramid of resolution and the chunks (first 15min): Handling huge imaging data with OME-Zarr

Channel Color and Naming¶

The task will assign channel names and colors based on a JSON file. There is a default template that is provided to set custom channel settings. If you are running the task locally, you can register your channel color settings as default in the package settings directory using the following procedure.

Here is the procedure to view the current available default settings:

View the available channel settings

In a shell, in the package directory, run:
```
get-channel-keys
```
This will print the available channel keys, e.g. the identifiers for the channel color settings.
View a given channel setting

In a shell, in the package directory, run:
```
get-channel-setting <key>
```
This will print the channel settings for the given channel key.

Here is the procedure to get the template and register your own settings as default in case of recurring use.

Obtain the channel settings template

In a shell, in the package directory, run:
```
copy-channel-template
```
This command copies the JSON template channel_setting_template.json into the package directory.
Edit the template

Open the copied file and modify it to describe your actual imaging channels. It is important to keep the elements and structure of the JSON file intact.
You can provide the path to this file to the task in the parameters to use these channel settings. In case of recurring use, you can register the settings as default in the package settings directory (see below).
Register the channel settings (Optional, only for local run usage)

If you have installed the task package locally you can register your new settings so that you can reuse it without entering again all the settings details. To make your JSON file available to the conversion task as the default setting, run:
```
set-channel-setting my_custom_channels.json
```
or accessible with a specific name:
```
set-channel-setting my_custom_channels.json --setting-name myspecificname
```
This will validate the JSON structure and store the file internally in the package settings directory. You can now access it using the key "default" or the name you provided.

Local Run Command¶

python run_convert_to_omezarr.py

Notes¶

The task currently supports mesoSPIM H5/TIFF/RAW formats.
Multiscale levels follow OME-NGFF conventions.