Class BicubicInterpolator

All Implemented Interfaces:
DoubleBinaryOperator, RealValuedFunctTwoOps, RealValuedFunctVAOps, VADomainOps

public class BicubicInterpolator extends RealValuedFunctionTwo
Bicubic Interpolation class.

This class constructs a real-valued function f with two arguments u and v that implements bicubic interpolation: approximation of a function over a rectangular interval using a cubic polynomial. The default range for the interpolation limits both u and v to the interval [0,1], although the implementation will allow values to be computed outside this range. The interpolation function is the sum over i and j, with both in the range [0,3] of the term aijuivj.

The algorithm is described in Bicubic Interpolation.

For convenience, a constructor allows coordinates (x, y) to be used where x and y vary between two values, one corresponding to u = 0 or v = 0, and the other corresponding to u = 1 or v = 1.

The function this class implements is valid on R2 but is a good approximation over a finite rectangular subset of R2. The methods getDomainMin1(), getDomainMin2(), getDomainMax1(), and getDomainMax2() provide the lower and upper bounds for this rectangle.

The algorithm described above requires 16 values to construct the interpolator: the values of f, f1, f2, and f12 at the corners of a rectangle, where the subscripts of f denote partial derivatives with respect to the first and second arguments.

Specific cases where fewer values are available can be handled as well. If f12(1,0), f12(0,1) and f12(1,1) are missing, one computes the sum over i and j of aijuivj where both i and j are in the range [0,3] and where i+j≤4. This yields the following 13 equations:

  • f(0,0) = 0 + a00.
  • f(1,0) = 0 + a00 + a10. + a20 + a30.
  • f(0,1) = 0 + a00 + a01 + a02 + a03.
  • f(1,1) = 0 + a00 + a01 + a02 + a03 + a10 + a11 + a12 + a13 + a20 + a21 + a22 + a30 + a31.
  • f1(0,0) = 0 + a10.
  • f1(1,0) = 0 + a10 + 2a20 + 3a30.
  • f(0,1) = 0 + a10 + a11 + a12 + a13.
  • f1(1,1) = 0 + a10 + a11 + a12 + a13 + 2a20 + 2a21 + 2a22 + 3a30 + 3a31.
  • f2(0,0) = 0 + a01.
  • f2(1,0) = 0 + a01 + a11 + a21 + a31.
  • f2(0,1) = 0 + a01 + 2a02 + 3a03.
  • f2(1,1) = 0 + a01 + 2a02 + 3a03 + a11 + 2a12 + 3a13 + a21 + 2a22 + a31.
  • f12(0,0) = 0 + a11.
These can be solved for the coefficients aij.

A matrix representation of cubic Bézier patches is described in A matrix representation of a cubic bézier patch.

