Package org.apache.sis.internal.referencing.j2d

Class Bezier

java.lang.Object
org.apache.sis.internal.referencing.j2d.Bezier
public abstract class Bezier extends Object
Helper class for appending Bézier curves to a path. This class computes cubic Bézier from 3 points and two slopes. The three points are the start point (t=0), middle point (t=½) and end point (t=1). The slopes are at start point and end point. The Bézier curve will obey exactly to those conditions (up to rounding errors).

After creating each Bézier curve, this class performs a quality control using 2 additional points located at one quarter (t≈¼) and three quarters (t≈¾) of the curve. If the distance between given points and a close point on the curve is greater than εx and εy thresholds, then the curve is divided in two smaller curves and the process is repeated until curves meet the quality controls.

If a quadratic curve degenerates to a cubic curve or a straight line, ignoring errors up to εx and εy, then CubicCurve2D are replaced by QuadCurve2D or Line2D.

Since:
1.0
Version:
1.0
Author:
Martin Desruisseaux (Geomatys)
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected int
    depth
    The number of times a curve has been divided in smaller curves.
    protected double
    dx
    Components of α=(∂y/∂x) derivative at the point evaluated by evaluateAt(double).
    protected double
    dy
    Components of α=(∂y/∂x) derivative at the point evaluated by evaluateAt(double).
    protected boolean
    forceCubic
    Whether to force the creation of QuadCurve2D.
    protected final double[]
    point
    A buffer used by subclasses for storing results of evaluateAt(double).
    protected double
    εx
    Maximal distance (approximate) on x and y axis between Bézier curves and desired curve.
    protected double
    εy
    Maximal distance (approximate) on x and y axis between Bézier curves and desired curve.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Bezier(int dimension)
    Creates a new builder.

  • Method Summary

    Modifier and Type
    Method
    Description
    final Path2D
    build()
    Creates a sequence of Bézier curves from the position given by evaluateAt(0) to the position given by evaluateAt(1).
    protected abstract void
    evaluateAt(double t)
    Invoked for computing a new point on the Bézier curve.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • εx

      protected double εx
      Maximal distance (approximate) on x and y axis between Bézier curves and desired curve. Also used for deciding if a cubic Bézier curve can be simplified to quadratic curve or straight line. Initial value is zero. Subclasses should set the values either in their constructor or at evaluateAt(double) method call. Can be set to infinity or NaN for disabling the quality checks, or to negative value for forcing unconditional divisions of Bézier curves in two sub-curves.

    • εy

      protected double εy
      Maximal distance (approximate) on x and y axis between Bézier curves and desired curve. Also used for deciding if a cubic Bézier curve can be simplified to quadratic curve or straight line. Initial value is zero. Subclasses should set the values either in their constructor or at evaluateAt(double) method call. Can be set to infinity or NaN for disabling the quality checks, or to negative value for forcing unconditional divisions of Bézier curves in two sub-curves.

    • dx

      protected double dx
      Components of α=(∂y/∂x) derivative at the point evaluated by evaluateAt(double).

    • dy

      protected double dy
      Components of α=(∂y/∂x) derivative at the point evaluated by evaluateAt(double).

    • point

      protected final double[] point
      A buffer used by subclasses for storing results of evaluateAt(double). The two first elements are x and y coordinates respectively. Other elements (if any) are ignored.

    • depth

      protected int depth
      The number of times a curve has been divided in smaller curves.
      See Also:
      • DEPTH_LIMIT

    • forceCubic

      protected boolean forceCubic
      Whether to force the creation of QuadCurve2D. The default value is false, which allows simplification to CubicCurve2D or Line2D. This flag can be set to true when building circular shapes, in which case simplifications to CubicCurve2D produce bad results.

  • Constructor Details

    • Bezier

      protected Bezier(int dimension)
      Creates a new builder.
      Parameters:
      dimension - length of the point array. Must be at least 2.

  • Method Details

    • evaluateAt

      protected abstract void evaluateAt(double t) throws org.opengis.referencing.operation.TransformException
      Invoked for computing a new point on the Bézier curve. This method is invoked with a t value varying from 0 to 1 inclusive. Value 0 is for the starting point and value 1 is for the ending point. Other values are for points interpolated between the start and end points. In particular value ½ is for the point in the middle of the curve. This method will also be invoked at least for values ¼ and ¾, and potentially for other values too.

      This method shall store the point coordinates in the point array with x coordinate in the first element and y coordinate in the second element. This method shall also store derivative (∂y/∂x) at that location in the dx and dy fields. If this method cannot compute a coordinate, it can store Double.NaN values except for t=0, ½ and 1 where finite coordinates are mandatory.

      Subclasses can optionally update the εx and εy values if the tolerance thresholds change as a result of this method call, for example because we come closer to a pole. The tolerance values used for each Bézier curve are the ones computed at t=¼ and t=¾ of that curve.

      Parameters:
      t - desired point on the curve, from 0 (start point) to 1 (end point) inclusive.
      Throws:
      org.opengis.referencing.operation.TransformException - if the point coordinates cannot be computed.

    • build

      public final Path2D build() throws org.opengis.referencing.operation.TransformException
      Creates a sequence of Bézier curves from the position given by evaluateAt(0) to the position given by evaluateAt(1). This method determines the number of intermediate points required for achieving the precision requested by the εx and εy parameters given at construction time.
      Returns:
      the sequence of Bézier curves.
      Throws:
      org.opengis.referencing.operation.TransformException - if the coordinates of a point cannot be computed.