The following provides technical details on the OME-TIFFformat. It assumes familiarity with both theTIFF andOME-XML formats, although there is some review of both.
An OME-TIFF dataset consists of:
- one or more files in standard TIFF format with the file extension.ome.tif or .ome.tiff orBigTIFF formatwith one of these same file extensions or a BigTIFF-specificextension .ome.tf2, .ome.tf8 or .ome.btf
- a string of OME-XML metadata embedded in the ImageDescription tag of thefirst IFD (Image File Directory) of each file. The XML string must be UTF-8encoded.
Note that BigTIFF-specific file extensions are an addition to the originalspecification, and software using an older version of the specification maynot be able to handle these file extensions.
OME-XML metadata¶
This string is a standard block of OME-XML, except that instead ofstoring pixels as BinData elements with base64-encoded pixel databeneath them, it references pixels with TiffData elements that specifywhich TIFF IFD corresponds to each image plane. As such, the OME-XMLstring can be regarded as a “metadata block” because the actual pixelsare stored within the TIFF structure, not the XML.
OME-TIFF header
The diagram OME-TIFF header (adapted from the TIFFspecification) shows the organization of a TIFF header along with theplacement of the OME-XML metadata block. Note this is for the TIFFstandard specification only; the header structure is slightlydifferent for BigTIFF; see the BigTIFF file format specification. A TIFF file cancontain any number of IFDs, with each one specifying an image plane along withcertain accompanying metadata such as pixel dimensions, physicaldimensions, bit depth, color table, etc. One of the fields an IFD cancontain is ImageDescription, which provides a place to write a commentdescribing the corresponding image plane. This field is a convenientplace to store the OME-XML metadata block—any TIFF library capable ofparsing IFDs and extracting an ImageDescription comment can easilyobtain an OME-TIFF file’s entire set of metadata as OME-XML.
Note
A TIFF file contains one IFD per image plane, but theOME-XML metadata block is stored only in the first IFD structure.However, for an image sequence distributed across multiple OME-TIFFfiles, each file will contain a copy of the OME-XML metadata block(see Partial OME-XML metadata below for exceptions tothis rule). Thus, if any files are lost, the metadata is preserved. TheOME-XML block in each file is nearly identical—the only difference is inthe TiffData elements appearing beneath Pixels elements, since each TIFFfile contains a different portion of the image data (seeMulti-file OME-TIFF below).
DimensionOrder¶
As mentioned above, the standard OME-XML format encodes image planes asbase64 character blocks contained within BinData elements beneath aPixels element. The Pixels element has a DimensionOrder attribute thatspecifies the rasterization order of the image planes. For example,XYZTC means that there is a series of image planes with the Z axisvarying fastest, followed by T, followed by C (e.g. if a XYZTC datasetcontains two focal planes, three time points and two channels, the orderwould be: Z0-T0-C0, Z1-T0-C0, Z0-T1-C0, Z1-T1-C0, Z0-T2-C0, Z1-T2-C0,Z0-T0-C1, Z1-T0-C1, Z0-T1-C1, Z1-T1-C1, Z0-T2-C1, Z1-T2-C1).
Since a multi-page TIFF has no limit to the number of image planes itcan contain, the same scheme described above for specifying therasterization order works within the OME-TIFF file. The only differenceis that instead of the pixels being encoded in base64 inside BinDataelements, they are stored within the TIFF file in the standard fashion,one per IFD; see the TiffData element below for specifics.
TIFF comments¶
When embedding your OME-XML string as a TIFF comment, it is best practice topreface it with the following informative comment:
<!-- Warning: this comment is an OME-XML metadata block, which containscrucial dimensional parameters and other important metadata. Please editcautiously (if at all), and back up the original data before doing so.For more information, see the OME-TIFF documentation:https://docs.openmicroscopy.org/latest/ome-model/ome-tiff/ -->
The TiffData element¶
As the illustration OME-TIFF header shows, all that is needed toindicate that the pixels are located within the enclosing TIFF structure is aTiffDataelement with no attributes. By default, the first IFD corresponds tothe first image plane (Z0-T0-C0), and the rasterization order of subsequentIFDs is given by the Pixels element’s DimensionOrder attribute, asdescribed above.
However, there are several attributes for TiffData elements allowinggreater control over the dimensional position of each IFD:
- IFD- gives the IFD(s) for which this element is applicable.Indexed from 0. Default is 0 (the first IFD).
- FirstZ- gives the Z position of the image plane at the specifiedIFD. Indexed from 0. Default is 0 (the first Z position).
- FirstT- gives the T position of the image plane at the specifiedIFD. Indexed from 0. Default is 0 (the first T position).
- FirstC- gives the C position of the image plane at the specifiedIFD. Indexed from 0. Default is 0 (the first C position).
- PlaneCount- gives the number of IFDs affected. Dimension order ofIFDs is given by the enclosing Pixels element’s DimensionOrderattribute. Default is the number of IFDs in the TIFF file, unless anIFD is specified, in which case the default is 1.
Here are some example XML fragments:
Fragment 1¶
<Pixels ID="urn:lsid:loci.wisc.edu:Pixels:ows325" Type="uint8" DimensionOrder="XYZTC" SizeX="512" SizeY="512" SizeZ="3" SizeT="2" SizeC="2"> <TiffData/></Pixels>
| IFD | Position |
|---|---|
| 0 | Z0-T0-C0 |
| 1 | Z1-T0-C0 |
| 2 | Z2-T0-C0 |
| 3 | Z0-T1-C0 |
| 4 | Z1-T1-C0 |
| 5 | Z2-T1-C0 |
| 6 | Z0-T0-C1 |
| 7 | Z1-T0-C1 |
| 8 | Z2-T0-C1 |
| 9 | Z0-T1-C1 |
| 10 | Z1-T1-C1 |
| 11 | Z2-T1-C1 |
The default TiffData tag simply assigns every IFD to a positionaccording to the given DimensionOrder rasterization. If the TIFF filehas more than SizeZ*SizeT*SizeC (3*2*2=12 in this case) IFDs, theremaining IFDs are extraneous and should be ignored by OME-TIFF readers.
Fragment 2¶
<Pixels ID="urn:lsid:loci.wisc.edu:Pixels:ows462" Type="uint8" DimensionOrder="XYCTZ" SizeX="512" SizeY="512" SizeZ="4" SizeT="3" SizeC="2"> <TiffData PlaneCount="10"/></Pixels>
| IFD | Position |
|---|---|
| 0 | Z0-T0-C0 |
| 1 | Z0-T0-C1 |
| 2 | Z0-T1-C0 |
| 3 | Z0-T1-C1 |
| 4 | Z0-T2-C0 |
| 5 | Z0-T2-C1 |
| 6 | Z1-T0-C0 |
| 7 | Z1-T0-C1 |
| 8 | Z1-T1-C0 |
| 9 | Z1-T1-C1 |
When specified, the PlaneCount attribute gives the number of IFDsaffected by the TiffData element. In this case, even though the Pixelselement defines 4*3*2=24 image planes total, the TiffData elementassigns only 10 planes. The remaining 14 planes are unspecified andhence lost.
Fragment 3¶
<Pixels ID="urn:lsid:loci.wisc.edu:Pixels:ows197" Type="uint8" DimensionOrder="XYZTC" SizeX="512" SizeY="512" SizeZ="4" SizeC="3" SizeT="2"> <TiffData IFD="3" PlaneCount="5"/></Pixels>
| IFD | Position |
|---|---|
| 3 | Z0-T0-C0 |
| 4 | Z1-T0-C0 |
| 5 | Z2-T0-C0 |
| 6 | Z3-T0-C0 |
| 7 | Z0-T1-C0 |
States that the rasterization begins at the fourth IFD (IFD #3), andcontinues for five planes total. IFDs #0, #1 and #2 are not used, andshould be ignored by OME-TIFF readers.
Fragment 4¶
<Pixels ID="urn:lsid:loci.wisc.edu:Pixels:ows789" Type="uint8" DimensionOrder="XYZTC" SizeX="512" SizeY="512" SizeZ="1" SizeC="1" SizeT="6"> <TiffData IFD="0" FirstT="5"/> <TiffData IFD="1" FirstT="4"/> <TiffData IFD="2" FirstT="3"/> <TiffData IFD="3" FirstT="2"/> <TiffData IFD="4" FirstT="1"/> <TiffData IFD="5" FirstT="0"/></Pixels>
| IFD | Position |
|---|---|
| 0 | Z0-T5-C0 |
| 1 | Z0-T4-C0 |
| 2 | Z0-T3-C0 |
| 3 | Z0-T2-C0 |
| 4 | Z0-T1-C0 |
| 5 | Z0-T0-C0 |
Any number of TiffData elements may be provided. In this case, the dimensionalpositions of each of the first six IFDs are explicitly defined, effectivelyoverriding the rasterization given by DimensionOrder, storing the planes inreverse temporal order.
For details on validating your OME-XML metadata block, see thevalidating OME-XML section on the Extracting, processing and validating OME-XML page.
Multi-file OME-TIFF¶
As demonstrated above, the OME-TIFF format is capable of storing theentire multidimensional image series in one master OME-TIFF file.
Alternatively, a collection of multiple OME-TIFF files may be used. Usingthe TiffData attributes outlined above together withUUIDelements and attributes, the OME-XML metadata block can unambiguouslydefine which dimensional positions correspond to which IFDs from whichfiles. Each OME-TIFF need not contain the same number of images.
The only difference between the OME-XML metadata block per TIFF file is theUUIDattribute of the root OME element. This value should be a distinctUUID value for each file, so that each TiffData element canunambiguously reference its relevant file using a UUID child element.
Note
The FileNameattribute of the UUID is optional, but strongly recommended—otherwise,the OME-TIFF reader must scan OME-TIFF files in the working directorylooking for matching UUID signatures.
When splitting an OME-TIFF across multiple files, the OME-XML metadata musteither be embedded into each TIFF file or use partial metadata blocks.
Embedded OME-XML metadata¶
In the first case, a nearly identical OME-XML metadata block must be insertedinto the first IFD of each constituent OME-TIFF file.
The only difference between the OME-XML metadata block per TIFF file is theUUIDattribute of the root OME element. This value should be a distinctUUID value for each file, so that each TiffData element canunambiguously reference its relevant file using a UUID child element.
The Tubhiswt demonstrate how OME-TIFF datasets can bedistributed across multiple files. Each of the files in the set has identicalmetadata apart from the UUID, the unique identifier in each file. Forexample the identifiers could be distributed as follows:
tubhiswt_C0_TP0.ome.tif with ID 45c8bf18-6aa2-478c-9080-e0b0d3eb1f70
<OME xmlns="http://www.openmicroscopy.org/Schemas/OME/2016-06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Creator="OME Bio-Formats 5.2.0-m4" UUID="urn:uuid:45c8bf18-6aa2-478c-9080-e0b0d3eb1f70" xsi:schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2016-06 http://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd">... <Pixels BigEndian="false" DimensionOrder="XYZTC" ID="Pixels:0" Interleaved="false" SignificantBits="8" SizeC="2" SizeT="43" SizeX="512" SizeY="512" SizeZ="10" Type="uint8">... <TiffData FirstC="0" FirstT="0" FirstZ="0" IFD="0" PlaneCount="1"> <UUID FileName="tubhiswt_C0_TP0.ome.tif"> urn:uuid:45c8bf18-6aa2-478c-9080-e0b0d3eb1f70 </UUID> </TiffData>... <TiffData FirstC="0" FirstT="1" FirstZ="1" IFD="1" PlaneCount="1"> <UUID FileName="tubhiswt_C0_TP1.ome.tif"> urn:uuid:743275b7-6726-46bd-b7bb-aca3085f429a </UUID> </TiffData>...
tubhiswt_C0_TP1.ome.tif with ID 743275b7-6726-46bd-b7bb-aca3085f429a
<OME xmlns="http://www.openmicroscopy.org/Schemas/OME/2016-06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Creator="OME Bio-Formats 5.2.0-m4" UUID="urn:uuid:743275b7-6726-46bd-b7bb-aca3085f429a" xsi:schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2016-06 http://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd"... <Pixels BigEndian="false" DimensionOrder="XYZTC" ID="Pixels:0" Interleaved="false" SignificantBits="8" SizeC="2" SizeT="43" SizeX="512" SizeY="512" SizeZ="10" Type="uint8">... <TiffData FirstC="0" FirstT="0" FirstZ="0" IFD="0" PlaneCount="1"> <UUID FileName="tubhiswt_C0_TP0.ome.tif"> urn:uuid:45c8bf18-6aa2-478c-9080-e0b0d3eb1f70 </UUID> </TiffData>... <TiffData FirstC="0" FirstT="1" FirstZ="0" IFD="0" PlaneCount="1"> <UUID FileName="tubhiswt_C0_TP1.ome.tif"> urn:uuid:743275b7-6726-46bd-b7bb-aca3085f429a </UUID> </TiffData>...
And so on for files:
- tubhiswt_C0_TP2.ome.tif with ID 1f462b60-b508-446e-b42a-c4e6fa2a44e8
- tubhiswt_C0_TP3.ome.tif with ID a023901d-43fd-44f2-b4be-159afa1e985c
- ...
Partial OME-XML metadata¶
Instead of embedding the full OME-XML metadata into the header of eachOME-TIFF, partial OME-XML metadata blocks can be stored in some or all of theOME-TIFF files using theBinary-Onlyelement as illustrated below:
<?xml version="1.0" encoding="UTF-8"?><OME UUID="urn:uuid:4978087c-a670-4b12-af53-256c62d8d101" xmlns="http://www.openmicroscopy.org/Schemas/OME/2016-06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2016-06 http://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd"> <BinaryOnly MetadataFile="multifile.companion.ome" UUID="urn:uuid:07504f88-7bc3-11e0-b937-2faf67bc00b3"/></OME>
The MetadataFileelement should contain the name of the master file containing the fullOME-XML metadata block andUUIDshould contain the UUID of this master file.
The master file containing the full OME-XML metadata should be either anOME-XML companion file with the extension .companion.ome or a masterOME-TIFF file containing the full metadata (see Multi-file OME-TIFF filesets forrepresentative samples).
