ianmackenzie / elm-geometry / CubicSpline2d

A CubicSpline2d is a cubic Bézier curve in 2D defined by a start point, end point and two inner control points. This module contains functionality for


type alias CubicSpline2d units coordinates =
Geometry.Types.CubicSpline2d units coordinates

Constructors

fromControlPoints : Point2d units coordinates -> Point2d units coordinates -> Point2d units coordinates -> Point2d units coordinates -> CubicSpline2d units coordinates

Construct a spline from its four control points:

exampleSpline =
    CubicSpline2d.fromControlPoints
        (Point2d.meters 1 1)
        (Point2d.meters 3 4)
        (Point2d.meters 5 1)
        (Point2d.meters 7 4)

fromEndpoints : Point2d units coordinates -> Vector2d units coordinates -> Point2d units coordinates -> Vector2d units coordinates -> CubicSpline2d units coordinates

Construct a spline from a given start point with a given start derivative, to a given end point with a given end derivative, like so:

Cubic spline from endpoints

The spline is based on a parameter that ranges from 0 to 1; as a result, in most cases the length of each derivative vector should be roughly equal to the length of the resulting spline.

fromQuadraticSpline : QuadraticSpline2d units coordinates -> CubicSpline2d units coordinates

Convert a quadratic spline into the equivalent cubic spline (every quadratic spline can be represented exactly as a cubic spline).

quadraticSpline =
    QuadraticSpline2d.fromControlPoints
        Point2d.origin
        (Point2d.meters 3 0)
        (Point2d.meters 3 3)

CubicSpline2d.fromQuadraticSpline quadraticSpline
--> CubicSpline2d.fromControlPoints
-->     Point2d.origin
-->     (Point2d.meters 2 0)
-->     (Point2d.meters 3 1)
-->     (Point2d.meters 3 3)

B-splines

bSplineSegments : List Basics.Float -> List (Point2d units coordinates) -> List (CubicSpline2d units coordinates)

Construct a B-spline from a list of knot values and a list of control points, and return the individual segments of that B-spline as a list.

The number of knots should be two greater than the number of control points; any extra knots or control points will be dropped. In most cases the first and last knots will be repeated three times; for example, the knots

[ 0, 0, 0, 1, 2, 3, 4, 4, 4 ]

could be used along with 7 control points to form 4 spline segments.

Note that a popular alternate convention uses two extra 'dummy' knot values at the start and end, so if you see an example where the number of knots is four greater than the number of control points (especially if you also notice that the first and last knots are repeated four times instead of three!) then you should drop the first and last knot values.

Knot values should be given in ascending order but will be sorted if necessary.

bSplineIntervals : List Basics.Float -> List (Interval Basics.Float)

For a given set of B-spline knots, return the corresponding intervals between knots that correspond to individual spline segments.

Properties

startPoint : CubicSpline2d units coordinates -> Point2d units coordinates

Get the start point of a spline. Equal to firstControlPoint.

firstControlPoint : CubicSpline2d units coordinates -> Point2d units coordinates

Get the first control point of the spline. Equal to startPoint.

secondControlPoint : CubicSpline2d units coordinates -> Point2d units coordinates

Get the second control point of the spline.

thirdControlPoint : CubicSpline2d units coordinates -> Point2d units coordinates

Get the third control point of the spline.

fourthControlPoint : CubicSpline2d units coordinates -> Point2d units coordinates

Get the fourth and last control point of the spline. Equal to endPoint.

endPoint : CubicSpline2d units coordinates -> Point2d units coordinates

Get the end point of a spline. Equal to fourthControlPoint.

startDerivative : CubicSpline2d units coordinates -> Vector2d units coordinates

Get the start derivative of a spline. This is equal to three times the vector from the spline's start point to its start control point.

CubicSpline2d.startDerivative exampleSpline
--> Vector2d.meters 6 9

endDerivative : CubicSpline2d units coordinates -> Vector2d units coordinates

Get the end derivative of a spline. This is equal to three times the vector from the spline's end control point to its end point.

CubicSpline2d.endDerivative exampleSpline
--> Vector2d.meters 6 9

boundingBox : CubicSpline2d units coordinates -> BoundingBox2d units coordinates

Compute a bounding box for a given spline. It is not guaranteed that the result will be the smallest possible bounding box, since for efficiency the bounding box is computed from the spline's control points (which cover a larger area than the spline itself).

CubicSpline2d.boundingBox exampleSpline
--> BoundingBox2d.from
-->     (Point2d.meters 1 1)
-->     (Point2d.meters 7 4)

Evaluation

pointOn : CubicSpline2d units coordinates -> Basics.Float -> Point2d units coordinates

Get the point along a spline at a given parameter value.


type Nondegenerate units coordinates

Represents a nondegenerate spline (one that has finite, non-zero length).

nondegenerate : CubicSpline2d units coordinates -> Result (Point2d units coordinates) (Nondegenerate units coordinates)

Attempt to construct a nondegenerate spline from a general CubicSpline2d. If the spline is in fact degenerate (consists of a single point), returns an Err with that point.

fromNondegenerate : Nondegenerate units coordinates -> CubicSpline2d units coordinates

Convert a nondegenerate spline back to a general CubicSpline2d.

tangentDirection : Nondegenerate units coordinates -> Basics.Float -> Direction2d coordinates

Get the tangent direction to a nondegenerate spline at a given parameter value.

sample : Nondegenerate units coordinates -> Basics.Float -> ( Point2d units coordinates, Direction2d coordinates )

Get both the point and tangent direction of a nondegenerate spline at a given parameter value.

Linear approximation

segments : Basics.Int -> CubicSpline2d units coordinates -> Polyline2d units coordinates

