GeoJS

Class: camera

geo. camera

new geo.camera(spec){geo.camera}

camera.js, line 53

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:

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

Name Type Description
projection string

One of the supported geo.camera.projection.
viewport object

The initial camera viewport

Name Type Description
width object
height object
Returns:
Type Description
geo.camera

Extends

Static Members

staticgeo.camera.clipbounds

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 {"left":"","right":1,"top":1,"bottom":"","far":2000,"near":0.01}
parallel {"left":"","right":1,"top":1,"bottom":"","far":"","near":1}

staticgeo.camera.projection

Supported projection types.

Properties:
Name Type Default Description
perspective true
parallel 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} or camera.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 or perspective.

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

staticgeo.camera.css(2)(t){string}

camera.js, line 904

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

inherited addPromise(promise){this}

object.js, line 80

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

applyProjection(pt){vec4}

camera.js, line 468

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.

css(transform){string}

camera.js, line 772

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 or world.
Returns:
Type Description
string The css transform string.

debug(){string}

camera.js, line 824

Return a debugging string of the current camera state.

Returns:
Type Description
string A string with the camera state.

displayToWorld(point){object}

camera.js, line 557

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.

displayToWorld4(point){vec4}

camera.js, line 524

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 vec2 | vec3 | vec4

The point in display coordinates.
Returns:
Type Description
vec4 The point in world space coordinates.

inherited geoIsOn(event, handler){boolean}

object.js, line 189

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 report true 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.

inherited geoOff(event, arg){this}

object.js, line 248

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, or undefined to remove all events (in which case arg 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

inherited geoOn(event, handler){this}

object.js, line 139

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 a geo.event object.
Returns:
Type Description
this

inherited geoOnce(event, handler){function}

object.js, line 168

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 a geo.event object.
Returns:
Type Description
function The actual bound handler. This is a wrapper around the handler that was passed to the function.

inherited geoTrigger(event, args){this}

object.js, line 209

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}

timestamp.js, line 25

Update the timestamp to the next global timestamp value.

Returns:
Type Description
this

inherited onIdle(handler){this}

object.js, line 36

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

pan(offset){this}

camera.js, line 705

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.

ppMatrix(mat, prec){string}

camera.js, line 794

Represent a glmatrix as a pretty-printed string.

Name Type Description
mat mat4

A 4 x 4 matrix.
prec number

The number of decimal places.
Returns:
Type Description
string

inherited removePromise(promise){this}

object.js, line 116

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}

timestamp.js, line 37

Get time.

Returns:
Type Description
number The timestamp. This is 0 if the timestamp has never been modified.

toString(){string}

camera.js, line 816

Pretty print the transform matrix.

Returns:
Type Description
string A string representation of the matrix.

unapplyProjection(pt){vec4}

camera.js, line 487

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.

valueOf(){mat4}

camera.js, line 841

Represent the value of the camera as its transform matrix.

Returns:
Type Description
mat4 The transform matrix.

viewFromCenterSizeRotation(center, size, rotation){this}

camera.js, line 690

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.

worldToDisplay(point){object}

camera.js, line 542

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.

worldToDisplay4(point){vec4}

camera.js, line 508

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 vec2 | vec3 | vec4

The point in world coordinates.
Returns:
Type Description
vec4 The point in display coordinates.

zoom(zoom){this}

camera.js, line 724

Zooms the view matrix by the given amount.

Name Type Description
zoom number

The zoom scale to apply
Returns:
Type Description
this Chainable.