dcmnorm-transcode 0.20.0

DICOM transfer-syntax registry and pixel codecs for dcmnorm, forked from dicom-transfer-syntax-registry 0.9.1. See README.md.
Documentation
#![deny(trivial_numeric_casts, unsafe_code, unstable_features)]
#![warn(
    missing_debug_implementations,
    missing_docs,
    unused_qualifications,
    unused_import_braces
)]
//! This crate contains the DICOM transfer syntax registry.
//!
//! The transfer syntax registry maps a DICOM UID of a transfer syntax (TS)
//! into the respective transfer syntax specifier.
//! This specifier defines:
//!
//! 1. how to read and write DICOM data sets;
//! 2. how to decode and encode pixel data.
//!
//! Support may be partial, in which case the data set can be retrieved
//! but the pixel data may not be decoded through this crate. To include
//! support for some transfer syntaxes with encapsulated pixel data,
//! add the **`native`** Cargo feature
//! or one of the other image encoding features available.
//!
//! All registered TSes are readily available
//! through the [`TransferSyntaxRegistry`] type.
//!
//! This registry is intended to be used in the development of higher level APIs,
//! which should learn to negotiate and resolve the expected
//! transfer syntax automatically.
//!
//! ## Transfer Syntaxes
//!
//! This crate encompasses basic DICOM level of conformance,
//! plus support for some transfer syntaxes with compressed pixel data.
//! _Implicit VR Little Endian_,
//! _Explicit VR Little Endian_,
//! and _Explicit VR Big Endian_
//! are fully supported.
//! Support may vary for transfer syntaxes which rely on encapsulated pixel data.
//!
//! | transfer syntax               | decoding support     | encoding support |
//! |-------------------------------|----------------------|------------------|
//! | Deflated Explicit VR Little Endian | Cargo feature `deflate` | ✓ |
//! | JPEG Baseline (Process 1)     | Cargo feature `jpeg` | ✓ |
//! | JPEG Extended (Process 2 & 4) | Cargo feature `jpeg` | x |
//! | JPEG Lossless, Non-Hierarchical (Process 14) | Cargo feature `jpeg` | x |
//! | JPEG Lossless, Non-Hierarchical, First-Order Prediction (Process 14 [Selection Value 1]) | Cargo feature `jpeg` | x |
//! | JPEG-LS Lossless              | not supported here; see `src/dicom_io/jpeg_ls.rs` | - |
//! | JPEG-LS Lossy (Near-Lossless) | not supported here; see `src/dicom_io/jpeg_ls.rs` | - |
//! | JPEG 2000 (Lossless Only)     | Cargo feature `jpeg2000` (OpenJPEG) | x |
//! | JPEG 2000                     | Cargo feature `jpeg2000` (OpenJPEG) | x |
//! | JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only) | Cargo feature `jpeg2000` (OpenJPEG) | x |
//! | JPEG 2000 Part 2 Multi-component Image Compression | Cargo feature `jpeg2000` (OpenJPEG) | x |
//! | JPIP Referenced Deflate       | Cargo feature `deflate` | ✓ |
//! | High-Throughput JPEG 2000 (Lossless Only) | Cargo feature `jpeg2000` (OpenHTJ2K) | x (dcmnorm encodes it directly) |
//! | High-Throughput JPEG 2000 with RPCL Options (Lossless Only) | Cargo feature `jpeg2000` (OpenHTJ2K) | x |
//! | High-Throughput JPEG 2000     | Cargo feature `jpeg2000` (OpenHTJ2K) | x (dcmnorm encodes it directly) |
//! | JPIP HTJ2K Referenced Deflate | Cargo feature `deflate` | ✓ |
//! | JPEG XL (Lossless/Recompression/general) | Cargo feature `jpeg-xl-codec` on the top-level `dcmnorm` crate; see `src/dicom_io/jpeg_xl.rs` | x |
//! | RLE Lossless                  | Cargo feature `rle` | x |
//! | Deflated Image Frame          | Cargo feature `deflate` | ✓ |
//!
//! Cargo features behind `native` (`jpeg`, `rle`, `deflate`)
//! provide implementations that are written in pure Rust (JPEG decoding via
//! the in-house `dcmnorm-jpeg`, encoding via `jpeg-encoder`) and are likely
//! available on all supported platforms without issues.
//! Additional codecs are opt-in by enabling Cargo features,
//! for scenarios where a native implementation is not available,
//! or alternative implementations are available.
//!
//! - `jpeg2000` provides JPEG 2000 decoding through the `dcmnorm-jpeg2000` crate: OpenJPEG (C,
//!   statically linked) for classic JPEG 2000 and the vendored OpenHTJ2K (C++) for
//!   High-Throughput JPEG 2000. Neither can be used in WebAssembly.
//!
//! JPEG-LS and JPEG XL are not supported via this registry - see `entries.rs`
//! for the reasoning. Transfer syntaxes which are not supported,
//! either due to being unable to read the data set
//! or decode encapsulated pixel data,
//! are listed as _stubs_ for partial support.
//! The full list is available in the [`entries`] module.

