Skip to content

Latest commit

 

History

History
225 lines (160 loc) · 4.94 KB

lights.md

File metadata and controls

225 lines (160 loc) · 4.94 KB

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

Light names

Required string. Can be anything except the [[reserved keywords|yaml#reserved-keywords]]. No default.

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

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

Required 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], [lat, long], or { lat: number, lng: number }. Vectors may be specified in meters m or pixels px, depending on the value of origin. [lat, long]s may be specified as lists or objects of the format { lat: number, lng: number}. No default value. Default unit for vectors are m.

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

Sets the reference point for the position parameter:

  • world: sets x and y in [lat, lng] 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 camera center, 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|lights#direction]] property.

position

This is the same as the point light's [[position|lights#position]] property.

origin

This is the same as the point light's [[origin|lights#origin]] property.

radius

This is the same as the point light's [[radius|lights#radius]] property.

attenuation

This is the same as the point light's [[attenuation|lights#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.