This is the technical documentation for Tangram’s cameras. For a conceptual overview of the camera system, see the Cameras Overview.

cameras

The cameras element is an optional top-level element in the scene file. Individual cameras are defined by a camera name under this element.

cameras:
    camera1:
        type: perspective
    camera2:
        type: perspective
    overview:
        type: isometric

camera

It is also permissable to use the element name camera at the top level, if there is only a single camera in the scene:

camera:
    type: perspective

camera names

Required string (except in the case of camera). Can be anything except the reserved keywords. No default.

cameras:
    myCamera:
        type: perspective
    camera2:
        type: perspective
    lock-off:
        type: perspective

common camera parameters

type

Required string. One of perspective, isometric, or flat. No default.

cameras:
    camera1:
        type: perspective
    camera2:
        type: isometric
    overview:
        type: flat

position

Optional [lat, lng] or [lat, lng, zoom]. No default.

Sets the longitude and latitude of the camera, in degrees.

camera1:
    position: [-73.97297501564027, 40.76434821445407]

zoom

Optional number. Default: 15

Sets the zoom level of the view, in standard Web Mercator zoom levels.

camera1:
    zoom: 14

active

Optional boolean. true or false. No default.

Sets the camera which provides the active view of the map when it is first loaded. If multiple cameras are defined, only one may be active at a time. If multiple cameras are set as active: true, the behavior will be unpredictable (see the yaml#mappings entry). The JavaScript API can be used to get or set the active camera.

camera1:
    active: false

max_tilt

[ES-only] Optional number or stops. Degrees. Defaults to 90.

Sets the maximum angle from vertical that the camera is permitted to tilt. For cameras with type: isometric the tilt is further constrained at high zooms to prevent the viewing plane from intersecting the ground.

perspective camera parameters

focal_length

Optional number or stops. Unitless. Defaults to [[16, 2], [17, 2.5], [18, 3], [19, 4], [20, 6]].

Sets the amount of vertical exaggeration in the z-plane. Changes the apparent height of extruded elements. Lower values = more exaggeration. Also see fov.

camera1:
    focal_length: [[16, 2], [17, 2.5], [18, 3], [19, 4], [20, 6]]

vanishing_point

Optional [number, number], in px. Defaults to [0px, 0px]. Units default to px.

Sets the apparent perspective origin, in pixels from the center of the screen.

camera1:
    type: perspective
    vanishing_point: [-250, -250]

fov

Optional number.

Sets the “field of view” of the camera, in degrees. Field of view has an inverse relationship with focal_length: higher values cause more exaggeration. If both are set, focal_length will take precedence over fov.

camera1:
    fov: 80

isometric camera parameters

axis

Optional [number, number]. Default: [0, 1]

Sets the [x, y] direction and amount of the isometric camera’s vertical axis, which controls controls how extruded objects’ height is displayed. A value of 1 equals a scale of 100%. Larger values produce more scaling.

isometric-cam:
    type: isometric
    axis: [1, .5]

flat camera parameters

The flat camera presents a top-down 2D map view (extrusion is not visible), and has no unique parameters.