Module org.bzdev.math

Package org.bzdev.math

Class BicubicInterpolator

java.lang.Object

org.bzdev.math.RealValuedFunctionVA

org.bzdev.math.RealValuedFunctionTwo

org.bzdev.math.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 a_ijuⁱv^j.

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 R² but is a good approximation over a finite rectangular subset of R². 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, f₁, f₂, and f₁₂ 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 f₁₂(1,0), f₁₂(0,1) and f₁₂(1,1) are missing, one computes the sum over i and j of a_ijuⁱv^j 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 + a₀₀.
• f(1,0) = 0 + a₀₀ + a₁₀. + a₂₀ + a₃₀.
• f(0,1) = 0 + a₀₀ + a₀₁ + a₀₂ + a₀₃.
• f(1,1) = 0 + a₀₀ + a₀₁ + a₀₂ + a₀₃ + a₁₀ + a₁₁ + a₁₂ + a₁₃ + a₂₀ + a₂₁ + a₂₂ + a₃₀ + a₃₁.
• f1(0,0) = 0 + a₁₀.
• f1(1,0) = 0 + a₁₀ + 2a₂₀ + 3a₃₀.
• f(0,1) = 0 + a₁₀ + a₁₁ + a₁₂ + a₁₃.
• f1(1,1) = 0 + a₁₀ + a₁₁ + a₁₂ + a₁₃ + 2a₂₀ + 2a₂₁ + 2a₂₂ + 3a₃₀ + 3a₃₁.
• f2(0,0) = 0 + a₀₁.
• f2(1,0) = 0 + a₀₁ + a₁₁ + a₂₁ + a₃₁.
• f2(0,1) = 0 + a₀₁ + 2a₀₂ + 3a₀₃.
• f2(1,1) = 0 + a₀₁ + 2a₀₂ + 3a₀₃ + a₁₁ + 2a₁₂ + 3a₁₃ + a₂₁ + 2a₂₂ + a₃₁.
• f12(0,0) = 0 + a₁₁.

These can be solved for the coefficients a_ij.

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 P_i,jB_i,3(u)B_j,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).

Nested Class Summary

Nested classes/interfaces inherited from class org.bzdev.math.RealValuedFunctionVA

RealValuedFunctionVA.Linear

Constructor Summary

Constructors

Constructor	Description
BicubicInterpolator(double[] inits)	Constructor.
BicubicInterpolator(double[][] controlPoints)	Constructor given Bézier control points.
BicubicInterpolator(double xmin, double xmax, double ymin, double ymax, double[] inits)	Constructor given an interpolation region.

Method Summary

Modifier and Type	Method	Description
double	deriv11At(double x, double y)	Evaluate the partial derivative $ \frac{\partial^2 f}{\partial x_1^2}$ for a function f(x1,x2).
double	deriv12At(double x, double y)	Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_1 \partial x_2}$ for a function f(x1,x2).
double	deriv1At(double x, double y)	Evaluate the partial derivative $\frac{\partial f}{\partial x_1}$ for a function f(x1, x2).
double	deriv21At(double x, double y)	Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_2 \partial x_1}$ for a function f(x1,x2).
double	deriv22At(double x, double y)	Evaluate the partial derivative $\frac{\partial^2 f}{\partial x_2^2}$ for a function f(x1,x2).
double	deriv2At(double x, double y)	Evaluate the partial derivative $\frac{\partial f}{\partial x_2}$ for a function f(x1,x2).
double[][]	getControlPoints()	Get the Bézier control points for this bicubic interpolator.
double[]	getControlPoints(boolean colOrder)	Get the Bézier control points for this bicubic interpolator.
double	getDomainMax1()	Get the upper bound of the first argument of the interpolated region.
double	getDomainMax2()	Get the upper bound of the second argument of the interpolated region.
double	getDomainMin1()	Get the lower bound of the first argument of the interpolated region.
double	getDomainMin2()	Get the lower bound of the second argument of the interpolated region.
double	valueAt(double x, double y)	Call the function.

Methods inherited from class org.bzdev.math.RealValuedFunctionTwo

deriv, deriv1, deriv11, deriv12, deriv2, deriv21, deriv22, derivAt, domainMax1Closed, domainMax2Closed, domainMaxClosed, domainMin1Closed, domainMin2Closed, domainMinClosed, getDomainMax, getDomainMin, isInDomain, isInDomain, secondDeriv, secondDerivAt, valueAt

Methods inherited from class org.bzdev.math.RealValuedFunctionVA

jacobian, jacobian, maxArgLength, minArgLength

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.bzdev.math.RealValuedFunctTwoOps

applyAsDouble, maxArgLength, minArgLength

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] = f₁(0,0)
• inits[5] = f₁(1,0)
• inits[6] = f₁(0,1)
• inits[7] = f₁(1,1)
• inits[8] = f₂(0,0)
• inits[9] = f₂(1,0)
• inits[10] = f₂(0,1)
• inits[11] = f₂(1,1)
• inits[12] = f₁₂(0,0)
• inits[13] = f₁₂(1,0)
• inits[14] = f₁₂(0,1)
• inits[15] = f₁₂(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] = f₁(xmin, ymin)
• inits[5] = f₁(xmax, ymin)
• inits[6] = f₁(xmin, ymax)
• inits[7] = f₁(xmax, ymax)
• inits[8] = f₂(xmin, ymin)
• inits[9] = f₂(xmax, ymin)
• inits[10] = f₂(xmin, ymax)
• inits[11] = f₂(xmax, ymax)
• inits[12] = f₁₂(xmin, ymin)
• inits[13] = f₁₂(xmax, ymin)
• inits[14] = f₁₂(xmin, ymax)
• inits[15] = f₁₂(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 a_ijxⁱy^j, summed over i and j, will include terms such at 0 ≤ i ≤ 3, 0 ≤ j ≤ 3, and i+j ≤ 4: if i+j > 4, a_ij 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(x₁, x₂).

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(x₁,x₂).

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(x₁,x₂).

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(x₁,x₂).

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(x₁,x₂).

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(x₁,x₂).

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