ome / ome/ngff

explicitly define the original coordinate system of an array

Open Beginner friendly
#490 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
171
Forks
75
Avg merge
2d 3h
Merged PRs (30d)
20

Description

Describe the issue

The spec claims that array coordinate systems do not need to be explicitly defined:

https://github.com/ome/ngff-spec/blob/990aeaa6d856a8a7c33b5f84370fa8bda8f4f9c4/index.md?plain=1#L292

But I don't think this is true. Since array coordinate systems are the input to all other coordinate systems, they very much need an explicit definition, as ambiguity will propagate.

For an array A with dimensionality N, where N >= 1, I would define A's array coordinate system C as follows:

  • C is an N-dimensional array with the same size as A.
  • The elements of C are N-tuples of integers
  • The first element of C is (0, ...) expanded to N dimensions.
  • All other elements of C are their array index relative to the origin.

For example, given an array with shape (2, 4), the array coordinate system defines the following 2-dimensional array of coordinates:

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

there's a more mathy way to say this but I don't think it's useful, and there's a less mathy way too: the array coordinate system is the set of array indices for the array, starting at (0, ...). Defining the origin explicitly is key. Different software packages disagree on where array indexing starts. This means different software would use the same transforms to generate images on different coordinate grids, which we don't want.

The spec does mention an origin here:

https://github.com/ome/ngff-spec/blob/990aeaa6d856a8a7c33b5f84370fa8bda8f4f9c4/index.md?plain=1#L340-L350

But it's not obvious that this claim defines the set of coordinates that all arrays start with. So I think the spec should be much more clear and define the origin in the context of the array coordinate system.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Open index.md at the cited discussion around lines 292 and 340-350. Compare how the array coordinate system and its origin are currently described, then update the specification so the coordinate set and starting origin are explicit. Done means the text removes ambiguity about array indexing while remaining consistent with the surrounding coordinate-system definitions.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
62/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.