README.md

multiview-stitcher

multiview-stitcher is an open-source modular toolbox for distributed and tiled stitching of 2-3D image data in python. It is a collection of algorithms (under development) to register and fuse small and large datasets from multi-positioning and multi-view light sheet microscopy, as well as other modalities such as correlative cryo-EM datasets.

For visualization, the associated napari-stitcher provides visualization functionality using the Napari viewer, including a standalone widget.

With a focus on interoperability and integration with existing tools and the ecosystem, the package intends to integrate as tightly as possible with the NGFF specification.

It leverages xarray in combination with spatial-image and multiscale-spatial-image for image handling and dask and dask-image for chunked and distributed image processing.

Quickstart

Notebooks

Check out the example notebooks.

Napari plugin

There's an associated napari plugin: napari-stitcher.

Image data by Arthur Michaut @ Jérôme Gros Lab @ Institut Pasteur.

Code example

These code snippets walk you through a small stitching workflow consisting of

1. Preparing the input image data and metadata (tile positions, spacing, channels)
2. Registering the tiles
3. Stitching / fusing the tiles

1) Prepare data for stitching

import numpy as np
from multiview_stitcher import msi_utils
from multiview_stitcher import spatial_image_utils as si_utils

# input data (can be any numpy compatible array: numpy, dask, cupy, etc.)
tile_arrays = [np.random.randint(0, 100, (2, 10, 100, 100)) for _ in range(3)]

# indicate the tile offsets and spacing
tile_translations = [
    {"z": 2.5, "y": -10, "x": 30},
    {"z": 2.5, "y": 30, "x": 10},
    {"z": 2.5, "y": 30, "x": 50},
]
spacing = {"z": 2, "y": 0.5, "x": 0.5}

channels = ["DAPI", "GFP"]

# build input for stitching
msims = []
for tile_array, tile_translation in zip(tile_arrays, tile_translations):
    sim = si_utils.get_sim_from_array(
        tile_array,
        dims=["c", "z", "y", "x"],
        scale=spacing,
        translation=tile_translation,
        transform_key="stage_metadata",
        c_coords=channels,
    )
    msims.append(msi_utils.get_msim_from_sim(sim, scale_factors=[]))

# plot the tile configuration
# from multiview_stitcher import vis_utils
# fig, ax = vis_utils.plot_positions(msims, transform_key='stage_metadata', use_positional_colors=False)

2) Register the tiles

from dask.diagnostics import ProgressBar
from multiview_stitcher import registration

with ProgressBar():
    params = registration.register(
        msims,
        reg_channel="DAPI",  # channel to use for registration
        transform_key="stage_metadata",
        new_transform_key="translation_registered",
    )

# plot the tile configuration after registration
# vis_utils.plot_positions(msims, transform_key='translation_registered', use_positional_colors=False)

3) Stitch / fuse the tiles

from multiview_stitcher import fusion

fused_sim = fusion.fuse(
    [msi_utils.get_sim_from_msim(msim) for msim in msims],
    transform_key="translation_registered",
)

# get fused array as a dask array
fused_sim.data

# get fused array as a numpy array
fused_sim.data.compute()

---

Installation

You can install multiview-stitcher via pip from PyPI:

pip install multiview-stitcher

or from the source code in this github repository:

pip install git+https://github.com/multiview-stitcher/multiview-stitcher.git

Stitching in the browser

multiview-stitcher can run without installation in your browser.

Try it out

• open JupyterLite in a private browser window
• upload this notebook into the jupyter lab window: notebooks/stitching_in_the_browser.ipynb
• upload files to stitch into a 'data' folder in the jupyter lab window
• follow the notebook

Limitations

• stitching will run with a single thread
• while the code runs locally, your local file system is not directly accessible from within the browser environment

Work in progress

WARNING: THIS IS WORK IN PROGRESS. multiview-stitcher is being developed in the open and has not reached a stable release yet. The API is subject to change.

Previous work

multiview-stitcher improves and replaces MVRegFUS.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Contributing

Contributions are welcome.

License

Distributed under the terms of the BSD-3 license, "multiview-stitcher" is free and open source software.