Turn overlapping microscope fields into one seamless, globally optimized mosaic using OpenCV registration, optional quality-gated RAFT refinement, and an auditable JSON report.
Important
StitchNet Laboratory is microscopy preprocessing research software. It is not a medical device, does not detect or diagnose cancer, and has not been clinically validated. Reconstruction confidence is engineering evidence—not clinical confidence.
Pairwise SIFT and correlation evidence is solved as a robust stage graph, preventing row-by-row drift. |
RAFT residual proposals are accepted only when they improve overlap photometry. Unsafe checkpoints are refused. |
Coverage, residuals, seam disagreement, fallbacks, warnings, and provenance ship beside the mosaic. |
The hosted demo is a zero-install, read-only tour with a verified public H&E fixture, downloadable mosaic, coverage mask, and complete quality report.
|
 |
| Liquid-glass local workspace | Verified H&E reconstruction |
The static demo does not upload visitor data or pretend to run Python/CUDA in GitHub Pages. Install locally to process your own microscopy tiles.
| Capability | Hosted demo | Local app |
|---|---|---|
| Explore the complete interface | ✅ | ✅ |
| Inspect and download a verified result | ✅ | ✅ |
| Process private PNG/TIFF/JPEG/BMP tiles | — | ✅ |
| Run classical global registration | — | ✅ |
| Run RTX/CUDA learned refinement | — | ✅ |
| Export 8-bit or 16-bit full resolution | Sample | ✅ |
Naive mosaicing chains neighbor transforms. Tiny errors then accumulate, illumination changes become visible blocks, and low-texture overlaps can create duplicated tissue or black holes. StitchNet treats reconstruction as one constrained graph:
- Validate every file, channel layout, dimension, and archive member.
- Measure overlap bands with SIFT, normalized correlation, and nominal priors.
- Arbitrate candidates by confidence; optionally test a gated RAFT residual.
- Optimize every tile position together with robust least squares.
- Balance and blend exposure using gain/bias correction and coverage-aware feathers.
- Release evidence as the mosaic, mask, preview, and machine-readable report.
This design handles grayscale, RGB, RGBA, mixed dimensions, 16-bit TIFF, single-row or single-column scans, and incomplete grids.
| Evaluation | Reproduced result |
|---|---|
| NIST MIST 25-tile phase mosaic | 0.584 px placement p95 · 1.000 coverage · 0 fallbacks |
| Perturbed held-out H&E · hybrid | 0.199 px ground-truth placement p95 |
| Perturbed held-out H&E · learned + gated | 0.156 px ground-truth placement p95 |
| Held-out H&E synthetic-warp evaluation | 20.18% error reduction |
| Deterministic stress suite | 4/4 passed |
| Current automated test suite | 26/26 passed |
Results were produced locally on 18 July 2026. See evaluation conditions, source hashes, constraints, and limitations. The held-out H&E source was not used for optimization; these engineering benchmarks are not clinical validation.
- Python 3.10–3.12
- Node.js 20.19+; Node 22 is recommended
- Git
- Optional NVIDIA CUDA GPU; learned mode was validated on an RTX 4060 Laptop GPU with 8 GB VRAM
git clone https://github.com/muhammadmahadazher/optical-image-aberration-Removel_using_StitchNet.git
cd optical-image-aberration-Removel_using_StitchNet
python -m pip install -e ".[ml]"
python start.pyThat one launch command starts the FastAPI backend, prepares the React frontend, and opens http://127.0.0.1:3000.
CPU-only, developer, and launcher options
# Classical stitching without the optional PyTorch runtime
python -m pip install -e .
# Development and test tools
python -m pip install -e ".[ml,dev]"
# Launcher options
python start.py --no-browser
python start.py --backend-only
python start.py --frontend-onlyThe same commands work on Windows PowerShell, Linux, and macOS. A virtual environment is recommended but not required.
- Drop individual tiles or one safe ZIP into the workspace.
- Confirm overlap, columns, registration mode, blending, and output depth.
- Run the job, inspect warnings and coverage, then download the mosaic and report.
For the most reliable layout inference, name tiles with explicit coordinates:
specimen_r001_c001.tif specimen_r001_c002.tif
specimen_r002_c001.tif specimen_r002_c002.tif
Indexed names such as specimen_0001.png also work when you provide the column count.
# Recommended global classical/hybrid mode
stitchnet data/my_tiles --overlap 0.20 --output mosaic.png
# Add the no-regression learned candidate
stitchnet data/my_tiles --overlap 0.20 --registration learned --output mosaic.png
# Preserve microscopy dynamic range
stitchnet data/my_tiles --overlap 0.20 --bit-depth 16 --output mosaic.tifEvery command writes its quality report beside the mosaic.
backend/ FastAPI jobs, safe uploads, recovery, artifact delivery
frontend/ React + Vite liquid-glass workspace and Pages demo
src/stitchnet/ Registration, global graph solver, blending, I/O, CLI
training/ RTX-friendly deterministic RAFT refinement training
evaluation/ Open-world, synthetic, and stress benchmarks
tests/ Unit, API, archive-security, integration, and ML gates
models/ Quality-gated learned checkpoint
reports/ Machine-readable benchmark and training evidence
legacy/ Original source prototype retained for code audit
| Read next | Purpose |
|---|---|
| Architecture | Components, algorithms, data flow, and engineering decisions |
| Evaluation | Benchmarks, fixtures, hashes, limitations, and reproduction |
| Deployment | Local backend and honest static-demo hosting contract |
| Medical safety | Intended use, exclusions, review, and governance boundaries |
| Data provenance | Dataset sources, terms, checksums, and redistribution notes |
Test, stress, and train the system
# Maintained application surfaces
python -m pytest -q
python -m ruff check src backend tests training evaluation scripts start.py
python scripts/frontend.py test
# Deterministic stress and open-world evaluation
python -m evaluation.stress_suite
python -m evaluation.open_world_mosaic \
--source data/external/openslide/CMU-1-Small-Region.svs
# Reproduce RTX-friendly training
python -m training.train_raft_refiner \
--train-dir data/external/nist_mist/tiles/Small_Phase_Test_Dataset/image-tiles \
--open-world-image data/external/openslide/CMU-1-Small-Region.svsTraining uses deterministic source-level splits, smooth synthetic optical distortions, frozen RAFT encoders, a small trainable update block, mixed precision, and deployment quality gates.
Does StitchNet detect cancer cells?
No. StitchNet reconstructs microscopy mosaics for downstream research. It contains no cancer classifier, diagnostic threshold, sensitivity/specificity claim, or clinical authorization.
Does the learned model replace classical registration?
No. Learned flow is an optional residual proposal. It must improve overlap photometry; classical feature and correlation candidates remain available as fallbacks.
Do uploaded images leave my computer?
Not in the local application. The backend binds to localhost and stores jobs locally. Researchers still remain responsible for authorization, de-identification, retention, access control, and institutional policy.
Can StitchNet preserve 16-bit microscopy TIFF data?
Yes. It supports grayscale and color high-bit-depth input, consistent normalization, 16-bit export, and intensity-independent coverage cropping.
Review the full-resolution overlaps, mosaic, coverage mask, warnings, and fallbacks before downstream analysis. Validate performance for every scanner, objective, stain, preparation protocol, and acquisition pattern. Never interpret registration confidence as biological certainty.
If StitchNet supports your research, cite the software using CITATION.cff. Reproducible issues and focused pull requests are welcome; never include patient data or unsupported clinical claims.
Released under the MIT License. Public fixtures and third-party dependencies keep their own terms—review data provenance before redistribution.
Microscopy stitching · digital pathology · medical imaging · image mosaicing · computer vision · OpenCV · PyTorch · RAFT optical flow · FastAPI · React
Built for careful reconstruction, transparent evidence, and expert review.