hwoutils.map_coordinates#

Image coordinate mapping with sub-pixel interpolation for JAX.

Adapted from the JAX project (PR #14218 by Louis Desdoigts); Apache 2.0.

At order=3 the kernel is the Keys cubic convolution (a = -0.5, Catmull-Rom), a true 4-tap interpolant. See hwoutils/docs/interpolation.md for details.

Original JAX source:: google/jax

Attributes#

_INDEX_FIXERS

Functions#

`_nonempty_prod`(arrs)
`_nonempty_sum`(arrs)
`_mirror_index_fixer`(index, size)
`_reflect_index_fixer`(index, size)
`_round_half_away_from_zero`(a)
`_nearest_indices_and_weights`(coordinate)
`_linear_indices_and_weights`(coordinate)
`_keys_basis`(t)	Keys cubic convolution kernel with a = -0.5 (Catmull-Rom).
`_cubic_indices_and_weights`(coordinate)	4-tap Keys stencil: samples at floor(coord) + {-1, 0, 1, 2}.
`_map_coordinates`(input, coordinates, order, mode, cval)
`map_coordinates`(input, coordinates, order[, mode, cval])	Map an input array onto new coordinates via sub-pixel interpolation.

Module Contents#

hwoutils.map_coordinates._nonempty_prod(arrs)[source]#

Parameters:: arrs (collections.abc.Sequence[jax._src.typing.Array])
Return type:: jax._src.typing.Array

hwoutils.map_coordinates._nonempty_sum(arrs)[source]#

Parameters:: arrs (collections.abc.Sequence[jax._src.typing.Array])
Return type:: jax._src.typing.Array

hwoutils.map_coordinates._mirror_index_fixer(index, size)[source]#

Parameters:

index (jax._src.typing.Array)
size (int)

Return type:

jax._src.typing.Array

hwoutils.map_coordinates._reflect_index_fixer(index, size)[source]#

Parameters:

index (jax._src.typing.Array)
size (int)

Return type:

jax._src.typing.Array

hwoutils.map_coordinates._INDEX_FIXERS: dict[str, collections.abc.Callable[[jax._src.typing.Array, int], jax._src.typing.Array]]#

hwoutils.map_coordinates._round_half_away_from_zero(a)[source]#

Parameters:: a (jax._src.typing.Array)
Return type:: jax._src.typing.Array

hwoutils.map_coordinates._nearest_indices_and_weights(coordinate)[source]#

Parameters:: coordinate (jax._src.typing.Array)
Return type:: list[tuple[jax._src.typing.Array, jax._src.typing.Array]]

hwoutils.map_coordinates._linear_indices_and_weights(coordinate)[source]#

Parameters:: coordinate (jax._src.typing.Array)
Return type:: list[tuple[jax._src.typing.Array, jax._src.typing.Array]]

hwoutils.map_coordinates._keys_basis(t)[source]#

Keys cubic convolution kernel with a = -0.5 (Catmull-Rom).

Piecewise cubic with compact support [-2, 2]:

inner (abs(t) <= 1): 1.5 abs(t)^3 - 2.5 abs(t)^2 + 1 outer (1 < abs(t) <= 2): -0.5 abs(t)^3 + 2.5 abs(t)^2 - 4 abs(t) + 2 else: 0

Properties:

True interpolant: K(0) = 1, K(k) = 0 for non-zero integer k, so evaluating at integer grid points returns the sample exactly.
Partition of unity at integer grid spacing: sum over integer shifts of K equals 1 for any offset. This makes it flux-preserving on integer downsampling of band-limited inputs.
Reproduces constants and linear functions exactly under translation; reproduces quadratics approximately (O(h^3)).
Has small negative lobes (min value ~ -0.0625), so outputs can be slightly negative even for non-negative inputs.

Parameters:: t (jax._src.typing.Array)
Return type:: jax._src.typing.Array

hwoutils.map_coordinates._cubic_indices_and_weights(coordinate)[source]#

4-tap Keys stencil: samples at floor(coord) + {-1, 0, 1, 2}.

Parameters:: coordinate (jax._src.typing.Array)
Return type:: list[tuple[jax._src.typing.Array, jax._src.typing.Array]]

hwoutils.map_coordinates._map_coordinates(input, coordinates, order, mode, cval)[source]#

Parameters:

input (jax._src.typing.ArrayLike)
coordinates (collections.abc.Sequence[jax._src.typing.ArrayLike])
order (int)
mode (str)
cval (jax._src.typing.ArrayLike)

Return type:

jax._src.typing.Array

hwoutils.map_coordinates.map_coordinates(input, coordinates, order, mode='constant', cval=0.0)[source]#

Map an input array onto new coordinates via sub-pixel interpolation.

Args:

input: The input array. coordinates: Sequence of coordinate arrays for each dimension. order: Interpolation order:

0: nearest neighbor.

1: linear.

3: Keys cubic convolution (a = -0.5, Catmull-Rom). A true 4-tap interpolant with partition of unity at integer grid spacing, so resampling preserves sample values at integer offsets and conserves flux on integer downsampling of band-limited inputs. See docs/interpolation.md.

mode: Boundary handling (‘constant’, ‘nearest’, ‘wrap’, ‘mirror’,: ‘reflect’).

cval: Value for ‘constant’ mode outside boundaries.

Returns:

Interpolated values at the given coordinates.

Parameters:

input (jax._src.typing.ArrayLike)
coordinates (collections.abc.Sequence[jax._src.typing.ArrayLike])
order (int)
mode (str)
cval (jax._src.typing.ArrayLike)

Return type:

jax._src.typing.Array