On this page

Class Camera`Abstract`

Methods mixed in to other classes for event capabilities.

Hierarchy (View Summary)

Evented
- Camera
  - MapLibreMap

Constructors

constructor

new Camera(
    transform: ITransform,
    cameraHelper: ICameraHelper,
    options: { bearingSnap: number; zoomSnap: number },
): Camera
Parameters
- transform: ITransform
- cameraHelper: ICameraHelper
- options: { bearingSnap: number; zoomSnap: number }
Returns Camera
Overrides Evented.constructor

Properties

cameraHelper

cameraHelper: ICameraHelper

handlers

handlers: HandlerManager

terrain

terrain: Terrain

transform

transform: ITransform

transformCameraUpdate

transformCameraUpdate: CameraUpdateTransformFunction | null

A callback used to defer camera updates or apply arbitrary constraints. If specified, this Camera instance can be used as a stateless component in React etc.

Methods

calculateCameraOptionsFromCameraLngLatAltRotation

calculateCameraOptionsFromCameraLngLatAltRotation(
    cameraLngLat: LngLatLike,
    cameraAlt: number,
    bearing: number,
    pitch: number,
    roll?: number,
): CameraOptions
Given a camera position and rotation, calculates zoom and center point and returns them as CameraOptions.
Parameters
- cameraLngLat: LngLatLike
  The lng, lat of the camera to look from
- cameraAlt: number
  The altitude of the camera to look from, in meters above sea level
- bearing: number
  Bearing of the camera, in degrees
- pitch: number
  Pitch of the camera, in degrees
- Optionalroll: number
  Roll of the camera, in degrees
Returns CameraOptions
the calculated camera options
Example
```
// Calculate options to look from camera position(1°, 0°, 1000m) with bearing = 90°, pitch = 30°, and roll = 45°
const cameraLngLat = new LngLat(1, 0);
const cameraAltitude = 1000;
const bearing = 90;
const pitch = 30;
const roll = 45;
const cameraOptions = map.calculateCameraOptionsFromCameraLngLatAltRotation(cameraLngLat, cameraAltitude, bearing, pitch, roll);
// Apply calculated options
map.jumpTo(cameraOptions);
```

calculateCameraOptionsFromTo

calculateCameraOptionsFromTo(
    from: LngLatLike,
    altitudeFrom: number,
    to: LngLatLike,
    altitudeTo?: number,
): CameraOptions
Given a camera 'from' position and a position to look at (to), calculates zoom and camera rotation and returns them as CameraOptions.
Parameters
- from: LngLatLike
  The camera to look from
- altitudeFrom: number
  The altitude of the camera to look from
- to: LngLatLike
  The center to look at
- OptionalaltitudeTo: number
  Optional altitude of the center to look at. If none given the ground height will be used.
Returns CameraOptions
the calculated camera options
Example
```
// Calculate options to look from (1°, 0°, 1000m) to (1°, 1°, 0m)
const cameraLngLat = new LngLat(1, 0);
const cameraAltitude = 1000;
const targetLngLat = new LngLat(1, 1);
const targetAltitude = 0;
const cameraOptions = map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitude, targetLngLat, targetAltitude);
// Apply calculated options
map.jumpTo(cameraOptions);
```

cameraForBounds

cameraForBounds(
bounds: LngLatBoundsLike,
options?: CameraForBoundsOptions,
): CenterZoomBearing | undefined
Parameters
- bounds: LngLatBoundsLike
  Calculate the center for these bounds in the viewport and use the highest zoom level up to and including Map.getMaxZoom that fits in the viewport. LngLatBounds represent a box that is always axis-aligned with bearing 0. Bounds will be taken in [sw, ne] order. Southwest point will always be to the left of the northeast point.
- Optionaloptions: CameraForBoundsOptions
  Options object
Returns CenterZoomBearing | undefined
If map is able to fit to provided bounds, returns center, zoom, and bearing. If map is unable to fit, method will warn and return undefined.
Example
```
let bbox = [[-79, 43], [-73, 45]];
let newCameraTransform = map.cameraForBounds(bbox, {
  padding: {top: 10, bottom:25, left: 15, right: 5}
});
```

easeTo

