img2dcm(1)                        OFFIS DCMTK                       img2dcm(1)



NAME
       img2dcm - Convert standard image formats into DICOM format

SYNOPSIS
       img2dcm [options] imgfile-in dcmfile-out


DESCRIPTION
       The  img2dcm  tool  serves  as  a conversion tool from a standard image
       format like JPEG or BMP to DICOM. Different output SOP Classes  can  be
       selected. The additional information (regarding patients, series, etc.)
       stored in the DICOM output file can be extracted from other DICOM files
       which serve as a template for the resulting DICOM object. img2dcm can
       also be configured to invent missing DICOM type 1 and type 2 attributes
       to work even without any template dataset.

PARAMETERS
       imgfile-in   image file to be imported

       dcmfile-out  DICOM output file


OPTIONS
   general options
         -h    --help
                 print this help text and exit

               --version
                 print version information and exit

               --arguments
                 print expanded command line arguments

         -q    --quiet
                 quiet mode, print no warnings and errors

         -v    --verbose
                 verbose mode, print processing details

         -d    --debug
                 debug mode, print debug information

         -ll   --log-level  [l]evel: string constant
                 (fatal, error, warn, info, debug, trace)
                 use level l for the logger

         -lc   --log-config  [f]ilename: string
                 use config file f for the logger


   input options
       general:

         -i    --input-format  [i]nput file format: string
                 supported formats: JPEG (default), BMP

         -df   --dataset-from  [f]ilename: string
                 use dataset from DICOM file f

         -stf  --study-from  [f]ilename: string
                 read patient/study from DICOM file f

         -sef  --series-from  [f]ilename: string
                 read patient/study/series from DICOM file f

         -ii   --instance-inc
                 increase instance number read from DICOM file

       JPEG format:

         -dp   --disable-progr
                 disable support for progressive JPEG

         -de   --disable-ext
                 disable support for extended sequential JPEG

         -jf   --insist-on-jfif
                 insist on JFIF header existence

         -ka   --keep-appn
                 keep APPn sections (except JFIF)


   processing options
       attribute checking:

               --do-checks
                 enable attribute validity checking (default)

               --no-checks
                 disable attribute validity checking

         +i2   --insert-type2
                 insert missing type 2 attributes (default)
                 (only with --do-checks)

         -i2   --no-type2-insert
                 do not insert missing type 2 attributes
                 (only with --do-checks)

         +i1   --invent-type1
                 invent missing type 1 attributes
                 (only with --do-checks)

         -i1   --no-type1-invent
                 do not invent missing type 1 attributes
                 (only with --do-checks)

       character set:

         +l1   --latin1
                 set latin-1 as standard character set (default)

         -l1   --no-latin1
                 keep 7-bit ASCII as standard character set

       other processing options:

         -k    --key  [k]ey: gggg,eeee="str", path or dictionary name="str"
                 add further attribute


   output options
       target SOP class:

         -sc   --sec-capture
                 write Secondary Capture SOP class

         -nsc  --new-sc
                 write new Secondary Capture SOP classes

         -vlp  --vl-photo
                 write Visible Light Photographic SOP class (default)

       output file format:

         +F    --write-file
                 write file format (default)

         -F    --write-dataset
                 write data set without file meta information

       group length encoding:

         +g=   --group-length-recalc
                 recalculate group lengths if present (default)

         +g    --group-length-create
                 always write with group length elements

         -g    --group-length-remove
                 always write without group length elements

       length encoding in sequences and items:

         +e    --length-explicit
                 write with explicit lengths (default)

         -e    --length-undefined
                 write with undefined lengths

       data set trailing padding (not with --write-dataset):

         -p    --padding-off
                 no padding (implicit if --write-dataset)

         +p    --padding-create  [f]ile-pad [i]tem-pad: integer
                 align file on multiple of f bytes
                 and items on multiple of i bytes


