new geo.camera(spec){geo.camera}
This class defines the raw interface for a camera. At a low level, the camera provides a methods for converting between a map's coordinate system to display pixel coordinates.
For the moment, all camera transforms are assumed to be expressible as 4x4 matrices. More general cameras may follow that break this assumption.
The interface for the camera is relatively stable for "map-like" views, e.g. when the camera is pointing in the direction [0, 0, -1], and placed above the z=0 plane. More general view changes and events have not yet been defined.
The camera emits the following events when the view changes:
geo.event.camera.pan
when the camera is translated in the x/y planegeo.event.camera.zoom
when the camera is changed in a way that modifies the current zoom levelgeo.event.camera.view
when the visible bounds change for any reasongeo.event.camera.projection
when the projection type changesgeo.event.camera.viewport
when the viewport changes
By convention, protected methods do not update the internal matrix state, public methods do. There are a few primary methods that are intended to be used by external classes to mutate the internal state:
- bounds: Set the visible bounds (for initialization and zooming)
- pan: Translate the camera in x/y by an offset (for panning)
- viewFromCenterSizeRotation: set the camera view based on a center point, boundary size, and rotation angle.
Name | Type | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
spec |
object |
nullable
Options argument
|
Returns:
Type | Description |
---|---|
geo.camera |
Extends
Static Members
-
staticgeo.camera.clipboundsnumber
-
Default camera clipping bounds. Some features and renderers may rely on the far clip value being more positive than the near clip value.
Properties:
Name Type Default Description perspective
number {"left":"","right":1,"top":1,"bottom":"","far":2000,"near":0.01} parallel
number {"left":"","right":1,"top":1,"bottom":"","far":"","near":1} -
staticgeo.camera.projectionboolean
-
Supported projection types.
Properties:
Name Type Default Description perspective
boolean true parallel
boolean true
Members
-
bounds
-
Getter/setter for the view bounds.
Properties:
Name Type Description bounds
object The view bounds.
Properties
Name Type Description left
number top
number right
number bottom
number -
clipbounds
-
Getter/setter for the render clipbounds. Opposite bounds must have different values. There are independent clipbounds for each projection (parallel and perspective); switching the projection will switch to the clipbounds. Individual values of the clipbounds can be set either via a command like
camera.clipbounds = {near: 3, far: 1}
orcamera.clipbounds.near = 3
. In the second example, no check is made to ensure a non-zero volume clipbounds.Properties:
Name Type Description clipbounds
object The clipbounds for the current projection.
-
display
-
Getter for the "display" matrix. This matrix converts from world coordinates into display coordinates. Read only.
Properties:
Name Type Description display
mat4 The display matrix.
-
inherited idle
-
Getter for the idle state. Read only.
Properties:
Name Type Description idle
boolean true
if the object is idle (onIdle
would call a handler immediately). -
inverse
-
Getter for the inverse transform matrix. Read only.
Properties:
Name Type Description inverse
mat4 The inverse transform matrix.
-
projection
-
Getter/setter for the projection type.
Properties:
Name Type Description projection
string The projection type. One of
parallel
orperspective
. -
projectionMatrix
-
Getter for the projection matrix. Read only.
Properties:
Name Type Description projectionMatrix
mat4 The projection matrix.
-
transform
-
Getter for the transform matrix. This is the projection multiplied by the view matrix. Read only.
Properties:
Name Type Description transform
mat4 The transform matrix.
-
view
-
Getter/setter for the view matrix.
Properties:
Name Type Description view
mat4 The view matrix.
-
viewport
-
Getter/setter for the viewport.
The viewport consists of a width and height in pixels, plus a left and top offset in pixels. The offsets are only used to determine if pixel alignment is possible.
Properties:
Name Type Description viewport
object The viewport in pixels.
Properties
Name Type Description width
number height
number top
number left
number -
world
-
Getter for the "world" matrix. This matrix converts from display coordinates into world coordinates. This is the inverse of the "display" matrix. Read only.
Properties:
Name Type Description world
mat4 The world matrix.
Static Methods
-
Output a mat4 as a css transform. This expects that the transform-origin is 0 0.
Name Type Description t
mat4 A matrix transform.
Returns:
Type Description string A css transform string.
Methods
-
Add a new promise object preventing idle event handlers from being called until it is resolved.
Name Type Description promise
Promise A promise object.
Returns:
Type Description this -
Apply the camera's projection transform to the given point.
Name Type Description pt
vec4 a point in clipped coordinates.
Returns:
Type Description vec4 the point in normalized coordinates. -
Returns a CSS transform that converts (by default) from world coordinates into display coordinates. This allows users of this module to position elements using world coordinates directly inside DOM elements. This expects that the transform-origin is 0 0.
Name Type Default Description transform
string 'display' optional The transform to return. One of
display
orworld
.Returns:
Type Description string The css transform string. -
Return a debugging string of the current camera state.
Returns:
Type Description string A string with the camera state. -
Project a 2D point object from viewport space into world space.
z
is set to -1 to scale with the clip space.Name Type Description point
object The point in display coordinates.
Name Type Description x
number y
number Returns:
Type Description object The point in world coordinates. -
Project a vector from viewport (display) space into world space. The resulting vector always has the last component (
w
) equal to 1.Name Type Description point
vec3 | vec4 The point in display coordinates.
Returns:
Type Description vec4 The point in world space coordinates. -
Report if an event handler is bound to this object.
Name Type Description event
string | Array.<string> An event or list of events to check.
handler
function optional A function that might be bound. If
undefined
, this will reporttrue
if there is any handler for the specified event.Returns:
Type Description boolean true if any of the specified events are bound to the specified handler. -
Remove handlers from one event or an array of events. If no event is provided all handlers will be removed.
Name Type Description event
string | Array.<string> optional An event or a list of events from
geo.event
or defined by the user, orundefined
to remove all events (in which casearg
is ignored).arg
function | Array.<function()> optional nullable A function or array of functions to remove from the events or a falsy value to remove all handlers from the events.
Returns:
Type Description this -
Bind an event handler to this object.
Name Type Description event
string An event from
geo.event
or a user-defined value.handler
function A function that is called when
event
is triggered. The function is passed ageo.event
object.Returns:
Type Description this -
Bind an event handler to this object that will fire once and then deregister itself.
Name Type Description event
string An event from
geo.event
or a user-defined value.handler
function A function that is called when
event
is triggered. The function is passed ageo.event
object.Returns:
Type Description function The actual bound handler. This is a wrapper around the handler that was passed to the function. -
Trigger an event (or events) on this object and call all handlers.
Name Type Description event
string | Array.<string> An event or list of events from
geo.event
or defined by the user.args
object optional Additional information to add to the
geo.event
object passed to the handlers.Returns:
Type Description this -
inherited modified(){this}
-
Update the timestamp to the next global timestamp value.
Returns:
Type Description this -
Bind a handler that will be called one time when all internal promises are resolved. If there are no outstanding promises, this is invoked synchronously.
Name Type Description handler
function A function taking no arguments.
Returns:
Type Description this -
Pans the view matrix by the given amount.
Name Type Description offset
object The delta in world space coordinates.
Name Type Default Description x
number y
number z
number 0 optional Returns:
Type Description this Chainable. -
Represent a glmatrix as a pretty-printed string.
Name Type Description mat
mat4 A 4 x 4 matrix.
prec
number optional The number of decimal places.
Returns:
Type Description string -
Mark a promise as no longer required to resolve before the idle state is reached.
Name Type Description promise
Promise A promise object.
Returns:
Type Description this -
inherited timestamp(){number}
-
Get time.
Returns:
Type Description number The timestamp. This is 0 if the timestamp has never been modified. -
Pretty print the transform matrix.
Returns:
Type Description string A string representation of the matrix. -
Unapply the camera's projection transform from the given point.
Name Type Description pt
vec4 a point in normalized coordinates.
Returns:
Type Description vec4 the point in clipped coordinates. -
Represent the value of the camera as its transform matrix.
Returns:
Type Description mat4 The transform matrix. -
Sets the view matrix so that the given world center is centered, at least a certain width and height are visible, and a rotation is applied. The resulting bounds may be larger in width or height than the values if the viewport is a different aspect ratio.
Name Type Description center
object Center of the view in gcs coordinates.
Name Type Description x
number y
number size
object Minimum size of the view in gcs units.
Name Type Description width
number height
number rotation
number in clockwise radians. Optional.
Returns:
Type Description this Chainable. -
Project a 2D point object from world space into viewport space.
z
is set to-this.clipbounds.near
to scale with the clip space.Name Type Description point
object The point in world coordinates.
Name Type Description x
number y
number Returns:
Type Description object The point in display coordinates. -
Project a vector from world space into viewport (display) space. The resulting vector always has the last component (
w
) equal to 1.Name Type Description point
vec3 | vec4 The point in world coordinates.
Returns:
Type Description vec4 The point in display coordinates. -
Zooms the view matrix by the given amount.
Name Type Description zoom
number The zoom scale to apply
Returns:
Type Description this Chainable.