Source code for colour.algebra.interpolation

"""
Interpolation
=============

Provide classes and functions for interpolating variables in colour science
computations.

This module implements various interpolation methods for one-dimensional
functions and multi-dimensional table-based interpolation. These methods
support spectral data processing, colour transformations, and general
numerical interpolation tasks in colour science applications.

-   :class:`colour.KernelInterpolator`: 1-D function generic interpolation
    with arbitrary kernel.
-   :class:`colour.NearestNeighbourInterpolator`: 1-D function
    nearest-neighbour interpolation.
-   :class:`colour.LinearInterpolator`: 1-D function linear interpolation.
-   :class:`colour.SpragueInterpolator`: 1-D function fifth-order polynomial
    interpolation using *Sprague (1880)* method.
-   :class:`colour.CubicSplineInterpolator`: 1-D function cubic spline
    interpolation.
-   :class:`colour.PchipInterpolator`: 1-D function piecewise cube Hermite
    interpolation.
-   :class:`colour.NullInterpolator`: 1-D function null interpolation.
-   :func:`colour.lagrange_coefficients`: Compute *Lagrange Coefficients*.
-   :func:`colour.algebra.table_interpolation_trilinear`: Perform trilinear
    interpolation with table.
-   :func:`colour.algebra.table_interpolation_tetrahedral`: Perform
    tetrahedral interpolation with table.
-   :attr:`colour.TABLE_INTERPOLATION_METHODS`: Supported table interpolation
    methods.
-   :func:`colour.table_interpolation`: Perform interpolation with table using
    specified method.

The interpolator classes dispatch to an array backend (*NumPy*, *PyTorch* or
*JAX*) resolved from the input data. To pin a specific backend instead -- e.g.
to guarantee automatic differentiation or ``jax.jit`` support -- import it from
:mod:`colour.algebra.interpolation.backends`, whose submodules expose the same
classes specialised for one backend.

Every interpolator accepts a ``dtype`` setting the stored-data and output
precision, defaulting to :attr:`colour.constants.DTYPE_FLOAT_DEFAULT` for *NumPy*
data and to the framework's own default float for *PyTorch* / *JAX* data. The
resolved dtype is exposed read-only as ``dtype``.

References
----------
-   :cite:`Bourkeb` : Bourke, P. (n.d.). Trilinear Interpolation. Retrieved
    January 13, 2018, from http://paulbourke.net/miscellaneous/interpolation/
-   :cite:`Burger2009b` : Burger, W., & Burge, M. J. (2009). Principles of
    Digital Image Processing. Springer London. doi:10.1007/978-1-84800-195-4
-   :cite:`CIETC1-382005f` : CIE TC 1-38. (2005). 9.2.4 Method of
    interpolation for uniformly spaced independent variable. In CIE 167:2005
    Recommended Practice for Tabulating Spectral Data for Use in Colour
    Computations (pp. 1-27). ISBN:978-3-901906-41-1
-   :cite:`CIETC1-382005h` : CIE TC 1-38. (2005). Table V. Values of the
    c-coefficients of Equ.s 6 and 7. In CIE 167:2005 Recommended Practice for
    Tabulating Spectral Data for Use in Colour Computations (p. 19).
    ISBN:978-3-901906-41-1
-   :cite:`Fairman1985b` : Fairman, H. S. (1985). The calculation of weight
    factors for tristimulus integration. Color Research & Application, 10(4),
    199-203. doi:10.1002/col.5080100407
-   :cite:`Kirk2006` : Kirk, R. (2006). Truelight Software Library 2.0.
    Retrieved July 8, 2017, from
    https://www.filmlight.ltd.uk/pdf/whitepapers/FL-TL-TN-0057-SoftwareLib.pdf
-   :cite:`Westland2012h` : Westland, S., Ripamonti, C., & Cheung, V. (2012).
    Interpolation Methods. In Computational Colour Science Using MATLAB (2nd
    ed., pp. 29-37). ISBN:978-0-470-66569-5
-   :cite:`Wikipedia2003a` : Wikipedia. (2003). Lagrange polynomial -
    Definition. Retrieved January 20, 2016, from
    https://en.wikipedia.org/wiki/Lagrange_polynomial#Definition
-   :cite:`Wikipedia2005b` : Wikipedia. (2005). Lanczos resampling. Retrieved
    October 14, 2017, from https://en.wikipedia.org/wiki/Lanczos_resampling
"""

