Class JSONRepresentationOfDicomObjectFactory


  • public class JSONRepresentationOfDicomObjectFactory
    extends java.lang.Object

    A class to encode a representation of a DICOM object in a JSON form, and to convert it back again.

    There are a number of characteristics of this form of output:

    Note that a round trip from DICOM to JSON and back again does not always result in full fidelity, since:

    • Binary floating point values will lose precision when converted to string representation and back again
    • Leading and trailing white space and control characters in strings will be discarded
    • Meta information header elements will be changed
    • Structural elements such as group lengths will be removed and may or may not be replaced
    • Physical offsets such as in the DICOMDIR will be invalidated
    • Large attributes with OB and OW value representations will have their values discarded so as not to encode the bulk pixel data (probably should be added as an option)

    A typical example of how to invoke this class to convert DICOM to JSON would be:

    try {
        AttributeList list = new AttributeList();
        list.read("dicomfile",null,true,true);
        JsonArray document = new JSONRepresentationOfDicomObjectFactory().getDocument(list);
        JSONRepresentationOfDicomObjectFactory.write(System.out,document);
    } catch (Exception e) {
        slf4jlogger.error("",e);
     }
     

    or even simpler, if there is no further use for the JSON document:

    try {
        AttributeList list = new AttributeList();
        list.read("dicomfile",null,true,true);
        JSONRepresentationOfDicomObjectFactory.createDocumentAndWriteIt(list,System.out);
    } catch (Exception e) {
        slf4jlogger.error("",e);
     }
     

    A typical example of converting JSON back to DICOM would be:

    try {
        AttributeList list = new JSONRepresentationOfDicomObjectFactory().getAttributeList("jsonfile");
        list.insertSuitableSpecificCharacterSetForAllStringValues();
        list.write(System.out,TransferSyntax.ExplicitVRLittleEndian,true,true);
    } catch (Exception e) {
        slf4jlogger.error("",e);
     }
     

    or if you need to handle the meta information properly:

    try {
        AttributeList list = new JSONRepresentationOfDicomObjectFactory().getAttributeList("jsonfile");
        list.insertSuitableSpecificCharacterSetForAllStringValues();
        String sourceApplicationEntityTitle = Attribute.getSingleStringValueOrEmptyString(list,TagFromName.SourceApplicationEntityTitle);
        list.removeMetaInformationHeaderAttributes();
        FileMetaInformation.addFileMetaInformation(list,TransferSyntax.ExplicitVRLittleEndian,sourceApplicationEntityTitle);
        list.write(System.out,TransferSyntax.ExplicitVRLittleEndian,true,true);
    } catch (Exception e) {
        slf4jlogger.error("",e);
     }
     

    When the JSON is being converted to DICOM, the group, element and VR attributes are not needed if the element name is a keyword that can be found in the dictionary; if they are present, then their values are checked against the dictionary values.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void addPersonNameAsComponentsToJsonObject​(javax.json.JsonObjectBuilder jsonPersonNameValue, java.lang.String value, java.lang.String alphabeticProperty, java.lang.String ideographicProperty, java.lang.String phoneticProperty)  
      static void createDocumentAndWriteIt​(AttributeList list, java.io.File outputFile)
      Serialize a JSON document created from a DICOM attribute list.
      static void createDocumentAndWriteIt​(AttributeList list, java.io.OutputStream out)
      Serialize a JSON document created from a DICOM attribute list.
      static void createDocumentAndWriteIt​(AttributeList list, java.lang.String outputPath)
      Serialize a JSON document created from a DICOM attribute list.
      AttributeList getAttributeList​(java.io.File file)
      Given a DICOM object encoded as a JSON document in a file convert it to a list of attributes.
      AttributeList getAttributeList​(java.io.InputStream stream)
      Given a DICOM object encoded as a JSON document in a stream convert it to a list of attributes.
      AttributeList getAttributeList​(java.lang.String name)
      Given a DICOM object encoded as a JSON document in a named file convert it to a list of attributes.
      AttributeList getAttributeList​(javax.json.JsonArray document)
      Given a DICOM object encoded as a JSON document convert it to a list of attributes.
      AttributeList getAttributeList​(javax.json.JsonArray document, boolean ignoreUnrecognizedTags, boolean ignoreSR)
      Given a DICOM object encoded as a JSON document convert it to a list of attributes.
      AttributeList getAttributeList​(javax.json.JsonObject topLevelObject, boolean ignoreUnrecognizedTags, boolean ignoreSR)
      Given a DICOM object encoded in a JSON document convert it to a list of attributes.
      protected static AttributeTag getAttributeTagFromHexadecimalGroupElementValues​(java.lang.String s)
      Parse an AttributeTag represented as an eight character hexadecimal representation as defined for the standard JSON or XML representation.
      javax.json.JsonArray getDocument​(AttributeList list)
      Given a DICOM object encoded as a list of attributes, get a JSON document.
      javax.json.JsonArray getDocument​(AttributeList list, boolean useKeywordInsteadOfTag, boolean addTag, boolean addKeyword, boolean addVR, boolean collapseValueArrays, boolean collapseEmptyToNull, boolean ignoreSR, boolean substituteUIDKeywords, boolean useNumberForIntegerOrDecimalString)
      Given a DICOM object encoded as a list of attributes, get a JSON document.
      javax.json.JsonArray getDocument​(java.io.File file)
      Given a DICOM object encoded as a list of attributes, get a JSON document.
      javax.json.JsonArray getDocument​(java.io.File file, boolean useKeywordInsteadOfTag, boolean addTag, boolean addKeyword, boolean addVR, boolean collapseValueArrays, boolean collapseEmptyToNull, boolean ignoreSR, boolean substituteUIDKeywords, boolean useNumberForIntegerOrDecimalString)
      Given a DICOM object encoded as a list of attributes, get a JSON document.
      javax.json.JsonArray getDocument​(java.lang.String filename)
      Given a DICOM object encoded as a list of attributes, get a JSON document.
      javax.json.JsonArray getDocument​(java.lang.String filename, boolean useKeywordInsteadOfTag, boolean addTag, boolean addKeyword, boolean addVR, boolean collapseValueArrays, boolean collapseEmptyToNull, boolean ignoreSR, boolean substituteUIDKeywords, boolean useNumberForIntegerOrDecimalString)
      Given a DICOM object encoded as a list of attributes, get a JSON document.
      static java.lang.String getJsonPersonNameFromPropertiesInJsonObject​(javax.json.JsonObject jsonObjectValue, java.lang.String alphabeticProperty, java.lang.String ideographicProperty, java.lang.String phoneticProperty)  
      static void main​(java.lang.String[] arg)
      Read a DICOM dataset and write a JSON representation of it to the standard output or specified path, or vice versa.
      protected static java.lang.String substituteKeywordForUIDIfPossible​(java.lang.String value)  
      protected static java.lang.String substituteKeywordForUIDIfPossibleAndAppropriateForVRAndRequested​(java.lang.String value, byte[] vr, boolean substitute)  
      protected static java.lang.String substituteKeywordForUIDIfPossibleAndRequested​(java.lang.String value, boolean substitute)  
      protected static java.lang.String substituteUIDForKeywordIfPossible​(java.lang.String value)  
      protected static java.lang.String substituteUIDForKeywordIfPossibleAndAppropriateForVR​(java.lang.String value, byte[] vr)  
      static void write​(java.io.File outputFile, javax.json.JsonArray document)
      Serialize a JSON document.
      static void write​(java.io.OutputStream out, javax.json.JsonArray document)
      Serialize a JSON document.
      static void write​(java.lang.String outputPath, javax.json.JsonArray document)
      Serialize a JSON document.
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • reservedKeywordForPersonNameAlphabeticPropertyInJsonRepresentation

        protected static java.lang.String reservedKeywordForPersonNameAlphabeticPropertyInJsonRepresentation
      • reservedKeywordForPersonNameIdeographicPropertyInJsonRepresentation

        protected static java.lang.String reservedKeywordForPersonNameIdeographicPropertyInJsonRepresentation
      • reservedKeywordForPersonNamePhoneticPropertyInJsonRepresentation

        protected static java.lang.String reservedKeywordForPersonNamePhoneticPropertyInJsonRepresentation
    • Constructor Detail

      • JSONRepresentationOfDicomObjectFactory

        public JSONRepresentationOfDicomObjectFactory()

        Construct a factory object, which can be used to get JSON documents from DICOM objects.

    • Method Detail

      • substituteKeywordForUIDIfPossible

        protected static java.lang.String substituteKeywordForUIDIfPossible​(java.lang.String value)
      • substituteKeywordForUIDIfPossibleAndRequested

        protected static java.lang.String substituteKeywordForUIDIfPossibleAndRequested​(java.lang.String value,
                                                                                        boolean substitute)
      • substituteKeywordForUIDIfPossibleAndAppropriateForVRAndRequested

        protected static java.lang.String substituteKeywordForUIDIfPossibleAndAppropriateForVRAndRequested​(java.lang.String value,
                                                                                                           byte[] vr,
                                                                                                           boolean substitute)
      • substituteUIDForKeywordIfPossible

        protected static java.lang.String substituteUIDForKeywordIfPossible​(java.lang.String value)
      • substituteUIDForKeywordIfPossibleAndAppropriateForVR

        protected static java.lang.String substituteUIDForKeywordIfPossibleAndAppropriateForVR​(java.lang.String value,
                                                                                               byte[] vr)
      • getAttributeTagFromHexadecimalGroupElementValues

        protected static final AttributeTag getAttributeTagFromHexadecimalGroupElementValues​(java.lang.String s)

        Parse an AttributeTag represented as an eight character hexadecimal representation as defined for the standard JSON or XML representation.

        Hex digits may be upper or lower case (though tthe standard requires upper only).

        Returns:
        AttributeTag or null if not in expected format
      • getJsonPersonNameFromPropertiesInJsonObject

        public static java.lang.String getJsonPersonNameFromPropertiesInJsonObject​(javax.json.JsonObject jsonObjectValue,
                                                                                   java.lang.String alphabeticProperty,
                                                                                   java.lang.String ideographicProperty,
                                                                                   java.lang.String phoneticProperty)
      • addPersonNameAsComponentsToJsonObject

        public static void addPersonNameAsComponentsToJsonObject​(javax.json.JsonObjectBuilder jsonPersonNameValue,
                                                                 java.lang.String value,
                                                                 java.lang.String alphabeticProperty,
                                                                 java.lang.String ideographicProperty,
                                                                 java.lang.String phoneticProperty)
        Parameters:
        jsonPersonNameValue -
        value -
        alphabeticProperty -
        ideographicProperty -
        phoneticProperty -
      • getDocument

        public javax.json.JsonArray getDocument​(AttributeList list,
                                                boolean useKeywordInsteadOfTag,
                                                boolean addTag,
                                                boolean addKeyword,
                                                boolean addVR,
                                                boolean collapseValueArrays,
                                                boolean collapseEmptyToNull,
                                                boolean ignoreSR,
                                                boolean substituteUIDKeywords,
                                                boolean useNumberForIntegerOrDecimalString)
                                         throws DicomException

        Given a DICOM object encoded as a list of attributes, get a JSON document.

        Parameters:
        list - the list of DICOM attributes
        useKeywordInsteadOfTag - use the keyword from the DicomDictionary rather than the hexadecimal tag group and element
        addTag - add the hexadecimal group and element as an additional attribute
        addKeyword - add the DicomDictionary keyword as an additional attribute
        addVR - add the value representation as an additional attribute
        collapseValueArrays - whether or not to elide value object and array when a single value and no other objects
        collapseEmptyToNull - whether or not to elide empty object as value and send null instead when zero length attribute
        ignoreSR - whether or not to ignore SR Content Items (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        substituteUIDKeywords - whether or not to substitute keywords for recognized standard SOP Classes
        useNumberForIntegerOrDecimalString - whether or not to use JSON Number instead of JSON String for IS and DS attributes
        Returns:
        the JSON document
        Throws:
        DicomException
      • getDocument

        public javax.json.JsonArray getDocument​(AttributeList list)
                                         throws DicomException

        Given a DICOM object encoded as a list of attributes, get a JSON document.

        Parameters:
        list - the list of DICOM attributes
        Returns:
        the JSON document
        Throws:
        DicomException
      • getDocument

        public javax.json.JsonArray getDocument​(java.io.File file,
                                                boolean useKeywordInsteadOfTag,
                                                boolean addTag,
                                                boolean addKeyword,
                                                boolean addVR,
                                                boolean collapseValueArrays,
                                                boolean collapseEmptyToNull,
                                                boolean ignoreSR,
                                                boolean substituteUIDKeywords,
                                                boolean useNumberForIntegerOrDecimalString)
                                         throws java.io.IOException,
                                                DicomException

        Given a DICOM object encoded as a list of attributes, get a JSON document.

        Parameters:
        file - the DICOM file
        useKeywordInsteadOfTag - use the keyword from the DicomDictionary rather than the hexadecimal tag group and element
        addTag - add the hexadecimal group and element as an additional attribute
        addKeyword - add the DicomDictionary keyword as an additional attribute
        addVR - add the value representation as an additional attribute
        collapseValueArrays - whether or not to elide value object and array when a single value and no other objects
        collapseEmptyToNull - whether or not to elide empty object as value and send null instead when zero length attribute
        ignoreSR - whether or not to ignore SR Content Items (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        substituteUIDKeywords - whether or not to substitute keywords for recognized standard SOP Classes
        useNumberForIntegerOrDecimalString - whether or not to use JSON Number instead of JSON String for IS and DS attributes
        Returns:
        the JSON document
        Throws:
        java.io.IOException
        DicomException
      • getDocument

        public javax.json.JsonArray getDocument​(java.io.File file)
                                         throws java.io.IOException,
                                                DicomException

        Given a DICOM object encoded as a list of attributes, get a JSON document.

        Parameters:
        file - the DICOM file
        Returns:
        the JSON document
        Throws:
        java.io.IOException
        DicomException
      • getDocument

        public javax.json.JsonArray getDocument​(java.lang.String filename,
                                                boolean useKeywordInsteadOfTag,
                                                boolean addTag,
                                                boolean addKeyword,
                                                boolean addVR,
                                                boolean collapseValueArrays,
                                                boolean collapseEmptyToNull,
                                                boolean ignoreSR,
                                                boolean substituteUIDKeywords,
                                                boolean useNumberForIntegerOrDecimalString)
                                         throws java.io.IOException,
                                                DicomException

        Given a DICOM object encoded as a list of attributes, get a JSON document.

        Parameters:
        filename - the DICOM file name
        useKeywordInsteadOfTag - use the keyword from the DicomDictionary rather than the hexadecimal tag group and element
        addTag - add the hexadecimal group and element as an additional attribute
        addKeyword - add the DicomDictionary keyword as an additional attribute
        addVR - add the value representation as an additional attribute
        collapseValueArrays - whether or not to elide value object and array when a single value and no other objects
        collapseEmptyToNull - whether or not to elide empty object as value and send null instead when zero length attribute
        ignoreSR - whether or not to ignore SR Content Items (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        substituteUIDKeywords - whether or not to substitute keywords for recognized standard SOP Classes
        useNumberForIntegerOrDecimalString - whether or not to use JSON Number instead of JSON String for IS and DS attributes
        Returns:
        the JSON document
        Throws:
        java.io.IOException
        DicomException
      • getDocument

        public javax.json.JsonArray getDocument​(java.lang.String filename)
                                         throws java.io.IOException,
                                                DicomException

        Given a DICOM object encoded as a list of attributes, get a JSON document.

        Parameters:
        filename - the DICOM file name
        Returns:
        the JSON document
        Throws:
        java.io.IOException
        DicomException
      • getAttributeList

        public AttributeList getAttributeList​(javax.json.JsonObject topLevelObject,
                                              boolean ignoreUnrecognizedTags,
                                              boolean ignoreSR)
                                       throws DicomException

        Given a DICOM object encoded in a JSON document convert it to a list of attributes.

        Parameters:
        topLevelObject - the first object of the array that is the JSON document
        ignoreUnrecognizedTags - whether or not to ignore unrecognized tags (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        ignoreSR - whether or not to ignore SR Content Items (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        Returns:
        the list of DICOM attributes
        Throws:
        DicomException
      • getAttributeList

        public AttributeList getAttributeList​(javax.json.JsonArray document,
                                              boolean ignoreUnrecognizedTags,
                                              boolean ignoreSR)
                                       throws DicomException

        Given a DICOM object encoded as a JSON document convert it to a list of attributes.

        Parameters:
        document - the JSON document
        ignoreUnrecognizedTags - whether or not to ignore unrecognized tags (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        ignoreSR - whether or not to ignore SR Content Items (e.g., when used with JSONRepresentationOfStructuredReportObjectFactory)
        Returns:
        the list of DICOM attributes
        Throws:
        DicomException
      • getAttributeList

        public AttributeList getAttributeList​(javax.json.JsonArray document)
                                       throws DicomException

        Given a DICOM object encoded as a JSON document convert it to a list of attributes.

        Parameters:
        document - the JSON document
        Returns:
        the list of DICOM attributes
        Throws:
        DicomException
      • getAttributeList

        public AttributeList getAttributeList​(java.io.InputStream stream)
                                       throws java.io.IOException,
                                              DicomException

        Given a DICOM object encoded as a JSON document in a stream convert it to a list of attributes.

        Parameters:
        stream - the input stream containing the JSON document
        Returns:
        the list of DICOM attributes
        Throws:
        java.io.IOException
        DicomException
      • getAttributeList

        public AttributeList getAttributeList​(java.io.File file)
                                       throws java.io.IOException,
                                              DicomException

        Given a DICOM object encoded as a JSON document in a file convert it to a list of attributes.

        Parameters:
        file - the input file containing the JSON document
        Returns:
        the list of DICOM attributes
        Throws:
        java.io.IOException
        DicomException
      • getAttributeList

        public AttributeList getAttributeList​(java.lang.String name)
                                       throws java.io.IOException,
                                              DicomException

        Given a DICOM object encoded as a JSON document in a named file convert it to a list of attributes.

        Parameters:
        name - the input file containing the JSON document
        Returns:
        the list of DICOM attributes
        Throws:
        java.io.IOException
        DicomException
      • write

        public static void write​(java.io.OutputStream out,
                                 javax.json.JsonArray document)
                          throws java.io.IOException

        Serialize a JSON document.

        Parameters:
        out - the output stream to write to
        document - the JSON document
        Throws:
        java.io.IOException
      • write

        public static void write​(java.io.File outputFile,
                                 javax.json.JsonArray document)
                          throws java.io.IOException

        Serialize a JSON document.

        Parameters:
        outputFile - the output file to write to
        document - the JSON document
        Throws:
        java.io.IOException
      • write

        public static void write​(java.lang.String outputPath,
                                 javax.json.JsonArray document)
                          throws java.io.IOException

        Serialize a JSON document.

        Parameters:
        outputPath - the output path to write to
        document - the JSON document
        Throws:
        java.io.IOException
      • createDocumentAndWriteIt

        public static void createDocumentAndWriteIt​(AttributeList list,
                                                    java.io.OutputStream out)
                                             throws DicomException

        Serialize a JSON document created from a DICOM attribute list.

        Parameters:
        list - the list of DICOM attributes
        out - the output stream to write to
        Throws:
        DicomException
      • createDocumentAndWriteIt

        public static void createDocumentAndWriteIt​(AttributeList list,
                                                    java.io.File outputFile)
                                             throws java.io.IOException,
                                                    DicomException

        Serialize a JSON document created from a DICOM attribute list.

        Parameters:
        list - the list of DICOM attributes
        outputFile - the output file to write to
        Throws:
        java.io.IOException
        DicomException
      • createDocumentAndWriteIt

        public static void createDocumentAndWriteIt​(AttributeList list,
                                                    java.lang.String outputPath)
                                             throws java.io.IOException,
                                                    DicomException

        Serialize a JSON document created from a DICOM attribute list.

        Parameters:
        list - the list of DICOM attributes
        outputPath - the output path to write to
        Throws:
        java.io.IOException
        DicomException
      • main

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

        Read a DICOM dataset and write a JSON representation of it to the standard output or specified path, or vice versa.

        Parameters:
        arg - either one input path of the file containing the DICOM/JSON dataset, or a direction argument (toDICOM or toJSON, case insensitive) and an input path, and optionally an output path