ianmackenzie / elm-geometry / LineSegment2d

A LineSegment2d is a line between two points in 2D. This module contains functionality such as:


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

Constructors

fromEndpoints : ( Point2d units coordinates, Point2d units coordinates ) -> LineSegment2d units coordinates

Construct a line segment from its two endpoints:

exampleLineSegment =
    LineSegment2d.fromEndpoints
        ( Point2d.meters 1 2
        , Point2d.meters 3 4
        )

from : Point2d units coordinates -> Point2d units coordinates -> LineSegment2d units coordinates

Construct a line segment from the first point to the second;

LineSegment2d.from firstPoint secondPoint

is equivalent to

LineSegment2d.fromEndpoints ( firstPoint, secondPoint )

fromPointAndVector : Point2d units coordinates -> Vector2d units coordinates -> LineSegment2d units coordinates

Construct a line segment given its start point and the vector from its start point to its end point;

LineSegment2d.fromPointAndVector point vector

is equivalent to

LineSegment2d.fromEndpoints
    ( point
    , point |> Point2d.translateBy vector
    )

along : Axis2d units coordinates -> Quantity Basics.Float units -> Quantity Basics.Float units -> LineSegment2d units coordinates

Construct a line segment lying on the given axis, with its endpoints at the given distances from the axis' origin point.

LineSegment2d.along Axis2d.x
    (Length.meters 3)
    (Length.meters 5)
--> LineSegment2d.fromEndpoints
-->     ( Point2d.meters 3 0
-->     , Point2d.meters 5 0
-->     )

Properties

startPoint : LineSegment2d units coordinates -> Point2d units coordinates

Get the start point of a line segment.

endPoint : LineSegment2d units coordinates -> Point2d units coordinates

Get the end point of a line segment.

endpoints : LineSegment2d units coordinates -> ( Point2d units coordinates, Point2d units coordinates )

Get the endpoints of a line segment as a tuple.

( p1, p2 ) =
    LineSegment2d.endpoints lineSegment

midpoint : LineSegment2d units coordinates -> Point2d units coordinates

Get the midpoint of a line segment.

LineSegment2d.midpoint exampleLineSegment
--> Point2d.meters 2 3

length : LineSegment2d units coordinates -> Quantity Basics.Float units

Get the length of a line segment.

LineSegment2d.length exampleLineSegment
--> Length.meters 2.8284

direction : LineSegment2d units coordinates -> Maybe (Direction2d coordinates)

Get the direction from a line segment's start point to its end point. If the line segment has zero length (the start and end points are the same), returns Nothing.

LineSegment2d.direction exampleLineSegment
--> Just (Direction2d.degrees 45)

axis : LineSegment2d units coordinates -> Maybe (Axis2d units coordinates)

Construct an axis collinear with a given line segment; the origin point of the axis will be the start point of the line segment and the direction of the axis will be the direction of the line segment. Returns Nothing if the line segment has zero length.

perpendicularDirection : LineSegment2d units coordinates -> Maybe (Direction2d coordinates)

Get the direction perpendicular to a line segment, pointing to the left. If the line segment has zero length, returns Nothing.

LineSegment2d.perpendicularDirection exampleLineSegment
--> Just (Direction2d.degrees 135)

vector : LineSegment2d units coordinates -> Vector2d units coordinates

Get the vector from a given line segment's start point to its end point.

LineSegment2d.vector exampleLineSegment
--> Vector2d.meters 2 2

boundingBox : LineSegment2d units coordinates -> BoundingBox2d units coordinates

Get the minimal bounding box containing a given line segment.

LineSegment2d.boundingBox exampleLineSegment
--> BoundingBox2d.from
-->     (Point2d.meters 1 2)
-->     (Point2d.meters 3 4)

Interpolation

interpolate : LineSegment2d units coordinates -> Basics.Float -> Point2d units coordinates

Interpolate a line segment between its start and end points; a value of 0.0 corresponds to the start point of the line segment, a value of 0.5 corresponds to its midpoint and a value of 1.0 corresponds to its end point. Values less than 0.0 or greater than 1.0 can be used to extrapolate.

LineSegment2d.interpolate exampleLineSegment 0.25
--> Point2d.meters 1.5 2.5

LineSegment2d.interpolate exampleLineSegment 1.5
--> Point2d.meters 4 5

