Class CubicBezierSpline1

All Implemented Interfaces:
DoubleUnaryOperator, RealValuedDomainOps, RealValuedFunctOps, RealValuedFunctVAOps, VADomainOps

public class CubicBezierSpline1 extends CubicSpline
Class providing a cubic spline for an evenly spaced set of values, with each segment using a Bernstein Polynomial basis. This class provides the same functionality as the class CubicSpline1: the difference is in its internal representation. The method getBernsteinCoefficients() will provides more accurate values than the corresponding method CubicSpline1.getBernsteinCoefficients() due to eliminating the addition of terms that cancel, and those methods are used when a cubic spline is used to create an instance of SplinePath2D.

The spline approximates a function f such that y = f(x). When the values used to compute the spline are evenly spaced, look-up is faster than otherwise.

The spline can be created in any of several modes described by the enumeration CubicSpline.Mode. The default mode is "NATURAL", which sets the second derivatives (but not necessarily the third derivative) to zero at the end points. For all other modes, a constructor specifying a mode is required. Some modes base the spline not only on the values at specific points, but on the derivatives at all or a subset of these points. While defaults of zero are provided, normally one would use a constructor in these cases that take additional arguments that follow the mode argument. The mode HERMITE uses Hermite Cubic splines and these are specified by providing both the value at a each point and the derivative at each point. Other modes support clamped splines (where derivatives are specified for the end points) and parabolic and cubic run-outs (for a parabolic run-out, the second derivatives at an end point and its adjacent point are equal; for a cubic run-out, the two intervals closest to an end point are described by a single cubic equation).

For all but one of the supported modes, the second derivative of the spline (e.g., the function the spline computes) is a continuous function. The mode HERMITE is an exception: Hermite splines have continuous first derivatives, but second derivatives may have discontinuities.

Methods are available for determining the spline's mode, the minimum and maximum values it can compute, the value at a specified point, the derivative at a specified point, whether the values that define the spline are strictly monotonic, and (if the spline is strictly monotonic) the value of the spline's inverse at a particular point.

Citations:

Note: unfortunately, the notations used in the last two references differ from each other.

