Dcmix

A DICOM library for Elixir - read, write, and manipulate DICOM files.

Dcmix (pronounced "DCM-icks") is a pure Elixir implementation for working with DICOM medical imaging files, inspired by dcmtk and dicom-rs.

⚠️ Experimental Status

This project is in an experimental stage and is not yet recommended for production use. A significant portion of this codebase was generated with AI assistance and has not been fully vetted for correctness, security, or compliance with the DICOM standard. Use at your own risk and please report any issues you encounter.

Features

• Read and parse DICOM Part 10 files
• Write DICOM files with proper file meta information
• Multiple transfer syntax support (Implicit VR LE, Explicit VR LE/BE)
• Export to JSON, XML, and image formats (PNG, PPM, PGM)
• Import from JSON, XML, and image files
• Human-readable dump output (dcmdump style)
• DICOM networking: C-FIND SCU (query remote PACS servers)
• Private tag support
• Mix tasks for CLI usage

Installation

Add dcmix to your list of dependencies in mix.exs:

def deps do
  [
    {:dcmix, github: "avandra/dcmix"}
  ]
end

Quick Start

Reading DICOM Files

# Read a DICOM file
{:ok, dataset} = Dcmix.read_file("patient.dcm")

# Get element values
patient_name = Dcmix.get_string(dataset, "PatientName")
rows = Dcmix.get(dataset, {0x0028, 0x0010})

# Dump contents
IO.puts(Dcmix.dump(dataset))

Writing DICOM Files

dataset = Dcmix.new()
|> Dcmix.put({0x0010, 0x0010}, :PN, "Doe^John")
|> Dcmix.put({0x0010, 0x0020}, :LO, "12345")
|> Dcmix.put({0x0008, 0x0060}, :CS, "CT")

:ok = Dcmix.write_file(dataset, "output.dcm")

Export Formats

# Export to JSON (DICOM JSON Model)
{:ok, json} = Dcmix.to_json(dataset, pretty: true)

# Export to XML (Native DICOM Model)
{:ok, xml} = Dcmix.to_xml(dataset)

# Export pixel data to image
:ok = Dcmix.to_image(dataset, "output.png")

Querying a PACS Server

# Build a query
query =
  Dcmix.DataSet.new()
  |> Dcmix.DataSet.put_element({0x0010, 0x0010}, :PN, "")
  |> Dcmix.DataSet.put_element({0x0008, 0x0020}, :DA, "20250101-20251231")

# Query a remote DICOM server
{:ok, datasets} = Dcmix.find("localhost:4242", query,
  calling_ae_title: "MY_SCU",
  called_ae_title: "PACS_AE"
)

Enum.each(datasets, fn ds ->
  IO.puts(Dcmix.DataSet.get_string(ds, {0x0010, 0x0010}))
end)

CLI Tools

mix dcmix.dump patient.dcm
mix dcmix.to_json --pretty patient.dcm output.json
mix dcmix.to_xml patient.dcm output.xml
mix dcmix.to_image --window auto patient.dcm output.png

Documentation

• Detailed Usage Guide - Pixel data, private tags, import operations
• Transfer Syntax Support - Supported transfer syntaxes
• Roadmap - Current and planned features

Development

mix deps.get          # Install dependencies
mix test              # Run tests
mix test --cover      # Run tests with coverage
mix credo --strict    # Static analysis
mix sobelow           # Security analysis

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

• Inspired by dcmtk and dicom-rs
• DICOM standard from NEMA