Patoloji Atlası’nda yayımlanan bütün slayt görüntülerini (whole slide image) QuPath içinden tarayıp doğrudan açmanızı sağlayan açık kaynaklı bir eklenti. Slaytlar HTTP üzerinden karo karo aktarılır; önceden indirmeniz gereken bir dosya yoktur.
Eklenti QuPath’e bir Deep Zoom (DZI) görüntü okuyucusu ile atlasın kendi görüntü listesinden beslenen aranabilir bir katalog ekler. Böylece slaytlar üzerinde QuPath’in tüm ölçüm, anotasyon ve analiz araçlarını kullanabilirsiniz.
Kısaca neler yapabilirsiniz: kategoriye göre slayt tarama, seçtiğiniz vakalardan ders/seminer/sınav için taşınabilir QuPath projesi oluşturma, kendi kendine çalışma sınavları hazırlayıp çözme, bir vakanın tüm boyalarını eşzamanlı karşılaştırma, kendi slaytınızın yanında atlastan referans slayt açma, koleksiyon ve favori kaydetme, katalog kapsam/QC panosu ve slayt alıntılama (BibTeX / RIS).
Gereksinim: QuPath 0.6 veya üzeri ve çalışma anında internet bağlantısı.
Kurulum (özet): QuPath’te Extensions → Manage extension catalogs → Add yolunu izleyip https://github.com/sbalci/patolojiatlasi-QuPath adresini ekleyin, ardından Extensions → Manage extensions altından eklentiyi Install edip QuPath’i yeniden başlatın. Ayrıntılı adımlar ve elle kurulum için aşağıdaki Install bölümüne bakın.
Aşağıdaki belgeler eklentinin deposundaki README dosyasıyla otomatik olarak eşitlenir; bu nedenle İngilizcedir. Menü ve düğme adları eklentideki hâliyle, yani Türkçe verilmiştir.
H.1 Belgeler (İngilizce)
H.2 About
The Patoloji Atlası is a whole-slide image teaching collection curated by pathologists and published openly on the web. This extension brings that same collection into QuPath so the slides can be browsed and opened for study and analysis without leaving the application. An About button in the browser window (and the extension’s entry in QuPath’s extension manager) links back to these sites:
Adds Extensions → Patoloji Atlası → Slaytlara gözat…, opening a searchable window that lists every image grouped by category (Gastrointestinal, Pancreatobiliary, Neuropathology, …), with a thumbnail preview and a Published only filter.
Each entry is a single stain of a case, so multi-stain cases (H&E plus IHC / special stains such as Warthin-Starry, Giemsa, CISH, PAS…) each appear as their own openable image.
Double-click an image (or select it and press Open in QuPath) to open it.
With a project open, the slide is added to the project and opened as an entry, so your annotations, detections and measurements are saved with the project.
With no project open, it opens in the current viewer for read-only viewing.
Curate a project from several images. Use Add to selection (button or the tree right-click menu) to build up a set as you browse and search — the selection persists across searches and Refresh list. Then Create project… opens a dialog where you review the set and either create a new project on disk or add the selection to the current project. Because slides stream from URLs, the resulting project is tiny and portable — hand the project folder to students (they need this extension installed) to run a course, seminar, or exam set.
Refresh list pulls the latest lists/list.yaml live from the patolojiatlasi/patolojiatlasi.github.io repository, so new cases appear without updating the extension. A snapshot of the list (288 images) is bundled so the browser works offline out of the box.
Registers .dzi URLs as an openable image type, so File → Open URI… with any https://images.patolojiatlasi.com/<case>/<stain>.dzi link works too.
H.4 Quiz (self-study)
Extensions → Patoloji Atlası → Sınav / Quiz → Hazırla… and Extensions → Patoloji Atlası → Sınav / Quiz → Çöz… turn atlas slides into a self-study quiz — no project and no server required. Four question types are supported:
Multiple-choice — a prompt with several options, one marked correct.
Free-text — a prompt with a model answer to compare your own notes against.
Annotation task — a prompt that asks you to mark or outline a feature on the slide (e.g. “mark every mitosis”); you draw with QuPath’s normal annotation tools, then click Göster to overlay the instructor’s reference annotation on the slide and compare by eye.
Guided navigation (“find it”) — a prompt that asks you to navigate to a region (e.g. “find the area of highest mitotic activity”); pan/zoom there yourself, then click Göster to overlay the target region and recentre the viewer on it.
Author (Sınav / Quiz → Hazırla…) — with an atlas slide open, add a question of any of the four types; each question is bound to the slide that was open when you added it (its DZI URL is stored with the question), so one pack can span several slides. For an annotation or navigation question, draw and select the reference region on the slide yourself, then click Referansı slayttan al to capture its shape as the question’s reference (annotation) or target (navigation) geometry. Save the finished set as a quiz-pack JSON.
Take (Sınav / Quiz → Çöz…) — load a quiz-pack and work through its questions in order; each question opens its slide, you answer it — pick an option, type notes, draw an outline, or navigate to a region — then click Göster to reveal the correct MCQ option, the free-text model answer, or, for annotation/navigation questions, an overlay of the reference/target region drawn directly on the slide.
This is self-study: there is no auto-grading — Göster only overlays the reference for a visual self-compare, nothing is scored. Nothing is saved anywhere either: the quiz-pack is a single portable file you’re free to email or hand out, and anything you draw while answering an annotation or navigation question is transient — it’s cleared again as soon as you move to the next/previous question or close the window, so it never ends up saved in the project.
H.5 Compare a case’s stains
Extensions → Patoloji Atlası → Karşılaştır → Bu vakanın boyalarını karşılaştır… opens every stain of the case shown in the active viewer — H&E plus any IHC / special stains — into QuPath’s native multi-viewer grid, with pan/zoom linked across all of them (QuPath’s built-in synchronize viewers behavior), so you can scroll one panel and have the others follow to the same field. The grid size (1×2 up to 2×3) is picked to fit the number of stains; cases with more than six stains only show the first six. If the active viewer isn’t showing a cataloged atlas slide, or the slide’s case has no other stains, you get a message instead of a grid.
Extensions → Patoloji Atlası → Karşılaştır → Tek görünüme dön turns synchronization off and collapses the grid back to a single viewer, closing the other panels (prompting to save first if any of them have unsaved edits, exactly like QuPath’s own close-viewer action).
H.6 Bench-side reference
Open an atlas case in a second viewer beside your own slide — handy for comparing your own case against a known reference while you work, without losing what’s already open. Two ways to launch it:
Browser right-click — in Slaytlara gözat…, right-click a case and choose Referans olarak yanında aç.
Extensions → Patoloji Atlası → Referans → Referans slayt aç… — a search-and-pick dialog (filter by title, organ, or stain) with a Yanında aç button (or double-click a row).
Either way, the reference slide streams into a new viewer added next to your active one; if nothing is open yet, it opens directly into that single viewer instead (there’s nothing to be “beside” yet). When both slides carry a known pixel size (µm/px), the reference viewer’s zoom is matched automatically to show the same on-screen scale as yours. A small floating Referans window appears alongside it with:
Büyütmeyi eşle — re-match magnification on demand.
Kaydırmayı da eşle (tam senkron) — toggle full pan/zoom sync between the two viewers (QuPath’s built-in synchronize-viewers behavior).
Referansı kapat — closes the reference viewer (prompting to save first if it has unsaved edits) and collapses the grid back to a single viewer.
H.7 Related-content navigator
Extensions → Patoloji Atlası → İlgili içerik… opens a companion window that, for the atlas slide currently open in the active viewer, shows two thumbnail filmstrips:
Bu vakanın diğer boyaları — the same case’s other stains (H&E plus any IHC / special stains), captioned by stain name.
Aynı kategoriden vakalar — other cases from the same category, one representative thumbnail per case (its H&E stain if it has one, otherwise its first stain).
The window auto-follows the active viewer — switch slides, open a different one, or close it, and both strips rebuild for whatever’s now open, with no need to reopen the window. If the active viewer isn’t showing a cataloged atlas slide, it shows a hint instead of strips. A Yenile button rebuilds on demand.
Click a thumbnail to swap the active viewer to that slide. Because QuPathViewer.setImageData bypasses QuPath’s own save prompt, the navigator checks first: if the slide you’re leaving has unsaved changes, you’re asked to confirm before it’s replaced.
The swap targets the active viewer. If you have a Case-Compare grid open, only the active panel changes — use the navigator with a single viewer for the intended jump-to-related experience.
H.8 Collections & favorites
Build a selection in the browser (right-click a slide → Add to selection, or the Add to selection button), then:
Koleksiyonu kaydet… writes the current selection to a small, shareable .json file — send it to a colleague, or keep it as your own case list. Refuses (with a status hint) if the selection is empty.
Koleksiyon yükle… opens a .json collection and re-resolves each entry against the currently-loaded catalog, adding whatever matches into the selection basket. The status line reports how many slides loaded and how many are no longer in the catalog (e.g. renamed or removed since the file was saved) — that part is safely ignored rather than failing the whole load.
Right-click a slide → ★ Favori (aç/kapat) to mark or unmark it as a favorite. Favorited slides show a ★ prefix in the tree. Favorites persist automatically to ~/QuPath-atlas-collections/favorites.json, independent of any saved collection file.
Favorileri yükle adds every currently-catalogued favorite into the selection basket.
Collections are portable: the .json file only needs the slide’s DZI URL plus a bit of display metadata, so it resolves correctly even against a refreshed catalog — share it with a colleague running the same extension.
H.9 Requirements
QuPath 0.6.x (built against the 0.6 API; runs on Java 21).
Internet access at runtime (slides stream from images.patolojiatlasi.com).
H.10 Install
Two ways to install, both needing only QuPath 0.6 or newer. Method A is recommended — you add the catalog once and QuPath installs the extension and offers future updates for you. Method B is a one-time manual download if you’d rather not add a catalog.
Method A — add the catalog to QuPath (recommended)
You add the catalog once; afterwards QuPath installs and updates the extension from it.
In QuPath, open Extensions → Manage extension catalogs.
Click Add, paste this repository URL, and confirm:
https://github.com/sbalci/patolojiatlasi-QuPath
QuPath finds the catalog.json in the repository for you.
Open Extensions → Manage extensions. Under the catalog you just added you’ll see QuPath Patoloji Atlası extension — click Install. QuPath downloads the matching release JAR for you (no manual file handling).
When prompted, restart QuPath. After it reopens, the extension lives under Extensions → Patoloji Atlası (start with Slaytlara gözat… to browse the slides).
Updating later. When a newer version is released, open Extensions → Manage extensions again and click Update next to the extension. If the update doesn’t seem to take effect, fully quit and reopen QuPath — QuPath re-reads the catalog and loads the new JAR on the next launch.
Method B — download the JAR from Releases (manual)
Go to the latest release and download the attached qupath-extension-atlas-<version>.jar (under Assets).
Start QuPath 0.6+.
Drag the .jar onto the QuPath window and confirm when asked to install it. (Alternatively, copy it into QuPath’s extensions directory: Extensions → Installed extensions → open extensions directory, drop the JAR there.)
Restart QuPath when prompted. The extension then appears under Extensions → Patoloji Atlası → Slaytlara gözat….
To update with Method B, download the newer JAR and repeat — replace the old JAR in the extensions directory (or just drag the new one on and let QuPath overwrite it).
H.11 Build (optional)
Pre-built JARs are attached to every GitHub release, so most users never need to build. To build from source (JDK 21 required):
./gradlew build # macOS / Linuxgradlew.bat build # Windows
The extension jar is written to build/libs/qupath-extension-atlas-<version>.jar. QuPath’s own APIs are resolved from the SciJava Maven repository at build time, so an internet connection is needed for the first build.
H.12 Notes & limitations
Pixel-size calibration.vips dzsave does not store microns-per-pixel in the DZI, so a slide opens uncalibrated (measurements in pixels) unless a pixel size is supplied. Three ways to supply it, in order of precedence: (1) a per-image "mpp" field in the catalog, (2) a catalog-wide "defaultMpp" (see Regenerating the bundled snapshot below) — both are applied automatically on open (and enable QuPath’s scale bar); (3) manually per slide after opening (Image tab → Set pixel size), or baked into a URL as …/HE.dzi?mpp=0.25. No pixel size is imposed by default, so a wrong calibration is never applied silently.
Image type is set on open when recognised. H&E → Brightfield (H&E) and a known special/histochemical stain → Brightfield (other), so color deconvolution works without setting it by hand. Any other stain (including IHC markers) is left unset — the extension only assigns a type it is confident about and never guesses IHC/DAB; set those in the Image tab.
Streaming, not downloaded. Tiles are fetched on demand into QuPath’s tile cache; a live connection is needed while panning into new regions.
Category coverage depends on the list metadata. Images are grouped from the speciality and organEN fields, falling back to the title/slug. Entries whose list record has none of these (currently a fair number, many with blank titles) land under Uncategorized — filling in organEN/titleEN in list.yaml will automatically improve grouping on the next refresh.
Respecting the source. The images belong to patolojiatlasi.com; this tool is for viewing and study. Avoid bulk-downloading the tile pyramids.
H.13 Focus heatmap
Extensions → Araştırma → Odak ısı haritası adds a dwell/attention heatmap that records where you look on a slide. This lives in the “Araştırma” menu (a top-level sibling of “Patoloji Atlası” in Extensions), together with image rotation and the “flag any project” action below — these tools are atlas-independent and work on any open slide, not just ones opened from the atlas catalogue. While tracking is on, the active viewer’s visible region is sampled a few times a second and accumulated into a per-slide grid shown as a translucent overlay — focused high-magnification viewing heats an area far faster than a zoomed-out browse, so the map doubles as a “did I review the whole slide?” check and as a way to study where readers focus.
Menu items:
Slayt üzerinde göster (ısı katmanı) — toggle the translucent heatmap overlay on the active viewer.
Ayrı pencerede göster — toggle a separate floating window showing the same heatmap.
Temizle — reset the current slide’s map.
Kaydet… — save the current map now to a folder you pick.
Araştırmaya katkıda bulun… — save an anonymised contribution (no user name; a random session id + stable slide key + date) under ~/QuPath-atlas-focus-maps/contributions/, for the planned per-slide crowd attention map. Uploading is disabled until the atlas website has a receiver — until then the file is only written locally and can be shared manually.
Oturumdan sonra sakla (kalıcı) — when off (default), maps live only for the session and are discarded; when on, each slide’s map is auto-saved (on slide change, close, or stopping) to ~/QuPath-atlas-focus-maps/ so it can be analysed later.
Gezinme kaydı (araştırma) — sessizce kaydeder, ısı haritası gösterilmez — the blinded-recording toggle; see Blinded research recording below.
Each saved map is a <slide>__<user>__<timestamp>.json (plus a .png preview). The JSON carries the slide name/URI, the user (OS login), image and grid dimensions, sample count, and the row-major grid of dwell values — enough to aggregate focus across readers offline. The plan for pooling contributions into a website overlay is in docs/focus-aggregation-plan.md.
Blinded research recording
For studies that need real, unbiased dwell-time data — where seeing a live heatmap of your own viewing could change how you look — the same focus tracker has a blinded mode: it silently records which regions of the slide you looked at and for how long, with no overlay, no window, and no on-screen indication of any kind while it’s active. It can’t be toggled visible; the Slayt üzerinde göster (ısı katmanı) / Ayrı pencerede göster / Temizle / Kaydet… / Araştırmaya katkıda bulun… menu items are all disabled for the duration, so a session can’t accidentally surface a heatmap or leak one to a file.
You can turn it on for a single session from Extensions → Araştırma → Odak ısı haritası → Gezinme kaydı (araştırma), or make it the default for an entire study. There are two ways to do that:
Building a project from the atlas browser: check “Araştırma projesi — gezinme kaydı (blinded)” in the Create project dialog.
Any other project — local slides, a server/PACS project, or one you already have open:Extensions → Araştırma → Mevcut projeyi araştırma projesi yap (gezinme kaydı)… flags the currently open project in one click, no atlas involvement required. This is the same sidecar mechanism, so it’s how a researcher sets up a double-blind spatial/temporal/directional viewing study on their own SVS files.
Either way, this writes a small atlas-research.json sidecar next to the project’s .qpproj file; every time the project is opened afterwards, blinded recording starts automatically — after a one-time consent notice explaining that anonymised viewing data (regions viewed + dwell time, no identity) is being recorded for research. (The “flag current project” action asks for that same consent immediately, since you’re opting in right there, and starts recording at once rather than waiting for the next reopen.) Declining leaves recording off and the notice reappears next time the project opens; accepting is remembered so later sessions start recording immediately, no re-prompt.
Where the data goes. When a project is open, every blinded write for that session goes into <project>/atlas-focus/ (captured once when recording starts, so a later project switch can’t misattribute a still-finishing session); with no project open it falls back to ~/QuPath-atlas-focus-maps/contributions/. While recording, the current slide’s map is checkpointed to a session-<id>.partial.json file roughly every 30 seconds, so a crash or force-quit loses at most that much data — not the whole session. Switching slides or stopping promotes the checkpoint into a final per-slide JSON fragment and removes the .partial.json. Closing or switching away from the project stops recording, writes the last slide’s fragment, and bundles every fragment from the session into a single atlas-focus_<timestamp>_<session>.zip in the project folder (or the fallback dir) — that one zip is what you hand to the study coordinator. Every artifact in this pipeline (checkpoint, fragment, zip) is JSON-only and anonymised: no PNG, no username, ever.
Running a study? See SHARING.md for the end-to-end guide to preparing a blinded-research project, packaging it (with the extension) for researchers, the consent / observer-effect tradeoff, and getting the data back — and analysis/ for the Python/R analysis toolkits.
H.14 Coverage & QC dashboard
Extensions → Patoloji Atlası → Katalog kapsamı ve QC… opens a read-only category x stain matrix computed from the bundled catalogue snapshot — for every category, how many slides and distinct cases fall into each of the four stain buckets (H&E / IHC / special stain / other), plus per-category published% and mpp-known% (pixel-size calibration coverage). A bold TOTAL strip under the table sums the whole catalogue.
Bağlantıları denetle — an opt-in, best-effort reachability check of every distinct DZI URL in the catalogue (a HEAD request per URL, run off the UI thread with a progress bar). Any unreachable slide is listed by title and URL underneath — nothing is checked automatically, since this makes a batch of network calls.
Drill down. Double-click a category row to seed the project builder (the same dialog the browser’s selection basket uses) with every case in that category, ready to review and turn into a project.
Export. Copy or save the matrix as CSV or Markdown — handy for pasting a data-availability statement or tracking catalogue gaps over time.
The classification (which stain bucket a slide falls into) is keyword-based, so the Diğer (“other”) / Uncategorized buckets are honest catch-alls rather than a guarantee of correctness — see stainBucket()/normalizeCategory() if you need to extend the keyword lists.
H.15 Provenance & citation
Beyond citing the extension itself (see Citation below), the atlas menu can generate ready-to-use citations and export files for the slides you actually used — image + extension + QuPath references together, so a figure or methods section always carries full provenance.
Cite a slide. Right-click a case in Slaytlara gözat… and choose Bu slaytı alıntıla…, or use Extensions → Patoloji Atlası → Atıf → Açık slaytı alıntıla… with the slide open in the active viewer. Produces BibTeX / RIS / plain-text citations for the atlas image, this extension, and QuPath (Bankhead et al. 2017), with copy-to-clipboard and save-to-file actions.
Export a cohort manifest. In the project-builder dialog (from the browser’s selection basket), click Künye / manifest dışa aktar… and pick a folder — writes atlas-manifest.csv, atlas-manifest.md, and atlas-methods.txt for every slide in the current selection. This does not create a project; it only records provenance for the slides you’ve gathered.
Cite a region. Select an annotation on an open atlas slide, then use Extensions → Patoloji Atlası → Atıf → Bu bölgeyi alıntıla…. Produces a figure-citation card — the slide citation, the viewport framing (downsample + center), an editable caption, and the region’s geometry as GeoJSON — with the same copy/save actions.
All three add a best-effort catalogue commit SHA (from a lightweight, unauthenticated GitHub API call) and this extension’s version to the exported provenance, without blocking the UI while that network lookup runs.
H.16 Citation
If you use this software, please cite it — GitHub renders a “Cite this repository” button from CITATION.cff. The archive is on Zenodo under a concept DOI that always resolves to the latest release (cite this — it stays the same across versions):