From b00557e1cb6e425269a2a7aecd5839ab8692dd02 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Fri, 29 Mar 2024 00:08:43 +0900 Subject: [PATCH] Document Zeiss CZI For https://github.com/openslide/openslide/pull/396. Co-authored-by: Wei Chen Signed-off-by: Wei Chen Signed-off-by: Benjamin Gilbert --- _includes/links.md | 1 + formats/index.md | 14 +++++ formats/zeiss/index.md | 117 +++++++++++++++++++++++++++++++++++++++++ index.md | 1 + 4 files changed, 133 insertions(+) create mode 100644 formats/zeiss/index.md diff --git a/_includes/links.md b/_includes/links.md index dbff556..7bccfd1 100644 --- a/_includes/links.md +++ b/_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/ diff --git a/formats/index.md b/formats/index.md index d350ea7..76c3741 100644 --- a/formats/index.md +++ b/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. diff --git a/formats/zeiss/index.md b/formats/zeiss/index.md new file mode 100644 index 0000000..b025d90 --- /dev/null +++ b/formats/zeiss/index.md @@ -0,0 +1,117 @@ +--- +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 image tiles at arbitrary pixel positions. +Tiles 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 tile positions are relative to the slide and not +the scene. + +The storage unit for an image tile is the subblock. A subblock contains +pixel data, a small piece of XML metadata (which is ignored by OpenSlide), +and a directory entry containing the subblock's dimensions, pixel format, +and compression type. Directory entries are stored alongside individual +subblocks, and a second copy of each entry is stored in an array whose +location is recorded in the file header. + +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. 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. + +Pixel data 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 and 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/ + + +### Gamma values + +Color images generated by at least Axioscan 7 scanners seem not to be gamma +corrected before storage, and appear dark. The +`zeiss.Information.Instrument.Detectors.$camera_id.GammaDefault` property +(where `$camera_id` can be read from +`zeiss.Information.Image.Dimensions.Channels.Channel:0.DetectorSettings.Detector.Id`) +might be the recommended gamma correction for displaying CZI images. +Observed values include 0.45 for Axiocam705c and AxioCamEL color cameras and +1 for Axiocam712m monochrome cameras. + + +## 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 + + + + +## ImHex Patterns + +- [CZI file](https://github.com/openslide/openslide/blob/main/misc/imhex/zeiss-czi.hexpat) diff --git a/index.md b/index.md index b9bf37e..c1d6809 100644 --- a/index.md +++ b/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