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:

echo "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:

echo -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):
sh
```
yay -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:
  archive         Archives one or more DICOM P10 files into a directory or ZIP
                  file alongside a DICOMDIR file
  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
  list            Lists DICOM P10 files in one or more directories
  rewrite         Rewrites DICOM P10 files to correct and recover their data
  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

INFO

Input and output filenames can be paths to local files, "-" for stdin/stdout, or an object URL on Amazon S3 (s3://), Google Cloud Storage (gs://), or Azure Blob Storage (az://).

Print a DICOM P10 file's data set to stdout:
sh
```
dcmfx print input.dcm
```
Convert a DICOM P10 file to a DICOM JSON file:
sh
```
dcmfx dcm-to-json input.dcm
```
To pretty-print the DICOM JSON directly to stdout:
sh
```
dcmfx dcm-to-json input.dcm --pretty --output-filename -
```
Convert a DICOM JSON file to a DICOM P10 file:
sh
```
dcmfx json-to-dcm input.json
```

Extract pixel data from a DICOM P10 file to one image file per frame:

dcmfx get-pixel-data input.dcm

Each frame of pixel data can be converted to PNG, 16-bit PNG, or JPEG images:

dcmfx 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

For monochrome pixel data, a VOI window center and width and/or a well-known color palette can be specified:

dcmfx 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:

dcmfx 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:
sh
```
dcmfx 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:
sh
```
dcmfx rewrite input.dcm --output-filename output.dcm
```
Modify a DICOM P10 file's transfer syntax:
sh
```
dcmfx modify input.dcm --output-filename output.dcm \
  --transfer-syntax explicit-vr-little-endian
```
Pixel data will be automatically transcoded as appropriate. See the output of dcmfx modify --help for details of supported transfer syntaxes.
De-identify a DICOM P10 file in-place following the Basic Application Level Confidentiality Profile defined in DICOM PS3.15 Annex E, which removes or replaces identifying data elements, replaces UIDs, and removes private data elements:
sh
```
dcmfx modify input.dcm --in-place --deidentify
```
Replacement UIDs are derived from the original UIDs using a secret that is randomly generated for each run, so references between the files de-identified in a single run stay intact. To keep UIDs consistent across separate runs, pass the same secret each time with --deidentify-uid-secret, or set it in the DCMFX_DEIDENTIFY_UID_SECRET environment variable to keep it out of the process list and shell history.
The profile's options defined in DICOM PS3.15 Annex E.3 can be enabled with --deidentify-options to retain information that the profile would otherwise remove, e.g. to retain dates shifted by a consistent number of days and the content of Structured Reports:
sh
```
dcmfx modify input.dcm --in-place --deidentify \
  --deidentify-options retain-modified-dates,clean-structured-content \
  --deidentify-date-shift -100
```
The supported options are retain-patient-characteristics, retain-device-identity, retain-institution-identity, retain-uids, retain-full-dates, retain-modified-dates, and clean-structured-content. See the output of dcmfx modify --help for details of each option.
Note that pixel data is not inspected: identifying information burned into pixel data, recognizable features such as faces, and metadata inside the frames of encapsulated pixel data are not detected or removed, however burned-in text at a fixed position may be able to be removed using the --mask or --crop arguments. Free text in content items retained by clean-structured-content is not scanned for identifying information. Encapsulated documents such as PDFs are removed rather than replaced, and a DICOMDIR loses its directory records, so a DICOMDIR should instead be regenerated from the de-identified files.
Remove the top-level '(7FE0,0010) Pixel Data' data element and all private data elements from a DICOM P10 file:
sh
```
dcmfx modify input.dcm --in-place --delete 7FE00010 --delete-private
```
Multiple data elements can be deleted by specifying --delete multiple times:
sh
```
dcmfx modify input.dcm --in-place --delete 00100010 --delete 00100030
```
Print a list of all DICOM files under the current directory:
sh
```
dcmfx list .
```
Print a list of all DICOM files under the current directory as JSON Lines that includes the value of each DICOM's '(0008,0018) SOP Instance UID' data element, followed by a summary of their transfer syntaxes and SOP classes:
sh
```
dcmfx list . --format json-lines --select 00080018 --summarize
```
Archive all *.dcm files under the current directory into a compressed ZIP file along with a DICOMDIR, and name the archived DICOMs using the schema PA000000/ST000000/SE000000/IM000000.
sh
```
dcmfx archive **/*.dcm --output-filename archive.zip \
  --path-structure patient-study-series --zip-compression-method deflate \
  --deflate-compression-level fast
```

CLI Tool ​

Installation ​

Usage ​

Examples ​

CLI Tool

Installation

Usage

Examples