Package gov.nih.mipav.model.file

Class FileDicomTag

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<FileDicomTag>
    public class FileDicomTag
extends ModelSerialCloneable
implements java.lang.Comparable<FileDicomTag>
    This class holds all the important information about each DICOM tag. As the parser reads the DICOM dictionary file, it stores new DicomTags in a standard Hashtable. Then when the DICOM file reader reads a new file, it sets the value attribute of the DicomTag. The other constructor is used for private tags, because private tags do not have unique attributes. Thus, the reader can read and display all the tags in a file, but may not read the data properly and does not know the significance of the data. If the user wishes to know more information about the file that is encoded in the private tags, then he or she needs to edit the DICOM dictionary file to include the necessary private tags.
    Author:
    Neva Cherniavsky, David Parsons
    See Also:
    FileInfoDicom, FileDicom, Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private int element
      Integer element word (in hexadecimal).
      private int group
      Integer group word (in hexadecimal).
      private int length
      Length of the tag as defined in the input image.
      private static long serialVersionUID
      Use serialVersionUID for interoperability.
      private FileDicomTagInfo tagInfo
      Pointer to more information about this tag, read in and contained within the dicom dictionary.
      private java.lang.Object value
      Actual value of the tag (may be an array of elements).
      private FileDicomTagInfo.VR valueRepresentation
      Value representation for this tag, if the tags in this dicom file have explicit VRs.

    • Constructor Summary

      Constructors 
      Constructor Description
      FileDicomTag​(FileDicomTagInfo info)
      Constructor that creates a DicomTag empty except for the group and element fields.
      FileDicomTag​(FileDicomTagInfo info, java.lang.Object value)
      Constructor that creates a DicomTag empty except for the name field. this is used for private tags and the name field is the supposed value of the tag.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int compareTo​(FileDicomTag toCompare)  
      boolean equals​(java.lang.Object obj)
      Tests whether a tag contains the same information as this tag.
      void finalize()
      Prepares this class for cleanup.
      private java.lang.String fromAStoVisibleString()
      From age string to something that makes more sense. ages are DICOM as nnnT.
      private java.lang.String fromDAtoVisibleString()
      parses the DICOM v3 format tag to make a mm/dd/yyyy formatted date.
      private java.lang.String fromPatientOrientationToVisibleString()
      DOCUMENT ME!
      private java.lang.String fromPatientSexToVisibleString()
      Converts a DICOM patient sex tag (eg, "M") into a more understandable value (eg, "Male").
      private java.lang.String fromTMtoVisibleString()
      Takes a DICOM tag with a TM value representation and returns it in the format HH:MM:SS.frac, or as much as is available to convert (ie, HH:MM could be all that is currently stored).
      private java.lang.String fromVisibleStringToAS​(java.lang.String tempValue)
      Converts the given readable string to a DICOM compliant age string.
      private java.lang.String fromVisibleStringToDA​(java.lang.String tempValue)
      Converts the given string into a DICOM-legal value for a DA value-representation (VR) tag. places a date (yyyymmdd) into value that is in either yyyymmdd (DICOM v3) or yyyy.mm.dd (
      private java.lang.String fromVisibleStringToDS​(java.lang.String tempValue)
      Takes the input string and forms a DICOM compliant decimal string out of it.
      private java.lang.String fromVisibleStringToDT​(java.lang.String tempValue)
      setVisibleStringToDT.
      private java.lang.String fromVisibleStringToPatientOrientation​(java.lang.String tmpValue)
      DOCUMENT ME!
      private java.lang.String fromVisibleStringToPatientSex​(java.lang.String tempValue)
      Converts patient sex (eg, "Male") into a valid DICOM value (eg, "M").
      private java.lang.String fromVisibleStringToPN​(java.lang.String tmpValue)
      Converts a DICOM person's name ("PN") tag into a more understandable value.
      private java.lang.String fromVisibleStringToTM​(java.lang.String tempValue)
      setVisibleStringToTM.
      int getDataLength()
      Calculates the number of bytes that the data (the object value) will take to be stored.
      int getElement()
      Accessor that returns the element word of the tag (hex).
      int getGroup()
      Accessor that returns the group word of the tag (hex).
      FileDicomTagInfo getInfo()
      Return a reference to information about this tag in the dicom dictionary.
      FileDicomKey getKey()
      Return the key object (group,element info) for this tag.
      java.lang.String getKeyword()
      Return the keyword for this tag.
      int getLength()
      Returns the length of this tag.
      java.lang.String getName()
      Return the name of this tag.
      int getNumberOfValues()
      Provides the number of items held by the tag, as opposed the value specified by Value Multiplicity(VM).
      FileDicomTagInfo.VR getType()
      Return the type of this tag (determined from its value representation (vr)).
      java.lang.Object getValue​(boolean parse)
      Translates the tag value into an understandable string so no other class need understand how to parse this information.
      java.lang.Object[] getValueList()
      Returns the value(s) as an array so that each tag with a value multiplicity of more than 1 -- ie, TypeString items separated by '\' -- is its own element in the array.
      int getValueMultiplicity()
      Accessor that returns the value multiplicity of the tag.
      FileDicomTagInfo.VR getValueRepresentation()
      Return the value representation (vr) of this tag.
      int hashCode()
      Returns the unique identifier's hash code.
      void setElement​(int element)
      Sets the Element of this DICOM tag as read in by FileDicom.
      void setGroup​(int group)
      Sets the Group of this DICOM tag as read in by FileDicom.
      void setLength​(int length)
      Sets the length of this DICOM tag as read in by FileDicom.
      void setValue​(java.lang.Object value)
      Sets the value and length attributes of the DicomTag.
      private void setValue​(java.lang.Object value, int length)
      Sets the value attribute of the DicomTag.
      void setValueRepresentation​(FileDicomTagInfo.VR vr)
      Sets the value representation (vr) of this tag.
      int sizeof()
      Gets the data size in bytes of the units held in this class.
      static java.lang.Double[] toDouble​(byte[] b, int vm, boolean endianess)
      Converts a little-endian byte array into an array of Doubles with length equal to the tag vm.
      static java.lang.Float[] toFloat​(byte[] b, int vm, boolean endianess)
      Converts a little-endian byte array into an array of Floats with length equal to the tag vm.
      static java.lang.Integer[] toInt​(byte[] b, int vm, boolean endianess)
      Converts a little-endian byte array into an array of Integers with length equal to the tag vm.
      static java.lang.Integer[] toShort​(byte[] b, int vm, boolean endianess)
      Converts a little-endian byte array into an array of Integers with length equal to the tag vm.
      java.lang.String toString()
      Used for debugging so that the information contained in the tag can be converted to a readable form.
      static java.lang.Long[] toUInt​(byte[] b, int vm, boolean endianess)
      Converts a little-endian byte array into an array of Longs with length equal to the tag vm.
      static java.lang.Integer[] toUShort​(byte[] b, int vm, boolean endianess)
      Converts a little-endian byte array into an array of Integers with length equal to the tag vm.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        Use serialVersionUID for interoperability.
        See Also:
        Constant Field Values

      • element

        private int element
        Integer element word (in hexadecimal).

      • group

        private int group
        Integer group word (in hexadecimal).

      • length

        private int length
        Length of the tag as defined in the input image.

      • tagInfo

        private final FileDicomTagInfo tagInfo
        Pointer to more information about this tag, read in and contained within the dicom dictionary.

      • value

        private java.lang.Object value
        Actual value of the tag (may be an array of elements).

      • valueRepresentation

        private FileDicomTagInfo.VR valueRepresentation
        Value representation for this tag, if the tags in this dicom file have explicit VRs. If the dicom tags have implicit VRs, then the DicomDictionary VR is used.

    • Constructor Detail

      • FileDicomTag

        public FileDicomTag​(FileDicomTagInfo info)
        Constructor that creates a DicomTag empty except for the group and element fields.
        Parameters:
        info - information about this tag

      • FileDicomTag

        public FileDicomTag​(FileDicomTagInfo info,
                    java.lang.Object value)
        Constructor that creates a DicomTag empty except for the name field. this is used for private tags and the name field is the supposed value of the tag.
        Parameters:
        info - information about this tag
        value - the object to be stored

    • Method Detail

      • equals

        public boolean equals​(java.lang.Object obj)
        Tests whether a tag contains the same information as this tag.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - A object (hopefully a non-null FileDicomTag, but not required).
        Returns:
        Whether all of the tag data (group, element, tag info, value, length) in the other tag is the same as this one. False if the tag is null or not a FileDicomTag.

      • finalize

        public void finalize()
        Prepares this class for cleanup.
        Overrides:
        finalize in class java.lang.Object

      • getDataLength

        public final int getDataLength()
        Calculates the number of bytes that the data (the object value) will take to be stored. This method returns the number of data items times the sizeof the data type. This may be different from the previously stored length of the tag.
        Returns:
        size of the value in bytes

      • getElement

        public final int getElement()
        Accessor that returns the element word of the tag (hex).
        Returns:
        the element word

      • getGroup

        public final int getGroup()
        Accessor that returns the group word of the tag (hex).
        Returns:
        the group word

      • getInfo

        public final FileDicomTagInfo getInfo()
        Return a reference to information about this tag in the dicom dictionary.
        Returns:
        Information about this tag.

      • getKey

        public final FileDicomKey getKey()
        Return the key object (group,element info) for this tag.
        Returns:
        This tag's key.

      • getKeyword

        public final java.lang.String getKeyword()
        Return the keyword for this tag.
        Returns:
        The tag keyword.

      • getLength

        public final int getLength()
        Returns the length of this tag.
        Returns:
        the length

      • getName

        public final java.lang.String getName()
        Return the name of this tag.
        Returns:
        The tag name.

      • getNumberOfValues

        public int getNumberOfValues()
        Provides the number of items held by the tag, as opposed the value specified by Value Multiplicity(VM). While a VM may specify an unlimited number of values, this represents the number of values actually held. This is numerically equivalent to the value of getValueList().length. Formerly getMultiplicity().
        Returns:
        DOCUMENT ME!

      • getType

        public final FileDicomTagInfo.VR getType()
        Return the type of this tag (determined from its value representation (vr)).
        Returns:
        The tag type.

      • getValue

        public java.lang.Object getValue​(boolean parse)
        Translates the tag value into an understandable string so no other class need understand how to parse this information. However, values with more than one multiple (vm > 1) are still encoded with "\" (as in unprocessable DICOM tags) or " \ " as separators. A single value may then be de-coded using StringBuffer(str, "\"), and ...nextToken().

        Eg., The age is encoded as '014Y', so getValue() returns '14 Years'. Coded strings such as patient sex is 'F', which returns 'Female'

        An additional note: in order to write a DICOM image correctly, the value should NOT be parsed into readable form.

        Parameters:
        parse - boolean indicating if we should parse (translate) the value or just return the value as-is
        Returns:
        the value

      • getValueList

        public java.lang.Object[] getValueList()
        Returns the value(s) as an array so that each tag with a value multiplicity of more than 1 -- ie, TypeString items separated by '\' -- is its own element in the array. This method will be so much simpler when (if) the tags are seperated out as individual classes.
        Returns:
        DOCUMENT ME!

      • getValueMultiplicity

        public final int getValueMultiplicity()
        Accessor that returns the value multiplicity of the tag. The value multiplicity is how many instances of this value representation (VR) there can be in one tag.
        Returns:
        the value multiplicity

      • getValueRepresentation

        public final FileDicomTagInfo.VR getValueRepresentation()
        Return the value representation (vr) of this tag. If the tag VR for this dicom are implicit, then the VR is retrieved from the DicomDictionary.
        Returns:
        The tag vr.

      • hashCode

        public final int hashCode()
        Returns the unique identifier's hash code.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        The hash code.

      • setElement

        public final void setElement​(int element)
        Sets the Element of this DICOM tag as read in by FileDicom.
        Parameters:
        element - element to set to

      • setGroup

        public final void setGroup​(int group)
        Sets the Group of this DICOM tag as read in by FileDicom.
        Parameters:
        group - group to set to

      • setLength

        public final void setLength​(int length)
        Sets the length of this DICOM tag as read in by FileDicom.
        Parameters:
        length - length to set to

      • setValue

        public void setValue​(java.lang.Object value)
        Sets the value and length attributes of the DicomTag. Parses value so the stored value is converted from a standard, English-readable string to a DICOM v3 form. If the parsing routine is unavailable, the value gets stored as is. Sending strings to set the value of tags of other types (eg., short) will attempt to convert the string to the correct type. Attempting to store a value which is too large for the given type will throw an exception. In any case, the proper size is used.

        For tags with neither value representation nor keyword (a private tag), this method ignores the value. To add, the user class must use setValue(). typeSequence and typeUnknown must also explicitly use setValue().

        Parameters:
        value - the value to store

      • setValue

        private final void setValue​(java.lang.Object value,
                            int length)
        Sets the value attribute of the DicomTag. Does NOT parse so stored value is the same as the one read in. getValue does parse.

        NOTE: DICOM compliant codes will be accepted.

        Parameters:
        value - the value to store
        length - length of the tag

      • setValueRepresentation

        public final void setValueRepresentation​(FileDicomTagInfo.VR vr)
        Sets the value representation (vr) of this tag. This method should only be used when a dicom's tag VRs are explicit. Otherwise, the DicomDictionary VR should be used (implicit).
        Parameters:
        vr - The tag's explicit value representation.

      • sizeof

        public int sizeof()
        Gets the data size in bytes of the units held in this class.
        Returns:
        DOCUMENT ME!

      • toString

        public java.lang.String toString()
        Used for debugging so that the information contained in the tag can be converted to a readable form.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The tag in readable form

      • fromAStoVisibleString

        private java.lang.String fromAStoVisibleString()
        From age string to something that makes more sense. ages are DICOM as nnnT. That is, three digits preceeeding a letter indicating the time unit; valid units are D (day), M (month), and Y (year).

        This method translates the unit into the word, and drops leading zeros.

        Returns:
        DOCUMENT ME!

      • fromDAtoVisibleString

        private java.lang.String fromDAtoVisibleString()
        parses the DICOM v3 format tag to make a mm/dd/yyyy formatted date.
        Returns:
        DOCUMENT ME!

      • fromPatientOrientationToVisibleString

        private java.lang.String fromPatientOrientationToVisibleString()
        DOCUMENT ME!
        Returns:
        DOCUMENT ME!

      • fromPatientSexToVisibleString

        private java.lang.String fromPatientSexToVisibleString()
        Converts a DICOM patient sex tag (eg, "M") into a more understandable value (eg, "Male"). "M", "F", and "O" are valid inputs. Any other value representation (VR) is converted to "Other" but an empty string (which is valid, since the Patient Sex tag is Type 2, that is, required to exist, but no value is required) returns an empty string.
        Returns:
        DOCUMENT ME!

      • fromTMtoVisibleString

        private java.lang.String fromTMtoVisibleString()
        Takes a DICOM tag with a TM value representation and returns it in the format HH:MM:SS.frac, or as much as is available to convert (ie, HH:MM could be all that is currently stored).
        Returns:
        String HH:MM:SS.fraction

      • fromVisibleStringToAS

        private java.lang.String fromVisibleStringToAS​(java.lang.String tempValue)
        Converts the given readable string to a DICOM compliant age string. The following limitations apply: has to start with numbers, then follow-up with the word 'days', 'months', 'years' irrespective of capitalization; a number may be no larger than 3 digits, or only the top three digits are accepted.
        Parameters:
        tempValue - Original (readable) string value.
        Returns:
        Dicom string version of age.

      • fromVisibleStringToDA

        private java.lang.String fromVisibleStringToDA​(java.lang.String tempValue)
        Converts the given string into a DICOM-legal value for a DA value-representation (VR) tag. places a date (yyyymmdd) into value that is in either yyyymmdd (DICOM v3) or yyyy.mm.dd (
        Parameters:
        tempValue - -- the string that represents the date. In American std mm/dd/yyyy or DIOCM's yyyymmdd or yyyy.mm.dd
        Returns:
        String a date in yyyymmdd DICOM v3 format

        • fromVisibleStringToDS

          private java.lang.String fromVisibleStringToDS​(java.lang.String tempValue)
          Takes the input string and forms a DICOM compliant decimal string out of it. Allows multiple values (separated by the '\' character.)
          Parameters:
          tempValue - DOCUMENT ME!
          Returns:
          DOCUMENT ME!

        • fromVisibleStringToDT

          private java.lang.String fromVisibleStringToDT​(java.lang.String tempValue)
          setVisibleStringToDT.
          Parameters:
          tempValue - DOCUMENT ME!
          Returns:
          DOCUMENT ME!

        • fromVisibleStringToPatientOrientation

          private java.lang.String fromVisibleStringToPatientOrientation​(java.lang.String tmpValue)
          DOCUMENT ME!
          Parameters:
          tmpValue - DOCUMENT ME!
          Returns:
          DOCUMENT ME!

        • fromVisibleStringToPatientSex

          private java.lang.String fromVisibleStringToPatientSex​(java.lang.String tempValue)
          Converts patient sex (eg, "Male") into a valid DICOM value (eg, "M"). "Male", "M", "Female","F", "Other" and "O" are valid inputs. Any other input is converted to an empty string (which is valid, since the Patient Sex tag is Type 2, that is, required to exist, but no value is required) and returned.
          Parameters:
          tempValue - DOCUMENT ME!
          Returns:
          DOCUMENT ME!

        • fromVisibleStringToPN

          private java.lang.String fromVisibleStringToPN​(java.lang.String tmpValue)
          Converts a DICOM person's name ("PN") tag into a more understandable value. Used so the '^' word-separation character isn't mistakenly removed.
          Parameters:
          tmpValue - DOCUMENT ME!
          Returns:
          DOCUMENT ME!

        • fromVisibleStringToTM

          private java.lang.String fromVisibleStringToTM​(java.lang.String tempValue)
          setVisibleStringToTM.
          Parameters:
          tempValue - DOCUMENT ME!
          Returns:
          DOCUMENT ME!

        • toInt

          public static final java.lang.Integer[] toInt​(byte[] b,
                                              int vm,
                                              boolean endianess)
          Converts a little-endian byte array into an array of Integers with length equal to the tag vm.
          Parameters:
          b - The byte array.
          vm - The tag VM.
          endianess - True indicates big endian, false indicates little endian.
          Returns:
          An Integer array with length vm.

        • toUInt

          public static final java.lang.Long[] toUInt​(byte[] b,
                                            int vm,
                                            boolean endianess)
          Converts a little-endian byte array into an array of Longs with length equal to the tag vm.
          Parameters:
          b - The byte array.
          vm - The tag VM.
          endianess - True indicates big endian, false indicates little endian.
          Returns:
          A Long array with length vm.

        • toShort

          public static final java.lang.Integer[] toShort​(byte[] b,
                                                int vm,
                                                boolean endianess)
          Converts a little-endian byte array into an array of Integers with length equal to the tag vm.
          Parameters:
          b - The byte array.
          vm - The tag VM.
          endianess - True indicates big endian, false indicates little endian.
          Returns:
          An Integer array (storing short values) with length vm.

        • toUShort

          public static final java.lang.Integer[] toUShort​(byte[] b,
                                                 int vm,
                                                 boolean endianess)
          Converts a little-endian byte array into an array of Integers with length equal to the tag vm.
          Parameters:
          b - The byte array.
          vm - The tag VM.
          endianess - True indicates big endian, false indicates little endian.
          Returns:
          An Integer array (storing short values) with length vm.

        • toFloat

          public static final java.lang.Float[] toFloat​(byte[] b,
                                              int vm,
                                              boolean endianess)
          Converts a little-endian byte array into an array of Floats with length equal to the tag vm.
          Parameters:
          b - The byte array.
          vm - The tag VM.
          endianess - True indicates big endian, false indicates little endian.
          Returns:
          An Float array with length vm.

        • toDouble

          public static final java.lang.Double[] toDouble​(byte[] b,
                                                int vm,
                                                boolean endianess)
          Converts a little-endian byte array into an array of Doubles with length equal to the tag vm.
          Parameters:
          b - The byte array.
          vm - The tag VM.
          endianess - True indicates big endian, false indicates little endian.
          Returns:
          An Double array with length vm.

        • compareTo

          public int compareTo​(FileDicomTag toCompare)
          Specified by:
          compareTo in interface java.lang.Comparable<FileDicomTag>