NOTES
   Attribute Sources
       For  converting  a  general image format into DICOM format, the img2dcm
       application may be fed with some additional input for filling mandatory
       (and optional) attributes in the new DICOM file like patient, study and
       series information. This information can be collected  using  different
       approaches, which can be combined and are applied to the result file in
       the following order:

        Using  the  --dataset-from  option  img2dcm  is  forced   to   import
         attributes from an existing DICOM file. The given DICOM file is fully
         imported and serves as the basis for all further  export  operations.
         As  an  exception, the SOP Instance UID is not copied by this option.
         Also image related data like Rows, Columns etc. is  exchanged  during
         conversion.  Note  that  img2dcm  does  not check any other attribute
         values for validity, e. g. it does not look into sequences  to  adapt
         any attributes to the new object (referenced images etc.). Therefore,
         it is recommended to use the templates  in  the  data  directory  for
         (old) SC and VLP objects. See also section Input Templates.
        The  --study-from  and --series-from options (mutually exclusive) can
         be used to import patient,  study  and  series  information  from  an
         existing  DICOM  file.  If --series-from is specified, then the given
         DICOM file is opened by img2dcm and all mandatory information down to
         the  series level is imported. Note that this includes patient, study
         and  series  information.  In  case  of  --study-from,   the   series
         information is excluded. The following attributes are taken over:

             Patient Level:
               Patients Name
               Patient ID
               Patients Sex
               Patients Birth Date
               Specific Character Set

             Study Level:
               Study Instance UID
               Study Date
               Study Time
               Referring Physicians Name
               Study ID
               Accession Number

             Series Level (only in case of option --series-from):
               Series Instance UID
               Series Number
               Manufacturer


        With  the --insert-type2 and --invent-type1 options (both enabled per
         default), missing  attributes  (type  2  attributes)  and/or  missing
         attribute  values (for type 1 attributes) are automatically added and
         invented  by  img2dcm.  Please  note  that  these  options  are  only
         evaluated  if  option  --do-checks is enabled (default). If the --no-
         checks options is enabled, no automatic attribute insertion will take
         place.
        The  --key  option can be used to add further attributes to the DICOM
         output file. This option is applied at  the  very  end,  just  before
         saving  the  DICOM  file.  It  is also possible to specify sequences,
         items and nested attributes using the --key option. In these cases, a
         special path notation has to be used. Details on this path notation
         can be found in the documentation of dcmodify.
   UIDs
       New Study and Series Instance UIDs are  generated  if  necessary  after
       applying  the  --study-from and --series options. If Study Instance UID
       or Series Instance UID are not present  after  these  steps,  they  are
       newly generated, independently from each other. A contrary behaviour is
       choosen for the SOP Instance UID that one could expect to be taken over
       when  using  the  --dataset-from  option. This is not the case, the SOP
       Instance UID is not copied to  the  new  object.  This  should  be  the
       desirable  behaviour  for  most  use  cases.  However, if a certain SOP
       Instance UID should be inserted into the new object, the  --key  option
       should be used.
   Input Templates
       For  supporting the conversion into DICOM, img2dcm comes with some pre-
       defined templates which can be used for the --dataset-from option  (see
       sample  files  SC.dump  and VLP.dump). These templates should be filled
       with the desired values and then must be dumped (converted) to a  DICOM
       file  before  actually being used with img2dcm. Use dump2dcm to convert
       the dump to DICOM. Example:

         dump2dcm SC.dump SC.dcm

       It is possible to use any DICOM file as a template.  Please  note  that
       the  complete  DICOM  dataset  is imported; hence, it should be assured
       that  only  attributes  are  present  which  should  be  part  of   the
       constructed  DICOM  object.  The  SOP  Class  UID  and  the  Pixel Data
       attributes (including attributes  like  Rows,  Columns  etc.)  are  not
       copied but replaced by img2dcm during conversion.
   Input Plugins
       The  img2dcm  application currently supports the JPEG and the BMP image
       format as input.
   JPEG Input Plugin
       For JPEG, the original JPEG from the source file  is  not  decoded  but
       extracted  and  slightly  transformed (e. g. JFIF header is cut off) to
       allow fast conversion of even  big  JPEG  files  without  the  need  of
       decoding  and re-encoding. The JPEG plugin chooses the necessary output
       transfer syntax automatically depending on the actual encoding  of  the
       data  inside  the JPEG file. Therefore, the following Transfer Syntaxes
       (and their corresponding JPEG encodings) are used by the JPEG plugin:
        JPEG Coding Process 1 Baseline, Lossy, Non-Hierarchical,  Sequential,
         DCT, Huffman, 8 Bit SOP Class = 1.2.840.10008.1.2.4.50
        JPEG  Coding  Process  2 (8-bit) and 4 (12-bit) Extended, Lossy, Non-
         Hierarchical,  Sequential,  DCT,  Huffman,  8/12  Bit  SOP  Class   =
         1.2.840.10008.1.2.4.51
        JPEG  Coding  Process  10  (8-bit)  and 12 (12-bit) Full Progression,
         lossy, Non-Hierarch., Progressive, DCT, Huffman, 8/12 Bit SOP Class =
         1.2.840.10008.1.2.4.55
       Color and grayscale images are supported.
       The  support  for  the  Extended  JPEG  Transfer Syntax can be disabled
       (--disable-ext option)  as  well  as  the  support  for  the  (retired)
       Progressive JPEG Transfer Syntax (--disable-progr option).
       JPEG  lossless encoding as well as any arithmethic or hierarchical JPEG
       encoding modes are not supported by the plugin.
       JFIF (JPEG File Interchange Format)  information  facilitates  optional
       APPn markers in a JPEG file. Many digital cameras do not integrate such
       JFIF information into the JPEG output they create.  For  example,  JFIF
       contains  information  about  the  pixel aspect ratio of the compressed
       image. If you want the img2dcm application to insist on a  JFIF  header
       in  the JPEG stream, you can use the option --insist-on-jfif which will
       abort if no JFIF information can be found.  By  default,  missing  JFIF
       information is ignored.
       For  DICOM it is kind of a gray zone, whether the integration of JFIF
       (or any other APPn) data into the DICOM objects internal  JPEG  stream
       is  allowed or not. However, the most reliable approach is to cut those
       markers and their information off the JPEG  stream.  This  approach  is
       also taken by the img2dcm application. By default, all APPn markers are
       cut off from the original JPEG stream. However, if  you  want  to  keep
       other  APPn markers than JFIF (e. g. EXIF information) inside the DICOM
       stream, the option --keep-appn  does  the  trick.  It  should  also  be
       slightly  faster  than  cutting off APPn information, because it is not
       necessary to scan the whole JPEG stream for such data. JFIF information
       is always removed by img2dcm.
   BMP Input Plugin
       img2dcm  supports  BMP  as  input format. However, so far only the most
       commmon BMP images are supported. In particular, BMP images  which  use
       bitfields  or  run  length  encoding  will be rejected. Such images are
       uncommon. All input images will be converted into a  DICOM  image  with
       RGB  color  model  and a bit depth of 24. There are no specific options
       for fine-tuning BMP format conversion.
   Output Plugins
       The desired output SOP Class can  be  selected  on  the  command  line.
       Currently,  an  export plugin for the Secondary Capture Image SOP class
       (default, option -sc), the new  Secondary  Capture  Image  SOP  classes
       (option  -nsc)  and  Visible Light Photographic Image SOP class (option
       -vl) are available. Please  note  that  the  first  one  is  deprecated
       according to the DICOM standard but is selected as a default because it
       is widely supported. Future versions of img2dcm might  provide  further
       output plugins for other SOP Classes.
       For  the  new  Secondary  Capture  SOP  classes,  it is not possible to
       specifiy which specific SOP class should be used for  output.  That  is
       because  these  new  SOP  classes are differentiated from each other by
       colour depth (1/8/16) and the fact whether the image is black/white  or
       colour. That is why img2dcm decides during conversion, which output SOP
       class is suitable for a given source image.
