<p align="center"> <img src="https://raw.githubusercontent.com/AtlasAnalyticsLab/AtlasPatch/main/assets/images/Logo.png" alt="AtlasPatch Logo" width="100%"> </p>

AtlasPatch: Efficient Tissue Detection and High-throughput Patch Extraction for Computational Pathology at Scale

<p align="center"> <a href="https://pypi.org/project/atlas-patch/"><img alt="PyPI" src="https://img.shields.io/pypi/v/atlas-patch"></a> <a href="https://pypi.org/project/atlas-patch/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/atlas-patch"></a> <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-CC--BY--NC--SA--4.0-blue"></a> </p> <!-- TODO: Update paper link (XXXX.XXXXX) once published on arXiv --> <p align="center"> <a href="https://atlasanalyticslab.github.io/AtlasPatch/"><b>Project Page</b></a> | <a href="https://arxiv.org/abs/2602.03998"><b>Paper</b></a> | <a href="https://huggingface.co/AtlasAnalyticsLab/AtlasPatch"><b>Hugging Face</b></a> | <a href="https://github.com/AtlasAnalyticsLab/AtlasPatch"><b>GitHub</b></a> </p>

Table of Contents

• Installation
  • Quick Install (Recommended)
  • OpenSlide Prerequisites
  • Optional Encoder Dependencies
  • Alternative Installation Methods
• Usage Guide
  • Pipeline Checkpoints
    • A - Tissue Detection
    • B - Patch Coordinate Extraction
    • C - Patch Embedding
    • D - Patch Writing
  • Visualization Samples
  • Process Command Arguments
    • Required
    • Optional
      • Patch Layout
      • Segmentation & Extraction Performance
      • Feature Extraction
      • Filtering & Quality
      • Visualization
      • Run Control
• Supported Formats
• Using Extracted Data
  • Patch Coordinates
  • Feature Matrices
• Available Feature Extractors
  • Core vision backbones on Natural Images
  • Medical- and Pathology-Specific Vision Encoders
  • CLIP-like models
    • Natural Images
    • Medical- and Pathology-Specific CLIP
• Bring Your Own Encoder
• SLURM job scripts
• Frequently Asked Questions (FAQ)
• Feedback
• Citation
• License
• Future Updates
  • Slide Encoders

Installation

Quick Install (Recommended)

# Install AtlasPatch
pip install atlas-patch

# Install SAM2 (required for tissue segmentation)
pip install git+https://github.com/facebookresearch/sam2.git

Note: AtlasPatch requires the OpenSlide system library for WSI processing. See OpenSlide Prerequisites below.

OpenSlide Prerequisites

Before installing AtlasPatch, you need the OpenSlide system library:

• Using Conda (Recommended):

  conda install -c conda-forge openslide
  

• Ubuntu/Debian:

  sudo apt-get install openslide-tools
  

• macOS:

  brew install openslide
  

• Other systems: Visit OpenSlide Documentation

Optional Encoder Dependencies

Some feature extractors require additional dependencies that must be installed separately:

# For CONCH encoder (conch_v1, conch_v15)
pip install git+https://github.com/Mahmoodlab/CONCH.git

# For MUSK encoder
pip install git+https://github.com/lilab-stanford/MUSK.git

These are only needed if you plan to use those specific encoders.

Alternative Installation Methods

<details> <summary><b>Using Conda Environment</b></summary>

# Create and activate environment
conda create -n atlas_patch python=3.10
conda activate atlas_patch

# Install OpenSlide
conda install -c conda-forge openslide

# Install AtlasPatch and SAM2
pip install atlas-patch
pip install git+https://github.com/facebookresearch/sam2.git

</details> <details> <summary><b>Using uv (faster installs)</b></summary>

# Install uv (see https://docs.astral.sh/uv/getting-started/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create and activate environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install AtlasPatch and SAM2
uv pip install atlas-patch
uv pip install git+https://github.com/facebookresearch/sam2.git

</details>

Usage Guide

AtlasPatch provides a flexible pipeline with 4 checkpoints that you can use independently or combine based on your needs.

Pipeline Checkpoints

<p align="center"> <img src="https://raw.githubusercontent.com/AtlasAnalyticsLab/AtlasPatch/main/assets/images/Checkouts.png" alt="AtlasPatch Pipeline Checkpoints" width="100%"> </p>

