1GDCMCONV(1)                   DICOM Manipulation.                  GDCMCONV(1)
2
3
4

NAME

6       gdcmconv - Tool to convert DICOM to DICOM.
7

SYNOPSIS

9           gdcmconv [options] file-in file-out
10

DESCRIPTION

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

PARAMETERS

18           file-in   DICOM input filename
19
20           file-out  DICOM output filename
21

OPTIONS

23             -i --input      DICOM filename
24             -o --output     DICOM filename
25

SPECIFIC OPTIONS

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

IMAGE OPTIONS

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

JPEG OPTIONS

56             -q --quality %*f           set quality.
57

JPEG-LS OPTIONS

59             -e --allowed-error %*i       set allowed error.
60

J2K OPTIONS

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

GENERAL OPTIONS

69             -h   --help
70                    print this help text and exit
71
72             -v   --version
73                    print version information and exit
74
75             -V   --verbose
76                    verbose mode (warning+error).
77
78             -W   --warning
79                    warning mode, print warning information
80
81             -E   --error
82                    error mode, print error information
83
84             -D   --debug
85                    debug mode, print debug information
86

SPECIAL OPTIONS

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

ENVIRONMENT VARIABLE

91             GDCM_ROOT_UID Root UID
92

SIMPLE USAGE

94       gdcmconv is a great tool to convert broken DICOM implementation into
95       properly parsable DICOM file. Usage is simply:
96
97           $ gdcmconv input.dcm output.dcm
98
99       or if you prefer being explicit:
100
101           $ gdcmconv -i input.dcm -o output.dcm
102
103       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
107       Typical cases where you would want to use gdcmconv in its simple form:
108
109       ·   convert non-cp246 conforming file into conforming cp246,
110
111       ·   convert implicit little endian transfer syntax file meta header
112           into proper explicit little endian transfer syntax,
113
114       ·   convert the GE-13 bytes bug,
115
116       ·   convert dual syntax file: implicit/explicit,
117
118       ·   convert Philips dual Little Endian/Big Endian file,
119
120       ·   convert GDCM 1.2.0 broken UN-2-bytes fields,
121
122       ·   ...
123
124       ·   All other broken files listed in the supported refsection.
125
126       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
130       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

TYPICAL USAGE

