Displacements are multiscales

[jo-mueller]

Fixes ome/ngff#520

This changes how displacement fields and coordinate arrays are expected to be stored in displacement/coordinate transforms, as discussed in the 06/2026 Hackathon at EMBL.

The gist: The arrays are now simply multiscale groups and the displacement/coordinate dimension should go into the channel dimension of the data.

• updated the spec text
• updated the examples (removed the 1d examples because 1d is not allowed anyway)
• no change to the schema
• updated version history

@bogovicj @clbarnes @melonora @LucaMarconato @thewtex @tischi @kevinyamauchi @jni @DragaDoncila @perlman
...who am I forgetting?

[github-actions]

Automated Review URLs

• Readthedocs

[jo-mueller]

Maybe should add a recommendation/statement about which resolution level of the displacement field implementations should use?

If multiple resolution levels are provided, implementations MAY choose any resolution level to compute the output.

Also, do we need to add constraints/hints on possible pathologies that can arise when downsampling vector fields/coordinate lists?

[thewtex]

🥇 😍 🚀

[thewtex]

Maybe should add a recommendation/statement about which resolution level of the displacement field implementations should use?

If multiple resolution levels are provided, implementations MAY choose any resolution level to compute the output.

👍

And possibly SHOULD use the finest resolution if the result is used beyond quick visualization purposes.

Also, do we need to add constraints/hints on possible pathologies that can arise when downsampling vector fields/coordinate lists?

We could also recommend that anti-alias filtering SHOULD be applied when downsampling, similar to an intensity image multiscale.

[imagesc-bot]

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

https://forum.image.sc/t/serialise-displacement-field-as-ome-zarr/121117/6

[jo-mueller]

@bogovicj @clbarnes @melonora @LucaMarconato @thewtex @tischi @kevinyamauchi @jni @DragaDoncila @perlman @d-v-b last call - any more feedback on this?

[LucaMarconato]

One comment not in the diff of this PR:

• If nearest interpolation is used for a coordinates transformation,
  the transformed image collapses into a single point at the nearest coordinate in the coordinate field.
• If nearest interpolation is used for a displacements transformation,
  the transformed image is piecewise constant with discontinuities at the boundaries between nearest neighbor regions.

I haven't worked with this yet so I may be missing something, but aren't the two representations (coordinate and displacements) equivalent? Why do we have 2 different "if"? Shouldn't be the implication the same?

EDIT: ah I see below that "displacements require M=N." so they are not equivalent and now I got what the 2 "if" mean: with displacement the shift is constant for all the neighbors of a point in the domain grid, while for coordinates the target image is constant for each point of the domain grid.

So the text it's correct, but it can be confusing if someone is new with the concept because the definition of how displacement and coordinates operates as a function is missing. The specs start right away in showing how to represent them, but not how they would behave as functions.

[LucaMarconato]

Thanks @jo-mueller for opening this! My comments are most about the text that is not touched by this PR, but that I reviewed together with the changes. I think the changes are mostly ok (and with the new usage of multiscales the text is shorter and clearer).

[jo-mueller]

@LucaMarconato thanks for the review! I expanded the example below the hint box a bit to make the procedure more clear on how the retrieved, interpolated vector is obtained from a given input point x in physical coordinates.

I'm considering the hint box entirely since the example is maybe more informative anyway. Let me know if that clears things up!