DZI Web Publication
Getting a whole slide image onto the public web as a zoomable viewer — the tiling, hosting and anonymisation decisions between a scanner file and a teaching case anyone can open.
What it is
A WSI cannot be served to a browser as a file; it is gigabytes and no viewer will load it. The standard answer is to re-tile it into a Deep Zoom Image (DZI) pyramid — a .dzi XML descriptor plus a _files/ directory of small tiles at each zoom level — and point a JavaScript viewer, in practice OpenSeadragon, at the descriptor. The viewer requests only the tiles for the current view, so the client never downloads more than it displays.
The conversion is one command. In Pathology Atlas Pipeline it is vips dzsave <source> <output> --tile-size --depth --suffix, with tile size, pyramid depth and tile compression as the parameters that matter. Everything else on this page is the decisions around that command, which is where the actual work is.
The decisions that are not obvious
Tile format and size trade storage against latency. JPEG tiles at 254 px are the pipeline’s defaults. Larger tiles mean fewer requests but more wasted bytes per pan; lossy tiles mean a smaller pyramid but compression artefacts baked into what a reader sees. For teaching this is fine. For anything a measurement is taken from, it is a decision to state rather than inherit.
Hosting model. Pathology Atlas Pipeline puts one GitHub repository per case under an organisation, with a list.yaml catalogue in the atlas site repo as the index, and serves via GitHub Pages. That keeps each case independently versioned and cheap to host, at the cost of making any viewer improvement a fleet-wide operation — which is why that project carries two separate scripts that drive the GitHub API across every repo at once.
Anonymisation is part of publication, not a preceding step. This is the one that carries consequences. A DZI pyramid is generated from a source file, so whichever file is handed to dzsave is the file that gets published. If anonymisation is requested and fails, the only safe behaviour is to stop, because the alternative silently tiles the original — label image and all. See De-identification for what the label carries, and Pathology Atlas Pipeline for a worked example of both behaviours in one repository’s history.
The published pyramid outlives the decision. Tiles are static files on a public host. A mistake is not corrected by fixing the pipeline; it is corrected by deleting and regenerating everything already pushed. That asymmetry is the argument for failing closed.
Why it matters for my work
Patoloji Atlası is the group’s public Turkish teaching atlas and this is how its cases get online. That project deliberately keeps WSIs on the Memorial share and publishes only screenshots and annotated crops in the site repo — the DZI route is the exception where a whole slide genuinely does leave, in tiled form, which is precisely why the anonymisation gate on it matters more than anywhere else in the estate.
It is also the cheapest way to make a case interactive for teaching without buying a hosted platform, which is the comparison worth holding against sources/notes/dapa-digital-anatomic-pathology-academy.md — that resource solves the same problem behind a login, this one solves it with static files and no account.
Pitfalls, all observed rather than theoretical
Every item here comes from defects recorded in Pathology Atlas Pipeline’s own regression tests, and they share one shape: the pipeline reported success while shipping a broken or unsafe page.
- A viewer that renders blank. Slide or stain names written as bare JavaScript object keys break on any hyphen — and 64 of 143 production names were hyphenated. The page loads, the viewer is empty, the deploy reports success.
- Placeholder dimensions shipped live. Rewrites of the tile source URL, width and height matched only one quote style, so they silently no-opped and viewers went out pointing at the template’s example image at the template’s dimensions.
- Non-ASCII text breaking the generator. Turkish case notes passed through
re.subreplacements raise “bad escape” on a\usequence, or corrupt silently on a backslash. - Templating that eats its own syntax. Escaped braces emitted
```{r}instead of```{r}, so the bilingual Quarto mechanism rendered as literal text.
The generalisable lesson: for a static-site publication path there is no runtime to throw an error. The failure mode is a page that exists and is wrong, so validation has to be an explicit step that inspects the artefact, not an absence of exceptions.
How it connects
Pathology Atlas Pipeline — the implementation, and the source of every specific claim here.
Patoloji Atlası — the atlas these cases publish into, and its editorial rules about what may leave the share.
De-identification — the label image and metadata that must be gone before a pyramid is generated, since publication is irreversible in practice.
Whole Slide Imaging — the pyramid structure this exploits is the same one the source format already uses; DZI is a re-tiling for the web rather than a new idea.
Patch Extraction — the other reason to cut a slide into tiles, and a genuinely different one: those tiles feed a model and their size is chosen for what the network sees, these tiles feed a browser and their size is chosen for bandwidth. Easy to conflate, never interchangeable.
WSI Quality Control — worth running before publication for the same reason it runs before annotation: effort spent tiling an unusable slide is wasted twice, because the output is public.
Video-Based WSI Mosaicing — the other source of something to publish: a mosaic built from a microscope camera reaches this same tiling step, with no label image to strip but no recorded pixel size either.
Open questions
- Is there a validation step that opens a published viewer and confirms it renders, rather than confirming files were written? The recorded defects all passed a file-level check.
[unverified]A second, stricter reader now exists that could serve as that check. QuPath Patoloji Atlası Extension adds a DZI ImageServer to QuPath and opens the published pyramids over HTTP — so a slide that renders in OpenSeadragon and opens in QuPath has been read by two independent implementations. That is a much stronger signal than a file listing, and it is already built. - The loop is now closed in both directions, which changes what the published tiles are for. This page describes converting a scanner file into DZI for the web; QuPath Patoloji Atlası Extension reads those same pyramids back into a full analysis application, without downloading a slide. The consequence worth stating: the published atlas is no longer only a teaching artefact, it is also a research substrate — anyone with QuPath can annotate, measure and run analysis on it. That raises the value of getting the pixel-size question below right, and it is why that extension tracks
mpp_known_pctacross the catalogue as a QC metric. - What fraction of published atlas slides actually carry a known µm/px? The atlas extension computes exactly this (
mpp_known_pctin its coverage dashboard) but no value is recorded here. That number bounds what measurement the published atlas can support, per this page’s own argument that a pyramid without a pixel size is a picture rather than a measurement. - What tile size and compression are actually in use across the published atlas, and were they ever chosen deliberately?
[unverified] - Does anything verify a slide was anonymised after publication, as an audit rather than a gate? A gate that can be bypassed by unchecking a box is not an audit trail.