CLI Tool
The dcmfx
CLI tool makes the capabilities of DCMfx available on the command line.
Installation
Select your platform below to see its installation instructions.
Windows
Download the latest version of dcmfx.exe
for Windows here.
macOS
Install Homebrew, then install DCMfx using the provided tap:
brew tap dcmfx/tap
brew install dcmfx
Linux
For Ubuntu, Debian, Linux Mint, and other Debian-based distributions, an APT repository is provided:
shecho "deb [trusted=yes] https://dcmfx.github.io/apt-repository stable main" | sudo tee /etc/apt/sources.list.d/dcmfx.list sudo apt update sudo apt install dcmfx
For Red Hat, Fedora, Amazon Linux, and other RPM-based distributions, a YUM repository is provided:
shecho -e "[dcmfx]\nname=DCMfx\nbaseurl=http://dcmfx.github.io/yum-repository\nenabled=1\ngpgcheck=0" | sudo tee /etc/yum.repos.d/dcmfx.repo sudo yum makecache sudo yum install dcmfx
For Arch Linux, a package is provided in the Arch User Repository (AUR). Install it with your preferred AUR helper (e.g. Yay):
shyay -S dcmfx
- Alternatively, download the latest binary or package here and install it manually.
Usage
After installation, run dcmfx --help
to see the available commands:
$ dcmfx --help
DCMfx is a CLI tool for working with DICOM and DICOM JSON
Usage: dcmfx [OPTIONS] <COMMAND>
Commands:
get-pixel-data Extracts pixel data from DICOM P10 files, writing it to image
and video files
modify Modifies the content of DICOM P10 files
print Prints the content of DICOM P10 files
json-to-dcm Converts DICOM JSON files to DICOM P10 files
dcm-to-json Converts DICOM P10 files to DICOM JSON files
help Print this message or the help of the given subcommand(s)
Options:
--print-stats Write timing and memory stats to stderr on exit
-h, --help Print help
-V, --version Print version
Examples
Print a DICOM P10 file's data set to stdout:
shdcmfx print input.dcm
Convert a DICOM P10 file to a DICOM JSON file:
shdcmfx dcm-to-json input.dcm
To pretty-print the DICOM JSON directly to stdout:
shdcmfx dcm-to-json input.dcm --pretty --output-filename -
Convert a DICOM JSON file to a DICOM P10 file:
shdcmfx json-to-dcm input.json
Extract pixel data from a DICOM P10 file to one image file per frame:
shdcmfx get-pixel-data input.dcm
Each frame of pixel data can be decoded and written to PNG, 16-bit PNG, JPEG, or WebP Lossless images:
shdcmfx get-pixel-data input.dcm --format png dcmfx get-pixel-data input.dcm --format png16 dcmfx get-pixel-data input.dcm --format jpg --jpeg-quality 90 dcmfx get-pixel-data input.dcm --format webp
Single channel data can also specify a VOI window center and width and/or a well-known color palette to use:
shdcmfx get-pixel-data input.dcm --format png --voi-window 500 2000 \ --color-palette hot-iron
The images can be rotated or flipped by specifying a transform:
shdcmfx get-pixel-data input.dcm --format jpg --transform rotate90 dcmfx get-pixel-data input.dcm --format jpg --transform flip-vertical
Extract pixel data from a DICOM P10 file to an MP4 video:
shdcmfx get-pixel-data input.dcm --format mp4
Additional options are available to specify the codec, video quality, encoder preset, pixel format, frame rate override, and so on.
Rewrite a DICOM P10 file. This will convert the specific character set to UTF-8, change sequences and items to undefined length, and correct invalid files where possible:
shdcmfx modify input.dcm --output-filename output.dcm
Modify a DICOM P10 file to use the 'Deflated Explicit VR Little Endian' transfer syntax with maximum compression:
shdcmfx modify input.dcm output.dcm \ --transfer-syntax deflated-explicit-vr-little-endian \ --zlib-compression-level 9
The
modify
command can only convert between the following transfer syntaxes:- Implicit VR Little Endian
- Explicit VR Little Endian
- Deflated Explicit VR Little Endian
- Explicit VR Big Endian
Conversion between other transfer syntaxes is not supported.
Anonymize a DICOM P10 file in-place by removing all identifying data elements and private data elements:
shdcmfx modify input.dcm --in-place --anonymize
Note that this does not remove any identifying information baked into pixel data or other binary data elements.
Remove the top-level '(7FE0,0010) Pixel Data' data element from a DICOM P10 file:
shdcmfx modify input.dcm --in-place --delete-tag 7FE00010
Multiple data elements can be deleted by using a comma as a separator:
shdcmfx modify input.dcm --in-place --delete-tag 00100010 --delete-tag 00100030
Gleam CLI
The above examples assume the Rust version of the CLI tool is in use, however most functionality is also supported by the Gleam version of the CLI, which can be run with gleam run
in /src/gleam/dcmfx_cli
.
The Gleam CLI is primarily used when working on the Gleam implementation of DCMfx. The Rust CLI is recommended for regular use as it is faster, has more features, and is a single standalone binary.