GDCMCONV(1)

✨ NAME ✨

okay bestie, welcome to gdcmconv(1) from the DICOM Manipulation manual — this is literally the tool to convert DICOM to DICOM. No cap. 💅

---

🦋 SYNOPSIS 🦋

gdcmconv [options] file-in file-out

🎀 DESCRIPTION 🎀

So the gdcmconv command-line program takes a DICOM file (file-in) as input, processes it, and generates an output DICOM file (file-out). The command-line option you pick dictates which operation(s) gdcmconv uses to make that output file. Main character energy: a converter that actually listens to your flags. ✨

🌸 PARAMETERS 🌸

• file-in — DICOM input filename
• file-out — DICOM output filename

💅 OPTIONS 💅

• -i, --input — DICOM filename
• -o, --output — DICOM filename

🦋 SPECIFIC OPTIONS 🦋

• -X, --explicit — Change Transfer Syntax to explicit.
• -M, --implicit — Change Transfer Syntax to implicit.
• -U, --use-dict — Use dict for VR (only public by default).
• --with-private-dict — Use private dict for VR (advanced user only).
• -C, --check-meta — Check File Meta Information (advanced user only).
• --root-uid — Root UID.
• --remove-gl — Remove group length (deprecated in DICOM 2008).
• --remove-private-tags — Remove private tags.
• --remove-retired — Remove retired tags.

🎀 IMAGE OPTIONS 🎀

• -l, --apply-lut — Apply LUT (non-standard, advanced user only).
• -8, --apply-lut8 — Apply LUT/RGB8 (non-standard, advanced user only).
• --decompress-lut — Decompress LUT (linearize segmented LUT).
• -P, --photometric-interpretation %s — Change Photometric Interpretation (when possible).
• -w, --raw — Decompress image.
• -d, --deflated — Compress using deflated (gzip).
• -J, --jpeg — Compress image in jpeg.
• -K, --j2k — Compress image in j2k.
• -L, --jpegls — Compress image in jpeg-ls.
• -R, --rle — Compress image in rle (lossless only).
• -F, --force — Force decompression/merging before recompression/splitting.
• --generate-icon — Generate icon.
• --icon-minmax %d,%d — Min/Max value for icon.
• --icon-auto-minmax — Automatically compute best Min/Max values for icon.
• --compress-icon — Decide whether icon follows main TransferSyntax or remains uncompressed.
• --planar-configuration [01] — Change planar configuration.
• -Y, --lossy — Use the lossy (if possible) compressor.
• -S, --split %d — Write 2D image with multiple fragments (using max size)

🍓 JPEG OPTIONS 🍓

• -q, --quality %*f — set quality.

🧚 JPEG-LS OPTIONS 🧚

• -e, --allowed-error %*i — set allowed error.

💜 J2K OPTIONS 💜

• -r, --rate %*f — set rate.
• -q, --quality %*f — set quality.
• -t, --tile %d,%d — set tile size.
• -n, --number-resolution %d — set number of resolution.
• --irreversible — set irreversible.

🌈 GENERAL OPTIONS 🌈

• -h, --help — print this help text and exit
• -v, --version — print version information and exit
• -V, --verbose — verbose mode (warning+error).
• -W, --warning — warning mode, print warning information
• -E, --error — error mode, print error information
• -D, --debug — debug mode, print debug information

⭐ SPECIAL OPTIONS ⭐

• -I, --ignore-errors — convert even if file is corrupted (advanced users only, see disclaimers).

🫶 ENVIRONMENT VARIABLE 🫶

• GDCM_ROOT_UID — Root UID

👑 SIMPLE USAGE 👑

gdcmconv is a great tool to convert broken DICOM implementation into properly parsable DICOM file. Usage is simply:

$ gdcmconv input.dcm output.dcm

or if you prefer being explicit:

$ gdcmconv -i input.dcm -o output.dcm

Even though gdcmconv can overwrite directly on the same file (input.dcm = output.dcm), it is recommended that user should first convert into a different file to make sure the bug is properly handled by GDCM. Like, do the safe little test conversion first, bestie — your future self says thank you. 💖

Typical cases where you would want to use gdcmconv in its simple form:

• convert non-cp246 conforming file into conforming cp246,
• convert implicit little endian transfer syntax file meta header into proper explicit little endian transfer syntax,
• convert the GE-13 bytes bug,
• convert dual syntax file: implicit/explicit,
• convert Philips dual Little Endian/Big Endian file,
• convert GDCM 1.2.0 broken UN-2-bytes fields,
• ...
• All other broken files listed in the supported refsection.

