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             -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

JPEG OPTIONS

58             -q --quality %*f           set quality.
59

JPEG-LS OPTIONS

61             -e --allowed-error %*i       set allowed error.
62

J2K OPTIONS

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

GENERAL OPTIONS

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

SPECIAL OPTIONS

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

ENVIRONMENT VARIABLE

93             GDCM_ROOT_UID Root UID
94

SIMPLE USAGE

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

TYPICAL USAGE

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

LOSSLESS CONVERSION

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

QUALITY CONTROL

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

SEE ALSO

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

AUTHOR

344       Mathieu Malaterre
345           Main developer
346
348       Copyright © 2006, 2011 Mathieu Malaterre
349
350
351
352GDCM 3.0.22                       08/07/2023                       GDCMCONV(1)
Impressum