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..70a2c8c --- /dev/null +++ b/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 + + + + +## 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