135   File Meta Header
136       Running
137
138           $ gdcmconv input.dcm output.dcm
139
140       Is not enough to recompute file meta header, when input file is buggy.
141       You may want to use: –check-meta
142
143           $ gdcmconv --check-meta input.dcm output.dcm
144
145       See typical cases such as: GE_DLX-8-MONO2-PrivateSyntax.dcm or
146       PICKER-16-MONO2-No_DicomV3_Preamble.dcm from gdcmData.
147
148   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
152           $ gdcmconv --explicit uncompressed.dcm compressed.dcm
153
154   Compressing to lossless JPEG
155       To compress an uncompressed DICOM file to a JPEG Lossless encapsulated
156       format:
157
158           $ gdcmconv --jpeg uncompressed.dcm compressed.dcm
159
160   Compressing to lossy JPEG
161       To compress an uncompressed DICOM file to a JPEG Lossy encapsulated
162       format:
163
164           $ gdcmconv --lossy --jpeg -q 90 uncompressed.dcm compressed.dcm
165
166       Note:
167
168             -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
170   Compressing to lossless JPEG-LS
171       To compress an uncompressed DICOM file to a JPEG-LS Lossless
172       encapsulated format:
173
174           $ gdcmconv --jpegls uncompressed.dcm compressed.dcm
175
176   Compressing to lossy JPEG-LS
177       To compress an uncompressed DICOM file to a JPEG-LS Lossy encapsulated
178       format:
179
180           $ gdcmconv --lossy --jpegls -e 2 uncompressed.dcm lossy_compressed.dcm
181
182       Note:
183
184       -e (or –lossy-error) means that the maximum tolerate error is 2 for
185       each pixel value
186
187   Compressing to lossless J2K
188       To compress an uncompressed DICOM file to a JPEG-2000 Lossless
189       encapsulated format:
190
191           $ gdcmconv --j2k uncompressed.dcm compressed.dcm
192
193   Compressing to lossy J2K
194       To compress an uncompressed DICOM file to a JPEG-2000 Lossy
195       encapsulated format:
196
197           $ gdcmconv --lossy -q 55,50,45 --j2k uncompressed.dcm lossy_compressed.dcm
198
199       Note:
200
201             -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
203   Compressing to lossless RLE
204       To compress an uncompressed DICOM file to a RLE Lossless encapsulated
205       format:
206
207           $ gdcmconv --rle uncompressed.dcm compressed.dcm
208
209       There is no such thing as lossy RLE compression.
210
211   Split encapsulated DICOM:
212       To split an encapsulated stream into smaller chunk (1024 bytes each):
213
214           $ gdcmconv --split 1024 rle.dcm rle_1024.dcm
215
216       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
220   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
226       Real life example of why you would use –force:
227
228       ·   When Pixel Data is missing data / is padded with junk
229
230       ·   When you would like to make sure GDCM can handle decompression &
231           recompression cycle
232
233
234   Decompressing a Compressed DICOM
235           $ gdcmconv --raw compressed.dcm uncompressed.dcm
236
237       In the case of uncompress file (Explicit and Implicit) the behavior is
238       to keep the original Transfer Syntax (so Implicit remains Implit)
239
240   Decompressing a Compressed DICOM as implicit
241           $ gdcmconv --raw --implicit compressed.dcm uncompressed_implicit.dcm
242
243       By symmetry it is also possible to use gdcmconv --raw --explicit to
244       make sure that target file is always Explicit TS.
245
246   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
251       For example, by default we will not compress the Icon Image Sequence
252       Pixel Data attribute:
253
254           $ gdcmconv --jpeg gdcmData/simpleImageWithIcon.dcm uncompressed_icon.dcm
255
256       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
261           $ gdcmconv --jpeg --compress-icon gdcmData/simpleImageWithIcon.dcm compressed_icon.dcm
262
263   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
268           $ gdcmconv --raw --generate-icon gdcmData/test.acr test_icon.dcm
269
270       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
276           $ gdcmconv --raw --generate-icon --icon-minmax 0,192 gdcmData/012345.002.050.dcm icon_minmax.dcm
277
278   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
286           $ gdcmconv --raw --planar-configuration 0 compressed.dcm uncompressed1.dcm
287
288       To reinvert the planar configuration of file 'uncompressed1.dcm',
289       simply do:
290
291           $ gdcmconv --raw --planar-configuration 1 uncompressed1.dcm uncompressed2.dcm
292

LOSSLESS CONVERSION

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
299       For more detail, see what are the true lossless transformations as
300       described:
301
302       http://gdcm.sourceforge.net/wiki/index.php/Color_Space_Transformations
303

QUALITY CONTROL

305       One important part when using gdcmconv it to have a way to quality
306       control the output.
307
308       You can use 3rd party tool to check the output of gdcmconv is correct.
309
310   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
314       ·   For DCMTK use: dcmdump
315
316       ·   For dicom3tools use: dcdump
317
318       For reference, gdcmconv --raw will act as dcmdjpeg +cn +px, since it
319       never tries to convert color space.
320
321   VIM: vimdiff
322       You can setup your favorite editor to compare the output, for instance
323       in vim:
324
325           autocmd BufReadPre *.dcm set ro
326           autocmd BufReadPost *.dcm silent %!dcmdump -M +uc "%"
327
328       then simply do:
329
330           $ vimdiff input.dcm output.dcm
331
332   vbindiff
333       On UNIX you can visually compare binary file using the vbindiff
334       command:
335
336           $ vbindiff input.dcm output.dcm
337

SEE ALSO

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

AUTHOR

342       Mathieu Malaterre
343           Main developer
344
346       Copyright © 2006, 2011 Mathieu Malaterre
347
348
349
350GDCM 3.0.8                        12/05/2020                       GDCMCONV(1)
Impressum