.. meta::
    :description: Infrastructure Image Formats

.. _raw_metadata:

RAW Metadata Files
==================

Dragonfly supports loading RAW image files with a sibling metadata file that specifies the geometry, shape and other
properties of the image data.

While there are several different formats out there (too many to be listed here), and while some of those formats are
supported by Dragonfly, Dragonfly supports two "homemade" metadata files for its RAW files:

DAT format

XML format

The DAT format is a legacy feature that should not be the preferred choice.


DAT Format
----------

The DAT file format is a straight ASCII text file where each line has a field name and a value, of the form

field: value

These are the valid fields, their meaning and the expected type of value.

+--------------------+-----------------------------------------------------------+------------+
| Name               | Meaning                                                   | Type       |
+====================+===========================================================+============+
| ObjectFileName     | File name of the RAW data file (only the file name, no    | string     |
|                    | path). It is implied that the file sits in the same       |            |
|                    | folder as the metadata file.                              |            |
+--------------------+-----------------------------------------------------------+------------+
| Resolution         | X Y Z dimensions                                          | 3 int      |
+--------------------+-----------------------------------------------------------+------------+
| Format             | Data type, one of: UCHAR USHORT FLOAT UINT                | string     |
+--------------------+-----------------------------------------------------------+------------+
| SliceThickness     | X Y Z pixel sizes                                         | 3 double   |
+--------------------+-----------------------------------------------------------+------------+
| MeasurementUnit    | Data unit, one of: METER MILLIMETER Density               | string     |
+--------------------+-----------------------------------------------------------+------------+
| TimeSteps          | T dimension                                               | int        |
+--------------------+-----------------------------------------------------------+------------+
| ChannelOrientation | 3 vectors of size 3, representing respectively the        | 9 double   |
|                    | direction, up and normal axis.                            |            |
+--------------------+-----------------------------------------------------------+------------+
| ChannelPosition    | A position triplet                                        | 3 double   |
+--------------------+-----------------------------------------------------------+------------+
| DataSlope          | The data slope                                            | double     |
+--------------------+-----------------------------------------------------------+------------+
| DataOffset         | The data offset                                           | double     |
+--------------------+-----------------------------------------------------------+------------+
| SliceData          | Slice orientation, position and pixel size.               |            |
|                    | Each slice should have the form:                          |            |
|                    | SliceData: sliceN N D D D D D D D D D D D D D D D         |            |
+--------------------+------------------------------------------------------------------------+


XML Format
----------

Here is the XML schema (xsd) file.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

 <xsd:element name="RAWFileData" type="RAWFormat" />


 <xsd:complexType name="RAWFormat">
   <xsd:sequence>
      <!-- ObjectFileName holds the RAW file name -->
      <xsd:element name="ObjectFileName" type="xsd:string" />
      <!-- Version holds a version number, not required -->
      <xsd:element name="Version" type="xsd:double" minOccurs="0" maxOccurs="1"/>
      <!-- Format holds the pixel data type -->
      <xsd:element name="Format" type="pixelType"/>
      <xsd:element name="DataSlope" type="xsd:double" minOccurs="0" maxOccurs="1"/>
      <xsd:element name="DataOffset" type="xsd:double" minOccurs="0" maxOccurs="1"/>
      <xsd:element name="Unit" type="xsd:string" minOccurs="0" maxOccurs="1"/>
      <xsd:element name="Resolution" type="imageResolution"/>
      <xsd:element name="Spacing" type="imageSpacing"/>
      <xsd:element name="Orientation" type="imageOrientation" minOccurs="0" maxOccurs="1"/>
      <xsd:element name="Position" type="imagePosition" minOccurs="0" maxOccurs="1"/>
      <!-- See note below -->
      <xsd:element name="SliceData" minOccurs="0"/>
   </xsd:sequence>
   </xsd:complexType>

	 <xsd:simpleType name="pixelType">
    <xsd:restriction base="xsd:string">
   <xsd:enumeration value="UCHAR" />
   <xsd:enumeration value="USHORT" />
   <xsd:enumeration value="UINT" />
   <xsd:enumeration value="FLOAT" />
  </xsd:restriction>
 </xsd:simpleType>

	 <xsd:complexType name="imageResolution">
	 <xsd:attribute use="required" name="X" type="xsd:integer" />
	 <xsd:attribute use="required" name="Y" type="xsd:integer" />
	 <xsd:attribute use="required" name="Z" type="xsd:integer" />
	 <xsd:attribute use="required" name="T" type="xsd:integer" />
	 </xsd:complexType>

      <!-- What we call spacing is the pixel size -->
	 <xsd:complexType name="imageSpacing">
	 <xsd:attribute use="required" name="X" type="xsd:double" />
	 <xsd:attribute use="required" name="Y" type="xsd:double" />
	 <xsd:attribute use="required" name="Z" type="xsd:double" />
	 </xsd:complexType>

      <!-- Orientation is 3 vectors, respectively direction, up and normal axis -->
	 <xsd:complexType name="imageOrientation">
	 <xsd:attribute use="required" name="X0" type="xsd:double" />
	 <xsd:attribute use="required" name="X1" type="xsd:double" />
	 <xsd:attribute use="required" name="X2" type="xsd:double" />
	 <xsd:attribute use="required" name="Y0" type="xsd:double" />
	 <xsd:attribute use="required" name="Y1" type="xsd:double" />
	 <xsd:attribute use="required" name="Y2" type="xsd:double" />
	 <xsd:attribute use="required" name="Z0" type="xsd:double" />
	 <xsd:attribute use="required" name="Z1" type="xsd:double" />
	 <xsd:attribute use="required" name="Z2" type="xsd:double" />
	 </xsd:complexType>

      <!-- Position is in world coordinates, P1 -> X, P2 -> Y, P3 -> Z -->
	 <xsd:complexType name="imagePosition">
	 <xsd:attribute use="required" name="P1" type="xsd:double" />
	 <xsd:attribute use="required" name="P2" type="xsd:double" />
	 <xsd:attribute use="required" name="P3" type="xsd:double" />
	 </xsd:complexType>

      <!-- When you have slice orientation and position, this is where you define them.
	  Because our XML is poorly structured for the slice data, we cannot describe it
	  in the XSD.

	  You start with an empty node named "SliceData"
	  For each slice, add a node thus:

	  SliceN X0= X1= X2= Y0= Y1= Y2= Z0= Z1= Z2= P1= P2= P3=

	  where N is the slice number (0 based)

	  -->
</xsd:schema>