Package com.pixelmed.dicom

## Class XMLRepresentationOfDicomObjectFactory

- java.lang.Object
- - com.pixelmed.dicom.XMLRepresentationOfDicomObjectFactory

-     public class XMLRepresentationOfDicomObjectFactory
      extends java.lang.Object

  A class to encode a representation of a DICOM object in an XML form, suitable for analysis as human-readable text, or for feeding into an XSLT-based validator, and to convert them back again.

  An example of the type of output produced by this class is as follows:

      <?xml version="1.0" encoding="UTF-8"?>
        <DicomObject>
          <FileMetaInformationGroupLength element="0000" group="0002" vr="UL">
            <value number="1">222</value>
          </FileMetaInformationGroupLength>
          ...
          <ImageType element="0008" group="0008" vr="CS">
            <value number="1">ORIGINAL</value>
            <value number="2">PRIMARY</value>
            <value number="3">CINE</value>
            <value number="4">NONE</value>
          </ImageType>
          ...
          <ContrastBolusAgentSequence element="0012" group="0018" vr="SQ">
            <Item number="1">
              <CodeValue element="0100" group="0008" vr="SH">
                <value number="1">C-17800</value>
              </CodeValue>
            ...
            </Item>
          </ContrastBolusAgentSequence>
          ...
          <PixelData element="0010" group="7fe0" vr="OW"/>
      </DicomObject>

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

  - Rather than a generic name for all DICOM data elements, like "element", with an attribute to provide the human-readable name, the name of the XML element itself is a human-readable keyword, as used in the DICOM Data Dictionary for the toolkit; the group and element tags are available as attributes of each such element; this makes construction of XPath accessors more straightforward.
  - The value representation of the DICOM source element is conveyed explicitly in an attribute; this facilitates validation of the XML result (e.g., that the correct VR has been used, and that the values are compatible with that VR).
  - Individual values of a DICOM data element are expressed as separate XML elements (named "value"), each with an attribute ("number") to specify their order, starting from 1 increasing by 1; this prevents users of the XML form from needing to parse multiple string values and separate out the DICOM value delimiter (backslash), and allows XPath accessors to obtain specific values; it also allows for access to separate values of binary, rather than string, DICOM data elements, which are represented the same way. Within each "value" element, the XML plain character data contains a string representation of the value.
  - Sequence items are encoded in a similar manner to multi-valued attributes, i.e., there is a nested XML data element (called "Item") with an explicit numeric attribute ("number") to specify their order, starting from 1 increasing by 1.

  E.g., to test if an image is original, which is determined by a specific value of `ImageType (0008,0008)`, one could write in XPath `"/DicomObject/ImageType/value[@number=1] = 'ORIGINAL'"`. To get the code value of the contrast agent in use, one could write `"/DicomObject/ContrastBolusAgentSequence/Item[@number=1]/CodeValue/value[@number=1]"`, or making some assumptions about cardinality and depth of nesting and removing the predicates, simply `"//ContrastBolusAgentSequence/Item/CodeValue/value"`. One could do this from the command line with a utility such as `XPathQuery`.

  Note that a round trip from DICOM to XML and back again does not 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
  - Attributes with OB and OW value representations 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 XML would be:

      try {
          AttributeList list = new AttributeList();
          list.read("dicomfile",null,true,true);
          Document document = new XMLRepresentationOfDicomObjectFactory().getDocument(list);
          XMLRepresentationOfDicomObjectFactory.write(System.out,document);
      } catch (Exception e) {
          e.printStackTrace(System.err);
       }

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

      try {
          AttributeList list = new AttributeList();
          list.read("dicomfile",null,true,true);
          XMLRepresentationOfDicomObjectFactory.createDocumentAndWriteIt(list,System.out);
      } catch (Exception e) {
          e.printStackTrace(System.err);
       }

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

      try {
          AttributeList list = new XMLRepresentationOfDicomObjectFactory().getAttributeList("xmlfile");
          list.write(System.out,TransferSyntax.ExplicitVRLittleEndian,true,true);
      } catch (Exception e) {
          e.printStackTrace(System.err);
       }

  or if you need to handle the meta information properly:

      try {
          AttributeList list = new XMLRepresentationOfDicomObjectFactory().getAttributeList("xmlfile");
          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) {
          e.printStackTrace(System.err);
       }

  See Also:
    `XMLRepresentationOfStructuredReportObjectFactory`, `XPathQuery`, `com.pixelmed.validate`, `Document`

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XMLRepresentationOfDicomObjectFactory()` | Construct a factory object, which can be used to get XML documents from DICOM objects.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static void` | `createDocumentAndWriteIt​(AttributeList list, java.io.OutputStream out)` | Serialize an XML document (DOM tree) created from a DICOM attribute list.
    `AttributeList` | `getAttributeList​(java.io.InputStream stream)` | Given a DICOM object encoded as an XML document in a stream convert it to a list of attributes.
    `AttributeList` | `getAttributeList​(java.lang.String name)` | Given a DICOM object encoded as an XML document in a named file convert it to a list of attributes.
    `AttributeList` | `getAttributeList​(org.w3c.dom.Document document)` | Given a DICOM object encoded as an XML document convert it to a list of attributes.
    `org.w3c.dom.Document` | `getDocument​(AttributeList list)` | Given a DICOM object encoded as a list of attributes, get an XML document as a DOM tree.
    `static void` | `main​(java.lang.String[] arg)` | Read a DICOM dataset and write an XML representation of it to the standard output, or vice versa.
    `static java.lang.String` | `toString​(org.w3c.dom.Node node)` |
    `static java.lang.String` | `toString​(org.w3c.dom.Node node, int indent)` |
    `static void` | `write​(java.io.OutputStream out, org.w3c.dom.Document document)` | Serialize an XML document (DOM tree).

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### XMLRepresentationOfDicomObjectFactory

          public XMLRepresentationOfDicomObjectFactory()
                                                throws javax.xml.parsers.ParserConfigurationException

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

      Throws:
        `javax.xml.parsers.ParserConfigurationException`

  - ### Method Detail

    - #### getDocument

          public org.w3c.dom.Document getDocument​(AttributeList list)

      Given a DICOM object encoded as a list of attributes, get an XML document as a DOM tree.

      Parameters:
        `list` - the list of DICOM attributes

    - #### getAttributeList

          public AttributeList getAttributeList​(org.w3c.dom.Document document)
                                         throws DicomException

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

      Parameters:
        `document` - the XML document
      Returns:
        the list of DICOM attributes
      Throws:
        `DicomException`

    - #### getAttributeList

          public AttributeList getAttributeList​(java.io.InputStream stream)
                                         throws java.io.IOException,
                                                org.xml.sax.SAXException,
                                                DicomException

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

      Parameters:
        `stream` - the input stream containing the XML document
      Returns:
        the list of DICOM attributes
      Throws:
        `java.io.IOException`
        `org.xml.sax.SAXException`
        `DicomException`

    - #### getAttributeList

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

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

      Parameters:
        `name` - the input file containing the XML document
      Returns:
        the list of DICOM attributes
      Throws:
        `java.io.IOException`
        `org.xml.sax.SAXException`
        `DicomException`

    - #### toString

          public static java.lang.String toString​(org.w3c.dom.Node node,
                                                  int indent)

      Parameters:
        `node` -
        `indent` -

    - #### toString

          public static java.lang.String toString​(org.w3c.dom.Node node)

      Parameters:
        `node` -

    - #### write

          public static void write​(java.io.OutputStream out,
                                   org.w3c.dom.Document document)
                            throws java.io.IOException,
                                   javax.xml.transform.TransformerConfigurationException,
                                   javax.xml.transform.TransformerException

      Serialize an XML document (DOM tree).

      Parameters:
        `out` - the output stream to write to
        `document` - the XML document
      Throws:
        `java.io.IOException`
        `javax.xml.transform.TransformerConfigurationException`
        `javax.xml.transform.TransformerException`

    - #### createDocumentAndWriteIt

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

      Serialize an XML document (DOM tree) created from a DICOM attribute list.

      Parameters:
        `list` - the list of DICOM attributes
        `out` - the output stream to write to
      Throws:
        `java.io.IOException`
        `DicomException`

    - #### main

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

      Read a DICOM dataset and write an XML representation of it to the standard output, or vice versa.

      Parameters:
        `arg` - either one filename of the file containing the DICOM dataset, or a direction argument (toDICOM or toXML, case insensitive) and an input filename