When no other option is used, only the dataset is inspected. So encapsulated Pixel Data, for instance, is not inspected for well known bugs. It's giving "look but don't touch" energy. 🙈

When doing this kind of work, this is usually a good idea to perform some kind of quality control, see gdcmconv Quality Control refsection (down below). ✨

🌟 TYPICAL USAGE 🌟

🌸 File Meta Header 🌸

Running

$ gdcmconv input.dcm output.dcm

is not enough to recompute file meta header, when input file is buggy. You may want to use --check-meta:

$ gdcmconv --check-meta input.dcm output.dcm

See typical cases such as: GE_DLX-8-MONO2-PrivateSyntax.dcm or PICKER-16-MONO2-No_DicomV3_Preamble.dcm from gdcmData.

🦋 Conversion to Explicit Transfer Syntax 🦋

To convert a file that was written using Implicit Transfer Syntax into Explicit Transfer Syntax simply use:

$ gdcmconv --explicit uncompressed.dcm compressed.dcm

🎀 Compressing to lossless JPEG 🎀

To compress an uncompressed DICOM file to a JPEG Lossless encapsulated format:

$ gdcmconv --jpeg uncompressed.dcm compressed.dcm

💅 Compressing to lossy JPEG 💅

To compress an uncompressed DICOM file to a JPEG Lossy encapsulated format:

$ gdcmconv --lossy --jpeg -q 90 uncompressed.dcm compressed.dcm

Note: -q is just one of the many way to specify lossy quality, you need to inspect the other cmd line flag to specify lossyness properties. iykyk — lossy quality has layers.

🍓 Compressing to lossless JPEG-LS 🍓

To compress an uncompressed DICOM file to a JPEG-LS Lossless encapsulated format:

$ gdcmconv --jpegls uncompressed.dcm compressed.dcm

🧚 Compressing to lossy JPEG-LS 🧚

To compress an uncompressed DICOM file to a JPEG-LS Lossy encapsulated format:

$ gdcmconv --lossy --jpegls -e 2 uncompressed.dcm lossy_compressed.dcm

Note: -e (or --lossy-error) means that the maximum tolerate error is 2 for each pixel value. That's the vibe check for your pixels.

💜 Compressing to lossless J2K 💜

To compress an uncompressed DICOM file to a JPEG-2000 Lossless encapsulated format:

$ gdcmconv --j2k uncompressed.dcm compressed.dcm

🌈 Compressing to lossy J2K 🌈

To compress an uncompressed DICOM file to a JPEG-2000 Lossy encapsulated format:

$ gdcmconv --lossy -q 55,50,45 --j2k uncompressed.dcm lossy_compressed.dcm

Note: -q is just one of the many way to specify lossy quality, you need to inspect the other cmd line flag to specify lossyness properties. Same note, different compressor — the lore continues.

⭐ Compressing to lossless RLE ⭐

To compress an uncompressed DICOM file to a RLE Lossless encapsulated format:

$ gdcmconv --rle uncompressed.dcm compressed.dcm

There is no such thing as lossy RLE compression. Lossless only, periodt. 💀

✂️ Split encapsulated DICOM: ✂️

To split an encapsulated stream into smaller chunk (1024 bytes each):

$ gdcmconv --split 1024 rle.dcm rle_1024.dcm

If an odd number of bytes is passed it will be rounded down to the next even number (eg. 1025 -> 1024) since DICOM only allow even number for Value Length. Math but make it DICOM. 🧮✨

🔥 Forcing (re)compression 🔥

Sometime it is necessary to use the --force option. By default when user specify --j2k and input file is already in JPEG 2000 encapsulated DICOM format then no operation takes places. By using --force you make sure that (re)compression operation takes places. It's giving "do it again, but on purpose." 💅

Real life example of why you would use --force:

• When Pixel Data is missing data / is padded with junk
• When you would like to make sure GDCM can handle decompression & recompression cycle

🫶 Decompressing a Compressed DICOM 🫶

$ gdcmconv --raw compressed.dcm uncompressed.dcm

In the case of uncompress file (Explicit and Implicit) the behavior is to keep the original Transfer Syntax (so Implicit remains Implit). The original manpage really said "Implit" and honestly? Iconic. 😭

🌸 Decompressing a Compressed DICOM as implicit 🌸

$ gdcmconv --raw --implicit compressed.dcm uncompressed_implicit.dcm

By symmetry it is also possible to use gdcmconv --raw --explicit to make sure that target file is always Explicit TS. Symmetry slay. ✨