The interpolated value of f(u,v) can be written as $$ (1\ u \ u^2 \ u^3) M P M^T \left( \begin{array}{c} 1 \\ v \\ v^2 \\ v^3 \end{array} \right)$$ where M is a constant matrix given in the citation and P is a matrix of control points. The interpolated value is Pi,jBi,3(u)Bj,3(v) summed over i and j from 0 to 3 inclusive. The functions $B_{k,n}$ are Bernstein polynomials defined by $$ B_{k,n}(t) = \left(\begin{array}{c} n \\ k\end{array}\right) t^k (1-t)^{n-i}$$. Because this interpolator produces a real value, the control points are one dimensional (for the multidimensional case, each component is handled separately).

  • Constructor Details

    • BicubicInterpolator

      public BicubicInterpolator(double[] inits) throws IllegalArgumentException
      Constructor. The values and derivatives are computed at the points (0,0), (1,0), (0,1) and (1,1), which are the corners of the interpolation region. For the function f being interpolated, the argument is an array whose values are as follows:
      • inits[0] = f(0,0).
      • inits[1] = f(1,0).
      • inits[2] = f(0,1).
      • inits[3] = f(1,1);
      • inits[4] = f1(0,0)
      • inits[5] = f1(1,0)
      • inits[6] = f1(0,1)
      • inits[7] = f1(1,1)
      • inits[8] = f2(0,0)
      • inits[9] = f2(1,0)
      • inits[10] = f2(0,1)
      • inits[11] = f2(1,1)
      • inits[12] = f12(0,0)
      • inits[13] = f12(1,0)
      • inits[14] = f12(0,1)
      • inits[15] = f12(1,1)
      where the subscripts for f denote partial derivatives with respect to the first and/or second arguments.

      If only inits[0] to inits[11] are provided, inits[12], inits[13], inits[14], and inits[15] are assumed to be zero, making the interpolation as close to linear as possible at the vertices.

      Parameters:
      inits - the values of the function and various partial derivatives at the corners of the interpolation region
      Throws:
      IllegalArgumentException - the array argument had the wrong length;
    • BicubicInterpolator

      public BicubicInterpolator(double[][] controlPoints)
      Constructor given Bézier control points.
      Parameters:
      controlPoints - the control points (a 4×4 array)
      Throws:
      IllegalArgumentException - the argument had the wrong length;
    • BicubicInterpolator

      public BicubicInterpolator(double xmin, double xmax, double ymin, double ymax, double[] inits) throws IllegalArgumentException
      Constructor given an interpolation region. The values and derivatives are computed at the points (xmin, ymin), (xmax, ymin), (xmin, ymax) and (xmax, ymax), which are the corners of the interpolation region, corresponding to the normalized parameters u and v with values (0, 0, (1, 0), (0, 1), and (1, 1) respectively. For the function f being interpolated, the argument is an array whose values are as follows:
      • inits[0] = f(xmin, ymin).
      • inits[1] = f(xmax, ymin).
      • inits[2] = f(xmin, ymax).
      • inits[3] = f(xmax, ymax);
      • inits[4] = f1(xmin, ymin)
      • inits[5] = f1(xmax, ymin)
      • inits[6] = f1(xmin, ymax)
      • inits[7] = f1(xmax, ymax)
      • inits[8] = f2(xmin, ymin)
      • inits[9] = f2(xmax, ymin)
      • inits[10] = f2(xmin, ymax)
      • inits[11] = f2(xmax, ymax)
      • inits[12] = f12(xmin, ymin)
      • inits[13] = f12(xmax, ymin)
      • inits[14] = f12(xmin, ymax)
      • inits[15] = f12(xmax, ymax)
      where the subscripts for f denote partial derivatives with respect to the first and/or second arguments.

      If only inits[0] to inits[12] are provided, in which case the inits array's length will be 13, the polynomial approximation aijxiyj, summed over i and j, will include terms such at 0 ≤ i ≤ 3, 0 ≤ j ≤ 3, and i+j ≤ 4: if i+j > 4, aij will be zero. If the array length is 12, so that inits[12] is not available, its value will be estimated.

      Parameters:
      xmin - the bound on the interpolation region, corresponding to u = 0, for the first argument of f
      xmax - the bound on the interpolation region, corresponding to u = 1, for the first argument of f
      ymin - the bound on the interpolation region, corresponding to v = 0, for the second argument of f
      ymax - the bound on the interpolation region, corresponding to v = 1, for the second argument of f
      inits - the values of the function and various partial derivatives at the corners of the interpolation region
      Throws:
      IllegalArgumentException - the array argument had the wrong length;
  • Method Details

    • getControlPoints

      public double[][] getControlPoints()
      Get the Bézier control points for this bicubic interpolator. This is a one-dimensional case, so the control points are just numbers.
      Returns:
      a matrix containing the control points
    • getControlPoints

      public double[] getControlPoints(boolean colOrder)
      Get the Bézier control points for this bicubic interpolator. This is a one-dimensional case, so the control points are just numbers.

      When colOrder is true, the ordering is the one used in the geom package.

      Parameters:
      colOrder - true if the elements of each column are adjacent in the the array; false if the elements of each row are adjacent
      Returns:
      a matrix containing the control points
    • getDomainMin1

      public double getDomainMin1()
      Get the lower bound of the first argument of the interpolated region.
      Overrides:
      getDomainMin1 in class RealValuedFunctionTwo
      Returns:
      the lower bound
    • getDomainMax1

      public double getDomainMax1()
      Get the upper bound of the first argument of the interpolated region.
      Overrides:
      getDomainMax1 in class RealValuedFunctionTwo
      Returns:
      the upper bound
    • getDomainMin2

      public double getDomainMin2()
      Get the lower bound of the second argument of the interpolated region.
      Overrides:
      getDomainMin2 in class RealValuedFunctionTwo
      Returns:
      the lower bound
    • getDomainMax2

      public double getDomainMax2()
      Get the upper bound of the second argument of the interpolated region.
      Overrides:
      getDomainMax2 in class RealValuedFunctionTwo
      Returns:
      the upper bound
    • valueAt

      public double valueAt(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Call the function.
      Specified by:
      valueAt in interface RealValuedFunctTwoOps
      Overrides:
      valueAt in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the function for the given arguments
    • deriv1At

      public double deriv1At(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Evaluate the partial derivative $\frac{\partial f}{\partial x_1}$ for a function f(x1, x2).
      Overrides:
      deriv1At in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the partial derivative for the given argument
    • deriv2At

      public double deriv2At(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Evaluate the partial derivative $\frac{\partial f}{\partial x_2}$ for a function f(x1,x2).
      Overrides:
      deriv2At in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the partial derivative for the given argument
    • deriv11At

      public double deriv11At(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Evaluate the partial derivative $ \frac{\partial^2 f}{\partial x_1^2}$ for a function f(x1,x2).
      Overrides:
      deriv11At in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the partial derivative for the given argument
    • deriv12At

      public double deriv12At(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_1 \partial x_2}$ for a function f(x1,x2).
      Overrides:
      deriv12At in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the partial derivative for the given argument
    • deriv21At

      public double deriv21At(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_2 \partial x_1}$ for a function f(x1,x2).
      Overrides:
      deriv21At in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the partial derivative for the given argument
    • deriv22At

      public double deriv22At(double x, double y)
      Description copied from class: RealValuedFunctionTwo
      Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_2^2}$ for a function f(x1,x2).
      Overrides:
      deriv22At in class RealValuedFunctionTwo
      Parameters:
      x - the function's first argument
      y - the function's second argument
      Returns:
      the value of the partial derivative for the given argument