SPIM initial support
====================
.. note::
This approach is still valid but has been **superseded** by the
:doc:`/developers/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
:doc:`tiled-images`).
This solution used StageLabel and the Position values on Plane to
record the location and arrangement of the individual tiles.
::
…
…
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.
::
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.
::
…
Extra attribute values for the objective objects.
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 ```` 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.
::
…
…
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.
:image_downloads:`2010-06/spim.ome.xml `
This file defines an instrument with multiple light sources and
objectives.
::
…
…
There are four image nodes each representing one SPIM angle.
::
…
…
…
They are connected together using a SpimSet annotation.
::
Each image contains two channels, one named 'Autoflouresence', and one
named 'Green-OME'.
::
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.
::
…
/wCrzur//wB5oMPi/wBIbJO3AP8ePGCF
There are extra annotations for the stage positions for each image and
the extra objective attributes for each objective.
::