QuPath Patoloji Atlası Extension

A QuPath 0.6+ extension that streams the public Patoloji Atlası slides into QuPath as Deep Zoom pyramids with nothing to download — and which quietly contains a full instrument for blinded observer studies, including ICC agreement analysis in both R and Python.

Purpose

Two things, and the second is easy to miss.

A DZI image server for QuPath. The atlas publishes its slides as Deep Zoom pyramids produced by vips dzsave and displayed on the web with OpenSeadragon — the pipeline described on DZI Web Publication. This extension adds DziImageServer and DziImageServerBuilder, so QuPath can open those same pyramids directly over HTTP, tile by tile, without downloading a slide first. Alongside it sits a browsable catalogue (AtlasBrowser, AtlasCatalog, AtlasCase, AtlasCollection, Favorites, CaseCompare) driven by the atlas’s own image list.

That closes a loop this wiki previously documented only one half of. Pathology Atlas Pipeline converts a scanner file into published DZI tiles; this reads those same tiles back into a full analysis application. The teaching artefact and the research substrate become the same object, which is a better outcome than either publishing or archiving alone.

A blinded-observer-study instrument. The focus/ package — BlindedStore, DecisionDialog, FocusHeatmap — records where a reader actually looked and what they decided, under blinding. It ships with a matching analysis toolkit in both languages: analysis/python/blinded_focus/{analyze,metrics,figures,io}.py and analysis/R/blinded_focus.R, deliberately mirroring each other function for function. See below; this is the part with research value beyond the atlas itself.

Data used

None of its own, and no patient data anywhere. It reads the public atlas catalogue over HTTP. Study output is reader-behaviour data — dwell grids, navigation paths, zoom levels, decisions — which concerns the reader, not the patient.

CoverageStats computes a QC matrix over the catalogue: category × stain type (H&E, IHC, special, other), with slide and case counts, published_pct and mpp_known_pct. That last column is the interesting one — it tracks what fraction of published atlas slides have a known µm/px, which is precisely the property DZI Web Publication argues separates a measurable image from a picture. (Despite the name, this is catalogue coverage and has nothing to do with the sampling problem on Coverage Bias.)

Methods

55 Java classes, Gradle, QuPath 0.6+. MIT licensed, and the LICENSE is the canonical MIT text — verified, and worth stating because the group’s other two QuPath extensions are not in that position (see QuPath Atölye Extension).

The release engineering is the most complete in the estate:

• One published release, v0.1.0 (2026-07-19), with the JAR attached.
• catalog.json advertises that JAR and the URL resolves — HTTP 200, checked 2026-07-26.
• A GitHub Actions build workflow with a status badge.
• CITATION.cff and .zenodo.json, and a Zenodo DOI that resolves: 10.5281/zenodo.21443833.
• Bilingual SHARING.md / SHARING.tr.md.

The blinded-focus toolkit, which is the research-relevant part

What it measures, read from metrics.py and blinded_focus.R:

• Where readers look — dwell grids normalised by max or sum, coverage, entropy, center_of_mass, top_hotspots, count_hotspots.
• How readers navigate — fixation detection by I-DT, path linearity over sub-paths, idle-gap handling, zoom behaviour including a “magnification percentage” measure attributed to Ghezloo.
• How similar two readers are — correlation coefficient, similarity, KL divergence, Jensen–Shannon divergence, nss, auc_judd, iou, and precision/recall at top-K against a reference or ROI.
• Formal agreement — the R side computes mean pairwise correlation and ICC(2,1) via irr::icc.

So this is a saliency-and-agreement instrument for reading behaviour, not merely a viewer. The two implementations are written to mirror each other exactly, with the R docstrings repeatedly noting which Python function each mirrors — a deliberate cross-language check that is unusual and worth copying.

Verdict written back after evaluating an alternative, 2026-07-26. MouseTracks — a maintained, actively released desktop input-heatmap tool — was read against this package and rejected. Two structural reasons, both of which this package satisfies precisely because it runs inside the viewer: it records screen pixels with no access to the viewport transform, so it has no concept of slide coordinates or magnification; and it stores a per-pixel last-visit stamp rather than a sequence, so revisits are lost and fixation or path analysis is impossible. It also computes no saliency or agreement statistics at all. Nothing in it is worth lifting — the density surface it builds is six lines of numpy.

The one thing it does that this package structurally cannot is whole-desktop, cross-application capture: how a pathologist’s time divides across QuPath, the LIS, the PACS viewer and email. That is a workload question rather than a slide-reading one. So this remains the right instrument for reading behaviour, and the gap it leaves is a different question rather than a weakness. The generalisable test that decision produced is on Reading-Behaviour Capture — check it before evaluating any future tool, because both properties are invisible in a feature list.