easeTo(options: EaseToOptions, eventData?: any): this
Changes any combination of center, zoom, bearing, pitch, roll, and padding with an animated transition between old and new values. The map will retain its current values for any details not specified in options.

!!! note "Reduced Motion" The transition will happen instantly if the user has enabled the reduced motion accessibility feature enabled in their operating system, unless options includes essential: true.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, zoomend, pitchstart, pitch, pitchend, rollstart, roll, rollend, and rotate.
Parameters
- options: EaseToOptions
  Options describing the destination and animation of the transition. Accepts CameraOptions and AnimationOptions.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
See
Navigate the map with game-like controls

fire

fire(event: string | Event, properties?: any): this
Parameters
- event: string | Event
- Optionalproperties: any
Returns this
Inherited from Evented.fire

fitBounds

fitBounds(
    bounds: LngLatBoundsLike,
    options?: FitBoundsOptions,
    eventData?: any,
): this
Pans and zooms the map to contain its visible area within the specified geographical bounds. This function will also reset the map's bearing to 0 if bearing is nonzero.

Triggers the following events: movestart and moveend.
Parameters
- bounds: LngLatBoundsLike
  Center these bounds in the viewport and use the highest zoom level up to and including Map.getMaxZoom that fits them in the viewport. Bounds will be taken in [sw, ne] order. Southwest point will always be to the left of the northeast point.
- Optionaloptions: FitBoundsOptions
  Options supports all properties from AnimationOptions and CameraOptions in addition to the fields below.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
let bbox = [[-79, 43], [-73, 45]];
map.fitBounds(bbox, {
  padding: {top: 10, bottom:25, left: 15, right: 5}
});
```
See
Fit a map to a bounding box

fitScreenCoordinates

fitScreenCoordinates(
    p0: PointLike,
    p1: PointLike,
    bearing: number,
    options?: FitBoundsOptions,
    eventData?: any,
): this
Pans, rotates and zooms the map to to fit the box made by points p0 and p1 once the map is rotated to the specified bearing. To zoom without rotating, pass in the current map bearing.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, zoomend and rotate.
Parameters
- p0: PointLike
  First point on screen, in pixel coordinates
- p1: PointLike
  Second point on screen, in pixel coordinates
- bearing: number
  Desired map bearing at end of animation, in degrees
- Optionaloptions: FitBoundsOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
let p0 = [220, 400];
let p1 = [500, 900];
map.fitScreenCoordinates(p0, p1, map.getBearing(), {
  padding: {top: 10, bottom:25, left: 15, right: 5}
});
```
See
Used by BoxZoomHandler

flyTo

flyTo(options: FlyToOptions, eventData?: any): this
Changes any combination of center, zoom, bearing, pitch, and roll, animating the transition along a curve that evokes flight. The animation seamlessly incorporates zooming and panning to help the user maintain her bearings even after traversing a great distance.

!!! note "Reduced Motion" The animation will be skipped, and this will behave equivalently to jumpTo if the user has the reduced motion accessibility feature enabled in their operating system, unless 'options' includes essential: true.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, zoomend, pitchstart, pitch, pitchend, rollstart, roll, rollend, and rotate.
Parameters
- options: FlyToOptions
  Options describing the destination and animation of the transition. Accepts CameraOptions, AnimationOptions, and the following additional options.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
