Provided by: dicom3tools_1.00~20220618093127-2_amd64 bug

NAME

       dcintro - ACR/NEMA DICOM PS3 ... Introduction and options

SYNOPSIS

       dcxxxx

DESCRIPTION

       The  options  described  are  common to all tools and conversions as necessary when either
       DICOM input or output or both are supported.

       Though input may be redirected from standard input or  standard  output,  in  general  the
       ability  to  seek  is  required on input, and if this is not supported, as in input from a
       pipe, the operation will fail.

       Under normal circumstances, utilities that read  DICOM  or  older  ACR/NEMA  input  files,
       whether  a  meta-information  header  is  present  or not, should be able to automatically
       determine the appropriate Transfer Syntax.

       For utilities that write DICOM  output,   the  default  behaviour  is  to  write  a  meta-
       information  header and preamble, and hence produce files that are compliant with DICOM PS
       3.10. No other files can claim conformance to the standard, and even then compliance  with
       a  specific  Media Application Profile is still required. It may be useful to suppress the
       meta-header if it is required to construct datasets  contained  temporarily  within  files
       prior to exchange using the DICOM network protocol.

       For  utilities  that  write  DICOM  output,  various attributes may be manually deleted or
       replaced after the initial DICOM dataset is read or generated.  Various options  exist  to
       replace  such  attributes  before  or  after the image pixel data encoding is established,
       hence either incorrect attributes can be corrected, or the encoding can be changed.

