hwoutils.map_coordinates
========================

.. py:module:: hwoutils.map_coordinates

.. autoapi-nested-parse::

   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:
       https://github.com/google/jax/blob/main/jax/_src/scipy/ndimage.py



Attributes
----------

.. autoapisummary::

   hwoutils.map_coordinates._INDEX_FIXERS


Functions
---------

.. autoapisummary::

   hwoutils.map_coordinates._nonempty_prod
   hwoutils.map_coordinates._nonempty_sum
   hwoutils.map_coordinates._mirror_index_fixer
   hwoutils.map_coordinates._reflect_index_fixer
   hwoutils.map_coordinates._round_half_away_from_zero
   hwoutils.map_coordinates._nearest_indices_and_weights
   hwoutils.map_coordinates._linear_indices_and_weights
   hwoutils.map_coordinates._keys_basis
   hwoutils.map_coordinates._cubic_indices_and_weights
   hwoutils.map_coordinates._map_coordinates
   hwoutils.map_coordinates.map_coordinates


Module Contents
---------------

.. py:function:: _nonempty_prod(arrs)

.. py:function:: _nonempty_sum(arrs)

.. py:function:: _mirror_index_fixer(index, size)

.. py:function:: _reflect_index_fixer(index, size)

.. py:data:: _INDEX_FIXERS
   :type:  dict[str, collections.abc.Callable[[jax._src.typing.Array, int], jax._src.typing.Array]]

.. py:function:: _round_half_away_from_zero(a)

.. py:function:: _nearest_indices_and_weights(coordinate)

.. py:function:: _linear_indices_and_weights(coordinate)

.. py:function:: _keys_basis(t)

   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.


.. py:function:: _cubic_indices_and_weights(coordinate)

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


.. py:function:: _map_coordinates(input, coordinates, order, mode, cval)

.. py:function:: map_coordinates(input, coordinates, order, mode = 'constant', cval = 0.0)

   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.