ianmackenzie / elm-geometry-prerelease / LineSegment3d

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


type alias LineSegment3d =
Geometry.Types.LineSegment3d

Constructors

fromEndpoints : ( Point3d, Point3d ) -> LineSegment3d

Construct a line segment from its two endpoints:

exampleLineSegment =
    LineSegment3d.fromEndpoints
        ( Point3d.fromCoordinates ( 1, 2, 3 )
        , Point3d.fromCoordinates ( 4, 5, 6 )
        )

from : Point3d -> Point3d -> LineSegment3d

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

LineSegment3d.from firstPoint secondPoint

is equivalent to

LineSegment3d.fromEndpoints ( firstPoint, secondPoint )

along : Axis3d -> Basics.Float -> Basics.Float -> LineSegment3d

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

LineSegment3d.along Axis3d.x 3 5
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 3, 0, 0 )
-->     , Point3d.fromCoordinates ( 5, 0, 0 )
-->     )

LineSegment3d.along Axis3d.y 2 -4
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 0, 2, 0 )
-->     , Point3d.fromCoordinates ( 0, -4, 0 )
-->     )

on : SketchPlane3d -> LineSegment2d -> LineSegment3d

Construct a 3D line segment lying on a sketch plane by providing a 2D line segment specified in XY coordinates within the sketch plane.

LineSegment3d.on SketchPlane3d.yz <|
    LineSegment2d.fromEndpoints
        ( Point2d.fromCoordinates ( 1, 2 )
        , Point2d.fromCoordinates ( 3, 4 )
        )
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 0, 1, 2 )
-->     , Point3d.fromCoordinates ( 0, 3, 4 )
-->     )

Properties

startPoint : LineSegment3d -> Point3d

Get the start point of a line segment.

LineSegment3d.startPoint exampleLineSegment
--> Point3d.fromCoordinates ( 1, 2, 3 )

endPoint : LineSegment3d -> Point3d

Get the end point of a line segment.

LineSegment3d.endPoint exampleLineSegment
--> Point3d.fromCoordinates ( 4, 5, 6 )

endpoints : LineSegment3d -> ( Point3d, Point3d )

Get the endpoints of a line segment as a tuple.

( p1, p2 ) =
    LineSegment3d.endpoints lineSegment

midpoint : LineSegment3d -> Point3d

Get the midpoint of a line segment.

LineSegment3d.midpoint exampleLineSegment
--> Point3d.fromCoordinates ( 2.5, 3.5, 4.5 )

length : LineSegment3d -> Basics.Float

Get the length of a line segment.

LineSegment3d.length exampleLineSegment
--> 5.1962

squaredLength : LineSegment3d -> Basics.Float

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

LineSegment3d.squaredLength exampleLineSegment
--> 27

direction : LineSegment3d -> Maybe Direction3d

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.

LineSegment3d.direction exampleLineSegment
--> Just
-->     (Direction3d.fromAzimuthAndElevation
-->         (degrees 45)
-->         (degrees 35.26)
-->     )

perpendicularDirection : LineSegment3d -> Maybe Direction3d

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

LineSegment3d.perpendicularDirection exampleLineSegment
--> Just
-->     (Direction3d.fromAzimuthAndElevation
-->         (degrees -90)
-->         (degrees 45)
-->     )

vector : LineSegment3d -> Vector3d

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

LineSegment3d.vector exampleLineSegment
--> Vector3d.fromComponents ( 2, 2, 2 )

boundingBox : LineSegment3d -> BoundingBox3d

Get the minimal bounding box containing a line segment.

LineSegment3d.boundingBox exampleLineSegment
--> BoundingBox3d.fromExtrema
-->     { minX = 1
-->     , maxX = 4
-->     , minY = 2
-->     , maxY = 5
-->     , minZ = 3
-->     , maxZ = 6
-->     }

Interpolation

interpolate : LineSegment3d -> Basics.Float -> Point3d

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.

LineSegment3d.interpolate exampleLineSegment (1 / 3)
--> Point3d.fromCoordinates ( 2, 4, 5 )

LineSegment3d.interpolate exampleLineSegment (-1 / 3)
--> Point3d.fromCoordinates ( 0, 1, 2 )

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 : LineSegment3d -> LineSegment3d

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

