Histopia for QuPath

The Histopia extension connects QuPath 0.7 to Histopia registration, global semantic-atlas, and semantic-topology workflows.

Capabilities

• select an exact cohort directly from the open QuPath project
• preserve project order or morphology-sort sections, with an optional fixed reference as the first order anchor
• configure registration, UNI2-h semantic analysis, CPU/GPU execution including explicit cuda:N selection, K range, and optional native OpenCV and libvips thread limits plus bounded global-fit threads without authoring config files
• choose conservative automatic registration and QC worker counts capped at four, then tune preprocessing, rigid-pair estimation, and memory-heavier QC rendering independently
• choose review, none, or full registration QC detail, with the production review tier retaining primary per-slide panels without generating every forensic pair diagnostic
• validate the selected Histopia workflow API, supported Python dependency ranges, native libvips runtime, and compute device directly from the extension
• run workflow-specific environment preflight automatically before registration, semantic analysis, and interchange export
• run registration and global semantic-atlas configs without blocking QuPath
• run an advanced semantic-topology config and its CPU environment preflight without blocking QuPath
• stream unbuffered Python progress, redact review notes from the command log, and cancel the complete Python process tree with bounded force escalation; current Histopia CLIs checkpoint cancelled stages as interrupted
• build and open one local staged mask/order QC portal
• record separate fingerprint-bound mask and order approvals before final registration sealing
• verify the final seal's artifact checksums and review fingerprint before displaying a sealed state or launching semantic analysis
• reject approval or semantic launch when the current QuPath selection differs from the prepared or sealed registration cohort
• bind registration QC and every approval to the slide cohort inside the current stage artifacts, hiding stages left by an earlier workspace run
• build and open the semantic 3D/QC viewer, then record fingerprint-bound semantic approval only after revalidating the exact current registration
• audit registration seals, optional semantic bindings, and review state as one path-free integrity report, while distinguishing a valid scientific review gate from a malformed or incomplete workflow
• launch a validated, compact Histopia interchange export
• select registration and optional semantic result directories
• discover every available K and default to Histopia's selected K
• select one bundle manifest and automatically import the matching open slide
• verify schema-2/3/4 annotation checksums and byte sizes before import
• reject schema-3 bundles with stale approval, mismatched provenance, or annotation paths and symlinks outside the bundle
• require matching final registration-approval metadata for schema-4 bundles
• preserve Histopia region classes and colors, with optional replacement of previous Histopia annotations

The extension does not run registration or UNI2-h inside QuPath's JVM. It calls the selected Python installation, where histopia and the required optional dependencies must already be installed.

Install

Install the current Python workflow in the environment that the extension will use:

python -m pip install \
  "histopia[registration,wsi,uni2h,topology,qupath] @ git+https://github.com/oncologylab/histopia.git@main"

Download qupath-extension-histopia-0.3.34.jar from the latest release. Drag the JAR onto QuPath 0.7, restart QuPath, then open Extensions > Histopia > Open Histopia tools.

The release also includes a SHA-256 checksum file. Verify it before installing:

sha256sum --check qupath-extension-histopia-0.3.34.jar.sha256

Build From Source

./gradlew build

The installable JAR is written under build/libs. Continuous integration also installs a pinned Histopia revision and executes the Java-generated registration and semantic configs against that package.

The Project workflow tab lists supported local WSI entries from the open QuPath project. Select at least two slides, choose a workspace and optional reference, then run registration. The first run prepares masks; open QC, review, and choose Approve masks. Run again to prepare morphology-aware order, review it, and choose Approve order. A third run computes alignment. After reviewing it, choose Seal reviewed run before starting the semantic atlas. When semantic analysis completes, choose Open semantic QC, review the atlas, and choose Approve semantic before export. Runtime configs, the exact project-selection manifest, and local review portals are kept in <workspace>/.histopia. The semantic viewer is served only on an ephemeral 127.0.0.1 port so browser modules and local assets load correctly. Audit integrity validates the current registration and any started semantic run together. A valid but unapproved stage is reported as requiring scientific review; stale bindings, malformed approvals, and incomplete runs fail the action. The portable report is written to <workspace>/.histopia/workflow-audit.json. Reopening the tools refreshes a newly opened project while retaining the selected cohort and reference for the same project. Unavailable project entries are reported and skipped without hiding usable slides. Workflow inputs are locked while a process is active. Starting semantic analysis verifies the existing registration selection and seal before atomically updating only the semantic runtime config, so reviewed registration provenance is not rewritten. When a workspace is reused after changing the selected slides, the current mask manifest is pruned to that cohort, stale order or alignment stages remain hidden, and QC, approval, and semantic actions reject mismatched artifacts.

