layers.md

This is the technical documentation for the "layers" block in Tangram's scene file. For a conceptual overview of the way Tangram applies styles to data, see the Filters Overview and the Styles Overview.

layers

The layers element is a required top-level element in the scene file. It has only one kind of sub-element: a layer name, which defines individual layers with a layer filter.

layers:
    earth:
        ...

layer name

Required string. Can be anything. No default.

layers:
    landuse:
        ...

Note: If a layer filter is not specified in a data parameter, Tangram will attempt to use the layer name as the filter. See Layer Name Shortcut.

layer parameters

data

Required parameter. Defines the beginning of a data block. Usable by top-level layers only. No default.

layers:
    landuse:
        data: { source: osm }

draw

Required parameter. Defines the beginning of a draw block. For draw parameters, see the draw entry.

layers:
    landuse:
        data: { source: osm }
        draw:
            ...

enabled

Optional Boolean. Allows layer to be turned off and on. Default is true.

layers:
    landuse:
        data: { source: osm }
        enabled: false

Unlike the draw-level visible parameter, once set, the enabled parameter cannot be overridden by any descendant layers. This is useful for culling large portions of the layer tree, e.g. for layer-toggle controls and/or overlays.

[This parameter was renamed from visible to avoid confusion with the draw-level visible parameter. Layer-level visible parameters are be supported through v0.12, but are deprecated in later releases.]

exclusive

Optional boolean. Ensures that no other sublayers at the same level will match the same features contained in the current sublayer. No default.

layers:
  layerA:
    filter: { kind: building }
    exclusive: true
  layerB:
    filter: { name: "tower" } # no features of "kind: building" will match here.

filter

Optional object or function. No default.

A filter element may be included once in any layer or sublayer. Only features matching the filter will be included in that layer (and its sublayers). For more on the filtering system, see Filters Overview.

layers:
    roads:
        data: { source: osm }
        filter: { kind: highway }

priority

Optional integer. Controls the order in which sub-layers at the same level are matched, and which one "wins" when multiple matching layers are merged.

When used with exclusive, if/else filter patterns can be expressed:

layers:
    layerA:             # if matches layerA...
        filter: ...
        priority: 1
        exclusive: true
        draw: ...
    layerB:             # else if matches layerB...
        filter: ...
        priority: 2
        exclusive: true
        draw: ...

sublayer name

Optional string. Can be anything except the other sublayer parameters: "draw", "filter", and "properties". No default.

Defines a sublayer. Sublayers can have all layer parameters except data, and can be nested.

All parameters not explicitly defined in a sublayer will be inherited from the parent layer, including draw, properties, and filter definitions. Note that filter objects in different sublayers may match simultaneously – see the Filters Overview.

layers:
    landuse:
        data: { source: osm }
        filter: ...
        draw: ...
        sublayer:
            filter: ...
            draw: ...
        sublayer2:
            filter: ...
            draw: ...
            subsublayer:
                filter: ...
                draw: ...

data parameters

all_layers

Optional boolean. Matches all layers in the data source. Useful for source introspection, without knowing or needing to specify all the layers in the data source by name.

data:
    source: newsource
    all_layers: true

layer

Optional string or [strings], naming a top-level named object in the source datalayer. In GeoJSON, this is a FeatureCollection. If a layer is not specified, the layer name will be used.

layers:
	buildings:
		data:
		    source: osm
		    layer: buildings

Many of our examples use flow syntax for data blocks:

layers:
	buildings:
		data: {source: osm, layer: buildings}

The specified "buildings" layer will match this named object in the "osm" datasource:

{"buildings":
    {"type":"FeatureCollection","features":[
        {"geometry":"..."}
    ]}
}

Because the layer name "buildings" is the same as the name of the desired GeoJSON object, the data object's layer parameter can be omitted; when no layer is specified, Tangram will attempt to use the layer name as the data layer. Most of our examples use this layer name shortcut.

layer:
    buildings:
        data: { source: osm }

When an array of layer names may is used as the value of the layer parameter, the corresponding data layers will be combined client-side. This allows easy styling of multiple layers at once:

layer:
    labels:
        data: { source: osm, layer: [buildings, pois] }
        filter: { name: true }
        draw:
            text:
                ...

The above example combines the "buildings" and "pois" layers into a new layer called "labels", for drawing with the text draw style.

source

Required string, naming one of the sources defined in the sources block.

data:
    source: osm

draw parameters

See the draw entry.