Add API and implementations to provide axis orientation

[melissalinkert]

See glencoesoftware/bioformats2raw#329 and https://ngff.openmicroscopy.org/rfc/4.

As outlined in glencoesoftware/bioformats2raw#329, this implements a new API that allows readers to provide axis orientation information. Right now, per RFC-4, only anatomical orientation is implemented; the intent is for this API to be flexible enough to support other orientation types in the future, if needed.

Tested on at least one dataset in each format, but unfortunately none are public, and none are true reference datasets where the correct values in RFC-4 terminology are known. Opening this is a non-draft PR to make sure no existing tests break, but once we have reference data (cc @thewtex) this will need more careful testing and possibly some updates as a result.

[thewtex]

We have some testing data here:

https://huggingface.co/fideus-labs/ome-zarr-rfc4-data

still a WIP.

[sbesson]

The API changes and the implementations have been extensively tested in the scope of glencoesoftware/bioformats2raw#335 converting the original data alongside the anatomical metadata exposed by the new API to the development OME-Zarr 0.9.dev1 specification.

The API changes define a new interface that can be implemented by potent readers and allows to associate orientations with a given term and type to image axes. The anatomical orientation is implemented using the vocabulary of RFC-4 with a clear extension mechanism for defining additional orientation types and terms. While this vocabulary is currently defined directly under formats-api, long-term it could certainly be consumed from an upstream component for the NGFF vocabulary, similarly to the enumeration from the OME XSD schema which are currently defined in the ome-xml components. Given the absence of such component, this is outside the scope of this implementation but could possibly lead to a coordinated effort between OME NGFF ORPs.

The latest changes in MINCReader led to one failure in the nightly tests - https://bf-testing-results.s3.amazonaws.com/2026/2026-10-01/ecat7.log and the configuration file will need to be updated with the PhysicalSizeZ of the corresponding sample which is now populated.

Once all tests are passing, I would be in favour of merging this effort into the next release candidate of Bio-Formats 9 and can complete the implementation of RFC-4 in bioformats2raw.

Listing a few possible questions/actions post release candidate:

• should we try to represent the ability to read orientation metadata for some formats/reader in https://bio-formats.readthedocs.io/en/latest/formats/index.html?
• should we extend the automated tests to optionally test the orientation term/types associated with the axes for the relevant format?
• should we add the relevant datasets from https://huggingface.co/fideus-labs/ome-zarr-rfc4-data to our curated QA repository?

[sbesson]

While testing the new key/value pairs, I originally used the following INI:

sizeZ=10

[series_0]
AxisCount=3
AxisOrientationType_0=anatomical
AxisOrientationTerm_0=rostral-to-caudal
AxisOrientationType_1=anatomical
AxisOrientationTerm_1=cranial-to-caudal
AxisOrientationType_2=anatomical
AxisOrientationTerm_2=dorsal-to-ventral

which opened in showinf as the orientation API is not used but failed to convert in bioformats2raw with an IndexOutOfBounds exception.

Could AxisCount be inferred from the dimensionality + modulo information?

[melissalinkert]

Should be fixed in 05fd41f.

[melissalinkert]

The latest changes in MINCReader led to one failure in the nightly tests - https://bf-testing-results.s3.amazonaws.com/2026/2026-10-01/ecat7.log and the configuration file will need to be updated with the PhysicalSizeZ of the corresponding sample which is now populated.

Done in https://github.com/ome/data_repo_config/pull/729.

Once all tests are passing, I would be in favour of merging this effort into the next release candidate of Bio-Formats 9 and can complete the implementation of RFC-4 in bioformats2raw.

👍

Listing a few possible questions/actions post release candidate:

• should we try to represent the ability to read orientation metadata for some formats/reader in https://bio-formats.readthedocs.io/en/latest/formats/index.html?

Captured in ome/bio-formats-documentation#488.

• should we extend the automated tests to optionally test the orientation term/types associated with the axes for the relevant format?
• should we add the relevant datasets from https://huggingface.co/fideus-labs/ome-zarr-rfc4-data to our curated QA repository?

Yes, I think doing both of these at the same time makes sense. Captured as https://github.com/ome/data_repo_config/issues/730.

[sbesson]

Thanks for capturing the suggestions as separate issues. All nightly repository tests are now passing with the configuration changes updating the physical size in Z for the MINC datasets - see https://bf-testing-results.s3.amazonaws.com/2026/2026-10-02/build-status.log