Enter auto, cpu, cuda, cuda:N, or mps in the semantic device control. Check environment runs the versioned histopia-qupath doctor in the selected Python environment and streams dependency, libvips, backend, and accelerator details to the extension log. Registration, semantic analysis, and export run their narrower preflight automatically before starting. The device control applies to UNI2-h feature extraction. The global PCA, correspondence, batch correction, K selection, and topology fit remain on the validated CPU implementation, so an idle accelerator during that stage is expected. Leave VIPS threads blank for libvips' adaptive default, or enter a positive cap shared by registration WSI reads and semantic extraction after benchmarking the target scanner format, storage, and host. The automatic registration-worker value uses half the available processors up to a maximum of four; it remains editable for measured host-specific tuning of thumbnail, mask, and section-order work. On one validated 17,280 x 17,664 SCN export, eight native threads completed in 5.17 seconds at 598 MiB peak RSS, while sixteen took 5.25 seconds at 839 MiB; the generated TIFFs were byte-identical. This is measured guidance, not a portable default. The registration-worker control also bounds independent rigid feature preparation and reference/adjacent pair estimation. Four workers reduced rigid alignment from 9.32 to 3.25 seconds on one 24-slide benchmark without changing the registration result. Leave OpenCV threads blank for the host default, or cap OpenCV's process-wide native pool during registration. Histopia restores the prior setting when the run ends. On the same 32-vCPU host with four registration workers, 16 OpenCV threads used about 28% less average CPU than the 32-thread default for about 4% more wall time; all measured registration results were byte-identical. QC workers independently bounds concurrent registration diagnostics so an eight-worker mask setting does not force eight memory-heavier QC renderers. In a measured 24-slide, 1200-pixel mask run, eight workers used 1.62 GB peak memory and was the practical throughput setting; 16 workers used 2.55 GB for only another 1.29x speedup. QC detail controls which alignment diagnostics are retained. review is the production default and keeps primary slide panels plus non-rigid acceptance panels. full adds pair, crop, blend, checkerboard, and contact diagnostics for algorithm debugging. none skips post-mask alignment imagery while retaining transforms, metrics, and export support. On a representative 24-slide run, review reduced registration-plus-QC time from 69.83 to 10.97 seconds and retained artifact volume from 1.278 GB to 437 MB, with byte-identical registration results and primary panels. Fit threads separately caps independent CPU fit tasks and native BLAS/OpenMP work during the global semantic fit; four is the measured conservative default.

The Run analysis tab remains available for advanced registration, semantic-atlas, or semantic-topology TOML and JSON configs. The Export and import tab writes a QuPath bundle, loads the available semantic K values, and imports annotations for the currently open matching source slide.

Semantic annotations are exported in original WSI pixel coordinates. Histopia thumbnail registration matrices are included as provenance and are not applied directly to QuPath native coordinates. Adjacent same-class patches are losslessly coalesced by default to reduce GeoJSON size and QuPath geometry overhead; the Python CLI retains a one-tile-per-patch audit mode.

See the Histopia QuPath integration guide for Python installation, bundle guarantees, and CLI usage.

Requirements

• QuPath 0.7
• Java version supported by QuPath
• Python 3.10 or later with Histopia installed
• project entries backed by one local NDPI, SCN, SVS, TIFF, or OME-TIFF URI

License

This extension is licensed under GPL-3.0-or-later to remain compatible with QuPath. Histopia has its own license.