NAME

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

SYNOPSIS

dcxxxx
 
See the file ../dicom3tools/gen.so.
 
 
See the file ../dicom3tools/optin.so.
 
 
See the file ../dicom3tools/optout.so.
 

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.