from __future__ import annotations

import sys
import typing
from functools import reduce
from unittest.mock import MagicMock

import numpy as np

from colour.utilities.requirements import is_scipy_installed
from colour.utilities.verbose import usage_warning

if not is_scipy_installed():  # pragma: no cover
    try:
        is_scipy_installed(raise_exception=True)
    except ImportError as error:
        usage_warning(str(error))

    mock = MagicMock()
    mock.__name__ = ""

    for module in (
        "scipy",
        "scipy.interpolate",
    ):
        sys.modules[module] = mock

from colour.constants import (
    DTYPE_INT_DEFAULT,
)

if typing.TYPE_CHECKING:
    from colour.hints import (
        ArrayLike,
        Literal,
    )

from colour.hints import NDArrayFloat, NDArrayReal, cast
from colour.utilities import (
    CanonicalMapping,
    array_namespace,
    validate_method,
    xp_as_float_array,
    xp_as_int_array,
    xp_astype,
    xp_reshape,
    xp_select,
)

from ._dispatch import (
    CubicSplineInterpolator,
    KernelInterpolator,
    LinearInterpolator,
    NearestNeighbourInterpolator,
    NullInterpolator,
    PchipInterpolator,
    SpragueInterpolator,
)
from .backends._kernels import (
    kernel_cardinal_spline,
    kernel_lanczos,
    kernel_linear,
    kernel_nearest_neighbour,
    kernel_sinc,
)

__author__ = "Colour Developers"
__copyright__ = "Copyright 2013 Colour Developers"
__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
__maintainer__ = "Colour Developers"
__email__ = "colour-developers@colour-science.org"
__status__ = "Production"


__all__ = [
    "kernel_nearest_neighbour",
    "kernel_linear",
    "kernel_sinc",
    "kernel_lanczos",
    "kernel_cardinal_spline",
    "KernelInterpolator",
    "NearestNeighbourInterpolator",
    "LinearInterpolator",
    "SpragueInterpolator",
    "CubicSplineInterpolator",
    "PchipInterpolator",
    "NullInterpolator",
    "lagrange_coefficients",
    "table_interpolation_trilinear",
    "table_interpolation_tetrahedral",
    "TABLE_INTERPOLATION_METHODS",
    "table_interpolation",
    "linear_interpolation_index_and_factor",
]


