SPIM initial support

Note

This approach is still valid but has been superseded by the 6D, 7D and 8D storage.

This proposal was put together after talks with various groups from the Single (or Selective) Plane Illumination Microscopy (also known as Light Sheet Microscopy) community, about how they can store data from this new and expanding field in the OME data formats.

Rather than a new full schema release, it was a common method of storing SPIM data in an existing schema. This was to allow users to start writing data from their SPIM systems right away in a way that could be upgraded to a full schema with SPIM support when it was released.

The solution below allowed the creation of valid OME-XML or OME-TIFF files that hold the extra SPIM data. We proposed to write an XSLT (Transform) that would upgrade these files to the schema version with the SPIM data moved to the correct location. What is described here is a file only solution. When the data is imported into an OMERO server, all the data will be retained as annotations but it cannot be fitted into the existing database model. This can result in some lost linkages between the data. This is be highlighted below where applicable.

Location in Model

SPIM data was placed in 6 key areas in the model:

1. Tiling
2. Illumination objectives and Cylindrical Lenses
3. Additional values for Objectives
4. Additional Stage Positions
5. SPIM angle
6. Custom system values

Tiling

Where the SPIM data has tiled images, the existing tiling method was used (see Tiled images).

This solution used StageLabel and the Position values on Plane to record the location and arrangement of the individual tiles.

<Image ID="Image:0" Name="Spim Sample Tile 1 Angle 1">
    <StageLabel Name="(1,1) of 1x2" X="1.00" Y="1.00"/>
    <Pixels>
        <Plane TheZ="1" TheT="1" TheC="1" PositionX="1.03" PositionY="0.98" PositionZ="1.02"/>
…
</Image>
<Image ID="Image:1" Name="Spim Sample Tile 2 Angle 1">
    <StageLabel Name="(1,2) of 1x2" X="1.00" Y="2.00"/>
    <Pixels>
        <Plane TheZ="1" TheT="1" TheC="1" PositionX="1.03" PositionY="50.05" PositionZ="1.02"/>
…
</Image>

Illumination objectives and Cylindrical Lenses

The additional objective and other elements in the excitation light path were stored as additional Objectives within the Instrument block. This was already designed to support multiple Objectives.

<Objective ID="Objective:1" Immersion="Oil" LensNA="0.95" NominalMagnification="20"/>
<Objective ID="Objective:TubeLens:1" Model="OME - Tube lens 120 mm Mk1"/>
<Objective ID="Objective:Illumation:1" Model="Objective Mk2" LensNA="0.5" WorkingDistance="19800"/>

Additional values for Objectives

As the function of Objective had been expanded to encompass the additional optical elements, some new attributes were required. These could not be attached directly to the Objective, so were instead attached as Annotations onto the Images that use the objectives. This was not ideal but was required due to restrictions on which objects can have annotations.

The definition of a single XmlAnnotation per Instrument was suggested, with each Image using that Instrument making use of an AnnotationRef to point at this Annotation.

The namespace of the XmlAnnotation had to be:

Namespace="ome-xml.org:additions:post2010-06:objective"

The Annotation would contain a single node that would define multiple Objectives, each with an ID matching one of the Objectives in the Instrument, and any additional attributes needed from the following list:

• FocalLength
• SlitAperture
• LightSheetWidth

Warning

Limitation - As the IDs of any Objective in the Instrument would not survive import into OMERO, these values, while imported as an annotation, would not be correctly linked.

<Image>
…
    <SA:AnnotationRef ID="Annotation:ObjectiveAdditions:1"/>
</Image>

<SA:XMLAnnotation ID="Annotation:ObjectiveAdditions:1" Namespace="ome-xml.org:additions:post2010-06:objective">
    <SA:Description>Extra attribute values for the objective objects.</SA:Description>
    <SA:Value>
        <OME-Extra:ObjectiveAttributes xmlns:OME-Extra="http://www.openmicroscopy.org/Schemas/Additions/2010-10">
            <ObjectiveAdditions ID="Objective:TubeLens:1" FocalLength="120" SlitAperture="6" LightSheetWidth="0.8"/>
            <ObjectiveAdditions ID="Objective:Illumation:1" FocalLength="25"/>
        </OME-Extra:ObjectiveAttributes>
    </SA:Value>
</SA:XMLAnnotation>

Additional Stage Positions

As there were several stages (Sample, Excitation Objective, Cylinder lens) that could be moved on a plane by plane basis, it was necessary to store these extra positions. It was proposed to use a collection of StagePosition objects, stored inside an XmlAnnotation linked to Image using an AnnotationRef.

The namespace of the XmlAnnotation must be:

Namespace="ome-xml.org:additions:post2010-06:spim:positions"

The Annotation would contain a single node that would define multiple StagePosition objects. Each of these objects would contain:

