Open Microscopy Environment OME XML Schema April 2011 Author: Ilya G. Goldberg, Andrew J Patterson Copyright (C) 2002-2011 Open Microscopy Environment The OME element is a container for all information objects accessible by OME. These information objects include descriptions of the imaging experiments and the people who perform them, descriptions of the microscope, the resulting images and how they were acquired, the analyses performed on those images, and the analysis results themselves. An OME file may contain any or all of this information. With the creation of the Metadata Only Companion OME-XML and Binary Only OME-TIFF files the top level OME node has changed slightly. It can EITHER: Contain all the previously expected elements OR: Contain a single BinaryOnly element that points at its Metadata Only Companion OME-XML file. Pointer to an external metadata file. If this element is present, then no other metadata may be present in this file, i.e. this file is a place-holder. Filename of the OME-XML metadata file for this binary data. If the file cannot be found, a search can be performed based on the UUID. The unique identifier of another OME-XML block whose metadata describes the binary data in this file. This UUID is considered authoritative regardless of mismatches in the filename. This unique identifier is used to keep track of multi part files. It allows the links between files to survive renaming. While OPTIONAL in the general case this is REQUIRED in a MetadataOnly Companion to a collection of BinaryOnly files. This is the name of the creating application of the OME-XML and preferably its full version. e.g "CompanyName, SoftwareName, V2.6.3456" This is optional but we hope it will be set by applications writing out OME-XML from scratch. This element describes the actual image and its meta-data. The elements that are references (ending in Ref or Settings) refer to elements defined outside of the Image element. Ref elements are simple links, while Settings elements are links with additional values. If any of the required Image attributes or elements are missing, its guaranteed to be an invalid document. The required attributes and elements are ID and Pixels. ExperimenterRef is required for all Images with well formed LSIDs. ImageType is a vendor-specific designation of the type of image this is. Examples of ImageType include 'STK', 'SoftWorx', etc. The Name attributes are in all cases the name of the element instance. In this case, the name of the image, not necessarily the filename. PixelSize* is in microns[um]. The acquisition date of the Image. The element contains a string in the ISO 8601 dateTime format (i.e. 1988-04-07T18:39:09) A description for the image. [plane text multi-line string] The Image will be unreadable if any of the required Pixel attributes are missing. The Pixels themselves are stored within the file compressed by plane, and encoded in Base64. The Pixels element must contain a list of BinData, each containing a single plane of pixels. These Pixels elements, when read in document order, must produce a 5-D pixel array of the size specified in this element, and in the dimension order specified by 'DimensionOrder'. The order in which the individual planes of data are interleaved. The variable type used to represent each pixel in the image. Dimensional size of pixel data array [units:none] Dimensional size of pixel data array [units:none] Dimensional size of pixel data array [units:none] Dimensional size of pixel data array [units:none] Dimensional size of pixel data array [units:none] Physical size of a pixel in microns[um]. Physical size of a pixel in microns[um]. Physical size of a pixel in microns[um]. TimeIncrement is used for time series that have a global timing specification instead of per-timepoint timing info. For example in a video stream. The unit is seconds[s]. The Plane object holds microscope stage and image timing data for a given channel/z-section/timepoint. This optional element is a hash of the plane's image data. It is a choice between all the support hash types. Currently the only method supported is SHA1. The Z-section this plane is for. [units:none] This is numbered from 0. The timepoint this plane is for. [units:none] This is numbered from 0. The channel this plane is for. [units:none] This is numbered from 0. Units are seconds since the beginning of the experiment [s] Units are seconds [s] The X position of the stage. [units are in the microscope reference frame] The Y position of the stage. [units are in the microscope reference frame] The Z position of the stage. [units are in the microscope reference frame] There must be one per channel in the Image, even for a single-plane image. And information about how each of them was acquired is stored in the various optional *Ref elements. Each Logical Channel is composed of one or more ChannelComponents. For example, an entire spectrum in an FTIR experiment may be stored in a single Logical Channel with each discrete wavenumber of the spectrum constituting a ChannelComponent of the FTIR Logical Channel. An RGB image where the Red, Green and Blue components do not reflect discrete probes but are instead the output of a color camera would be treated similarly - one Logical channel with three ChannelComponents in this case. The total number of ChannelComponents for a set of pixels must equal SizeC. The IlluminationType attribute is a string enumeration which may be set to 'Transmitted', 'Epifluorescence', 'Oblique', or 'NonLinear'. The PhotometricInterpretation attribute is used to describe how to display a multi-component channel. This attribute may be set to: 'monochrome', 'RGB', 'ARGB', 'CMYK', 'HSV'. The default for single-component channels is 'monochrome'. The user interface logic for labeling a given channel for the user should use the first existing attribute in the following sequence: Name -> Fluor -> EmissionWavelength -> ChannelComponent/Index. A name for the channel that is suitable be presented to the user. The number of samples the detector takes to form each pixel value. The SamplesPerPixel attribute is the number of channel components in the logical channel. [units:none] The method of illumination used to capture the channel. The optional PinholeSize attribute allows specifying adjustable pin hole diameters for confocal microscopes (units microns[um]). AcquisitionMode describes the type of microscopy performed for each channel ContrastMethod describes the technique used to achieve contrast for each channel Excitation wavelength of excitation for a particular channel, in nanometres[nm]. Emission wavelength of excitation for a particular channel, in nanometres[nm]. The Fluor attribute is used for fluorescence images. This is the name of the fluorophore used to produce this channel [plain text string] The NDfilter attribute is used to specify the combined effect of any neutral density filters used. [units optical density expressed as a PercentFraction] The PockelCellSetting used for this channel. This is the amount the polarization of the beam is rotated by. [units:none] A color used render this channel - encoded as RGBA The default value "-2147483648" is #FFFFFFFF so solid white (it is a signed 32 bit value) This place holder means there is on pixel data in this file. This described the location of the pixel data in a tiff file. This must be used when the IFDs are located in another file. Note: It is permissible for this to be self referential. This can be used when the IFDs are located in another file. The / (forward slash) is used as the path separator. A relative path is recommended. However an absolute path can be specified. Default is to use the file the ome-xml data has been pulled from. Note: It is permissible for this to be self referential. The file image1.tiff may contain ome-xml data that has FilePath="image1.tiff" or "./image1.tiff" Gives the IFD(s) for which this element is applicable. Indexed from 0. Default is 0 (the first IFD). [units:none] Gives the Z position of the image plane at the specified IFD. Indexed from 0. Default is 0 (the first Z position). [units:none] Gives the T position of the image plane at the specified IFD. Indexed from 0. Default is 0 (the first T position). [units:none] Gives the C position of the image plane at the specified IFD. Indexed from 0. Default is 0 (the first C position). [units:none] Gives the number of IFDs affected. Dimension order of IFDs is given by the enclosing Pixels element's DimensionOrder attribute. Default is the number of IFDs in the TIFF file, unless an IFD is specified, in which case the default is 1. [units:none] The StageLabel is used to specify a name and position for a stage position in the microscope's reference frame. The X position of the stage label. [units are in the microscope reference frame] The Y position of the stage label. [units are in the microscope reference frame] The Z position of the stage label. [units are in the microscope reference frame] Defines a microbeam operation type and the region of the image it was applied to. The LightSourceRef element is a reference to a LightSource specified in the Instrument element which was used for a technique other than illumination for the purpose of imaging. For example, a laser used for photobleaching. A description for the Microbeam Manipulation. [plane text multi-line string] The type of manipulation performed. This element describes the instrument used to capture the Image. It is primarily a container for manufacturer's model and catalog numbers for the Microscope, LightSource, Detector, Objective and Filters components. Additionally, one or more OTF elements may be specified, describing the optical transfer function under different conditions. The Objective element contains the additional elements LensNA and Magnification. The Filters element can be composed either of separate excitation, emission filters and a dichroic mirror or a single filter set. Within the Image itself, a reference is made to this one Filter element. The OTF element contains an optical transfer function. The same OTF can be used for all wavelengths, or there may be one per wavelength. There may be multiple light sources, detectors, objectives and filters on a microscope. Each of these has their own ID attribute, which can be referred to from Channel. It is understood that the light path configuration can be different for each channel, but cannot be different for each timepoint or each plane of an XYZ stack. The microscope's manufacturer specification. NOTE: OTF is DEPRECATED as it is due to be removed. No objections were received in reply to: http://lists.openmicroscopy.org.uk/pipermail/ome-devel/2011-April/001931.html The optical transfer function. FilterSetRef refers to the set of filters used in computing the OTF. This element must contain a BinData element containing the Base64-encoded OTF. These work the same way as they do for the Data element within Image. The variable type used to specify the size of pixel the OTF is for designed for. The OpticalAxisAveraged is a boolean specifying whether or not optical axis averaging was done. [flag] The width of the OTF. [units:none] The height of the OTF. [units:none] This describes the environment that the biological sample was in during the experiment. The Temperature is in Celsius[C]. AirPressure is in millibars[mbar]. Humidity around the sample [units:none] A fraction, as a value from 0.0 to 1.0. Carbon Dioxide concentration around the sample [units:none] A fraction, as a value from 0.0 to 1.0. The Project ID is required. Datasets can be grouped into projects using a many-to-many relationship. A Dataset may belong to one or more Projects by including one or more ProjectRef elements which refer to Project IDs. Projects do not directly contain images - only by virtue of containing datasets, which themselves contain images. A description for the project. [plane text multi-line string] The Group ID is required. Contact information should be specified for the leader of the group and a contact person. The Leader and/or Contact are themselves experimenters. A description for the group. [plane text multi-line string] Contact information for a Group leader specified using a reference to an Experimenter element defined elsewhere in the document. The Contact element describes the contact person for a group of experimenters - typically a project leader or lab manager. This person is specified as a reference to an OME experimenter. An element specifying a collection of images that are always processed together. Images can belong to more than one Dataset, and a Dataset may contain more than one Image. Images contain one or more DatasetRef elements to specify what datasets they belong to. Once a Dataset has been processed in any way, its collection of images cannot be altered. The ExperimenterRef and GroupRef elements specify the person and group this Dataset belongs to. Projects may contain one or more Datasets, and Datasets may belong to one or more Projects. This relationship is specified by listing ProjectRef elements within the Dataset element. A description for the dataset. [plane text multi-line string] A name for the dataset that is suitable be presented to the user. This element describes the type of experiment. The required Type attribute must contain one or more entries from the following list: FP FRET Time-lapse 4-D+ Screen Immunocytochemistry FISH Electrophysiology Ion-Imaging Colocalization PGI/Documentation FRAP Photoablation Optical-Trapping Photoactivation Fluorescence-Lifetime Spectral-Imaging Other FP refers to fluorescent proteins, PGI/Docuemntation is not a 'data' image. The optional Description element may contain free text to further describe the experiment. A description for the experiment. [plane text multi-line string] This is a link to the Experimenter who conducted the experiment A term to describe the type of experiment. This element describes a person who performed an imaging experiment. This person may also be a user of the OME system, in which case the UserName element contains their login name. Experimenters may belong to one or more groups which are specified using one or more GroupRef elements. This is the only required name field. [plain text string] First name, sometime called christian name or given name or forename. [plain text string] Any other names. [plain text string] A person's last name sometimes called surname or family name. [plain text string] A person's email address. [valid email address as string] A person's Institution The organizing structure that people belong to other than groups. A university, or company, etc. We do not specify a department element, and do not mean for Institution to be used in this way. We simply wish to say XXX at YYY. Where YYY has a better chance of being tied to a geographically fixed location and of being more recognizable than a group of experimenters. [plain text string] This is the username of the experimenter (in a 'unix' or 'database' sense). [plain text string] abstract This is the base from which many microscope components are extended. E.g Objective, Filter etc. Provides attributes for recording common properties of these components such as Manufacturer name, Model etc, all of which are optional. The manufacturer of the component. [plain text string] The Model of the component. [plain text string] The serial number of the component. [plain text string] The lot number of the component. [plain text string] Binary contents coded in hexadecimal (20 characters long) A simple type that restricts the value to an integer between 0 and 9223372036854775807 (inclusive). A simple type that restricts the value to an integer between 0 and 2,147,483,647 (inclusive). A simple type that restricts the value to an integer between 1 and 2,147,483,647 (inclusive). A simple type that restricts the value to a float between >0 and max 32-bit float {i.e. (2−2^-23) × 2^27 ≈ 3.4 × 10^38} A simple type that restricts the value to a float between 0 and 1 (inclusive). This is a unique ID for the file but does not conform to the ID pattern used in the rest of the file. The rest of the IDs are either an full LSID or an internal ID which is a string that is simply unique in this file. As the UniversallyUniqueIdentifier is used from outside this file to identify it having the same ID in another file could cause problems. A UUID is 32 hexadecimal digits, in 5 groups, 8-4-4-4-12, separated by hyphens e.g. urn:uuid:3e450fae-b8f2-4d35-aa54-702168b2487f There are methods to generate these in most modern languages. http://www.ietf.org/rfc/rfc4122.txt The number size/kind used to represent a pixel A description of the microscope's objective lens. Required elements include the lens numerical aperture, and the magnification, both of which a floating point (real) numbers. The values are those that are fixed for a particular objective: either because it has been manufactured to this specification or the value has been measured on this particular objective. Correction: This is the type of correction coating applied to this lens. Immersion: This is the types of immersion medium the lens is designed to work with. It is not the same as 'Medium' in ObjectiveRef (a single type) as here Immersion can have compound values like 'Multi'. LensNA: The numerical aperture of the lens (as a float) NominalMagnification: The specified magnification e.g. x10 CalibratedMagnification: The measured magnification e.g. x10.3 WorkingDistance: WorkingDistance of the lens. The Units are microns[um]. The correction applied to the lens The immersion medium the lens is designed for The numerical aperture of the lens expressed as a floating point (real) number. Expected range 0.02 - 1.5 [units:none] The magnification of the lens as specified by the manufacturer - i.e. '60' is a 60X lens. [units:none] The magnification of the lens as measured by a calibration process- i.e. '59.987' for a 60X lens. [units:none] The working distance of the lens expressed as a floating point (real) number. Units are microns[um]. Records whether or not the objective was fitted with an Iris. [flag] The type of detector used to capture the image. The Detector ID can be used as a reference within the Channel element in the Image element. Each attribute now has an indication of what type of detector it applies to. This is preparatory work for cleaning up and possibly splitting this object into sub-types. The Detector Gain for this detector, as a float. [units:none] {used:CCD,EMCCD,PMT} The Voltage of the detector (e.g. PMT voltage) as a float. volts[V] {used:PMT} The Detector Offset. [units:none] {used:CCD,EMCCD} The Zoom or "Confocal Zoom" or "Scan Zoom" for a detector. [units:none] {used:PMT} Gain applied to the detector signal. This is the electronic gain (as apposed to the inherent gain) that is set for the detector. [units:none] {used:EMCCD#EMGain} The Type of detector. E.g. CCD, PMT, EMCCD etc. Filter set manufacturer specification The Filters placed in the Excitation light path. The Filters placed in the Emission light path. A filter is either an excitation or emission filters. There should be one filter element specified per wavelength in the image. The channel number associated with a filter set is specified in Channel. It is based on the FilterSpec type, so has the required attributes Manufacturer, Model, and LotNumber. It may also contain a Type attribute which may be set to 'LongPass', 'ShortPass', 'BandPass', 'MultiPass', 'Dichroic', 'NeutralDensity', or 'Other'. It can be associated with an optional FilterWheel - Note: this is not the same as a FilterSet A filter 'wheel' in OME can refer to any arrangement of filters in a filter holder of any shape. It could, for example, be a filter slider. [plain text string] This records the range of wavelengths that are transmitted by the filter. It also records the maximum amount of light transmitted. CutIn is the wavelength below which there is less than 50% transmittance for a filter. Units: nanometres[nm]. CutOut is the wavelength above which there is less than 50% transmittance for a filter. Units: nanometres[nm]. CutInTolerance Units: nanometres[nm], CutOutTolerance Units: nanometres[nm], The amount of light the filter transmits at a maximum [units:none] A fraction, as a value from 0.0 to 1.0. The dichromatic beamsplitter or dichroic mirror used for this filter combination. A description of the light path The Filters placed in the Excitation light path. The Filters placed in the Emission light path. abstract-proprietary The lightsource for the instrument. An instrument may have several light sources. The type of lightsource is specified by one of the child-elements which are 'Laser', 'Filament', 'Arc' or 'LightEmittingDiode'. Each of the light source types has its own Type attribute to further differentiate the light source (eg, Nd-YAG for Laser or Hg for Arc). A LightSource ID must be specified for each light source, and the individual light sources can be referred to by their LightSource IDs (eg from Channel). The light-source power. units milliwatts[mW] Laser types are specified using two attributes - the Type and the LaserMedium. The Laser element may contain a Pump sub-element which refers to a LightSource used as a laser pump. Type is the general category of laser. The Medium attribute specifies the actual lasing medium for a given laser type. The Wavelength of the laser in nanometres[nm] FrequencyMultiplication that may be specified. [units:none] Whether or not the laser is Tuneable [flag] The Pulse mode of the laser. If true the laser has a PockelCell to rotate the polarization of the beam. [flag] The is the rate in Hz at which the laser pulses if the Pulse type is 'Repetitive'. hertz[Hz] The Arc element is used to describe various kinds of Arc lamps - Hg, Xe, HgXe. The Power of the Arc is now stored in the LightSource. The type of Arc lamp. The Filament element is used to describe various kinds of filament bulbs such as Incadescent or Halogen. The Power of the Filament is now stored in the LightSource. The type of filament. The LightEmittingDiode element is used to describe various kinds of LED lamps. As the LightEmittingDiode is inside a LightSource it already has available the values from ManufacturerSpec (Manufacturer, Model, SerialNumber, LotNumber) And the values from LightSource which includes Power in milliwatts We have looked at extending this element but have had a problem producing a generic solution. Possible attributes talked about adding include: Power in lumens - but this is complicated by multi-channel devices like CoolLED where each channel's power is different Wavelength Range - not a simple value so would require multiple attributes or a child element Angle of Projection - this would be further affected by the optics used for filtering the naked LED or that combine power from multiple devices These values are further affected if you over-drive the LED resulting in a more complex system Another issue is that LED's may not be used directly for illumination but as drivers for secondary emissions from doped fiber optics. This would require the fiber optics to be modeled. Thanks to Paul Goodwin of Applied Precision of information about this topic. The Pump element is a reference to a LightSource. It is used within the Laser element to specify the light source for the laser's pump (if any). abstract Reference is an empty complex type that is contained and extended by all the *Ref elements and also the Settings Complex Type Each *Ref element defines an attribute named ID of simple type *ID and no other information Each simple type *ID is restricted to the base type LSID with an appropriate pattern There may be one or more of these in a Dataset. This empty element has a required Project ID attribute that refers to Projects defined within the OME element. This empty element has a required Experimenter ID and an optional DocumentID attribute which refers to one of the Experimenters defined within OME. This empty element has a reference (the Group ID attribute) to a Group defined within OME. This empty element can be used (via the required Instrument ID attribute) to refer to an Instrument defined within OME. The DatasetRef element refers to a Dataset by specifying the Dataset ID attribute. One or more DatasetRef elements may be listed within the Image element to specify what Datasets the Image belongs to. abstract Settings is an empty complex type that is contained and extended by all the *Settings elements Each *Settings element defines an attribute named ID of simple type *ID and the other information that is needed. Each simple type *ID is restricted to the base type LSID with an appropriate pattern The Attenuation of the light source [units:none] A fraction, as a value from 0.0 to 1.0. The Wavelength of the light source. nanometres[nm] This holds the setting applied to a detector as well as a reference to the detector. The ID is the detector used in this case. Each attribute now has an indication of what type of detector it applies to. This is preparatory work for cleaning up and possibly splitting this object into sub-types. The Offset of the detector. [units none] {used:CCD,EMCCD} The Gain of the detector. [units:none] {used:CCD,EMCCD,PMT} The Voltage of the detector. volts[V] {used:PMT} The speed at which the detector can count pixels. {used:CCD,EMCCD} Units of ReadOutRate is MHz. This is the bytes per second that can be read from the detector (like a baud rate). megahertz[MHz] Represents the number of pixels that are combined to form larger pixels. {used:CCD,EMCCD} This holds the setting applied to an objective as well as a reference to the objective. The ID is the objective used in this case. The CorrectionCollar is it normal an adjustable ring on the objective. Each has an arbitrary scale on it so the values is unit-less. [units:none] A description of a Medium used for the lens. The Medium is the actual immersion medium used in this case. The RefractiveIndex is that of the immersion medium. This is a ratio so it also unit-less. [units:none] Either LSID or internal consistent IDs for the file See: http://www.openmicroscopy.org/site/support/file-formats/working-with-ome-xml/id-and-lsid