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

Project Page | Paper | Hugging Face | GitHub

Table of Contents

• Installation
  • 1. Install OpenSlide
  • 2. Install AtlasPatch
  • 3. Install SAM2
  • Optional extras
  • Alternative Installation Methods
• Usage Guide
  • Choose a Command
  • Quick Start
    • Full patch pipeline
    • Slide encoding
    • Patient encoding
  • Supported Inputs
  • Visualization Samples
• Encoders
  • Available Patch 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
  • Available Slide Encoders
  • Available Patient Encoders
• Output Files
  • What AtlasPatch writes
    • Per-Slide H5 files
    • Patient embedding files
    • Optional image outputs
  • Reading the files
    • Patch coordinates
    • Patch feature matrices
    • Slide embeddings
    • Patient embeddings
• SLURM job scripts
• Frequently Asked Questions (FAQ)
• Feedback
• Citation
• License

Installation

AtlasPatch targets Python 3.10+.

1. Install OpenSlide

AtlasPatch needs the OpenSlide system library before you install the Python package.

# conda
conda install -c conda-forge openslide

# Ubuntu / Debian
sudo apt-get install openslide-tools

# macOS
brew install openslide

2. Install AtlasPatch

pip install atlas-patch

3. Install SAM2

All WSI-facing AtlasPatch commands use SAM2 for tissue segmentation.

pip install git+https://github.com/facebookresearch/sam2.git

Optional extras

The default install stays lean. Install only the model stacks you need.

Some patch encoders still require upstream project packages in addition to atlas-patch[patch-encoders]:

# Optional: CONCH patch encoders
pip install git+https://github.com/MahmoodLab/CONCH.git

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

Alternative Installation Methods

# 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

# Install uv
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

Usage Guide

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

Choose a Command

Quick Start

Full patch pipeline

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

This writes a per-slide H5 file at ./output/patches/slide.h5 with:

• coords
• features/uni_v2
• slide metadata in file attributes

Slide encoding

atlaspatch encode-slide /path/to/slides \
  --output ./output \
  --slide-encoders titan \
  --patch-size 512 \
  --target-mag 20 \
  --device cuda

encode-slide is WSI-only. It creates or reuses the per-slide patch H5, backfills the required upstream patch features automatically, and appends slide embeddings into the same file.

See Available Slide Encoders for the built-in encoder list, requirements, and install extras.

If you want multiple slide encoders in one run, they must be compatible with one patch geometry. For example, titan and prism need different patch sizes, so they should be run separately.

Patient encoding

Create a CSV file:

case_id,slide_path,mpp
case-001,/data/case-001-slide-a.svs,0.25
case-001,/data/case-001-slide-b.svs,
case-002,/data/case-002-slide-a.svs,

Then run:

atlaspatch encode-patient cases.csv \
  --output ./output \
  --patient-encoders moozy \
  --patch-size 224 \
  --target-mag 20 \
  --device cuda

encode-patient groups slides by case_id, creates or reuses per-slide H5 files, ensures the required patch features exist, and writes one patient embedding per case.

See Available Patient Encoders for the built-in encoder list, requirements, and install extras.

Supported Inputs

From atlaspatch info:

• WSI formats: .svs, .tif, .tiff, .ndpi, .vms, .vmu, .scn, .mrxs, .bif, .dcm
• image formats: .png, .jpg, .jpeg, .bmp, .webp, .gif

Visualization Samples

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

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

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.

Encoders

Available Patch Feature Extractors

Core vision backbones on Natural Images

Medical- and Pathology-Specific Vision Encoders

Note: Some encoders (e.g., uni_v1, etc.) require access approval from Hugging Face. To use these models:

1. Request access on the respective Hugging Face model page
2. Once approved, set your Hugging Face token as an environment variable:

   export HF_TOKEN=your_huggingface_token
   

3. Then you can use the encoder in your commands

CLIP-like models

Natural Images

Medical- and Pathology-Specific CLIP

Bring Your Own Encoder

Add a custom encoder without touching AtlasPatch by writing a small plugin and pointing the CLI at it with --feature-plugin /path/to/plugin.py. The plugin must expose a register_feature_extractors(registry, device, dtype, num_workers) function; inside that hook call register_custom_encoder with a loader that knows how to load the model and run a forward pass.

import torch
from torchvision import transforms
from atlas_patch.models.patch.custom import CustomEncoderComponents, register_custom_encoder


def build_my_encoder(device: torch.device, dtype: torch.dtype) -> CustomEncoderComponents:
    """
    Build the components used by AtlasPatch to embed patches with a custom model.

    Returns:
        CustomEncoderComponents describing the model, preprocess transform, and forward pass.
    """
    model = ...  # your torch.nn.Module
    model = model.to(device=device, dtype=dtype).eval()
    preprocess = transforms.Compose([transforms.Resize(224), transforms.ToTensor()])

    def forward(batch: torch.Tensor) -> torch.Tensor:
        return model(batch)  # must return [batch, embedding_dim]

    return CustomEncoderComponents(model=model, preprocess=preprocess, forward_fn=forward)


def register_feature_extractors(registry, device, dtype, num_workers):
    register_custom_encoder(
        registry=registry,
        name="my_encoder",
        embedding_dim=512,
        loader=build_my_encoder,
        device=device,
        dtype=dtype,
        num_workers=num_workers,
    )

Run AtlasPatch with --feature-plugin /path/to/plugin.py --feature-extractors my_encoder to benchmark your encoder alongside the built-ins. Multiple plugins and extractors can be added at once. Your custom embeddings will be written under features/my_encoder, row-aligned with coords, next to the built-in extractors.

Available Slide Encoders

Available Patient Encoders

