opm-processing-v2

Overview

This package is the 2nd generation of the Arizona State University Quantitative Imaging and Inference Lab (qi2lab) oblique plane microscopy (OPM) processing software. Currently, it assumes that data is generated using (1) our 2nd generation OPM control code or (2) the ASI single-objective light sheet Micromanager plugin. The ASI instrument support is experimental and will continue to evolve as we get more data examples from "in the wild" instruments.

The core algorithms can be used for any microscope that acquires data at a skewed angle, including diSPIM, LLSM, or OPM. Please open an issue if you would like help adapting the code to work with your microscope, we are happy to assist.

The goal is provide highly performant data I/O via Tensorstore and image processing (illumination correction, deconvolution, deskewing, downsampling, maximum Z projection, and 3D stitching+fusion) via Numba, CuPy, and cuCIM.

We rely on BaSiCPy to post-hoc estimate illumination profiles and a modified version of gradient consensus Richardson-Lucy deconvolution to perform 3D deconvolution.

Installation

Create a python 3.12 environment,

conda create -n opmprocessing python=3.12

activate the environment,

conda activate opmprocessing

install the repository and register the local CUDA installation. On Linux, this will finish the installation. On Windows, further steps are needed.

pip install "opm-processing-v2 @ git+https://github.com/QI2lab/opm-processing-v2"
setup-cuda
conda deactivate opmprocessing

On Windows, it is currently not possible to install cuCIM via the standard approach. The current work-around involves the following:

1. Ensure you have followed the above steps through setup-cuda.
2. Launch a terminal with administrative privileges.
3. Activate the conda environment, conda activate opmprocessing.
4. Allow symbolic links, git config --global --add core.symlinks true.
5. Install cuCIM, pip install -e "git+https://github.com/rapidsai/cucim.git@v25.04.00#egg=cucim-cu12&subdirectory=python/cucim".

We will update installation instructions if the Windows installation is fixed.

Usage

Activate the conda environment,

conda activate opmprocessing

To deskew raw data,

process "/path/to/qi2lab_acquisition.zarr"

If you get an error, make sure you ran setup-cuda!

The defaults parameters generate different outputs depending if it acquisition is of oblique or projection data.

For oblique data, there are three zarr3 compliant datastores:

1. Full 3D data (/path/to/qi2lab_acquisition_deskewed.zarr) with dimensions tpczyx.
2. Maximum Z projections (/path/to/qi2lab_acquisition_max_z_deskewed.zarr) with dimensions tpcyx.
3. Stage-position fused maximum z projections (/path/to/qi2lab_acquisition_maxz.zarr) with dimensions tcyx.

For projection data, there are two zarr3 compliant datastores:

1. Full 2D projection data (/path/to/qi2lab_acquisition_deconvolved.zarr) with dimensions tpczyx.
2. Stage-position fused 2D projection data (/path/to/qi2lab_acquisition_fused.zarr) with dimensions tcyx.

All datastores are camera offset and gain corrected. The fused datastore uses the provided stage positions, without optimization.

To display deskewed data,

display "/path/to/qi2lab_acquisition.zarr" --to_display full

There are three to_display options that correspond to the three datastores described above,

1. full
2. max-z
3. fused-max-z

To register and fuse optionally deconvolved and desekwed data into an ome-ngff v0.5 datastore,

fuse "/path/to/qi2lab_acquisition.zarr"

The registered, optionally deconvolved, and fused data will be in /path/to/qi2lab_acquisition_fused_deskewed.ome.zarr. This data can be viewed by dragging and dropping the folder into napari and selecting the napari-ome-zarr plugin for viewing.