OPENSLIDE-FORMATS(3)

📦 version 3.4.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 openslide-formats — section 3, File Formats 💖

okay bestie, welcome to the glow-up of the file-formats reference page. this is openslide-formats from the manual, and it is literally the encyclopedia of every format OpenSlide fucks with. grab a strawberry drink, we're going in 🍓

🌸 NAME 🌸

openslide-formats — the reference of supported formats, periodt.

✨ DESCRIPTION ✨

(no notes here, this section is just a doorway. the real tea is right below 👇)

📋 LIST OF KNOWN PROPERTIES 📋

🫶 Properties generated by OpenSlide

  • openslide.background-color — the background color of the slide, handed to you as an RGB hex triplet. heads up: this property is not always present.
  • openslide.bounds-height — the height of the rectangle that bounds the non-empty region of the slide. and yeah, this property is not always present either.
  • openslide.bounds-width — the width of that same rectangle bounding the non-empty region of the slide. also not always present.
  • openslide.bounds-x — the X coordinate of the rectangle bounding the non-empty region of the slide. again: not always present.
  • openslide.bounds-y — the Y coordinate of the rectangle bounding the non-empty region of the slide. you already know: not always present.
  • openslide.comment — a free-form text comment. say whatever you want, it's a free-for-all ✍️
  • openslide.mpp-x — microns per pixel in the X dimension of level 0. may not be present, and may not even be accurate. it's giving trust issues.
  • openslide.mpp-y — microns per pixel in the Y dimension of level 0. same deal: may not be present or accurate.
  • openslide.objective-power — the magnification power of the objective. often inaccurate, sometimes just straight up missing 🙈
  • openslide.quickhash-1 — a non-cryptographic hash of a subset of the slide data. it can be used to uniquely identify a particular virtual slide, but it cannot be used to detect file corruption or modification. so cute but not a bodyguard.
  • openslide.vendor — the name of the vendor backend. the "who made u" property 💅

🧚 Properties for TIFF-based formats

  • tiff.Artist — the contents of the TIFF Artist tag.
  • tiff.Copyright — the contents of the TIFF Copyright tag.
  • tiff.DateTime — the contents of the TIFF DateTime tag.
  • tiff.DocumentName — the contents of the TIFF DocumentName tag.
  • tiff.HostComputer — the contents of the TIFF HostComputer tag.
  • tiff.ImageDescription — the contents of the TIFF ImageDescripton tag. (yes, that spelling is the spelling. leaving it exactly as it is, no cap.)
  • tiff.Make — the contents of the TIFF Make tag.
  • tiff.Model — the contents of the TIFF Model tag.
  • tiff.ResolutionUnit — the contents of the TIFF ResolutionUnit tag.
  • tiff.Software — the contents of the TIFF Software tag.
  • tiff.XPosition — the contents of the TIFF XPosition tag.
  • tiff.XResolution — the contents of the TIFF XResolution tag.
  • tiff.YPosition — the contents of the TIFF YPosition tag.
  • tiff.YResolution — the contents of the TIFF YResolution tag.

🌈 Vendor-specific properties

a whole list of vendor-specific properties lives on the pages for each vendor format[1]. go peek, iykyk.

🔬 APERIO FORMAT 🔬

  • Format — single-file pyramidal tiled TIFF, with non-standard metadata and compression
  • File extensions — .svs, .tif
  • OpenSlide vendor backend — aperio

📄 Vendor Documentation

http://www.aperio.com/documents/api/Aperio_Digital_Slides_and_Third-party_data_interchange.pdf

👀 Detection

Aperio slides are stored in single-file TIFF format. OpenSlide will detect a file as Aperio if:

  1. The file is TIFF.
  2. The initial image is tiled.
  3. The ImageDescription tag starts with Aperio.

🏷️ Relevant TIFF tags

  • ImageDescription — Stores some important key-value pairs and other information, see below
  • Compression — May be 33003 or 33005, which represent specific kinds of JPEG 2000 compression, see below

🕵️ Extra data stored in ImageDescription

For tiled images, the ImageDescription tag contains some dimensional downsample information as well as what look like offsets. Additionally, vertical line-delimited key-value pairs are stored, in at least the full-resolution image. A key-value pair is equals-delimited. These key-values are stored as properties starting with “aperio.”. Currently, OpenSlide does not use any of the information present in these key-value fields.

For stripped images, the ImageDescription tag may contain a name, followed by a carriage return. This is used for naming the associated images. The second image in the file does not have a name, though it is an associated image.

🗂️ TIFF Image Directory Organization

http://www.aperio.com/documents/api/Aperio_Digital_Slides_and_Third-party_data_interchange.pdf page 14:

The first image in an SVS file is always the baseline image (full resolution). This image is always tiled, usually with a tile size of 240x240 pixels. The second image is always a thumbnail, typically with dimensions of about 1024x768 pixels. Unlike the other slide images, the thumbnail image is always stripped. Following the thumbnail there may be one or more intermediate “pyramid” images. These are always compressed with the same type of compression as the baseline image, and have a tiled organization with the same tile size.

Optionally at the end of an SVS file there may be a slide label image, which is a low resolution picture taken of the slide’s label, and/or a macro camera image, which is a low resolution picture taken of the entire slide. The label and macro images are always stripped.

🌊 JPEG 2000 (compression types 33003 or 33005)

Some Aperio files use compression type 33003 or 33005. Images using this compression need to be decoded as a JPEG 2000 codestream. For 33003: YCbCr format, possibly with a chroma subsampling of 4:2:2. For 33005: RGB format. Note that the TIFF file may not encode the colorspace or subsampling parameters in the PhotometricInterpretation field, nor the YCbCrSubsampling field, even though the TIFF standard seems to require this. The correct subsampling can be found in the JPEG 2000 codestream.

