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

PARAMETERS

22       imgfile-in   image file to be imported
23
24       dcmfile-out  DICOM output file
25

OPTIONS

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

NOTES

172   Attribute Sources
173       For  converting  a  general image format into DICOM format, the img2dcm
174       application may be fed with some additional input for filling mandatory
175       (and optional) attributes in the new DICOM file like patient, study and
176       series information. This information can be collected  using  different
177       approaches, which can be combined and are applied to the result file in
178       the following order:
179
180       • Using  the  --dataset-from  option  img2dcm  is  forced   to   import
181         attributes from an existing DICOM file. The given DICOM file is fully
182         imported and serves as the basis for all further  export  operations.
183         As  an  exception, the SOP Instance UID is not copied by this option.
184         Also image related data like Rows, Columns etc. is  exchanged  during
185         conversion.  Note  that  img2dcm  does  not check any other attribute
186         values for validity, e. g. it does not look into sequences  to  adapt
187         any attributes to the new object (referenced images etc.). Therefore,
188         it is recommended to use the templates  in  the  data  directory  for
189         (old) SC and VLP objects. See also section 'Input Templates'.
190       • The  --study-from  and --series-from options (mutually exclusive) can
191         be used to import patient,  study  and  series  information  from  an
192         existing  DICOM  file.  If --series-from is specified, then the given
193         DICOM file is opened by img2dcm and all mandatory information down to
194         the  series level is imported. Note that this includes patient, study
195         and  series  information.  In  case  of  --study-from,   the   series
196         information is excluded. The following attributes are taken over:
197             Patient Level:
198               Patient's Name
199               Patient ID
200               Patient's Sex
201               Patient's Birth Date
202               Specific Character Set
203
204             Study Level:
205               Study Instance UID
206               Study Date
207               Study Time
208               Referring Physician's Name
209               Study ID
210               Accession Number
211
212             Series Level (only in case of option --series-from):
213               Series Instance UID
214               Series Number
215               Manufacturer
216       • With  the --insert-type2 and --invent-type1 options (both enabled per
217         default), missing  attributes  (type  2  attributes)  and/or  missing
218         attribute  values (for type 1 attributes) are automatically added and
219         invented  by  img2dcm.  Please  note  that  these  options  are  only
220         evaluated  if  option  --do-checks is enabled (default). If the --no-
221         checks options is enabled, no automatic attribute insertion will take
222         place.
223       • The  --key  option can be used to add further attributes to the DICOM
224         output file. This option is applied at  the  very  end,  just  before
225         saving  the  DICOM  file.  It  is also possible to specify sequences,
226         items and nested attributes using the --key option. In these cases, a
227         special 'path' notation has to be used. Details on this path notation
228         can be found in the documentation of dcmodify.
229   UIDs
230       New Study and Series Instance UIDs are  generated  if  necessary  after
231       applying  the  --study-from and --series options. If Study Instance UID
232       or Series Instance UID are not present  after  these  steps,  they  are
233       newly  generated, independently from each other. A contrary behavior is
234       chosen for the SOP Instance UID that one could expect to be taken  over
235       when  using  the  --dataset-from  option. This is not the case, the SOP
236       Instance UID is not copied to  the  new  object.  This  should  be  the
237       desirable  behavior  for  most  use  cases.  However,  if a certain SOP
238       Instance UID should be inserted into the new object, the  --key  option
239       should be used.
240   Input Templates
241       For  supporting the conversion into DICOM, img2dcm comes with some pre-
242       defined templates which can be used for the --dataset-from option  (see
243       sample  files  SC.dump  and VLP.dump). These templates should be filled
244       with the desired values and then must be dumped (converted) to a  DICOM
245       file  before  actually being used with img2dcm. Use dump2dcm to convert
246       the dump to DICOM. Example:
247         dump2dcm SC.dump SC.dcm
248
249       It is possible to use any DICOM file as a template.  Please  note  that
250       the  complete  DICOM  dataset  is imported; hence, it should be assured
251       that  only  attributes  are  present  which  should  be  part  of   the
252       constructed  DICOM  object.  The  SOP  Class  UID  and  the  Pixel Data
253       attributes (including attributes  like  Rows,  Columns  etc.)  are  not
254       copied but replaced by img2dcm during conversion.
255   Input Plugins
256       The  img2dcm  application currently supports the JPEG and the BMP image
257       format as input.
258   JPEG Input Plugin
259       For JPEG, the original JPEG from the source file  is  not  decoded  but
260       extracted  and  slightly  transformed (e. g. JFIF header is cut off) to
261       allow fast conversion of even  big  JPEG  files  without  the  need  of
262       decoding  and re-encoding. The JPEG plugin chooses the necessary output
263       transfer syntax automatically depending on the actual encoding  of  the
264       data  inside  the JPEG file. Therefore, the following Transfer Syntaxes
265       (and their corresponding JPEG encodings) are used by the JPEG plugin:
266       • JPEG Coding Process 1 Baseline, Lossy, Non-Hierarchical,  Sequential,
267         DCT, Huffman, 8 Bit SOP Class = 1.2.840.10008.1.2.4.50
268       • JPEG  Coding  Process  2 (8-bit) and 4 (12-bit) Extended, Lossy, Non-
269         Hierarchical,  Sequential,  DCT,  Huffman,  8/12  Bit  SOP  Class   =
270         1.2.840.10008.1.2.4.51
271       • JPEG  Coding  Process  10  (8-bit)  and 12 (12-bit) Full Progression,
272         lossy, Non-Hierarch., Progressive, DCT, Huffman, 8/12 Bit SOP Class =
273         1.2.840.10008.1.2.4.55
274       Color and grayscale images are supported.
275       The  support  for  the  Extended  JPEG  Transfer Syntax can be disabled
276       (--disable-ext option)  as  well  as  the  support  for  the  (retired)
277       Progressive JPEG Transfer Syntax (--disable-progr option).
278       JPEG  lossless  encoding as well as any arithmetic or hierarchical JPEG
279       encoding modes are not supported by the plugin.
280       JFIF (JPEG File Interchange Format)  information  facilitates  optional
281       APPn markers in a JPEG file. Many digital cameras do not integrate such
282       JFIF information into the JPEG output they create.  For  example,  JFIF
283       contains  information  about  the  pixel aspect ratio of the compressed
284       image. If you want the img2dcm application to insist on a  JFIF  header
285       in  the JPEG stream, you can use the option --insist-on-jfif which will
286       abort if no JFIF information can be found.  By  default,  missing  JFIF
287       information is ignored.
288       For  DICOM it is kind of a 'gray zone', whether the integration of JFIF
289       (or any other APPn) data into the DICOM object's internal  JPEG  stream
290       is  allowed or not. However, the most reliable approach is to cut those
291       markers and their information off the JPEG  stream.  This  approach  is
292       also taken by the img2dcm application. By default, all APPn markers are
293       cut off from the original JPEG stream. However, if  you  want  to  keep
294       other  APPn markers than JFIF (e. g. EXIF information) inside the DICOM
295       stream, the option --keep-appn  does  the  trick.  It  should  also  be
296       slightly  faster  than  cutting off APPn information, because it is not
297       necessary to scan the whole JPEG stream for such data. JFIF information
298       is always removed by img2dcm.
299   BMP Input Plugin
300       img2dcm  supports  BMP  as  input format. However, so far only the most
301       common BMP images are supported. In particular, BMP  images  which  use
302       bit  fields  or  run  length encoding will be rejected. Such images are
303       uncommon. All input images will be converted into a  DICOM  image  with
304       RGB  color  model  and a bit depth of 24. There are no specific options
305       for fine-tuning BMP format conversion.
306   Output Plugins
307       The desired output SOP Class can  be  selected  on  the  command  line.
308       Currently,  an  export plugin for the Secondary Capture Image SOP class
309       (default, option -sc), the new  Secondary  Capture  Image  SOP  classes
310       (option  -nsc)  and  Visible Light Photographic Image SOP class (option
311       -vl) are available. Please  note  that  the  first  one  is  deprecated
312       according to the DICOM standard but is selected as a default because it
313       is widely supported. Future versions of img2dcm might  provide  further
314       output plugins for other SOP Classes.
315       For  the  new  Secondary  Capture  SOP  classes,  it is not possible to
316       specify which specific SOP class should be used  for  output.  That  is
317       because  these  new  SOP  classes are differentiated from each other by
318       color depth (1/8/16) and the fact whether the image is  black/white  or
319       color.  That is why img2dcm decides during conversion, which output SOP
320       class is suitable for a given source image.