use dcmnorm_encoding::transfer_syntax::{AdapterFreeTransferSyntax as Ts, Codec};
use lazy_static::lazy_static;
use std::collections::hash_map::Entry;
use std::collections::HashMap;
use std::fmt;

pub use dcmnorm_encoding::{TransferSyntax, TransferSyntaxIndex};
pub mod entries;

pub(crate) mod alloc;

mod adapters;
#[cfg(feature = "deflate")]
mod deflate;

/// Main implementation of a registry of DICOM transfer syntaxes.
///
/// Consumers would generally use [`TransferSyntaxRegistry`] instead.
pub struct TransferSyntaxRegistryImpl {
    m: HashMap<&'static str, TransferSyntax>,
}

impl fmt::Debug for TransferSyntaxRegistryImpl {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let entries: HashMap<&str, &str> =
            self.m.iter().map(|(uid, ts)| (*uid, ts.name())).collect();
        f.debug_struct("TransferSyntaxRegistryImpl")
            .field("m", &entries)
            .finish()
    }
}

impl TransferSyntaxRegistryImpl {
    /// Obtain an iterator of all registered transfer syntaxes.
    pub fn iter(&self) -> impl Iterator<Item = &TransferSyntax> {
        self.m.values()
    }

    /// Obtain a DICOM codec by transfer syntax UID.
    fn get<U: AsRef<str>>(&self, uid: U) -> Option<&TransferSyntax> {
        let ts_uid = uid
            .as_ref()
            .trim_end_matches(|c: char| c.is_whitespace() || c == '\0');
        self.m.get(ts_uid)
    }

    /// Register the given transfer syntax (TS) to the system. It can override
    /// another TS with the same UID, in the only case that the TS requires
    /// certain codecs which are not supported by the previously registered
    /// TS. If no such requirements are imposed, this function returns `false`
    /// and no changes are made.
    fn register(&mut self, ts: TransferSyntax) -> bool {
        match self.m.entry(ts.uid()) {
            Entry::Occupied(mut e) => {
                let replace = match (&e.get().codec(), ts.codec()) {
                    (Codec::Dataset(None), Codec::Dataset(Some(_)))
                    | (
                        Codec::EncapsulatedPixelData(None, None),
                        Codec::EncapsulatedPixelData(..),
                    )
                    | (
                        Codec::EncapsulatedPixelData(Some(_), None),
                        Codec::EncapsulatedPixelData(Some(_), Some(_)),
                    )
                    | (
                        Codec::EncapsulatedPixelData(None, Some(_)),
                        Codec::EncapsulatedPixelData(Some(_), Some(_)),
                    ) => true,
                    // weird one ahead: the two specifiers do not agree on
                    // requirements, better keep it as a separate match arm for
                    // debugging purposes
                    (Codec::Dataset(None), Codec::EncapsulatedPixelData(_, _)) => {
                        tracing::warn!("Inconsistent requirements for transfer syntax {}: `Dataset` cannot be replaced by `EncapsulatedPixelData`", ts.uid());
                        false
                    }
                    // another weird one:
                    // the two codecs do not agree on requirements
                    (Codec::EncapsulatedPixelData(_, _), Codec::Dataset(None)) => {
                        tracing::warn!("Inconsistent requirements for transfer syntax {}: `EncapsulatedPixelData` cannot be replaced by `Dataset`", ts.uid());
                        false
                    }
                    // ignoring TS with less or equal implementation
                    _ => false,
                };

                if replace {
                    e.insert(ts);
                    true
                } else {
                    false
                }
            }
            Entry::Vacant(e) => {
                e.insert(ts);
                true
            }
        }
    }
}

