Document Zeiss CZI

For openslide/openslide#396.

Co-authored-by: Wei Chen <[email protected]>
Signed-off-by: Benjamin Gilbert <[email protected]>

_includes/links.md

@@ -38,6 +38,7 @@
 [format-sakura]: /formats/sakura/
 [format-trestle]: /formats/trestle/
 [format-ventana]: /formats/ventana/
+[format-zeiss]: /formats/zeiss/
 
 [announce-subscribe]: https://lists.andrew.cmu.edu/mailman/listinfo/openslide-announce/
 [users-subscribe]: https://lists.andrew.cmu.edu/mailman/listinfo/openslide-users/

formats/index.md

@@ -141,6 +141,20 @@ More info
 : [Ventana format][format-ventana]
 
 
+## Zeiss
+
+Single-file binary format with overlaps, often using JPEG XR compression.
+
+File extensions
+: `.czi`
+
+OpenSlide vendor backend
+: `zeiss`
+
+More info
+: [Zeiss format][format-zeiss]
+
+
 ## Generic tiled TIFF
 
 Single-file pyramidal tiled TIFF.

formats/zeiss/index.md

@@ -0,0 +1,101 @@
+---
+title: Zeiss format
+permalink: /formats/zeiss/
+---
+
+Format
+: single-file binary format
+
+File extensions
+: `.czi`
+
+OpenSlide vendor backend
+: `zeiss`
+
+
+## Detection
+
+OpenSlide will detect a file as Zeiss if:
+
+ 1. The file is not a TIFF.
+ 2. The file has at least 32 bytes and starts with `ZISRAWFILE`.
+
+
+## CZI format
+
+CZI slides consist of overlapping subblocks (image tiles) at arbitrary pixel
+positions.  Subblocks in level 0 are typically large, e.g. 2056 x 2464
+pixels.  A slide may or may not include downsampled levels.  Slides may
+include multiple scenes (scan regions), whose pyramids can have different
+numbers of downsampled levels.  Scenes are reflected in the metadata but
+aren't very important for rendering the slide, since subblock positions are
+relative to the slide and not the scene.
+
+Slides have an array of subblock directory entries, which contain the
+subblock's dimensions, pixel format, compression type, and a pointer to a
+segment containing XML metadata and an image tile.  A dimension represents
+coordinates along an axis; it contains a short string identifying the
+dimension, an offset, and for some dimensions, a size in level 0 and in the
+subblock's level.  Possible dimensions are "`X`" and "`Y`" pixel
+coordinates, a scene identifier "`S`", a channel identifier "`C`" (with
+value 0 for brightfield), and the tile's Z-index "`M`".  Higher Z-indexes
+should be rendered after lower Z-indexes.  `X` offsets are negative.  The
+downsample of a subblock can be computed by dividing its `X` or `Y` size in
+level 0 by its size in the subblock's level.
+
+Subblocks may be compressed in any of several formats.  JPEG XR is common.
+Uncompressed 24 bpp or 48 bpp pixel data is also possible, as well as pixel
+data compressed with lossless [Zstandard][zstd] compression.  The format
+also permits JPEG and LZW compression, though these do not appear to be
+common and OpenSlide does not support them.
+
+CZI files can embed arbitrary named attachments, which might be JPEG images,
+nested CZI files, or other metadata.  The `Label` and `SlidePreview`
+attachments are stored as nested CZIs with one subblock of uncompressed
+pixel data, 24 bpp and 48 bpp respectively.  The `Thumbnail` attachment is
+stored as a JPEG.
+
+CZI also includes a large XML document containing scan parameters for the
+slide.
+
+[zstd]: https://facebook.github.io/zstd/
+
+## Associated Images
+
+`label`
+: the `Label` attachment (optional)
+
+`macro`
+: the `SlidePreview` attachment (optional)
+
+`thumbnail`
+: the `Thumbnail` attachment (optional)
+
+
+## Known Properties
+
+Certain text nodes and attributes from the XML metadata are represented as
+properties prefixed with "`zeiss.`".  The available properties are those
+from the `AttachmentInfos`, `DisplaySetting`, `Information`, and `Scaling`
+elements of `ImageDocument.Metadata`.
+
+`openslide.mpp-x`
+: calculated as 1000000 times `zeiss.Scaling.Items.X.Value`
+
+`openslide.mpp-y`
+: calculated as 1000000 times `zeiss.Scaling.Items.Y.Value`
+
+`openslide.objective-power`
+: normalized `zeiss.Information.Instrument.Objectives.$objective.NominalMagnification`
+where the value of `$objective` is obtained from
+`zeiss.Information.Image.ObjectiveSettings.ObjectiveRef.Id`
+
+
+## Test Data
+
+<https://openslide.cs.cmu.edu/download/openslide-testdata/Zeiss/>
+
+
+## ImHex Patterns
+
+- [CZI file](https://github.com/openslide/openslide/blob/main/misc/imhex/zeiss-czi.hexpat)

index.md

@@ -52,6 +52,7 @@ The library can read virtual slides in the following formats:
  * [Sakura (.svslide)][format-sakura]
  * [Trestle (.tif)][format-trestle]
  * [Ventana (.bif, .tif)][format-ventana]
+ * [Zeiss (.czi)][format-zeiss]
  * [Generic tiled TIFF (.tif)][format-generic-tiff]
 
 It provides a simple C interface for programmers to use to decode