camera

geo. camera

new camera(specnullable) → {geo.camera}

Description:

  • 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.
Source:
Parameters:
Name Type Attributes Description
spec object <nullable>

Options argument

Properties
Name Type Description
projection string

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

The initial camera viewport

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

Extends

Members

bounds

Description:

  • Getter/setter for the view bounds.

Source:
Properties:
Name Type Description
bounds object

The view bounds.

Properties
Name Type Description
left number
top number
right number
bottom number

Getter/setter for the view bounds.

clipbounds

Description:

  • 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.

Source:
Properties:
Name Type Description
clipbounds object

The clipbounds for the current projection.

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.

display

Description:

  • Getter for the "display" matrix. This matrix converts from world coordinates into display coordinates. Read only.

Source:
Properties:
Name Type Description
display mat4

The display matrix.

Getter for the "display" matrix. This matrix converts from world coordinates into display coordinates. Read only.

idle

Description:

  • Getter for the idle state. Read only.

Source:
Inherited From:
Properties:
Name Type Description
idle boolean

true if the object is idle (onIdle would call a handler immediately).

Getter for the idle state. Read only.

inverse

Description:

  • Getter for the inverse transform matrix. Read only.

Source:
Properties:
Name Type Description
inverse mat4

The inverse transform matrix.

Getter for the inverse transform matrix. Read only.

projection

Description:

  • Getter/setter for the projection type.

Source:
Properties:
Name Type Description
projection string

The projection type. One of parallel or perspective.

Getter/setter for the projection type.

Fires:

projectionMatrix

Description:

  • Getter for the projection matrix. Read only.

Source:
Properties:
Name Type Description
projectionMatrix mat4

The projection matrix.

Getter for the projection matrix. Read only.

transform

Description:

  • Getter for the transform matrix. This is the projection multiplied by the view matrix. Read only.

Source:
Properties:
Name Type Description
transform mat4

The transform matrix.

Getter for the transform matrix. This is the projection multiplied by the view matrix. Read only.

view

Description:

  • Getter/setter for the view matrix.

Source:
Properties:
Name Type Description
view mat4

The view matrix.

Getter/setter for the view matrix.

viewport

Description:

  • 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.

Source:
Properties:
Name Type Description
viewport object

The viewport in pixels.

Properties
Name Type Description
width number
height number
top number
left number

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.

Fires:

world

Description:

  • Getter for the "world" matrix. This matrix converts from display coordinates into world coordinates. This is the inverse of the "display" matrix. Read only.

Source:
Properties:
Name Type Description
world mat4

The world matrix.

Getter for the "world" matrix. This matrix converts from display coordinates into world coordinates. This is the inverse of the "display" matrix. Read only.

(static) clipbounds :number

Description:

  • Default camera clipping bounds. Some features and renderers may rely on the far clip value being more positive than the near clip value.

Source:
Properties:
Name Type Description
perspective number
parallel number

Default camera clipping bounds. Some features and renderers may rely on the far clip value being more positive than the near clip value.

Type:
  • number

(static) projection :boolean

Description:

  • Supported projection types.

Source:
Properties:
Name Type Description
perspective boolean
parallel boolean

Supported projection types.

Type:
  • boolean

Methods

addPromise(promise) → {this}

Description:

  • Add a new promise object preventing idle event handlers from being called until it is resolved.

Source:
Inherited From:
Parameters:
Name Type Description
promise Promise

A promise object.
Returns:
Type
this

applyProjection(pt) → {vec4}

Description:

  • Apply the camera's projection transform to the given point.

Source:
Parameters:
Name Type Description
pt vec4

a point in clipped coordinates.
Returns:

the point in normalized coordinates.

Type
vec4

css(transformopt) → {string}

Description:

  • 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.

Source:
Parameters:
Name Type Attributes Default Description
transform string <optional>
 'display'

The transform to return. One of display or world.
Returns:

The css transform string.

Type
string

debug() → {string}

Description:

  • Return a debugging string of the current camera state.

Source:
Returns:

A string with the camera state.

Type
string

displayToWorld(point) → {object}

Description:

  • Project a 2D point object from viewport space into world space. z is set to -1 to scale with the clip space.

Source:
Parameters:
Name Type Description
point object

The point in display coordinates.

Properties
Name Type Description
x number
y number
Returns:

The point in world coordinates.

Type
object

displayToWorld4(point) → {vec4}

Description:

  • Project a vector from viewport (display) space into world space. The resulting vector always has the last component (w) equal to 1.