impl TransferSyntaxIndex for TransferSyntaxRegistryImpl {
    #[inline]
    fn get(&self, uid: &str) -> Option<&TransferSyntax> {
        Self::get(self, uid)
    }
}

impl TransferSyntaxRegistry {
    /// Obtain an iterator of all registered transfer syntaxes.
    #[inline]
    pub fn iter(&self) -> impl Iterator<Item = &TransferSyntax> {
        get_registry().iter()
    }
}

/// Zero-sized representative of the main transfer syntax registry.
#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash)]
pub struct TransferSyntaxRegistry;

impl TransferSyntaxIndex for TransferSyntaxRegistry {
    #[inline]
    fn get(&self, uid: &str) -> Option<&TransferSyntax> {
        get_registry().get(uid)
    }
}

lazy_static! {

    static ref REGISTRY: TransferSyntaxRegistryImpl = {
        let mut registry = TransferSyntaxRegistryImpl {
            m: HashMap::with_capacity(64),
        };

        use self::entries::*;
        let built_in_ts: [TransferSyntax; 46] = [
            IMPLICIT_VR_LITTLE_ENDIAN.erased(),
            EXPLICIT_VR_LITTLE_ENDIAN.erased(),
            EXPLICIT_VR_BIG_ENDIAN.erased(),

            ENCAPSULATED_UNCOMPRESSED_EXPLICIT_VR_LITTLE_ENDIAN.erased(),

            DEFLATED_EXPLICIT_VR_LITTLE_ENDIAN.erased(),
            JPIP_REFERENCED_DEFLATE.erased(),
            JPIP_HTJ2K_REFERENCED_DEFLATE.erased(),

            JPEG_BASELINE.erased(),
            JPEG_EXTENDED.erased(),
            JPEG_LOSSLESS_NON_HIERARCHICAL.erased(),
            JPEG_LOSSLESS_NON_HIERARCHICAL_FIRST_ORDER_PREDICTION.erased(),
            JPEG_LS_LOSSLESS_IMAGE_COMPRESSION.erased(),
            JPEG_LS_LOSSY_IMAGE_COMPRESSION.erased(),
            JPEG_2000_IMAGE_COMPRESSION_LOSSLESS_ONLY.erased(),
            JPEG_2000_IMAGE_COMPRESSION.erased(),
            JPEG_2000_PART2_MULTI_COMPONENT_IMAGE_COMPRESSION_LOSSLESS_ONLY.erased(),
            JPEG_2000_PART2_MULTI_COMPONENT_IMAGE_COMPRESSION.erased(),
            HIGH_THROUGHPUT_JPEG_2000_IMAGE_COMPRESSION_LOSSLESS_ONLY.erased(),
            HIGH_THROUGHPUT_JPEG_2000_WITH_RPCL_OPTIONS_IMAGE_COMPRESSION_LOSSLESS_ONLY.erased(),
            HIGH_THROUGHPUT_JPEG_2000_IMAGE_COMPRESSION.erased(),
            JPEG_XL_LOSSLESS.erased(),
            JPEG_XL_RECOMPRESSION.erased(),
            JPEG_XL.erased(),
            JPIP_REFERENCED.erased(),
            JPIP_HTJ2K_REFERENCED.erased(),
            MPEG2_MAIN_PROFILE_MAIN_LEVEL.erased(),
            FRAGMENTABLE_MPEG2_MAIN_PROFILE_MAIN_LEVEL.erased(),
            MPEG2_MAIN_PROFILE_HIGH_LEVEL.erased(),
            FRAGMENTABLE_MPEG2_MAIN_PROFILE_HIGH_LEVEL.erased(),
            MPEG4_AVC_H264_HIGH_PROFILE.erased(),
            FRAGMENTABLE_MPEG4_AVC_H264_HIGH_PROFILE.erased(),
            MPEG4_AVC_H264_BD_COMPATIBLE_HIGH_PROFILE.erased(),
            FRAGMENTABLE_MPEG4_AVC_H264_BD_COMPATIBLE_HIGH_PROFILE.erased(),
            MPEG4_AVC_H264_HIGH_PROFILE_FOR_2D_VIDEO.erased(),
            FRAGMENTABLE_MPEG4_AVC_H264_HIGH_PROFILE_FOR_2D_VIDEO.erased(),
            MPEG4_AVC_H264_HIGH_PROFILE_FOR_3D_VIDEO.erased(),
            FRAGMENTABLE_MPEG4_AVC_H264_HIGH_PROFILE_FOR_3D_VIDEO.erased(),
            MPEG4_AVC_H264_STEREO_HIGH_PROFILE.erased(),
            FRAGMENTABLE_MPEG4_AVC_H264_STEREO_HIGH_PROFILE.erased(),
            HEVC_H265_MAIN_PROFILE.erased(),
            HEVC_H265_MAIN_10_PROFILE.erased(),
            RLE_LOSSLESS.erased(),
            DEFLATED_IMAGE_FRAME_COMPRESSION.erased(),
            SMPTE_ST_2110_20_UNCOMPRESSED_PROGRESSIVE.erased(),
            SMPTE_ST_2110_20_UNCOMPRESSED_INTERLACED.erased(),
            SMPTE_ST_2110_30_PCM.erased(),
        ];

        // add built-in TSes manually
        for ts in built_in_ts {
            registry.register(ts);
        }

        registry
    };
}