EXAMPLES
       Here are some examples that show how the  img2dcm  application  can  be
       used.
       1.  img2dcm image.jpg out.dcm
           Read  JPEG  file  image.jpg, convert to the old Secondary Capture
           SOP class and save the result to DICOM file out.dcm. This is  the
           easiest  way  of  using  img2dcm.  Any type 1 and type 2 attributes
           required for writing valid objects of this SOP class  are  inserted
           automatically.

       2.  img2dcm -i BMP image.bmp out.dcm
           Same as above but tells img2dcm to read a BMP file instead of JPEG.

       3.  img2dcm image.jpg out.dcm -vlp -k PatientName=Bond^James
           Same as first example, but writes Visible Light Photographic  Image
           object  to  out.dcm  and  sets  PatientName to Bond^James which
           otherwise would be left empty.

       4.  img2dcm   image.jpg   out.dcm   --series-from    template.dcm    -k
           PatientName=Bond^James
           Same  as 1), but imports patient/study/series infomation from DICOM
           file template.dcm. Please note that  attribute  PatientName  will
           contain Bond^James at the end, any value from template.dcm will
           be overwritten. That is, because the -k option is  applied  at  the
           very end of the conversion pipeline (see above).

       5.  img2dcm image.jpg out.dcm --no-checks
           Same as 1), but does not perform any attribute checking and no type
           1 and type 2 attribute insertion! So in this case, an invalid DICOM
           object  would  be  generated. This can be interesting if the output
           file is  not  meant  to  be  completed  but  will  undergo  further
           transformations,  e.  g. adding attributes using dcmodify. Only use
           option --no-checks if you know what you are doing!

       6.  img2dcm image.jpg out.dcm --no-type1-invent
           Same as 1), but does not insert missing type  1  attributes  and/or
           their values. Type 2 attributes will be inserted. Note that in this
           case it must be assured that all type 1 attributes are provided  by
           other means, i. e. by adding them with the --key option. Otherwise,
           img2dcm will report an error and will stop converting.

       7.  img2dcm image.jpg out.dcm --keep-appn --insist-on-jfif
           Same as 1), but takes over APPn  information  like  EXIF  into  the
           DICOM  objects  resulting  JPEG  stream. Further, --insist-on-jfif
           will force img2dcm to abort if no JFIF information is  existent  in
           the source file.