Approximate a cubic spline by a given number of line segments. Note that the number of points in the polyline will be one more than the number of segments.

approximate : Quantity Basics.Float units -> CubicSpline2d units coordinates -> Polyline2d units coordinates

Approximate a cubic spline as a polyline, within a given tolerance. Every point on the returned polyline will be within the given tolerance of the spline.

Transformations

These transformations generally behave just like the ones in the Point2d module.

reverse : CubicSpline2d units coordinates -> CubicSpline2d units coordinates

Reverse a spline so that the start point becomes the end point, and vice versa.

scaleAbout : Point2d units coordinates -> Basics.Float -> CubicSpline2d units coordinates -> CubicSpline2d units coordinates

Scale a spline about the given center point by the given scale.

rotateAround : Point2d units coordinates -> Angle -> CubicSpline2d units coordinates -> CubicSpline2d units coordinates

Rotate a spline counterclockwise around a given center point by a given angle.

translateBy : Vector2d units coordinates -> CubicSpline2d units coordinates -> CubicSpline2d units coordinates

Translate a spline by a given displacement.

translateIn : Direction2d coordinates -> Quantity Basics.Float units -> CubicSpline2d units coordinates -> CubicSpline2d units coordinates

Translate a spline in a given direction by a given distance.

mirrorAcross : Axis2d units coordinates -> CubicSpline2d units coordinates -> CubicSpline2d units coordinates

Mirror a spline across an axis.

Unit conversions

at : Quantity Basics.Float (Quantity.Rate units2 units1) -> CubicSpline2d units1 coordinates -> CubicSpline2d units2 coordinates

Convert a spline from one units type to another, by providing a conversion factor given as a rate of change of destination units with respect to source units.

at_ : Quantity Basics.Float (Quantity.Rate units1 units2) -> CubicSpline2d units1 coordinates -> CubicSpline2d units2 coordinates

Convert a spline from one units type to another, by providing an 'inverse' conversion factor given as a rate of change of source units with respect to destination units.

Coordinate conversions

relativeTo : Frame2d units globalCoordinates { defines : localCoordinates } -> CubicSpline2d units globalCoordinates -> CubicSpline2d units localCoordinates

Take a spline defined in global coordinates, and return it expressed in local coordinates relative to a given reference frame.

placeIn : Frame2d units globalCoordinates { defines : localCoordinates } -> CubicSpline2d units localCoordinates -> CubicSpline2d units globalCoordinates

Take a spline considered to be defined in local coordinates relative to a given reference frame, and return that spline expressed in global coordinates.

Subdivision

bisect : CubicSpline2d units coordinates -> ( CubicSpline2d units coordinates, CubicSpline2d units coordinates )

Split a spline into two roughly equal halves. Equivalent to CubicSpline2d.splitAt 0.5.

splitAt : Basics.Float -> CubicSpline2d units coordinates -> ( CubicSpline2d units coordinates, CubicSpline2d units coordinates )

Split a spline at a particular parameter value, resulting in two smaller splines.

Arc length parameterization


type ArcLengthParameterized units coordinates

A spline that has been parameterized by arc length.

arcLengthParameterized : { maxError : Quantity Basics.Float units } -> Nondegenerate units coordinates -> ArcLengthParameterized units coordinates

Build an arc length parameterization of the given spline, with a given accuracy.

arcLength : ArcLengthParameterized units coordinates -> Quantity Basics.Float units

Find the total arc length of a spline, to within the accuracy given when calling arcLengthParameterized.

pointAlong : ArcLengthParameterized units coordinates -> Quantity Basics.Float units -> Point2d units coordinates

Get the point along a spline at a given arc length.

tangentDirectionAlong : ArcLengthParameterized units coordinates -> Quantity Basics.Float units -> Direction2d coordinates

Get the tangent direction along a spline at a given arc length.

sampleAlong : ArcLengthParameterized units coordinates -> Quantity Basics.Float units -> ( Point2d units coordinates, Direction2d coordinates )

Get the point and tangent direction along a spline at a given arc length.

Low level

An ArcLengthParameterized value is a combination of an ArcLengthParameterization and an underlying CubicSpline2d. If you need to do something fancy, you can extract these two values separately.

arcLengthParameterization : ArcLengthParameterized units coordinates -> ArcLength.Parameterization units

fromArcLengthParameterized : ArcLengthParameterized units coordinates -> CubicSpline2d units coordinates

Advanced

You are unlikely to need to use these functions directly, but they are useful if you are writing low-level geometric algorithms.

firstDerivative : CubicSpline2d units coordinates -> Basics.Float -> Vector2d units coordinates

Get the first derivative of a spline at a given parameter value.

secondDerivative : CubicSpline2d units coordinates -> Basics.Float -> Vector2d units coordinates

Evaluate the second derivative of a spline at a given parameter value.

thirdDerivative : CubicSpline2d units coordinates -> Vector2d units coordinates

Get the third derivative of a spline (for a cubic spline, this is a constant).

firstDerivativeBoundingBox : CubicSpline2d units coordinates -> VectorBoundingBox2d units coordinates

Get the bounds on the first deriative of a spline.

secondDerivativeBoundingBox : CubicSpline2d units coordinates -> VectorBoundingBox2d units coordinates

Get the bounds on the second deriative of a spline.

maxSecondDerivativeMagnitude : CubicSpline2d units coordinates -> Quantity Basics.Float units

Find a conservative upper bound on the magnitude of the second derivative of a spline. This can be useful when determining error bounds for various kinds of linear approximations.

numApproximationSegments : Quantity Basics.Float units -> CubicSpline2d units coordinates -> Basics.Int

Determine the number of linear segments needed to approximate a cubic spline to within a given tolerance.