EXAMPLES

322       Here are some examples that show how the  img2dcm  application  can  be
323       used.
324       1.  img2dcm image.jpg out.dcm
325           Read  JPEG  file  'image.jpg', convert to the old Secondary Capture
326           SOP class and save the result to DICOM file 'out.dcm'. This is  the
327           easiest  way  of  using  img2dcm.  Any type 1 and type 2 attributes
328           required for writing valid objects of this SOP class  are  inserted
329           automatically.
330       2.  img2dcm -i BMP image.bmp out.dcm
331           Same as above but tells img2dcm to read a BMP file instead of JPEG.
332       3.  img2dcm image.jpg out.dcm -vlp -k 'PatientName=Bond^James'
333           Same  as first example, but writes Visible Light Photographic Image
334           object to 'out.dcm' and  sets  PatientName  to  'Bond^James'  which
335           otherwise would be left empty.
336       4.  img2dcm    image.jpg    out.dcm   --series-from   template.dcm   -k
337           'PatientName=Bond^James'
338           Same as 1), but imports patient/study/series information from DICOM
339           file  'template.dcm'.  Please  note that attribute PatientName will
340           contain 'Bond^James' at the end, any value from 'template.dcm' will
341           be  overwritten.  That  is, because the -k option is applied at the
342           very end of the conversion pipeline (see above).
343       5.  img2dcm image.jpg out.dcm --no-checks
344           Same as 1), but does not perform any attribute checking and no type
345           1 and type 2 attribute insertion! So in this case, an invalid DICOM
346           object would be generated. This can be interesting  if  the  output
347           file  is  not  meant  to  be  completed  but  will  undergo further
348           transformations, e. g. adding attributes using dcmodify.  Only  use
349           option --no-checks if you know what you are doing!
350       6.  img2dcm image.jpg out.dcm --no-type1-invent
351           Same  as  1),  but does not insert missing type 1 attributes and/or
352           their values. Type 2 attributes will be inserted. Note that in this
353           case  it must be assured that all type 1 attributes are provided by
354           other means, i. e. by adding them with the --key option. Otherwise,
355           img2dcm will report an error and will stop converting.
356       7.  img2dcm image.jpg out.dcm --keep-appn --insist-on-jfif
357           Same  as  1),  but  takes  over APPn information like EXIF into the
358           DICOM object's resulting  JPEG  stream.  Further,  --insist-on-jfif
359           will  force  img2dcm to abort if no JFIF information is existent in
360           the source file.