See Also:
  • Constructor Details

    • CubicBezierSpline1

      public CubicBezierSpline1(CallableArgsReturns<Double,Double> f, double x0, double x1, int n)
      Constructor given a function f(x). The function is represented by an instance of org.bzdev.lang.CallableArgsReturns.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
    • CubicBezierSpline1

      public CubicBezierSpline1(CallableArgsReturns<Double,Double> f, double x0, double x1, int n, CubicSpline.Mode mode)
      Constructor given a function f(x) and a mode. The function is represented by an instance of org.bzdev.lang.CallableArgsReturns.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
    • CubicBezierSpline1

      public CubicBezierSpline1(CallableArgsReturns<Double,Double> f, double x0, double x1, int n, CubicSpline.Mode mode, double derivative)
      Constructor given a function f(x), a mode, and a first derivative The function is represented by an instance of org.bzdev.lang.CallableArgsReturns. The mode must be one that requires at most one derivative.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative - the derivative at the edge specified by mode
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
    • CubicBezierSpline1

      public CubicBezierSpline1(CallableArgsReturns<Double,Double> f, double x0, double x1, int n, CubicSpline.Mode mode, double derivative1, double derivative2)
      Constructor given a function f(x), a mode, and a first derivative The function is represented by an instance of org.bzdev.lang.CallableArgsReturns. The mode must be one that requires at most two derivatives.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative1 - the derivative at the first edge
      derivative2 - the derivative at the second edge
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
    • CubicBezierSpline1

      public CubicBezierSpline1(CallableArgsReturns<Double,Double> f, double x0, double x1, int n, CubicSpline.Mode mode, CallableArgsReturns<Double,Double> fprime)
      Constructor given a function f(x), a mode, and a first derivative The function and its derivative are represented by instances of org.bzdev.lang.CallableArgsReturns.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      fprime - a CallableArgsReturns representing the derivative of the function for which a spline should be computed
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
    • CubicBezierSpline1

      public CubicBezierSpline1(RealValuedFunctOps f, double x0, double x1, int n)
      Constructor given a real-valued function.
      Parameters:
      f - the function to evaluate
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
    • CubicBezierSpline1

      public CubicBezierSpline1(RealValuedFunction f, double x0, double x1, int n, CubicSpline.Mode mode)
      Constructor given a real-valued function and a mode. For some modes, the RealValuedFunction f must provide a derivative. For all modes, it must provide a value.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
      UnsupportedOperationException - the real-valued function f did not provide a valueAt method or derivAt method
    • CubicBezierSpline1

      public CubicBezierSpline1(RealValuedFunctOps f, double x0, double x1, int n, CubicSpline.Mode mode, double derivative)
      Constructor given a real-valued function, a mode, and a first derivative
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative - the derivative at the edge specified by mode
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
      UnsupportedOperationException - the real-valued function f did not provide a valueAt method
    • CubicBezierSpline1

      public CubicBezierSpline1(RealValuedFunctOps f, double x0, double x1, int n, CubicSpline.Mode mode, double derivative1, double derivative2)
      Constructor given a function f(x), a mode, and a first derivative The function is represented by an instance of org.bzdev.lang.CallableArgsReturns.
      Parameters:
      f - a CallableArgsReturns representing a function for which a spline should be computed
      x0 - the first end point in the function's domain
      x1 - the second end point in the function's domain
      n - the number of points to use in the spline
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative1 - the derivative at the first edge
      derivative2 - the derivative at the second edge
      Throws:
      IllegalArgumentException - n < 2 or an error occurred while evaluating the function.
      UnsupportedOperationException - the real-valued function f did not provide a valueAt method
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, double x0, double deltax)
      Constructor given an array. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, double x0, double deltax, CubicSpline.Mode mode, double derivative)
      Constructor given an array, mode, and derivative. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative - the derivative at the edge specified by mode
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, double x0, double deltax, CubicSpline.Mode mode, double derivative1, double derivative2)
      Constructor given an array, mode, and two derivatives. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative1 - the derivative at the first edge
      derivative2 - the derivative at the second edge
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, double x0, double deltax, CubicSpline.Mode mode)
      Constructor given an array and mode. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, int n, double x0, double deltax)
      Constructor given an array and the number of points in the array to use. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      n - the number of indices in y that will be used
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, int n, double x0, double deltax, CubicSpline.Mode mode)
      Constructor given an array and the number of points in the array to use and a mode. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      n - the number of indices in y that will be used
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, int n, double x0, double deltax, CubicSpline.Mode mode, double derivative)
      Constructor given an array and the number of points in the array to use, a mode and the value of a derivative. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      n - the number of indices in y that will be used
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative - the derivative at either the start or the end of the spline, depending on the mode
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, int n, double x0, double deltax, CubicSpline.Mode mode, double derivative1, double derivative2)
      Constructor given an array and the number of points in the array to use, a mode and the value of two derivatives. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      n - the number of indices in y that will be used
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      derivative1 - the derivative at the first edge
      derivative2 - the derivative at the second edge
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, int n, double x0, double deltax, CubicSpline.Mode mode, double[] yp)
      Constructor given an array and the number of points in the array to use, a mode and an array of derivatives. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      n - the number of indices in y that will be used
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      yp - the derivatives corresponding to each element of y for the fully clamped case and the appropriate number of derivatives otherwise
    • CubicBezierSpline1

      public CubicBezierSpline1(double[] y, double x0, double deltax, CubicSpline.Mode mode, double[] yp)
      Constructor given an array, a mode and an array of derivatives. The indices used to compute the spline are in the range [0,n). for an index i, the corresponding value of x is x0 + i*deltax and y[i] will be equal to f(x).
      Parameters:
      y - the values at equally spaced points
      x0 - the argument corresponding to index 0 of the array y
      deltax - the difference in the argument corresponding to successive indices of y
      mode - the mode for the spline as described in the API documentation for CubicSpline.Mode.
      yp - the derivatives corresponding to each element of y for the fully clamped case and the appropriate number of derivatives otherwise
  • Method Details

    • getDomainMin

      public double getDomainMin()
      Description copied from class: RealValuedFunction
      Get the minimum value in the domain of the function.
      Specified by:
      getDomainMin in interface RealValuedDomainOps
      Overrides:
      getDomainMin in class RealValuedFunction
      Returns:
      the minimum value
    • getDomainMax

      public double getDomainMax()
      Description copied from interface: RealValuedDomainOps
      Get the maximum value in the domain of the function.
      Specified by:
      getDomainMax in interface RealValuedDomainOps
      Overrides:
      getDomainMax in class RealValuedFunction
      Returns:
      the maximum value
    • getMode

      public CubicSpline.Mode getMode()
      Get the spline's mode.
      Specified by:
      getMode in class CubicSpline
      Returns:
      the mode for the spline.
      See Also:
    • countKnots

      public int countKnots()
      Description copied from class: CubicSpline
      Count the number of knots in this spline.
      Specified by:
      countKnots in class CubicSpline
      Returns:
      the number of knots
    • getBernsteinCoefficients

      public double[] getBernsteinCoefficients()
      Description copied from class: CubicSpline
      Get the coefficients βi for the segments of this spline when represented as a sum of Bernstein polynomials $\sum^3_{i=0}\beta_i B_{i,3}(t)$ where t∈[0,1].

      There are 4 coefficients per segment, but for a spline, the last coefficient of one segment is the first for the next. With the exception of the initial coefficient, the first coefficient for each segment is not listed, to avoid duplications. The value of the coefficients match the points the spline is guaranteed to pass through at indices 0, 3, 6, 9, etc. These represent the i=0 case in the sum given above. For segment j, βi = array[3*j + i] for i ∈ [0,3] and j ∈ [0, n], where n is the number of segments.

      One use of this method is to provide the control points for a path - for example, the classes Path2D, Path3D, and their subclasses.

      Specified by:
      getBernsteinCoefficients in class CubicSpline
      Returns:
      the coefficients
    • valueAt

      public double valueAt(double x) throws IllegalArgumentException
      Compute the value of the spline for a specified argument.
      Specified by:
      valueAt in interface RealValuedFunctOps
      Overrides:
      valueAt in class RealValuedFunction
      Parameters:
      x - the value at which to evaluate the spline
      Returns:
      the value at x
      Throws:
      IllegalArgumentException - the argument was out of range.
    • derivAt

      public double derivAt(double x) throws IllegalArgumentException
      Compute the value of derivative of the spline for a specified argument.
      Overrides:
      derivAt in class RealValuedFunction
      Parameters:
      x - the value at which to evaluate the derivative
      Returns:
      the value at x
      Throws:
      IllegalArgumentException - the argument was out of range.
    • secondDerivAt

      public double secondDerivAt(double x) throws IllegalArgumentException
      Compute the value of second derivative of the spline for a specified argument.
      Overrides:
      secondDerivAt in class RealValuedFunction
      Parameters:
      x - the value at which to evaluate the second derivative
      Returns:
      the value at x
      Throws:
      IllegalArgumentException - the argument was out of range.
    • verify

      public boolean verify(double limit)
      Verify that the spline's polynomials compute various values consistently to an accuracy given by the argument The cubic polynomials that the spline uses are supposed to compute the same value, first derivative, and second derivative where they meet, and each mode places constraints on the end points.
      Specified by:
      verify in class CubicSpline
      Parameters:
      limit - the accuracy limit
      Returns:
      true of the tests succeed; false otherwise
    • isStrictlyMonotonic

      public boolean isStrictlyMonotonic()
      Description copied from class: CubicSpline
      Determine if the values defining a spline form a strictly monotonic sequence of numbers.
      Specified by:
      isStrictlyMonotonic in class CubicSpline
      Returns:
      true if the values are strictly monotonic; false otherwise
    • getInversionLimit

      public double getInversionLimit()
      Get the inversion limit. Computing the inverse in most cases requires solving a cubic equation, with valid solutions being in the range [0, 1]. The inversion limit allows solutions in the range [-inversionLimit, 1+inversionLimit] to be accepted, with values outside of the interval [0, 1] replaced by 0 or 1, whichever is closer. The use of an inversion limit allows for round-off errors.
      Specified by:
      getInversionLimit in class CubicSpline
      Returns:
      the inversion limit
    • setInversionLimit

      public void setInversionLimit(double limit)
      Set the inversion limit. Computing the inverse in most cases requires solving a cubic equation, with valid solutions being in the range [0, 1]. The inversion limit allows solutions in the range [-inversionLimit, 1+inversionLimit] to be accepted, with values outside of the interval [0, 1] replaced by 0 or 1, whichever is closer. The use of an inversion limit allows for round-off errors.
      Specified by:
      setInversionLimit in class CubicSpline
      Parameters:
      limit - the invrsion limit
    • inverseAt

      public double inverseAt(double y)
      For a spline that represents the function y = f(x), get the value of its inverse x=f-1(y).
      Specified by:
      inverseAt in class CubicSpline
      Parameters:
      y - the argument for the inverse function
      Returns:
      the inverse evaluated at y
      Throws:
      IllegalArgumentException - an inverse could not be computed.