# Histopia: reviewed serial-section registration and 3D histology for spatial omics cohorts

> Histopia is research software from Oncology Lab for aligning serial histology and proteomic sections, masking tissue group-aware, segmenting morphology with UNI2-h, and rendering interactive 3D stacks. It is alpha software with explicit review gates, and the README says validation does not establish clinical use.

**oncologylab/histopia** — Histology Spatial Topology for Omics Profiling and Inter-section Alignment

- Repository: https://github.com/oncologylab/histopia
- Website: https://oncologylab.github.io/histopia/
- Stars: 629 · Forks: 5
- Language: Python
- License: BSD-3-Clause
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/oncologylab-histopia

## The problem Histopia solves: sections that do not line up

Serial-section histology produces a stack of physical slices cut from one tissue block. Each slice is stained, scanned and stored as its own whole-slide image, and nothing in that process guarantees that slice 12 sits in the same coordinate frame as slice 11. The same problem appears in proteomic imaging cohorts, where the tissue is the same but the acquisition is per section. Histopia is aimed at that gap. Its stated scope is serial-section histology and proteomic image analysis, and it covers inter-section alignment, group-aware tissue masking, global morphology segmentation, spatial topology and interactive 3D reconstruction across sections. The audience is research groups, not clinical labs. The README closes with the sentence that Histopia remains research software, and pyproject.toml classifies it as Development Status 3 - Alpha with Intended Audience :: Science/Research.

## How the registration, semantic and topology stages fit together

The pipeline is split into named workflows, each with its own documentation page: registration, semantic atlas, semantic topology, stain profiling, visualization and QuPath. Registration builds group-aware tissue masks, then handles reviewed section orientation and order, hybrid serial/reference affine alignment, QC and resumable WSI export. The word reviewed matters: orientation and order are not guessed silently, they are review-gated. The semantic atlas then fits UNI2-h morphology regions globally, with guarded slide correction, automatic K evaluation and cross-section topology. Semantic topology consumes the registered masks, builds tissue envelopes, produces confidence-core and exhaustive selected-K semantic surfaces, runs held-out reconstruction validation, and carries explicit physical z spacing plus uncertainty-aware connected-volume review. Stain profiling works in source space with relative optical density for H-DAB, Sirius Red, PAS and Alcian Blue, with guarded background correction. Caching is strict by design: registration ordering and viewer assets use exact, checksummed caches, and semantic fitting reuses only a fully sealed result whose feature contents, slide order, scientific controls, algorithm revision and numerical runtime all match. Change a reviewed mask, a geometry, an orientation, a transform, a semantic label or an encoding setting and the affected cache is invalidated. That is a deliberate trade of speed for reproducibility.

## Installing Histopia and running a first registration config

The base package installs from PyPI with pip. The README shows a single-line install, and pyproject.toml requires Python 3.10 or newer. The base install pulls in only packaging and, on Python below 3.11, tomli, so the heavy imaging and machine-learning dependencies arrive through extras.

```bash
pip install histopia
```

Pick the extras that match the workflow you intend to run. The README lists registration, wsi, semantic, topology, stain, uni2h and qupath as separate profiles, and they can be combined in one command.

```bash
pip install "histopia[registration,wsi]"
pip install "histopia[semantic]"
pip install "histopia[topology]"
pip install "histopia[stain]"
```

The repository ships example configuration files under examples/, including registration_config.toml, semantic_atlas_config.toml, stain_config.toml and topology_config.toml. Copy the one you need and edit it rather than starting from an empty file. Before starting a long extraction, check what the machine actually offers. The README gives these doctor commands, and the device flag accepts auto, cpu, cuda, cuda:N or mps.

```bash
histopia-semantic doctor --device auto
histopia-semantic doctor --device cuda:0
```

Then run extraction and fitting against your config. Compute settings can be overridden on the command line without editing the scientific configuration, which keeps the config file as the record of what was scientifically intended.

```bash
histopia-semantic extract --config atlas.toml --device cuda:0 \
  --batch-size 128 --patch-workers 4 --vips-threads 8
histopia-semantic fit --config atlas.toml --fit-threads 4
```

When you change the algorithm and want a fresh fit rather than a reused sealed result, the README documents an explicit overwrite flag.

```bash
histopia-semantic fit --config atlas.toml --fit-threads 4 --overwrite-fit
```

For development work, the README gives a clone-and-install path with the dev extra and pytest.

```bash
git clone https://github.com/oncologylab/histopia.git
cd histopia
python -m pip install -e ".[dev,registration,semantic,wsi]"
python -m pytest
```

## Audit as a gate, not a report

The most opinionated part of Histopia is that it refuses to treat a finished run as a publishable one. The histopia-visualize audit command takes one or more run directories per sample along with a viewer manifest, and produces a path-free report that separates approved results from explicit review gates, missing stages and integrity failures. The README states that the report includes family-scoped stain approval and topology binding to the exact registration and semantic results. Stable viewer builds publish approved results only, and histopia-visualize review generates a separate review hub holding pending registration, 3D, semantic and stain evidence. This is a real design position: the tool assumes a human decides what is acceptable, and it makes that decision part of the artifact rather than a note in a lab book. It also means a cohort can be technically complete and still not publishable, which will frustrate anyone expecting a one-command pipeline. The README is explicit that the public GitHub Pages showcase includes both approved and visibly identified review-stage demonstration cohorts, and that it is not a production release manifest.

## Where Histopia is the wrong tool

