Improve the resolution descriptions of the imgData endpoint

[sbesson]

Bio-Formats and OMERO introduced the ability to work natively with multi-resolution file formats 12 years ago. See notably the PR introducing the sub-resolution API in Bio-Formats ¹ and in OMERO ². In OMERO.web in particular, the return value of PixelBuffer.getResolutionDescriptions() is getting converted into a 1D array of floating point values representing the zoom level scaling computed as the ratio of the sizeX for the current resolution divided by the sizeX of the largest resolution and this zoomLevelScaling list is exposed in the webclient/imgData endpoint of OMERO.web ³.

The approach above has been working quite successfully for the last 12 years and provides an simple representation of the resolution levels available for a given image. In the scenario where the image is downsampled uniformly according to a scale factor without rounding issues e.g. [48000,24000], [12000,6000], [3000,1500], [750,375], this 1D representation is sufficient.
However we have been recently exposed to limitations of this representation in the scenarios where:

• the ratio between zoom level can be represented exactly as a decimal number e.g. scaleFactor of 3 or dimensions that do not divide exactly into an integer
• there is some anisotropy in the X vs Y downsampling for certain resolution levels

In these scenarios, computing the sizes of each resolution using the size of the largest resolution (i.e. the sizeX and sizeZ) and the knowledge of the zoomLevelScaling can easily lead to off-by-one (or more) errors in the sizeY ⁴. This is problematic as the computed resolution dimensions are translated into tile requests which in turn exceed the effective dimensions.

From a quick investigation of mathematical workaround, there is no canonical way to fix all scenarios using the current API. Instead a more robust approach would be to update the webclient/imgData endpoint and return a new field that marshals and exposes the fullness of PixelBuffer.getResolutionDescriptions() including the sizes alongside each dimension for each resolution level. If available, clients including the OMERO.web viewers should be able to consume these dimensions directly rather than recomputing them internally and make the appropriate requests

Footnotes

1. https://github.com/ome/bioformats/pull/118 ↩

2. https://github.com/ome/openmicroscopy/pull/634 ↩

3. https://github.com/ome/omero-web/commit/4c8de98a6e24eb671474681729e7d73aa394102f ↩

4. https://github.com/glencoesoftware/qupath-extension-omero-web/issues/8 ↩