WIP: 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

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]

Ok...I added a bunch of examples from https://github.com/jo-mueller/ngff-rfc5-coordinate-transformation-examples and made sure tests are passing on them. Also, I invalidated some of them. Will add a few more 👍