OpenSolid.SketchPlane3d

A SketchPlane3d represents a 2D planar coordinate system in 3D space, and is defined by its origin point and X and Y directions (which are always perpendicular to each other). Sketch planes are the primary tool for converting back and forth between 2D and 3D coordinates:

3D geometry such as points, directions and line segments can be projected into a sketch plane, which effectively projects the geometry onto the sketch plane and then expresses the projected geometry in 2D coordinates.
2D geometry can be place onto a sketch plane to result in 3D geometry. For example, a 2D point placed onto a sketch plane will result in a 3D point on that sketch plane that has the given 2D coordinate in the sketch plane.

Many 3D data types have projectInto functions that return the corresponding 2D data type, and those 2D data types have placeOnto functions for converting back to 3D. For example, Triangle3d.projectInto returns a Triangle2d and Triangle2d.placeOnto returns a Triangle3d. These pairs of functions are almost, but not quite, inverses of each other:

Point2d.placeOnto sketchPlane >> Point3d.projectInto sketchPlane will just return the original Point2d (within roundoff error).
Point3d.projectInto sketchPlane >> Point2d.placeOnto sketchPlane is equivalent to Point3d.projectOnto (SketchPlane3d.plane sketchPlane) since the result will always be on the given sketch plane.

Sketch planes can be constructed explicitly by passing a record with originPoint, xDirection and yDirection fields to the SketchPlane3d constructor, for example

sketchPlane =
    SketchPlane3d
        { originPoint = Point3d ( 2, 1, 3 )
        , xDirection = Direction3d.y
        , yDirection = Direction3d.flip Direction3d.z
        }

If you construct a SketchPlane3d this way, you must ensure that the X and Y basis directions are perpendicular to each other.

Predefined sketch planes

These predefined sketch planes all have the global origin point as their origin point, and use the two indicated global axes as their X and Y axes. For example,

SketchPlane3d.yz
--> SketchPlane3d
-->     { originPoint = Point3d.origin
-->     , xDirection = Direction3d.y
-->     , yDirection = Direction3d.z
-->     }

xy : SketchPlane3d

A sketch plane formed from the global X and Y axes.

yx : SketchPlane3d

A sketch plane formed from the global Y and X axes.

yz : SketchPlane3d

A sketch plane formed from the global Y and Z axes.

zy : SketchPlane3d

A sketch plane formed from the global Z and Y axes.

zx : SketchPlane3d

A sketch plane formed from the global Z and X axes.

xz : SketchPlane3d

A sketch plane formed from the global X and Z axes.

Accessors

originPoint : SketchPlane3d -> Point3d

Get the origin point of a sketch plane.

SketchPlane3d.originPoint SketchPlane3d.xy
--> Point3d.origin

xDirection : SketchPlane3d -> Direction3d