LineSegment3d.reverse exampleLineSegment
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 4, 5, 6 )
-->     , Point3d.fromCoordinates ( 1, 2, 3 )
-->     )

scaleAbout : Point3d -> Basics.Float -> LineSegment3d -> LineSegment3d

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

point =
    Point3d.fromCoordinates ( 1, 1, 1 )

LineSegment3d.scaleAbout point 2 exampleLineSegment
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 1, 3, 5 )
-->     , Point3d.fromCoordinates ( 7, 9, 11 )
-->     )

rotateAround : Axis3d -> Basics.Float -> LineSegment3d -> LineSegment3d

Rotate a line segment around a given axis by a given angle (in radians).

exampleLineSegment
    |> LineSegment3d.rotateAround Axis3d.z (degrees 90)
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( -2, 1, 3 )
-->     , Point3d.fromCoordinates ( -5, 4, 6 )
-->     )

translateBy : Vector3d -> LineSegment3d -> LineSegment3d

Translate a line segment by a given displacement.

displacement =
    Vector3d.fromComponents ( 1, 2, 3 )

exampleLineSegment
    |> LineSegment3d.translateBy displacement
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 2, 4, 6 )
-->     , Point3d.fromCoordinates ( 5, 7, 9 )
-->     )

translateIn : Direction3d -> Basics.Float -> LineSegment3d -> LineSegment3d

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

LineSegment3d.translateIn direction distance

is equivalent to

LineSegment3d.translateBy
    (Vector3d.withLength distance direction)

mirrorAcross : Plane3d -> LineSegment3d -> LineSegment3d

Mirror a line segment across a plane.

exampleLineSegment
    |> LineSegment3d.mirrorAcross Plane3d.xy
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 1, 2, -3 )
-->     , Point3d.fromCoordinates ( 4, 5, -6 )
-->     )

projectOnto : Plane3d -> LineSegment3d -> LineSegment3d

Find the orthographic projection of a line segment onto a plane.

LineSegment3d.projectOnto Plane3d.yz exampleLineSegment
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 0, 2, 3 )
-->     , Point3d.fromCoordinates ( 0, 5, 6 )
-->     )

mapEndpoints : (Point3d -> Point3d) -> LineSegment3d -> LineSegment3d

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,

LineSegment3d.projectOnto plane

is equivalent to

LineSegment3d.mapEndpoints (Point3d.projectOnto plane)

Coordinate conversions

relativeTo : Frame3d -> LineSegment3d -> LineSegment3d

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

localFrame =
    Frame3d.atPoint
        (Point3d.fromCoordinates ( 1, 2, 3 ))

LineSegment3d.relativeTo localFrame exampleLineSegment
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 0, 0, 0 )
-->     , Point3d.fromCoordinates ( 3, 3, 3 )
-->     )

placeIn : Frame3d -> LineSegment3d -> LineSegment3d

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 =
    Frame3d.atPoint
        (Point3d.fromCoordinates ( 1, 2, 3 ))

LineSegment3d.placeIn localFrame exampleLineSegment
--> LineSegment3d.fromEndpoints
-->     ( Point3d.fromCoordinates ( 2, 4, 6 )
-->     , Point3d.fromCoordinates ( 5, 7, 9 )
-->     )

projectInto : SketchPlane3d -> LineSegment3d -> LineSegment2d

Project a line segment into a given sketch plane. Conceptually, this finds the orthographic projection of the line segment onto the plane and then expresses the projected line segment in 2D sketch coordinates.

exampleLineSegment
    |> LineSegment3d.projectInto SketchPlane3d.xy
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 1, 2 )
-->     , Point2d.fromCoordinates ( 4, 5 )
-->     )

exampleLineSegment
    |> LineSegment3d.projectInto SketchPlane3d.yz
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 2, 3 )
-->     , Point2d.fromCoordinates ( 5, 6 )
-->     )

exampleLineSegment
    |> LineSegment3d.projectInto SketchPlane3d.zx
--> LineSegment2d.fromEndpoints
-->     ( Point2d.fromCoordinates ( 3, 1 )
-->     , Point2d.fromCoordinates ( 6, 4 )
-->     )