If you just need to interpolate between two points, you don't have to construct a line segment first - you can use Point2d.interpolateFrom directly.

Intersection

intersectionPoint : LineSegment2d units coordinates -> LineSegment2d units coordinates -> Maybe (Point2d units coordinates)

Attempt to find the unique intersection point of two line segments. If there is no such point (the two line segments do not touch, or they overlap), returns Nothing.

-- 4 corners of a square

a =
    Point2d.meters 0 0

b =
    Point2d.meters 1 0

c =
    Point2d.meters 1 1

d =
    Point2d.meters 0 1

-- definition of some segments with those points

ab =
    LineSegment2d.from a b
...

-- searching for intersections

LineSegment2d.intersectionPoint ab bc
--> Just (Point2d.meters 1 0)
-- corner point b

LineSegment2d.intersectionPoint ac bd
--> Just (Point2d.meters 0.5 0.5)
-- diagonal crossing at square center

LineSegment2d.intersectionPoint ab cd
--> Nothing -- parallel lines

LineSegment2d.intersectionPoint ab ab
--> Nothing -- collinear lines

Note that if the endpoint of one line segment lies on the other line segment, numerical roundoff means that the intersection may or may not be found. If two segments have a shared endpoint (the two segments meet in something like a 'V', where the end point of one segment is the start point of the next), that point is guaranteed to be returned as the intersection point, but if two segments meet in a 'T' shape the intersection point may or may not be found.

intersectionWithAxis : Axis2d units coordinates -> LineSegment2d units coordinates -> Maybe (Point2d units coordinates)

Attempt to find the unique intersection point of a line segment with an axis. If there is no such point (the line segment does not touch the axis, or lies perfectly along it), returns Nothing.

lineSegment =
    LineSegment2d.fromEndpoints
        ( Point2d.meters 1 -1
        , Point2d.meters 4 1
        )

LineSegment2d.intersectionWithAxis Axis2d.x lineSegment
--> Just (Point2d.meters 2.5 0)

LineSegment2d.intersectionWithAxis Axis2d.y lineSegment
--> Nothing

Measurement

signedDistanceAlong : Axis2d units coordinates -> LineSegment2d units coordinates -> Quantity.Interval.Interval Basics.Float units

Measure the distance of a line segment along an axis. This is the range of distances along the axis resulting from projecting the line segment perpendicularly onto the axis.

Note that reversing the line segment will not affect the result.

signedDistanceFrom : Axis2d units coordinates -> LineSegment2d units coordinates -> Quantity.Interval.Interval Basics.Float units

Measure the distance of a line segment from an axis. If the returned interval:

Note that reversing the line segment will not affect the result.

Transformations

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

reverse : LineSegment2d units coordinates -> LineSegment2d units coordinates

Reverse a line segment, swapping its start and end points.

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

Scale a line segment about the given center point by the given scale.

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

Rotate a line segment counterclockwise around a given center point by a given angle.

translateBy : Vector2d units coordinates -> LineSegment2d units coordinates -> LineSegment2d units coordinates

Translate a line segment by a given displacement.

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

Translate a line segment in a given direction by a given distance.

mirrorAcross : Axis2d units coordinates -> LineSegment2d units coordinates -> LineSegment2d units coordinates

Mirror a line segment across an axis. Note that the endpoints of a mirrored segment are equal to the mirrored endpoints of the original segment, but as a result the normal direction of a mirrored segment is the opposite of the mirrored normal direction of the original segment (since the normal direction is always considered to be 'to the left' of the line segment).

projectOnto : Axis2d units coordinates -> LineSegment2d units coordinates -> LineSegment2d units coordinates

Project a line segment onto an axis.

mapEndpoints : (Point2d unitsA coordinatesA -> Point2d unitsB coordinatesB) -> LineSegment2d unitsA coordinatesA -> LineSegment2d unitsB coordinatesB

Transform the start and end points of a line segment by a given function and create a new line segment from the resulting points. Most other transformation functions can be defined in terms of mapEndpoints; for example,

LineSegment2d.projectOnto axis

is equivalent to

LineSegment2d.mapEndpoints (Point2d.projectOnto axis)

Unit conversions

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

Convert a line segment 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) -> LineSegment2d units1 coordinates -> LineSegment2d units2 coordinates

Convert a line segment 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 } -> LineSegment2d units globalCoordinates -> LineSegment2d units localCoordinates

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

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

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