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 -P --photometric-interpretation %s Change Photometric Interpretation (when possible).
40 -w --raw Decompress image.
41 -d --deflated Compress using deflated (gzip).
42 -J --jpeg Compress image in jpeg.
43 -K --j2k Compress image in j2k.
44 -L --jpegls Compress image in jpeg-ls.
45 -R --rle Compress image in rle (lossless only).
46 -F --force Force decompression/merging before recompression/splitting.
47 --generate-icon Generate icon.
48 --icon-minmax %d,%d Min/Max value for icon.
49 --icon-auto-minmax Automatically commpute best Min/Max values for icon.
50 --compress-icon Decide whether icon follows main TransferSyntax or remains uncompressed.
51 --planar-configuration [01] Change planar configuration.
52 -Y --lossy Use the lossy (if possible) compressor.
53 -S --split %d Write 2D image with multiple fragments (using max size)
54
56 -q --quality %*f set quality.
57
59 -e --allowed-error %*i set allowed error.
60
62 -r --rate %*f set rate.
63 -q --quality %*f set quality.
64 -t --tile %d,%d set tile size.
65 -n --number-resolution %d set number of resolution.
66 --irreversible set irreversible.
67
69 -h --help
70 print this help text and exit
71 -v --version
73 print version information and exit
74 -V --verbose
76 verbose mode (warning+error).
77 -W --warning
79 warning mode, print warning information
80 -E --error
82 error mode, print error information
83 -D --debug
85 debug mode, print debug information
86
88 -I --ignore-errors convert even if file is corrupted (advanced users only, see disclaimers).
89
91 GDCM_ROOT_UID Root UID
92
94 gdcmconv is a great tool to convert broken DICOM implementation into
95 properly parsable DICOM file. Usage is simply:
96 $ gdcmconv input.dcm output.dcm
98 or if you prefer being explicit:
100 $ gdcmconv -i input.dcm -o output.dcm
102 Even though gdcmconv can overwrite directly on the same file (input.dcm
104 = output.dcm), it is recommended that user should first convert into a
105 different file to make sure the bug is properly handled by GDCM.
106 Typical cases where you would want to use gdcmconv in its simple form:
108 • convert non-cp246 conforming file into conforming cp246,
110 • convert implicit little endian transfer syntax file meta header
112 into proper explicit little endian transfer syntax,
113 • convert the GE-13 bytes bug,
115 • convert dual syntax file: implicit/explicit,
117 • convert Philips dual Little Endian/Big Endian file,
119 • convert GDCM 1.2.0 broken UN-2-bytes fields,
121 • ...
123 • All other broken files listed in the supported refsection.
125 When no option other is used, only the dataset is inspected. So
127 encapsulated Pixel Data, for instance, is not inspected for well known
128 bugs.
129 When doing this kind of work, this is usually a good idea to perform
131 some kind of quality control, see gdcmconv Quality Control refsection
132 (down below).
133
135 File Meta Header
136 Running
137 $ gdcmconv input.dcm output.dcm
139 Is not enough to recompute file meta header, when input file is buggy.
141 You may want to use: –check-meta
142 $ gdcmconv --check-meta input.dcm output.dcm
144 See typical cases such as: GE_DLX-8-MONO2-PrivateSyntax.dcm or
146 PICKER-16-MONO2-No_DicomV3_Preamble.dcm from gdcmData.
147 Conversion to Explicit Transfer Syntax
149 To convert a file that was written using Implicit Transfer Syntax into
150 Explicit Transfer Syntax simply use:
151 $ gdcmconv --explicit uncompressed.dcm compressed.dcm
153 Compressing to lossless JPEG
155 To compress an uncompressed DICOM file to a JPEG Lossless encapsulated
156 format:
157 $ gdcmconv --jpeg uncompressed.dcm compressed.dcm
159 Compressing to lossy JPEG
161 To compress an uncompressed DICOM file to a JPEG Lossy encapsulated
162 format:
163 $ gdcmconv --lossy --jpeg -q 90 uncompressed.dcm compressed.dcm
165 Note:
167 -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.
169 Compressing to lossless JPEG-LS
171 To compress an uncompressed DICOM file to a JPEG-LS Lossless
172 encapsulated format:
173 $ gdcmconv --jpegls uncompressed.dcm compressed.dcm
175 Compressing to lossy JPEG-LS
177 To compress an uncompressed DICOM file to a JPEG-LS Lossy encapsulated
178 format:
179 $ gdcmconv --lossy --jpegls -e 2 uncompressed.dcm lossy_compressed.dcm
181 Note:
183 -e (or –lossy-error) means that the maximum tolerate error is 2 for
185 each pixel value
186 Compressing to lossless J2K
188 To compress an uncompressed DICOM file to a JPEG-2000 Lossless
189 encapsulated format:
190 $ gdcmconv --j2k uncompressed.dcm compressed.dcm
192 Compressing to lossy J2K
194 To compress an uncompressed DICOM file to a JPEG-2000 Lossy
195 encapsulated format:
196 $ gdcmconv --lossy -q 55,50,45 --j2k uncompressed.dcm lossy_compressed.dcm
198 Note:
200 -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.
202 Compressing to lossless RLE
204 To compress an uncompressed DICOM file to a RLE Lossless encapsulated
205 format:
206 $ gdcmconv --rle uncompressed.dcm compressed.dcm
208 There is no such thing as lossy RLE compression.
210 Split encapsulated DICOM:
212 To split an encapsulated stream into smaller chunk (1024 bytes each):
213 $ gdcmconv --split 1024 rle.dcm rle_1024.dcm
215 If an odd number of bytes is passed it will be rounded down to the next
217 even number (eg. 1025 -> 1024) since DICOM only allow even number for
218 Value Length.
219 Forcing (re)compression
221 Sometime it is necessary to use the –force option. By default when user
222 specify –j2k and input file is already in JPEG 2000 encapsulated DICOM
223 format then no operation takes places. By using –force you make sure
224 that (re)compression operation takes places.
225 Real life example of why you would use –force:
227 • When Pixel Data is missing data / is padded with junk
229 • When you would like to make sure GDCM can handle decompression &
231 recompression cycle
232 Decompressing a Compressed DICOM
235 $ gdcmconv --raw compressed.dcm uncompressed.dcm
236 In the case of uncompress file (Explicit and Implicit) the behavior is
238 to keep the original Transfer Syntax (so Implicit remains Implit)
239 Decompressing a Compressed DICOM as implicit
241 $ gdcmconv --raw --implicit compressed.dcm uncompressed_implicit.dcm
242 By symmetry it is also possible to use gdcmconv --raw --explicit to
244 make sure that target file is always Explicit TS.
245 Compressing an uncompressed Icon
247 By default when compressing a DICOM Image file, gdcmconv will not
248 compress the icon. A user option needs to be turned on to explicitly
249 force the compression of the Icon Image Sequence Pixel Data
250 For example, by default we will not compress the Icon Image Sequence
252 Pixel Data attribute:
253 $ gdcmconv --jpeg gdcmData/simpleImageWithIcon.dcm uncompressed_icon.dcm
255 In the following example we will explicitly compress the Icon Image
257 Sequence Pixel Data attibute. In that case the same Transfer Syntax is
258 being used for both the main Pixel Data and the Pixel Data from the
259 Icon Image Sequence:
260 $ gdcmconv --jpeg --compress-icon gdcmData/simpleImageWithIcon.dcm compressed_icon.dcm
262 Generating an Icon
264 For some application it might be necessary to produce a small preview
265 of the main image to be able to quickly load that short preview instead
266 of the main image. In that case:
267 $ gdcmconv --raw --generate-icon gdcmData/test.acr test_icon.dcm
269 In some cases the main Pixel Data element is expressed as pixel defined
271 on 16bits. Since Icon can only store at most pixel of size 8bits, a
272 rescale operation needs to take place. In order to properly select a
273 better interval for doing the rescale operation user can specify the
274 min max used for the rescale operation:
275 $ gdcmconv --raw --generate-icon --icon-minmax 0,192 gdcmData/012345.002.050.dcm icon_minmax.dcm
277 Changing the planar Configuration
279 Often RLE files are compressed using a different Planar Configuration
280 (RRR ... GGG... BBB...) instead of the usual triplet (RGB ... RGB ...
281 RGB ). So upon decompression the Planar Configuration is 1. This is
282 perfectly legal in DICOM, however this is unconventional, and thus it
283 may be a good idea to also change the planar configuration and set it
284 to the default :
285 $ gdcmconv --raw --planar-configuration 0 compressed.dcm uncompressed1.dcm
287 To reinvert the planar configuration of file 'uncompressed1.dcm',
289 simply do:
290 $ gdcmconv --raw --planar-configuration 1 uncompressed1.dcm uncompressed2.dcm
292
294 When talking about lossless conversion, there is an ambiguity that need
295 to be understood. To achieve higher compression ratio, the RGB color
296 space is usually not used, in favor of a YBR one. Changing from one
297 color space to the other is (bit level) not lossless.
298 For more detail, see what are the true lossless transformations as
300 described:
301 http://gdcm.sourceforge.net/wiki/index.php/Color_Space_Transformations
303
305 One important part when using gdcmconv it to have a way to quality
306 control the output.
307 You can use 3rd party tool to check the output of gdcmconv is correct.
309 DCMTK / dicom3tools
311 Using another DICOM implementation such as the one from DCMTK or
312 dicom3tools can be a good process to check the output of gdcmconv.
313 • For DCMTK use: dcmdump
315 • For dicom3tools use: dcdump
317 For reference, gdcmconv --raw will act as dcmdjpeg +cn +px, since it
319 never tries to convert color space.
320 VIM: vimdiff
322 You can setup your favorite editor to compare the output, for instance
323 in vim:
324 autocmd BufReadPre *.dcm set ro
326 autocmd BufReadPost *.dcm silent %!dcmdump -M +uc "%"
327 then simply do:
329 $ vimdiff input.dcm output.dcm
331 vbindiff
333 On UNIX you can visually compare binary file using the vbindiff
334 command:
335 $ vbindiff input.dcm output.dcm
337
339 gdcmdump(1), gdcmraw(1), gdcminfo(1), gdcmdiff(1)
340
342 Mathieu Malaterre
343 Main developer
344
346 Copyright © 2006, 2011 Mathieu Malaterre
347GDCM 3.0.8 01/26/2021 GDCMCONV(1)