Get the X direction of a sketch plane (the direction of the sketch plane's X axis).

SketchPlane3d.xDirection SketchPlane3d.zx
--> Direction3d.z

yDirection : SketchPlane3d -> Direction3d

Get the Y direction of a sketch plane (the direction of the sketch plane's Y axis).

SketchPlane3d.yDirection SketchPlane3d.zx
--> Direction3d.x

normalDirection : SketchPlane3d -> Direction3d

Get the normal direction to a sketch plane. This is equal to the cross product of the sketch plane's X and Y directions.

SketchPlane3d.normalDirection SketchPlane3d.xy
--> Direction3d.z


SketchPlane3d.normalDirection SketchPlane3d.xz
--> Direction3d.flip Direction3d.y

Axes

xAxis : SketchPlane3d -> Axis3d

Get the X axis of a sketch plane. A 2D X coordinate within the sketch plane corresponds to a distance along this axis in 3D.

SketchPlane3d.xAxis SketchPlane3d.zx
--> Axis3d.z

yAxis : SketchPlane3d -> Axis3d

Get the Y axis of a sketch plane. A 2D Y coordinate within the sketch plane corresponds to a distance along this axis in 3D.

SketchPlane3d.yAxis SketchPlane3d.zx
--> Axis3d.x

normalAxis : SketchPlane3d -> Axis3d

Get the normal axis to a sketch plane (the axis formed from the sketch plane's origin point and normal direction).

SketchPlane3d.normalAxis SketchPlane3d.xy
--> Axis3d.z


SketchPlane3d.normalAxis SketchPlane3d.xz
--> Axis3d.flip Axis3d.y

Conversions

plane : SketchPlane3d -> Plane3d

Conver a SketchPlane3d to a Plane3d with the same origin point and normal direction.

SketchPlane3d.plane SketchPlane3d.xy
--> Plane3d.xy


SketchPlane3d.plane SketchPlane3d.yx
--> Plane3d.flip Plane3d.xy

Transformations

flipX : SketchPlane3d -> SketchPlane3d

Flip the X direction of a sketch plane, leaving its Y direction and origin point unchanged.

SketchPlane3d.flipX SketchPlane3d.yz
--> SketchPlane3d
-->     { originPoint = Point3d.origin
-->     , xDirection = Direction3d.flip Direction3d.y
-->     , yDirection = Direction3d.z
-->     }

flipY : SketchPlane3d -> SketchPlane3d

Flip the Y direction of a sketch plane, leaving its X direction and origin point unchanged.

SketchPlane3d.flipY SketchPlane3d.yz
--> SketchPlane3d
-->     { originPoint = Point3d.origin
-->     , xDirection = Direction3d.y
-->     , yDirection = Direction3d.flip Direction3d.z
-->     }

moveTo : Point3d -> SketchPlane3d -> SketchPlane3d

Set the origin point of the given sketch plane to the given point, leaving its X and Y directions unchanged.

SketchPlane3d.moveTo (Point3d ( 2, 1, 3 )) SketchPlane3d.yz
--> SketchPlane3d
-->     { originPoint = Point3d ( 2, 1, 3 )
-->     , xDirection = Direction3d.y
-->     , yDirection = Direction3d.z
-->     }

rotateAround : Axis3d -> Float -> SketchPlane3d -> SketchPlane3d

Rotate a sketch plane around an axis by a given angle (in radians). The sketch plane's origin point and X and Y directions will all be rotated around the given axis.

SketchPlane3d.rotateAround Axis3d.x (degrees 90) SketchPlane3d.xy
--> SketchPlane3d.xz

rotateAroundOwn : (SketchPlane3d -> Axis3d) -> Float -> SketchPlane3d -> SketchPlane3d

Rotate a sketch plane around one of its own axes by a given angle (in radians).

The first argument is a function that returns the axis to rotate around, given the current sketch plane. The majority of the time this will be either SketchPlane3d.xAxis or SketchPlane3d.yAxis.

This function is convenient when constructing sketch planes via a series of transformations. For example,

SketchPlane3d.xy
    |> SketchPlane3d.translateBy (Vector3d ( 1, 0, 0 ))
    |> SketchPlane3d.rotateAroundOwn SketchPlane3d.yAxis (degrees -45)
--> SketchPlane3d
-->     { originPoint = Point3d ( 1, 0, 0 )
-->     , xDirection = Direction3d ( 0.7071, 0, 0.7071 )
-->     , yDirection = Direction3d.y
-->     }

Note that since the rotation was around the sketch plane's own Y axis (which passes through the sketch plane's origin point) instead of the global Y axis, the origin point itself was not affected by the rotation.

translateBy : Vector3d -> SketchPlane3d -> SketchPlane3d

Translate a sketch plane by a given displacement.

displacement =
    Vector3d ( 2, 1, 3 )


SketchPlane3d.translateBy displacement SketchPlane3d.xy
--> SketchPlane3d
-->     { originPoint = Point3d ( 2, 1, 3 )
-->     , xDirection = Direction3d.x
-->     , yDirection = Direction3d.y
-->     }

translateAlongOwn : (SketchPlane3d -> Axis3d) -> Float -> SketchPlane3d -> SketchPlane3d

Translate a sketch plane along one of its own axes by a given distance.

The first argument is a function that returns the axis to translate along, given the current sketch plane. The majority of the time this will be either SketchPlane3d.xAxis or SketchPlane3d.yAxis.

This function is convenient when constructing frames via a series of transformations. For example,

SketchPlane3d.xy
    |> SketchPlane3d.rotateAround Axis3d.x (degrees 45)
    |> SketchPlane3d.translateAlongOwn SketchPlane3d.yAxis 2

means 'take the global XY sketch plane, rotate it around the global X axis by 45 degrees, then translate the result 2 units along its own (rotated) Y axis', resulting in

SketchPlane3d
    { originPoint = Point3d ( 0, 1.4142, 1.4142 )
    , xDirection = Direction3d.x
    , yDirection = Direction3d ( 0, 0.7071, 0.7071 )
    }

mirrorAcross : Plane3d -> SketchPlane3d -> SketchPlane3d

Mirror a sketch plane across a plane.

sketchPlane =
    SketchPlane3d
        { originPoint = Point2d ( 2, 1, 3 )
        , xDirection = Direction3d.y
        , yDirection = Direction3d.z
        }


SketchPlane3d.mirrorAcross Plane3d.xy sketchPlane
--> SketchPlane3d
-->     { originPoint = Point2d ( 2, 1, -3 )
-->     , xDirection = Direction3d.y
-->     , yDirection = Direction3d.flip Direction3d.z
-->     }

Coordinate frames

relativeTo : Frame3d -> SketchPlane3d -> SketchPlane3d

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

placeIn : Frame3d -> SketchPlane3d -> SketchPlane3d

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

opensolid/geometry/1.1.0