From d7df1f759df528bdc1d9580564f4f187b9a655f1 Mon Sep 17 00:00:00 2001 From: Benjamin Gilbert Date: Thu, 27 Jul 2023 02:03:28 -0400 Subject: [PATCH] Document DICOM format libdicom controls which Dimension Organization Types are supported. Co-authored-by: John Cupitt Signed-off-by: John Cupitt Signed-off-by: Benjamin Gilbert --- _includes/links.md | 1 + formats/dicom/index.md | 93 ++++++++++++++++++++++++++++++++++++++++++ formats/index.md | 14 +++++++ index.md | 1 + 4 files changed, 109 insertions(+) create mode 100644 formats/dicom/index.md diff --git a/_includes/links.md b/_includes/links.md index 99841a8..988af1f 100644 --- a/_includes/links.md +++ b/_includes/links.md @@ -26,6 +26,7 @@ [formats]: /formats/ [format-aperio]: /formats/aperio/ +[format-dicom]: /formats/dicom/ [format-generic-tiff]: /formats/generic-tiff/ [format-hamamatsu]: /formats/hamamatsu/ [format-leica]: /formats/leica/ diff --git a/formats/dicom/index.md b/formats/dicom/index.md new file mode 100644 index 0000000..8440724 --- /dev/null +++ b/formats/dicom/index.md @@ -0,0 +1,93 @@ +--- +title: DICOM format +--- + +Format +: international standard multi-file medical imaging format + +File extensions +: `.dcm` + +OpenSlide vendor backend +: `dicom` + + +## Format Documentation + +[DICOM Whole Slide Imaging](https://dicom.nema.org/dicom/dicomwsi/) + + +## Detection + +OpenSlide will detect a file as DICOM if: + + 1. The file can be parsed as a DICOM Part 10 file. + 2. The _Media Storage SOP Class UID_ is _VL Whole Slide Microscopy Image + Storage_ (`1.2.840.10008.5.1.4.1.1.77.1.6`). + + +## File Organization + +OpenSlide uses [libdicom](https://libdicom.readthedocs.io/) to parse and +load DICOM files. + +OpenSlide non-recursively scans the containing directory for other DICOM +files with the same _Series Instance UID_ attribute value as the specified +file. It uses the _Image Type_ attribute of each matching file to determine +the file's role within the whole slide image: + +| Role | Allowed _Image Type_ values | +| - | - | - | +| Slide level | `ORIGINAL\PRIMARY\VOLUME\NONE`
`DERIVED\PRIMARY\VOLUME\NONE`
`DERIVED\PRIMARY\VOLUME\RESAMPLED` | +| Associated image | `ORIGINAL\PRIMARY\LABEL\NONE`
`ORIGINAL\PRIMARY\OVERVIEW\NONE`
`ORIGINAL\PRIMARY\THUMBNAIL\RESAMPLED`
`DERIVED\PRIMARY\LABEL\NONE`
`DERIVED\PRIMARY\OVERVIEW\NONE`
`DERIVED\PRIMARY\THUMBNAIL\RESAMPLED` | +| Ignored | All others | + +If multiple files in the directory have the same _SOP Instance UID_, +the extra copies are ignored. + +A file's _Dimension Organization Type_ can be `TILED_FULL`, `TILED_SPARSE`, +or `3D`. These transfer syntaxes and photometric interpretations are +supported: + +| Pixel encoding | _Transfer Syntax UID_ | Allowed _Photometric Interpretation_ values | +| - | - | - | +| Uncompressed little-endian | `1.2.840.10008.1.2.1` | `RGB` | +| JPEG baseline | `1.2.840.10008.1.2.4.50` | `RGB`
`YBR_FULL_422` | +| JPEG 2000 | `1.2.840.10008.1.2.4.91` | `RGB`
`YBR_ICT` | +| JPEG 2000 lossless | `1.2.840.10008.1.2.4.90` | `RGB`
`YBR_ICT` | + + +## ICC Profiles + +The slide ICC profile is taken from the _ICC Profile_ attribute of the +highest-resolution image. Associated image ICC profiles are taken from the +_ICC Profile_ of the associated image. + + +## Associated Images + +| Associated image | Allowed _Image Type_ values | +| - | - | - | +| thumbnail | `ORIGINAL\PRIMARY\THUMBNAIL\RESAMPLED`
`DERIVED\PRIMARY\THUMBNAIL\RESAMPLED` | +| label | `ORIGINAL\PRIMARY\LABEL\NONE`
`DERIVED\PRIMARY\LABEL\NONE` | +| macro | `ORIGINAL\PRIMARY\OVERVIEW\NONE`
`DERIVED\PRIMARY\OVERVIEW\NONE` | + + +## Known Properties + +Many DICOM attributes are represented hierarchically as properties prefixed +with "`dicom.`". + +`openslide.mpp-x` +: normalized X component of _Pixel Spacing_ from highest-resolution level + +`openslide.mpp-y` +: normalized Y component of _Pixel Spacing_ from highest-resolution level + +`openslide.objective-power` +: _Objective Lens Power_ from highest-resolution level + + +## Test Data + + diff --git a/formats/index.md b/formats/index.md index 0715ce6..d350ea7 100644 --- a/formats/index.md +++ b/formats/index.md @@ -26,6 +26,20 @@ More info : [Aperio format][format-aperio] +## DICOM + +International standard multi-file medical imaging format. + +File extensions +: `.dcm` + +OpenSlide vendor backend +: `dicom` + +More info +: [DICOM format][format-dicom] + + ## Hamamatsu Multi-file JPEG/NGR with proprietary metadata and index file formats, and diff --git a/index.md b/index.md index 1d48019..1657914 100644 --- a/index.md +++ b/index.md @@ -44,6 +44,7 @@ terms of the [GNU Lesser General Public License, version 2.1][license]. The library can read virtual slides in the following formats: * [Aperio (.svs, .tif)][format-aperio] + * [DICOM (.dcm)][format-dicom] * [Hamamatsu (.vms, .vmu, .ndpi)][format-hamamatsu] * [Leica (.scn)][format-leica] * [MIRAX (.mrxs)][format-mirax]