RFC-4: Response 1

RFC-4: Response 1#

Summary of Changes#

This response addresses feedback received during the review process and provides substantial improvements to RFC-4. The major changes include a structural redesign to support extensibility, removal of default values, and comprehensive implementation examples.

Addressing Review Feedback#

Juan Nunez-Iglesias Review (Review 2)#

We have implemented all three significant recommendations from Juan’s review:

1. General Orientation vs. Anatomical-Only Orientation#

Problem: The original proposal was too restrictive, focusing only on anatomical orientation when the concept could serve many more scientific domains.

Solution: We redesigned the field structure from a simple anatomicalOrientation string field to a more general orientation object with type and value fields:

{
  "orientation": {
    "type": "anatomical",
    "value": "left-to-right"
  }
}

This structure can support multiple orientation domains including:

  • Anatomical: left-to-right, anterior-to-posterior, etc.

  • Engineering/Microfluidics: upstream/downstream

  • Geographical: north/south, east/west

  • Oceanographic: increasing-depth

  • Histological: basal/apical

The field name changed from anatomicalOrientation to orientation to reflect this broader scope, while maintaining the anatomical use case as the primary focus.

2. Removal of Default Values#

Problem: Having a default orientation would encourage data producers to omit orientation metadata, making everything silently “just work” while being implicit.

Solution: We removed the implicit default orientation. The specification now states:

If no orientation is specified, there is no implicit default value. Applications MAY assume a default orientation but SHOULD warn users that orientation metadata is expected but missing.

This approach promotes explicit metadata specification and prevents silent assumptions about orientation.

3. Interaction with RFC-5#

Problem: The RFC needed to clarify how it interacts with coordinate transformations (RFC-5).

Solution: We added a dedicated section explaining the interaction:

In cases where anatomical axes are not aligned with imaging axes, RFC-5 transformations can be used to define the relationship between image space and anatomical space. The orientation field would then apply to the axes of the anatomical coordinate system, not the imaging coordinate system.

David’s Comment#

We addressed David’s feedback regarding the implementation details and practical considerations by providing comprehensive implementation examples and clarifying the scope of applicability.

Technical Improvements#

LinkML Schema Definition#

We developed a comprehensive LinkML schema (orientation.yml) that defines:

  • Base Orientation Class: Abstract class with type and value attributes

  • AnatomicalOrientation Class: Specific implementation for anatomical orientations

  • Axis Definitions: Complete axis schema including SpaceAxis, TimeAxis, and ChannelAxis

  • Controlled Vocabularies: Enums for orientation values, units, and axis types

The LinkML schema provides the foundation for generating implementations across multiple languages and validation schemas.

Practical Implementation#

We have developed a full working implementation in the ngff-zarr package that demonstrates:

  • Validation: Proper validation of orientation metadata

  • Serialization/Deserialization: Handling of the orientation objects

  • Integration: How orientation metadata integrates with existing NGFF axis definitions

  • Examples: Real-world usage patterns and test cases

Documentation Improvements#

Enhanced Examples#

The RFC now includes concrete JSON examples showing the complete axis configuration:

{
  "axes": [
    {
      "name": "x",
      "type": "space",
      "unit": "millimeter",
      "orientation": {"type": "anatomical", "value": "left-to-right"}
    }
  ]
}

Extensibility Guidelines#

We added clear guidance on how the structure can be extended for future orientation types while maintaining backward compatibility.

Conclusion#

These changes transform RFC-4 from a narrowly-focused anatomical orientation specification into a general, extensible orientation framework while maintaining strong support for the anatomical use case. The comprehensive implementation examples and working package provide concrete guidance for adoption, and the removal of default values promotes explicit, unambiguous metadata specification.

The changes directly address all reviewer feedback while significantly improving the technical quality and future applicability of the specification.

Contents