The scene file is a YAML document which organizes all of the elements Tangram uses to draw a map. YAML is a data format similar in many ways to JSON, but it has some unique features which we thought made it more friendly and easy to use for our purposes. (See the YAML entry for more about those features.)

Top-level Elements

There are a variety of top-level elements allowed in a scene file. Each defines the beginning of a block named for the element.

cameras

Optional element. The cameras block allows modifications to the view of the map.

See Cameras Overview and cameras.

layers

Required element. The layers block divides the data into layers and assigns styling parameters.

See Styles Overview and layers.

global

Optional element. The global block allows the addition of custom named parameters which can be substituted for values elsewhere in the scene file.

See global.

import

Optional element. The import block allows other .yaml files, containing any combination of Tangram scene blocks, specified from the top-level blocks outward, up to entire scene files, to be imported into the current scene, through a simple text-based merge.

See import.

lights

Optional element. The lights block allows control of the lighting of the map.

See Lights Overview and lights.

scene

Optional element. The scene block sets various scene-wide parameters.

See scene.

sources

Required element. The sources block identifies datasources.

See sources.

styles

Optional element. The styles block defines rendering styles, which are composed of materials and shaders.

See Styles Overview and styles.

textures

Optional element. The textures block allows for advanced configuration of textures within materials.

See Materials Overview and textures.

The basics

To create a map, the scene file requires only:

• a data source
• data interpretation rules (filters)
• styling rules

Here's a simple scene file:

sources:
    nextzen:
        type: TopoJSON
        url: https://tile.nextzen.org/tilezen/vector/v1/256/all/{z}/{x}/{y}.topojson

layers:
    earth:
        data: { source: nextzen }
        draw:
            polygons:
                order: 0
                color: darkgreen
    water:
        data: { source: nextzen }
        draw:
            polygons:
                order: 1
                color: lightblue

    roads:
        data: { source: nextzen }
        draw:
            lines:
                order: 2
                color: white
                width: 1.5px

In this example, all three elements are included – this will produce a map.