Difference between revisions of "The MIRC ZipObject"

From MircWiki
Jump to: navigation, search
m (Reverted edits by Massage (Talk); changed back to last version by Johnperry)
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The MIRC ZipObject is a class that provides access to collections of files wrapped in a zip file. It is intended to encapsulate groups of related files, for instance, the output of analysis of clinical trial data. To carry information that allows applications to know how to relate a ZipObject to other data, each ZipObject must contain a manifest. A manifest is an XML text file named <b>manifest.xml</b>, located in the root of zip file's directory tree (e.g. with no path information).
+
The MIRC ZipObject is a collection of files wrapped in a zip file. It is intended to encapsulate groups of related files, for instance several data files which are the results of analysis of clinical trial data. To carry information that allows applications to know how to relate a ZipObject to other data, each ZipObject must contain a manifest. A manifest is an XML text file named <b>manifest.xml</b>, located in the root of zip file's directory tree (e.g. with no path information).
  
The root element of a manifest can have any name. By convention, it is called <b>manifest</b>, but in some situations, it can be useful to use different names when a clinical trial has multiple types of ZipObjects and it is desired to make the root element name indicate the type.
+
The root element of a manifest can have any name. By convention, it is called <b>manifest</b>.
  
The root element has two required attributes:
+
The root element has several attributes:
*<b>uid</b> defines a unique identifier for the ZipObject. The DICOM UID format is strongly suggested, but there is no technical requirement imposed by the RSNA MIRC implementation on the format.
+
*<b>uid</b> is required. It defines a unique identifier for the ZipObject. The DICOM UID format is strongly suggested, but there is no technical requirement imposed by the RSNA MIRC implementation on the format.
*<b>study-uid</b> provides a reference to the study. It is necessary to link the ZipObject to the MIRCdocument containing the other objects associated with the same study. If the ZipObject contains results obtained from the analysis of DICOM images from a specific study, the DICOM StudyInstanceUID should be used.  
+
*<b>study-uid</b> is required in clinical trial data submissions. It provides a reference to the study. This attribute links the ZipObject to other objects associated with the same study. If the ZipObject contains results obtained from the analysis of DICOM images from a specific study, the DICOM StudyInstanceUID must be used. If the ZipObject is not used as part of a clinical trial data submission, this attribute is optional.
 
+
*<b>pt-id</b> is optional. For ZipObjects which encapsulate data for a single patient, this identifier may be included.
The root element has one additional attribute which has special support in the MIRC ZipObject class:
+
*<b>pt-name</b> is optional. For ZipObjects which encapsulate data for a single patient, this attribute may be included.
 
*<b>description</b> is optional. It provides a free text description of the ZipObject. The RSNA MIRC implementation presents this text in the table of object references in a MIRCdocument.
 
*<b>description</b> is optional. It provides a free text description of the ZipObject. The RSNA MIRC implementation presents this text in the table of object references in a MIRCdocument.
 +
*<b>date</b> is optional. It provides a date for the ZipObject. The date must be in the format specified by ISO 8601 (YYYY-MM-DD).
 +
*<b>version</b> is optional. It provides a version reference for the manifest format. This could be used by software as an aid in interpreting its contents.
 +
*<b>type</b> is optional. It can be used to distinguish between ZipObjects of different types. No enumerated values of the type attribute are defined.
  
Additional attributes may be included as well; however, they have no special support in the MIRC ZipObject class, for example:
+
The manifest root element has no required child elements. The intention is that each manifest contain whatever child elements are appropriate to describe the contents of the ZipObject and their relationships with each other as well as external objects, but there is no required standard format. It is expected that each application (e.g., each clinical trial or research project) will invent its own manifest consistent with the attributes defined above.
*<b>date</b> provides a date for the ZipObject. The date must be in the format specified by ISO 8601 (YYYY-MM-DD).
+
*<b>version</b> provides a version reference for the manifest format. This could be used by software as an aid in interpreting its contents.
+
 
+
The manifest root element has no required child elements. The intention is that each manifest contain whatever child elements are appropriate to describe the contents of the ZipObject and their relationships with each other as well as external objects, but there is no required standard format.
+
  
 
An example of a simple manifest is:
 
An example of a simple manifest is:
Line 27: Line 26:
 
<manifest uid="1.2.3.4.5"
 
