Provided by: dcmtk_3.6.0-15+deb8u1build0.14.04.1_amd64 bug

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:
               Patient's Name
               Patient ID
               Patient's Sex
               Patient's Birth Date
               Specific Character Set

             Study Level:
               Study Instance UID
               Study Date
               Study Time
               Referring Physician's 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 object's 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  object's
           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.