QuPath Annotation Workflow
The group’s pipeline for turning whole-slide images into annotated research data in QuPath, with GeoJSON as the interchange format.
What it is
QuPath is the group’s annotation and image-analysis hub, and the workflow around it is conventionalised.
Input. WSIs from the Memorial share or via Sectra PACS. Two extensions bridge to PACS: sectra-qupath-extension (Groovy) and sectra-python-qupath-extension (Python, for automation). Slide-level QC via HistoQC produces outputs used as QuPath-project filters, so poor-quality slides are excluded before annotation effort is spent — see WSI Quality Control.
Annotation. Regions drawn in QuPath, optionally via QuickAnnotator for rapid browser-based work or HistomicsML for interactive region labelling. TissueSelector filters tissue regions beforehand; CohortFinder handles batch-level project curation.
Export. GeoJSON is the interchange format between QuPath and every downstream tool. The naming convention is {organ}__{class}__{reviewer}.geojson — the reviewer field is what makes multi-observer agreement analysis possible later, so it is not optional.
That choice has a cost worth knowing about: a good deal of older pathology tooling predates GeoJSON and parses Aperio ImageScope XML instead. WSITools is a worked example — its annotation module reads ImageScope Region/Vertex XML through minidom and has no JSON support at all, so a GeoJSON file does not merely fail to map, it raises a syntax error. This is not a reason to move off GeoJSON. Reading GeoJSON is a dozen lines — iterate features, take geometry.coordinates and properties.classification.name, and treat the coordinates as level-0 pixels, which is the same convention OpenSlide’s read_region expects. Writing that adapter is nearly always cheaper than adopting a tool’s native format.
Governance. .qpproj project files for cohorts containing patient identifiers must not be committed; they stay on the Memorial share. Scripts live in the project repo where they are used, and only genuinely generic scripts belong in the extension repos.
Calibration. Where annotation feeds an agreement study, reviewers calibrate against a reference scorer on a pilot batch first. A QuPath annotation protocol for tumour and necrosis exists at version 0.9 draft, owned by the digital pathology research team, standardising region annotation, naming, export settings, and reviewer calibration rules.
Why it matters for my work
This pipeline is shared infrastructure across the morphology and AI clusters. HER2 Intratumoral Heterogeneity uses it for WSI-level heterogeneity mapping with GeoJSON export per the group SOP. Omentum uses it for benign-mimic teaching cases and rubric piloting. A planned kidney tumour-and-necrosis study uses it to produce polygons for region-level agreement analysis. Patoloji Atlası is the exception that proves the rule — it exports PNG overlays rather than GeoJSON, because it is a teaching surface, not a research dataset.
How it connects
QuPath Tooling — the full repository index behind each step of this pipeline.
Interobserver Agreement — the reviewer field in the GeoJSON naming convention is what makes multi-observer analysis possible; the analysis itself runs in meddecide.
Intratumoral Heterogeneity — spatial quantification is the main scientific payoff of annotating whole slides rather than scoring fields by eye.
WSI Quality Control — runs upstream, so annotation effort is not spent on unusable slides.
De-identification — determines what may leave the Memorial share at all.
Mitotic Count — an unexpected diagnostic use of this pipeline: QuPath reports annotation area in mm², so “count within a calibrated 2–3 mm² region” is an annotation task the tooling already supports rather than new capability.
Cell Detection and Counting — the automated counterpart: dot annotations exported here are exactly the training signal a detection network needs, and dots are cheap enough to produce during routine work.
CORAL — an independent arrival at this page’s GeoJSON-as-interchange decision. A spatial-proteomics pipeline from another group exports its tissue boundaries as GeoJSON for the explicit purpose of hand correction in QuPath, which is mild evidence the choice here was right.
VALIS — the route to drawing an annotation once instead of once per stain. It registers a whole series of slides from one block and exposes a public function for warping point coordinates, and GeoJSON vertices are exactly the coordinates it takes — so a tumour boundary drawn on the H&E could be carried onto the IHC rather than redrawn. Untested here, and it needs only two serial slides to try.
Open questions
- The tumour/necrosis annotation protocol is still a 0.9 draft — what is needed to finalise it?
- For region-level agreement, which overlap metric will be used (Dice, IoU, tolerance band)? Not decided. [unverified]
- Is there a script that validates GeoJSON filenames against the convention? A five-line check at export time would prevent unusable annotation batches.