🖼️ Associated Images

  • thumbnail — the second image in the file
  • label — optional, the name “label” is given in ImageDescription
  • macro — optional, the name “macro” is given in ImageDescription

💫 Known Properties

All key-value data encoded in the ImageDescription TIFF field is represented as properties prefixed with “aperio.”.

  • openslide.mpp-x — normalized aperio.MPP
  • openslide.mpp-y — normalized aperio.MPP
  • openslide.objective-power — normalized aperio.AppMag

🧪 Test Data

http://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/

🦋 HAMAMATSU FORMAT 🦋

  • Format — multi-file JPEG/NGR with proprietary metadata and index file formats, and single-file TIFF-like format with proprietary metadata
  • File extensions — .vms, .vmu, .ndpi
  • OpenSlide vendor backend — hamamatsu

👀 Detection

OpenSlide will detect a file as Hamamatsu if:

  1. The file given is a INI-style text file.
  2. It has a [Virtual Microscope Specimen] (VMS) or [Uncompressed Virtual Microscope Specimen] (VMU) group.
  3. If VMS, there are at least 1 row and 1 column of JPEG images (NoJpegColumns and NoJpegRows).

or if:

  1. The file has a TIFF directory structure.
  2. TIFF tag 65420 is present.

🌟 Overview

The Hamamatsu format has three variants. VMS and VMU consist of an index file, 2 or more image files, and (in the case of VMS) an “optimisation” file. NDPI consists of a single TIFF-like file with some custom TIFF tags. VMS and NDPI contain JPEG images; VMU contains NGR images (a custom uncompressed format).

Multiple focal planes are ignored, only focal plane 0 is read. (sorry bestie, plane 1 and up are getting ghosted 👻)

JPEG does not allow for files larger than 65535 pixels on a side. In VMS, multiple JPEG files are used to encode large images. To avoid having many files, VMS uses close to maximum size (65K by 65K) JPEG files. NDPI, instead, stuffs large levels into a single JPEG and sets the overflowed width/height fields to 0.

Unfortunately, JPEG provides very poor support for random-access decoding of parts of a file. To get around this, JPEG restart markers are placed at regular intervals, and these offsets are specified in the optimisation file (in VMS) or in a TIFF tag (in NDPI). With restart markers identified, OpenSlide can treat JPEG as a tiled format, where the height is the height of an MCU row, and the width is the number of MCUs per row divided by the restart marker interval times the width of an MCU. (This often leads to oddly-shaped and inefficient tiles of 4096x8, for example.)

Unfortunately, the VMS optimisation file does not give the location of every restart marker, only the ones found at the beginning of an MCU row. It also seems that the file ends early, and does not give the location of the restart marker at the last MCU row of the last image file.

Thus, the optimisation file can only be taken as a hint, and cannot be trusted. The entire set of JPEG files must be scanned for restart markers in order to facilitate random access. OpenSlide does this lazily as needed, and also in a background thread that runs only when OpenSlide is otherwise idle.

The VMS map file is a lower-resolution version of the other images, and can be used to make a 2-level JPEG pyramid. JPEG also allows for lower-resolution decoding, so further pyramid levels are synthesized from each JPEG file.

🗒️ VMS File

The .vms file is the main index file for the VMS format. It is a Windows INI-style key-value pair file, with sections. Only keys in the Virtual Microscope Specimen group are read by OpenSlide.

okay so here's the keys you'll actually see chillin' inside that file — and bestie, every single one matters, so I'm not skipping a single one 💅

  • NoLayers — the number of layers, and rn it literally has to be 1 or the whole thing just won't be accepted. one layer only, no negotiations 🙅‍♀️
  • NoJpegColumns — how many JPEG files go across, and this is handed to you in the ImageFile attributes
  • NoJpegRows — how many JPEG files go down, also given in the ImageFile attributes
  • ImageFile — semantically equivalent to ImageFile(0,0,0), though it's not actually specified that way. it's the image sitting at position (0,0,0) of the set of images ✨
  • ImageFile(x,y) — semantically equivalent to ImageFile(0,x,y), though again, not specified that way. it's the image at position (0,x,y) of the set of images
  • ImageFile(z,x,y) — here x and y are non-negative integers, and both x and y cannot be 0. z is a positive integer. these are the images that make up the virtual slide, as a concatenation of JPEG images. x and y say where each JPEG lives, and z says which focal plane it's on 🔍
  • MapFile — a lower-resolution version of all the ImageFiles
  • OptimisationFile — a file that specifies some of the restart marker offsets in each ImageFile
  • AuthCode — unknown 💀 nobody knows what this one does, we just vibe with it
  • SourceLens — apparently the objective power 👑
  • PhysicalWidth — width of the main image, in nm
  • PhysicalHeight — height of the main image, in nm
  • LayerSpacing — unknown 💀
  • MacroImage — the image file for the “macro” associated image
  • PhysicalMacroWidth — width of the macro image, in nm
  • PhysicalMacroHeight — height of the macro image, in nm, and sometimes it comes with a trailing semicolon. yes, a rogue semicolon. we deal 🙈
  • XOffsetFromSlideCentre — distance in X from the center of the entire slide (i.e., the macro image) to the center of the main image, in nm
  • YOffsetFromSlideCentre — distance in Y from the center of the entire slide to the center of the main image, in nm

🌸 VMU File 🌸

The .vmu file is the main index file for the VMU format — like, it's the one holding the whole thing together 🫶

Only keys in the Uncompressed Virtual Microscope Specimen group are read by OpenSlide. everything else in there? not our business, bestie 💜

