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

dcmnorm-transcode

dcmnorm's own fork of the DICOM transfer-syntax registry (TransferSyntaxRegistry, the table of known transfer syntax UIDs, and the codec adapters for JPEG Baseline/Extended/Lossless, JPEG 2000, RLE Lossless, and Deflated pixel data) that dcmnorm builds on.

Forked from dicom-rs's dicom-transfer-syntax-registry 0.9.1 as a mechanical, byte-for-byte transcription of src/, then trimmed and given in-house JPEG decode ownership (see below) once nothing else in the dependency graph needed its original full surface.

Enabled features mirror what dcmnorm's Cargo.toml actually requests: native (JPEG + RLE), deflate, openjpeg-sys. Not enabled: openjp2 (alternate JPEG2000 backend, openjpeg-sys is used instead), simd (available for jpeg-encoder but not currently requested).

Codec ownership

  • JPEG decode (baseline/extended/lossless, transfer syntaxes .4.50/.51/.57/.70) is now backed by crates/dcmnorm-jpeg, an in-house crate forked from jpeg-decoder 0.3.2 — see that crate's own README for why. JPEG encode (baseline lossy re-encode only) still uses the external jpeg-encoder crate: it's unmodified and works fine, so per the ownership criterion ("own it unless it's a genuinely decoupled codec that already works with no modifications") it stays external.
  • RLE Lossless (.2.5, adapters/rle_lossless.rs) has always been dcmnorm's own code with zero external dependency — nothing to change here, it was already in-house.
  • Deflate (dataset-level Deflated Explicit VR LE, the rare "Deflated Image Frame Compression" pixel adapter, and an unrelated internal use in volume_export.rs/texture_export.rs for GPU-cache compression) stays on flate2 — generic, standard DEFLATE compression with zero DICOM-specific value in re-implementing it.
  • JPEG 2000/HTJ2K (adapters/jpeg2k.rs, via the jpeg2k crate wrapping openjpeg-sys) stays external and is the real, live default JPEG2000 decode path (src/dicom_io/io.rs's Kakadu-then-OpenJPEG fallback) — correctly out of scope per the original dicom-rs-removal plan: hand-writing a compliant JPEG2000 codec is far riskier than the value it'd add.
  • JPEG-LS and JPEG XL have no adapters in this crate at all anymore (see "Trimmed to dcmnorm's actual surface" below) — dcmnorm's own JPEG-LS support calls charls directly, bypassing this registry entirely, and nothing in the wild has ever required JPEG XL decode.

Trimmed to dcmnorm's actual surface

Originally kept as a full byte-identical port because dicom-object and dicom-ul (both since fully replaced) needed the complete upstream API surface, not just what dcmnorm itself calls. Once both were gone, this was trimmed:

  • Deleted adapters/jpegls.rs and adapters/jpegxl.rs — both gated behind Cargo features (charls, jxl-oxide/zune-jpegxl) that were never requested by any real build in this workspace (confirmed via cargo tree -e features). Their transfer syntax UIDs remain registered as registry-completeness stubs in entries.rs (Codec::None — metadata only, no codec code), so lookups/negotiation against real-world senders still resolve the UID correctly.
  • Deleted adapters/encapsulated.rs — it wasn't even wired into adapters/mod.rs and didn't compile as-is (leftover cruft from the fork); the real, working implementation of its transfer syntax (Encapsulated Uncompressed Explicit VR LE) lives in adapters/uncompressed.rs
    • entries.rs and was untouched by this deletion.
  • Removed the native_windows (deprecated alias for native), openjpeg-sys-threads, charls, charls-vcpkg, jxl-oxide, zune-jpegxl, zune-jpegxl-threads, rayon, and inventory-registry Cargo features, and their corresponding optional dependencies — none were ever requested by any build target in this workspace.
  • default = [] (was default = ["rayon", "simd"]) so a direct cargo build --workspace/cargo test --workspace doesn't silently pull in features the real dcmnorm/dcmtalk/binding builds never request.

Left alone (confirmed live or confirmed cheap-and-harmless, not trim candidates): decode::/encode::/text::/adapters.rs/transfer_syntax/ in dcmnorm-encoding (all reachable via the live TransferSyntaxRegistry dispatch table); the MPEG/JPIP/SMPTE/HTJ2K stub registry entries in entries.rs (metadata-only Codec::None rows, negligible cost, useful for negotiation completeness against real-world senders); JPEG Extended/Lossless variants and Deflated-Explicit-VR-LE/JPIP-Deflate/ Deflated-Image-Frame-Compression/JPEG2000-Part-2-multi-component (all share live, tested codec code paths — untested by name in tests.rs, but not separable dead code).

What was left out

Upstream's own tests/ directory (~1500 lines, its dev-dependencies were dicom-test-files — a crate that fetches real sample DICOM files — and dicom-object) was deliberately not ported. dcmnorm's own test suite plus its test/files/*.dcm fixtures are the acceptance bar for this fork, and pulling in a network-fetched sample-file dependency was more scope than that needed.

Naming history

Originally kept the package/lib name dicom-transfer-syntax-registry/ dicom_transfer_syntax_registry (patched in via [patch.crates-io]) because dicom-object and dicom-ul both still depended on it. Fully renamed to dcmnorm-transcode/dcmnorm_transcode once both were replaced by dcmnorm-object and dcmnorm-dimse and nothing in the dependency graph needed the original name anymore.

Upstream changes ported since the fork

Selectively ported from dicom-rs after 0.9.1 (each commit message names the upstream commit):

  • adapters/rle_lossless.rs + alloc.rs: bounds-checked segment slicing and allocation guards against implausible compression ratios (upstream 10f9b6db). The ratio limit is 64:1, PackBits' actual maximum, rather than upstream's 32:1, which refuses valid mostly-blank images; and the RLE header itself is validated (64 bytes, at most 15 segments), as is each segment's decoded length, neither of which upstream checks. Not from upstream: each segment's bytes are placed by the PS3.5 Annex G layout (sample by sample, most significant byte first, into little-endian interleaved output) rather than the inherited index expression, which shifted 8-bit single-sample images by one byte and byte-swapped 16-bit colour (#41); the header's segment count must match BitsAllocated x SamplesPerPixel; and 32-bit samples decode.
  • adapters/jpeg.rs: color JPEG Baseline output is labeled YBR_FULL_422 (upstream 636ae060), or YBR_FULL when jpeg-encoder doesn't subsample chroma, instead of RGB.