[docs] def lagrange_coefficients(r: float, n: int = 4) -> NDArrayFloat: """ Compute *Lagrange coefficients* at specified point :math:`r` for polynomial interpolation of degree :math:`n`. Parameters ---------- r Point at which to compute the *Lagrange coefficients*. n Degree of the polynomial interpolation. The number of coefficients returned will be :math:`n + 1`. Returns ------- :class:`numpy.ndarray` Array of *Lagrange coefficients* computed at point :math:`r`. References ---------- :cite:`Fairman1985b`, :cite:`Wikipedia2003a` Examples -------- >>> lagrange_coefficients(0.1) array([ 0.8265, 0.2755, -0.1305, 0.0285]) """ r_i = np.arange(n) L_n = [] for j in range(len(r_i)): basis = [(r - r_i[i]) / (r_i[j] - r_i[i]) for i in range(len(r_i)) if i != j] L_n.append(reduce(lambda x, y: x * y, basis)) return np.asarray(L_n)
[docs] def table_interpolation_trilinear(V_xyz: ArrayLike, table: ArrayLike) -> NDArrayFloat: """ Perform trilinear interpolation of the specified :math:`V_{xyz}` values using the specified interpolation table. Parameters ---------- V_xyz :math:`V_{xyz}` values to interpolate. table 4-Dimensional (NxNxNx3) interpolation table. Returns ------- :class:`numpy.ndarray` Interpolated :math:`V_{xyz}` values. References ---------- :cite:`Bourkeb` Examples -------- >>> import os >>> import colour >>> path = os.path.join( ... os.path.dirname(__file__), ... "..", ... "..", ... "io", ... "luts", ... "tests", ... "resources", ... "iridas_cube", ... "Colour_Correct.cube", ... ) >>> LUT = colour.read_LUT(path) >>> table = LUT.table >>> prng = np.random.RandomState(4) >>> V_xyz = colour.algebra.random_triplet_generator(3, random_state=prng) >>> print(V_xyz) # doctest: +ELLIPSIS [[0.9670298... 0.7148159... 0.9762744...] [0.5472322... 0.6977288... 0.0062302...] [0.9726843... 0.2160895... 0.2529823...]] >>> table_interpolation_trilinear(V_xyz, table) # doctest: +ELLIPSIS array([[1.0120664..., 0.7539146..., 1.0228540...], [0.5075794..., 0.6479459..., 0.1066404...], [1.0976519..., 0.1785998..., 0.2299897...]]) """ V_xyz = cast("NDArrayFloat", V_xyz) xp = array_namespace(V_xyz) original_shape = V_xyz.shape V_xyz = cast("NDArrayFloat", xp_reshape(xp.clip(V_xyz, 0, 1), (-1, 3), xp=xp)) # Index computation table = xp_as_float_array(table, xp=xp, like=V_xyz) i_m = xp_as_int_array(table.shape[:-1], xp=xp, like=V_xyz) - 1 V_xyz_s = V_xyz * i_m i_f = xp_astype(V_xyz_s, DTYPE_INT_DEFAULT, xp=xp) i_f = xp.clip(i_f, 0, i_m) i_c = xp.minimum(i_f + 1, i_m) # Relative coordinates (fractional part) frac = V_xyz_s - i_f # Extract indices for direct lookup fx, fy, fz = i_f[:, 0], i_f[:, 1], i_f[:, 2] cx, cy, cz = i_c[:, 0], i_c[:, 1], i_c[:, 2] # Extract fractional coordinates dx, dy, dz = frac[:, 0:1], frac[:, 1:2], frac[:, 2:3] dx1, dy1, dz1 = 1.0 - dx, 1.0 - dy, 1.0 - dz # Direct vertex lookups (8 corners of cube) v000 = table[fx, fy, fz] v001 = table[fx, fy, cz] v010 = table[fx, cy, fz] v011 = table[fx, cy, cz] v100 = table[cx, fy, fz] v101 = table[cx, fy, cz] v110 = table[cx, cy, fz] v111 = table[cx, cy, cz] # Trilinear interpolation (vectorized) result = ( v000 * (dx1 * dy1 * dz1) + v001 * (dx1 * dy1 * dz) + v010 * (dx1 * dy * dz1) + v011 * (dx1 * dy * dz) + v100 * (dx * dy1 * dz1) + v101 * (dx * dy1 * dz) + v110 * (dx * dy * dz1) + v111 * (dx * dy * dz) ) return xp_reshape(result, original_shape, xp=xp)
[docs] def table_interpolation_tetrahedral(V_xyz: ArrayLike, table: ArrayLike) -> NDArrayFloat: """ Perform tetrahedral interpolation of the specified :math:`V_{xyz}` values using the specified 4-dimensional interpolation table. Parameters ---------- V_xyz :math:`V_{xyz}` values to interpolate. table 4-Dimensional (NxNxNx3) interpolation table. Returns ------- :class:`numpy.ndarray` Interpolated :math:`V_{xyz}` values. References ---------- :cite:`Kirk2006` Examples -------- >>> import os >>> import colour >>> path = os.path.join( ... os.path.dirname(__file__), ... "..", ... "..", ... "io", ... "luts", ... "tests", ... "resources", ... "iridas_cube", ... "Colour_Correct.cube", ... ) >>> LUT = colour.read_LUT(path) >>> table = LUT.table >>> prng = np.random.RandomState(4) >>> V_xyz = colour.algebra.random_triplet_generator(3, random_state=prng) >>> print(V_xyz) # doctest: +ELLIPSIS [[0.9670298... 0.7148159... 0.9762744...] [0.5472322... 0.6977288... 0.0062302...] [0.9726843... 0.2160895... 0.2529823...]] >>> table_interpolation_tetrahedral(V_xyz, table) # doctest: +ELLIPSIS array([[1.0196197..., 0.7674062..., 1.0311751...], [0.5105603..., 0.6466722..., 0.1077296...], [1.1178206..., 0.1762039..., 0.2209534...]]) """ V_xyz = cast("NDArrayFloat", V_xyz) xp = array_namespace(V_xyz) original_shape = V_xyz.shape V_xyz = cast("NDArrayFloat", xp_reshape(xp.clip(V_xyz, 0, 1), (-1, 3), xp=xp)) # Index computation table = xp_as_float_array(table, xp=xp, like=V_xyz) i_m = xp_as_int_array(table.shape[:-1], xp=xp, like=V_xyz) - 1 V_xyz_s = V_xyz * i_m i_f = xp_astype(V_xyz_s, DTYPE_INT_DEFAULT, xp=xp) i_f = xp.clip(i_f, 0, i_m) i_c = xp.minimum(i_f + 1, i_m) # Relative coordinates r = V_xyz_s - i_f x, y, z = r[:, 0], r[:, 1], r[:, 2] # Extract indices for direct lookup fx, fy, fz = i_f[:, 0], i_f[:, 1], i_f[:, 2] cx, cy, cz = i_c[:, 0], i_c[:, 1], i_c[:, 2] # Look up 8 corner vertices V000 = table[fx, fy, fz] V001 = table[fx, fy, cz] V010 = table[fx, cy, fz] V011 = table[fx, cy, cz] V100 = table[cx, fy, fz] V101 = table[cx, fy, cz] V110 = table[cx, cy, fz] V111 = table[cx, cy, cz] # Expand dimensions for broadcasting x = x[:, None] y = y[:, None] z = z[:, None] # Tetrahedral interpolation - select tetrahedron based on position xyz_o = xp_select( [ xp.logical_and(x > y, y > z), xp.logical_and(x > z, z >= y), xp.logical_and(z >= x, x > y), xp.logical_and(y >= x, x > z), xp.logical_and(y >= z, z >= x), xp.logical_and(z > y, y >= x), ], [ (1 - x) * V000 + (x - y) * V100 + (y - z) * V110 + z * V111, (1 - x) * V000 + (x - z) * V100 + (z - y) * V101 + y * V111, (1 - z) * V000 + (z - x) * V001 + (x - y) * V101 + y * V111, (1 - y) * V000 + (y - x) * V010 + (x - z) * V110 + z * V111, (1 - y) * V000 + (y - z) * V010 + (z - x) * V011 + x * V111, (1 - z) * V000 + (z - y) * V001 + (y - x) * V011 + x * V111, ], xp=xp, ) return xp_reshape(xyz_o, original_shape, xp=xp)
TABLE_INTERPOLATION_METHODS = CanonicalMapping( { "Trilinear": table_interpolation_trilinear, "Tetrahedral": table_interpolation_tetrahedral, } ) TABLE_INTERPOLATION_METHODS.__doc__ = """ Supported table interpolation methods. References ---------- :cite:`Bourkeb`, :cite:`Kirk2006` """
[docs] def table_interpolation( V_xyz: ArrayLike, table: ArrayLike, method: Literal["Trilinear", "Tetrahedral"] | str = "Trilinear", ) -> NDArrayFloat: """ Perform interpolation of the specified :math:`V_{xyz}` values using a 4-dimensional interpolation table. Interpolate the input :math:`V_{xyz}` values through either trilinear or tetrahedral interpolation methods using the specified lookup table. Parameters ---------- V_xyz :math:`V_{xyz}` values to interpolate, where each row represents a three-dimensional coordinate within the interpolation table's domain. table 4-dimensional (NxNxNx3) interpolation table defining the mapping from input coordinates to output values. method Interpolation method to use. Either "Trilinear" for trilinear interpolation or "Tetrahedral" for tetrahedral interpolation. Returns ------- :class:`numpy.ndarray` Interpolated :math:`V_{xyz}` values with the same shape as the input array. References ---------- :cite:`Bourkeb`, :cite:`Kirk2006` Examples -------- >>> import os >>> import colour >>> path = os.path.join( ... os.path.dirname(__file__), ... "..", ... "..", ... "io", ... "luts", ... "tests", ... "resources", ... "iridas_cube", ... "Colour_Correct.cube", ... ) >>> LUT = colour.read_LUT(path) >>> table = LUT.table >>> prng = np.random.RandomState(4) >>> V_xyz = colour.algebra.random_triplet_generator(3, random_state=prng) >>> print(V_xyz) # doctest: +ELLIPSIS [[0.9670298... 0.7148159... 0.9762744...] [0.5472322... 0.6977288... 0.0062302...] [0.9726843... 0.2160895... 0.2529823...]] >>> table_interpolation(V_xyz, table) # doctest: +ELLIPSIS array([[1.0120664..., 0.7539146..., 1.0228540...], [0.5075794..., 0.6479459..., 0.1066404...], [1.0976519..., 0.1785998..., 0.2299897...]]) >>> table_interpolation(V_xyz, table, method="Tetrahedral") ... # doctest: +ELLIPSIS array([[1.0196197..., 0.7674062..., 1.0311751...], [0.5105603..., 0.6466722..., 0.1077296...], [1.1178206..., 0.1762039..., 0.2209534...]]) """ method = validate_method(method, tuple(TABLE_INTERPOLATION_METHODS)) return TABLE_INTERPOLATION_METHODS[method](V_xyz, table)
def linear_interpolation_index_and_factor( value: ArrayLike, break_points: ArrayLike ) -> tuple[NDArrayReal, NDArrayFloat]: """ Compute the bin index and fractional position for piecewise linear interpolation of *value* within sorted *break_points*. For each element in *value*, the returned ``index`` identifies the interval ``[break_points[index], break_points[index + 1])`` that contains the value, and ``factor`` gives the normalised position within that interval (0 at the left edge, 1 at the right). Values outside the range of *break_points* are clamped. Parameters ---------- value Query value(s), scalar or array. break_points Sorted array of break points defining the piecewise linear intervals. Returns ------- :class:`tuple` Tuple of ``(index, factor)`` arrays with the same shape as *value*. Examples -------- >>> break_points = np.array([0.0, 1.0, 2.0, 3.0]) >>> linear_interpolation_index_and_factor(1.5, break_points) ... # doctest: +ELLIPSIS (array(1...), array(0.5)) >>> linear_interpolation_index_and_factor( # doctest: +ELLIPSIS ... np.array([0.0, 0.5, 2.5, 3.0]), break_points ... ) (array([0, 0, 2, 3]...), array([0. , 0.5, 0.5, 0. ])) """ xp = array_namespace(value, break_points) value = xp_as_float_array(value, xp=xp, like=break_points) break_points = xp_as_float_array(break_points, xp=xp, like=value) clamped = xp.clip(value, break_points[0], break_points[-1]) # Upper bound search starting from break_points[1]. next_idx = ( xp_reshape( xp.searchsorted( break_points[1:], xp_reshape(clamped, (-1,), xp=xp), side="right", ), clamped.shape, xp=xp, ) + 1 ) at_end = next_idx >= len(break_points) index = xp.where(at_end, len(break_points) - 1, next_idx - 1) safe_next = xp.clip(next_idx, max=len(break_points) - 1) denominator = break_points[safe_next] - break_points[index] factor = xp.where( at_end | (denominator == 0), 0.0, (clamped - break_points[index]) / xp.where(denominator == 0, 1.0, denominator), ) return xp_astype(index, DTYPE_INT_DEFAULT, xp=xp), factor