Okay so, bestie, here's the tea on the keys that show up in that file — I'm listing every single one so you don't have to squint at a hex dump at 3am 💖

  • NoLayers — scroll up to the VMS bit, it's covered there
  • ImageFile — (same as VMS above, go peek)
  • ImageFile(x,y) — (yep, VMS above again)
  • ImageFile(z,x,y) — (VMS above, you know the drill)
  • MapFile — (VMS above 👆)
  • MapScale — lowkey seems to be the downsample factor of the map
  • AuthCode — (VMS above, bestie)
  • SourceLens — (VMS above, fr)
  • PixelWidth — the width of the image, in pixels ✨
  • PixelHeight — the height of the image, in pixels ✨
  • PhysicalWidth — (VMS above)
  • PhysicalHeight — (VMS above)
  • LayerSpacing — (VMS above)
  • LayerOffset — unknown 🙈 nobody knows her
  • MacroImage — (VMS above)
  • PhysicalMacroWidth — (VMS above)
  • PhysicalMacroHeight — (VMS above)
  • XOffsetFromSlideCentre — (VMS above)
  • YOffsetFromSlideCentre — (VMS above)
  • Reference — unknown 💀
  • BitsPerPixel — bits per pixel, and rn it's expected to be 36
  • PixelOrder — currently expected to be RGB
  • Creator — a string describing the software that made this image 👑
  • IlluminationMode — unknown
  • ExposureMultiplier — unknown, possibly the multiplier used to scale to 15 bits?
  • GainRed — unknown
  • GainGreen — unknown
  • GainBlue — unknown
  • FocalPlaneTolerance — unknown
  • NMP — unknown
  • MacroIllumination — unknown
  • FocusOffset — unknown
  • RefocusInterval — unknown
  • CubeName — unknown
  • HardwareModel — the name of the hardware 🎀
  • HardwareSerial — the serial number of the hardware 🎀
  • NoFocusPoints — unknown
  • FocusPoint0X — unknown
  • FocusPoint0Y — unknown
  • FocusPoint0Z — unknown
  • FocusPoint1X — unknown
  • FocusPoint1Y — unknown
  • FocusPoint1Z — unknown
  • FocusPoint2X — unknown
  • FocusPoint2Y — unknown

That's a whole lot of "unknown" and I am not okay 😭 but hey, at least now you know exactly which ones are mysterious and which ones just point you back upstairs to the VMS section.

…and the last lil' handful of properties from that table, bestie — every single one of these is typed Unknown ngl, so we're just vibing with the names 💫

  • FocusPoint2Z — type: Unknown
  • FocusPoint3X — type: Unknown
  • FocusPoint3Y — type: Unknown
  • FocusPoint3Z — type: Unknown
  • NoBlobPoints — type: Unknown
  • BlobPoint0Blob — type: Unknown
  • BlobPoint0FocusPoint — type: Unknown
  • BlobPoint1Blob — type: Unknown
  • BlobPoint1FocusPoint — type: Unknown
  • BlobPoint2Blob — type: Unknown
  • BlobPoint2FocusPoint — type: Unknown
  • BlobPoint3Blob — type: Unknown
  • BlobPoint3FocusPoint — type: Unknown
  • BlobMapWidth — type: Unknown
  • BlobMapHeight — type: Unknown

🌈 NDPI File 🌈

okay so NDPI is giving "TIFF but make it chaotic" — it uses a TIFF-like structure, but here's the thing: libtiff literally cannot read the headers of an NDPI file. why? because NDPI sets RowsPerStrip to the height of the file, and once you do the multiplication it typically overflows libtiff and it just flat-out refuses to open the file 😭 also, the TIFF tags are not stored in sorted order. iconic behaviour honestly.

NDPI stores an image pyramid inside TIFF directory entries. in some files, the lower-resolution pyramid levels contain no restart markers. and the macro image, plus sometimes an active-region map, seems to come last.

JPEG files inside NDPI are not necessarily valid 👀 if ImageWidth or ImageHeight exceeds the JPEG limit of 65535, then the width or height as stored in the JPEG file is 0. libjpeg will refuse to read the header of such a file, so the JPEG data stream must be altered when it's fed into libjpeg. like, you can't just hand it over, you gotta do surgery first 💅

NDPI is based on the classic TIFF format, and classic TIFF does not support files larger than 4 GB. but plot twist: NDPI files can be larger than 4 GB 🫠 NDPI generally handles this by overflowing the corresponding TIFF fields, which means the reader has to guess the high-order bits. this affects TIFF Value Offsets with pointers to out-of-line values, and also the value of the StripOffsets field. some TIFF fields (e.g. Software) have the same Value Offset in every directory — for those, no concatenation of high-order bits is necessary. for the others (primarily field 65426) it seems reasonable to select high-order bits which place the value at the largest offset below the directory itself, since the TIFF directory is positioned after the data it points to. and NDPI always stores next-directory offsets (in the TIFF header and at the end of each directory) as 64-bit quantities, even though TIFF specifies them as 32 bits — this is possible because the TIFF standard places them at the end of their parent data structures. cute, right? 🌸

ngl it is not clear whether NDPI can support individual directories larger than 4 GB. such files would require additional inferences for the StripByteCounts field, for Value Offsets that are identical across directories, and for the optimisation entries. so like… tread carefully bestie 💀