LOGGING

362       The level of logging output of  the  various  command  line  tools  and
363       underlying  libraries  can  be  specified by the user. By default, only
364       errors and warnings are written to the  standard  error  stream.  Using
365       option  --verbose  also  informational messages like processing details
366       are reported. Option --debug can be used to get  more  details  on  the
367       internal  activity,  e.g.  for debugging purposes. Other logging levels
368       can be selected using option --log-level. In --quiet  mode  only  fatal
369       errors  are reported. In such very severe error events, the application
370       will usually terminate. For  more  details  on  the  different  logging
371       levels, see documentation of module 'oflog'.
372       In  case  the logging output should be written to file (optionally with
373       logfile rotation), to syslog (Unix) or the event log  (Windows)  option
374       --log-config  can  be  used.  This  configuration  file also allows for
375       directing only certain messages to a particular output stream  and  for
376       filtering  certain  messages  based  on the module or application where
377       they are generated.  An  example  configuration  file  is  provided  in
378       <etcdir>/logger.cfg.

COMMAND LINE

380       All  command  line  tools  use  the  following notation for parameters:
381       square brackets enclose optional  values  (0-1),  three  trailing  dots
382       indicate  that multiple values are allowed (1-n), a combination of both
383       means 0 to n values.
384       Command line options are distinguished from parameters by a leading '+'
385       or  '-' sign, respectively. Usually, order and position of command line
386       options are arbitrary (i.e. they  can  appear  anywhere).  However,  if
387       options  are  mutually exclusive the rightmost appearance is used. This
388       behavior conforms to the  standard  evaluation  rules  of  common  Unix
389       shells.
390       In  addition,  one  or more command files can be specified using an '@'
391       sign as a prefix to the filename (e.g. @command.txt).  Such  a  command
392       argument  is  replaced  by  the  content of the corresponding text file
393       (multiple whitespaces are treated as a  single  separator  unless  they
394       appear  between  two  quotation marks) prior to any further evaluation.
395       Please note that a command file cannot contain  another  command  file.
396       This  simple  but  effective  approach  allows  one to summarize common
397       combinations of options/parameters and  avoids  longish  and  confusing
398       command lines (an example is provided in file <datadir>/dumppat.txt).

ENVIRONMENT

400       The  img2dcm  utility  will  attempt  to  load  DICOM data dictionaries
401       specified in the DCMDICTPATH environment variable. By default, i.e.  if
402       the   DCMDICTPATH   environment   variable   is   not   set,  the  file
403       <datadir>/dicom.dic will be loaded unless the dictionary is built  into
404       the application (default for Windows).
405       The   default   behavior   should  be  preferred  and  the  DCMDICTPATH
406       environment variable only used when alternative data  dictionaries  are
407       required.  The  DCMDICTPATH environment variable has the same format as
408       the Unix shell PATH variable in that a colon (':')  separates  entries.
409       On  Windows systems, a semicolon (';') is used as a separator. The data
410       dictionary code will  attempt  to  load  each  file  specified  in  the
411       DCMDICTPATH  environment variable. It is an error if no data dictionary
412       can be loaded.

FILES

414       <datadir>/SC.dump - Sample dump file for Secondary Capture images
415       <datadir>/VLP.dump - Sample dump file for  Visible  Light  Photographic
416       images

SEE ALSO

418       dcm2pnm(1), dcmj2pnm(1), dump2dcm(1), dcmconv(1), dcmodify(1)
420       Copyright  (C)  2007-2016  by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
421       Germany.
422
423
424
425Version 3.6.4                   Thu Nov 29 2018                     img2dcm(1)
Impressum