User Guide - Supported image formats

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

Note: Remember, in all cases, anchor supports sets of these image-types, rather than processing only single images.

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.

Warning: Caveat emptor. Anchor has been tested so far on a limited subset of these formats.

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.

Tags: