1img2dcm(1)                        OFFIS DCMTK                       img2dcm(1)
2
3
4

NAME

6       img2dcm - Convert standard image formats into DICOM format
7
8

SYNOPSIS

10       img2dcm [options] imgfile-in dcmfile-out
11

DESCRIPTION

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

PARAMETERS

28       imgfile-in   image file to be imported
29
30       dcmfile-out  DICOM output file
31

OPTIONS

33   general options
34         -h    --help
35                 print this help text and exit
36
37               --version
38                 print version information and exit
39
40               --arguments
41                 print expanded command line arguments
42
43         -q    --quiet
44                 quiet mode, print no warnings and errors
45
46         -v    --verbose
47                 verbose mode, print processing details
48
49         -d    --debug
50                 debug mode, print debug information
51
52         -ll   --log-level  [l]evel: string constant
53                 (fatal, error, warn, info, debug, trace)
54                 use level l for the logger
55
56         -lc   --log-config  [f]ilename: string
57                 use config file f for the logger
58
59   input options
60       general:
61
62         -i    --input-format  [i]nput file format: string
63                 supported formats: JPEG (default), BMP
64
65         -df   --dataset-from  [f]ilename: string
66                 use dataset from DICOM file f
67
68         -stf  --study-from  [f]ilename: string
69                 read patient/study from DICOM file f
70
71         -sef  --series-from  [f]ilename: string
72                 read patient/study/series from DICOM file f
73
74         -ii   --instance-inc
75                 increase instance number read from DICOM file
76
77       JPEG format:
78
79         -dp   --disable-progr
80                 disable support for progressive JPEG
81
82         -de   --disable-ext
83                 disable support for extended sequential JPEG
84
85         -jf   --insist-on-jfif
86                 insist on JFIF header existence
87
88         -ka   --keep-appn
89                 keep APPn sections (except JFIF)
90
91   processing options
92       attribute checking:
93
94               --do-checks
95                 enable attribute validity checking (default)
96
97               --no-checks
98                 disable attribute validity checking
99
100         +i2   --insert-type2
101                 insert missing type 2 attributes (default)
102                 (only with --do-checks)
103
104         -i2   --no-type2-insert
105                 do not insert missing type 2 attributes
106                 (only with --do-checks)
107
108         +i1   --invent-type1
109                 invent missing type 1 attributes
110                 (only with --do-checks)
111
112         -i1   --no-type1-invent
113                 do not invent missing type 1 attributes
114                 (only with --do-checks)
115
116       character set:
117
118         +l1   --latin1
119                 set latin-1 as standard character set (default)
120
121         -l1   --no-latin1
122                 keep 7-bit ASCII as standard character set
123
124       other processing options:
125
126         -k    --key  [k]ey: gggg,eeee="str", path or dictionary name="str"
127                 add further attribute
128
129   output options
130       target SOP class:
131
132         -sc   --sec-capture
133                 write Secondary Capture SOP class
134
135         -nsc  --new-sc
136                 write new Secondary Capture SOP classes
137
138         -vlp  --vl-photo
139                 write Visible Light Photographic SOP class (default)
140
141       output file format:
142
143         +F    --write-file
144                 write file format (default)
145
146         -F    --write-dataset
147                 write data set without file meta information
148
149       group length encoding:
150
151         +g=   --group-length-recalc
152                 recalculate group lengths if present (default)
153
154         +g    --group-length-create
155                 always write with group length elements
156
157         -g    --group-length-remove
158                 always write without group length elements
159
160       length encoding in sequences and items:
161
162         +e    --length-explicit
163                 write with explicit lengths (default)
164
165         -e    --length-undefined
166                 write with undefined lengths
167
168       data set trailing padding (not with --write-dataset):
169
170         -p    --padding-off
171                 no padding (implicit if --write-dataset)
172
173         +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

NOTES

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
186       • 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
210             Study Level:
211               Study Instance UID
212               Study Date
213               Study Time
214               Referring Physician's Name
215               Study ID
216               Accession Number
217
218             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
258       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.

EXAMPLES

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.

LOGGING

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.

COMMAND LINE

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

ENVIRONMENT

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.

FILES

423       <datadir>/SC.dump - Sample dump file for Secondary Capture images
424       <datadir>/VLP.dump  -  Sample  dump file for Visible Light Photographic
425       images

SEE ALSO

427       dcm2pnm(1), dcmj2pnm(1), dump2dcm(1), dcmconv(1), dcmodify(1)
429       Copyright (C) 2007-2021 e.V., Escherweg 2, 26121 Oldenburg, Germany.
430
431
432
433Version 3.6.6                   Thu Jan 14 2021                     img2dcm(1)
Impressum