Output Files

Everything AtlasPatch writes lives under the directory you pass to --output.

What AtlasPatch writes

Per-Slide H5 files

Each processed slide gets one H5 file:

<output>/patches/<stem>.h5

That file may contain:

• coords
• features/<patch_encoder>
• slide_features/<slide_encoder>

Rows in features/<patch_encoder> are aligned with coords.

Patient embedding files

Patient embeddings are written separately:

<output>/patient_features/<encoder>/<case_id>.h5

Each patient H5 file stores the case embedding in features.

Optional image outputs

• patch PNGs: <output>/images/<stem>/
• overlays and masks: <output>/visualization/

Reading the files

Per-slide H5 files keep patch coordinates, patch features, and slide embeddings together in one place.

Patch coordinates

• dataset: coords
• shape: (N, 5)
• columns: (x, y, read_w, read_h, level)
• x and y are level-0 pixel coordinates.
• read_w, read_h, and level describe how the patch was read from the WSI.
• the level-0 footprint of each patch is stored as the patch_size_level0 file attribute

Example:

import h5py
import numpy as np
import openslide
from PIL import Image

h5_path = "output/patches/sample.h5"
wsi_path = "/path/to/slide.svs"

with h5py.File(h5_path, "r") as f:
    coords = f["coords"][...]  # (N, 5) int32: [x, y, read_w, read_h, level]
    patch_size = int(f.attrs["patch_size"])

with openslide.OpenSlide(wsi_path) as wsi:
    for x, y, read_w, read_h, level in coords:
        img = wsi.read_region(
            (int(x), int(y)),
            int(level),
            (int(read_w), int(read_h)),
        ).convert("RGB")
        if img.size != (patch_size, patch_size):
            img = img.resize((patch_size, patch_size), resample=Image.BILINEAR)
        patch = np.array(img)  # (H, W, 3) uint8

Patch feature matrices

• group: features/
• dataset: features/<patch_encoder>
• shape: (N, D)

Rows in every feature matrix are aligned with coords.

import h5py

with h5py.File("output/patches/sample.h5", "r") as f:
    feature_names = list(f["features"].keys())
    resnet50_features = f["features/resnet50"][...]

Slide embeddings

• group: slide_features/
• dataset: slide_features/<slide_encoder>
• shape: (D,)

import h5py

with h5py.File("output/patches/sample.h5", "r") as f:
    titan_embedding = f["slide_features/titan"][...]

Patient embeddings

Patient embeddings are stored in separate H5 files under patient_features/<encoder>/.

import h5py

with h5py.File("output/patient_features/moozy/case-001.h5", "r") as f:
    case_embedding = f["features"][...]

SLURM job scripts

We prepared ready-to-run SLURM templates under jobs/:

• Patch extraction (SAM2 + H5/PNG): jobs/atlaspatch_patch.slurm.sh. Edits to make:
  • Set WSI_ROOT, OUTPUT_ROOT, PATCH_SIZE, TARGET_MAG, SEG_BATCH.
  • Ensure --cpus-per-task matches the CPU you want; the script passes --patch-workers ${SLURM_CPUS_PER_TASK} and caps --max-open-slides at 200.
  • --fast-mode is on by default; append --no-fast-mode to enable content filtering.
  • Submit with sbatch jobs/atlaspatch_patch.slurm.sh.
• Feature embedding (adds features into existing H5 files): jobs/atlaspatch_features.slurm.sh. Edits to make:
  • Set WSI_ROOT, OUTPUT_ROOT, PATCH_SIZE, and TARGET_MAG.
  • Configure FEATURES (comma/space list, multiple extractors are supported), FEATURE_DEVICE, FEATURE_BATCH, FEATURE_WORKERS, and FEATURE_PRECISION.
  • This script is intended for feature extraction; use the patch script when you need segmentation + coordinates, and run the feature script to embed one or more models into those H5 files.
  • Submit with sbatch jobs/atlaspatch_features.slurm.sh.
• Running multiple jobs: you can submit several jobs in a loop (for example, for i in {1..50}; do sbatch jobs/atlaspatch_features.slurm.sh; done). AtlasPatch uses per-slide lock files to avoid overlapping work on the same slide.

Frequently Asked Questions (FAQ)

atlaspatch process /path/to/slides --output ./output --max-open-slides 50

atlaspatch process /path/to/slides --output ./output --mpp-csv /path/to/mpp.csv

atlaspatch process /path/to/slides --output ./output --force

slide_features/<slide_encoder>

patient_features/<encoder>/<case_id>.h5

Have a question not covered here? Feel free to open an issue and ask!

Feedback

• Report problems via the bug report template so we can reproduce and fix them quickly.
• Suggest enhancements through the feature request template with your use case and proposal.
• When opening a PR, fill out the pull request template and run the listed checks (lint, format, type-check, tests).

Citation

If you use AtlasPatch in your research, please cite our paper:

@article{atlaspatch2026,
  title   = {AtlasPatch: Efficient Tissue Detection and High-throughput Patch Extraction for Computational Pathology at Scale},
  author  = {Alagha, Ahmed and Leclerc, Christopher and Kotp, Yousef and Metwally, Omar and Moras, Calvin and Rentopoulos, Peter and Rostami, Ghodsiyeh and Nguyen, Bich Ngoc and Baig, Jumanah and Khellaf, Abdelhakim and Trinh, Vincent Quoc-Huy and Mizouni, Rabeb and Otrok, Hadi and Bentahar, Jamal and Hosseini, Mahdi S.},
  journal = {arXiv preprint arXiv:2602.03998},
  year    = {2026}
}

License

AtlasPatch is released under CC BY-NC-SA 4.0.