Port RFC5 updated proposal to ngff-spec

[jo-mueller]

This is the PR following up to ome/ngff#389.

This PR

• inserts the proposed text into the full spec document
• makes sure that the correct formatting and cross-referencing is used
• adds some more examples to the transformations
• update and add new schemas
• adds a summary of changes to the changelog
• add scene example metadata

PRs to merge first:

• Backticks everywhere #73

[github-actions]

Automated Review URLs

• Readthedocs

[jo-mueller]

@dstansby updated the schemas! Could I ask you to have a swift look if something strikes you as off?

[dstansby]

I had a look, and I'm struggling to read the schemas by eye, and the rendering doesn't look so nice either (https://ngff-spec--67.org.readthedocs.build/en/67/schemas/scene/, https://ngff-spec--67.org.readthedocs.build/en/67/schemas/coordinate-transformations/, https://ngff-spec--67.org.readthedocs.build/en/67/schemas/coordinate-systems/)

Perhaps a better test than manual review is checking that the examples all validate correctly using the schemas?

[jo-mueller]

and I'm struggling to read the schemas by eye

I feel you 🙄

and the rendering doesn't look so nice either

Tbf, it doesn't look very different from the rendering on the current main. I think it's getting especially nasty for the OneOf of AllOf clauses in the schema, but I'm afraid the rendering is what it is. We were thinking about experimenting with LinkML for the schemas (maybe these render nicer?) but that's a different discussion.

But you're right about the validator - I guess the easiest thing is then to create fork of the validator, point it to this branch for the schemas and check the examples 👍 OR simply copy some of the examples to the testing CI in here.

[dstansby]

I had more of a look at the RTD build, and some initial comments:

There's "Coordinate systems" and "Coordinate systems and transforms" pages, which seems confusing (duplication of coordinate systems):

I don't understand why coordinate systems and transformations are in the same schema, wouldn't it be much cleaner to have them in separate schemas?

On a similar theme, it would be much nicer to have all the different transforms as their own schema that are then referenced by other schemas. It would incraese the number of schema files, but make it much easier to find a given transformation for example.

[jo-mueller]

There's "Coordinate systems" and "Coordinate systems and transforms" pages, which seems confusing (duplication of coordinate systems):

I think that's a legacy thing. They maybe used to be but the schemas are separated as you suggest. It was just that the title of the coordinate transformations schema file was still "coordinate systems and transformations" - I changed it, should be fixed now.

On a similar theme, it would be much nicer to have all the different transforms as their own schema that are then referenced by other schemas. It would incraese the number of schema files, but make it much easier to find a given transformation for example.

Agree! Makes total sense and can do.

[jo-mueller]

@dstansby found it! The failing example (byDImension.json) used an array coordinate system, which hsa two axes of "type": "array". The coordinate system schema requires at least two spatial axes though. I need to check whether that's actually enforced by the spec.

[dstansby]

At https://ngff.openmicroscopy.org/rfc/5/responses/2/index.html#change-bydimension-convention it says:

Outcome: It was agreed to change the byDimension convention to align with other transformations. The updated metadata layout is as follows:

{
  "type": "byDimension",
  "input": "high_dimensional_coordinatesystem_A",
  "output": "high_dimensional_coordinatesystem_B", 
  "transformations": [
    {
      "input_axes": [0, 1],
      "output_axes": [0, 1],
      "transformation": {
        "type": "scale",
        "scale": [0.5, 0.5]
      }
      
    },
    {
      "input_axes": [2],
      "output_axes": [2],
      "transformation": {
        "type": "translation",
        "translation": [10.0]
      }
    }
  ]
}

On the latest RTD build of this PR, the spec doesn't seem to have been updated to reflect this: https://ngff-spec--67.org.readthedocs.build/en/67/#bydimension, and at least the first example does not align with the above example JSON from the review:

{
  "coordinateSystems": [
    { "name": "in", "axes": [ {"name": "j"}, {"name": "i"} ] },
    { "name": "out", "axes": [ {"name": "y"}, {"name": "x"} ] }
  ],
  "coordinateTransformations": [
    {
      "type": "byDimension",
      "input": "in",
      "output": "out",
      "transformations": [
        {
          "type": "translation",
          "translation": [-1.0],
          "input_axes": [1],
          "output_axes": [1]
        },
        {
          "type": "scale",
          "scale": [2.0],
          "input_axes": [0],
          "output_axes": [0]
        }
      ]
    }
  ]
}

@jo-mueller is this something that still needs fixing here?

[jo-mueller]

@dstansby thanks a lot for the extra look, this was indeed incorrect...talk about not seeing the forest for trees anymore 🙄 I also adjusted the schemas and examples for the CI accordingly.

[imagesc-bot]

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

https://forum.image.sc/t/how-to-build-hcs-zarrs-with-multiple-image-types-per-fov/119329/9

[joshmoore]

Got an additional 👍 from @clbarnes. Merging to let @jo-mueller announce as appropriate.

[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/69