Replace arrayCoordinateSystem with explanation on how to express dimensionless transforms in pixel coordinates

[jo-mueller]

Fixes ome/ngff#438
Addresses comment 4 on RFC5.

Title. This PR replaces the definition of implicit arrayCoordinateSystems with examples and explanatory text on how to properly express transforms that are done in pixel space, not unit space.

Follow up PR to #103 and #90

cc @bogovicj @btbest @will-moore @clbarnes @dstansby

[github-actions]

Automated Review URLs

• Readthedocs

[btbest]

Perfect from my point of view! 🚀

[d-v-b]

I am not sure why this section needs to talk about interpolation? I also would not say "pixel/voxel" -- just say "pixel" here, and make it clear that this term denotes an N-dimensional geometrical element.

[jo-mueller]

Actually, I think the phrasing of a hyper-rectangle as the area that would correspond to the sample at location (i, j) is quite illuminating. I would simply consider it a rephrasing of the same concept.

[d-v-b]

the issue with defining a pixel as a unit hyperrectangle is that it stops being a hyperrectangle when you apply any transform that doesn't preserve angles, like shearing.

So if the 4 coordinates

[
  [(0,0), (0, 1)], 
  [(1, 0), (1, 1)]
]

is "4 pixels" (because nearest-neighbor interpolation would render the intensities at these coordinates as squares), shearing those coordinates, e.g.:

[
  [(0, 0), (0, 1)], 
  [(1, 1), (1, 2)]
]

gives you 4 of something other than a pixel (because these would be rendered as 4 rhombuses by nearest neighbor interpolation)

Is that the intent of this definition? An image is made of pixels until you apply certain transforms to it, and after that its made of something with no name?

[jo-mueller]

So...clearer separation of when we speak about

• Pixels: "Little hyper-boxes" in native coordinate systems directly attached to arrays
• Coordinates: Points in space that describe locations in a given coordinate system and that can be transformed into other coordinate systems
  ?

[d-v-b]

what do we lose if we just talk about points? Will the lack of a definition of "pixel" impair anyone's ability to make sense of the transforms + coordinate systems framework?

[d-v-b]

that's good clarification @mkitti. I should have said "all the transforms defined here work on coordinates".

[jo-mueller]

what do we lose if we just talk about points?

Nothing, but: I'm afraid we are inching into discussion points that are better placed in ome/ngff#492, tbh, because they exceed the scope of this PR.

[d-v-b]

as long as this PR purports to be about "pixel coordinates", I think clarifying usage of the term "pixel" here is important. maybe adjust the title if "pixel coordinates" is not in fact a key part of this PR?

[jo-mueller]

as long as this PR purports to be about "pixel coordinates", I think clarifying usage of the term "pixel" here is important.

I'm not saying it isn't. My point is simply that the term "pixel" currently occurs 17 times throughout different sections and it is out of scope of this PR to fix termini in sections that are about labels, multiscales, etc.

I do think common language is important, I simply prefer doing it in incremental steps. Right now, this PR doesn't use the term "pixel" anymore (save for the title, ofc), except in a section that is concerned with the actual definition of the term itself, which I hope would agree it's an improvement?

[d-v-b]

i definitely agree that the particular discussion about what "pixel" means, and what it contributes to the spec, can be continued elsewhere; hopefully the outcome of that discussion would not require editing any of the text modified here.

[d-v-b]

is there a definition of "intrinsic coordinate system somewhere?

[jo-mueller]

Hm...In #117, I added this further up under the coordinate systems section:

Could add that here as well?

[d-v-b]

so "intrinsic coordinate system" means "native physical coordinate system"? IMO this is not terribly clear, since both "intrinsic coordinate system" and "native coordinate system" are terms invented in this spec, as far as I can tell.

I would encourage reducing the number of different "kinds" of coordinate systems, especially if their differences cannot be strictly defined (i.e., defined well enough for a program to do something useful with).

Putting aside the "coordinate system" language for a minute, there is something special about the coordinates an array "starts with" -- without defining these coordinates, you have not defined the input to any of the transforms. So there needs to be some way for an array to declare what coordinates it has, before any transforms are applied.

"Array declares its coordinates" is not in principle the same thing as an "intrinsic coordinate system" or "array coordinate system" because ome-zarr could in principle add a convention (like xarray) where the array's coordinates are data that you read from a coordinate array (and so they would not start at (0,0,0), and might have units, etc). I would not close the door on this possibility.

So I would not use language that implies that the coordinates an array declares (implicitly, for now, but possibly explicitly later) are somehow categorically different from the coordinates that pop out of transforms. So I don't think you need to talk about pixel units or array units or any of that. The minimal thing is to instruct viewers how to address the coordinates an array starts with.

[bogovicj]

I see this PR's scope as being pretty small, it does what it says and is clear (modulo the discussion below). So I approve these changes.

There are comments here about definitions and terminology that deserve further discussion. @d-v-b opened this issue ome/ngff#492
and I suggest we move the discussion there.

It's true that the phrasing of the examples and text edited here will change as a result of those decisions we'll have about terminology, but they'll affect more than what is written here, so I'd suggest those larger changes be a separate PR.

[will-moore]

I never really felt the need for Array coordinate systems, so it almost feels a bit verbose to describe how to work without them. But no objections if it's useful, Thanks

[jo-mueller]

so it almost feels a bit verbose to describe how to work without them. But no objections if it's useful

Yeah...maybe we'll need a section for "How to express this or that data structure" to be broken out of the spec at some point 🤔