Okay so here's the tea on those TIFF tags, bestie — every single one, no skips 💅

  • ImageWidth — width of the image 🫶
  • ImageHeight — height of the image
  • Make — literally just "Hamamatsu"
  • Model — "NanoZoomer" or "C9600-12", etc
  • XResolution — the X resolution, and it looks correct when you read it together with ResolutionUnit
  • YResolution — same deal, the Y resolution, seemingly correct alongside ResolutionUnit
  • ResolutionUnit — the resolution unit, and yeah it seems right
  • Software — "NDP.scan", sometimes with a version number tacked on
  • StripOffsets — the offset of the JPEG file for this layer
  • StripByteCounts — the length of the JPEG file for this layer
  • 65420 — always there, always 1. file format version, maybe? 🤔
  • 65421 — SourceLens, correctly downsampled for each entry. -1 for the macro image, -2 for a map of non-empty regions
  • 65422 — XOffsetFromSlideCentre
  • 65423 — YOffsetFromSlideCentre
  • 65424 — seemingly the Z offset from the center focal plane (in nm? 👀)
  • 65425 — unknown, always 0?
  • 65426 — Optimisation entries, as above
  • 65427 — Reference
  • 65428 — unknown, AuthCode?
  • 65430 — unknown, have seen 0.0
  • 65433 — unknown, I have seen 1500 in this tag
  • 65439 — unknown, perhaps some polygon ROI? 🦋
  • 65440 — unknown, I have seen this: <0 0 0 1 0 2 0 3 0 4 0 5 0 6 0 7 0 8 1 9 1 10 1 11 1 12 1 13 1 14 1 15 1 16 1 17>
  • 65441 — unknown, always 0?
  • 65442 — Scanner serial number 🔥
  • 65443 — unknown, have seen 0 or 16
  • 65444 — unknown, always 80?
  • 65445 — unknown, have seen 0, 2, 10
  • 65446 — unknown, always 0?
  • 65449 — ASCII metadata block, key=value pairs, not always present
  • 65455 — unknown, have seen 13
  • 65456 — unknown, have seen 101
  • 65457 — unknown, always 0?
  • 65458 — unknown, always 0?

Optimisation File (only for VMS)

So this file is a list of 32- (or 64- or 320- ?) bit little endian values, and each one gives you the file offset into an MCU row. Every offset starts at a 40-byte alignment, and the last row (of the whole entire file, not each image, okay?) seems to just be missing. 🙈 All the offsets get packed into 1 file, even when there's multiple images. The order of the images goes left-to-right, top-to-bottom. Periodt.

Map File (only for VMS/VMU)

The VMS map file is a standard JPEG file, bestie. Its restart markers (if there are any) are not included in the optimisation file. The VMU map file is in NGR format instead. This file can be used to give you a lower-resolution view of the slide. ✨

Image Files (only for VMS/VMU)

These files are given by the VMS/VMU ImageFile keys. They're assumed to have a height that's a multiple of the MCU height. They're assumed to have a width that's a multiple of MCUs per row divided by the restart interval. 🎀

For VMS, these files are in JPEG. For VMU, they're in NGR format.

NGR Format

The NGR file has uncompressed 16-bit RGB data with a small header. The files we've encountered start with GN, then two more bytes, and then width, height, and column width in little endian 32-bit format. The column width has to divide evenly into the width — that's important, because NGR files are generated in columns, where the first column comes first in the file, followed by subsequent files. Columns are painted left-to-right. 🖌️

At offset 24 there's another 32-bit integer which gives the offset in the file to the start of the image data. The image data we've encountered is in 16-bit little endian format.

Associated Images

macro — the image file given by the MacroImage value in the VMS/VMU file, or SourceLens of -1 in NDPI 🌸

Known Properties

All the key-value data stored in the VMS/VMU file, plus the known tags from the NDPI file, get encoded as properties prefixed with "hamamatsu.". iykyk 💜

  • openslide.mpp-x — for VMS, calculated as hamamatsu.PhysicalWidth/(1000*openslide.level[0].width). For NDPI, calculated as 10000/tiff.XResolution, if tiff.ResolutionUnit is centimeter.
  • openslide.mpp-y — the y-axis microns-per-pixel, bestie 💜 For VMS it's calculated as hamamatsu.PhysicalHeight/(1000*openslide.level[0].height). For NDPI it's calculated as 10000/tiff.YResolution, but only if tiff.ResolutionUnit is centimeter.
  • openslide.objective-power — the normalized hamamatsu.SourceLens. that's it, that's the whole thing ✨

🎀 Test Data 🎀

💖 LEICA FORMAT 💖

🌸 Format 🌸

single-file pyramidal tiled BigTIFF with non-standard metadata. it's giving extra, ngl 🫶

🦋 File extensions 🦋

.scn

👑 OpenSlide vendor backend 👑

leica

✨ Detection ✨

Leica slides live in single-file BigTIFF format, periodt. OpenSlide will clock a file as Leica if:

  1. The file is TIFF.
  2. The initial image is tiled.
  3. The ImageDescription tag contains valid XML in either of these namespaces:
⚠️ To open Leica files, OpenSlide must be built with libtiff 4 or above. no libtiff 4, no vibes, fr fr.

🍓 Relevant TIFF tags 🍓

  • ImageDescription — Stores an XML document containing various metadata. main character tag energy 👑

💅 File Organization 💅

The ImageDescription tag of the first TIFF directory contains an XML document that defines the structure of the slide.

Leica slides are structured as a collection of images, each of which has multiple dimensions (pyramid levels). The collection has a size, and images have a size and position, measured in nanometers. Each dimension has a size in pixels, an optional focal plane number, and a TIFF directory containing the image data. Fluorescence images have different dimensions (and thus different TIFF directories) for each channel. OpenSlide currently rejects fluorescence images and ignores focal planes other than plane 0. 💀 sorry fluorescence girlies.

Brightfield slides have at least two images: a low-resolution macro image and one or more main images corresponding to regions of the macro image. The macro image has a position of (0, 0) and a size matching the size of the collection. Fluorescence slides can have two macro images: one brightfield and one fluorescence.

The slide provides enough information to composite the various images, including the macro image, into a single pyramid. However, there are some complications:

  • The resolution of the macro image is generally not related to the resolution of the main images by a power of two.
  • Downsampled dimensions are generally downsampled from the next larger dimension by a factor of 4, but main images can be scanned with distinct objectives that may differ by only a factor of 2.

Thus, in general, the images in a collection cannot be rendered into a unified pyramid without scaling the original pixel data. OpenSlide does not attempt to do this. Instead, OpenSlide omits the macro image from the pyramid and refuses to open slides whose main images have inconsistent resolutions. 😭 it said "not my problem".

