1img2dcm(1) OFFIS DCMTK img2dcm(1)
2
6 img2dcm - Convert standard image formats into DICOM format
7
10 img2dcm [options] imgfile-in dcmfile-out
11
13 The img2dcm tool serves as a conversion tool from a standard image
14 format like JPEG or BMP to DICOM. Different output SOP Classes can be
15 selected. The additional information (regarding patients, series, etc.)
16 stored in the DICOM output file can be extracted from other DICOM files
17 which serve as a 'template' for the resulting DICOM object. img2dcm can
18 also be configured to invent missing DICOM type 1 and type 2 attributes
19 to work even without any template dataset.
20 img2dcm only supports single-frame output so far, i.e. it is not
22 possible to create multi-frame objects. Thus, also output SOP Classes
23 that potentially allow multiple frames within one object (such as the
24 new Secondary Capture SOP Classes) can only be created containing a
25 single frame.
26
28 imgfile-in image file to be imported
29 dcmfile-out DICOM output file
31
33 general options
34 -h --help
35 print this help text and exit
36 --version
38 print version information and exit
39 --arguments
41 print expanded command line arguments
42 -q --quiet
44 quiet mode, print no warnings and errors
45 -v --verbose
47 verbose mode, print processing details
48 -d --debug
50 debug mode, print debug information
51 -ll --log-level [l]evel: string constant
53 (fatal, error, warn, info, debug, trace)
54 use level l for the logger
55 -lc --log-config [f]ilename: string
57 use config file f for the logger
58 input options
60 general:
61 -i --input-format [i]nput file format: string
63 supported formats: JPEG (default), BMP
64 -df --dataset-from [f]ilename: string
66 use dataset from DICOM file f
67 -stf --study-from [f]ilename: string
69 read patient/study from DICOM file f
70 -sef --series-from [f]ilename: string
72 read patient/study/series from DICOM file f
73 -ii --instance-inc
75 increase instance number read from DICOM file
76 JPEG format:
78 -dp --disable-progr
80 disable support for progressive JPEG
81 -de --disable-ext
83 disable support for extended sequential JPEG
84 -jf --insist-on-jfif
86 insist on JFIF header existence
87 -ka --keep-appn
89 keep APPn sections (except JFIF)
90 processing options
92 attribute checking:
93 --do-checks
95 enable attribute validity checking (default)
96 --no-checks
98 disable attribute validity checking
99 +i2 --insert-type2
101 insert missing type 2 attributes (default)
102 (only with --do-checks)
103 -i2 --no-type2-insert
105 do not insert missing type 2 attributes
106 (only with --do-checks)
107 +i1 --invent-type1
109 invent missing type 1 attributes
110 (only with --do-checks)
111 -i1 --no-type1-invent
113 do not invent missing type 1 attributes
114 (only with --do-checks)
115 character set:
117 +l1 --latin1
119 set latin-1 as standard character set (default)
120 -l1 --no-latin1
122 keep 7-bit ASCII as standard character set
123 other processing options:
125 -k --key [k]ey: gggg,eeee="str", path or dictionary name="str"
127 add further attribute
128 output options
130 target SOP class:
131 -sc --sec-capture
133 write Secondary Capture SOP class
134 -nsc --new-sc
136 write new Secondary Capture SOP classes
137 -vlp --vl-photo
139 write Visible Light Photographic SOP class (default)
140 output file format:
142 +F --write-file
144 write file format (default)
145 -F --write-dataset
147 write data set without file meta information
148 group length encoding:
150 +g= --group-length-recalc
152 recalculate group lengths if present (default)
153 +g --group-length-create
155 always write with group length elements
156 -g --group-length-remove
158 always write without group length elements
159 length encoding in sequences and items:
161 +e --length-explicit
163 write with explicit lengths (default)
164 -e --length-undefined
166 write with undefined lengths
167 data set trailing padding (not with --write-dataset):
169 -p --padding-off
171 no padding (implicit if --write-dataset)
172 +p --padding-create [f]ile-pad [i]tem-pad: integer
174 align file on multiple of f bytes
175 and items on multiple of i bytes
176
178 Attribute Sources
179 For converting a general image format into DICOM format, the img2dcm
180 application may be fed with some additional input for filling mandatory
181 (and optional) attributes in the new DICOM file like patient, study and
182 series information. This information can be collected using different
183 approaches, which can be combined and are applied to the result file in
184 the following order:
185 • Using the --dataset-from option img2dcm is forced to import
187 attributes from an existing DICOM file. The given DICOM file is fully
188 imported and serves as the basis for all further export operations.
189 As an exception, the SOP Instance UID is not copied by this option.
190 Also image related data like Rows, Columns etc. is exchanged during
191 conversion. Note that img2dcm does not check any other attribute
192 values for validity, e. g. it does not look into sequences to adapt
193 any attributes to the new object (referenced images etc.). Therefore,
194 it is recommended to use the templates in the data directory for
195 (old) SC and VLP objects. See also section 'Input Templates'.
196 • The --study-from and --series-from options (mutually exclusive) can
197 be used to import patient, study and series information from an
198 existing DICOM file. If --series-from is specified, then the given
199 DICOM file is opened by img2dcm and all mandatory information down to
200 the series level is imported. Note that this includes patient, study
201 and series information. In case of --study-from, the series
202 information is excluded. The following attributes are taken over:
203 Patient Level:
204 Patient's Name
205 Patient ID
206 Patient's Sex
207 Patient's Birth Date
208 Specific Character Set
209 Study Level:
211 Study Instance UID
212 Study Date
213 Study Time
214 Referring Physician's Name
215 Study ID
216 Accession Number
217 Series Level (only in case of option --series-from):
219 Series Instance UID
220 Series Number
221 Manufacturer
222 • With the --insert-type2 and --invent-type1 options (both enabled per
223 default), missing attributes (type 2 attributes) and/or missing
224 attribute values (for type 1 attributes) are automatically added and
225 invented by img2dcm. Please note that these options are only
226 evaluated if option --do-checks is enabled (default). If the --no-
227 checks options is enabled, no automatic attribute insertion will take
228 place.
229 • The --key option can be used to add further attributes to the DICOM
230 output file. It is also possible to specify sequences, items and
231 nested attributes using the --key option. In these cases, a special
232 'path' notation has to be used. Details on this path notation can be
233 found in the documentation of dcmodify. The --key option can be
234 present more than once. The value part (after the '=') may be absent
235 causing the attribute to be set with zero length. Please be advised
236 that the --key option is applied at the very end, just before saving
237 the DICOM file, so there is no value checking whatsoever.
238 UIDs
239 New Study and Series Instance UIDs are generated if necessary after
240 applying the --study-from and --series options. If Study Instance UID
241 or Series Instance UID are not present after these steps, they are
242 newly generated, independently from each other. A contrary behavior is
243 chosen for the SOP Instance UID that one could expect to be taken over
244 when using the --dataset-from option. This is not the case, the SOP
245 Instance UID is not copied to the new object. This should be the
246 desirable behavior for most use cases. However, if a certain SOP
247 Instance UID should be inserted into the new object, the --key option
248 should be used.
249 Input Templates
250 For supporting the conversion into DICOM, img2dcm comes with some pre-
251 defined templates which can be used for the --dataset-from option (see
252 sample files SC.dump and VLP.dump). These templates should be filled
253 with the desired values and then must be dumped (converted) to a DICOM
254 file before actually being used with img2dcm. Use dump2dcm to convert
255 the dump to DICOM. Example:
256 dump2dcm SC.dump SC.dcm
257 It is possible to use any DICOM file as a template. Please note that
259 the complete DICOM dataset is imported; hence, it should be assured
260 that only attributes are present which should be part of the
261 constructed DICOM object. The SOP Class UID and the Pixel Data
262 attributes (including attributes like Rows, Columns etc.) are not
263 copied but replaced by img2dcm during conversion.
264 Input Plugins
265 The img2dcm application currently supports the JPEG and the BMP image
266 format as input.
267 JPEG Input Plugin
268 For JPEG, the original JPEG from the source file is not decoded but
269 extracted and slightly transformed (e. g. JFIF header is cut off) to
270 allow fast conversion of even big JPEG files without the need of
271 decoding and re-encoding. The JPEG plugin chooses the necessary output
272 transfer syntax automatically depending on the actual encoding of the
273 data inside the JPEG file. Therefore, the following Transfer Syntaxes
274 (and their corresponding JPEG encodings) are used by the JPEG plugin:
275 • JPEG Coding Process 1 Baseline, Lossy, Non-Hierarchical, Sequential,
276 DCT, Huffman, 8 Bit SOP Class = 1.2.840.10008.1.2.4.50
277 • JPEG Coding Process 2 (8-bit) and 4 (12-bit) Extended, Lossy, Non-
278 Hierarchical, Sequential, DCT, Huffman, 8/12 Bit SOP Class =
279 1.2.840.10008.1.2.4.51
280 • JPEG Coding Process 10 (8-bit) and 12 (12-bit) Full Progression,
281 lossy, Non-Hierarch., Progressive, DCT, Huffman, 8/12 Bit SOP Class =
282 1.2.840.10008.1.2.4.55
283 Color and grayscale images are supported.
284 The support for the Extended JPEG Transfer Syntax can be disabled
285 (--disable-ext option) as well as the support for the (retired)
286 Progressive JPEG Transfer Syntax (--disable-progr option).
287 JPEG lossless encoding as well as any arithmetic or hierarchical JPEG
288 encoding modes are not supported by the plugin.
289 JFIF (JPEG File Interchange Format) information facilitates optional
290 APPn markers in a JPEG file. Many digital cameras do not integrate such
291 JFIF information into the JPEG output they create. For example, JFIF
292 contains information about the pixel aspect ratio of the compressed
293 image. If you want the img2dcm application to insist on a JFIF header
294 in the JPEG stream, you can use the option --insist-on-jfif which will
295 abort if no JFIF information can be found. By default, missing JFIF
296 information is ignored.
297 For DICOM it is kind of a 'gray zone', whether the integration of JFIF
298 (or any other APPn) data into the DICOM object's internal JPEG stream
299 is allowed or not. However, the most reliable approach is to cut those
300 markers and their information off the JPEG stream. This approach is
301 also taken by the img2dcm application. By default, all APPn markers are
302 cut off from the original JPEG stream. However, if you want to keep
303 other APPn markers than JFIF (e. g. EXIF information) inside the DICOM
304 stream, the option --keep-appn does the trick. It should also be
305 slightly faster than cutting off APPn information, because it is not
306 necessary to scan the whole JPEG stream for such data. JFIF information
307 is always removed by img2dcm.
308 BMP Input Plugin
309 img2dcm supports BMP as input format. However, so far only the most
310 common BMP images are supported. In particular, BMP images which use
311 bit fields or run length encoding will be rejected. Such images are
312 uncommon. All input images will be converted into a DICOM image with
313 RGB color model and a bit depth of 24. There are no specific options
314 for fine-tuning BMP format conversion.
315 Output Plugins
316 The desired output SOP Class can be selected on the command line.
317 Currently, an export plugin for the Secondary Capture Image SOP class
318 (default, option -sc), the new Secondary Capture Image SOP classes
319 (option -nsc) and Visible Light Photographic Image SOP class (option
320 -vl) are available. Please note that the first one is deprecated
321 according to the DICOM standard but is selected as a default because it
322 is widely supported. Future versions of img2dcm might provide further
323 output plugins for other SOP Classes.
324 For the new Secondary Capture SOP classes, it is not possible to
325 specify which specific SOP class should be used for output. That is
326 because these new SOP classes are differentiated from each other by
327 color depth (1/8/16) and the fact whether the image is black/white or
328 color. That is why img2dcm decides during conversion, which output SOP
329 class is suitable for a given source image.
331 Here are some examples that show how the img2dcm application can be
332 used.
333 1. img2dcm image.jpg out.dcm
334 Read JPEG file 'image.jpg', convert to the old Secondary Capture
335 SOP class and save the result to DICOM file 'out.dcm'. This is the
336 easiest way of using img2dcm. Any type 1 and type 2 attributes
337 required for writing valid objects of this SOP class are inserted
338 automatically.
339 2. img2dcm -i BMP image.bmp out.dcm
340 Same as above but tells img2dcm to read a BMP file instead of JPEG.
341 3. img2dcm image.jpg out.dcm -vlp -k 'PatientName=Bond^James'
342 Same as first example, but writes Visible Light Photographic Image
343 object to 'out.dcm' and sets PatientName to 'Bond^James' which
344 otherwise would be left empty.
345 4. img2dcm image.jpg out.dcm --series-from template.dcm -k
346 'PatientName=Bond^James'
347 Same as 1), but imports patient/study/series information from DICOM
348 file 'template.dcm'. Please note that attribute PatientName will
349 contain 'Bond^James' at the end, any value from 'template.dcm' will
350 be overwritten. That is, because the -k option is applied at the
351 very end of the conversion pipeline (see above).
352 5. img2dcm image.jpg out.dcm --no-checks
353 Same as 1), but does not perform any attribute checking and no type
354 1 and type 2 attribute insertion! So in this case, an invalid DICOM
355 object would be generated. This can be interesting if the output
356 file is not meant to be completed but will undergo further
357 transformations, e. g. adding attributes using dcmodify. Only use
358 option --no-checks if you know what you are doing!
359 6. img2dcm image.jpg out.dcm --no-type1-invent
360 Same as 1), but does not insert missing type 1 attributes and/or
361 their values. Type 2 attributes will be inserted. Note that in this
362 case it must be assured that all type 1 attributes are provided by
363 other means, i. e. by adding them with the --key option. Otherwise,
364 img2dcm will report an error and will stop converting.
365 7. img2dcm image.jpg out.dcm --keep-appn --insist-on-jfif
366 Same as 1), but takes over APPn information like EXIF into the
367 DICOM object's resulting JPEG stream. Further, --insist-on-jfif
368 will force img2dcm to abort if no JFIF information is existent in
369 the source file.
371 The level of logging output of the various command line tools and
372 underlying libraries can be specified by the user. By default, only
373 errors and warnings are written to the standard error stream. Using
374 option --verbose also informational messages like processing details
375 are reported. Option --debug can be used to get more details on the
376 internal activity, e.g. for debugging purposes. Other logging levels
377 can be selected using option --log-level. In --quiet mode only fatal
378 errors are reported. In such very severe error events, the application
379 will usually terminate. For more details on the different logging
380 levels, see documentation of module 'oflog'.
381 In case the logging output should be written to file (optionally with
382 logfile rotation), to syslog (Unix) or the event log (Windows) option
383 --log-config can be used. This configuration file also allows for
384 directing only certain messages to a particular output stream and for
385 filtering certain messages based on the module or application where
386 they are generated. An example configuration file is provided in
387 <etcdir>/logger.cfg.
389 All command line tools use the following notation for parameters:
390 square brackets enclose optional values (0-1), three trailing dots
391 indicate that multiple values are allowed (1-n), a combination of both
392 means 0 to n values.
393 Command line options are distinguished from parameters by a leading '+'
394 or '-' sign, respectively. Usually, order and position of command line
395 options are arbitrary (i.e. they can appear anywhere). However, if
396 options are mutually exclusive the rightmost appearance is used. This
397 behavior conforms to the standard evaluation rules of common Unix
398 shells.
399 In addition, one or more command files can be specified using an '@'
400 sign as a prefix to the filename (e.g. @command.txt). Such a command
401 argument is replaced by the content of the corresponding text file
402 (multiple whitespaces are treated as a single separator unless they
403 appear between two quotation marks) prior to any further evaluation.
404 Please note that a command file cannot contain another command file.
405 This simple but effective approach allows one to summarize common
406 combinations of options/parameters and avoids longish and confusing
407 command lines (an example is provided in file <datadir>/dumppat.txt).
409 The img2dcm utility will attempt to load DICOM data dictionaries
410 specified in the DCMDICTPATH environment variable. By default, i.e. if
411 the DCMDICTPATH environment variable is not set, the file
412 <datadir>/dicom.dic will be loaded unless the dictionary is built into
413 the application (default for Windows).
414 The default behavior should be preferred and the DCMDICTPATH
415 environment variable only used when alternative data dictionaries are
416 required. The DCMDICTPATH environment variable has the same format as
417 the Unix shell PATH variable in that a colon (':') separates entries.
418 On Windows systems, a semicolon (';') is used as a separator. The data
419 dictionary code will attempt to load each file specified in the
420 DCMDICTPATH environment variable. It is an error if no data dictionary
421 can be loaded.
423 <datadir>/SC.dump - Sample dump file for Secondary Capture images
424 <datadir>/VLP.dump - Sample dump file for Visible Light Photographic
425 images
427 dcm2pnm(1), dcmj2pnm(1), dump2dcm(1), dcmconv(1), dcmodify(1)
429 Copyright (C) 2007-2021 e.V., Escherweg 2, 26121 Oldenburg, Germany.
430Version 3.6.6 Thu Jan 14 2021 img2dcm(1)