The Pathology-CoT engine, added 2026-07-27 — and it closes a loop this wiki opened

Eleven commits on a single day added a pathologycot/ package: PathologyCotDiscretizer, Behavior, CotFragment, PathologyCotDraft, PathologyCotExport, PathologyCotIO and PathologyCotActions, each with a unit test, plus an Araştırma → Pathology-CoT menu. It turns recorded viewing sessions into a six-stage pipeline that discretises behaviour into inspect-versus-peek events, assembles them into a reviewable “tour”, and exports a case folder of image crops with a conversation.json.

This is the group building what this wiki recommended, one day after recommending it. Pathology-CoT was evaluated and not adopted — no licence, a fraction of the advertised dataset, and bound to one viewer’s logs — with the verdict that its behaviour discretisation thresholds were the one thing worth reimplementing. The commit messages describe exactly that: a clean-room reimplementation, deliberately not derived from the unlicensed upstream, sitting inside the group’s own viewer where slide coordinates and magnification are available. That is also the reference-not-copy rule from Digital Pathology Drafts applied without being asked.

The bug fixes in the same series are worth recording because they are the errors this kind of pipeline actually makes: an idle-gap boundary point misattributed in the discretise loop, a peek-versus-inspect mislabel, a conversation.json referencing crops the exporter never wrote, and — the one that matters most — a diagnosis-extraction leak. That last is a train/test leakage class of problem in a behavioural dataset, and catching it before the data existed is better than discovering it in a model.

This makes the extension the second half of a pair: the focus/ package measures where readers look, and pathologycot/ turns that into a structured record a model could learn from. See Agentic Slide Navigation for why recorded expert behaviour is the scarce input, and Reading-Behaviour Capture for the two properties that make such a record analysable at all — both of which this satisfies and the rejected alternative did not.

Current state / open questions

Created 2026-07-13 and pushed through 2026-07-27, so this is a young but fast-moving repository — the Pathology-CoT engine above landed in one day. 141 tracked files at review.

Nothing here is broken, which is worth saying plainly given what the sibling extensions turned up. Licence canonical, release published, catalog resolves, DOI live, CI configured. Of the three QuPath extensions the group publishes, this is the one whose packaging can be pointed at as the template for the others.

Open questions:

• Has the blinded-focus instrument actually been run with more than one reader, and on what material? Nothing in the repository records a completed study, so its metrics are implemented but not yet exercised. [unverified]
• The DZI reader depends on the atlas’s published tile layout. If Pathology Atlas Pipeline changes its vips dzsave parameters, does this reader break, and is there a test that would catch it?
• mpp_known_pct implies some published atlas slides lack a pixel size. What fraction, and can it be backfilled from the source files? That number bounds what analysis the atlas can support.
• Has the Pathology-CoT engine been run on a real session yet? The tests exercise the discretiser, but nothing in the repository records an exported case folder from an actual reading. The instrument and the recorder now both exist; what is missing is one session that goes end to end, which would also validate the thresholds the clean-room reimplementation had to choose for itself. [unverified]
• The discretisation thresholds were reimplemented rather than copied, so they are not guaranteed to match the published ones. If any comparison with the original paper’s results is intended, that difference has to be measured rather than assumed away.

Related: DZI Web Publication — the publishing half of the loop this extension closes; that page’s argument about µm/px is what mpp_known_pct measures.

Related: Pathology Atlas Pipeline — produces the DZI pyramids this consumes, and the page that holds the anonymisation gate protecting everything upstream of them.

Related: Patoloji Atlası — the teaching collection itself and its editorial contract.

Related: Interobserver Agreement — the blinded-focus toolkit is an instrument for exactly the studies that page discusses, and it measures a dimension that page does not yet cover: agreement in where readers look, not only in what they conclude.

Related: QuPath Atölye Extension — the sibling extension, and the contrast on licence and release hygiene.

Related: Pathology-CoT — the evaluated-and-rejected upstream whose one salvageable idea this extension reimplemented clean-room; read that page for what was deliberately not carried over.

Derived from: refreshed 2026-07-29 — git log --since=2026-07-26 and the changed-file list for the pathologycot/ package and its tests, plus docs/superpowers/plans/2026-07-26-pathology-cot-data-engine.md. Earlier reading, working tree read 2026-07-26 at commit 3bcf68c — README.md, LICENSE, CITATION.cff, .zenodo.json, catalog.json, build.gradle, src/main/java/com/patolojiatlasi/qupath/** including dzi/ and focus/, analysis/python/blinded_focus/*.py, analysis/R/blinded_focus.R, plus the GitHub REST API for releases and licence state and HTTP checks of the catalog asset and the Zenodo DOI.