Class AttributeList

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.util.Map<AttributeTag,​Attribute>, java.util.NavigableMap<AttributeTag,​Attribute>, java.util.SortedMap<AttributeTag,​Attribute>

    public class AttributeList
    extends java.util.TreeMap<AttributeTag,​Attribute>

    The AttributeList class maintains a list of individual DICOM attributes.

    Instances of the class may be used for entire composite storage SOP instances, or fragments of such instances such as meta information headers, or simply as lists of attributes to be passed to other methods (e.g. lists of attributes to add or remove from another list).

    The class is actually implemented by extending java.util.TreeMap as a map of AttributeTag keys to Attribute values. Consequently, all the methods of the underlying collection are available, including adding key-value pairs and extracting values by key. Iteration through the list of key-value pairs in the map is also supported, and the iterator returns values in the ascending numerical order of the AttributeTag keys, since that is how AttributeTag implements Comparable.

    Note that large attribute values such as Pixel Data may be left on disk rather than actually read in when the list is created, and loaded on demand; extreme caution should be taken if the underlying file from which an AttributeList has been read is moved or renamed; a specific method, setFileUsedByOnDiskAttributes(), is provided to address this concern.

    By default, compressed pixel data is decompressed during reading; this behavior can be controlled by calling setDecompressPixelData() before reading.

    The class provides methods for reading entire objects as a list of attributes, from files or streams. For example, the following fragment will read an entire object from the specified file and dump the contents of the attribute list:

            AttributeList list = new AttributeList();
            list.read(arg[0]);
            System.err.print(list);
     

    Similarly, methods are provided for writing entire objects. For example, the previous fragment could be extended to write the list to a file unchanged as follows:

            list.write(arg[1],TransferSyntax.ExplicitVRLittleEndian,true,true);
     

    Note that in general, one would want to perform significantly more cleaning up before writing an object that has just been read, and a number of such methods are provided either in this class or on related classes as illustrated in this example:

            AttributeList list = new AttributeList();
            list.read(arg[0]);
            //list.removePrivateAttributes();
            list.removeGroupLengthAttributes();
            list.removeMetaInformationHeaderAttributes();
            list.remove(TagFromName.DataSetTrailingPadding);
            list.correctDecompressedImagePixelModule();
            list.insertLossyImageCompressionHistoryIfDecompressed();
      CodingSchemeIdentification.replaceCodingSchemeIdentificationSequenceWithCodingSchemesUsedInAttributeList(list);
            list.insertSuitableSpecificCharacterSetForAllStringValues();
            FileMetaInformation.addFileMetaInformation(list,TransferSyntax.ExplicitVRLittleEndian,"OURAETITLE");
            list.write(arg[1],TransferSyntax.ExplicitVRLittleEndian,true,true);
     

    Note that this example is essentially the functionality of the main() method of this class, which may be used as a copying utility when invoked with input and output file arguments.

    Correction of the PhotometricInterpretation and related attributes by an explicit call to the correctDecompressedImagePixelModule() method is necessary if the color space of a compressed input transfer syntax was changed during decompression (e.g., from YBR_FULL_422 for JPEG lossy to RGB), since the PixelData is always decompressed during reading by the read() method and its ilk; the call does nothing (is harmless) if the input was not compressed or not multi-component.

    Individual attributes can be added or deleted as desired, either using a newly created list or one which has been read in from an existing object. For example, to zero out the patient's name one might do something like the following:

            list.replaceWithZeroLengthIfPresent(TagFromName.PatientName);
     

    or to replace it with a particular value one might do the following:

            Attribute a = new PersonNameAttribute(TagFromName.PatientName);
            a.addValue(value);
            list.put(TagFromName.PatientName,a);            // one could list.remove(TagFromName.PatientName) first, but this is implicit in the put
     

    A more compact shorthand method for adding new (or replacing existing) attributes (if they are in the dictionary so that the VR can be determined) is also supplied:

            list.putNewAttribute(TagFromName.PatientName);
     

    and if a specific character set other than the default is in use:

            list.putNewAttribute(TagFromName.PatientName,specificCharacterSet);
     

    and since this method returns the generated attribute, values can easily be added as:

            list.putNewAttribute(TagFromName.PatientName,specificCharacterSet).addValue("Blo^Joe");
     

    Note also that the Attribute class provides some useful static methods for extracting and manipulating individual attributes within a list. For example:

            String patientName=Attribute.getSingleStringValueOrNull(list,TagFromName.PatientName);
     

    Ideally one should take care when adding or manipulating lists of attributes to handle the specific character set correctly and consistently when there is a possibility that it may be other than the default. The previous example of replacing the patient's name could be more properly rewritten as:

            SpecificCharacterSet specificCharacterSet = new SpecificCharacterSet(Attribute.getStringValues(list,TagFromName.SpecificCharacterSet));
            Attribute a = new PersonNameAttribute(TagFromName.PatientName,specificCharacterSet);
            a.addValue(value);
            list.put(TagFromName.PatientName,a);
     

    Note that in this example if the SpecificCharacterSet attribute were not found or was present but empty the various intervening methods would return null and the SpecificCharacterSet() constructor would use the default (ascii) character set.

    When an attribute list is read in, the SpecificCharacterSet attribute is automatically detected and set and applied to all string attributes as they are read in and converted to the internal string form which is used by Java (Unicode).

    The same applies when they are written, with some limitations on which character sets are supported. However, if new attributes have been added to the list with a different SpecificCharacterSet, it is necessary to call insertSuitableSpecificCharacterSetForAllStringValues() before writing, which will check all string values of all attributes affected by SpecificCharacterSet, choose a suitable new SpecificCharacterSet, and insert or replace the existing SpecificCharacterSet attribute. By the time that the list is written out, all of the Attributes must have the same SpecificCharacterSet.

    See Also:
    Attribute, AttributeTag, FileMetaInformation, SpecificCharacterSet, TagFromName, TransferSyntax, Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  AttributeList.ReadTerminationStrategy
      An interface to supply the criteria for prematurely terminating the reading of a DICOM file.
      • Nested classes/interfaces inherited from class java.util.AbstractMap

        java.util.AbstractMap.SimpleEntry<K extends java.lang.Object,​V extends java.lang.Object>, java.util.AbstractMap.SimpleImmutableEntry<K extends java.lang.Object,​V extends java.lang.Object>
    • Constructor Summary

      Constructors 
      Constructor Description
      AttributeList()  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String buildInstanceTitleFromAttributeList()
      Construct a text title to describe this list.
      static java.lang.String buildInstanceTitleFromAttributeList​(AttributeList list)
      Construct a text title to describe the specified list.
      protected void checkSanityOfValueLength​(long vl, byte[] vr, AttributeTag tag, boolean encounteredIncorrectImplicitVRElementEncodinginExplicitVR)
      Check that the value length is reasonable under the circumstances.
      static void clearByteOffset​(AttributeList list)
      Clear the byte offset value of any SequenceItems.
      void correctDecompressedImagePixelModule()
      Correct the PhotometricInterpretation and Planar Configuration iff pixel data in a compressed input transfer syntax was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.
      void correctDecompressedImagePixelModule​(boolean deferredDecompression)
      Correct the PhotometricInterpretation and Planar Configuration iff pixel data in a compressed input transfer syntax was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.
      boolean equals​(java.lang.Object o)  
      java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs()
      Find all referenced SOP Instance UIDs that are nested within Sequences in this list.
      static java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs​(AttributeList list)
      Find all referenced SOP Instance UIDs that are nested within Sequences in the specified list.
      static java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs​(AttributeList list, java.util.Set<java.lang.String> setOfReferencedSOPInstanceUIDs)
      Find all referenced SOP Instance UIDs that are nested within Sequences in the specified list and add them to the supplied set.
      java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs​(java.util.Set<java.lang.String> setOfReferencedSOPInstanceUIDs)
      Find all referenced SOP Instance UIDs that are nested within Sequences in this list and add them to the supplied set.
      Attribute get​(AttributeTag t)
      Returns the value (attribute) to which this map maps the specified key (tag).
      Attribute get​(AttributeTag t, java.lang.String creator)
      Returns the private data element specified by the tag and creator.
      java.lang.String getDecompressedPhotometricInterpretation()
      Get the corrected PhotometricInterpretation iff the color space was a compressed input transfer syntax that was or would be decompressed during reading.
      java.lang.String getDecompressedPhotometricInterpretation​(java.lang.String vPhotometricInterpretation)
      Get the corrected PhotometricInterpretation iff the color space was a compressed input transfer syntax that was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.
      java.lang.String getDelimitedStringValuesOrDefault​(java.lang.String dflt, java.text.NumberFormat format, java.lang.String delimiter)
      Get all the string values for the attribute list, separated by the specified delimiter.
      static DicomDictionary getDictionary()
      Get the dictionary in use for this list.
      javax.imageio.metadata.IIOMetadata getIIOMetadata​(int frame)
      Returns a reference to the IIOMetadata object for the selected frame, or null if none was available during reading.
      Attribute getPixelData()
      Returns the Attribute that contains the Pixel Data.
      java.lang.String getPrivateCreatorString​(AttributeTag tag)
      Get the private creator of a private tag.
      AttributeTag getPrivateCreatorTag​(AttributeTag tag)
      Get the private creator of a private tag.
      SpecificCharacterSet getSuitableSpecificCharacterSetForAllStringValues()
      Get a new SpecificCharacterSet suitable for encoding all of the values of the string attributes of a dataset.
      int hashCode()  
      void insertLossyImageCompressionHistoryIfDecompressed()
      Update the lossy image compression history attributes if a lossy compressed input transfer syntax was decompress during reading.
      void insertLossyImageCompressionHistoryIfDecompressed​(boolean deferredDecompression)
      Update the lossy image compression history attributes if a lossy compressed input transfer syntax that was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.
      void insertSuitableSpecificCharacterSetForAllStringValues()
      Insert a new SpecificCharacterSet suitable for encoding all of the values of the string attributes of a dataset into the AttributeList.
      boolean isEnhanced()
      Determine whether or not this list is an enhanced instance.
      boolean isImage()
      Determine whether or not this list is an image.
      boolean isSRDocument()
      Determine whether or not this list is an SR Document.
      static void main​(java.lang.String[] arg)
      Read the DICOM input file as a list of attributes and write it to the specified output file or dump it.
      static AttributeList makeAttributeListFromKeywordAndValuePairs​(java.lang.String[] arg, int offset, int length)
      Make a new AttributeList from String keyword and value pairs.
      Attribute put​(Attribute a)
      Associates the specified value (attribute) with the key that is the existing tag of the attribute.
      Attribute put​(AttributeTag t, Attribute a)
      Associates the specified value (attribute) with the specified key (tag).
      Attribute putNewAttribute​(AttributeTag t)
      Create a new attribute with the specified tag and insert it in the map associating the generated attribute with the specified tag as the key.
      Attribute putNewAttribute​(AttributeTag t, SpecificCharacterSet specificCharacterSet)
      Create a new attribute with the specified tag and insert it in the map associating the generated attribute with the specified tag as the key.
      long read​(DicomInputStream i)
      Read all the DICOM attributes in the stream until there are no more.
      long read​(DicomInputStream i, AttributeList.ReadTerminationStrategy strategy)
      Read all the DICOM attributes in the stream until the specified tag is encountered.
      long read​(DicomInputStream i, AttributeTag stopAtTag)
      Read all the DICOM attributes in the stream until the specified tag is encountered.
      long read​(DicomInputStream i, AttributeTag stopAtTag, AttributeList.ReadTerminationStrategy strategy)
      Read all the DICOM attributes in the stream until the specified tag is encountered.
      long read​(java.io.File file)
      Read an entire DICOM object in the specified file.
      long read​(java.io.File file, AttributeList.ReadTerminationStrategy strategy)
      Read an entire DICOM object in the specified file.
      long read​(java.io.File file, AttributeTag stopAtTag)
      Read an entire DICOM object in the specified file.
      long read​(java.lang.String name)
      Read an entire DICOM object in the specified file.
      long read​(java.lang.String name, AttributeList.ReadTerminationStrategy strategy)
      Read an entire DICOM object in the specified file.
      long read​(java.lang.String name, AttributeTag stopAtTag)
      Read an entire DICOM object in the specified file.
      long read​(java.lang.String name, java.lang.String transferSyntaxUID, boolean hasMeta, boolean useBufferedStream)
      Read an entire DICOM object in the specified file.
      long read​(java.lang.String name, java.lang.String transferSyntaxUID, boolean hasMeta, boolean useBufferedStream, AttributeList.ReadTerminationStrategy strategy)
      Read an entire DICOM object in the specified file.
      long read​(java.lang.String name, java.lang.String transferSyntaxUID, boolean hasMeta, boolean useBufferedStream, AttributeTag stopAtTag)
      Read an entire DICOM object in the specified file.
      long readOnlyMetaInformationHeader​(DicomInputStream i)
      Read the meta information header (if present) and then stop.
      long readOnlyMetaInformationHeader​(java.io.File file)
      Read the meta information header (if present) for the specified file and then close it.
      long readOnlyMetaInformationHeader​(java.lang.String name)
      Read the meta information header (if present) for the specified file and then close it.
      Attribute remove​(AttributeTag tag)
      Removes the mapping for this key (tag), if present.
      void removeCommandGroupAttributes()
      Remove any command group data elements present in the list.
      void removeCurveAttributes()
      Remove any curve attributes present in the list.
      void removeGroup​(int group)
      Removes all of the data elements in the specified standard or private group.
      void removeGroupLengthAttributes()
      Remove any group length attributes present in the list, except the meta information header length, as well as LengthToEnd.
      void removeMetaInformationHeaderAttributes()
      Remove any meta information header attributes present in the list.
      void removeOverlayAttributes()
      Remove any overlay attributes present in the list.
      void removePrivateAttributes()
      Remove any private attributes present in the list.
      void removeRecursively​(AttributeTag tag)
      Removes the mapping for this key (tag), if present, in this and any contained lists.
      void removeUnsafePrivateAttributes()
      Remove unsafe private attributes present in the list.
      void replace​(AttributeTag tag, java.lang.String value)
      Replaces an attribute with a new value, if present in the list, otherwise adds it.
      void replaceWithDummyValueIfPresent​(AttributeTag tag, java.lang.String dummyValue)
      Replaces an attribute with a dummy value, if present in the list.
      void replaceWithValueIfPresent​(AttributeTag tag, java.lang.String value)
      Replaces an attribute with a new value, if present in the list.
      void replaceWithZeroLengthIfPresent​(AttributeTag tag)
      Replaces an attribute with a zero length attribute, if present in the list.
      void setDecompressPixelData​(boolean decompressPixelData)
      Change the pixel data decompression behavior if encapsulated pixel data is encountered.
      void setFileUsedByOnDiskAttributes​(java.io.File file)
      Change the file containing the data used by any attribute whose values are left on disk, for example if the file has been renamed.
      void setSpecificCharacterSet​(SpecificCharacterSet specificCharacterSet)
      Set the SpecificCharacterSet suitable for all of the string attributes of a dataset in an AttributeList.
      java.lang.String toString()
      Dump the contents of the attribute list as a human-readable string.
      java.lang.String toString​(DicomDictionary dictionary)
      Dump the contents of the attribute list as a human-readable string.
      void write​(DicomOutputStream dout)
      Write the entire attribute list to the specified stream.
      void write​(DicomOutputStream dout, boolean useMeta)
      Write the entire attribute list to the specified stream.
      void write​(java.io.File file)
      Write the entire attribute list to the specified file in explicit VR little endian transfer syntax with a meta information header.
      void write​(java.io.File file, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream)
      Write the entire attribute list to the specified file.
      void write​(java.io.File file, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream, byte[] preamble)
      Write the entire attribute list to the specified file.
      void write​(java.io.OutputStream o, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream)
      Write the entire attribute list to the specified stream.
      void write​(java.io.OutputStream o, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream, boolean closeAfterWrite)
      Write the entire attribute list to the specified stream.
      void write​(java.io.OutputStream o, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream, boolean closeAfterWrite, byte[] preamble)
      Write the entire attribute list to the specified stream.
      void write​(java.lang.String name)
      Write the entire attribute list to the named file in explicit VR little endian transfer syntax with a meta information header.
      void write​(java.lang.String name, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream)
      Write the entire attribute list to the named file.
      void write​(java.lang.String name, java.lang.String transferSyntaxUID, boolean useMeta, boolean useBufferedStream, byte[] preamble)
      Write the entire attribute list to the named file.
      protected void writeFragment​(DicomOutputStream dout)
      Write the entire attribute list (which may be part of a larger enclosing dataset) to the specified stream.
      • Methods inherited from class java.util.TreeMap

        ceilingEntry, ceilingKey, clear, clone, comparator, containsKey, containsValue, descendingKeySet, descendingMap, entrySet, firstEntry, firstKey, floorEntry, floorKey, forEach, get, headMap, headMap, higherEntry, higherKey, keySet, lastEntry, lastKey, lowerEntry, lowerKey, navigableKeySet, pollFirstEntry, pollLastEntry, putAll, remove, replace, replace, replaceAll, size, subMap, subMap, tailMap, tailMap, values
      • Methods inherited from class java.util.AbstractMap

        isEmpty
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, getOrDefault, isEmpty, merge, putIfAbsent, remove
    • Field Detail

      • maximumShortVRValueLength

        public static final long maximumShortVRValueLength
        See Also:
        Constant Field Values
      • maximumInMemoryNumberOfCompressedFrames

        public static final long maximumInMemoryNumberOfCompressedFrames
        See Also:
        Constant Field Values
      • decompressPixelData

        protected boolean decompressPixelData
      • pixelDataWasActuallyDecompressed

        protected boolean pixelDataWasActuallyDecompressed
      • pixelDataIsLossy

        protected boolean pixelDataIsLossy
      • lossyMethod

        protected java.lang.String lossyMethod
      • compressionRatio

        protected double compressionRatio
      • iioMetadata

        protected javax.imageio.metadata.IIOMetadata[] iioMetadata
      • colorSpaceWasConvertedToRGBDuringDecompression

        protected boolean colorSpaceWasConvertedToRGBDuringDecompression
    • Constructor Detail

      • AttributeList

        public AttributeList()
    • Method Detail

      • checkSanityOfValueLength

        protected void checkSanityOfValueLength​(long vl,
                                                byte[] vr,
                                                AttributeTag tag,
                                                boolean encounteredIncorrectImplicitVRElementEncodinginExplicitVR)
                                         throws DicomException

        Check that the value length is reasonable under the circumstances.

        Used to avoid trying to allocate insanely large attribute values when parsing corrupt or non-DICOM datasets.

        Protected so that this can be overridden in sub-classes if necessary for a particular application.

        Parameters:
        vl - the value length
        vr - the value representation
        tag - the tag
        encounteredIncorrectImplicitVRElementEncodinginExplicitVR - which increases the likelihood of an insane value
        Throws:
        DicomException - if the value length is not reasonable
      • setDecompressPixelData

        public void setDecompressPixelData​(boolean decompressPixelData)

        Change the pixel data decompression behavior if encapsulated pixel data is encountered.

        Encapsulated pixel data is any PixelData element with an undefined VL.

        Default for each newly constructed AttributeList is to decompress.

        If decompression is deferred, take care not to remove the Transfer Syntax from the AttributeList if classes perform decompression based on the list contents e.g., SourceImage created from AttributeList.

        Parameters:
        decompressPixelData - whether or not to decompress the pixel data
      • equals

        public boolean equals​(java.lang.Object o)
        Specified by:
        equals in interface java.util.Map<AttributeTag,​Attribute>
        Overrides:
        equals in class java.util.AbstractMap<AttributeTag,​Attribute>
      • readOnlyMetaInformationHeader

        public long readOnlyMetaInformationHeader​(DicomInputStream i)
                                           throws java.io.IOException,
                                                  DicomException

        Read the meta information header (if present) and then stop.

        Leaves the stream opened and positioned at the start of the data set.

        Parameters:
        i - the stream to read from
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(DicomInputStream i,
                         AttributeTag stopAtTag)
                  throws java.io.IOException,
                         DicomException

        Read all the DICOM attributes in the stream until the specified tag is encountered.

        Does not read beyond the group element pair of the specified stop tag.

        Leaves the stream open.

        Parameters:
        i - the stream to read from
        stopAtTag - the tag (in the top level data set) at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the stopAtTag, if stopped)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(DicomInputStream i,
                         AttributeTag stopAtTag,
                         AttributeList.ReadTerminationStrategy strategy)
                  throws java.io.IOException,
                         DicomException

        Read all the DICOM attributes in the stream until the specified tag is encountered.

        Does not read beyond the group element pair of the specified stop tag.

        Leaves the stream open.

        Parameters:
        i - the stream to read from
        stopAtTag - the tag (in the top level data set) at which to stop
        strategy - the ReadTerminationStrategy at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the stopAtTag or the tag read before the ReadTerminationStrategy terminated)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(DicomInputStream i,
                         AttributeList.ReadTerminationStrategy strategy)
                  throws java.io.IOException,
                         DicomException

        Read all the DICOM attributes in the stream until the specified tag is encountered.

        Does not read beyond the group element pair of the specified stop tag.

        Leaves the stream open.

        Parameters:
        i - the stream to read from
        strategy - the ReadTerminationStrategy at which to stop
        Returns:
        the byte offset at which the read stopped (which will be dependent on the ReadTerminationStrategy)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(DicomInputStream i)
                  throws java.io.IOException,
                         DicomException

        Read all the DICOM attributes in the stream until there are no more.

        Leaves the stream open.

        Parameters:
        i - the stream to read from
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.lang.String name,
                         java.lang.String transferSyntaxUID,
                         boolean hasMeta,
                         boolean useBufferedStream)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Parameters:
        name - the input file name
        transferSyntaxUID - the transfer syntax to use for the data set (leave null for autodetection)
        hasMeta - look for a meta information header
        useBufferedStream - buffer the input for better performance
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.lang.String name,
                         java.lang.String transferSyntaxUID,
                         boolean hasMeta,
                         boolean useBufferedStream,
                         AttributeList.ReadTerminationStrategy strategy)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Parameters:
        name - the input file name
        transferSyntaxUID - the transfer syntax to use for the data set (leave null for autodetection)
        hasMeta - look for a meta information header
        useBufferedStream - buffer the input for better performance
        strategy - the ReadTerminationStrategy at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the tag read before the ReadTerminationStrategy terminatedy)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.lang.String name,
                         java.lang.String transferSyntaxUID,
                         boolean hasMeta,
                         boolean useBufferedStream,
                         AttributeTag stopAtTag)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Parameters:
        name - the input file name
        transferSyntaxUID - the transfer syntax to use for the data set (leave null for autodetection)
        hasMeta - look for a meta information header
        useBufferedStream - buffer the input for better performance
        stopAtTag - the tag (in the top level data set) at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the stopAtTag, if stopped)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • readOnlyMetaInformationHeader

        public long readOnlyMetaInformationHeader​(java.lang.String name)
                                           throws java.io.IOException,
                                                  DicomException

        Read the meta information header (if present) for the specified file and then close it.

        Parameters:
        name - the input file name
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.lang.String name)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Always tries to automatically detect the meta information header or transfer syntax if no meta information header and buffers the input for better performance.

        Parameters:
        name - the input file name
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.lang.String name,
                         AttributeTag stopAtTag)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Always tries to automatically detect the meta information header or transfer syntax if no meta information header and buffers the input for better performance.

        Parameters:
        name - the input file name
        stopAtTag - the tag (in the top level data set) at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the stopAtTag, if stopped)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.lang.String name,
                         AttributeList.ReadTerminationStrategy strategy)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Always tries to automatically detect the meta information header or transfer syntax if no meta information header and buffers the input for better performance.

        Parameters:
        name - the input file name
        strategy - the ReadTerminationStrategy at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the tag read before the ReadTerminationStrategy terminated)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.io.File file)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Always tries to automatically detect the meta information header or transfer syntax if no meta information header and buffers the input for better performance.

        Parameters:
        file - the input file
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.io.File file,
                         AttributeTag stopAtTag)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Always tries to automatically detect the meta information header or transfer syntax if no meta information header and buffers the input for better performance.

        Parameters:
        file - the input file
        stopAtTag - the tag (in the top level data set) at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the stopAtTag, if stopped)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • read

        public long read​(java.io.File file,
                         AttributeList.ReadTerminationStrategy strategy)
                  throws java.io.IOException,
                         DicomException

        Read an entire DICOM object in the specified file.

        Reads the attributes of both the meta information header (if present) and data set.

        Always tries to automatically detect the meta information header or transfer syntax if no meta information header and buffers the input for better performance.

        Parameters:
        file - the input file
        strategy - the ReadTerminationStrategy at which to stop
        Returns:
        the byte offset at which the read stopped (which will be just past the tag read before the ReadTerminationStrategy terminated)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • readOnlyMetaInformationHeader

        public long readOnlyMetaInformationHeader​(java.io.File file)
                                           throws java.io.IOException,
                                                  DicomException

        Read the meta information header (if present) for the specified file and then close it.

        Parameters:
        file - the input file
        Returns:
        the byte offset at which the read stopped
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM parsing
      • writeFragment

        protected void writeFragment​(DicomOutputStream dout)
                              throws java.io.IOException,
                                     DicomException

        Write the entire attribute list (which may be part of a larger enclosing dataset) to the specified stream.

        Does not close the output stream, assumes any meta header vs. dataset ransition has occurred and further assumes that any additional codecs (like deflate) have already been pushed onto the stream.

        Intended for use only for write datasets that are within sequence items (hence is not public).

        Parameters:
        dout - the stream to write to
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(DicomOutputStream dout,
                          boolean useMeta)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified stream.

        Leaves the stream open.

        Parameters:
        dout - the stream to write to
        useMeta - true if the meta information header attributes are to be written, false if they are to be ommitted
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(DicomOutputStream dout)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified stream.

        Leaves the stream open.

        Parameters:
        dout - the stream to write to
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.io.OutputStream o,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified stream.

        Closes the stream after writing.

        Parameters:
        o - the stream to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance (set this true only if the supplied stream is not already buffered)
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.io.OutputStream o,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream,
                          boolean closeAfterWrite,
                          byte[] preamble)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified stream.

        Parameters:
        o - the stream to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance (set this true only if the supplied stream is not already buffered)
        closeAfterWrite - requests that the supplied stream be closed after writing
        preamble - 128 bytes to use as preamble, otherwise null to use default of all zero bytes
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.io.OutputStream o,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream,
                          boolean closeAfterWrite)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified stream.

        Parameters:
        o - the stream to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance (set this true only if the supplied stream is not already buffered)
        closeAfterWrite - requests that the supplied stream be closed after writing
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.lang.String name,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream,
                          byte[] preamble)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the named file.

        Parameters:
        name - the file name to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance
        preamble - 128 bytes to use as preamble, otherwise null to use default of all zero bytes
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.lang.String name,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the named file.

        Parameters:
        name - the file name to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.lang.String name)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the named file in explicit VR little endian transfer syntax with a meta information header.

        Parameters:
        name - the file name to write to
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding or inconsistent TransferSyntaxUID
      • write

        public void write​(java.io.File file,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream,
                          byte[] preamble)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified file.

        Parameters:
        file - the file to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance
        preamble - 128 bytes to use as preamble, otherwise null to use default of all zero bytes
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.io.File file,
                          java.lang.String transferSyntaxUID,
                          boolean useMeta,
                          boolean useBufferedStream)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified file.

        Parameters:
        file - the file to write to
        transferSyntaxUID - the transfer syntax to use to write the data set
        useMeta - write the meta information header attributes (if true they must be present in the list with appropriate values already)
        useBufferedStream - buffer the output for better performance
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding
      • write

        public void write​(java.io.File file)
                   throws java.io.IOException,
                          DicomException

        Write the entire attribute list to the specified file in explicit VR little endian transfer syntax with a meta information header.

        Parameters:
        file - the file to write to
        Throws:
        java.io.IOException - if an I/O error occurs
        DicomException - if an error in DICOM encoding or inconsistent TransferSyntaxUID
      • put

        public Attribute put​(AttributeTag t,
                             Attribute a)
                      throws java.lang.NullPointerException,
                             java.lang.ClassCastException

        Associates the specified value (attribute) with the specified key (tag).

        If the map previously contained a mapping for this key, the old value is replaced.

        No untyped Object put(Object key, Object value) method is required to over ride the super class method since the parent TreeMap class of AttributeList is now typed, and the untyped method would have the same erasure.

        Specified by:
        put in interface java.util.Map<AttributeTag,​Attribute>
        Overrides:
        put in class java.util.TreeMap<AttributeTag,​Attribute>
        Parameters:
        t - key (tag) with which the specified value (attribute) is to be associated
        a - value (attribute) to be associated with the specified key (tag)
        Returns:
        previous value (attribute) associated with specified key (tag), or null if there was no mapping for key (tag)
        Throws:
        java.lang.NullPointerException - thrown if a or t is null
        java.lang.ClassCastException - thrown if a or t is not the correct class
        See Also:
        TreeMap.put(Object,Object)
      • put

        public Attribute put​(Attribute a)

        Associates the specified value (attribute) with the key that is the existing tag of the attribute.

        If the map previously contained a mapping for this key, the old value is replaced.

        Parameters:
        a - value (attribute) to be associated with the specified key (tag)
        Returns:
        previous value (attribute) associated with specified key (tag), or null if there was no mapping for key (tag)
        Throws:
        java.lang.NullPointerException - thrown if a or t is null
        See Also:
        put(AttributeTag,Attribute)
      • get

        public Attribute get​(AttributeTag t)

        Returns the value (attribute) to which this map maps the specified key (tag).

        Returns null if the map contains no mapping for this key. A return value of null does indicate that the map contains no mapping for the key, unlike java.util.get(Object) since the put operation checks for and disallows null insertions. This contract will hold true unless one goes to great effort to insert a key that maps to a null value by using one of the other insertion methods of the super class, in which case other operations (like writing) may fail later with a NullPointerException.

        Parameters:
        t - key (tag) whose associated value (attribute) is to be returned
        Returns:
        the Attribute or null if not found
      • isImage

        public boolean isImage()

        Determine whether or not this list is an image.

        An image is defined to be something with a PixelData attribute at the top level.

        Returns:
        true if an image
      • isEnhanced

        public boolean isEnhanced()

        Determine whether or not this list is an enhanced instance.

        An enhanced instance is defined to be something with a Shared or Per-Frame Functional Groups Sequence attribute at the top level.

        Returns:
        true if an enhanced instance
      • isSRDocument

        public boolean isSRDocument()

        Determine whether or not this list is an SR Document.

        An SR Document is defined to be something with a ContentSequence attribute at the top level.

        Returns:
        true if an SR Document
        See Also:
        SOPClass.isStructuredReport(String)
      • remove

        public Attribute remove​(AttributeTag tag)

        Removes the mapping for this key (tag), if present.

        Parameters:
        tag - key (tag) for which mapping should be removed
        Returns:
        previous value (attribute) associated with specified key (tag), or null if there was no mapping for key (tag)
      • removeRecursively

        public void removeRecursively​(AttributeTag tag)

        Removes the mapping for this key (tag), if present, in this and any contained lists.

        I.e., recurses into sequences.

        Parameters:
        tag - key (tag) for which mapping should be removed
      • removeGroup

        public void removeGroup​(int group)

        Removes all of the data elements in the specified standard or private group.

        Parameters:
        group - group for which all elements should be removed
      • replaceWithZeroLengthIfPresent

        public void replaceWithZeroLengthIfPresent​(AttributeTag tag)
                                            throws DicomException

        Replaces an attribute with a zero length attribute, if present in the list.

        Does nothing if the attribute was not already present.

        Parameters:
        tag - key (tag) for which the attribute should be replaced
        Throws:
        DicomException - thrown if there is any difficulty creating the new zero length attribute
      • replace

        public void replace​(AttributeTag tag,
                            java.lang.String value)
                     throws DicomException

        Replaces an attribute with a new value, if present in the list, otherwise adds it.

        Parameters:
        tag - key (tag) for which the attribute should be replaced
        value - the value to use
        Throws:
        DicomException - thrown if there is any difficulty creating the new zero length attribute
      • replaceWithValueIfPresent

        public void replaceWithValueIfPresent​(AttributeTag tag,
                                              java.lang.String value)
                                       throws DicomException

        Replaces an attribute with a new value, if present in the list.

        Does nothing if the attribute was not already present.

        Parameters:
        tag - key (tag) for which the attribute should be replaced
        value - the value to use
        Throws:
        DicomException - thrown if there is any difficulty creating the new zero length attribute
      • replaceWithDummyValueIfPresent

        public void replaceWithDummyValueIfPresent​(AttributeTag tag,
                                                   java.lang.String dummyValue)
                                            throws DicomException

        Replaces an attribute with a dummy value, if present in the list.

        Does nothing if the attribute was not already present.

        Parameters:
        tag - key (tag) for which the attribute should be replaced
        dummyValue - the dummy value to use
        Throws:
        DicomException - thrown if there is any difficulty creating the new zero length attribute
      • removePrivateAttributes

        public void removePrivateAttributes()

        Remove any private attributes present in the list.

        Private attributes are all those with an odd group number.

        Also recurses into standard sequences and removes any private attributes therein.

      • removeUnsafePrivateAttributes

        public void removeUnsafePrivateAttributes()

        Remove unsafe private attributes present in the list.

        Unsafe private attributes are all those with an odd group number that are not known to be safe, in the sense that they do not contain individually identifiable information.

        Will not remove private creators of potentially safe private tags, even if there are no such safe tags found.

        Also recurses into standard sequences and removes any unsafe private attributes therein.

        See Also:
        ClinicalTrialsAttributes
      • getPrivateCreatorTag

        public AttributeTag getPrivateCreatorTag​(AttributeTag tag)

        Get the private creator of a private tag.

        Parameters:
        tag - the private tag
        Returns:
        the private creator tag
      • getPrivateCreatorString

        public java.lang.String getPrivateCreatorString​(AttributeTag tag)

        Get the private creator of a private tag.

        Any leading or trailing white space padding is removed

        Parameters:
        tag - the private tag
        Returns:
        the private creator, or an empty String if not found
      • get

        public Attribute get​(AttributeTag t,
                             java.lang.String creator)

        Returns the private data element specified by the tag and creator.

        Only the lower 8 bits of the specified tag are considered.

        Parameters:
        t - tag whose associated attribute is to be returned
        creator - private creator (owner of block of private data elements)
        Returns:
        the Attribute or null if not found
      • getPixelData

        public Attribute getPixelData()

        Returns the Attribute that contains the Pixel Data.

        Handles standard and various private float or double alternatives to the conventional (0x7FE0,0x0010).

        Returns:
        the Attribute or null if not found
      • removeCommandGroupAttributes

        public void removeCommandGroupAttributes()

        Remove any command group data elements present in the list.

        Command group data elements are all those in group 0x0000.

        For consistency, "attributes" rather than "data elements" is used in the method name, even though these aren't really attributes.

      • removeMetaInformationHeaderAttributes

        public void removeMetaInformationHeaderAttributes()

        Remove any meta information header attributes present in the list.

        Meta information header attributes are all those in group 0x0002.

        Also removes any command group 0x0000 data elements, which should never be present in DICOM Files, but are seen occasionally.

        Note that this should always be done when modifying the SOP Class or Instance UID of an attribute list what has been read before writing, since it is vital that the corresponding meta information header attributes match those in the data set.

        See Also:
        FileMetaInformation
      • removeGroupLengthAttributes

        public void removeGroupLengthAttributes()

        Remove any group length attributes present in the list, except the meta information header length, as well as LengthToEnd.

        Group length attributes are all those with an element of 0x0000.

        LengthToEnd (0x0008,0x0001) is always removed if present as well.

        These have never been required in DICOM and are a holdover from the old ACR-NEMA days, and are a source of constant problems, so should always be removed.

        The meta information header length is left alone, since it is mandatory.

        Also recurses into sequences and removes any contained group lengths.

        See Also:
        FileMetaInformation
      • removeOverlayAttributes

        public void removeOverlayAttributes()

        Remove any overlay attributes present in the list.

        Overlay attributes are those for which com.pixelmed.dicom.AttributeTag.isOverlayGroup() returns true.

        Note that any overlay data in the high bits of the PixelData are NOT removed by this method but can be removed by reading the PixelData into a com.pixelmed.display.SourceImage and creating a new PixelData attribute from it.

      • toString

        public java.lang.String toString()

        Dump the contents of the attribute list as a human-readable string.

        Each attribute is written to a separate line, in the form defined for com.pixelmed.dicom.Attribute.toString().

        Overrides:
        toString in class java.util.AbstractMap<AttributeTag,​Attribute>
        Returns:
        the string
      • getDelimitedStringValuesOrDefault

        public java.lang.String getDelimitedStringValuesOrDefault​(java.lang.String dflt,
                                                                  java.text.NumberFormat format,
                                                                  java.lang.String delimiter)

        Get all the string values for the attribute list, separated by the specified delimiter.

        If there is no string value for an individual value or an exception trying to fetch it, the supplied default is returned for each Attribute.

        A canonicalized (unpadded) form is returned for each Attribute value, not the original string.

        Parameters:
        dflt - what to return if there are no (valid) string values
        format - the format to use for each numerical or decimal value (null if none)
        delimiter - the delimiter to use between each value
        Returns:
        the values as a delimited String
      • setFileUsedByOnDiskAttributes

        public void setFileUsedByOnDiskAttributes​(java.io.File file)

        Change the file containing the data used by any attribute whose values are left on disk, for example if the file has been renamed.

        Parameters:
        file - the new file containing the data
      • putNewAttribute

        public Attribute putNewAttribute​(AttributeTag t,
                                         SpecificCharacterSet specificCharacterSet)
                                  throws DicomException

        Create a new attribute with the specified tag and insert it in the map associating the generated attribute with the specified tag as the key.

        If the map previously contained a mapping for the tag (key), the old value is replaced.

        The PixelRepresentation is assumed to be unsigned (US will be used for US/SS VR data elements).

        Parameters:
        t - key (AttributeTag tag) with which the generated attribute is to be associated
        specificCharacterSet - the SpecificCharacterSet to be used text values
        Returns:
        the newly created attribute
        Throws:
        DicomException - if cannot create attribute, such as if cannot find tag in dictionary
      • putNewAttribute

        public Attribute putNewAttribute​(AttributeTag t)
                                  throws DicomException

        Create a new attribute with the specified tag and insert it in the map associating the generated attribute with the specified tag as the key.

        If the map previously contained a mapping for the tag (key), the old value is replaced.

        The PixelRepresentation is assumed to be unsigned (US will be used for US/SS VR data elements).

        Parameters:
        t - key (AttributeTag tag) with which the generated attribute is to be associated
        Returns:
        the newly created attribute
        Throws:
        DicomException - if cannot create attribute, such as if cannot find tag in dictionary
      • setSpecificCharacterSet

        public void setSpecificCharacterSet​(SpecificCharacterSet specificCharacterSet)

        Set the SpecificCharacterSet suitable for all of the string attributes of a dataset in an AttributeList.

        Any existing SpecificCharacterSet for Attributes (whether read or created de novo) is replaced.

        Recurses into SequenceAttributes.

        Parameters:
        specificCharacterSet - the SpecificCharacterSet sufficient to encode all values
      • getSuitableSpecificCharacterSetForAllStringValues

        public SpecificCharacterSet getSuitableSpecificCharacterSetForAllStringValues()

        Get a new SpecificCharacterSet suitable for encoding all of the values of the string attributes of a dataset.

        Any existing SpecificCharacterSet within the AttributeList or any SpecificCharacterSet established for specific Attributes (e.g., when read or created de novo) is ignored.

        Only a single value is ever used (i.e., ISO 2022 escapes are not created).

        Returns:
        a new SpecificCharacterSet sufficient to encode all values
      • insertSuitableSpecificCharacterSetForAllStringValues

        public void insertSuitableSpecificCharacterSetForAllStringValues()
                                                                  throws DicomException

        Insert a new SpecificCharacterSet suitable for encoding all of the values of the string attributes of a dataset into the AttributeList.

        Any existing SpecificCharacterSet within the AttributeList or any SpecificCharacterSet established for specific Attributes (e.g., when read or created de novo) is ignored.

        Only a single value is ever used (i.e., ISO 2022 escapes are not created).

        If the encoding is ASCII, which is the default, the SpecificCharacterSet is removed (since it is Type 1C).

        Throws:
        DicomException - if cannot create attribute
      • clearByteOffset

        public static void clearByteOffset​(AttributeList list)

        Clear the byte offset value of any SequenceItems.

        Recurses into SequenceAttributes.

        Parameters:
        list -
      • getIIOMetadata

        public javax.imageio.metadata.IIOMetadata getIIOMetadata​(int frame)

        Returns a reference to the IIOMetadata object for the selected frame, or null if none was available during reading.

        Parameters:
        frame - the frame number, from 0
        Returns:
        an IIOMetadata object, or null.
      • insertLossyImageCompressionHistoryIfDecompressed

        public void insertLossyImageCompressionHistoryIfDecompressed​(boolean deferredDecompression)
                                                              throws DicomException

        Update the lossy image compression history attributes if a lossy compressed input transfer syntax that was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.

        E.g., from YBR_FULL_422 for JPEG lossy to RGB.

        Does nothing (is harmless) if the input was not compressed or not multi-component.

        Recurses into sequences in case there is icon pixel data that was also decompressed.

        Parameters:
        deferredDecompression - true if decompressing compressed frames later rather than during reading of AttributeList
        Throws:
        DicomException - if cannot create replacement attribute
      • insertLossyImageCompressionHistoryIfDecompressed

        public void insertLossyImageCompressionHistoryIfDecompressed()
                                                              throws DicomException

        Update the lossy image compression history attributes if a lossy compressed input transfer syntax was decompress during reading.

        E.g., from YBR_FULL_422 for JPEG lossy to RGB.

        Does nothing (is harmless) if the input was not compressed or not multi-component.

        Recurses into sequences in case there is icon pixel data that was also decompressed.

        Throws:
        DicomException - if cannot create replacement attribute
      • getDecompressedPhotometricInterpretation

        public java.lang.String getDecompressedPhotometricInterpretation()
                                                                  throws DicomException

        Get the corrected PhotometricInterpretation iff the color space was a compressed input transfer syntax that was or would be decompressed during reading.

        E.g., from YBR_FULL_422 for JPEG lossy to RGB.

        Returns:
        the corrected PhotometricInterpretation, or original PhotometricInterpretation if it does not need correction
        Throws:
        DicomException - if cannot create replacement attribute
      • getDecompressedPhotometricInterpretation

        public java.lang.String getDecompressedPhotometricInterpretation​(java.lang.String vPhotometricInterpretation)

        Get the corrected PhotometricInterpretation iff the color space was a compressed input transfer syntax that was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.

        E.g., from YBR_FULL_422 for JPEG lossy to RGB.

        Parameters:
        vPhotometricInterpretation - the PhotometricInterpretation supplied in the AttributeList
        Returns:
        the corrected PhotometricInterpretation, or original PhotometricInterpretation if it does not need correction
      • correctDecompressedImagePixelModule

        public void correctDecompressedImagePixelModule​(boolean deferredDecompression)
                                                 throws DicomException

        Correct the PhotometricInterpretation and Planar Configuration iff pixel data in a compressed input transfer syntax was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.

        If the color space was or will be converted, change the PhotometricInterpretation, e.g., from YBR_FULL_422 for JPEG lossy to RGB.

        If the pixel data was or will be decompressed, if JPEG (not RLE) change the PlanarConfiguration to 0 if not already (i.e., color-by-pixel not color-by-plane).

        Does nothing (is harmless) if the input was not (or will not be) decompressed or is not multi-component.

        Recurses into sequences in case there is icon pixel data that was also (or will be) decompressed.

        Parameters:
        deferredDecompression - true if decompressing compressed frames later rather than during reading of AttributeList
        Throws:
        DicomException - if cannot create replacement attribute
      • correctDecompressedImagePixelModule

        public void correctDecompressedImagePixelModule()
                                                 throws DicomException

        Correct the PhotometricInterpretation and Planar Configuration iff pixel data in a compressed input transfer syntax was actually decompressed during reading of AttributeList or will be if compressed frames are decompressed.

        If the color space was or will be converted, change the PhotometricInterpretation, e.g., from YBR_FULL_422 for JPEG lossy to RGB.

        If the pixel data was or will be decompressed, if JPEG (not RLE) change the PlanarConfiguration to 0 if not already (i.e., color-by-pixel not color-by-plane).

        Does nothing (is harmless) if the input was not compressed or not multi-component.

        Recurses into sequences in case there is icon pixel data that was also decompressed.

        Throws:
        DicomException - if cannot create replacement attribute
      • buildInstanceTitleFromAttributeList

        public java.lang.String buildInstanceTitleFromAttributeList()

        Construct a text title to describe this list.

        Returns:
        a single line constructed from patient, study, series and instance attribute values
      • buildInstanceTitleFromAttributeList

        public static java.lang.String buildInstanceTitleFromAttributeList​(AttributeList list)

        Construct a text title to describe the specified list.

        Parameters:
        list - the AttributeList
        Returns:
        a single line constructed from patient, study, series and instance attribute values (or empty string if list is null)
      • findAllNestedReferencedSOPInstanceUIDs

        public static java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs​(AttributeList list,
                                                                                             java.util.Set<java.lang.String> setOfReferencedSOPInstanceUIDs)

        Find all referenced SOP Instance UIDs that are nested within Sequences in the specified list and add them to the supplied set.

        Parameters:
        list - the AttributeList
        setOfReferencedSOPInstanceUIDs - may be empty or null
        Returns:
        the supplied set or a new set if null, with all referenced SOP Instance UIDs found added
      • findAllNestedReferencedSOPInstanceUIDs

        public static java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs​(AttributeList list)

        Find all referenced SOP Instance UIDs that are nested within Sequences in the specified list.

        Parameters:
        list - the AttributeList
        Returns:
        a set of all referenced SOP Instance UIDs
      • findAllNestedReferencedSOPInstanceUIDs

        public java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs​(java.util.Set<java.lang.String> setOfReferencedSOPInstanceUIDs)

        Find all referenced SOP Instance UIDs that are nested within Sequences in this list and add them to the supplied set.

        Parameters:
        setOfReferencedSOPInstanceUIDs - may be empty or null
        Returns:
        the supplied set or a new set if null, with all referenced SOP Instance UIDs found added
      • findAllNestedReferencedSOPInstanceUIDs

        public java.util.Set<java.lang.String> findAllNestedReferencedSOPInstanceUIDs()

        Find all referenced SOP Instance UIDs that are nested within Sequences in this list.

        Returns:
        a set of all referenced SOP Instance UIDs
      • makeAttributeListFromKeywordAndValuePairs

        public static AttributeList makeAttributeListFromKeywordAndValuePairs​(java.lang.String[] arg,
                                                                              int offset,
                                                                              int length)
                                                                       throws DicomException

        Make a new AttributeList from String keyword and value pairs.

        Parameters:
        arg - an array of String keyword and value pairs
        offset - the offset into the array to start
        length - the number of array entries (not pairs) to use
        Returns:
        a new AttributeList
        Throws:
        DicomException - if unable to make an Attribute
      • main

        public static void main​(java.lang.String[] arg)

        Read the DICOM input file as a list of attributes and write it to the specified output file or dump it.

        When copying, removes any group lengths and creates a new meta information header.

        Parameters:
        arg - array of one string (the filename to read and dump), two strings (the filename to read and the filename to write), three strings (the filename to read, the transfer syntax to write, the filename to write), or four strings (the transfer syntax to read (must be zero length if metaheader present), the filename to read, the transfer syntax to write, the filename to write) five strings (the transfer syntax to read (must be zero length if metaheader present), the filename to read, the transfer syntax to write, the filename to write, and whether or not to write a metaheader)