Unify input output

[jo-mueller]

Fixes ome/ngff#480
Fixes ome/ngff#437
Relevant for ome/ngff#360

Description

In previous versions of the spec, we had used a mix of contentions when it came to specifying the inputs and outputs of coordinate transformations:

• In the scene context, input and output had to be an object with fields name and path.
• For the multiscale transformations inside the multiscales metadata (multiscales > datasets > coordinateTransformations), only a string was allowed, which had to correspond to the path of the respective dataset entry.
• For the additional transforms next to the multiscales metadata (multiscales > coordinateTransformations), a string was required, which had to correspond top the name of a coordinate system in the same metadata document.

Following the original suggestion of @dstansby at ome/ngff#437, this is unified into a common syntax in this PR. It also has adjustments for schemas, examples and CI tests.

cc @will-moore @dstansby @clbarnes @bogovicj

[github-actions]

Automated Review URLs

• Readthedocs

[dstansby]

Some comments, but 👍 this looks great overall

[dstansby]

Could "generally" be changed to either "are recommended to" or "always", to make it clearer whether they're always present, and if not recommended?

[dstansby]

What does "generally be a..." mean here? That it's an innacurate represenatation? That sometimes it isn't a represenation in a physical coordinate system?

As a general thought I think it's more confusing to have general statements like this in the spec that are not true for all datasets.

[jo-mueller]

The statement here was intended to introduce the term "intrinsic" up front, because it's used several times further down. I guess there are cases where the described image array (i.e., the "intrinsic" coordinate system) is different from the coordinate system in which one would want to natively view the image. For instance, in SCAPE microscopy, the acquired image stack is skewed, so the native stack is not something one would prefer to look at. But that's relatively niche and for 99% of all use cases, the statement probably holds.

[dstansby]

I don't understand the "path must be equal to path" constraint here? Possibly this is a hangover from the previous version and can just be deleted now?

[jo-mueller]

Yeah...it sounded clunky no matter how I put it.

Essentially, a dataset entry must contain

{
  "path": "s0",
  "coordinateTransformations": [
    {
      "type": "indentity",
      "input": {"path": "s0"},
      "output": {"name": "physical"}
    }
  ]
}

and I wanted to express that the contents of both path fields in here must be identical.

[dstansby]

Again, what does "generally" mean?

[dstansby]

Suggested change

	The value of `output` can be the name of an output coordinate System in the same multiscales group
	The value of `output` can be the name of an output coordinate system in the same multiscales group

[dstansby]

Also, this currently implies value of output can be a string, is that correct?

[jo-mueller]

Ah, good point. I edited the section a bit in 9c7dae2