Clarify interpolation algorithms for resample2d

[inexorabletash]

This gives formal definitions for the nearest-neighbor and linear interpolation modes. The definitions are based on text given by @fdwr and baseline implementation by @BruceDai and independently verified.

Resolves #358

---

Preview | Diff

[fdwr]

Nice. Thanks for improving the spec. 🙏

[fdwr]

The specific sampling algorithms are based on those widely used in existing Machine Learning frameworks.

Note

Some ML libraries got this wrong historically and did things like stretch the centers of the input corner pixels to the centers of the output corner pixels (rather than the corner extents, including the whole pixel box rectangle rather than just a point sample), which graphics experts know is incorrect 😉 and gives you poor results. Imaging libraries like OpenCV though do the right thing, and thankfully newer versions of TF and PyTorch have fixed this behavior by default. e.g. #1 #2.

Wrong:

Right:

(no action - resolve me)

[inexorabletash]

If we want to say more in the spec we can!

[fdwr]

Updated comment with visualization - think it would help? I should probably recreate it from scratch to avoid directly reusing Jacob Richeimer's figure https://jricheimer.github.io/tensorflow/2019/02/11/resize-confusion/.

[inexorabletash]

I'm thinking it will be hard to capture more of the history here without it turning into an essay equivalent to these linked resources. Maybe we should just link to these blog posts? @anssiko - any thoughts on non-normative links to potentially ephemeral resources?

[fdwr]

No need to stall on this aspect. Happy to merge if you say go.

[huningxin]

LGTM with nits, thanks much!

[fdwr]

👍

[inexorabletash]

If it still looks good @fdwr can you squash-merge ?

[huningxin]

👍

[vmukhachev]

it seems, it is not what Chrome on Windows does:

nearest-neighbor of [0, 1, 2, 3, 4, 5] to the shape 21 gives [0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 5, 5, 5, 5]
the spec says to return
[0, 0, 0, 0, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5]

and for nearest-neighbor of [0, 1, 2, 3, 4, 5] to the shape 3:
[1, 3, 5]
vs
[0, 2, 4]

Some testing of all inputsizes and outputsizes between 1 and 51 shows that Chrome does something like
x = floor(inputCoordinate.x + 0.5)
instead of
x = ceil(inputCoordinate.x - 0.5)
as specified
It floor(z+0.5) fails 22 of those tests althought