Quick overview of the checkpoint commands:

• detect-tissue: runs SAM2 segmentation and writes mask overlays under <output>/visualization/.
• segment-and-get-coords: runs segmentation + patch coordinate extraction into <output>/patches/<stem>.h5.
• process: full pipeline (segmentation + coords + feature embeddings) in the same H5.
• segment-and-get-coords --save-images: same as segment-and-get-coords, plus patch PNGs under <output>/images/<stem>/.

---

[A] Tissue Detection

Detect and visualize tissue regions in your WSI using SAM2 segmentation.

atlaspatch detect-tissue /path/to/slide.svs \
  --output ./output \
  --device cuda

---

[B] Patch Coordinate Extraction

Detect tissue and extract patch coordinates without feature embedding.

atlaspatch segment-and-get-coords /path/to/slide.svs \
  --output ./output \
  --patch-size 256 \
  --target-mag 20 \
  --device cuda

---

[C] Patch Embedding

Run the full pipeline: Tissue detection, coordinate extraction, and feature embedding.

atlaspatch process /path/to/slide.svs \
  --output ./output \
  --patch-size 256 \
  --target-mag 20 \
  --feature-extractors resnet50 \
  --device cuda

---

[D] Patch Writing

Full pipeline with optional patch image export for visualization or downstream tasks.

atlaspatch segment-and-get-coords /path/to/slide.svs \
  --output ./output \
  --patch-size 256 \
  --target-mag 20 \
  --device cuda \
  --save-images

---

Pass a directory instead of a single file to process multiple WSIs; outputs land in <output>/patches/<stem>.h5 based on the path you provide to --output.

Visualization Samples

Below are some examples for the output masks and overlays (original image, predicted mask, overlay, contours, grid).

<p align="center"> <img src="https://raw.githubusercontent.com/AtlasAnalyticsLab/AtlasPatch/main/assets/images/VisualizationSamples.png" alt="AtlasPatch visualization samples" width="100%"> </p>

Quantitative and qualitative analysis of AtlasPatch tissue detection against existing slide-preprocessing tools.

<p align="center"> <img src="https://raw.githubusercontent.com/AtlasAnalyticsLab/AtlasPatch/main/assets/images/Comparisons.jpg" alt="AtlasPatch method comparison" width="100%"> </p>

Representative WSI thumbnails are shown from diverse tissue features and artifact conditions, with tissue masks predicted by thresholding methods (TIAToolbox, CLAM) and deep learning methods (pretrained "non-finetuned" SAM2 model, Trident-QC, Trident-Hest and AtlasPatch), highlighting differences in boundary fidelity, artifact suppression and handling of fragmented tissue. Tissue detection performance is also shown on the held-out test set for AtlasPatch and baseline pipelines, highlighting that AtlasPatch matches or exceeds their segmentation quality. The segmentation complexity–performance trade-off, plotting F1-score against segmentation runtime (on a random set of 100 WSIs), shows AtlasPatch achieves high performance with substantially lower wall-clock time than tile-wise detectors and heuristic pipelines, underscoring its suitability for large-scale WSI preprocessing.

Process Command Arguments

The process command is the primary entry point for most workflows. It runs the full pipeline: tissue segmentation, patch coordinate extraction, and feature embedding. You can process a single slide or an entire directory of WSIs in one command.

atlaspatch process <WSI_PATH> --output <DIR> --patch-size <INT> --target-mag <INT> --feature-extractors <NAMES> [OPTIONS]

Required

| Argument | Description | | --- | --- | | WSI_PATH | Path to a single slide file or a directory containing slides. When a directory is provided, all supported formats are processed. | | --output, -o | Root directory for results. Outputs are organized as <output>/patches/<stem>.h5 for coordinates and features, and <output>/visualization/ for overlays. | | --patch-size | Final patch size in pixels at the target magnification (e.g., 256 for 256×256 patches). | | --target-mag | Magnification level to extract patches at. Common values: 5, 10, 20, 40. The pipeline reads from the closest available pyramid level and resizes if needed. | | --feature-extractors | Comma or space-separated list of encoder names from Available Feature Extractors. Multiple encoders can be specified to extract several feature sets in one pass (e.g., resnet50,uni_v2). |

Optional

Patch Layout

| Argument | Default | Description