Source:
Parameters:
Name Type Description
point vec3 | vec4

The point in display coordinates.
Returns:

The point in world space coordinates.

Type
vec4

geoIsOn(event, handleropt) → {boolean}

Description:

  • Report if an event handler is bound to this object.

Source:
Inherited From:
Parameters:
Name Type Attributes 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:

true if any of the specified events are bound to the specified handler.

Type
boolean

geoOff(eventopt, argopt, nullable) → {this}

Description:

  • Remove handlers from one event or an array of events. If no event is provided all handlers will be removed.

Source:
Inherited From:
Parameters:
Name Type Attributes 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
this

geoOn(event, handler) → {this}

Description:

  • Bind an event handler to this object.

Source:
Inherited From:
Parameters:
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
this

geoOnce(event, handler) → {function}

Description:

  • Bind an event handler to this object that will fire once and then deregister itself.

Source:
Inherited From:
Parameters:
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:

The actual bound handler. This is a wrapper around the handler that was passed to the function.

Type
function

geoTrigger(event, argsopt) → {this}

Description:

  • Trigger an event (or events) on this object and call all handlers.

Source:
Inherited From:
Parameters:
Name Type Attributes 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
this

modified() → {this}

Description:

  • Update the timestamp to the next global timestamp value.

Source:
Inherited From:
Returns:
Type
this

onIdle(handler) → {this}

Description:

  • 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.

Source:
Inherited From:
Parameters:
Name Type Description
handler function

A function taking no arguments.
Returns:
Type
this

pan(offset) → {this}

Description:

  • Pans the view matrix by the given amount.

Source:
Parameters:
Name Type Description
offset object

The delta in world space coordinates.

Properties
Name Type Attributes Default Description
x number
y number
z number <optional>
 0
Returns:

Chainable.

Type
this

ppMatrix(mat, precopt) → {string}

Description:

  • Represent a glmatrix as a pretty-printed string.

Source:
Parameters:
Name Type Attributes Description
mat mat4

A 4 x 4 matrix.
prec number <optional>

The number of decimal places.
Returns:
Type
string

removePromise(promise) → {this}

Description:

  • Mark a promise as no longer required to resolve before the idle state is reached.

Source:
Inherited From:
Parameters:
Name Type Description
promise Promise

A promise object.
Returns:
Type
this

timestamp() → {number}

Description:

  • Get time.

Source:
Inherited From:
Returns:

The timestamp. This is 0 if the timestamp has never been modified.

Type
number

toString() → {string}

Description:

  • Pretty print the transform matrix.

Source:
Returns:

A string representation of the matrix.

Type
string

unapplyProjection(pt) → {vec4}

Description:

  • Unapply the camera's projection transform from the given point.

Source:
Parameters:
Name Type Description
pt vec4

a point in normalized coordinates.
Returns:

the point in clipped coordinates.

Type
vec4

valueOf() → {mat4}

Description:

  • Represent the value of the camera as its transform matrix.

Source:
Returns:

The transform matrix.

Type
mat4

viewFromCenterSizeRotation(center, size, rotation) → {this}

Description:

  • 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.

Source:
Parameters:
Name Type Description
center object

Center of the view in gcs coordinates.

Properties
Name Type Description
x number
y number
size object

Minimum size of the view in gcs units.

Properties
Name Type Description
width number
height number
rotation number

in clockwise radians. Optional.
Returns:

Chainable.

Type
this

worldToDisplay(point) → {object}

Description:

  • Project a 2D point object from world space into viewport space. z is set to -this.clipbounds.near to scale with the clip space.

Source:
Parameters:
Name Type Description
point object

The point in world coordinates.

Properties
Name Type Description
x number
y number
Returns:

The point in display coordinates.

Type
object

worldToDisplay4(point) → {vec4}

Description:

  • Project a vector from world space into viewport (display) space. The resulting vector always has the last component (w) equal to 1.

Source:
Parameters:
Name Type Description
point vec3 | vec4

The point in world coordinates.
Returns:

The point in display coordinates.

Type
vec4

zoom(zoom) → {this}

Description:

  • Zooms the view matrix by the given amount.

Source:
Parameters:
Name Type Description
zoom number

The zoom scale to apply
Returns:

Chainable.

Type
this

(static) css(t) → {string}

Description:

  • Output a mat4 as a css transform. This expects that the transform-origin is 0 0.

Source:
Parameters:
Name Type Description
t mat4

A matrix transform.
Returns:

A css transform string.

Type
string