Edit me

Supported image types

Images are diverse

We intuitively think of an image file as a digital photograph, similar in appearance to human vision, containing a matrix of RGB or grayscale pixels.

In reality, images come in diverse form: varying in dimension, number of channels, color depth and type, whether pixel-sizes are uniform in all dimensions, and in many other respects.

And when encoded onto a filesystem, file formats vary widely also with different encodings, types of compression, proprietary codes, and metadata.

Image types supported in Anchor

Anchor supports much, but not all, of this diversity:

  • 2D/3D rectangular images with arbitrary number of channels and pixel-size (anisotropy).
  • diverse bit depths: unsigned 8-bit, unsigned 16-bit, unsigned 32-bit and floating point.
  • time-series and other indexed forms of images in a limited way.
  • certain forms of metadata (pixel size, channel names) but not others.
  • Anchor-specific data structures for:
    • object-segmentations (pixel subregions, encoded into HDF5)
    • geometric shapes (useful for shape annotations).

What’s not supported

Images containing the following are not yet supported:

  • transparency
  • pyramidal formats (containing multiple scaled-down versions for quick access at scale)
  • point clouds

Reading and writing image formats

A flexible method of reading and writing different file-formats is provided through customizable classes for reading and writing images, inheriting from StackReader and StackWriter respectively.

Specifying image file extensions

By default anchor, searches for image-files by comparing file-extensions against those in defaultInputExtensions.xml:

  • $ANCHOR_HOME/config/defaultInputExtensions.xml in the main Anchor distribution.

Specifying default readers and writers

The default readers and writers are set in defaultBeans.xml configuration-files, found at:

  • $ANCHOR_HOME/config/defaultBeans.xml in the main Anchor distribution, and
  • $USER_HOME/.anchor/defaultBeans.xml optionally, taking precedence.

In practice, these readers and writers are usually implemented via hierarchies of rules that select an appropriate driver for a particular type of image, based upon whether its 2D/3D, the number of channels, bit depth etc.

The user may also suggest a preferred file format for writing via the -of command-line-option. See the Converting and manipulating images for example usage.

Reading images

By default, the following logic decides which reader is used for an image file:

Condition Reader Supported Formats
.bmp extension OpenCVReader BMP
.jpg or .jpeg extension BioformatsReader JPEG (auto-adjusted to any EXIF orientation)
anything else BioformatsReader approximately 150 supported formats

See the StackReader section of defaultBeans.xml for the exact configurable rules.

Multi-file driver

Another driver, the MultiFileReader virtually combines different files into a single image (as varying channels, or varying z-stacks in a 3D image, or varying timepoints in a time-series). A regular-expression is used to match file-paths.

Helper utility drivers

Other drivers in org.anchoranalysis.plugin.io.bean.rasterreader provide useful utility functions:

Class Function
FlattenAsChannel Converts indexed/time-series images into different channels.
ImposeResolution Imposes a specific physical pixel size (across X,Y,Z dimensions).
ReadVoxelExtentXml Reads physical pixel-size from an accompanying .xml file for each image.
RejectIfConditionXYResolution Rejects images if a condition is filled on the X-Y resolution.

Writing images

By default, the following logic decides which writer is used for an image:

Image Type Writer Reason
Binary 2D PNG via ImageJ Avoids compression artefacts.
Binary 3D Tiff via Bioformats Like above, but can save 3D images.
*RGB or Grayscale 2D PNG via ImageJ Widely-supported and lossless compression.
RGB or Grayscale 3D Tiff via Bioformats Can save 3D images as multi-frame.
*Three-channels but not RGB Tiff via Bioformats Can save three channels independently.
anything else OMETiff via Bioformats Supports diverse image types.

Binary images are stored as unsigned 8-bit but with only 0 and 255 as valid states.

In the two asterixed cases, if a -of command-line-option is supplied, a matching writer for this format will be found and instead used, but only if one is available and supports the image-type.

See the StackWriter section of defaultBeans.xml for the exact configurable rules.