OpenSolid.Frame2d

Frame2d

A Frame2d has an origin point and a pair of X and Y directions (which are always perpendicular to each other). It can be thought of as:

A local coordinate system: Most geometric types have associated relativeTo and placeIn functions that convert values of that type from global coordinates to local coordinates in a particular frame, and vice versa.
A pair of X and Y axes: It is often convenient to (for example) mirror across the X axis of a frame, or project onto its Y axis. Frames can also themselves be translated, rotated and mirrored!
A combined 2D position and orientation: For example, a Frame2d could be used to define the position and orientation of a spaceship in a 2D game. Movement of the ship would then be done by translating and rotating the frame.

Frames can by constructed by passing a record with originPoint, xDirection and yDirection fields to the Frame2d constructor, for example:

frame =
    Frame2d
        { originPoint = Point2d ( 2, 3 )
        , xDirection = Direction2d.fromAngle (degrees 45)
        , yDirection = Direction2d.fromAngle (degrees 135)
        }

In this case you must be careful to ensure that the X and Y directions are perpendicular.

Predefined frames

xy : Frame2d

The global XY frame.

Frame2d.xy
--> Frame2d
-->     { originPoint = Point2d.origin
-->     , xDirection = Direction2d.x
-->     , yDirection = Direction2d.y
-->     }

Constructors

at : Point2d -> Frame2d

Construct a frame aligned with the global XY frame but with the given origin point.

Frame2d.at (Point2d ( 2, 3 ))
--> Frame2d
-->     { originPoint = Point2d ( 2, 3 )
-->     , xDirection = Direction2d.x
-->     , yDirection = Direction2d.y
-->     }

Accessors

originPoint : Frame2d -> Point2d

Get the origin point of a given frame.

Frame2d.originPoint Frame2d.xy
--> Point2d.origin

xDirection : Frame2d -> Direction2d

Get the X direction of a given frame.

Frame2d.xDirection Frame2d.xy
--> Direction2d.x

yDirection : Frame2d -> Direction2d

Get the Y direction of a given frame.

Frame2d.yDirection Frame2d.xy
--> Direction2d.y

Axes

xAxis : Frame2d -> Axis2d

Get the X axis of a given frame (the axis formed from the frame's origin point and X direction).

Frame2d.xAxis Frame2d.xy
--> Axis2d.x

yAxis : Frame2d -> Axis2d

Get the Y axis of a given frame (the axis formed from the frame's origin point and Y direction).

Frame2d.yAxis Frame2d.xy
--> Axis2d.y

Transformations

flipX : Frame2d -> Frame2d

Reverse the X direction of a frame, leaving its Y direction and origin point the same.

Frame2d.flipX Frame2d.xy
--> Frame2d
-->     { originPoint = Point2d.origin
-->     , xDirection = Direction2d.flip Direction2d.x
-->     , yDirection = Direction2d.y
-->     }

flipY : Frame2d -> Frame2d

Reverse the Y direction of a frame, leaving its X direction and origin point the same.

Frame2d.flipY Frame2d.xy
--> Frame2d
-->     { originPoint = Point2d.origin
-->     , xDirection = Direction2d.x
-->     , yDirection = Direction2d.flip Direction2d.y
-->     }

moveTo : Point2d -> Frame2d -> Frame2d

Move a frame so that it has the given origin point.

frame =
    Frame2d
        { point = Point2d ( 2, 3 )
        , xDirection = Direction2d ( 0.8, 0.6 )
        , yDirection = Direction2d ( -0.6, 0.8 )
        }


Frame2d.moveTo (Point2d ( 1, 1 )) frame
--> Frame2d
-->     { point = Point2d ( 1, 1 )
-->     , xDirection = Direction2d ( 0.8, 0.6 )
-->     , yDirection = Direction2d ( -0.6, 0.8 )
-->     }

rotateBy : Float -> Frame2d -> Frame2d

Rotate a frame counterclockwise by a given angle around the frame's own origin point. The resulting frame will have the same origin point, and its X and Y directions will be rotated by the given angle.

frame =
    Frame2d.at (Point2d ( 1, 1 ))


Frame2d.rotateBy (degrees 45) frame
--> Frame2d
-->     { originPoint = Point2d ( 1, 1 )
-->     , xDirection = Direction2d ( 0.7071, 0.7071 )
-->     , yDirection = Direction2d ( -0.7071, 0.7071 )
-->     }

rotateAround : Point2d -> Float -> Frame2d -> Frame2d

Rotate a frame counterclockwise around a given point by a given angle. The frame's origin point will be rotated around the given point by the given angle, and its X and Y basis directions will be rotated by the given angle.

frame =
    Frame2d.at (Point2d ( 1, 1 ))


Frame2d.rotateAround Point2d.origin (degrees 45) frame
--> Frame2d
-->     { originPoint = Point2d ( 0, 1.4142 )
-->     , xDirection = Direction2d ( 0.7071, 0.7071 )
-->     , yDirection = Direction2d ( -0.7071, 0.7071 )
-->     }

translateBy : Vector2d -> Frame2d -> Frame2d

Translate a frame by a given displacement.

frame =
    Frame2d.at (Point2d ( 2, 3 ))


displacement =
    Vector2d ( 1, 1 )


Frame2d.translateBy displacement frame
--> Frame2d.at (Point2d ( 3, 4 ))

translateAlongOwn : (Frame2d -> Axis2d) -> Float -> Frame2d -> Frame2d

Translate a frame 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 frame. The majority of the time this argument will be either Frame2d.xAxis or Frame2d.yAxis. The second argument is the distance to translate along the given axis.

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

Frame2d.at (Point2d ( 2, 0 ))
    |> Frame2d.rotateBy (degrees 45)
    |> Frame2d.translateAlongOwn Frame2d.xAxis 2

means "construct a frame at the point (2, 0), rotate it around its own origin point by 45 degrees, then translate it along its own X axis by 2 units", resulting in

Frame2d
    { originPoint = Point2d ( 3.4142, 1.4142 )
    , xDirection = Direction2d ( 0.7071, 0.7071 )
    , yDirection = Direction2d ( -0.7071, 0.7071 )
    }

mirrorAcross : Axis2d -> Frame2d -> Frame2d

Mirror a frame across an axis.

frame =
    Frame2d.at (Point2d ( 2, 3 ))


Frame2d.mirrorAcross Axis2d.x frame
--> Frame2d
-->     { originPoint = Point2d ( 2, -3 )
-->     , xDirection = Direction2d.x
-->     , yDirection = Direction2d.flip Direction2d.y
-->     }

Note that this will switch the handedness of the frame.

Coordinate frames

relativeTo : Frame2d -> Frame2d -> Frame2d

Take two frames defined in global coordinates, and return the second one expressed in local coordinates relative to the first.

placeIn : Frame2d -> Frame2d -> Frame2d

Take one frame defined in global coordinates and a second frame defined in local coordinates relative to the first frame, and return the second frame expressed in global coordinates.

opensolid/geometry/1.0.2