ianmackenzie / elm-geometry-prerelease / LineSegment2d

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


type alias LineSegment2d =
Geometry.Types.LineSegment2d

Constructors

fromEndpoints : ( Point2d, Point2d ) -> LineSegment2d

Construct a line segment from its two endpoints:

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

from : Point2d -> Point2d -> LineSegment2d

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

LineSegment2d.from firstPoint secondPoint

is equivalent to

LineSegment2d.fromEndpoints ( firstPoint, secondPoint )

along : Axis2d -> Basics.Float -> Basics.Float -> LineSegment2d

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 3 5
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 3, 0 )
-->     , Point2d.fromCoordinates ( 5, 0 )
-->     )

LineSegment2d.along Axis2d.y 2 -4
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 0, 2 )
-->     , Point2d.fromCoordinates ( 0, -4 )
-->     )

Properties

startPoint : LineSegment2d -> Point2d

Get the start point of a line segment.

LineSegment2d.startPoint exampleLineSegment
--> Point2d.fromCoordinates ( 1, 2 )

endPoint : LineSegment2d -> Point2d

Get the end point of a line segment.

LineSegment2d.endPoint exampleLineSegment
--> Point2d.fromCoordinates ( 3, 4 )

endpoints : LineSegment2d -> ( Point2d, Point2d )

Get the endpoints of a line segment as a tuple.

( p1, p2 ) =
    LineSegment2d.endpoints lineSegment

midpoint : LineSegment2d -> Point2d

Get the midpoint of a line segment.

LineSegment2d.midpoint exampleLineSegment
--> Point2d.fromCoordinates ( 2, 3 )

length : LineSegment2d -> Basics.Float

Get the length of a line segment.

LineSegment2d.length exampleLineSegment
--> 2.8284

squaredLength : LineSegment2d -> Basics.Float

Get the squared length of a line segment. Slightly more efficient than length since it avoids a square root.

LineSegment2d.squaredLength exampleLineSegment
--> 8

direction : LineSegment2d -> Maybe Direction2d

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.fromAngle (degrees 45))

perpendicularDirection : LineSegment2d -> Maybe Direction2d

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.fromAngle (degrees 135))

vector : LineSegment2d -> Vector2d

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

LineSegment2d.vector exampleLineSegment
--> Vector2d.fromComponents ( 2, 2 )

boundingBox : LineSegment2d -> BoundingBox2d

Get the minimal bounding box containing a given line segment.

LineSegment2d.boundingBox exampleLineSegment
--> BoundingBox2d.fromExtrema
-->     { minX = 1
-->     , maxX = 3
-->     , minY = 2
-->     , maxY = 4
-->     }

Interpolation

interpolate : LineSegment2d -> Basics.Float -> Point2d

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.fromCoordinates ( 1.5, 2.5 )

LineSegment2d.interpolate exampleLineSegment 1.5
--> Point2d.fromCoordinates ( 4, 5 )

Intersection

intersectionPoint : LineSegment2d -> LineSegment2d -> Maybe Point2d

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.fromCoordinates ( 0, 0 )

b =
    Point2d.fromCoordinates ( 1, 0 )

c =
    Point2d.fromCoordinates ( 1, 1 )

d =
    Point2d.fromCoordinates ( 0, 1 )

-- definition of some segments with those points

ab =
    LineSegment2d.from a b
...

-- searching for intersections

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

LineSegment2d.intersectionPoint ac bd
--> Just (Point2d.fromCoordinates ( 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 -> LineSegment2d -> Maybe Point2d

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.fromCoordinates ( 1, -1 )
        , Point2d.fromCoordinates ( 4, 1 )
        )

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

LineSegment2d.intersectionWithAxis Axis2d.y lineSegment
--> Nothing

Transformations

Transforming a line segment is equivalent to transforming its start and end points and forming a new line segment between the resulting points.

reverse : LineSegment2d -> LineSegment2d

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

LineSegment2d.reverse exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 3, 4 )
-->     , Point2d.fromCoordinates ( 1, 2 )
-->     )

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

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

point =
    Point2d.fromCoordinates ( 1, 1 )

LineSegment2d.scaleAbout point 2 exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 1, 3 )
-->     , Point2d.fromCoordinates ( 5, 7 )
-->     )

rotateAround : Point2d -> Basics.Float -> LineSegment2d -> LineSegment2d

Rotate a line segment counterclockwise around a given center point by a given angle (in radians).

exampleLineSegment
    |> LineSegment2d.rotateAround Point2d.origin
        (degrees 90)
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( -2, 1 )
-->     , Point2d.fromCoordinates ( -4, 3 )
-->     )

translateBy : Vector2d -> LineSegment2d -> LineSegment2d

Translate a line segment by a given displacement.

displacement =
    Vector2d.fromComponents ( 1, 2 )

exampleLineSegment
    |> LineSegment2d.translateBy displacement
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 2, 4 )
-->     , Point2d.fromCoordinates ( 4, 6 )
-->     )

translateIn : Direction2d -> Basics.Float -> LineSegment2d -> LineSegment2d

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

LineSegment2d.translateIn direction distance

is equivalent to

LineSegment2d.translateBy
    (Vector2d.withLength distance direction)

mirrorAcross : Axis2d -> LineSegment2d -> LineSegment2d

Mirror a line segment across an axis.

LineSegment2d.mirrorAcross Axis2d.y exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( -1, 2 )
-->     , Point2d.fromCoordinates ( -3, 4 )
-->     )

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 -> LineSegment2d -> LineSegment2d

Project a line segment onto an axis.

LineSegment2d.projectOnto Axis2d.x exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 1, 0 )
-->     , Point2d.fromCoordinates ( 3, 0 )
-->     )

LineSegment2d.projectOnto Axis2d.y exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 0, 2 )
-->     , Point2d.fromCoordinates ( 0, 4 )
-->     )

mapEndpoints : (Point2d -> Point2d) -> LineSegment2d -> LineSegment2d

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)

Coordinate conversions

relativeTo : Frame2d -> LineSegment2d -> LineSegment2d

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

localFrame =
    Frame2d.atPoint (Point2d.fromCoordinates ( 1, 2 ))

LineSegment2d.relativeTo localFrame exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 0, 0 )
-->     , Point2d.fromCoordinates ( 2, 2 )
-->     )

placeIn : Frame2d -> LineSegment2d -> LineSegment2d

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.

localFrame =
    Frame2d.atPoint (Point2d.fromCoordinates ( 1, 2 ))

LineSegment2d.placeIn localFrame exampleLineSegment
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 2, 4 )
-->     , Point2d.fromCoordinates ( 4, 6 )
-->     )