ATLAS is a companion extension to SlicerMorph, focused on high‑fidelity, scalable generation and transfer of 3D anatomical landmarks and dense correspondences using atlas construction, Statistical Shape Models (SSMs), and PCA‑guided deformable registration.
It streamlines:
- Building an atlas (mean model + dense correspondences) from meshes and sparse landmarks
- Constructing and persisting PCA Statistical Shape Models for variation exploration
- Single and batch automated landmark transfer with robust rigid + PCA‑CPD deformable alignment and optional surface projection
- Continuous optimization of the template (pose + shape) before large batch runs
- Segmentation of the 3D model into parts
If you are new to 3D Slicer or SlicerMorph, begin with SlicerMorph tutorials first. ATLAS assumes you already understand loading models, markups, and basic scene management.
- Installation
- How to Cite
- Updating ATLAS
- Module Descriptions
- Dependencies
- Related / Complementary Extensions
- Tutorials & Learning Resources
- Important Websites
- Funding Acknowledgement
- License
- About
When ATLAS becomes available through the Extension Manager, install it like any other extension. (Currently under active development; interim manual install below.)
- Clone the repository outside your Slicer install:
git clone https://github.com/agporto/ATLAS.git
- Add the cloned top‑level folder to Slicer using the main dropdown menu:
Developer Tools> Extension Wizard→ Select Extension → Select Folder. - Open one of the ATLAS modules (BUILDER, DATABASE, PREDICT, SEGMENTATION) to confirm load.
If you use a cloud Slicer image (e.g., MorphoCloud) you can clone the repo into a writable workspace and add the module path as above. Ensure outbound network allowed for Python dependency install (see below).
If you use ATLAS in publications, please cite (placeholder until formal publication):
Porto, A. (2025). ATLAS: Automated Template-based Landmark Alignment System. GitHub repository. https://github.com/agporto/ATLAS
Also cite SlicerMorph (Rolfe et al. 2021, Methods in Ecology and Evolution) and 3D Slicer (Kikinis et al. 2014) where appropriate. If you use the BUILDER module, please cite DeCA (Rolfe and Maga , 2023). If you use the underlying PCA‑CPD method (biocpd) or tiny3d backend, consult their respective citations.
ATLAS organizes functionality into four scripted modules:
Category: Atlas & Correspondence Generation
Purpose: Align a set of meshes and sparse landmark sets; automatically pick a reference (closest to mean), similarity-align all specimens, generate a mean (atlas) surface, and derive dense correspondences via TPS warp + k‑d tree mapping. Optionally downsamples to produce a sparser, index‑stable subset.
Key Outputs: Timestamped output folder containing aligned meshes (*_align.ply), aligned landmarks (*_align.mrk.json), mean/atlasModel.ply, mean/atlasLMs.mrk.json, and sampled dense set (atlas.mrk.json).
Notable Features: Robust base selection; flexible file stem resolution; index preservation during downsampling.
Category: Statistical Shape Modeling
Purpose: Build a PCA SSM from a folder of dense correspondences; store as a lightweight on‑disk database with manifest; load into scene for interactive mode exploration.
Workflow: Ingest → validate consistent point counts → SVD (variance threshold) → save mean, modes, eigenvalues.
Visualization: Single-PC slider + spinbox; deforms mesh in real time using k‑NN interpolation (weights from inverse distance) between landmark displacements and all vertices.
Outputs: manifest.json, ssm_model.npz, copied template and markup files.
Category: Automated Landmark Transfer
Purpose: Transfer template sparse landmarks to a target mesh (single or batch) via multi-stage alignment: subsampling & FPFH features → RANSAC + ICP rigid alignment → PCA‑guided Coherent Point Drift (CPD) deformable registration → optional surface projection refinement.
Modes:
- Single specimen alignment (tune parameters, inspect intermediate clouds/models)
- Batch processing (reuse tuned parameters; cancellation + progress)
- Template optimization (continuous search in SSM space + RANSAC scoring to refine initial template pose/shape)
Outputs: Predicted landmark .mrk.json files, warped template models (scene), optionally refined projected landmarks.
ATLAS is pure Python + VTK within Slicer, with two external Python packages used at runtime.
On first use of PREDICT, a dialog offers to install:
tiny3d– lightweight point cloud / registration toolkit (Open3D style API)biocpd– PCA‑guided CPD atlas registration
- SlicerMorph – Broader morphology workflows (import, GPA, semi-landmarks, ALPACA).
- Dense Correspondence Analysis (DeCA) – Downstream analysis of dense correspondences.
- ALPACA / MALPACA (in SlicerMorph) – Alternative automated landmarking strategies; compare performance.
Dedicated ATLAS tutorials are forthcoming. In the meantime:
- Use SlicerMorph tutorials for general data prep & landmark management: https://github.com/SlicerMorph/Tutorials
- Explore parameter effects: run PREDICT Single mode on a representative specimen and inspect each intermediate node.
Planned documents (placeholders):
- Quick Start Atlas Build
- Batch Landmark Transfer Best Practices
- Template Optimization Guide
- 3D Slicer: https://www.slicer.org
- SlicerMorph: https://slicermorph.github.io
- DeCA: https://github.com/SlicerMorph/SlicerDenseCorrespondenceAnalysis
- ATLAS repository: https://github.com/agporto/ATLAS
- Slicer Forum (support/discussion): https://discourse.slicer.org (use the
morphologyorextensionscategories).
Coming soon
Released under the BSD 2-Clause License. See the LICENSE file for full text.
If you redistribute modified versions, please retain attribution and clearly document changes.
Author / Maintainer: Arthur Porto
Scope: Atlas construction, SSM building, automated & optimized morphometric landmark transfer.
Status: Active development (2025). Feedback and contributions welcome via Issues and Pull Requests.
1. BUILDER: Provide model + landmark folders → Run → get atlas + dense correspondences.
2. DATABASE: Ingest atlas model + dense + sparse + population folder → Build SSM → Load.
3. PREDICT (Single): Tune parameters, run Rigid (RANSAC+ICP) → Deformable (PCA‑CPD) → optional Projection.
4. PREDICT (Template Optimization): Improve template before large batch.
5. PREDICT (Batch): Apply tuned settings to directory of targets → landmark .mrk.json outputs.
| Issue | Likely Cause | Remedy |
|---|---|---|
| Landmark count mismatch (BUILDER) | Inconsistent input landmark files | Standardize counts & regenerate outliers |
| Subsampling produced 0 points | Point density too low / extreme scale difference | Increase pointDensity or disable skipScaling |
| RANSAC fitness low | distanceThreshold too small / poor normals | Increase threshold / radii; check mesh quality |
| PCA‑CPD aborts early | Wrong SSM (point count mismatch) | Rebuild or reload matching database |
| Projection overshoot | projectionFactor too large | Decrease factor (1–3%) |
| Batch cancel slow | Large per-specimen transforms | Allow current specimen to finish; reduce RANSAC iters |
Enable View > Error Log in Slicer for stack traces; include logs in Issues.
Last updated: 2025-08-23