OME-TIFF n-pages versus bands swapped?

[tomouellette]

Hi there,

So I'm using the C++ bindings to read in OME-TIFF images. My understanding is the current OME-TIFF specification assigns the following dimensions: XYZCT. When I read in a 3-channel OME-TIFF sample image (https://downloads.openmicroscopy.org/images/OME-TIFF/2016-06/bioformats-artificial/multi-channel.ome.tif) I currently see that the channels are assigned to n-pages and not bands.

Should I assume that the default for libvips is to assign the volumetric (Z) dimension to bands and channels to n-pages, or is this unexpected behaviour? I couldn't find anything noting this in the documentation.

Here's some output:

Metadata printed using the C++ API:

height: 167
width: 439
bands: 1
interpretation: B_W
format: CHAR
n-pages: 3

Description: <?xml version="1.0" encoding="UTF-8"?><!-- Warning: this comment is an OME-XML metadata block, which contains crucial dimensional parameters and other important metadata. Please edit cautiously (if at all), and back up the original data before doing so. For more information, see the OME-TIFF web site: http://www.openmicroscopy.org/site/support/ome-model/ome-tiff/. --><OME xmlns="http://www.openmicroscopy.org/Schemas/OME/2016-06" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" Creator="OME Bio-Formats 5.2.2" UUID="urn:uuid:bebd2be7-8253-4b90-be93-4df567ffe1be" xsi:schemaLocation="http://www.openmicroscopy.org/Schemas/OME/2016-06 http://www.openmicroscopy.org/Schemas/OME/2016-06/ome.xsd"><Image ID="Image:0" Name="multi-channel.ome.tif"><Pixels BigEndian="true" DimensionOrder="XYZCT" ID="Pixels:0" SizeC="3" SizeT="1" SizeX="439" SizeY="167" SizeZ="1" Type="int8"><Channel ID="Channel:0:0" SamplesPerPixel="1"><LightPath/></Channel><Channel ID="Channel:0:1" SamplesPerPixel="1"><LightPath/></Channel><Channel ID="Channel:0:2" SamplesPerPixel="1"><LightPath/></Channel><TiffData FirstC="0" FirstT="0" FirstZ="0" IFD="0" PlaneCount="1"><UUID FileName="multi-channel.ome.tif">urn:uuid:bebd2be7-8253-4b90-be93-4df567ffe1be</UUID></TiffData><TiffData FirstC="1" FirstT="0" FirstZ="0" IFD="1" PlaneCount="1"><UUID FileName="multi-channel.ome.tif">urn:uuid:bebd2be7-8253-4b90-be93-4df567ffe1be</UUID></TiffData><TiffData FirstC="2" FirstT="0" FirstZ="0" IFD="2" PlaneCount="1"><UUID FileName="multi-channel.ome.tif">urn:uuid:bebd2be7-8253-4b90-be93-4df567ffe1be</UUID></TiffData></Pixels></Image></OME>

Metadata printed using vipsheader:

multi-channel.ome.tif: 439x167 char, 1 band, b-w, tiffload
width: 439
height: 167
bands: 1
format: char
coding: none
interpretation: b-w
xoffset: 0
yoffset: 0
xres: 0
yres: 0
filename: /Users/tomouellette/Downloads/multi-channel.ome.tif
vips-loader: tiffload
n-pages: 3
image-description: <?xml version="1.0" encoding="UTF-8"?><!-- Warning: this comment is an OME-XML metadata block, which contains crucial dimensional parameters and other important metadata. Please edit cautiously (if at all), and back up the original data before doing so...
resolution-unit: cm
bits-per-sample: 8
orientation: 1

[jcupitt]

Hello @tomouellette,

The libvips TIFF reader is a general one, with only a few additions to make working with OME-TIFF easier. Since it tries to give you exactly what's in the TIFF file, you need to know how OME-TIFF images are encoded.

OME-TIFF images are all one band, and they use the pages dimension to store extra bands. Pyramids are stored in sub-ifd levels off each page. They do this because many microscopes have different cameras for different modalities, so you can't be sure different channels will have the same number of pixels in each direction.

The tiffinfo utility is very handy for seeing the internal structure of a TIFF file.

When reading OME-TIFF with libvips the best strategy is to open page 0 and get the IMAGEDESCRIPTION XML. Parse that and figure out which channels (bands, pages, etc.) you want to load as a group. libvips needs all bands in an image to have the same pixel dimensions, so (for example) you may find you need to upscale some of the fluorescence bands before you can load them, or you might prefer to load them as a separate image. You can almost always load RGB as a set, fortunately.

You can load a set of consecutive pages of the same size with eg. (using python for brevity):

ome = pyvips.Image.new_from_file("xxx.ome.tiff", page=2, n=3)

Then split that to a set of pages and join them bandwise.

pages = ome.pagesplit()
image = pages[0].bandjoin(pages[1:])

Finally, tag the image as being RGB with:

image = image.copy(interpretation="srgb")

This works well for volumetric OME-TIFF too, though you should probably tag them as multiband.

[tomouellette]

Thanks for the detailed response. This is very helpful!