Dicom

██████╗ ██╗ ██████╗ ██████╗ ███╗   ███╗
██╔══██╗██║██╔════╝██╔═══██╗████╗ ████║
██║  ██║██║██║     ██║   ██║██╔████╔██║
██║  ██║██║██║     ██║   ██║██║╚██╔╝██║
██████╔╝██║╚██████╗╚██████╔╝██║ ╚═╝ ██║
╚═════╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝     ╚═╝

  DICOM toolkit for Elixir · PS3.5/6/10/15/16/18

Pure Elixir DICOM toolkit for DICOM Part 10 files. Zero runtime dependencies.

Features

• P10 file parsing -- read DICOM Part 10 files into structured data sets
• P10 file writing -- serialize data sets back to Part 10 binaries with File Meta Information
• Streaming parser -- lazy, event-based parsing for large files and pipelines (stable API)
• Data dictionary -- PS3.6 tag registry (5,035 entries) with VR, VM, keyword lookup, and retired flags
• DICOM JSON -- encode/decode DataSets to/from the DICOM JSON model (PS3.18 Annex F.2) for DICOMweb
• Pixel data frames -- extract individual frames from native and encapsulated pixel data (PS3.5 §A.4)
• De-identification -- PS3.15 Basic Profile helpers with consistent UID replacement and private tag control
• Structured Reports -- reusable PS3.16 building blocks plus focused builders for TID 1500, TID 3300, and TID 3700
• Character set support -- single-byte Specific Character Set repertoires and UTF-8
• SOP Class registry -- 232 SOP Classes with modality mapping and O(1) lookup
• Transfer syntaxes -- 49 tracked (34 active + 15 retired); unknown UIDs rejected by default
• Sequences -- defined-length and undefined-length SQ with nested items
• Zero dependencies -- pure Elixir, no NIFs, no external tools

Installation

Add dicom to your mix.exs dependencies:

def deps do
  [
    {:dicom, "~> 0.7.0"}
  ]
end

Structured Reports

dicom now includes an initial PS3.16 authoring foundation:

• coded entries via Dicom.SR.Code
• content-tree construction via Dicom.SR.ContentItem
• observation context helpers via Dicom.SR.Observer
• SR document rendering via Dicom.SR.Document
• focused template builders:
  • Dicom.SR.Templates.MeasurementReport (TID 1500)
  • Dicom.SR.Templates.StressTestingReport (TID 3300)
  • Dicom.SR.Templates.ECGReport (TID 3700)

Example:

alias Dicom.SR.{Code, Measurement, MeasurementGroup}
alias Dicom.SR.Templates.MeasurementReport

measurement =
  Measurement.new(
    Code.new("8867-4", "LN", "Heart rate"),
    62,
    Code.new("/min", "UCUM", "beats per minute")
  )

group =
  MeasurementGroup.new("lesion-1", Dicom.UID.generate(),
    measurements: [measurement]
  )

{:ok, document} =
  MeasurementReport.new(
    study_instance_uid: Dicom.UID.generate(),
    series_instance_uid: Dicom.UID.generate(),
    sop_instance_uid: Dicom.UID.generate(),
    observer_name: "REPORTER^ALICE",
    procedure_reported: [Code.new("P5-09051", "SRT", "Chest CT")],
    measurement_groups: [group]
  )

{:ok, data_set} = Dicom.SR.Document.to_data_set(document)
{:ok, binary} = Dicom.write(data_set)

Current PS3.16 scope is deliberately explicit:

• implemented now:
  • SR coding primitives
  • reusable content trees
  • template identification
  • SR document rendering with Part 10 serialization
  • practical document builders for TID 1500, TID 3300, and TID 3700
• not claimed yet:
  • full CID validation across every invoked context group
  • every included sub-template of those TIDs
  • full image-reference / spatial-coordinate / segmentation linkage semantics
  • broad “complete PS3.16” conformance language

The implemented builders aim to be clean and normative within that scoped surface, but they are intentionally not marketed as full PS3.16 coverage.

Quick Start

# Parse a DICOM file
{:ok, data_set} = Dicom.parse_file("/path/to/image.dcm")

# Access attributes by tag
patient_name = Dicom.DataSet.get(data_set, Dicom.Tag.patient_name())
study_date   = Dicom.DataSet.get(data_set, Dicom.Tag.study_date())
modality     = Dicom.DataSet.get(data_set, Dicom.Tag.modality())

# Decode values with VR awareness
raw_element = Dicom.DataSet.get_element(data_set, Dicom.Tag.rows())
rows = Dicom.Value.decode(raw_element.value, raw_element.vr)

# Build a data set from scratch
ds = Dicom.DataSet.new()
    |> Dicom.DataSet.put({0x0002, 0x0002}, :UI, "1.2.840.10008.5.1.4.1.1.2")
    |> Dicom.DataSet.put({0x0002, 0x0003}, :UI, Dicom.UID.generate())
    |> Dicom.DataSet.put({0x0002, 0x0010}, :UI, Dicom.UID.explicit_vr_little_endian())
    |> Dicom.DataSet.put({0x0010, 0x0010}, :PN, "DOE^JOHN")
    |> Dicom.DataSet.put({0x0010, 0x0020}, :LO, "PAT001")

# Serialize and write
{:ok, binary} = Dicom.write(ds)
:ok = Dicom.write_file(ds, "/path/to/output.dcm")

# DataSet bracket access and Enumerable
patient = data_set[Dicom.Tag.patient_name()]
tags = Enum.map(data_set, fn {tag, _elem} -> tag end)

# Tag parsing and date/time conversion
{:ok, tag}  = Dicom.Tag.parse("(0010,0010)")
{:ok, date} = Dicom.Value.to_date("20240115")

# Inspect for quick debugging
IO.inspect(data_set)

Streaming

# Stream events lazily from a file (constant memory)
events = Dicom.stream_parse_file("/path/to/large_image.dcm")

# Filter for specific tags without loading the entire file
patient_tags =
  events
  |> Stream.filter(&match?({:element, %{tag: {0x0010, _}}}, &1))
  |> Enum.map(fn {:element, elem} -> {elem.tag, elem.value} end)

# Or materialize back into a DataSet
{:ok, data_set} =
  Dicom.stream_parse(binary)
  |> Dicom.P10.Stream.to_data_set()

DICOM Standard Coverage

Transfer syntaxes: Implicit VR LE, Explicit VR LE, Deflated Explicit VR LE, and Explicit VR BE (retired) are fully supported for read and write. Other registered syntaxes (compressed, video) are supported as metadata-only. Unknown UIDs are rejected by default; use TransferSyntax.encoding(uid, lenient: true) to fall back to Explicit VR LE.

Performance

Indicative measurements on Apple Silicon (Elixir 1.18, OTP 27):

Testing

1300+ tests, 16 property-based tests, 35 doctests at 98%+ coverage.

mix test              # 0 failures
mix test --cover      # HTML report in cover/
mix format --check-formatted

Contributing

Contributions are welcome. Please read our Contributing Guide and Code of Conduct before opening a PR.

License

MIT -- see LICENSE for details.