/// Retrieve a reference to the global codec registry.
#[inline]
pub(crate) fn get_registry() -> &'static TransferSyntaxRegistryImpl {
    &REGISTRY
}

/// create a TS with an unsupported pixel encapsulation
pub(crate) const fn create_ts_stub(uid: &'static str, name: &'static str) -> Ts {
    TransferSyntax::new_ele(uid, name, Codec::EncapsulatedPixelData(None, None))
}

/// Retrieve the default transfer syntax.
pub fn default() -> Ts {
    entries::IMPLICIT_VR_LITTLE_ENDIAN
}

#[cfg(test)]
mod tests {
    use dcmnorm_encoding::TransferSyntaxIndex;

    use crate::TransferSyntaxRegistry;

    #[test]
    fn has_mandatory_tss() {
        let implicit_vr_le = TransferSyntaxRegistry
            .get("1.2.840.10008.1.2")
            .expect("transfer syntax registry should provide Implicit VR Little Endian");
        assert_eq!(implicit_vr_le.uid(), "1.2.840.10008.1.2");
        assert!(implicit_vr_le.is_fully_supported());

        // should also work with trailing null character
        let implicit_vr_le_2 = TransferSyntaxRegistry.get("1.2.840.10008.1.2\0").expect(
            "transfer syntax registry should provide Implicit VR Little Endian with padded TS UID",
        );

        assert_eq!(implicit_vr_le_2.uid(), implicit_vr_le.uid());

        let explicit_vr_le = TransferSyntaxRegistry
            .get("1.2.840.10008.1.2.1")
            .expect("transfer syntax registry should provide Explicit VR Little Endian");
        assert_eq!(explicit_vr_le.uid(), "1.2.840.10008.1.2.1");
        assert!(explicit_vr_le.is_fully_supported());

        // should also work with trailing null character
        let explicit_vr_le_2 = TransferSyntaxRegistry.get("1.2.840.10008.1.2.1\0").expect(
            "transfer syntax registry should provide Explicit VR Little Endian with padded TS UID",
        );

        assert_eq!(explicit_vr_le_2.uid(), explicit_vr_le.uid());
    }

    #[test]
    fn provides_iter() {
        let all_tss: Vec<_> = TransferSyntaxRegistry.iter().collect();

        assert!(all_tss.len() >= 2);

        // contains at least Implicit VR Little Endian and Explicit VR Little Endian
        assert!(all_tss.iter().any(|ts| ts.uid() == "1.2.840.10008.1.2"));
        assert!(all_tss.iter().any(|ts| ts.uid() == "1.2.840.10008.1.2.1"));
    }
}