// fly with default options to null island
map.flyTo({center: [0, 0], zoom: 9});
// using flyTo options
map.flyTo({
  center: [0, 0],
  zoom: 9,
  speed: 0.2,
  curve: 1,
  easing(t) {
    return t;
  }
});
```
See

getBearing

getBearing(): number
Returns the map's current bearing. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.

Returns number
The map's current bearing.

See
Navigate the map with game-like controls

getCenter

getCenter(): LngLat
Returns the map's geographical centerpoint.

Returns LngLat
The map's geographical centerpoint.
Example
Return a LngLat object such as {lng: 0, lat: 0}
```
let center = map.getCenter();
// access longitude and latitude values directly
let {lng, lat} = map.getCenter();
```

getCenterClampedToGround

getCenterClampedToGround(): boolean
Returns the value of centerClampedToGround.

If true, the elevation of the center point will automatically be set to the terrain elevation (or zero if terrain is not enabled). If false, the elevation of the center point will default to sea level and will not automatically update. Defaults to true. Needs to be set to false to keep the camera above ground when pitch > 90 degrees.

Returns boolean

getCenterElevation

getCenterElevation(): number
Returns the elevation of the map's center point.

Returns number
The elevation of the map's center point, in meters above sea level.

getPadding

getPadding(): PaddingOptions
Returns the current padding applied around the map viewport.

Returns PaddingOptions
The current padding around the map viewport.

getPitch

getPitch(): number
Returns the map's current pitch (tilt).

Returns number
The map's current pitch, measured in degrees away from the plane of the screen.

getRoll

getRoll(): number
Returns the map's current roll angle.

Returns number
The map's current roll, measured in degrees about the camera boresight.

getVerticalFieldOfView

getVerticalFieldOfView(): number
Returns the map's current vertical field of view, in degrees.

Returns number
The map's current vertical field of view.
Default Value
```
36.87
```
Example
```
const verticalFieldOfView = map.getVerticalFieldOfView();
```

getZoom

getZoom(): number
Returns the map's current zoom level.

Returns number
The map's current zoom level.
Example
```
map.getZoom();
```

getZoomSnap

getZoomSnap(): number
Returns the map's current zoom snap level.

Returns number
The map's current zoom snap level.

isEasing

isEasing(): boolean
Returns boolean

jumpTo(options: JumpToOptions, eventData?: any): this
Changes any combination of center, zoom, bearing, pitch, and roll, without an animated transition. The map will retain its current values for any details not specified in options.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, zoomend, pitchstart, pitch, pitchend, rollstart, roll, rollend and rotate.
Parameters
- options: JumpToOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
// jump to coordinates at current zoom
map.jumpTo({center: [0, 0]});
// jump with zoom, pitch, and bearing options
map.jumpTo({
  center: [0, 0],
  zoom: 8,
  pitch: 45,
  bearing: 90
});
```
See
- Jump to a series of locations
- Update a feature in realtime

listens

listens(type: string): boolean
Returns a true if this instance of Evented or any forwardeed instances of Evented have a listener for the specified type.
Parameters
- type: string
  The event type
Returns boolean
true if there is at least one registered listener for specified event type, false otherwise

Inherited from Evented.listens

migrateProjection

migrateProjection(
newTransform: ITransform,
newCameraHelper: ICameraHelper,
): void
Parameters
- newTransform: ITransform
- newCameraHelper: ICameraHelper
Returns void
Internal
Creates a new specialized transform instance from a projection instance and migrates to this new transform, carrying over all the properties of the old transform (center, pitch, etc.). When the style's projection is changed (or first set), this function should be called.

off

off(type: string, listener: Listener): this
Removes a previously registered event listener.
Parameters
- type: string
  The event type to remove listeners for.
- listener: Listener
  The listener function to remove.
Returns this
Inherited from Evented.off

on

on(type: string, listener: Listener): Subscription
Adds a listener to a specified event type.
Parameters
- type: string
  The event type to add a listen for.
- listener: Listener
  The function to be called when the event is fired. The listener function is called with the data object passed to fire, extended with target and type properties.
Returns Subscription
Inherited from Evented.on

once

once(type: string, listener?: Listener): Camera | Promise<any>
Adds a listener that will be called only once to a specified event type.

The listener will be called first time the event fires after the listener is registered.
Parameters
- type: string
  The event type to listen for.
- Optionallistener: Listener
  The function to be called when the event is fired the first time.
Returns Camera | Promise<any>
this or a promise if a listener is not provided

Inherited from Evented.once

panBy

panBy(offset: PointLike, options?: EaseToOptions, eventData?: any): this
Pans the map by the specified offset.

Triggers the following events: movestart and moveend.
Parameters
- offset: PointLike
  x and y coordinates by which to pan the map.
- Optionaloptions: EaseToOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
See
Navigate the map with game-like controls

panTo

panTo(lnglat: LngLatLike, options?: EaseToOptions, eventData?: any): this
Pans the map to the specified location with an animated transition.

Triggers the following events: movestart and moveend.
Parameters
- lnglat: LngLatLike
  The location to pan the map to.