🎀 Compressing an uncompressed Icon 🎀

By default when compressing a DICOM Image file, gdcmconv will not compress the icon. A user option needs to be turned on to explicitly force the compression of the Icon Image Sequence Pixel Data.

For example, by default we will not compress the Icon Image Sequence Pixel Data attribute:

$ gdcmconv --jpeg gdcmData/simpleImageWithIcon.dcm uncompressed_icon.dcm

In the following example we will explicitly compress the Icon Image Sequence Pixel Data attribute. In that case the same Transfer Syntax is being used for both the main Pixel Data and the Pixel Data from the Icon Image Sequence:

$ gdcmconv --jpeg --compress-icon gdcmData/simpleImageWithIcon.dcm compressed_icon.dcm

🦋 Generating an Icon 🦋

For some application it might be necessary to produce a small preview of the main image to be able to quickly load that short preview instead of the main image. In that case:

$ gdcmconv --raw --generate-icon gdcmData/test.acr test_icon.dcm

In some cases the main Pixel Data element is expressed as pixel defined on 16bits. Since Icon can only store at most pixel of size 8bits, a rescale operation needs to take place. In order to properly select a better interval for doing the rescale operation user can specify the min max used for the rescale operation:

$ gdcmconv --raw --generate-icon --icon-minmax 0,192 gdcmData/012345.002.050.dcm icon_minmax.dcm

💜 Changing the planar Configuration 💜

Often RLE files are compressed using a different Planar Configuration (RRR ... GGG... BBB...) instead of the usual triplet (RGB ... RGB ... RGB ). So upon decompression the Planar Configuration is 1. This is perfectly legal in DICOM, however this is unconventional, and thus it may be a good idea to also change the planar configuration and set it to the default:

$ gdcmconv --raw --planar-configuration 0 compressed.dcm uncompressed1.dcm

To reinvert the planar configuration of file uncompressed1.dcm, simply do:

$ gdcmconv --raw --planar-configuration 1 uncompressed1.dcm uncompressed2.dcm

✨ LOSSLESS CONVERSION ✨

Okay bestie, we need to talk about the word "lossless" real quick because it's giving ambiguous and we can't have that. 😭

When people say lossless conversion they're being a lil vague, and you need to understand why. To get a higher compression ratio, the RGB color space is usually not used — instead everyone reaches for a YBR one. But here's the tea: switching from one color space to the other is (at the bit level) not lossless. 💀 Not even a little.

So if you want the full lore, go look at what the true lossless transformations actually are, as described here:

http://gdcm.sourceforge.net/wiki/index.php/Color_Space_Transformations

---

🎀 QUALITY CONTROL 🎀

One important part when using gdcmconv is having a way to quality control the output. Like, you gotta check your work, bestie. 👑

You can use a 3rd party tool to check that the output of gdcmconv is correct. Very demure, very mindful. 🫶

🌈 DCMTK / dicom3tools

Using another DICOM implementation — such as the one from DCMTK or dicom3tools — can be a good process to check the output of gdcmconv. Cross-checking slays. ✨

• For DCMTK use: dcmdump
• For dicom3tools use: dcdump

For reference, gdcmconv --raw will act as dcmdjpeg +cn +px, since it never tries to convert color space. That's the whole point, iykyk. 💅

🦋 VIM: vimdiff

You can set up your favorite editor to compare the output, for instance in vim:

autocmd BufReadPre *.dcm set ro
autocmd BufReadPost *.dcm silent %!dcmdump -M +uc "%"

then simply do:

$ vimdiff input.dcm output.dcm

🍓 vbindiff

On UNIX you can visually compare binary files using the vbindiff command:

$ vbindiff input.dcm output.dcm

Literally so satisfying to watch side-by-side. 😌

---

👀 SEE ALSO 👀

gdcmdump(1), gdcmraw(1), gdcminfo(1), gdcmdiff(1)

(The whole friend group, fr fr. Go say hi. 💖)

---

💜 AUTHOR 💜

Mathieu Malaterre Main developer

(Yes, the icon himself. 🎀)

---

⭐ COPYRIGHT ⭐

Copyright © 2006, 2011 Mathieu Malaterre

---

And that's a wrap on gdcmconv, bestie!! You made it to the end of the manual — proud of you fr fr. 🫶✨

This beauty is from GDCM 3.0.24, dated 12/25/2025. Christmas day release, main character energy honestly. 🎄👑 Now go convert some DICOMs and slay. 💅