Skip to content

DICOM-Decoder 1.1.2

Choose a tag to compare

View all tags
@ThalesMMS ThalesMMS released this 19 May 08:11
· 17 commits to main since this release
1.1.2
2e943d6

DICOM-Decoder 1.1.2

These notes cover the changes since the last previously published release, 1.0.1. The short-lived 1.1.1 release object was removed after discovering a volume geometry regression. Tag 1.1.2 is the intended replacement release.

Compare: 1.0.1...1.1.2

Summary

This release expands DICOM-Decoder from a single-file/image decoder into a broader Swift DICOM toolkit. It adds directory and ZIP series loading, volume assembly, DICOM geometry handling, async and batch APIs, a SwiftUI component module, a command-line tool, broader documentation, benchmarking infrastructure, and substantially expanded tests.

The final patch in this release fixes the release-blocking geometry issue: when the real slice center-to-center distance derived from ImagePositionPatient differs from tag-derived Z spacing, volume reconstruction now uses the IPP deltas. SliceThickness is nominal and can differ from the physical distance between adjacent slice centers.

DICOM geometry and series loading

  • Added DicomDecodedSeries and DicomSeriesLoader APIs for loading a DICOM directory, ZIP archive, or individual DICOM source into a contiguous decoded series.
  • Added ZIP source handling through ZIPFoundation, with temporary extraction and cleanup coverage.
  • Added slice ordering by projecting ImagePositionPatient onto the normal derived from ImageOrientationPatient, with fallback behavior for series where positional metadata is absent.
  • Added geometry extraction for ImageOrientationPatient, ImagePositionPatient, PixelSpacing, slice spacing/thickness, origin, row/column direction vectors, and dimensions. Added volume assembly for single-channel 16-bit series, preserving signed and unsigned data paths and producing raw and modality-adjusted buffers where appropriate.
  • Added progress and warning reporting for decoded series loads.
  • Added validation for inconsistent series geometry, unsupported pixel formats, missing DICOM files, empty sources, and unsafe ZIP input.
  • Fixed Z spacing selection for volume reconstruction: reliable IPP-derived spacing now overrides nominal tag-derived spacing when both are present. Tag-derived spacing remains the fallback when IPP deltas cannot be computed.
  • Added regression coverage for the case where tag-derived Z spacing is 2.0 but IPP slice centers are spaced at 1.0.

Decoder API modernization

  • Split the decoder implementation into focused files for loading, metadata, pixels, range pixels, validation, async access, V2 value APIs, DICOM tag APIs, and legacy compatibility.
  • Added throwing initializers and static factory methods for clearer error handling.
  • Added async/await loading paths and async initializers for non-blocking use in applications.
  • Added batch loading APIs and protocol-oriented service interfaces.
  • Added type-safe metadata access through DicomTag while preserving raw-tag access for custom and private tags.
  • Added structured value types such as window settings, pixel spacing, rescale parameters, geometry values, and related Codable support.
  • Added richer DICOM error cases and validation status reporting.
  • Added patient/study/series model helpers and metadata grouping utilities.
  • Renamed the Swift package to DICOMDecoder while keeping the public DicomCore product.

Pixel access, transfer syntaxes, and memory behavior

  • Kept native JPEG Lossless support and refactored the implementation into marker parsing, prediction, pixel decoding, Huffman, bitstream, and shared type components.
  • Expanded JPEG Lossless tests for prediction selection values, marker parsing, byte stuffing, truncated data, invalid tables, and conformance fixture hooks.
  • Added best-effort compressed pixel support paths around existing decoder capabilities.
  • Added range-based pixel access for 8-bit, 16-bit, and 24-bit data so callers can process regions without always materializing full images.
  • Added memory-mapped data streaming behavior for large inputs.
  • Added downsampling helpers for preview and thumbnail workflows.
  • Added explicit handling and tests for endian conversion, signed pixel normalization, MONOCHROME1 inversion, and RGB access paths.
  • Added buffer pooling and memory-pressure handling utilities to reduce repeated large allocations in series and pixel workloads.

Windowing and image processing

  • Expanded DCMWindowingProcessor with batch processing, statistics, named presets, preset suggestions, and enhancement helpers.
  • Added vDSP-based CPU windowing as the baseline path.
  • Added Metal-backed windowing support with fallback behavior when Metal is not available.
  • Added benchmark tooling for comparing vDSP and Metal windowing.
  • Added Hounsfield conversion helpers, automatic window suggestions, quality metrics, histogram equalization helpers, and noise-reduction helpers.
  • Split DICOM dictionary resources into core, imaging, and RT/specialized dictionaries.

SwiftUI module and example app

  • Added the DicomSwiftUI product with image display, metadata display, series navigation, and windowing controls.
  • Added view models for image display, series navigation, windowing, and preview data.
  • Added rendering utilities for converting decoded DICOM pixels into displayable images.
  • Added preview helpers and mock decoder support for SwiftUI previews and tests.
  • Added a runnable DicomSwiftUIExample target with document picking, study browsing, metadata, image, series, and windowing examples.

Command-line tool

  • Added the dicomtool executable.
  • Added commands for inspection, validation, extraction, and batch workflows.
  • Added CLI output formatting, image export utilities, validation issue classification, and smoke/integration tests.

Documentation and developer tooling

  • Expanded the README, getting started guide, usage examples, glossary, and troubleshooting documentation.
  • Added DocC articles, tutorials, and sample code for core decoding, series loading, migration, performance, and window/level workflows.
  • Added benchmark documentation and scripts for repeatable performance reports.
  • Added release process documentation and VS Code launch configuration.
  • Updated CI scheme detection and package workflow handling during the development cycle.

Testing

  • Added extensive unit, integration, performance, protocol, SwiftUI, CLI, series loading, JPEG Lossless, metadata, windowing, and memory-pool coverage.
  • Validation used for this release:
    • swift test
    • Result: 1698 tests executed, 9 skipped, 0 failures.

Compatibility notes

  • Products in this release:
    • DicomCore
    • DicomSwiftUI
    • dicomtool
    • DicomSwiftUIExample
  • Supported package platforms remain iOS 13+ and macOS 12+.
  • The decoder remains a research/prototype toolkit and is not clinical validation or regulatory clearance.
  • Some optional JPEG Lossless conformance tests skip unless external compressed DICOM fixtures are supplied.
Assets 2
Loading