LOGGING
       The  level  of  logging  output  of  the various command line tools and
       underlying libraries can be specified by the  user.  By  default,  only
       errors  and  warnings  are  written to the standard error stream. Using
       option --verbose also informational messages  like  processing  details
       are  reported.  Option  --debug  can be used to get more details on the
       internal activity, e.g. for debugging purposes.  Other  logging  levels
       can  be  selected  using option --log-level. In --quiet mode only fatal
       errors are reported. In such very severe error events, the  application
       will  usually  terminate.  For  more  details  on the different logging
       levels, see documentation of module oflog.
       In case the logging output should be written to file  (optionally  with
       logfile  rotation),  to syslog (Unix) or the event log (Windows) option
       --log-config can be used.  This  configuration  file  also  allows  for
       directing  only  certain messages to a particular output stream and for
       filtering certain messages based on the  module  or  application  where
       they  are  generated.  An  example  configuration  file  is provided in
       <etcdir>/logger.cfg).
COMMAND LINE
       All command line tools  use  the  following  notation  for  parameters:
       square  brackets  enclose  optional  values  (0-1), three trailing dots
       indicate that multiple values are allowed (1-n), a combination of  both
       means 0 to n values.
       Command line options are distinguished from parameters by a leading +
       or - sign, respectively. Usually, order and position of command  line
       options  are  arbitrary  (i.e.  they  can appear anywhere). However, if
       options are mutually exclusive the rightmost appearance is  used.  This
       behaviour  conforms  to  the  standard  evaluation rules of common Unix
       shells.
       In addition, one or more command files can be specified  using  an  @
       sign  as  a  prefix to the filename (e.g. @command.txt). Such a command
       argument is replaced by the content  of  the  corresponding  text  file
       (multiple  whitespaces  are  treated  as a single separator unless they
       appear between two quotation marks) prior to  any  further  evaluation.
       Please  note  that  a command file cannot contain another command file.
       This  simple  but  effective  approach  allows  to   summarize   common
       combinations  of  options/parameters  and  avoids longish and confusing
       command lines (an example is provided in file <datadir>/dumppat.txt).
ENVIRONMENT
       The img2dcm utility  will  attempt  to  load  DICOM  data  dictionaries
       specified  in the DCMDICTPATH environment variable. By default, i.e. if
       the  DCMDICTPATH  environment   variable   is   not   set,   the   file
       <datadir>/dicom.dic  will be loaded unless the dictionary is built into
       the application (default for Windows).
       The  default  behaviour  should  be  preferred  and   the   DCMDICTPATH
       environment  variable  only used when alternative data dictionaries are
       required. The DCMDICTPATH environment variable has the same  format  as
       the  Unix  shell PATH variable in that a colon (:) separates entries.
       On Windows systems, a semicolon (;) is used as a separator. The  data
       dictionary  code  will  attempt  to  load  each  file  specified in the
       DCMDICTPATH environment variable. It is an error if no data  dictionary
       can be loaded.
FILES
       <datadir>/SC.dump - Sample dump file for Secondary Capture images
       <datadir>/VLP.dump  -  Sample  dump file for Visible Light Photographic
       images
SEE ALSO
       dcm2pnm(1), dcmj2pnm(1), dump2dcm(1), dcmconv(1), dcmodify(1)
COPYRIGHT
       Copyright (C) 2007-2010 by OFFIS e.V., Escherweg  2,  26121  Oldenburg,
       Germany.



Version 3.6.0                     6 Jan 2011                        img2dcm(1)
