ianmackenzie / elm-geometry / Arc2d

An Arc2d is a section of a circle, defined by its center point, start point and swept angle (the counterclockwise angle from the start point to the end point). This module includes functionality for


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

Constructors

from : Point2d units coordinates -> Point2d units coordinates -> Angle -> Arc2d units coordinates

Construct an arc with from the first given point to the second, with the given swept angle.

p1 =
    Point2d.meters 2 1

p2 =
    Point2d.meters 1 2

arc1 =
    Arc2d.from p1 p2 (Angle.degrees 90)

Arc2d.centerPoint arc1
--> Point2d.meters 1 1

arc2 =
    Arc2d.from p1 p2 (Angle.degrees -90)

Arc2d.centerPoint arc2
--> Point2d.meters 2 2

arc3 =
    Arc2d.from p1 p2 (Angle.degrees 180)

Arc2d.centerPoint arc3
--> Point2d.meters 1.5 1.5

with : { centerPoint : Point2d units coordinates, radius : Quantity Basics.Float units, startAngle : Angle, sweptAngle : Angle } -> Arc2d units coordinates

Construct an arc with the given center point, radius, start angle and swept angle:

arc =
    Arc2d.with
        { centerPoint = Point2d.meters 2 0
        , radius = Length.meters 1
        , startAngle = Angle.degrees 45
        , sweptAngle = Angle.degrees -90
        }

Arc2d.startPoint arc
--> Point2d.meters 2.7071 0.7071

Arc2d.endPoint arc
--> Point2d.meters 2.7071 -0.7071

sweptAround : Point2d units coordinates -> Angle -> Point2d units coordinates -> Arc2d units coordinates

Construct an arc by sweeping (rotating) a given start point around a given center point by a given angle. The center point to sweep around is given first and the start point to be swept is given last.

exampleArc =
    Point2d.meters 3 1
        |> Arc2d.sweptAround (Point2d.meters 1 1)
            (Angle.degrees 90)

Arc2d.endPoint exampleArc
--> Point2d.meters 1 3

A positive swept angle means that the arc is formed by rotating the start point counterclockwise around the center point. A negative swept angle results in a clockwise arc instead.

throughPoints : Point2d units coordinates -> Point2d units coordinates -> Point2d units coordinates -> Maybe (Arc2d units coordinates)

Attempt to construct an arc that starts at the first given point, passes through the second given point and ends at the third given point:

Arc2d.throughPoints
    Point2d.origin
    (Point2d.meters 1 0)
    (Point2d.meters 0 1)
--> Just
-->     (Point2d.origin
-->         |> Arc2d.sweptAround
-->             (Point2d.meters 0.5 0.5)
-->             (Angle.degrees 270)
-->     )

If the three points are collinear, returns Nothing:

Arc2d.throughPoints
    Point2d.origin
    (Point2d.meters 1 0)
    (Point2d.meters 2 0)
--> Nothing

withRadius : Quantity Basics.Float units -> SweptAngle -> Point2d units coordinates -> Point2d units coordinates -> Maybe (Arc2d units coordinates)

Attempt to construct an arc with the given radius between the given start and end points. Note that this is only possible if the given radius is large enough! For any given valid radius, start point and end point, there are four possible results, so the SweptAngle argument is used to specify which arc to create. For example:

p1 =
    Point2d.meters 1 0

p2 =
    Point2d.meters 0 1

Arc2d.withRadius (Length.meters 1)
    SweptAngle.smallPositive
    p1
    p2
--> Just
-->     (Point2d.meters 1 0
-->         |> Arc2d.sweptAround Point2d.origin
-->             (Angle.degrees 90)
-->     )

If the start and end points are coincident or the distance between them is more than twice the given radius, returns Nothing:

-- p1 and p2 are too far apart to be connected by an
-- arc of radius 0.5
Arc2d.withRadius (Length.meters 0.5)
    SweptAngle.smallPositive
    p1
    p2
