OMERO Zarr Pixel Buffer

Requirements

• OMERO 5.6+
• Java 11+
• libblosc 1.9.0 or later

Artifacts

The latest artifacts built and deployed by GitHub actions can be found on the Glencoe Software artifactory

Installation

The OMERO Zarr pixel buffer follows the principles of a classical OMERO.server service extension. It can be included in an OMERO deployment:

• either by adding the JAR file and all its dependencies (jzarr, caffeine, s3fs, aws-java-sdk-s3, tika-core) under the lib/server directory of OMERO.server and restarting the server,

• or by building a modified version of the OMERO.server binary after declaring com.glencoesoftware.omero:omero-zarr-pixel-buffer as a dependency of the Ivy build system.

Usage

The pixel buffer can read Zarr data generated by the bioformats2raw utility and meeting the following requirements:

• the Zarr dataset must be conformant with the Zarr v2 specification and the version 0.4 of the NGFF specification
• the image (or label image) must have between 2 and 5 declared dimensions of type space, channel or time. Supported dimensions are: (y, x), (t, y, x), (c, y, x), (z, y, x), (t, c, y, x), (t, z, y, x), (c, z, y, x) and (t, c, z, y, x)
• the resolution levels must be downsampled alongside the spatial dimensions, either alongside the (y, x) or the (z, y, x) axes
• the scaling factor alongside both the y and the x axes between successive resolution levels must be equal to two

An OMERO Image or Mask object can be associated to Zarr by setting its ExternalInfo with the following properties:

• entityType must be set to com.glencoesoftware.ngff:multiscales

• entityId must be set to 3

• lsid must be set to the path of the Zarr group describing the multiscales image or the label image:

  • either the absolute path to the multiscales group if the Zarr is stored on the filesystem e.g. /data/CMU-1.ome.zarr/0,
  • or the URI specifying the location of the multiscales group if the Zarr is stored on AWS S3 or S3 compatible storage. The location must be specified as s3://<endpoint>/<bucket>/<prefix> where <endpoint> is the S3 endpoint - see https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region for the list of the regional AWS S3 endpoints, is the bucket name and <prefix> is the prefix to the Zarr group containing the multiscales image e.g. s3://s3.us-east-1.amazonaws.com/gs-public-zarr-archive/CMU-1.ome.zarr/0. The URI stored in the lsid attribute must be percent-encoded as defined in RFC3986.

When reading Zarr data from a S3 location, the pixel buffer will look for credentials in the following order to make authenticated requests:

1. the credentials profiles file, typically located at ~/.aws/credentials and shared by many AWS SDKs and the AWS CLI,
2. the instance profile credentials for Amazon EC2 instances configured with a policy allowing to assume an IAM role.

If a credentials profiles file is found, the default profile will be loaded and used for authentication. A different named profile can be used by appending the profile query parameter to the location URI e.g. s3://<endpoint>/<bucket>/<key>?profile=<profile>.

To read public Zarr data hosted on S3 using anonymous (unsigned) requests, the anonymous=true query parameter must be appended to the location URI e.g. s3://s3.us-east-1.amazonaws.com/gs-public-zarr-archive/CMU-1.ome.zarr/0?anonymous=true. Note profile and anonymous are mutually incompatible query parameters.

The ExternalInfo of an Image or a Mask can be accessed and set using the OMERO API directly, the OMERO CLI (omero obj [ext-info-set|ext-info-get]) or a client including the functionality to import OME-Zarr labels and/or images.

Development

Clone the repository:

git clone https://github.com/glencoesoftware/omero-zarr-pixel-buffer

Run the Gradle build including the tests

./gradlew build

License

OMERO Zarr pixel buffer is distributed under the terms of the GPL license. Please see LICENSE.txt for further details.