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   Compressing an uncompressed Icon
238       By default when compressing a DICOM Image file, gdcmconv will not
239       compress the icon. A user option needs to be turned on to explicitly
240       force the compression of the Icon Image Sequence Pixel Data
241
242       For example, by default we will not compress the Icon Image Sequence
243       Pixel Data attribute:
244
245           $ gdcmconv --jpeg gdcmData/simpleImageWithIcon.dcm uncompressed_icon.dcm
246
247       In the following example we will explicitly compress the Icon Image
248       Sequence Pixel Data attibute. In that case the same Transfer Syntax is
249       being used for both the main Pixel Data and the Pixel Data from the
250       Icon Image Sequence:
251
252           $ gdcmconv --jpeg --compress-icon gdcmData/simpleImageWithIcon.dcm compressed_icon.dcm
253
254   Generating an Icon
255       For some application it might be necessary to produce a small preview
256       of the main image to be able to quickly load that short preview instead
257       of the main image. In that case:
258
259           $ gdcmconv --raw --generate-icon gdcmData/test.acr test_icon.dcm
260
261       In some cases the main Pixel Data element is expressed as pixel defined
262       on 16bits. Since Icon can only store at most pixel of size 8bits, a
263       rescale operation needs to take place. In order to properly select a
264       better interval for doing the rescale operation user can specify the
265       min max used for the rescale operation:
266
267           $ gdcmconv --raw --generate-icon --icon-minmax 0,192 gdcmData/012345.002.050.dcm icon_minmax.dcm
268
269   Changing the planar Configuration
270       Often RLE files are compressed using a different Planar Configuration
271       (RRR ... GGG... BBB...) instead of the usual triplet (RGB ... RGB ...
272       RGB ). So upon decompression the Planar Configuration is 1. This is
273       perfectly legal in DICOM, however this is unconventional, and thus it
274       may be a good idea to also change the planar configuration and set it
275       to the default :
276
277           $ gdcmconv --raw --planar-configuration 0 compressed.dcm uncompressed1.dcm
278
279       To reinvert the planar configuration of file 'uncompressed1.dcm',
280       simply do:
281
282           $ gdcmconv --raw --planar-configuration 1 uncompressed1.dcm uncompressed2.dcm
283

LOSSLESS CONVERSION

285       When talking about lossless conversion, there is an ambiguity that need
286       to be understood. To achieve higher compression ratio, the RGB color
287       space is usually not used, in favor of a YBR one. Changing from one
288       color space to the other is (bit level) not lossless.
289
290       For more detail, see what are the true lossless transformations as
291       described:
292
293       http://gdcm.sourceforge.net/wiki/index.php/Color_Space_Transformations
294

QUALITY CONTROL

296       One important part when using gdcmconv it to have a way to quality
297       control the output.
298
299       You can use 3rd party tool to check the output of gdcmconv is correct.
300
301   DCMTK / dicom3tools
302       Using another DICOM implementation such as the one from DCMTK or
303       dicom3tools can be a good process to check the output of gdcmconv.
304
305       ·   For DCMTK use: dcmdump
306
307       ·   For dicom3tools use: dcdump
308
309       For reference, gdcmconv --raw will act as dcmdjpeg +cn +px, since it
310       never tries to convert color space.
311
312   VIM: vimdiff
313       You can setup your favorite editor to compare the output, for instance
314       in vim:
315
316           autocmd BufReadPre *.dcm set ro
317           autocmd BufReadPost *.dcm silent %!dcmdump -M +uc "%"
318
319       then simply do:
320
321           $ vimdiff input.dcm output.dcm
322
323   vbindiff
324       On UNIX you can visually compare binary file using the vbindiff
325       command:
326
327           $ vbindiff input.dcm output.dcm
328

SEE ALSO

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

AUTHOR

333       Mathieu Malaterre
334           Main developer
335
337       Copyright © 2006, 2011 Mathieu Malaterre
338
339
340
341GDCM 3.0.1                        01/28/2020                       GDCMCONV(1)
Impressum