1GDCMCONV(1) DICOM Manipulation. GDCMCONV(1)
2
6 gdcmconv - Tool to convert DICOM to DICOM.
7
9 gdcmconv [options] file-in file-out
10
12 The gdcmconv command line program takes as input a DICOM file (file-in)
13 and process it to generate an output DICOM file (file-out). The command
14 line option dictate the type of operation(s) gdcmconv will use to
15 generate the output file.
16
18 file-in DICOM input filename
19 file-out DICOM output filename
21
23 -i --input DICOM filename
24 -o --output DICOM filename
25
27 -X --explicit Change Transfer Syntax to explicit.
28 -M --implicit Change Transfer Syntax to implicit.
29 -U --use-dict Use dict for VR (only public by default).
30 --with-private-dict Use private dict for VR (advanced user only).
31 -C --check-meta Check File Meta Information (advanced user only).
32 --root-uid Root UID.
33 --remove-gl Remove group length (deprecated in DICOM 2008).
34 --remove-private-tags Remove private tags.
35 --remove-retired Remove retired tags.
36
38 -l --apply-lut Apply LUT (non-standard, advanced user only).
39 -8 --apply-lut8 Apply LUT/RGB8 (non-standard, advanced user only).
40 --decompress-lut Decompress LUT (linearize segmented LUT).
41 -P --photometric-interpretation %s Change Photometric Interpretation (when possible).
42 -w --raw Decompress image.
43 -d --deflated Compress using deflated (gzip).
44 -J --jpeg Compress image in jpeg.
45 -K --j2k Compress image in j2k.
46 -L --jpegls Compress image in jpeg-ls.
47 -R --rle Compress image in rle (lossless only).
48 -F --force Force decompression/merging before recompression/splitting.
49 --generate-icon Generate icon.
50 --icon-minmax %d,%d Min/Max value for icon.
51 --icon-auto-minmax Automatically compute best Min/Max values for icon.
52 --compress-icon Decide whether icon follows main TransferSyntax or remains uncompressed.
53 --planar-configuration [01] Change planar configuration.
54 -Y --lossy Use the lossy (if possible) compressor.
55 -S --split %d Write 2D image with multiple fragments (using max size)
56
58 -q --quality %*f set quality.
59
61 -e --allowed-error %*i set allowed error.
62
64 -r --rate %*f set rate.
65 -q --quality %*f set quality.
66 -t --tile %d,%d set tile size.
67 -n --number-resolution %d set number of resolution.
68 --irreversible set irreversible.
69
71 -h --help
72 print this help text and exit
73 -v --version
75 print version information and exit
76 -V --verbose
78 verbose mode (warning+error).
79 -W --warning
81 warning mode, print warning information
82 -E --error
84 error mode, print error information
85 -D --debug
87 debug mode, print debug information
88
90 -I --ignore-errors convert even if file is corrupted (advanced users only, see disclaimers).
91
93 GDCM_ROOT_UID Root UID
94
96 gdcmconv is a great tool to convert broken DICOM implementation into
97 properly parsable DICOM file. Usage is simply:
98 $ gdcmconv input.dcm output.dcm
100 or if you prefer being explicit:
102 $ gdcmconv -i input.dcm -o output.dcm
104 Even though gdcmconv can overwrite directly on the same file (input.dcm
106 = output.dcm), it is recommended that user should first convert into a
107 different file to make sure the bug is properly handled by GDCM.
108 Typical cases where you would want to use gdcmconv in its simple form:
110 • convert non-cp246 conforming file into conforming cp246,
112 • convert implicit little endian transfer syntax file meta header
114 into proper explicit little endian transfer syntax,
115 • convert the GE-13 bytes bug,
117 • convert dual syntax file: implicit/explicit,
119 • convert Philips dual Little Endian/Big Endian file,
121 • convert GDCM 1.2.0 broken UN-2-bytes fields,
123 • ...
125 • All other broken files listed in the supported refsection.
127 When no option other is used, only the dataset is inspected. So
129 encapsulated Pixel Data, for instance, is not inspected for well known
130 bugs.
131 When doing this kind of work, this is usually a good idea to perform
133 some kind of quality control, see gdcmconv Quality Control refsection
134 (down below).
135
137 File Meta Header
138 Running
139 $ gdcmconv input.dcm output.dcm
141 Is not enough to recompute file meta header, when input file is buggy.
143 You may want to use: –check-meta
144 $ gdcmconv --check-meta input.dcm output.dcm
146 See typical cases such as: GE_DLX-8-MONO2-PrivateSyntax.dcm or
148 PICKER-16-MONO2-No_DicomV3_Preamble.dcm from gdcmData.
149 Conversion to Explicit Transfer Syntax
151 To convert a file that was written using Implicit Transfer Syntax into
152 Explicit Transfer Syntax simply use:
153 $ gdcmconv --explicit uncompressed.dcm compressed.dcm
155 Compressing to lossless JPEG
157 To compress an uncompressed DICOM file to a JPEG Lossless encapsulated
158 format:
159 $ gdcmconv --jpeg uncompressed.dcm compressed.dcm
161 Compressing to lossy JPEG
163 To compress an uncompressed DICOM file to a JPEG Lossy encapsulated
164 format:
165 $ gdcmconv --lossy --jpeg -q 90 uncompressed.dcm compressed.dcm
167 Note:
169 -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.
171 Compressing to lossless JPEG-LS
173 To compress an uncompressed DICOM file to a JPEG-LS Lossless
174 encapsulated format:
175 $ gdcmconv --jpegls uncompressed.dcm compressed.dcm
177 Compressing to lossy JPEG-LS
179 To compress an uncompressed DICOM file to a JPEG-LS Lossy encapsulated
180 format:
181 $ gdcmconv --lossy --jpegls -e 2 uncompressed.dcm lossy_compressed.dcm
183 Note:
185 -e (or –lossy-error) means that the maximum tolerate error is 2 for
187 each pixel value
188 Compressing to lossless J2K
190 To compress an uncompressed DICOM file to a JPEG-2000 Lossless
191 encapsulated format:
192 $ gdcmconv --j2k uncompressed.dcm compressed.dcm
194 Compressing to lossy J2K
196 To compress an uncompressed DICOM file to a JPEG-2000 Lossy
197 encapsulated format:
198 $ gdcmconv --lossy -q 55,50,45 --j2k uncompressed.dcm lossy_compressed.dcm
200 Note:
202 -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.
204 Compressing to lossless RLE
206 To compress an uncompressed DICOM file to a RLE Lossless encapsulated
207 format:
208 $ gdcmconv --rle uncompressed.dcm compressed.dcm
210 There is no such thing as lossy RLE compression.
212 Split encapsulated DICOM:
214 To split an encapsulated stream into smaller chunk (1024 bytes each):
215 $ gdcmconv --split 1024 rle.dcm rle_1024.dcm
217 If an odd number of bytes is passed it will be rounded down to the next
219 even number (eg. 1025 -> 1024) since DICOM only allow even number for
220 Value Length.
221 Forcing (re)compression
223 Sometime it is necessary to use the –force option. By default when user
224 specify –j2k and input file is already in JPEG 2000 encapsulated DICOM
225 format then no operation takes places. By using –force you make sure
226 that (re)compression operation takes places.
227 Real life example of why you would use –force:
229 • When Pixel Data is missing data / is padded with junk
231 • When you would like to make sure GDCM can handle decompression &
233 recompression cycle
234 Decompressing a Compressed DICOM
237 $ gdcmconv --raw compressed.dcm uncompressed.dcm
238 In the case of uncompress file (Explicit and Implicit) the behavior is
240 to keep the original Transfer Syntax (so Implicit remains Implit)
241 Decompressing a Compressed DICOM as implicit
243 $ gdcmconv --raw --implicit compressed.dcm uncompressed_implicit.dcm
244 By symmetry it is also possible to use gdcmconv --raw --explicit to
246 make sure that target file is always Explicit TS.
247 Compressing an uncompressed Icon
249 By default when compressing a DICOM Image file, gdcmconv will not
250 compress the icon. A user option needs to be turned on to explicitly
251 force the compression of the Icon Image Sequence Pixel Data
252 For example, by default we will not compress the Icon Image Sequence
254 Pixel Data attribute:
255 $ gdcmconv --jpeg gdcmData/simpleImageWithIcon.dcm uncompressed_icon.dcm
257 In the following example we will explicitly compress the Icon Image
259 Sequence Pixel Data attibute. In that case the same Transfer Syntax is
260 being used for both the main Pixel Data and the Pixel Data from the
261 Icon Image Sequence:
262 $ gdcmconv --jpeg --compress-icon gdcmData/simpleImageWithIcon.dcm compressed_icon.dcm
264 Generating an Icon
266 For some application it might be necessary to produce a small preview
267 of the main image to be able to quickly load that short preview instead
268 of the main image. In that case:
269 $ gdcmconv --raw --generate-icon gdcmData/test.acr test_icon.dcm
271 In some cases the main Pixel Data element is expressed as pixel defined
273 on 16bits. Since Icon can only store at most pixel of size 8bits, a
274 rescale operation needs to take place. In order to properly select a
275 better interval for doing the rescale operation user can specify the
276 min max used for the rescale operation:
277 $ gdcmconv --raw --generate-icon --icon-minmax 0,192 gdcmData/012345.002.050.dcm icon_minmax.dcm
279 Changing the planar Configuration
281 Often RLE files are compressed using a different Planar Configuration
282 (RRR ... GGG... BBB...) instead of the usual triplet (RGB ... RGB ...
283 RGB ). So upon decompression the Planar Configuration is 1. This is
284 perfectly legal in DICOM, however this is unconventional, and thus it
285 may be a good idea to also change the planar configuration and set it
286 to the default :
287 $ gdcmconv --raw --planar-configuration 0 compressed.dcm uncompressed1.dcm
289 To reinvert the planar configuration of file 'uncompressed1.dcm',
291 simply do:
292 $ gdcmconv --raw --planar-configuration 1 uncompressed1.dcm uncompressed2.dcm
294
296 When talking about lossless conversion, there is an ambiguity that need
297 to be understood. To achieve higher compression ratio, the RGB color
298 space is usually not used, in favor of a YBR one. Changing from one
299 color space to the other is (bit level) not lossless.
300 For more detail, see what are the true lossless transformations as
302 described:
303 http://gdcm.sourceforge.net/wiki/index.php/Color_Space_Transformations
305
307 One important part when using gdcmconv it to have a way to quality
308 control the output.
309 You can use 3rd party tool to check the output of gdcmconv is correct.
311 DCMTK / dicom3tools
313 Using another DICOM implementation such as the one from DCMTK or
314 dicom3tools can be a good process to check the output of gdcmconv.
315 • For DCMTK use: dcmdump
317 • For dicom3tools use: dcdump
319 For reference, gdcmconv --raw will act as dcmdjpeg +cn +px, since it
321 never tries to convert color space.
322 VIM: vimdiff
324 You can setup your favorite editor to compare the output, for instance
325 in vim:
326 autocmd BufReadPre *.dcm set ro
328 autocmd BufReadPost *.dcm silent %!dcmdump -M +uc "%"
329 then simply do:
331 $ vimdiff input.dcm output.dcm
333 vbindiff
335 On UNIX you can visually compare binary file using the vbindiff
336 command:
337 $ vbindiff input.dcm output.dcm
339
341 gdcmdump(1), gdcmraw(1), gdcminfo(1), gdcmdiff(1)
342
344 Mathieu Malaterre
345 Main developer
346
348 Copyright © 2006, 2011 Mathieu Malaterre
349GDCM 3.0.22 08/07/2023 GDCMCONV(1)