axio-stitching 1.1.1

High-throughput microscopy tile-scan stitching — Zeiss and vendor-neutral — as a desktop app, a CLI, and an AI-agent tool server.

🔬 Overview

AXIO Stitching Studio assembles massive tiled microscopy scans (up to 5,000+ tiles per scene, gigapixel canvases) into contiguous mosaics, with flatfield shading correction and globally-optimized tile registration. One engine drives three surfaces, so every route produces identical results:

Originally built for Zeiss Axio tile scans, the input layer is now vendor-neutral: it auto-detects Zeiss XML, Fiji/ImageJ TileConfiguration.txt, OME-TIFF stage positions, an explicit positions list, or a bare folder of TIFFs with grid-encoded filenames.

🏗️ Architecture

graph TD
    subgraph "Input layer (auto-detected)"
        S1[Zeiss _info.xml / _meta.xml]
        S2[Fiji TileConfiguration.txt]
        S3[OME-TIFF stage positions]
        S4[positions .json]
        S5[tile folder with grid filenames]
    end
    S1 & S2 & S3 & S4 & S5 --> TS[tile_sources - vendor-neutral resolution]
    TS --> E[StitchingEngine]
    E -->|corrects| C[BaSiCPy / Median / Spatial]
    E -->|registers| R[Phase Correlation / SIFT global solve / Stage Coordinates]
    E -->|assembles| O[Feather-blended 16-bit ImageJ TIFF + preview PNG]
    subgraph "Surfaces (one engine, identical results)"
        GUI[PySide6 GUI] --> E
        CLI[axio CLI] --> E
        MCP[MCP server - 17 typed tools] --> E
    end
    MCP -.->|axio agent install| AG[Claude Code / ChatGPT-Codex / Antigravity / Claude Desktop / Gemini CLI]

Supporting subsystems the surfaces share: doctor (environment diagnosis with fixes), estimate (pre-flight canvas/RAM/disk/time sizing with an ok / tight / will_not_fit verdict), jobs (background execution with journalling and orphan detection), and qc (memory-bounded mosaic metrics: empty area, clipping, seam prominence).

✨ Features

• Vendor-neutral inputs — Zeiss XML, Fiji TileConfiguration, OME-TIFF PositionX/Y, explicit positions, or filename-encoded grids, auto-detected with a confidence rating.
• Pre-flight sizing — axio estimate reports canvas dimensions, peak RAM, disk needs, and rough wall-clock before a run, so a gigapixel job never dies 40 minutes in.
• Shading correction — BaSiCPy flatfield, median profile, or spatial background subtraction.
• Global registration — bounded phase correlation or SIFT with a Tikhonov-anchored least-squares solve (a single bad tile pair cannot corrupt the mosaic), or pure stage coordinates.
• Multi-channel & split-channel — channels inside one TIFF (ref_channel) or one file per channel (ref_tag/target_tags); registration is computed once on the reference and applied to every channel, so they stay in register. Both layouts are auto-recognized, including the exact parameters to pass.
• 3D Z-stacks — in-file or filename-tagged slices (auto-recognized); MIP-aligned or reference-slice-aligned volumes, or a cheap MIP-only projection.
• Built-in QC — streamed (memory-bounded) metrics over the finished mosaic plus a preview image, so "exit 0" is never mistaken for "stitched correctly".
• Responsive GUI — the engine runs in a decoupled subprocess; the UI never freezes, and when launched by an AI agent it opens pre-loaded with the agent's dataset, parameters, and finished preview.

📥 Quick Start (No Python Required)

For Windows users, one installer sets up everything — the desktop GUI, the axio CLI, the MCP server, and (optionally, checked by default) the AI-agent integration for every platform detected on your machine:

1. Go to the Releases page.
2. Download and run AXIO_Stitching_Studio_<version>_Setup.exe (per-user install, no admin).
3. Launch AXIO Stitching Studio from the Start menu. Restart any open agent apps once so they pick up the new MCP server.

Windows SmartScreen note: the installer is not code-signed, so on first run Windows may show "Windows protected your PC". Click More info → Run anyway to proceed. To verify what you downloaded, compare the file's SHA-256 (Get-FileHash AXIO_Stitching_Studio_<version>_Setup.exe in PowerShell) against the SHA256SUMS.txt attached to the same release — every release artifact is built from its git tag by the public CI workflow, so its provenance is auditable.