- Optionaloptions: EaseToOptions
  Options describing the destination and animation of the transition.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
map.panTo([-74, 38]);
// Specify that the panTo animation should last 5000 milliseconds.
map.panTo([-74, 38], {duration: 5000});
```
See
Update a feature in realtime

queryTerrainElevation

queryTerrainElevation(lngLatLike: LngLatLike): number | null
Gets the elevation at a given location, in meters above sea level. Returns null if terrain is not enabled. If terrain is enabled with some exaggeration value, the value returned here will be reflective of (multiplied by) that exaggeration value. This method should be used for proper positioning of custom 3d objects, as explained here
Parameters
- lngLatLike: LngLatLike
  [x,y] or LngLat coordinates of the location
Returns number | null
elevation in meters

resetNorth

resetNorth(options?: AnimationOptions, eventData?: any): this
Rotates the map so that north is up (0° bearing), with an animated transition.

Triggers the following events: movestart, moveend, and rotate.
Parameters
- Optionaloptions: AnimationOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

resetNorthPitch

resetNorthPitch(options?: AnimationOptions, eventData?: any): this
Rotates and pitches the map so that north is up (0° bearing) and pitch and roll are 0°, with an animated transition.

Triggers the following events: movestart, move, moveend, pitchstart, pitch, pitchend, rollstart, roll, rollend, and rotate.
Parameters
- Optionaloptions: AnimationOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

rotateTo

rotateTo(bearing: number, options?: EaseToOptions, eventData?: any): this
Rotates the map to the specified bearing, with an animated transition. The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.

Triggers the following events: movestart, moveend, and rotate.
Parameters
- bearing: number
  The desired bearing.
- Optionaloptions: EaseToOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

setBearing

setBearing(bearing: number, eventData?: any): this
Sets the map's bearing (rotation). The bearing is the compass direction that is "up"; for example, a bearing of 90° orients the map so that east is up.

Equivalent to jumpTo({bearing: bearing}).

Triggers the following events: movestart, moveend, and rotate.
Parameters
- bearing: number
  The desired bearing.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
Rotate the map to 90 degrees
```
map.setBearing(90);
```

setCenter

setCenter(center: LngLatLike, eventData?: any): this
Sets the map's geographical centerpoint. Equivalent to jumpTo({center: center}).

Triggers the following events: movestart and moveend.
Parameters
- center: LngLatLike
  The centerpoint to set.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
map.setCenter([-74, 38]);
```

setCenterClampedToGround

setCenterClampedToGround(centerClampedToGround: boolean): void
Sets the value of centerClampedToGround.

If true, the elevation of the center point will automatically be set to the terrain elevation (or zero if terrain is not enabled). If false, the elevation of the center point will default to sea level and will not automatically update. Defaults to true. Needs to be set to false to keep the camera above ground when pitch > 90 degrees.
Parameters
- centerClampedToGround: boolean
Returns void

setCenterElevation

setCenterElevation(elevation: number, eventData?: any): this
Sets the elevation of the map's center point, in meters above sea level. Equivalent to jumpTo({elevation: elevation}).

Triggers the following events: movestart and moveend.
Parameters
- elevation: number
  The elevation to set, in meters above sea level.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

setEventedParent

setEventedParent(parent?: Evented | null, data?: any): this
Bubble all events fired by this instance of Evented to this parent instance of Evented.
Parameters
- Optionalparent: Evented | null
- Optionaldata: any
Returns this
Inherited from Evented.setEventedParent

setPadding

setPadding(padding: PaddingOptions, eventData?: any): this
Sets the padding in pixels around the viewport.

Equivalent to jumpTo({padding: padding}).

Triggers the following events: movestart and moveend.
Parameters
- padding: PaddingOptions
  The desired padding.
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
Sets a left padding of 300px, and a top padding of 50px
```
map.setPadding({ left: 300, top: 50 });
```

setPitch

setPitch(pitch: number, eventData?: any): this
Sets the map's pitch (tilt). Equivalent to jumpTo({pitch: pitch}).

Triggers the following events: movestart, moveend, pitchstart, and pitchend.
Parameters
- pitch: number
  The pitch to set, measured in degrees away from the plane of the screen (0-60).
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

