ianmackenzie / elm-geometry-prerelease / Plane3d

A Plane3d is an infinite flat plane in 3D. It is defined by an origin point and normal direction and is useful for several operations including:


type alias Plane3d =
Geometry.Types.Plane3d

Constants

xy : Plane3d

The global XY plane, centered at the origin with a normal in the positive Z direction.

Plane3d.xy
--> Plane3d.through Point3d.origin Direction3d.z

yz : Plane3d

The global YZ plane, centered at the origin with a normal in the positive X direction.

Plane3d.yz
--> Plane3d.through Point3d.origin Direction3d.x

zx : Plane3d

The global ZX plane, centered at the origin with a normal in the positive Y direction.

Plane3d.zx
--> through Point3d.origin Direction3d.y

Constructors

through : Point3d -> Direction3d -> Plane3d

Construct a plane through the given point, with the given normal direction.

xyPlane =
    Plane3d.through Point3d.origin Direction3d.z

withNormalDirection : Direction3d -> Point3d -> Plane3d

Construct a plane with the given normal direction, through the given point. Flipped version of through.

plane =
    Plane3d.withNormalDirection Direction3d.y
        (Point3d.fromCoordinates ( 2, 1, 3 ))

throughPoints : Point3d -> Point3d -> Point3d -> Maybe Plane3d

Attempt to construct a plane passing through the three given points. The origin point of the resulting plane will be equal to the first given point, and the normal direction will be such that the three given points are in counterclockwise order around it according to the right-hand rule. If the three given points are collinear, returns Nothing.

Plane3d.throughPoints
    (Point3d.fromCoordinates ( 2, 0, 0 ))
    (Point3d.fromCoordinates ( 3, 0, 0 ))
    (Point3d.fromCoordinates ( 4, 1, 1 ))
--> Just
-->     (Plane3d.through
-->         (Point3d.fromCoordinates ( 2, 0, 0 ))
-->         (Direction3d.fromAzimuthAndElevation
-->             (degrees -90)
-->             (degrees 45)
-->         )
-->     )

Plane3d.throughPoints
    (Point3d.fromCoordinates ( 2, 0, 0 ))
    (Point3d.fromCoordinates ( 3, 0, 0 ))
    (Point3d.fromCoordinates ( 4, 0, 0 ))
--> Nothing

Properties

originPoint : Plane3d -> Point3d

Get the origin point of a plane.

Plane3d.originPoint Plane3d.xy
--> Point3d.origin

normalDirection : Plane3d -> Direction3d

Get the normal direction of a plane.

Plane3d.normalDirection Plane3d.xy
--> Direction3d.z

normalAxis : Plane3d -> Axis3d

Construct an axis from the origin point and normal direction of a plane.

Plane3d.normalAxis Plane3d.zx
--> Axis3d.y

Transformations

offsetBy : Basics.Float -> Plane3d -> Plane3d

Shift a plane in its own normal direction by the given (signed) distance.

Plane3d.offsetBy 1.0 Plane3d.zx
--> Plane3d.withNormalDirection Direction3d.y
-->     (Point3d.fromCoordinates ( 0, 1, 0 ))

Plane3d.offsetBy -2.0 Plane3d.xy
--> Plane3d.withNormalDirection Direction3d.z
-->     (Point3d.fromCoordinates ( 0, 0, -2 ))

reverseNormal : Plane3d -> Plane3d

Reverse a plane's normal direction while leaving its origin point unchanged.

Plane3d.reverseNormal Plane3d.xy
--> Plane3d.through Point3d.origin
-->     Direction3d.negativeZ

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

Rotate a plane around an axis by a given angle.

Plane3d.rotateAround Axis3d.y (degrees 90) Plane3d.xy
--> Plane3d.yz

translateBy : Vector3d -> Plane3d -> Plane3d

Translate a plane by a given displacement. Applies the given displacement to the plane's origin point and leaves its normal direction unchanged.

plane =
    Plane3d.withNormalDirection Direction3d.z
        (Point3d.fromCoordinates ( 1, 1, 1 ))

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

Plane3d.translateBy displacement plane
--> Plane3d.withNormalDirection Direction3d.z
-->     (Point3d.fromCoordinates ( 2, 3, 4 ))

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

Translate a plane in a given direction by a given distance;

Plane3d.translateIn direction distance

is equivalent to

Plane3d.translateBy
    (Vector3d.withLength distance direction)

moveTo : Point3d -> Plane3d -> Plane3d

Move a plane so that it has the given origin point but unchanged normal direction.

newOrigin =
    Point3d.fromCoordinates ( 1, 2, 3 )

Plane3d.moveTo newOrigin Plane3d.xy
--> Plane3d.through newOrigin Direction3d.z

mirrorAcross : Plane3d -> Plane3d -> Plane3d

Mirror one plane across another. The plane to mirror across is given first and the plane to mirror is given second.

plane =
    Plane3d.withNormalDirection Direction3d.z
        (Point3d.fromCoordinates ( 1, 2, 3 ))

Plane3d.mirrorAcross Plane3d.xy plane
--> Plane3d.withNormalDirection Direction3d.negativeZ
-->     (Point3d.fromCoordinates ( 1, 2, -3 ))

Coordinate conversions

relativeTo : Geometry.Types.Frame3d -> Plane3d -> Plane3d

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

referenceFrame =
    Frame3d.atPoint
        (Point3d.fromCoordinates ( 1, 1, 1 ))

plane =
    Plane3d.withNormalDirection Direction3d.z
        (Point3d.fromCoordinates ( 0, 0, 2 ))

Plane3d.relativeTo referenceFrame plane
--> Plane3d.withNormalDirection Direction3d.z
-->     (Point3d.fromCoordinates ( -1, -1, 1 ))

placeIn : Geometry.Types.Frame3d -> Plane3d -> Plane3d

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

referenceFrame =
    Frame3d.atPoint
        (Point3d.fromCoordinates ( 1, 1, 1 ))

plane =
    Plane3d.withNormalDirection Direction3d.z
        (Point3d.fromCoordinates ( 1, 2, 3 ))

Plane3d.placeIn referenceFrame plane
--> Plane3d.withNormalDirection Direction3d.z
-->     (Point3d.fromCoordinates ( 2, 3, 4 ))