PATHOLOGY SEGMENTATION FRAMEWORK

PuzzleSeg

A unified framework for training, evaluating, and deploying segmentation models on whole-slide images.

Standardize WSI and ROI data, connect pluggable models, run gigapixel inference, and evaluate results at slide level, with reproducible configurations from experiment to deployment.

WSI-nativePluggable modelsSlide-level evaluationReproducible experiments
MODEL DEMO

See a PuzzleSeg-trained model run on a whole slide

This demo shows a segmentation model trained and deployed with PuzzleSeg. PuzzleSeg is the underlying framework; the model and annotation interface are an example implementation.

PUZZLESEG-TRAINED MODELINFERENCE DEMO · GIF
Inference demo of a segmentation model trained with PuzzleSeg inside an annotation tool

Who it is for

  1. 01

    Computational pathology research teams

    Iterating between public datasets and in-house cohorts, and needing every experiment to stay reproducible and comparable.

  2. 02

    Pathology AI engineering teams

    Connecting multiple model families to one training and inference pipeline, then deploying WSI inference reliably in production.

  3. 03

    Teams scaling patch models to WSI

    Holding a model already validated on patches and needing to reach gigapixel slides without rewriting the engineering stack.

What it solves

  1. 01

    Inconsistent data conventions

    Every scanner, magnification, and annotation format gets its own reader, and one coordinate mistake distorts the whole pipeline.

  2. 02

    Whole-slide inference is hard to ship

    A model that runs on patches hits memory, throughput, and tile-seam limits once it faces a gigapixel slide.

  3. 03

    Metrics that cannot be compared

    Patch-level metrics cannot answer slide-level questions, and configuration drift between runs is hard to trace.

ARCHITECTURE ADVANTAGES · 1 / 2

Three unifying layers across the segmentation workflow

Three shared interfaces for data, execution, and experiment provenance span training, gigapixel inference, slide-level evaluation, and reproduction.

01

Data and spatial layer

Preserve consistent coordinate and scale semantics from ingestion to gigapixel inference.

Unified WSI / ROI schema

Consistent coordinates

Level-0 coordinates and MPP unify reading, tiling, and preprocessing.

Gigapixel-native inference

WSI native

Tissue filtering, window fusion, and sparse storage balance memory and throughput.

02

Model and execution layer

Connect models, training strategies, and distributed runtimes through stable interfaces.

Unified outputs and registration

Pluggable models

SegmentationOutput and registries connect multiple model families by configuration.

Composable training orchestration

Efficient tuning

Compose losses, AMP, DDP, FSDP, ZeRO-3, and PEFT / LoRA.

03

Evaluation and provenance layer

Unify metrics, configuration, and tracking so every experiment is reliable and auditable.

Slide-level evaluation

Reliable metrics

Aggregate patch predictions by slide while decoupling inference, metrics, and visualization.

Reproducible and observable

Auditable experiments

Checkpoints retain configuration alongside experiment tracking and deterministic settings.

COMPLETE ARCHITECTURE · 2 / 2

From WSI data to reproducible outputs

Control, execution, and artifact layers preserve WSI + ROI, Level-0 spatial semantics, and Patch-to-Slide traceability.

CONTROL PLANE

HYDRA YAML + CLI OVERRIDESConfiguration is centrally managed and retained with checkpoints · Reproducible · Composable · Traceable

01InputPathology data inputConnect WSI, ROI, and public or private pathology datasets.WSI / ROIPublic and private datasetsDataset converters
02StandardizeUnified data and spatial schemaUnify data representation while preserving Level-0 coordinate semantics.Parquet / ROIRecordLevel-0 coordinatesBackend → dataset → tilingNumPy → model-agnostic collate
03CorePuzzleSeg core engineUnify models, training, and distributed execution across four bottom-up layers.Layer 4 · Distributed trainerAccelerate · DDP · FSDPLayer 3 · Training strategyPEFT · LoRALayer 2 · Processor + modelProcessor · ModelLayer 1 · Registries and interfacesRegistry · Interface
04ExecuteInference and evaluationOne engine covers Patch / WSI with synchronous and asynchronous execution.Patch inferenceSliding-window WSISync / async evaluationSlide aggregationSemantic → instance · COCO mAP / cgF1
05DeliverArtifacts and visualizationRetain models, configurations, metrics, and visual results.Checkpoints + config.yamlmetrics.json / metrics.xlsxW&B / Reports / Overlays
ARTIFACT LAYER

DATA MANIFEST · CHECKPOINT + CONFIG · METRICS + OVERLAYS + REPORTS

Unified WSI + ROI · Level-0 spatial semantics · Patch-to-Slide traceability

MODEL AND TASK COVERAGE

Supported tasks and model adapters

Task type describes what a model outputs; input / prompt mode describes what drives the segmentation. They are independent dimensions, and integration status is tracked separately from task capability.