Uninstalling cleanly deregisters the agent integration before removing files. To rebuild the installer from source: python scripts/build_installer.py (needs PyInstaller + Inno Setup 6).

🛠️ Installation (from source)

git clone https://github.com/phwr9jj7-beep/AXIO_Sticthing.git
cd AXIO_Sticthing
conda env create -f environment.yml
conda activate axio-stitch-env

or with plain pip into any Python ≥ 3.10 environment:

pip install -e ".[all]"

🚀 Usage

Desktop GUI

Windows: launcher.bat · Linux/macOS: bash launcher.sh

1. Drag and drop a Zeiss _info.xml metadata file (or use Browse…).
2. Select your Shading Correction and Stitching Algorithm.
3. Configure multi-channel / Z-stack settings if necessary.
4. Click Run Stitching Pipeline — the preview appears in the second tab when done.

Command line

axio doctor                                                      # diagnose the environment first
axio inspect  --source "D:/data/scan_info.xml"                    # scenes, tiles, channels, Z
axio estimate --source "D:/data/scan_info.xml" --out-dir "D:/out" # canvas, peak RAM, disk, time
axio validate --source "D:/data/scan_info.xml" --out-dir "D:/out"
axio stitch   --source "D:/data/scan_info.xml" --out-dir "D:/out" --correction basicpy --algorithm phase
axio qc       "D:/out/stitched_scene0_phase.tif"                  # empty area, clipping, seams
axio outputs  "D:/out"                                            # what a previous run produced

--source accepts any supported input (--xml remains as a legacy alias):

axio estimate is worth the ten seconds it costs: these canvases are gigapixel, and it reports whether the job fits in RAM and on disk before you spend an hour finding out. Every command takes --json for scripting.

🤖 AI agent integration (MCP + Skill)

AXIO ships an MCP server (17 typed tools) and an Agent Skill, and an installer that wires both into the agent platforms on your machine:

axio agent status              # what is detected, installed, or drifted
axio agent install --dry-run   # every file and config key that would change
axio agent install             # every platform detected on this machine
axio agent uninstall           # remove only what AXIO wrote, hash-verified

The tools cover the full loop an agent needs: environment diagnosis, dataset inspection (with automatic recognition of split-channel and Z-stack layouts, down to the exact parameters to pass), pre-flight sizing with an actionable verdict, background stitching with job polling and cooperative cancellation, preview images the agent can actually look at, streamed QC metrics, and a GUI handoff that opens the app pre-loaded with the agent's dataset, parameters, and finished preview.

Shared config files (Codex's config.toml, Antigravity's mcp_config.json, Claude Desktop's claude_desktop_config.json) are edited surgically: one owned key, backed up before the first change, written atomically, and removed on uninstall only while it still hashes to what was written — anything you have since edited is reported as drift and left alone.

See docs/AGENT_INTEGRATION.md for the per-platform paths, the full tool list, and the safety contract.

🧪 Testing

pip install -e ".[dev]"
pytest            # 353 tests: engine, input formats, MCP tools, installer safety, QC, CLI

📖 Wiki & Documentation

• docs/AGENT_INTEGRATION.md — agent platforms, MCP tools, installer safety contract.
• SPEC.md — technical specification and test plan.
• CHANGELOG.md — release history.
• Comprehensive architectural guidelines and workflow protocols in the GitHub Wiki.
• Have a question? Join the Discussions Forum!

📂 Data Availability

Due to the massive size of spatial microscopy scans, the raw datasets (15GB+) are not hosted in this GitHub repository. The raw 2026-04-17 .tif tile scans and corresponding metadata XMLs are permanently hosted and openly accessible at:

[Insert Zenodo / Figshare DOI Link Here]

📚 References & Citations

If you use this software, please consider citing the underlying algorithms that power the pipeline:

1. BaSiCPy Shading Correction: Peng, T., Thorn, K., Schroeder, T. et al. A BaSiC tool for background and shading correction of optical microscopy images. Nat Commun 8, 14836 (2017). https://doi.org/10.1038/ncomms14836
2. SIFT Feature Extraction: Lowe, D.G. Distinctive Image Features from Scale-Invariant Keypoints. International Journal of Computer Vision 60, 91–110 (2004). https://doi.org/10.1023/B:VISI.0000029664.99615.94