Scene-file.md

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.

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

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

See Styles Overview and layers.

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

See Cameras Overview and cameras.

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

See Lights Overview and lights.

####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 very simple scene file:

sources:
    osm:
        type: GeoJSON
        url:  http://vector.mapzen.com/osm/all/{z}/{x}/{y}.json

layers:
    earth:
        data: { source: osm }
        style: { order: 0, color: green }
    water:
        data: { source: osm }
        style: { order: 1, color: blue }

In this example, all three elements are included – this will produce a (very simple) map!

Examples

For more examples of scene files, check out our demos – ours are usually named scene.yaml.

For even more amazing examples, check out the Tangram Sandbox!