Task typeAdapter modelInput / prompt modePlatform capabilityModel integration status
Semantic segmentationU-NetTask-specific supervised training

Task-specific training with a stable semantic segmentation baseline

Integrated
Promptable concept segmentationSAM 3Text or visual prompt

Text or visual prompt segmentation with LoRA tuning and Patch / WSI evaluation

Integrated
Reasoning-guided segmentationLISAImage and natural-language reasoning instructions

Generates masks from images and natural-language reasoning instructions with LoRA and ZeRO-3

Integrated
Object detection——Image input, automatic detection

Data schema and output interfaces support box annotations; a dedicated detection model is pending

Pending
PERFORMANCE ALIGNMENT

Task-specific validation and reproduction results

MedSAM3 Instance Segmentation

PanNuke Patch and Lizard WSI are reported separately under different protocols

Authors' reported resultPuzzleSeg · PanNukePuzzleSeg · Lizard WSI
.791
.867
.823
Dice
.707
.773
.705
Mask IoU
.637
.865
.837
IoU50 Recall
.468
.563
.308
IoU75 Recall

Results are reported separately by dataset and protocol. Values from different datasets are not combined into a single benchmark.

PathLISA Reasoning Segmentation

Same 5 datasets · same single-tile record granularity

Reference resultPuzzleSeg
.212
.225
Macro IoU
.111
.154
Weighted IoU

Sliding-window WSI Evaluation Gains

GlaS · same PuzzleSeg U-Net · Patch vs. Sliding-window aggregation

PatchSliding-windownnU-Net reference
.82.85.90.95Dice.911.926.936IoU.843.866.885+0.015 Dice · +0.023 IoU

Magnified axis (.82—.95); Sliding-window closes more than half the gap to nnU-Net.

CASE STUDY · BUILT WITH PUZZLESEG

Triplet-SAM: report-grounded segmentation with traceable concept-to-mask links

Triplet-V1 generates a structured pathology description. A resolver converts supported findings into concept prompts, and SAM3 grounds each prompt to image regions. This links selected report items to inspectable spatial masks.

  1. 01Report generationTriplet-V1

    Read the image

    A pathology multimodal model reads the slide scale by scale and writes a structured description.

    ImageStructured findings
  2. 02Concept extractionReport parser

    Split into concepts

    Each report item becomes a concept prompt that a segmentation model can consume.

    Structured findingsConcept prompts
  3. 03Pixel groundingTriplet-SAM

    Ground to pixels

    Triplet-V1 and SAM3 reason jointly to produce one spatial mask per concept.

    Concept promptsSpatial masks
Input
Multi-scale WSI pyramid
Input image

One example at each of three scales — 10× / 40× / 200×.

Pick a magnification to see its segmentation output
Output
Composite segmentation mask with four classes

Selected report items map to localizable, inspectable mask regions.

CASE STUDY · ON REAL SLIDES

One ROI, three scales of evidence

Left is the raw field, center is the structured description from Triplet-V1, right is the mask Triplet-SAM grounds from it. The three rows are three magnifications of the same ROI, and the highlighted entry in the center column is what each mask was grounded on.

Breast core-biopsy whole slide with the ROI boxed in orange
Whole slide
The ROI field after zooming in
ROI field

One breast core-biopsy WSI, narrowed from the whole slide to the ROI shared by the three scales below.

10×Tissue contextWhere the tumor is and how far it spreads
10× raw pathology field
Tumor_presence
Tumor lesion present
Tissue_parenchyma
Dense
Tissue_stroma
Dense
Normal_tissue_ratio
No
Growth_pattern
Solid nested
Stromal_background
Fibrotic
Lobular_structure_preserved
Not preserved
Ductal_structure_preserved
Not preserved
10× Tumor extent mask
Tumor extent
40×Tissue architectureHow cells are arranged and what the stroma looks like
40× raw pathology field
Cell_polarity
Lost
Cell_overlapping
Present
Cell_sparsity
Absent
Cytoplasmic_features
Eosinophilic
Nuclear_size_uniformity
Non-uniform
Nuclear_chromasia
Hyperchromatic
Stroma
Small-vessel infiltration
40× Epithelial nests and ducts mask
Epithelial nests and ducts
200×Cellular morphologyHow atypical the nuclei are
200× raw pathology field
Nuclear_atypia
Severe
Nuclear_membrane
Markedly irregular
Chromatin_pattern
Hyperchromatic
Apoptosis_or_necrosis
Patchy necrosis / karyorrhexis
Nucleolus_visibility
Prominent, with pleomorphism
Nuclear_to_cytoplasmic_ratio
Markedly increased
Cytoplasmic_secretions
None
Mitotic_figures
Atypical figures suspected
200× Individual nuclei mask
Individual nuclei
PUZZLESEG

Bring PuzzleSeg into your pathology segmentation workflow

Integrate the framework, adapt a model, or deploy WSI inference in your environment. We support research teams and pathology organizations from technical evaluation through production deployment.