OPTIONS

       Input options are:

       -if|-input-file|< name

       -input-nometa
              Input does not contain a meta-information header and preamble.   Needed  only  when
              the  automatic  determination  of  input  Transfer  Syntax  fails.  When specified,
              suppresses check for the presence of a meta-information header and will use  either
              the transfer syntax specified by -input-ts " uid" or the byte order and implicit or
              explicit  vr,  otherwise  these  are  automatically  determined  from  the  dataset
              (guessed).

       -input-nolengthtoend
              Ignore the length to end value, if present. Normally the reading stops after length
              to end bytes have been read and any trailing padding present is ignored.

       -ignoreoutofordertags
              Ignore tags that are incorrectly out of order and keep reading the dataset.  Useful
              for debugging invalid data sets, but may cause parser to get lost if problem is not
              really out of order tags. Also enables parsing past various other  encoding  issues
              that are not related to tag order.

       -usvrlutdata
              If the VR for the LUT Data attribute is not explicitly specified, then a US (rather
              than the default OW) VR will be used; can be used to convert one form to another by
              converting to implicit first and then using this option .

       -input-ts uid
              Use the input Transfer Syntax specified by the UID.  Needed only when the automatic
              determination of input Transfer Syntax fails.  Will be used  to  set  the  transfer
              syntax  for  the  meta-header  (if  present) rather than the dataset unless -input-
              nometa is also specified.

       -input-default
              Use the default Implicit VR Little Endian Transfer Syntax for input.   Needed  only
              when the automatic determination of input Transfer Syntax fails.

       -input-byteorder|-input-endian  big|little
              Select  an  uncompressed  input  Transfer Syntax that uses the specified byteorder.
              Requires that the input Value Representation also be specified.  Needed  only  when
              the automatic determination of input Transfer Syntax fails.

       -input-vr  implicit|explicit
              Select  an  uncompressed  input  Transfer  Syntax  that  uses  the  specified Value
              Representation. Requires that the input byteorder also be specified.   Needed  only
              when the automatic determination of input Transfer Syntax fails.

       Output options are:

       -of|-output-file|> name

       -n|-nometa|-output-nometa
              Don't write an output meta-information header and preamble.

       -justmeta|-output-justmeta
              Write only a meta-information header and preamble, and not the data set itself.

       -implicitmeta|-output-implicitmeta
              Use  the  obsolete pre-standard draft Implicit VR Little Endian Transfer Syntax for
              the meta-information header.

       -ts|-output-ts|-output-transfersyntax uid
              Use the output Transfer Syntax specified by the UID.

       -output-default
              Use the default Implicit VR Little Endian Transfer Syntax for output.  This is  the
              default mode anyway, and the option is redundant.

       -output-byteorder|-output-endian  big|little
              Select  an  uncompressed  output Transfer Syntax that uses the specified byteorder.
              Requires that the output Value Representation also be specified.

       -output-vr  implicit|explicit
              Select an uncompressed  output  Transfer  Syntax  that  uses  the  specified  Value
              Representation. Requires that the output byteorder also be specified.

       -s|-stamp uiddatetimestamp
              When  UIDs  are automatically generated, they incorporate the current date and time
              to ensure uniqueness. If two invocations of a utility  are  to  generate  the  same
              UIDs,  for  example for two images of a series to share a common SeriesInstanceUID,
              then the current date and time  may  be  replaced  in  the  generated  uid  by  the
              explicitly  specified  value.  This option is also useful for regression testing to
              ensure that the output  matches  that  of  a  previous  invocation,  without  being
              affected  by  the  current date and time. A typical value to use for a stamp shared
              between multiple images in the same study would be "`date '+%Y%m%d%H%M%S'`.$$".

       -addlengths
              Add group length attributes to every group.  Normally  the  group  length  is  only
              generated  for the meta-information header group, where it is mandatory. These have
              been retired by DICOM 3.0 but are often checked by applications, and are  sometimes
              required by older ACR/NEMA applications. Note that LengthToEnd is not added by this
              option unless -addlengthtoend is also specified.

       -addlengthtoend
              Add the LengthToEnd attribute. This has been retired by DICOM  3.0  but  are  often
              checked by applications, and are sometimes required by older ACR/NEMA applications.

       -tiff|-tif
              Add  a  TIFF  header in the DICOM Meta-information preamble, which points to a TIFF
              Image File Directory (IFD) at the end of the dataset in the  DataSetTrailingPadding
              Attribute  after the PixelData attribute. This allows the DICOM file to be a 'dual-
              personality' file, sharing the pixel data with two formats, and allowing both  TIFF
              and DICOM readers to handle the image.

       -removeprivate
              Remove any private attributes present, ie. all those in odd groups.

       -removeinstanceuid
              Remove  any  existing  SOPInstanceUID. This is generally a prelude to automatically
              generating a new one, which will happen unless -noadddicom is also specified.

       -noadddicom
              Suppress the automatic insertion of SOP Instance UIDs and SOP Class UIDs where they
              are  missing  and  can  be meaningfully guessed at given the presence and values of
              other attributes. For a composite image object instance, the StudyID,  SeriesNumber
              and ImageNumber will be used together with the date and time or explicit stamp (see
              -stamp) to generate StudyInstanceUID, SeriesInstanceUID  and  SOPInstanceUID.   The
              SOPClassUID  will  be  guessed  at  from  Modality  if  not ambiguous.  There is no
              guarantee that a complete IOD will be generated in this manner, it is just  a  best
              effort  when  required  attributes  are  missing, and has no effect on an exisiting
              complete IOD.

       -nodisclaimer
              Suppress insertion  of  the  'for  investigational  use  only'  disclaimer  in  the
              ImageComments attribute.

       -disambiguateseriesbydescription
              When  inserting  Series  Instance UIDs, use not just the Series Number but also the
              characters in the Series Description to (try to) build a value  that  disambiguates
              series with the same number but different descriptions.

       -d|-delete deletekeyword
              Delete  the  named  attribute after the data set has been cleaned of old metaheader
              attributes, UIDs (if requested) and private attributes (if requested),  but  before
              automatic DICOM attributes (if not suppressed), disclaimers (if not suppressed) and
              new metaheader (if not suppressed) attributes have been added.

       -r|-replace|-rb|-replace-before replacekeyword values
              Replace or add the named attribute after the data  set  has  been  cleaned  of  old
              metaheader  attributes,  UIDs (if requested) and private attributes (if requested),
              but BEFORE automatic DICOM attributes (if  not  suppressed),  disclaimers  (if  not
              suppressed)  and new metaheader attributes (if not suppressed) have been added, and
              the output encoding transformations have been  established.  Note  that  attributes
              related  to  image  pixel  encoding  changed at this point WILL affect actual image
              pixel data  transformations,  and  hence  may  be  specified  here  to  cause  such
              transformations, based on BitsAllocated, BitsStored and HighBit. Note that in order
              to replace a value with a string that starts with a leading hyphen ('-') that might
              otherwise  be  interpreted  as another option, enter the value in single quotes and
              preceded the hyphen with a space (which will later  be  elided),  eg.  "-r  Rescale
              Intercept ' -1024'".

       -ra|-replace-after replacekeyword values
              Replace  or  add  the  named  attribute  after  automatic  DICOM attributes (if not
              suppressed), disclaimers (if not suppressed) and new metaheader attributes (if  not
              suppressed)  have  been  added,  but  before group lengths (if requested) have been
              added. Note that attributes related to image pixel encoding changed at  this  point
              will  have  no  effect on actual image pixel data transformations, and hence may be
              specified here to correct such attributes.

       -version
              Print a version string to stderr, and exit if there are no other arguments.

ENVIRONMENT


EXAMPLES


FILES


SEE ALSO


AUTHOR

       Copyright (c) 1993-2022, David A. Clunie DBA PixelMed Publishing. All rights reserved.

BUGS

       Though redirection from a file on standard  input  should  work,  certain  libraries  give
       incorrect  results,  rather  than  actually  failing  with  a seek error ... this has been
       observed with libg++ 2.7.0 and is a bit worrying. The use of  standard  input  redirection
       has not been removed however, for use in those environments in which it does work.

       One  cannot  specify  a zero length string value for replacements on the command line. One
       can specify a string with a single space byte, which then gets removed as trailing  zeroes
       are removed, so one can make zero length type 2 attributes.