--> Nothing

Note that this means it is dangerous to use this function to construct 180 degree arcs (half circles), since in this case due to numerical roundoff the distance between the two given points may appear to be slightly more than twice the given radius. In this case it is safer to use Arc2d.from, such as (for a counterclockwise arc):

halfCircle =
    Arc2d.from firstPoint secondPoint <|
        Angle.degrees 180

(Use Angle.degrees -180 for a clockwise arc.)

Properties

centerPoint : Arc2d units coordinates -> Point2d units coordinates

Get the center point of an arc.

radius : Arc2d units coordinates -> Quantity Basics.Float units

Get the radius of an arc.

startPoint : Arc2d units coordinates -> Point2d units coordinates

Get the start point of an arc.

midpoint : Arc2d units coordinates -> Point2d units coordinates

Get the midpoint of an arc.

endPoint : Arc2d units coordinates -> Point2d units coordinates

Get the end point of an arc.

sweptAngle : Arc2d units coordinates -> Angle

Get the swept angle of an arc. The result will be positive for a counterclockwise arc and negative for a clockwise one.

boundingBox : Arc2d units coordinates -> BoundingBox2d units coordinates

Get a bounding box for a given arc.

Evaluation

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

Get the point along an arc at a given parameter value.


type Nondegenerate units coordinates

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

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

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

fromNondegenerate : Nondegenerate units coordinates -> Arc2d units coordinates

Convert a nondegenerate arc back to a general Arc2d.

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

Get the tangent direction to a nondegenerate arc 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 arc at a given parameter value.

Linear approximation

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

Approximate an arc by a given number of line segments:

Arc2d.segments 2 exampleArc
--> Polyline2d.fromVertices
-->     [ Point2d.meters 3 1
-->     , Point2d.meters 2.4142 2.4142
-->     , Point2d.meters 1 3
-->     ]

Note that the number of points in the polyline is one more than the number of segments.

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

Approximate an arc as a polyline, within a given tolerance:

Arc2d.approximate (Length.meters 0.1) exampleArc
--> Polyline2d.fromVertices
-->     [ Point2d.meters 3 1
-->     , Point2d.meters 2.732 2
-->     , Point2d.meters 2 2.732
-->     , Point2d.meters 1 3
-->     ]

In this example, every point on the returned polyline will be within 0.1 meters of the original arc.

toPolyline : { maxError : Quantity Basics.Float units } -> Arc2d units coordinates -> Polyline2d units coordinates

DEPRECATED - use segments or approximate instead.

Transformations

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

reverse : Arc2d units coordinates -> Arc2d units coordinates

Reverse the direction of an arc, so that the start point becomes the end point and vice versa.

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

Scale an arc about a given point by a given scale.

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

Rotate an arc around a given point by a given angle.

translateBy : Vector2d units coordinates -> Arc2d units coordinates -> Arc2d units coordinates

Translate an arc by a given displacement.

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

Translate an arc in a given direction by a given distance.

mirrorAcross : Axis2d units coordinates -> Arc2d units coordinates -> Arc2d units coordinates

Mirror an arc across a given axis. This negates the sign of the arc's swept angle.

Unit conversions

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

Convert an arc 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) -> Arc2d units1 coordinates -> Arc2d units2 coordinates

Convert an arc 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 } -> Arc2d units globalCoordinates -> Arc2d units localCoordinates

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

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

Take an arc considered to be defined in local coordinates relative to a given reference frame, and return that arc expressed in global 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 : Arc2d units coordinates -> Basics.Float -> Vector2d units coordinates

Get the first derivative of an arc at a given parameter value.

firstDerivativeBoundingBox : Arc2d units coordinates -> VectorBoundingBox2d units coordinates

Get the bounds on the first derivative of an arc.

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

Determine the number of linear segments needed to approximate an arc to within a given tolerance.