Three limits are stated in the repository itself. First, the README says current validation does not establish clinical use. If your work needs a diagnostic claim, this is not the software for it. Second, cell-level correspondence between sections is not established by current validation. Histopia aligns sections and builds semantic surfaces at region scale; it does not promise that a given cell in one section maps to a specific cell in the next. Third, final OME metadata conformance is not established either, so downstream tools that expect conformant OME output should be tested against real exports before you plan around them. Beyond the stated limits, the packaging tells its own story: the project version is 0.1.0 and the classifier is Alpha. The release list is dominated by interactive presentation demos (a three-mouse presentation demo and successive sixteen-mouse showcase builds), which are visualization artifacts rather than library releases. Anyone who needs a stable API surface, or who wants to pin a semantic version and forget about it, should look elsewhere. The dependency extras are also opinionated: registration and stain both pull opencv-contrib-python-headless, wsi and stain both need pyvips, and the semantic path expects UNI2-h features. Those are not small installs, and the README points to checked-in constraint files under constraints/ for exact validation environments rather than promising that any combination of versions works.

## Histopia against a general-purpose registration toolkit

The obvious alternative is a general-purpose medical image registration library, or a general image-analysis platform such as QuPath used on its own. The difference in approach is where the domain knowledge lives. A general registration toolkit gives you transformations, similarity metrics and optimizers, and leaves tissue masking, section ordering, staining differences between adjacent slices and the question of which sections belong to the same block entirely to you. Histopia puts those concerns in the workflow: group-aware tissue masks, reviewed section orientation and order, hybrid serial/reference affine alignment, and stain-family-specific optical density handling for H-DAB, Sirius Red, PAS and Alcian Blue. On the other side, Histopia does not try to replace QuPath. It ships a QuPath 0.7 extension release that launches registration and semantic jobs, passes compact checksummed GeoJSON regions and native WSI coordinates back, and supports dynamic K selection, with a fail-closed workflow integrity audit. So the honest comparison is not Histopia versus QuPath; it is Histopia plus QuPath versus assembling the same cohort workflow yourself out of a registration library, a segmentation stack and a viewer. The former constrains you to Histopia's stages and review gates. The latter costs you the review gates, and the caching that invalidates results when scientific controls change.

## Maintenance, upgrades and the BSD 3-Clause licence

The repository is not archived, and the last push was on 2026-08-28, so it is being worked on. The most recent releases on the list are demonstration builds rather than numbered library versions, and the package version in pyproject.toml is 0.1.0, so upgrade planning should assume the API can move. The README describes a dependency-management document and checked-in constraint files under constraints/ for exact validation environments, which is the mechanism the project offers for reproducibility: pin against those constraints rather than against loose version ranges. The extras are range-pinned (for example numpy>=1.26,<3 and scikit-learn>=1.5,<2), so a fresh resolve months from now will not necessarily match a validated environment. On licensing, Histopia is distributed under the BSD 3-Clause License, and pyproject.toml declares the same licence file. That is a permissive licence, but it says nothing about the licences of the optional dependencies you enable, and it says nothing about the terms attached to UNI2-h features or to any model weights the semantic workflow expects. Those are separate questions and the README does not answer them; check them before you build a distribution around this stack. Nothing here is legal advice.

## Conclusion

Adopt Histopia if you already run serial-section histology or proteomic imaging cohorts and you want alignment, semantic regions, stain quantification and a 3D viewer inside one Python and QuPath workflow, with results that stay explicitly review-gated. Do not adopt it if you need a validated clinical pipeline, cell-level correspondence between sections, or a finished OME metadata story: the README states that current validation does not establish clinical use, cell-level correspondence, or final OME metadata conformance, and pyproject.toml marks the package as Development Status 3 - Alpha. Before committing a cohort, run histopia-semantic doctor --device auto on the machine that will do the extraction, check that the optional extras you need (registration, wsi, semantic, topology, stain, qupath) resolve against the checked-in constraints, and confirm which of your runs will be treated as approved versus review-stage by histopia-visualize audit.

## FAQ

### How do I install Histopia?

Install the base package with pip install histopia, then add the workflow extras you need, for example pip install "histopia[registration,wsi]" or pip install "histopia[semantic]". Python 3.10 or newer is required according to pyproject.toml.

### What does Histopia need in order to run its semantic atlas?

The semantic workflow uses globally fitted UNI2-h morphology regions with guarded slide correction and automatic K evaluation, and it installs through the semantic extra. The README lists a separate uni2h extra as well, and notes that UNI2-h extraction supports device set to auto, cpu, cuda, cuda:N or mps.

### Is Histopia suitable for clinical use?

No. The README states that Histopia remains research software and that current validation does not establish clinical use, cell-level correspondence, or final OME metadata conformance. pyproject.toml classifies the package as Development Status 3 - Alpha.

### Can Histopia be used from QuPath?

Yes. The project ships a QuPath 0.7 extension release that launches registration and semantic jobs, with fail-closed workflow integrity audits, compact checksummed GeoJSON regions, dynamic K selection and native WSI coordinates. The README points to the extension release page and to a qupath extra for the Python side.

## Sources

- [License: BSD-3-Clause](https://github.com/oncologylab/histopia/blob/main/LICENSE)
- [oncologylab/histopia on GitHub](https://github.com/oncologylab/histopia)
- [Project website](https://oncologylab.github.io/histopia/)
- [README](https://github.com/oncologylab/histopia/blob/main/README.md)
- [Releases](https://github.com/oncologylab/histopia/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oncologylab-histopia