<manifest uid="1.2.3.4.5"
 
           study-uid="1.2.3.4.5.1"
 
           study-uid="1.2.3.4.5.1"
 +
          pt-id="123"
 
           description="Analytical results"
 
           description="Analytical results"
 
           date="2006-11-06"
 
           date="2006-11-06"
 
           version="1">
 
           version="1">
     <patient-id>123</patient-id>
+
     <series>
    <series-uid>1.2.3.4.5.2</series-uid>
+
        <series-uid>1.2.3.4.5.2</series-uid>
     <series-uid>1.2.3.4.5.3</series-uid>
+
        <instance-uid>1.2.3.4.5.4</instance-uid>
 +
        <instance-uid>1.2.3.4.5.5</instance-uid>
 +
        <instance-uid>1.2.3.4.5.6</instance-uid>
 +
        <instance-uid>1.2.3.4.5.7</instance-uid>
 +
     </series>
 +
    <series>
 +
        <series-uid>1.2.3.4.5.3</series-uid>
 +
        <instance-uid>1.2.3.4.5.8</instance-uid>
 +
        <instance-uid>1.2.3.4.5.9</instance-uid>
 +
    </series>
 
</manifest>
 
</manifest>
 
</pre>
 
</pre>
 
<b>Important note:</b> The RSNA MIRC implementation does not provide anonymization for ZipObjects.
 
 
The RSNA MIRC software provides a ZipObject class, <b>org.rsna.mircsite.util.ZipObject</b>, which provides access to the manifest, certain manifest attributes, and all the files within the zip file. See [[The RSNA MIRC Source Code]] for instructions on obtaining the source code.
 

Latest revision as of 18:57, 31 July 2009

The MIRC ZipObject is a collection of files wrapped in a zip file. It is intended to encapsulate groups of related files, for instance several data files which are the results of analysis of clinical trial data. To carry information that allows applications to know how to relate a ZipObject to other data, each ZipObject must contain a manifest. A manifest is an XML text file named manifest.xml, located in the root of zip file's directory tree (e.g. with no path information).

The root element of a manifest can have any name. By convention, it is called manifest.

The root element has several attributes:

  • uid is required. It defines a unique identifier for the ZipObject. The DICOM UID format is strongly suggested, but there is no technical requirement imposed by the RSNA MIRC implementation on the format.
  • study-uid is required in clinical trial data submissions. It provides a reference to the study. This attribute links the ZipObject to other objects associated with the same study. If the ZipObject contains results obtained from the analysis of DICOM images from a specific study, the DICOM StudyInstanceUID must be used. If the ZipObject is not used as part of a clinical trial data submission, this attribute is optional.
  • pt-id is optional. For ZipObjects which encapsulate data for a single patient, this identifier may be included.
  • pt-name is optional. For ZipObjects which encapsulate data for a single patient, this attribute may be included.
  • description is optional. It provides a free text description of the ZipObject. The RSNA MIRC implementation presents this text in the table of object references in a MIRCdocument.
  • date is optional. It provides a date for the ZipObject. The date must be in the format specified by ISO 8601 (YYYY-MM-DD).
  • version is optional. It provides a version reference for the manifest format. This could be used by software as an aid in interpreting its contents.
  • type is optional. It can be used to distinguish between ZipObjects of different types. No enumerated values of the type attribute are defined.

The manifest root element has no required child elements. The intention is that each manifest contain whatever child elements are appropriate to describe the contents of the ZipObject and their relationships with each other as well as external objects, but there is no required standard format. It is expected that each application (e.g., each clinical trial or research project) will invent its own manifest consistent with the attributes defined above.

An example of a simple manifest is:

<manifest uid="1.2.3.4.5"
          study-uid="1.2.3.4.5.1"
          description="Analytical results" />

A more complex manifest might be:

<manifest uid="1.2.3.4.5"
          study-uid="1.2.3.4.5.1"
          pt-id="123"
          description="Analytical results"
          date="2006-11-06"
          version="1">
    <series>
        <series-uid>1.2.3.4.5.2</series-uid>
        <instance-uid>1.2.3.4.5.4</instance-uid>
        <instance-uid>1.2.3.4.5.5</instance-uid>
        <instance-uid>1.2.3.4.5.6</instance-uid>
        <instance-uid>1.2.3.4.5.7</instance-uid>
    </series>
    <series>
        <series-uid>1.2.3.4.5.3</series-uid>
        <instance-uid>1.2.3.4.5.8</instance-uid>
        <instance-uid>1.2.3.4.5.9</instance-uid>
    </series>
</manifest>