Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	(including JPEG-LS) 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 input	filename

       dcmfile-out  DICOM output filename ("-" for stdout)

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

	 -dx   --dataset-from-xml  [f]ilename: string
		 use dataset from XML 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)

	 -rc   --remove-com
		 remove	COM segment

       XML validation:

	 +Vd   --validate-document
		 validate XML document against DTD

	 +Vn   --check-namespace
		 check XML namespace in	document root

   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 (default)
		 (only with --do-checks)

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

       character set conversion	of study/series	file:

	 -Ct   --transliterate
		 try to	approximate characters that cannot be
		 represented through similar looking characters

	 -Cd   --discard-illegal
		 discard characters that cannot	be represented
		 in destination	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 (default)

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

	 -vlp  --vl-photo
		 write Visible Light Photographic SOP class

	 -oph  --oph-photo
		 write Ophthalmic Photography SOP classes

       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'. As an
	 alternative to	option --dataset-from the  mutually  exclusive	option
	 --dataset-from-xml  can be used. In this case,	however, the file must
	 contain XML data in the format	as produced by dcm2xml.

        The --study-from and --series-from options  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.  Using --study-from and --series-from at the	same time does
	 make sense. If	both options are provided on  the  command  line,  the
	 rightmost option wins.	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.	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.  The	--key  option  can  be
	 present  more than once. The value part (after	the '=') may be	absent
	 causing the attribute to be set with zero length. Please  be  advised
	 that  the --key option	is applied at the very end, just before	saving
	 the DICOM file, so there is no	value checking whatsoever.

   UIDs
       New Study and Series Instance UIDs are  generated  if  necessary	 after
       applying	 the --study-from and --series-from 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  behavior is	chosen for the SOP Instance UID	that one could
       expect to be taken over when using  the	--dataset-from	or  --dataset-
       from-xml	 option.  This	is  not	 the case, the SOP Instance UID	is not
       copied to the new object. This should be	 the  desirable	 behavior  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

       For  Ophthalmic	Photography  images,  XML  templates are provided (see
       sample file OP_template_utf_8.xml and OP_template_latin_1.xml).

       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.

   Multiframe Images
       It  is  possible	 to  convert  multiple	input  files  into  one	 DICOM
       multiframe image	if the selected	DICOM SOP class	 supports  multiframe.
       In  particular,	the  Multi-frame Secondary Capture SOP Classes support
       this feature. They are  selected	 through  the  --new-sc	 command  line
       option.

   Character Sets
       When  an	 input	template  is loaded using --dataset-from or --dataset-
       from-xml, the specific character	set of that template is	used  for  the
       generated  DICOM	file. If the --study-from or --series-from options are
       used additionally, img2dcm will try to convert  the  character  set  of
       these  attributes  to that of the template, and will report an error if
       that is not possible.

       If the  --study-from  or	 --series-from	options	 are  used  without  a
       template,  the  specific	 character  set	of this	source is used for the
       generated DICOM file. Any keys specified	on the command line  with  the
       --key  option are treated as raw	bytes and override any attributes that
       may already  be	present	 due  to  a  template  or  study/series	 file.
       Therefore, care should be taken to not specify a	specific character set
       on  the	command	 line  if one might be loaded from another file. It is
       also  the  user's  responsibility  to  ensure  that  attribute	values
       specified  on  the  command  line  use  the  correct  encoding,	as  no
       conversion will take place before the values are	stored	in  the	 DICOM
       file.

   Input Plugins
       The  img2dcm  application  currently supports the JPEG, JPEG-LS 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
	  Transfer Syntax UID =	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
	  Transfer Syntax UID =	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
	  Transfer Syntax UID =	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 arithmetic	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. As	stated
       before, JFIF information	is always removed by  img2dcm.	However,  when
       using  this  option,  the APP2 marker is	retained, but img2dcm does not
       create an equivalent ICC	Profile	(0028,2000) attribute.

   JPEG-LS Input Plugin
       The JPEG-LS plugin has been integrated  directly	 into  the  main  JPEG
       plugin. There is	no need	for the	user to	explicitly state in advance if
       input is	JPEG or	JPEG-LS.

       For  JPEGL-LS, the original JPEG-LS from	the source file	is not decoded
       but extracted and slightly transformed (e. g. APP8 marker is  cut  off)
       to  allow fast conversion of even big JPEG-LS files without the need of
       decoding	and re-encoding.

       The  JPEG-LS  plugin  chooses  the  necessary  output  transfer	syntax
       automatically  depending	 on the	actual encoding	of the data inside the
       JPEG-LS file. Therefore,	the following  Transfer	 Syntaxes  (and	 there
       corresponding JPEG-LS encodings)	are used by the	JPEG-LS	plugin:

        JPEG-LS Lossless Image	Compression
	  Transfer Syntax UID =	1.2.840.10008.1.2.4.80

        JPEG-LS Lossy (Near-Lossless) Image Compression
	  Transfer Syntax UID =	1.2.840.10008.1.2.4.81

       Color  and  grayscale  images  are  supported. CP-1843 enforce that the
       value of	Planar	Configuration  (0028,0006)  is	irrelevant  since  the
       manner of encoding components is	specified in the JPEG-LS bit stream as
       component,  line	 or  sample  interleaved,  hence it shall be set to 0.
       Since no	color transformation specific for JPEG-LS is currently defined
       in DICOM, it is assumed that the	JPEG-LS	stream is encoded in RGB color
       space.

       For DICOM it is clear that SPIFF	header should not be  present  in  the
       DICOM  object's internal	JPEG-LS	stream.	The plugin will	simply rejects
       any input JPEG-LS file containing a SPIFF header	at marker APP8.

       By default, all APPn markers are	cut  off  from	the  original  JPEG-LS
       stream.	However,  if you want to keep APPn markers (e.g. APP8/HP color
       transform information, aka 'mrfx') inside the DICOM stream, the	option
       --keep-appn  does  the  trick. Pay attention that the plugin will check
       the actual color	transform specified in the APP8/HP marker. Since DICOM
       does not	allow any color	transform to be	specified in the APP8  marker,
       only a value of 0 (no color transform) is accepted.

   BMP Input Plugin
       img2dcm	supports  BMP  as  input format. However, so far only the most
       common BMP images are supported.	In particular, BMP  images  which  use
       bit  fields  or	run  length encoding will be rejected. Such images are
       uncommon. Input images will either be converted into a DICOM image with
       RGB color model	and  a	bit  depth  of	24,  or	 into  an  image  with
       MONOCHROME2  color  model  an  8	 bits per pixel. 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,  export  plugins  for	 the Secondary Capture Image SOP Class
       (default, option	-sc), the  Multi-frame	Secondary  Capture  Image  SOP
       Classes	(option	 -nsc),	 Visible  Light	 Photographic  Image SOP Class
       (option -vl), and the Ophthalmic	Photography Image SOP Classes  (option
       -oph)  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
       specify which specific SOP Class	should be used	for  output.  That  is
       because	these  new  SOP	 classes are differentiated from each other by
       color depth (1/8/16) and	the fact whether the image is  black/white  or
       color.  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  information  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.

       8.  img2dcm image1.jpg image2.jpg out.dcm --new-sc
	    Read the JPEG files	'image1.jpg' and 'image2.jpg',	convert	 to  a
	   multiframe  image  of the appropriate Multi-frame Secondary Capture
	   SOP Class, and save the result to DICOM file	'out.dcm'.

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
       behavior	 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  one	 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  behavior  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
       <datadir>/OP_template.xml  -  Sample  XML   template   for   Ophthalmic
       Photography images

SEE ALSO
       dcm2pnm(1),    dcmj2pnm(1),   dump2dcm(1),   dcmconv(1),	  dcmodify(1),
       dcm2xml(1)

COPYRIGHT
       Copyright (C) 2007-2024 by OFFIS	e.V., Escherweg	 2,  26121  Oldenburg,
       Germany.

Version	3.6.9			Wed Dec	11 2024			    img2dcm(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=img2dcm&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help