A Camera2d maps a 2d scene to a screen.
The camera is defined by an origin point within the scene which is at the center of the camera, and a zoom ratio mapping scene units onto screen units.
The screen is defined by a bounding box defined in screen space.
The camera and screen together form a mapping from scene units and coordinates onto screen units and coordinates. Functions are provided to map points in both directions of this transformation. For example, going from screen to scene lets you map pointer events into the scene.
Functions are provided for moving the cameras origin point in scene or screen space, as well as for adjusting the zoom ratio.
A Camera2d is similar to an ianmackenzie/elm-geometry
Frame2d
but with the
addition of the zoom ratio.
A Camera onto a 2d scene, centered on a particular origin point in the scene and with a zoom ratio.
ZoomSpace is a mapping of the camera coordinates from (X, Y, Zoom) to (X, Y, 1 / Zoom). Linear motion of the camera in ZoomSpace maps to linear motion of the camera in the 3d space above the drawing.
The camera can be thought of as looking down from above onto a drawing on the 2d XY-plane at Z = 0. The camera has a height above this plane and always keeps the plane in perfect focus. As the cameras height changes, so does its degree of zoom.
ZoomSpace is linear with respect to this 3d space above the drawing. Linear motion of the camera in ZoomSpace will produce linear motion of the camera as imagined this way, and is useful for getting predictable animations of the camera position and zoom level.
zoomedAt : Point2d units coordinates -> Quantity Basics.Float (Quantity.Rate screenUnits units) -> Camera2d units screenUnits coordinates
Creates a camera centered at the origin point with the given zoom ratio.
fromZoomSpace : Point3d units (ZoomSpace screenUnits coordinates) -> Camera2d units screenUnits coordinates
Maps ZoomSpace to camera coords.
origin : Camera2d units screenUnits coordinates -> Point2d units coordinates
Gets the camera origin point in scene coordinates.
zoom : Camera2d units screenUnits coordinates -> Quantity Basics.Float (Quantity.Rate screenUnits units)
Gets the cameras current zoom level.
setOrigin : Point2d units coordinates -> Camera2d units screenUnits coordinates -> Camera2d units screenUnits coordinates
Shifts the camera origin point to a new location in scene coordinates.
setZoom : Quantity Basics.Float (Quantity.Rate screenUnits units) -> Camera2d units screenUnits coordinates -> Camera2d units screenUnits coordinates
Adjusts the camera zoom level.
The origin point will not be shifted by this operation. The effect of this on the screen mapping will be that the zoom is centered on the middle of the screen, and the origin point remains at the center of the screen.
setZoomAtScreenPoint : Quantity Basics.Float (Quantity.Rate screenUnits units) -> Point2d screenUnits screenCoordinates -> BoundingBox2d screenUnits screenCoordinates -> Camera2d units screenUnits coordinates -> Camera2d units screenUnits coordinates
Adjusts the camera zoom around a point on the screen. The point within the scene corresponding to the screen point, will be at the same screen point after the zoom adjustment.
This is convenient when adjusting the zoom around a pointer position, allowing a user to zoom in on a particular area under the pointer.
Note that if the screen point does not align with the origin point, then the origin point will be shifted by this operation.
translateBy : Vector2d units coordinates -> Camera2d units screenUnits coordinates -> Camera2d units screenUnits coordinates
Shifts the camera by a vector in screne coordinates.
translateByScreenVector : Vector2d screenUnits screenCoordinates -> Camera2d units screenUnits coordinates -> Camera2d units screenUnits coordinates
Shifts the camera origin point by a vector in screen coordinates.
This can be convenient when working with pointers on the screen.
pointToScene : Camera2d sceneUnits screenUnits sceneCoordinates -> BoundingBox2d screenUnits screenCoordinates -> Point2d screenUnits screenCoordinates -> Point2d sceneUnits sceneCoordinates
Maps a point in screen space to a point in scene space.
This can be useful when mapping pointer events onto a drawing, since the pointer events will be described by their screen coordinates.
pointToScreen : Camera2d sceneUnits screenUnits sceneCoordinates -> BoundingBox2d screenUnits screenCoordinates -> Point2d sceneUnits sceneCoordinates -> Point2d screenUnits screenCoordinates
Maps a point in scene space to a point in screen space.
This can be useful when overlaying something in screen space onto a drawing in scene space, for example a menu or other user interface construction that is not part of the drawing itself.
svgViewBox : Camera2d sceneUnits screenUnits sceneCoordinates -> BoundingBox2d screenUnits screenCoordinates -> TypedSvg.Core.Attribute a
Given a camera and a rectangular frame where a drawing will be rendered on
screen, provides the SVG viewBox
parameters that will yield a correctly scaled
and translated scene space described by that camera.
The screen coordinate defined frame will have the cameras origin point at its center, and the frame will be the same size as the whole SVG element. See svgViewBoxWithFocus for a version where the camera is centered in a different frame.
svgViewBoxWithFocus : Camera2d sceneUnits screenUnits sceneCoordinates -> BoundingBox2d screenUnits screenCoordinates -> BoundingBox2d screenUnits screenCoordinates -> TypedSvg.Core.Attribute a
Given a camera and a rectangular frame where a drawing will be rendered on
screen, provides the SVG viewBox
parameters that will yield a correctly scaled
and translated scene space described by that camera.
In this case two screen coordinate defined frames are provided to set up the camera. The first defines the area where the camera is considered to be focussed and centered on, but this does not have to occupy the whole of the SVG element. The second defines the boundary of the actual SVG element. Typically the first frame is wholly inside the second one, but it does not have to be.
This is useful if you want a camera that does not fill all of an SVG, you might have areas that show other things or some kind of overlay that you consider to be acting as a boundary to the camera frame.
If you have an SVG that fills the whole window
, and want the camera focussed on a
frame
inside that, this would give you the correct SVG viewBox parameters:
Camera2d.svgViewBoxWithFocus
camera
frame
window
interpolateFrom : Camera2d units screenUnits coordinates -> Camera2d units screenUnits coordinates -> Basics.Float -> Camera2d units screenUnits coordinates
Interpolate between one camera position and another in ZoomSpace.
toZoomSpace : Camera2d units screenUnits coordinates -> Point3d units (ZoomSpace screenUnits coordinates)
Maps the camera coords to ZoomSpace.
This is useful in conjunction with fromZoomSpace when animating the camera. See ZoomSpace for an explanation of the geometry of ZoomSpace and how it simplifies the camera motion.