Units of measurement

Since Bio-Formats 5.1 and the adoption of the 2015-01 OME Data Model, the data model and the corresponding Bio-Formats model and metadata APIs have added support for units of measurement. Previously, the units for various properties such as the physical size of an image, stage position, confocal pinhole size, light wavelengths etc. were fixed in the model. This was however somewhat inflexible, and not appropriate for imaging modalities at widely different scales. The solution to this was to add a unit of measurement to each of these properties. The image size, for example, was previously specified to be stored in micrometers but may now be specified in any SI length unit of choice, or one of the supported non-SI length units. This permits the preservation of the unit used by a proprietary file format or used at acquisition time, for example nanometers, millimeters, meters, or inches or thousandths of an inch could be used instead.

At the OME-XML level, the properties continue to use the old attribute names. They are supplemented by an additional attribute with a Unit suffix, for example the PhysicalSizeX attribute and its companion PhysicalSizeXUnit attribute.

At the API level, two classes are used:

Unit<T>
represents a unit system for a given dimension such as length, pressure or time.
Quantity
represents a value and unit in a given unit system; this is subclassed for each of the supported dimensions such as Length, Pressure etc. For example the Length class could represent the value and unit of 5.3 µm and the Pressure class 956 mbar.

All of the model and metadata APIs pass Quantity objects in place of raw numerical values. Updating your code will require replacing the use of raw values with quantities. Where your code needs to deal with the quantity in a specific unit, for example µm, you will need to perform an explicit unit conversion to transform the value to the required unit.

The three situations you will need to deal with are:

  • getting a quantity from a get method in the API
  • converting a quantity to a desired unit
  • setting a quantity with a set method in the API (possibly also requiring the creation of a quantity)

Examples of how to use units and quantities for these purposes are shown in the sections Reading files (ReadPhysicalSize example which uses getPixelsPhysicalSize and also demonstrates unit conversion) and Further details on exporting raw pixel data to OME-TIFF files (setPixelsPhysicalSize).