🌈 Associated Images 🌈

  • macro — the highest-resolution dimension of the macro image.

🧚 Known Properties 🧚

  • leica.aperture — the numericalAperture of the main image.
  • leica.barcode — the barcode text. (For slides in the 2010/10/01 namespace, OpenSlide 3.4.0 and earlier report this property as a Base64-encoded string; OpenSlide 3.4.1 and later report it in plain text. For slides in the 2010/03/10 namespace, OpenSlide reports the barcode as it is stored in the XML, since we do not know whether those barcodes are Base64-encoded. If you have a 2010/03/10 slide with a bar code, please comment in this bug[2] or contact the OpenSlide mailing list.)
  • leica.creation-date — the creationDate of the main image.
  • leica.device-model — the device model of the main image.
  • leica.device-version — the device version of the main image.
  • leica.illumination-source — the illuminationSource of the main image.
  • leica.objective — the objective of the main image.
  • openslide.mpp-x — calculated as 10000/tiff.XResolution, if tiff.ResolutionUnit is centimeter.
  • openslide.mpp-y — calculated as 10000/tiff.YResolution, if tiff.ResolutionUnit is centimeter.
  • openslide.objective-power — normalized leica.objective.

⭐ Test Data ⭐

http://openslide.cs.cmu.edu/download/openslide-testdata/Leica/

🫶 MIRAX FORMAT 🫶

🌸 Format 🌸

multi-file with very complicated proprietary metadata and indexes. it's giving chaos but make it indexed 💀

🦋 File extensions 🦋

.mrxs

👑 OpenSlide vendor backend 👑

mirax

✨ Detection ✨

OpenSlide will detect a file as MIRAX if:

  1. The file is not a TIFF.
  2. The filename ends with .mrxs.
  3. A directory exists in the same location as the file, with the same name as the file minus the extension.
  4. A file named Slidedat.ini exists in the directory.

🍓 Overview 🍓

MIRAX can store slides in JPEG, PNG, or BMP formats. Because JPEG does not allow for large images, and JPEG and PNG provide very poor support for random-access decoding of part of an image, multiple images are needed to encode a slide. To avoid having many individual files, MIRAX packs these images into a small number of data files. The index file provides offsets into the data files for each required piece of data.

The camera on MIRAX scanners takes overlapping photos and records the position of each one. Each photo is then split into multiple images which do not overlap. Overlaps only occur between images that come from different photos.

To generate level n + 1, each image from level n is downsampled by 2 and then concatenated into a new image, 4 old images per new image (2 x 2). This process is repeated for each level, irrespective of image overlaps. Therefore, at sufficiently high levels, a single image can contain one or more embedded overlaps of non-integral width. lowkey cursed but okay 💅

💜 Index File 💜

The index file starts with a five-character ASCII version string, followed by the SLIDE_ID from the slidedat file. The rest of the file consists of 32-bit little-endian integers (unaligned), which can be data values or pointers to byte offsets within the index file.

The first two integers point to offset tables for the hierarchical and nonhierarchical roots, respectively. These tables contain one record for each VAL in the HIERARCHICAL slidedat section. For example, the record for NONHIER_1_VAL_2 would be stored at nonhier_root + 4 * (NONHIER_0_COUNT + 2).

Each record is a pointer to a linked list of data pages. The first two values in a data page are the number of data items in the page and a pointer to the next page. The first page always has 0 data items, and the last page has a 0 next pointer.

There is one hierarchical record for each zoom level. The record contains data items consisting of an image index, offset and length within a file, and a file number. The file number can be converted to a data file name via the DATAFILE slidedat section. The image index is equal to image_y * GENERAL.IMAGENUMBER_X + image_x. Image coordinates which are not multiples of the zoom level's downsample factor are omitted.

Nonhierarchical records refer to associated images and additional metadata. Nonhierarchical data items consist of three zero values followed by an offset, length, and file number as in hierarchical records.

🌈 Data Files 🌈

A data file begins with a header containing a five-character ASCII version string, the SLIDE_ID from the slidedat file, the file number encoded into three ASCII characters, and 256 bytes of padding. (In newer slides, the SLIDE_ID and file number are encoded as UTF-16LE, so the second half of each value is truncated away.) The remainder of the file contains packed data referenced by the index file.

🧚 Slide Position File 🧚

The slide position file is referenced by the VIMSLIDE_POSITION_BUFFER.default nonhierarchical section. It contains one entry for each camera position (not each image position) in row-major order. Each entry is nine bytes: a flag byte, the X pixel coordinate of the photo (4 bytes, little-endian, may be negative), and the Y coordinate (4 bytes, little-endian, may be negative). In slides with CURRENT_SLIDE_VERSION ≥ 1.9, the flag byte is 1 if the slide file contains images for this camera position, 0 otherwise. In older slides, the flag byte is always 0.

In slides with CURRENT_SLIDE_VERSION ≥ 2.2, the slide position file is compressed with DEFLATE and referenced by the StitchingIntensityLayer.StitchingIntensityLevel nonhierarchical section.

⭐ Associated Images ⭐

  • thumbnail — the image named "ScanDataLayer_SlidePreview" in Slidedat.ini (optional).
  • label — the image named "ScanDataLayer_SlideBarcode" in Slidedat.ini (optional).
  • macro — the image named "ScanDataLayer_SlideThumbnail" in Slidedat.ini (optional).

🎀 Known Properties 🎀

All key-value data stored in the Slidedat.ini file are encoded as properties prefixed with "mirax.".

  • openslide.mpp-x — normalized MICROMETER_PER_PIXEL_X from the Slidedat section corresponding to level 0 (typically mirax.LAYER_0_LEVEL_0_SECTION.MICROMETER_PER_PIXEL_X).
  • openslide.mpp-y — normalized MICROMETER_PER_PIXEL_Y from the Slidedat section corresponding to level 0 (typically mirax.LAYER_0_LEVEL_0_SECTION.MICROMETER_PER_PIXEL_Y).
  • openslide.objective-power — normalized mirax.GENERAL.OBJECTIVE_MAGNIFICATION.