• TheZ, TheT, TheC to define the exact plane it was for
• Name, used to identify which stage the position was e.g. “objective_stage”, “excitation_stage”, “cylinder_stage”
• The PositionX, PositionY, PositionZ location of the stage. Not all of these position values needed to be present.

SPIM angle

The images collected for SPIM are recorded from a number of discrete angles. The angle for each image must be recorded. It was proposed that all the planes for the Z, C, T of each stack of images were stored in their correct location inside a single Image object. Multiple Image objects would then be used, each one repressing a single angle. The order and angle of these separate Images would then be defined by a single XmlAnnotation which each of the Images would reference using an AnnotationRef.

The namespace of the XmlAnnotation must be:

Namespace="ome-xml.org:additions:post2010-06:spim:set"

The Annotation would contain a single <OME-Extra:SpimSet> node that would define multiple SpimImage objects, each with an ID matching one of the Image objects that referenced the Annotation and an additional attribute:

• Angle

Warning

Limitation - although the IDs of any Image in the file would not survive import into OMERO, the linkages between these images could be maintained by adding the SpimSet annotation to each Image, as in the example below. Once imported, the single XML annotation would be linked to the imported images.

<Image ID="Image:0">
…
    <SA:AnnotationRef ID="Annotation:SpimSet:1"/>
</Image>
<Image ID="Image:1">
…
    <SA:AnnotationRef ID="Annotation:SpimSet:1"/>
</Image>

<SA:XMLAnnotation ID="Annotation:SpimSet:1" Namespace="ome-xml.org:additions:post2010-06:spim:set">
    <SA:Value>
        <OME-Extra:SpimSet xmlns:OME-Extra="http://www.openmicroscopy.org/Schemas/Additions/2010-10">
            <SpimImage ID="Image:0" Angle="0"/>
            <SpimImage ID="Image:1" Angle="45"/>
        </OME-Extra:SpimSet>
    </SA:Value>
</SA:XMLAnnotation>

Custom system values

At the time this was proposed, most SPIM systems were prototypes using custom software to drive them. If these systems required additional values to be stored in the file that do not fit within the above expansion of the OME model, then they should use their own Annotation, probably an XML annotation and define their own annotation namespace to use. This would be read and imported (and upgraded) into Bio-Formats and OMERO like any other annotation.

Sample

A hand written sample file is available that illustrates how the data can be structured. It is an OME-XML file but the broad structure of the metadata is the same for an OME-TIFF.

2010-06/spim.ome.xml

This file defines an instrument with multiple light sources and objectives.

<Instrument ID="Instrument:SpimSampleMicroscope1">
…
<LightSource ID="LightSource:1" Model="Laser Mk1" Manufacturer="OME-Sample"
            SerialNumber="LASER-1">
…
<Objective ID="Objective:TubeLens:1" Manufacturer="OME-Sample"
            Model="OME - Tube lens 120 mm Mk1"/>

There are four image nodes each representing one SPIM angle.

<Image ID="Image:0" Name="Spim Sample Tile 1 Angle 1">
…
<Image ID="Image:1" Name="Spim Sample Tile 2 Angle 1">
…
<Image ID="Image:2" Name="Spim Sample Tile 1 Angle 2">
…
<Image ID="Image:3" Name="Spim Sample Tile 2 Angle 2">

They are connected together using a SpimSet annotation.

<SA:XMLAnnotation ID="Annotation:SpimSet:1" Namespace="ome-xml.org:additions:post2010-06:spim:set">

Each image contains two channels, one named ‘Autoflouresence’, and one named ‘Green-OME’.

<Channel ID="Channel:0.0" Fluor="Autofluorescence" Color="-1"/>
<Channel ID="Channel:0.1" Fluor="Green-OME" Color="16711935"/>

Each image has 2 timepoints and two z-sections and is a small 6 pixel x 4 pixel image. This allows the BinData to be very small to allow you to focus on the file structure.

<Pixels DimensionOrder="XYCZT" ID="Pixels:0:0" PhysicalSizeX="10000.0"
    PhysicalSizeY="10000.0" PhysicalSizeZ="0.0" Type="uint8" SizeC="2" SizeT="2" SizeX="6"
    SizeY="4" SizeZ="2">
…
<Bin:BinData BigEndian="false" Length="32"
    >/wCrzur//wB5oMPi/wBIbJO3AP8ePGCF</Bin:BinData>

There are extra annotations for the stage positions for each image and the extra objective attributes for each objective.

<SA:XMLAnnotation ID="Annotation:ExtraStageLabel:1:0"
…
<SA:XMLAnnotation ID="Annotation:ExtraStageLabel:1:1"
…
<SA:XMLAnnotation ID="Annotation:ExtraStageLabel:1:2"
…
<SA:XMLAnnotation ID="Annotation:ExtraStageLabel:1:3"
…
<SA:XMLAnnotation ID="Annotation:ObjectiveAdditions:1"

The file is valid and can be opened with OMERO.importer and Bio-Formats.