setRoll

setRoll(roll: number, eventData?: any): this
Sets the map's roll angle. Equivalent to jumpTo({roll: roll}).

Triggers the following events: movestart, moveend, rollstart, and rollend.
Parameters
- roll: number
  The roll to set, measured in degrees about the camera boresight
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

setVerticalFieldOfView

setVerticalFieldOfView(fov: number, eventData?: any): this
Sets the map's vertical field of view, in degrees.

Triggers the following events: movestart, move, and moveend.
Parameters
- fov: number
  The vertical field of view to set, in degrees (0-180).
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Default Value
```
36.87
```
Example
Change vertical field of view to 30 degrees
```
map.setVerticalFieldOfView(30);
```

setZoom

setZoom(zoom: number, eventData?: any): this
Sets the map's zoom level. Equivalent to jumpTo({zoom: zoom}).

Triggers the following events: movestart, move, moveend, zoomstart, zoom, and zoomend.
Parameters
- zoom: number
  The zoom level to set (0-20).
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
Zoom to the zoom level 5 without an animated transition
```
map.setZoom(5);
```

setZoomSnap

setZoomSnap(snap: number): this
Sets the map's zoom snap level.
Parameters
- snap: number
  The zoom snap level to set.
Returns this

snapToNorth

snapToNorth(options?: AnimationOptions, eventData?: any): this
Snaps the map so that north is up (0° bearing), if the current bearing is close enough to it (i.e. within the bearingSnap threshold).

Triggers the following events: movestart, moveend, and rotate.
Parameters
- Optionaloptions: AnimationOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this

stop

stop(): this
Stops any animated transition underway.

Returns this

zoomIn

zoomIn(options?: AnimationOptions, eventData?: any): this
Incrementally increases the map's zoom level by 1, first snapping to the nearest zoomSnap increment.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, and zoomend.
Parameters
- Optionaloptions: AnimationOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
Zoom the map in one level with a custom animation duration
```
map.zoomIn({duration: 1000});
```

zoomOut

zoomOut(options?: AnimationOptions, eventData?: any): this
Decreases the map's zoom level by 1, first snapping to the nearest zoomSnap increment.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, and zoomend.
Parameters
- Optionaloptions: AnimationOptions
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
Zoom the map out one level with a custom animation offset
```
map.zoomOut({offset: [80, 60]});
```

zoomTo

zoomTo(zoom: number, options?: EaseToOptions | null, eventData?: any): this
Zooms the map to the specified zoom level, with an animated transition.

Triggers the following events: movestart, move, moveend, zoomstart, zoom, and zoomend.
Parameters
- zoom: number
  The zoom level to transition to.
- Optionaloptions: EaseToOptions | null
  Options object
- OptionaleventData: any
  Additional properties to be added to event objects of events triggered by this method.
Returns this
Example
```
// Zoom to the zoom level 5 without an animated transition
map.zoomTo(5);
// Zoom to the zoom level 8 with an animated transition
map.zoomTo(8, {
  duration: 2000,
  offset: [100, 50]
});
```

Was this helpful?

Class CameraAbstract

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Camera

Properties

cameraHelper

handlers

terrain

transform

transformCameraUpdate

Methods

calculateCameraOptionsFromCameraLngLatAltRotation

Parameters

Returns CameraOptions

Example

calculateCameraOptionsFromTo

Parameters

Returns CameraOptions

Example

cameraForBounds

Parameters

Returns CenterZoomBearing | undefined

Example

easeTo

Parameters

Returns this

See

fire

Parameters

Returns this

fitBounds

Parameters

Returns this

Example

See

fitScreenCoordinates

Parameters

Returns this

Example

See

flyTo

Parameters

Returns this

Example

See

getBearing

Returns number

See

getCenter

Returns LngLat

Example

getCenterClampedToGround

Returns boolean

getCenterElevation

Returns number

getPadding

Returns PaddingOptions

getPitch

Returns number

getRoll

Returns number

getVerticalFieldOfView

Returns number

Default Value

Example

getZoom

Returns number

Example

getZoomSnap

Returns number

isEasing

Returns boolean

jumpTo

Parameters

Class Camera`Abstract`