💫 See Also 💫

Introduction to MIRAX/MRXS[3]. Note that our terminology has changed since that document was written; where it says "tile", substitute "image", and where it says "subtile", substitute "tile". iykyk ✨

🌟 Test Data 🌟

http://openslide.cs.cmu.edu/download/openslide-testdata/Mirax/

👑 PHILIPS FORMAT 👑

💖 Format

  • single-file pyramidal tiled TIFF or BigTIFF with non-standard metadata

🎀 File extensions

  • .tiff

✨ OpenSlide vendor backend

  • philips

🔍 Detection

Philips TIFF files are stored in single-file TIFF or BigTIFF format. OpenSlide will detect a file as Philips if:

  1. The file is TIFF.
  2. The TIFF Software tag starts with Philips.
  3. The ImageDescription tag contains valid XML.
  4. The root element of the XML is DataObject and has an ObjectType attribute with a value of DPUfsImport.
To open BigTIFF files, OpenSlide must be built with libtiff 4 or above. no cap, that's a hard requirement 💀

🦋 File Organization

Philips TIFF is an export format. The native Philips format, iSyntax, is a custom multi-file format not currently supported by OpenSlide. 😭

The ImageDescription tag of the first TIFF directory contains an XML document with a hierarchical structure containing key-value pairs. The keys are based on DICOM tags.

The level dimensions given in the TIFF ImageWidth and ImageLength fields, and also in the ImageDescription XML, are merely the TIFF tile size multiplied by the number of tiles in each dimension. Thus, they include the size of the padding in the right-most column and bottom-most row of tiles. Each level typically uses the same tile size but requires a different amount of padding, so the aspect ratios of the levels are inconsistent and the level dimensions are not proportional to the level downsamples. Correct downsamples can be calculated from the levels' pixel spacings in the XML metadata. slay, math 💅

Slides with multiple regions of interest are structured as a single image pyramid enclosing all regions. Slides may omit pixel data for TIFF tiles not in an ROI; this is represented as a TileOffset of 0 and a TileByteCount of 0. When such tiles are downsampled into a tile that does contain pixel data, their contents are rendered as white pixels. 🤍

Label and macro images are stored as Base64-encoded JPEGs in the ImageDescription XML. Some slides also store these images as stripped TIFF directories whose ImageDescriptions start with Label and Macro, respectively.

🌸 Relevant TIFF tags

  • ImageDescription — Stores an XML document containing various metadata and associated image data
  • Software — Starts with Philips

🫶 Associated Images

  • label — the TIFF directory with an ImageDescription starting with Label, or the image data in the DPScannedImage with a PIM_DP_IMAGE_TYPE of LABELIMAGE
  • macro — the TIFF directory with an ImageDescription starting with Macro, or the image data in the DPScannedImage with a PIM_DP_IMAGE_TYPE of MACROIMAGE

💜 Known Properties

All key-value data encoded in the DPUfsImport object, in the first DPScannedImage object with a PIM_DP_IMAGE_TYPE of WSI, and in that object's PixelDataRepresentation objects is represented as properties prefixed with “philips.”. 💖

  • openslide.mpp-x — calculated as 1000 * philips.DICOM_PIXEL_SPACING[1]
  • openslide.mpp-y — calculated as 1000 * philips.DICOM_PIXEL_SPACING[0]

🧚 Test Data

No public data available. Contact the mailing list[4] if you have some. bestie if you're sitting on Philips test data, the mailing list needs you fr fr 🙏

🍓 SAKURA FORMAT 🍓

💖 Format

  • SQLite database containing pyramid tiles and metadata

🎀 File extensions

  • .svslide

✨ OpenSlide vendor backend

  • sakura

🔍 Detection

OpenSlide will detect a file as Sakura if:

  1. The file is a SQLite database.
  2. The DataManagerSQLiteConfigXPO table contains exactly one row, and its TableName field refers to a unique table.
  3. The unique table contains a row with id = "++MagicBytes" and data = "SVGigaPixelImage".
those magic bytes are literally the whole vibe check. no match, no Sakura. 💀

🦋 File Organization

Sakura slides are SQLite 3 database files written by the eXpress Persistent Objects ORM. Tables contain slide metadata, associated images, and JPEG tiles. Tiles are addressed as (focal plane, downsample, level-0 X coordinate, level-0 Y coordinate, color channel), with separate grayscale JPEGs for each color channel. Despite the generality of the address format, tiles appear to be organized in a regular grid, with power-of-two level downsamples and without overlapping tiles. The structure of the file allows scans to be sparse, but it is not clear if this is actually done. 🤔

🌈 SQL Tables

Some irrelevant tables and columns have been omitted from the summary below.

DataManagerSQLiteConfigXPO.PP — Useful only to get a reference to the unique table. OpenSlide requires this table to contain exactly one row.

  • TableName (text) — Name of the unique table, described below

SVSlideDataXPO.PP — High-level metadata about a slide. OpenSlide assumes this table will contain exactly one row.

  • OID (integer) — Primary key
  • m_labelScan (integer) — Foreign key to label associated image in SVScannedImageDataXPO
  • m_overviewScan (integer) — Foreign key to macro associated image in SVScannedImageDataXPO
  • SlideId (text) — UUID
  • Date (text) — File creation date?
  • Description (text) — Descriptive text?
  • Creator (text) — Author?
  • DiagnosisCode (text) — Unknown, have seen “0”
  • HRScanCount (integer) — Presumably the number of corresponding rows in SVHRScanDataXPO
  • Keywords (text) — Descriptive text?
  • TotalDataSizeBytes (integer) — Presumably the sum of TotalDataSizeBytes in corresponding SVHRScanDataXPO rows

