RFC-4: Clarify subject-local orientation and add layered-tissue vocabulary

[thewtex]

Follow-up to RFC-4 review 3 (Dave Horsfall, Hannifa Lab; added in #435), implementing its two accepted recommendations. The review was generated from a Hannifa Lab discussion spanning wet-lab scientists, clinicians, bioinformaticians, and engineers, and recommended "Accept, with minor changes: explicitly support subject-local orientation and expand the vocabulary to include layered-tissue terms."

What changed

1. New "Subject-Local vs. Patient-Global Orientation" clarification (rfc/4/index.md)

Clarifies that the orientation subject need not be a whole organism — it may be a local anatomical structure such as a tissue biopsy, histology slide, or dissected organ. The existing "roughly aligned to the imaging axes" requirement is reinterpreted to apply to the local tissue structure, and RFC-5 transformations are cited for relating subject-local axes to a patient-global / atlas frame when such a registration is available.

2. Six new controlled-vocabulary terms for layered and polarized tissues (anatomical vocabulary grows 18 → 24 values)

Pair	Intended use
superficial-to-deep / deep-to-superficial	layered tissues (skin, gut, cortex)
apical-to-basal / basal-to-apical	epithelial layers, polarized cell structures
apex-to-base / base-to-apex	organs such as the heart or lungs

3. Removed the now-redundant histological: basal/apical future-domain example, since basal/apical are now part of the anatomical vocabulary.

Why

In spatial transcriptomics, histopathology, and high-resolution histology, the imaged subject is frequently a tissue specimen whose global position/orientation on the donor is unknown, but whose internal orientation is well defined — e.g. a skin biopsy's depth axis is superficial-to-deep regardless of where on the body it was taken. The prior wording was geared toward whole-patient imaging; these changes make the orientation field usable by the tissue-profiling community without requiring full patient-to-atlas registration, and supply the layered/polarized-tissue terms that community needs.

Implementation details

• The six values were added to the LinkML source of truth (rfc/4/orientation.yml) and propagated consistently to every derived artifact — orientation.schema.json, orientation.py, orientation.ts, markdown/AnatomicalOrientationValues.md — and to every representation embedded in index.md (controlled-vocabulary list, permissible-values table, JSON-Schema, Pydantic, and TypeScript snippets). A new "layered and polarized tissues" category was added to the vocabulary list and a 2026-06-03 changelog entry references review 3.
• Derived files were hand-edited rather than regenerated: the locally available LinkML (metamodel 1.11.0) diverges from the committed output (1.7.0) and regeneration would have introduced unrelated abstract-class/version noise. The updated orientation.yml was nonetheless verified to still generate cleanly through LinkML (all six values present, no errors).
• The frozen review snapshot under rfc/4/versions/ was intentionally left untouched.

Verification

• All 24 vocabulary values consistent across every file; identical ordering in .py / .ts / .json; hyphenated values vs. underscored identifiers correct.
• orientation.schema.json is valid JSON, orientation.yml valid YAML, orientation.py compiles, and the RFC page parses under MyST with no new errors.
• codespell clean; CodeRabbit review reported 0 findings.

Out of scope

Review 3's third discussion point — a deeper RFC-4 ↔ RFC-5 semantic bridge for programmatic atlas registration — is left for future collaboration, as the reviewer suggested. The RFC's existing "Interaction with RFC-5" section already covers the basic relationship.

[github-actions]

Automated Review URLs

• Readthedocs

[thewtex]

@davehorsfall @melonora @dyf please take a look 🙏

@jo-mueller I also added the null / undefined explicit mention as we discussed.

[imagesc-bot]

This pull request has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/rfc-4-updates-enhanced-anatomical-orientation-support-for-ome-ngff/115625/10

[imagesc-bot]

This pull request has been mentioned on Image.sc Forum. There might be relevant details there:

https://forum.image.sc/t/ngff-weekly-dev-update-thread/110810/105

[melonora]

Just to put it on record, I discussed this with @thewtex on zulip, the idea of local tissue orientation vs orientation of the tissue within the anatomical body can be seen as a primary orientation vs secondary orientation. We discussed this alternative and while there are emerging examples we agree it would be an overkill for now.

Just to clarify by one example, there are labs doing whole body tissue clearing to perform lightsheet microscopy. Afterwards, from regions of interest biopsies are taken and subjected to highly multiplexed protein imaging. While these biopsies have a local orientation, they also have a secondary orientation in the whole body.

@thewtex shall we add this to alternatives discussed?

[d-v-b]

i think you can make the anatomical direction information robust by framing it as an annotation for a vector, where the only supported vectors right now are vectors that point in the direction of the coordinate axes. If ome-zarr gets formal support for geometrical objects like vectors, then images could use the anatomical direction information to annotate these vectors in ways that make sense for the contents of the image, e.g. an image of multiple organs, or multiple organisms, where anatomical orientation only makes sense locally

[thewtex]

@melonora @d-v-b thanks both — I've captured these points in the RFC text in a follow-up commit:

• The orientation field describes a single, primary (subject-local) orientation. Additional/secondary orientations — e.g. @melonora's whole-body-clearing
  example where a biopsy has both a local tissue orientation and a secondary orientation within the donor body — are not supported at this time.
• Per @d-v-b's framing: if OME-Zarr later gains a generic vector / geometrical-object data structure, these orientation annotations could be applied to such vectors, allowing multiple orientations to be expressed where anatomical orientation only makes sense locally (multiple organs or organisms in one image).