Tangram is an open-source 3D rendering engine specifically designed for drawing maps, using the OpenGL graphics API. It parses vector data in a variety of formats, and produces a 3D scene with geometry, labels, and icons all built and styled on the fly. It also accepts tiled raster inputs, with special facility for processing terrain data.

Tangram is implemented in two official flavors: Tangram JS for use in web browsers, and Tangram ES for native mapping on mobile devices.

Both libraries use a "scene file" to configure and modify the data sources, filters, and display options used when drawing the map. The scene file is written in YAML using a custom, Tangram-specific syntax.

Tangram JS

Tangram JS is a JavaScript library for use in web browsers. It uses WebGL to construct and draw vector and raster map data at high speeds. It provides an API through a scene.config object, which is essentially the scene file in JavaScript object form – this config object may be modified at run-time to change nearly any property of the scene.

Tangram ES

Tangram ES is a C++ library, with a rendering engine based on OpenGL ES, and designed for mobile and embedded systems. It currently targets five platforms: Android, iOS, Mac OS X, Ubuntu Linux, and Raspberry Pi.

Releases

Tangram JS versions are matched to Leaflet versions to ensure ongoing compatability (primarily relating to scrollwheel zoom behavior). In general, the latest version of Tangram is based on the latest version of Leaflet, but if you require a specific version of Leaflet or Tangram, refer to the below compatability table.

Tangram version	Leaflet version
0.7 and previous	0.7.7
0.8 and later	1.x

The latest release of Tangram JS may always be referenced at:

https://unpkg.com/tangram/dist/tangram.min.js

for the minified version, and

https://unpkg.com/tangram/dist/tangram.debug.js

for the debug version.

If you'd like to use a specific release of Tangram JS, you may specify its version number in its url:

<script src="https://unpkg.com/tangram@0.15.1/dist/tangram.min.js"></script>

See details of the latest Tangram JS release here.

Tangram ES releases are tagged according to their target platform.

See the latest Tangram ES releases here.

Note: the documentation always refers to the latest release of Tangram – reverse compatibility of scene file syntax is not guaranteed.

Leaflet

[Tangram JS only]

Tangram JS includes an interface to the popular Leaflet web-mapping library. In this way Tangram JS is technically a Leaflet "plugin," with Leaflet handling user interaction such as clicking, zooming, and panning, and Tangram providing the content of each tile.

Note: Tangram requires that the Leaflet map use the default "Web Mercator" Coordinate Reference System, also known as EPSG:3857. As this is the default, it is not necessary to specify it in the Leaflet instantiation, but here's what it would look like if you did:

var map = L.map('map', {
    crs: L.CRS.EPSG3857
});

Leaflet options

When Tangram's Leaflet layer is instantiated, various parameters may be passed to the layer inside the options object to control the layer's appearance and behavior.

var layer = Tangram.leafletLayer({
    scene: 'scene.yaml',
    attribution: 'attribution string'
});

This object may contain any of the standard Leaflet layer options, plus a number of Tangram-specific options, listed below.

introspection

When set to true, this parameter will load the scene with introspection enabled, making a call to scene.setIntrospection(true) unnecessary.

var layer = Tangram.leafletLayer({
    introspection: true
});

scene

The required scene parameter specifies the URL of the scene file to be loaded.

var layer = Tangram.leafletLayer({
    scene: 'scene.yaml'
});

preUpdate/postUpdate

The optional preUpdate and postUpdate parameters allow functions to be referenced or defined, to be called immediately before and/or after Tangram's frame update loop runs (up to 60 frames per second, depending on hardware and scene complexity). These functions are called each frame, continuously, regardless of whether the Tangram scene is animated (e.g. the map may not be visually changing in any way, but the update functions will still be called). They are passed a single argument, a flag indicating if Tangram will render (for preUpdate), or just did render (for postUpdate) new content.

var layer = Tangram.leafletLayer({
    preUpdate: myPreUpdateFunction,
    postUpdate: function(didRender) {
        console.log('postUpdate!');
        if (didRender) {
            console.log('new frame rendered!');
        }
    },
    ...
});

modifyScrollWheel

By default, Tangram modifies Leaflet's scrollwheel behavior, for better synchronization with its own render loop while zooming. If this interferes with your application, you can disable this behavior with the optional modifyScrollWheel option:

var layer = Tangram.leafletLayer({
    modifyScrollWheel: false,
    ...
});

modifyZoomBehavior

By default, Tangram modifies Leaflet's double-click and zoom behavior, to keep the Tangram layer in sync with marker/SVG layers. If this interferes with your application, you can disable this behavior with the optional modifyZoomBehavior option:

var layer = Tangram.leafletLayer({
    modifyZoomBehavior: false,
    ...
});

webGLContextOptions

Using this option, WebGL context options may be explicitly added or overridden.

var layer = Tangram.leafletLayer({
    scene: ...,
    webGLContextOptions: {
      preserveDrawingBuffer: true,
      antialias: false
    }
  });

Multiple Maps

Due to architectural limitations, there can be only one Tangram map per "browsing context". This means there can be only one embedded Tangram map on a web page, and one Tangram layer per Leaflet map, although Tangram may be composited with other kinds of Leaflet layers.

An iframe counts as a separate browsing context, so we make frequent use of the Tangram-frame repository for this purpose, by using Tangram-frame links as the "src" of iframes.

The Scene File

Tangram uses a "scene file" written in YAML to configure data sources, filters, and styling rules. Its structure and syntax is interchangable between Tangram JS and Tangram ES, with a very small number of exceptions as noted in the documentation with [JS only] or [ES only].

See Scene File.

Scene Bundling

More complex map styles can require a large number of assets, including multiple scene files, textures and sprite images, and so on. For ease of transport, a Tangram scene file and its assets may be bundled in a .zip file, which may then be named in place of the .yaml file when specifying a scene file.

For example, with Tangram JS:

    var map = L.map();

    var layer = Tangram.leafletLayer({
        scene: 'scene.zip'
    });

    layer.addTo(map);

Tangram will unpack the zip internally, expecting only a single .yaml file to be in the zip's root, which it will use as the scene file. Any other bundled .yaml files (eg basemaps or blocks included with the import block) must therefore be in subdirectories, and all paths in the .yaml file must be relative to this root scene file.

Getting Started

Check out our Tangram Setup Guides for more information about getting started with your Tangram installation.

Contributing

Questions? Suggestions? Typos? Bug fixes? We welcome contributions, either to the libraries or to the documentation itself. Learn more at the links below:

• Contributing to Tangram JS
• Tangram ES README