🎀 SVHRScanDataXPO.PP 🎀

okay so this one is a single high-resolution scan of a slide, and it belongs to SVSlideDataXPO. and bestie, OpenSlide literally assumes this table has exactly one row. one. not two. don't test it. 💅

  • OID — integer — the primary key 🔑
  • ParentSlide — integer — foreign key pointing back at SVSlideDataXPO
  • ScanId — text — a UUID
  • Date — text — scan date? (yes the question mark is doing a lot of heavy lifting here 🙈)
  • Description — text — descriptive text?
  • Name — text — scan name?
  • PosOnSlideMm — blob — 16 bytes of binary
  • ResolutionMmPerPix — real — millimeters per pixel
  • NominalLensMagnification — real — objective power
  • ThumbnailImage — blob — thumbnail associated image data
  • TotalDataSizeBytes — integer — same as the TOTAL_SIZE blob in the unique table
  • FocussingMethod — integer — unknown; have seen “1”
  • FocusStack — blob — 8 bytes of binary per focal plane; the center focal plane apparently has all zeroes ✨

🌸 SVScannedImageDataXPO.PP 🌸

this one is holding the associated images that aren't the thumbnail, iykyk 💖

  • OID — integer — primary key 🔑
  • Id — text — a UUID
  • PosOnSlideMm — blob — 16 bytes of binary
  • ScanCenterPosMm — blob — 16 bytes of binary
  • ResolutionMmPerPix — real — millimeters per pixel
  • Image — blob — JPEG image data
  • ThumbnailImage — blob — low-resolution JPEG thumbnail

🦋 tile.PP 🦋

ngl this table is most naturally used to map tile coordinates to tile IDs, but it is not suitable for individual lookups because it has no useful indexes. also? some Sakura slides just don't have it at all 😭. so OpenSlide ignores the table entirely and constructs tile IDs directly from tile coordinates. main character behavior, honestly 👑

  • TILEID — text — foreign key to the unique table
  • PYRAMIDLEVEL — integer — downsample of the pyramid level
  • COLUMNINDEX — integer — level-0 X coordinate of the top-left corner of the tile
  • ROWINDEX — integer — level-0 Y coordinate of the top-left corner of the tile
  • COLORINDEX — integer — 0 for red, 1 for green, 2 for blue 🌈

💜 Unique table 💜

this is the table that DataManagerSQLiteConfigXPO.TableName names. it contains named blobs, including the JPEG tile data. the moment. the icon. the legend. 🫶

  • id — text — primary key 🔑
  • size — integer — length of the data field
  • data — blob — data item

and yes, that's the whole unique table, she's simple but she's doing the most fr fr 💅

