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:
relativeTo
and placeIn
functions that convert values of that type from global
coordinates to local coordinates in a particular frame, and vice versa.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.Geometry.Types.Frame2d
xy : Frame2d
The global XY frame.
Frame2d.originPoint Frame2d.xy
--> Point2d.origin
Frame2d.xDirection Frame2d.xy
--> Direction2d.x
Frame2d.yDirection Frame2d.xy
--> Direction2d.y
atPoint : Point2d -> Frame2d
Construct a frame aligned with the global XY frame but with the given origin point.
point =
Point2d.fromCoordinates ( 2, 3 )
frame =
Frame2d.atPoint point
Frame2d.originPoint frame
--> point
Frame2d.xDirection frame
--> Direction2d.x
Frame2d.yDirection frame
--> Direction2d.y
atCoordinates : ( Basics.Float, Basics.Float ) -> Frame2d
Shorthand for Frame2d.atPoint
;
Frame2d.atCoordinates ( x, y )
is equivalent to
Frame2d.atPoint (Point2d.fromCoordinates ( x, y ))
withXDirection : Direction2d -> Point2d -> Frame2d
Construct a frame with the given X axis direction, having the given origin point. The Y axis direction will be constructed by rotating the given X direction 90 degrees counterclockwise:
frame =
Frame2d.withXDirection
(Direction2d.fromAngle (degrees 30))
(Point2d.fromCoordinates ( 2, 3 ))
Frame2d.yDirection frame
--> Direction2d.fromAngle (degrees 120)
withYDirection : Direction2d -> Point2d -> Frame2d
Construct a frame with the given Y axis direction, having the given origin point. The X axis direction will be constructed by rotating the given X direction 90 degrees clockwise:
frame =
Frame2d.withYDirection
(Direction2d.fromAngle (degrees 30))
(Point2d.fromCoordinates ( 2, 3 ))
Frame2d.yDirection frame
--> Direction2d.fromAngle (degrees -60)
unsafe : { originPoint : Point2d, xDirection : Direction2d, yDirection : Direction2d } -> Frame2d
Construct a frame directly from its origin point and X and Y directions:
frame =
Frame2d.unsafe
{ originPoint =
Point2d.fromCoordinates ( 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. To construct pairs of perpendicular directions,
Direction2d.orthonormalize
or
Direction2d.orthogonalize
may be useful.
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
isRightHanded : Frame2d -> Basics.Bool
Check if a frame is right-handed.
Frame2d.isRightHanded Frame2d.xy
--> True
Frame2d.isRightHanded (Frame2d.reverseX Frame2d.xy)
--> False
All predefined frames are right-handed, and most operations on frames preserve
handedness, so about the only ways to end up with a left-handed frame are by
constructing one explicitly with unsafe
or by mirroring a right-handed frame.
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
reverseX : Frame2d -> Frame2d
Reverse the X direction of a frame, leaving its Y direction and origin point the same.
point =
Point2d.fromCoordinates ( 2, 3 )
frame =
Frame2d.atPoint point |> Frame2d.reverseX
Frame2d.originPoint frame
--> point
Frame2d.xDirection frame
--> Direction2d.negativeX
Frame2d.yDirection frame
--> Direction2d.y
Note that this will switch the handedness of the frame.
reverseY : Frame2d -> Frame2d
Reverse the Y direction of a frame, leaving its X direction and origin point the same.
point =
Point2d.fromCoordinates ( 2, 3 )
frame =
Frame2d.atPoint point |> Frame2d.reverseY
Frame2d.originPoint frame
--> point
Frame2d.xDirection frame
--> Direction2d.x
Frame2d.yDirection frame
--> Direction2d.negativeY
Note that this will switch the handedness of the frame.
moveTo : Point2d -> Frame2d -> Frame2d
Move a frame so that it has the given origin point.
point =
Point2d.fromCoordinates ( 1, 1 )
Frame2d.xy |> Frame2d.moveTo point
--> Frame2d.atPoint point
rotateBy : Basics.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.
rotatedFrame =
Frame2d.rotateBy (degrees 30) Frame2d.xy
Frame2d.xDirection rotatedFrame
--> Direction2d.fromAngle (degrees 30)
Frame2d.yDirection rotatedFrame
--> Direction2d.fromAngle (degrees 120)
rotateAround : Point2d -> Basics.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.
rotatedFrame =
Frame2d.atPoint (Point2d.fromCoordinates ( 1, 1 ))
|> Frame2d.rotateAround Point2d.origin
(degrees 45)
Frame2d.originPoint rotatedFrame
--> Point2d.fromCoordinates ( 0, 1.4142 )
Frame2d.xDirection rotatedFrame
--> Direction2d.fromAngle (degrees 45)
Frame2d.yDirection rotatedFrame
--> Direction2d.fromAngle (degrees 135)
translateBy : Vector2d -> Frame2d -> Frame2d
Translate a frame by a given displacement.
frame =
Frame2d.atPoint (Point2d.fromCoordinates ( 2, 3 ))
displacement =
Vector2d.fromComponents ( 1, 1 )
Frame2d.translateBy displacement frame
--> Frame2d.atPoint (Point2d.fromCoordinates ( 3, 4 ))
translateIn : Direction2d -> Basics.Float -> Frame2d -> Frame2d
Translate a frame in a given direction by a given distance;
Frame2d.translateIn direction distance
is equivalent to
Frame2d.translateBy
(Vector2d.withLength distance direction)
translateAlongOwn : (Frame2d -> Axis2d) -> Basics.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,
frame =
Frame2d.atPoint (Point2d.fromCoordinates ( 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 frame
--> Point2d.fromCoordinates ( 3.4142, 1.4142 )
Frame2d.xDirection frame
--> Direction2d.fromAngle (degrees 45)
Frame2d.yDirection frame
--> Direction2d.fromAngle (degrees 135)
mirrorAcross : Axis2d -> Frame2d -> Frame2d
Mirror a frame across an axis.
frame =
Frame2d.atPoint (Point2d.fromCoordinates ( 2, 3 ))
mirroredFrame =
Frame2d.mirrorAcross Axis2d.x frame
Frame2d.originPoint mirroredFrame
--> Point2d.fromCoordinates ( 2, -3 )
Frame2d.xDirection mirroredFrame
--> Direction2d.x
Frame2d.yDirection mirroredFrame
--> Direction2d.negativeY
Note that this will switch the handedness of the frame.
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.