This is the technical documentation for Tangram’s lights. For a conceptual overview of the lighting system, see the Lights Overview.

Lights

The lights element is a top-level element in the scene file. Individual lights are defined by a light name under this element.

lights:
    mainlight:
        type: directional

Note: To have your map colors match your style colors exactly in all cases, do not specify any lights. In this case, the default light will be a directional light whose diffuse and ambient components have been tuned to exactly produce 100% illumination, while providing some shading on 3D-extruded features. In this way, 3D buildings will have shading, while the colors of all other flat features will precisely match their color declarations.

Light names

Required string. Can be anything*. No default.

lights:
    light1:
        type: ambient
    directionalLight:
        type: directional
    point-light:
        type: point

• For technical reasons, hyphens in light names are converted to underscores internally. Thus "light-1" becomes "light_1". For this reason, you may not have two lights whose names are identical except for a hyphen in one case and an underscore in the same place in the other (eg "light-1" and "light_1"a) as they will be interpreted as the same name.

Common light parameters

type

Required string. One of ambient, directional, point, or spotlight. No default.

lights:
    light1:
        type: ambient
    light2:
        type: directional
    light3:
        type: point
    light4:
        type: spotlight

ambient

Optional parameter. number, [R, G, B], hex-color, or css color name. Numerical values go from 0 to 1. Defaults to 0.

    light1:
        type: point
        diffuse: white
        ambient: .3

diffuse

Optional parameter. number, [R, G, B], hex-color, or css color name. Numerical values go from 0 to 1. Defaults to 1.

light1:
    type: point
    diffuse: white

specular

Optional parameter. number, [R, G, B], hex-color, or css color name. Numerical values go from 0 to 1. Default is 0.

light1:
    type: directional
    direction: [0, 1, -.5]
    diffuse: white
    specular: ‘#FFFF99’

visible

Optional Boolean. Default is true.

Allows a defined light to be disabled or enabled through the JavaScript API.

light1:
    type: point
    visible: false

Directional light properties

direction

Optional vector. [x, y, z]. Defaults to [0.2, 0.7, -0.5]

light1:
    type: directional
    direction: [0, 1, -.5]

Point light properties

position

Required vector [x, y, z], [long, lat], or { lng: number, lat: number }. Vectors may be specified in meters m, pixels px, or degrees, depending on the value of origin. [long, lat]s may be specified as lists or objects of the format { lng: number, lat: number}. Default is [0, 0, 100px].

Default unit for origins or camera and ground are m. When origin is world x and y are interpreted as degrees.

lights:
    cameralight:
        type: point
        position: [0px, 0px, -700px]
        origin: camera

    worldlight-ground:
        type: point
        position: [ 0m, 100m, 500m ]
        origin: ground

    worldlight-world:
        type: point
        position: [-74.00976419448853, 40.70531887544228, 500m]
        origin: world

origin

Optional string, one of world, camera, or ground. Defaults to ground.

Sets the reference point for the position parameter:

• world: sets x and y in [long, lat] and z in m from the ground
• camera: sets x and y in px from the camera center, and z in m from the camera
• ground: sets x and y in px from the point on the ground in the center of the current view, and z in m from the ground

light1:
    type: point
    position: [0px, 0px, 300px]
    origin: ground

radius

Optional number or [inner_radius, outer_radius]. Assumes units of meters m. Defaults to null.

If only a single number is set, it defines the outer radius, and the inner radius is set to 0.

light1:
    type: point
    diffuse: white
    radius: [300,700]

attenuation

Optional number. Defaults to 1.

Sets the exponent of the attenuation function, which is applied between the inner and outer radius values.

light1:
    type: point
    radius: [300,700]
    attenuation: 0.2

Spotlight properties

direction

This is the same as the directional light's direction property.

position

This is the same as the point light's position property.

origin

This is the same as the point light's origin property.

radius

This is the same as the point light's radius property.

attenuation

This is the same as the point light's attenuation property.

angle

Optional number, in degrees. Defaults to 20.

Sets the width of the spotlight's beam.

light1:
    type: spotlight
    direction: [0, 1, -.5]
    position: [0, 0, 300]
    origin: ground
    radius: 700
    angle: 45

exponent

Optional number. Defaults to 0.2.

This parameter sets the exponent of the spotlight's fallof, from the center of the beam to the edges. Higher values will give a sharper spotlight.

light1:
    type: spotlight
    direction: [0, 1, -.5]
    position: [0, 0, 300]
    origin: ground
    diffuse: white
    ambient: .3
    radius: 700
    attenuation: 0.2
    angle: 45
    exponent: 10.