Metadata-Version: 2.4
Name: atlas-cci-align
Version: 1.3.6
Summary: Code to open, stitch and z-align roughly and finely SEM images from an ATLAS project
Author-email: Rafael Camacho <rafael.camacho@gu.se>, Simon Leclerc <simon.leclerc@gu.se>
License: MIT License
        
        Copyright (c) 2025 Centre for Cellular Imaging
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.1.0
Requires-Dist: zarr>=3.0.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: xmltodict>=1.0.0
Requires-Dist: matplotlib>=3.0.0
Requires-Dist: shapely
Requires-Dist: pylibCZIrw>=6.1.0
Requires-Dist: czitools
Requires-Dist: scipy
Requires-Dist: scikit-image==0.25.2
Requires-Dist: tifffile
Requires-Dist: python-dateutil
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: webknossos==4.3.2; extra == "test"
Dynamic: license-file

# atlas-cci-align

Utilities for processing SEM image data exported from ATLAS/FIBICS projects.

The package currently focuses on turning an ATLAS project into stitched 2D
planes, then roughly aligning those planes into a 3D stack. It provides helpers
to:

- read ATLAS mosaic metadata (`.mif`) and per-tile TIFF metadata;
- reconstruct one stitched 2D image per acquisition plane;
- estimate rough pairwise z-alignment between stitched planes;
- apply the cumulative alignment into a Zarr array;
- export the aligned Zarr stack back to a CZI file.

The stitching code uses tile positions, scan rotation, acquisition order, image
size, and pixel size from the ATLAS/FIBICS metadata. ATLAS records when tile
acquisition is finished, so dynamic/incremental processing should be possible in
principle.

## Status

This is early packaging work. The rough stitching and z-alignment utilities are
being moved from notebooks/scripts into an installable package.

## Install

```bash
pip install atlas-cci-align
```

The distribution name is `atlas-cci-align`, while the Python package is imported
as:

```python
import atlas
```

## Minimal Workflow

At a high level, the intended workflow is:

1. Parse an ATLAS mosaic project and build a tile dataframe.
2. Stitch tiles into one 2D plane.
3. Repeat for the planes in the project.
4. Run rough z-alignment across the stitched planes.
5. Save the aligned stack as Zarr.
6. Optionally export the Zarr stack as CZI.

The public API is still being shaped, so consult the modules directly for now:

- `atlas.stitching`
- `atlas.alignment`
- `atlas.io`
- `atlas.image_analysis`

## Stage-only stitching

For metadata-based placement without cross-correlation or valid-area cropping:

```python
from atlas.io import get_metadata_for_stitched_tif
from atlas.stitching import stage_stitching, save_stitched_image

image, tiles, transforms = stage_stitching(mif_file)
save_stitched_image(
    output_tif_path,
    image,
    get_metadata_for_stitched_tif(mif_file),
    compression="deflate",
)
```

This retains full tiles and zero-filled gaps, using stage positions corrected
for scan rotation. Later tiles in acquisition order overwrite earlier tiles
in overlaps. Deflate compression is lossless. The existing
`stitch_ATLAS_tiles` workflow and default uncompressed saving are unchanged.

Use `ATLAS-stage-import.ipynb` to process a series. It writes
`stage_stitched_S_<number>.tiff`, `stage_stitching_S_<number>.csv`, and
`stage_stitched_transforms_S_<number>.json` next to the section folders,
skipping TIFFs that already exist. The CSV records tile metadata and nominal
placement; the JSON records zero registration corrections. The notebook
defaults to no added buffer, matching the function; raw import uses 1 µm
to allow for registration shifts.
Local examples and comparison results under `private-data/` are Git-ignored.

## Transfer an aligned WEBKNOSSOS region

`transfer_wk_annotation_region.py` downloads the user bounding box from an
annotation on the fine-aligned dataset, then optionally uploads the image data
using a different organization's token. Configure the inputs at the top of the
script. The default test magnification is `32-32-8`; `DO_UPLOAD = False` downloads
only. Tokens can be entered at the top or supplied as `WK_SOURCE_TOKEN` and
`WK_TARGET_TOKEN` environment variables. The destination organization is taken
from the target token; an optional expected organization ID can be specified.
The uploaded name defaults to `<source dataset name>_mag<MAG>`;
set `TARGET_DATASET_NAME` to override it.

The script lists bounding boxes and requires an index when there are several.
It selects image/color layers by default, preserves voxel size and source
coordinates, and stores the subset as compressed Zarr v3 under `private-data/`.
Only the requested magnification is downloaded. Coarse voxels can extend to
the next magnification-aligned boundary. No full-resolution data or annotation
contents are transferred.

Completed downloads are recorded locally and reused for upload retries. A
partial download or a changed selection requires a new output directory.
For server-side display transformations, use a materialized aligned dataset
before transferring the selected region.

The SDK and compatible IPython/Pydantic versions are included in
`environment.yml`. Run with:

```bash
conda activate atlas-env
python transfer_wk_annotation_region.py
```
