Provided by: dicom3tools_1.00~20220120135102-1_amd64 
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-2021, 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.