Skip to content

Latest commit

 

History

History
191 lines (147 loc) · 6.64 KB

sources.md

File metadata and controls

191 lines (147 loc) · 6.64 KB

This is the technical documentation for Tangram's sources block. For a conceptual overview of the way Tangram works with data sources, see the Filters Overview.

sources

The sources element is a required top-level element in a Tangram scene file. It declares the beginning of a sources block. It takes only one kind of parameter: the source name. Any number of source names can be declared.

source names

Required string, can be anything. No default.

Specifies the beginning of a source block.

The source below is named osm:

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

type

Required string. Sets the type of the datasource. No default.

Three options are currently supported:

  • TopoJSON
  • GeoJSON
  • MVT (Mapbox Vector Tiles)

As of v0.2, Tangram supports either tiled or untiled datasources.

url

Required string. Specifies the source's URL. No default.

URLs should be "schemeless," meaning without the "http:" at the beginning – this ensures that they will be loaded correctly under both http and https.

sources:
    osm:
        type: MVT
        url:  //vector.mapzen.com/osm/all/{z}/{x}/{y}.mvt

The URL to a tiled datasource will include special tokens ("{x}", "{z}", etc.) which will be automatically replaced with the appropriate position and zoom coordinates to fetch the correct tile at a given point. Various tilesources may have differing URL schemes.

sources:
    local:
        type: GeoJSON
        url:  //localhost:8000/tiles/{x}-{y}-{z}.json

An untiled datasource will have a simple URL to a single file:

sources:
    overlay:
        type: GeoJSON
        url:  overlay.json

Relative URLs are relative to the scene file's location. In the above example, "overlay.json" should be in the same directory as the scene file.

layers

Depending on the datasource, you may be able to request specific layers from the tiles by modifying the url:

# all layers
http://vector.mapzen.com/osm/all/{z}/{x}/{y}.json

# building layer only
http://vector.mapzen.com/osm/buildings/{z}/{x}/{y}.json
curly braces

When tiles are requested, Tangram will parse the datasource url and interpret items in curly braces according to the convention used by Leaflet and others, replacing e.g. {z} with the appropriate zoom level.

access tokens

The url may require an access token:

mapbox:
    type: MVT
    url: http://{s:[a,b,c,d]}.tiles.mapbox.com/v4/mapbox.mapbox-streets-v6-dev/{z}/{x}/{y}.vector.pbf?access_token=pk.eyJ1IjoiYmNhbXBlciIsImJiOiJWUmh3anY0In0.1fgSTNWpQV8-5sBjGbBzGg

max_zoom

Optional integer. No default.

Sets the highest zoom level which will be requested from the datasource. At higher zoom levels, the data from this zoom level will continue to be displayed.

sources:
    local:
        type: GeoJson
        url: localhost:8000//tiles/{x}-{y}-{z}.json
        max-zoom: 15

####enforce_winding Optional boolean. Default for tiled data sources is false; default for non-tiled data sources is true.

Allows the default to be overridden, for cases where a tiled data source has inconsistent winding order, or for non-tiled sources which are known to be consistent (this can save a small amount of computation).

If a data source has inconsistent winding order, it will manifest as missing vertical surfaces on buildings or other extruded elements.

sources:
   osm:
        type: GeoJSON
        url:  http://vector.someothertileservice.com/osm/all/{z}/{x}/{y}.json
        enforce_winding: true # reverse the default, because this source has winding problems
    schools:
        type: GeoJSON
        url: demos/data/school-districts-polygon.geojson
        enforce_winding: false # default for non-tiled sources is true

####scripts Optional [strings], specifying the URL of a JavaScript file.

These scripts will be loaded before the data is processed so that they are available to the transform function.

scripts: [ 'http://url.com/js/script.js', 'local_script.js']

####extra_data Optional YAML, defining custom data to be used in post-processing.

This data is made available to transform functions as the second parameter. extra_data could also be manipulated dynamically at run-time, via the scene.config variable (the serialized form of the scene file); for example, scene.config.sources.source_name.extra_data could be assigned an arbitrary JSON object, after which scene.rebuild() could be called to re-process the tile data.

extra_data:
    Broadway: Wide St.
    Wall St.: Tall St.
    Water St.: Wine St.

transform: |
    function (data, extra_data) {
        // manipulate data with extra_data
        var keys = Object.keys(extra_data);
        if (data.roads) {
            data.roads.features.forEach(function(feature) {
                if (extra_data[feature.properties.name]) {
                    feature.properties.name = extra_data[feature.properties.name]; // selectively rename features
                }
            });
        }
        return data;
    }

####transform Optional function.

This allows the data to be manipulated after it is loaded but before it is styled. Transform functions are useful for custom post-processing, either where you may not have direct control over the source data, or where you have a dynamic manipulation you would like to perform that incorporates other data separate from the source. The transform function is passed a data object, with a GeoJSON FeatureCollection assigned to each layer name, e.g. data.buildings would provide data from the buildings layer, with individual features accessible in data.buildings.features.

transform: |
    function (data) {
        // manipulate data
        if (data.roads) {
            data.roads.features.forEach(function(feature) {
                if (feature.properties.name) {
                    feature.properties.name += ' test!'; // add a string to each feature name
                }
            });
        }
        return data;
    }

examples

# Mapzen tiles in TopoJSON format
mapzen:
    type: TopoJSON
    url: http://vector.mapzen.com/osm/all/{z}/{x}/{y}.topojson

# Mapzen tiles in GeoJSON format
mapzen:
    type: GeoJSON
    url: http://vector.mapzen.com/osm/all/{z}/{x}/{y}.json

# Mapzen tiles in Mapbox Vector Tile format
mapzen:
    type: MVT
    url: http://vector.mapzen.com/osm/all/{z}/{x}/{y}.mvt

All of our demos were created using the Mapzen Vector Tiles service, which hosts tiled OpenStreetMap data.