This table stores a variety of blob types.

  • ++MagicBytes — SVGigaPixelImage
  • ++VersionBytes — the format version, like 1.0.0
  • Header — peek below 👇
  • TOTAL_SIZE — okay so the data field on this one is empty, and the size field is the sum of all the other size fields except ++MagicBytes and ++VersionBytes
  • T;2048|4096;4;2;0 — an image tile, with downsample 4, X coordinate 2048, Y coordinate 4096, channel 2 (that's blue bestie 💙), and focal plane 0
  • T;2048|4096;4;2;0# — the MD5 hash of the T;2048|4096;4;2;0 image tile

✨ Header blob ✨

The Header blob is a lil binary structure holding little-endian integers, laid out like this:

  • offset 0, size 4 — tile size in pixels
  • offset 4, size 4 — image width in pixels
  • offset 8, size 4 — image height in pixels
  • offset 12, size 4 — unknown; have seen 8 (bits per channel? 👀)
  • offset 16, size 4 — number of focal planes
  • offset 20, size 4 — unknown; have seen 3 (number of channels? 🤔)
  • offset 24, size 4 — unknown; have seen 1
  • offset 28, size 2 — unknown; have seen 256
  • offset 30, size 4 — unknown; have seen 1
  • offset 34, size 4 — unknown; have seen 2
  • offset 38, size 4 — unknown; have seen 3
  • offset 42, size 4 — unknown; have seen 4
  • offset 46, size 4 — unknown; have seen 5
  • offset 50, size 4 — unknown; have seen 6

🖼️ Associated Images

  • label — SVScannedImageDataXPO.Image corresponding to SVSlideDataXPO.m_labelScan
  • macro — SVScannedImageDataXPO.Image corresponding to SVSlideDataXPO.m_overviewScan
  • thumbnail — SVHRScanDataXPO.ThumbnailImage

🏷️ Known Properties

  • sakura.Creator — SVSlideDataXPO.Creator
  • sakura.Date — SVSlideDataXPO.Date
  • sakura.Description — SVSlideDataXPO.Description
  • sakura.DiagnosisCode — SVSlideDataXPO.DiagnosisCode
  • sakura.FocussingMethod — SVHRScanDataXPO.FocussingMethod
  • sakura.Keywords — SVSlideDataXPO.Keywords
  • sakura.NominalLensMagnification — SVHRScanDataXPO.NominalLensMagnification
  • sakura.ResolutionMmPerPix — SVHRScanDataXPO.ResolutionMmPerPix
  • sakura.ScanId — SVHRScanDataXPO.ScanId
  • sakura.SlideId — SVSlideDataXPO.SlideId
  • openslide.mpp-x — calculated as 1000 * sakura.ResolutionMmPerPix
  • openslide.mpp-y — calculated as 1000 * sakura.ResolutionMmPerPix
  • openslide.objective-power — the normalized sakura.NominalLensMagnification

🧪 Test Data

No public data available. 😭 Contact the mailing list[4] if you have some — fr fr, the maintainers would be so grateful 🫶

🌸 TRESTLE FORMAT 🌸

Format

single-file pyramidal tiled TIFF, with non-standard metadata and overlaps; additional files contain more metadata and detailed overlap info. It's giving extra, bestie, and we love that for it 💅

File extensions

.tif

OpenSlide vendor backend

trestle

Detection

Trestle slides are stored in single-file TIFF format. OpenSlide will detect a file as Trestle if:

  1. The file is TIFF.
  2. The TIFF Software tag starts with MedScan.
  3. The ImageDescription tag is present.
  4. All images are tiled.
no cap, that's the whole vibe check ✨

Relevant TIFF tags

  • ImageDescription — Stores some important key-value pairs, see below
  • Software — Starts with MedScan
  • XResolution, YResolution — Seems to store microns-per-pixel (MPP), which may or may not take into account the correct objective power. Note that this is inverted from standard TIFF, which stores pixels-per-unit, not units-per-pixel. Yes, it's lowkey chaotic 🙈

Extra data stored in ImageDescription

The ImageDescription tag contains semicolon-delimited key-value pairs. A key-value pair is equals-delimited. We use the OverlapsXY and Background Color keys from the ImageDescription, and ignore the rest. All of these values are stored as properties starting with “trestle.”.

  • Background Color — Hex-encoded background color info, assumed to be in the format RRGGBB.
  • White Balance — Hex-encoded white balance
  • Objective Power — Reported objective power, often incorrect.
  • JPEG Quality — The JPEG quality value.
  • OverlapsXY — Overlaps, see below.

periodt. now onto the overlaps, because of course there are overlaps 🎀

TIFF Image Directory Organization

The first image in the TIFF file is the full-resolution image. The subsequent images are assumed to be decreasingly sized reduced-resolution images.

Overlaps

The OverlapsXY pseudo-field encodes a list of tile overlap values as ASCII.

Example: “64 64 32 32 16 16” (note the initial space).

These values represent the standard overlaps between adjacent tiles in X and Y, in pixels. This example encodes 3 levels worth of overlaps. Further overlaps are assumed to have the value 0.

Individual tile overlaps may differ from the standard overlaps. These individual overlaps are recorded in .tif-Nb files adjacent to the .tif file, where N is the level number. OpenSlide does not read these files, though they have been partially decoded; see issue 21[5] for details.

bestie, the initial space is literally in there. don't erase it, i'm begging 🫶

Associated Images

  • macro — the image with a filename extension of .Full (optional)

Known Properties

All data encoded in the ImageDescription TIFF field is represented as properties prefixed with “trestle.”.

  • openslide.mpp-x — copy of tiff.XResolution (note that this is a totally non-standard use of this TIFF tag)
  • openslide.mpp-y — copy of tiff.YResolution (note that this is a totally non-standard use of this TIFF tag)
  • openslide.objective-power — normalized trestle.Objective Power

Test Data

http://openslide.cs.cmu.edu/download/openslide-testdata/Trestle/

💜 VENTANA FORMAT 💜

Format

single-file pyramidal tiled BigTIFF with non-standard metadata and overlaps

File extensions

.bif, .tif

OpenSlide vendor backend

ventana

Detection

Ventana slides are stored in single-file BigTIFF format. OpenSlide will detect a file as Ventana if:

  1. The file is TIFF.
  2. The XMP tag contains valid XML.
  3. The XML contains an iScan element, either as the root element or as a child of a Metadata root element.

To open Ventana files, OpenSlide must be built with libtiff 4 or above.

BigTIFF said "i'm the main character" and honestly? valid 👑

Associated Images

  • macro — the TIFF directory whose ImageDescription is Label Image or Label_Image
  • thumbnail — the TIFF directory whose ImageDescription is Thumbnail

Known Properties

All XML attributes in the iScan element are represented as properties prefixed with “ventana.”.

  • openslide.mpp-x — normalized ventana.ScanRes
  • openslide.mpp-y — normalized ventana.ScanRes
  • openslide.objective-power — normalized ventana.Magnification

Test Data

http://openslide.cs.cmu.edu/download/openslide-testdata/Ventana/

🌈 GENERIC TILED TIFF FORMAT 🌈

Format

single-file pyramidal tiled TIFF

File extensions

.tif

OpenSlide vendor backend

generic-tiff

Detection

OpenSlide will detect a file as generic TIFF if:

  1. No other detections succeed.
  2. The file is TIFF.
  3. The initial image is tiled.
it's the fallback bestie, the "if nobody else claims you, i will" energy 😭💖

TIFF Image Directory Organization

The first image in the TIFF file is the full-resolution image. Any other tiled images in the file with the “reduced resolution” bit set are assumed to be reduced-resolution versions of the original.

Associated Images

None.

Known Properties

Many TIFF tags are encoded as properties starting with “tiff.”.

Test Data

http://openslide.cs.cmu.edu/download/openslide-testdata/Generic-TIFF/

👑 AUTHORS 👑

The Carnegie Mellon School of Computer Science.

This manual page was written by Mathieu Malaterre <malat@debian.org> for the Debian GNU/Linux system (but may be used by others).

🎀 NOTES 🎀

  1. pages for each vendor format http://openslide.org/formats/
  2. this bug http://openslide.orghttps://github.com/openslide/openslide/issues/155
  3. Introduction to MIRAX/MRXS http://openslide.orghttps://lists.andrew.cmu.edu/pipermail/openslide-users/2012-July/000373.html
  4. mailing list http://openslide.orghttps://lists.andrew.cmu.edu/mailman/listinfo/openslide-users/
  5. issue 21 http://openslide.orghttps://github.com/openslide/openslide/issues/21#issuecomment-23615583

okay bestie, that's the whole manual page 💖 it's OpenSlide 3.4.1+dfsg, dated 07/29/2016, and it lives in OPENSLIDE-FORMATS(3). go slay your slides, fr fr ✨🦋

📦 where this page comes from