dcmnorm
Fast, open-source DICOM toolkit in Rust: parse, render, transcode, reformat, and network. Ships as a CLI, a Rust library, and Node.js/Python/Java bindings.
🔗 Live demo: try the Node bindings in your browser — upload a .dcm file (or pick a bundled
sample) and see its JSON metadata, a JPEG of every frame, and per-step timings.
Install
CLIs (dcmnorm, dcmtalk) |
uv tool install dcmnorm or pipx install dcmnorm; curl -sSL pohcee.com/dcmnorm | sh (Linux, macOS); release archives and .deb; cargo install dcmnorm-cli dcmtalk (builds from source) |
| Python | pip install dcmnorm (CPython 3.9+ for import dcmnorm; the wheel also carries the CLIs) |
| Node.js | npm install dcmnorm (Node 18+) |
| Java | com.pohcee:dcmnorm plus com.pohcee:dcmnorm-natives for your platform (Java 11+), below |
| Rust | cargo add dcmnorm (crates.io) |
Java, Maven (linux-x86_64 shown; also linux-aarch_64, osx-aarch_64, osx-x86_64,
windows-x86_64, or ${os.detected.classifier} with the os-maven-plugin):
com.pohcee
dcmnorm
${dcmnorm.version}
com.pohcee
dcmnorm-natives
${dcmnorm.version}
linux-x86_64
runtime
Gradle (Kotlin DSL):
dependencies {
implementation("com.pohcee:dcmnorm:$dcmnormVersion")
runtimeOnly("com.pohcee:dcmnorm-natives:$dcmnormVersion:linux-x86_64")
}
Rust (Cargo.toml):
[]
= { = "https://github.com/pohcee/dcmnorm", = "v0.15.0" }
More options (the agent plugin, Docker, building from source): docs/install.md.
Quick start
CLI:
Python:
= # metadata only, PixelData not read
= # 8-bit pixels: frame.data, frame.shape
Node.js:
const = require;
const ds = await ;
console.log;
const = await ;
await ;
Java:
DicomDataset ds ;
System.out.;
BufferedImage image ;
ImageIO.;
Dcmnorm.;
Rust:
use ;
use ;
let scan = new;
let options = DatasetReadOptions ;
let ds = read_dataset_document?;
if let Some = ds.dataset.get.map
let frame = render_source_frame?;
let mut out = transcode_source?;
write_dicom_file?;
Each binding's README has its full API; for Java, the guide maps each common workflow to its dcm4che idiom.
Why dcmnorm
- Fast: faster than dcmtk and dcm4che in every parse, render, and transcode benchmark; DICOM → JSON takes ~3 ms whether the file is 90 KB or 29 MB (benchmarks)
- Broad: renders most DICOM imaging SOP classes, including WSI, with modality/VOI LUTs, windowing, and overlays; cine → MP4; MPR reformats (gantry tilt, Enhanced multi-frame); NIfTI/NRRD volume export; rigid CT/MR/PT registration and DICOM Spatial Registration objects
- Networked:
dcmtalkcovers C-ECHO/C-STORE/C-FIND/C-MOVE plus a storage SCP, with no dcmtk dependency - Embeddable: in-process Node.js, Python, and Java bindings, plus a Rust library crate
- Agent-ready: ships with a skill for popular AI coding assistants
- Powers dcm2bq: an open-source DICOM-to-BigQuery project under GoogleCloudPlatform
What's in this repository
dcmnorm: a library crate with DICOM file, memory, JSON conversion, and DIMSE network helpersexec/dcmnorm: a CLI for converting between DICOM, transcoded DICOM, JSON, and rendered images/raw frames, and for writing a DICOMDIRexec/dcmtalk: a DIMSE network CLI (C-ECHO/C-STORE/C-FIND/C-MOVE SCU plus a storage SCP), covering the same ground as dcmtk'sechoscu/storescu/findscu/movescu/storescpbindings/node: Node.js bindings (npm i dcmnorm) that call the library in-process via napi-rs — see that package's own README for its APIbindings/node/examples/test-website: the source for the live demo above — also runnable locally, in Docker, or deployed to your own Cloud Run project
bindings/python: Python bindings (import dcmnorm, in thedcmnormPyPI package) that call the library in-process via PyO3 — see that package's own README for its APIbindings/java: Java bindings (com.pohcee:dcmnorm+com.pohcee:dcmnorm-nativeson Maven Central;dcmnorm-java/dcmnorm-java-nativesup to 0.13.x, now relocated) that call the library in-process via the jni crate — see that package's own README for its API
Documentation
- Installing: PyPI, the agent plugin, FFmpeg for video, Cargo, release
binaries and
.debpackages, Docker - dcmnorm CLI: every option - JSON conversion, filtering, bulk data, validation, histograms, editing, rendering, texture export, MPR and volume export, overlays, batch mode, transcoding, video, JPEG 2000 codec selection, DICOMDIR, registration
- dcmtalk CLI: C-ECHO, C-STORE, C-FIND, C-MOVE and a storage SCP
- Bindings: Node.js, Python, Java and the Java guide for dcm4che users
- Benchmarks: dcmnorm vs dcmtk and dcm4che
- Building and testing: workspace layout, prerequisites, Kakadu FFI
- Releasing and packaging
- Design notes: JPEG 2000 codec evaluation, agent plugin distribution
Contributing
Issues and pull requests are welcome! Bug reports with a sample file (de-identified, please) are especially helpful. If dcmnorm is useful to you, a ⭐ helps others find it.
Before pushing, run scripts/lint.sh (rustfmt + clippy, as CI does; --fix applies the fixes).
git config core.hooksPath .githooks runs it for you on commit (rustfmt) and push (clippy).
Thanks
This workspace is built on the DICOM-rs project's Rust
DICOM crates (dicom-core, dicom-object, dicom-ul, and others) for DICOM parsing, encoding,
and the Upper Layer/association protocol.
exec/dcmtalk's subcommands (echoscu/storescu/findscu/movescu/storescp) follow the
naming and behavior established by DCMTK, the long-standing reference
DICOM toolkit.
Thanks to both projects and their maintainers.
License
Licensed under the Apache License, Version 2.0.
Bundled third-party code keeps its own license: OpenHTJ2K
(crates/dcmnorm-jpeg2000/vendor/openhtj2k) is BSD-3-Clause, see its
LICENSE.