Quickstart

1. Install

Suite3D is not on PyPI. Install from git:

pip install git+https://github.com/alihaydaroglu/suite3d.git
pip install 'cupy-cuda12x>=13.0,<14.0'

A GPU is used for registration. There is a CPU fallback, but it is much slower.

Pin cupy to the 13.x line.

For the napari viewer, also pip install 'suite3d[viz]'.

2. Get the data

The demo datasets are on figshare: Volumetric 2-photon imaging datasets used to test Suite3D.

Download a dataset and unpack it. --data-root expects:

<data-root>/
    v1/raw/*.tif
    hippocampus/raw/*.tif
    lbm/raw/*.tif
    manifest.json

It also accepts a single dataset folder (.../v1) or its raw/ directory, if you only downloaded one.

3. Run a demo

git clone https://github.com/alihaydaroglu/suite3d.git
cd suite3d/demos/01-v1-tc030
python run_pipeline.py --data-root /path/to/data --out-dir ./results

This writes a job directory at ./results/s3d-demo-v1/, exports the results, and opens a viewer.

--viewer html      # portable offline browser (default)
--viewer napari    # desktop 3D viewer
--viewer none

Stages can be skipped to reuse what is already on disk:

python run_pipeline.py --out-dir ./results \
    --skip-init --skip-register --skip-corrmap --viewer napari

4. What to expect

Registration dominates. Plan for disk, not just time.

Demo 04 reuses demo 03's job directory.

Easy to get wrong

fs is the volume rate, not the plane rate.