Tangram Versions Save

Bug Fixes

• Scope line dash patterns by style, to remove (more) spurious warnings on rapid scene update/load. 4e1e5e5

Bug Fixes

• Fix copying of internal tile data, to ensure data is only copied from the same data source. Fixes issue where scenes with multiple data sources would intermittently drop/miss tiles when overzooming. 6babc9c

Bug Fixes

• Fix raster sampling at explicit pixel locations with sampleRasterAtPixel(), when using with mixed vector/raster tile sizes. 98c528c
  • Affects e.g. 256px vector tiles masking 512px raster tiles, and/or when using the zoom_offset parameter (which implicitly changes tile size).
• Fix shader uniforms that are arrays of vectors. 495a090
  • Example:

    shaders:
      uniforms:
        u_colors:
          - [0.5, 0.5, 0.5] # gray
          - [1, 0, 0] # red
          - [1, 0, 1] # purple
          - [0, 1, 1] # yellow
    

  • Note: prior fix in v0.16.0 was flawed.
• Use rollup commonjs plugin ignoreGlobal option to fix a minification error when bundling Tangram with Webpack. de04804
  • Prior to this fix, bundling with Webpack in production mode (with minification) required a modified Webpack config, with the noParse option applied to Tangram. This is no longer necessary, allowing for simpler builds without special config. Also see #699.
• scene.queryFeatures() will now return empty feature set if the scene isn't initialized (e.g. has not been loaded yet, is still in process of loading, etc.). 5d94514
• Fix view tile retention for overzoomed tiles (not a visible bug, but efficiency improvement to match intended internal tile caching). 7c19438

Improvements

• Adds a first property to the first view_complete event after each scene load (e.g. this value resets after a scene.load()). a30ca53
  • Example: scene.subscribe({ view_complete: ({ first }) => console.log('First view complete event?', first) });
• Copy existing tile source data for overzoomed tiles when possible; skips redundant network request and parsing (in practice these requests were almost always cached, but parsing computation was not). 50f587b

Bug Fixes

• Remove spurious warnings/errors when changing scene state with scene.updateConfig() or loading a new scene with scene.load().

New Features & Functionality Changes

• Geo-referenced / un-tiled raster data sources #688
  • Support for standalone, un-tiled raster images with a provided bounding box placing them in space. This functionality is commonly used for overlays of historical images, drone or other local aerial imagery, etc.
  • Basic syntax is similar to GeoJSON/TopoJSON sources, where the lack of an {x}/{y}/{z} tile pattern in the URL indicates the image should be treated as a standalone/un-tiled source:

    sources:
      chelan:
        type: Raster # can now indicate either tiled or un-tiled image source
        url: images/chelan.jpg # no tile XYZ pattern in URL indicates standalone image
        bounds: [-120.588, 47.467, -119.904, 48.033] # geo-extent of the image
    

  • This example shows a USGS historical map from the Chelan, WA area, overlaid on top of the Mapzen Walkabout base map:
  • Additional data source parameters exist for:
    • Compositing multiple images, each with their own bounds, together into a single data source:

      images:
        type: Raster
        composite:
          - { url: image1.png, bounds: [...] }
          - { url: image2.png, bounds: [...] }
          - { url: image3.png, bounds: [...] }
          ...
      

      • An example of a large collection of aerial drone images of crop fields, combined into a single raster source, where each field is a separate image:
    • An alpha value can be set either for the entire data source, or per image within the composite array (with the latter taking precedence):

      image:
        type: Raster
        alpha: 0.7 # apply 70% alpha to images
        composite:
          - { url: ..., bounds: ... }
          - { url: ..., bounds: ..., alpha: 1 } # override to apply full alpha to this image
      

      • Since the default opaque blend mode does not process alpha values (e.g. all pixels are drawn with full opacity), the raster data source alpha parameter only applies when rendering a raster source with non-opaque blend modes (such as translucent or overlay), and is ignored (with a warning) when using opaque.
    • An example with two composite images, with alpha applied to the larger image:
    • The max_display_density parameter will limit the internal resolution a which a raster source is re-sampled. Setting this to a low value like max_display_density: 1 will reduce texture memory usage on high-density displays (such as some phones), at the expense of some visual resolution.
• URL template support for high-resolution (e.g. @2x, @3x, etc.) raster tiles #695
  • Some raster tile sources support multiple resolutions, for better quality on high-density displays, following the @2x file naming convention for web and mobile assets. Similar to Leaflet, this is supported in Tangram raster data sources with the {r} URL template token: https://tiles.maps.com/{z}/{x}/{y}{r}.png.
  • The most common case is sources that support 1x and 2x tiles, and this is the default configuration. However, other resolutions are also possible. Multiple resolutions can be supported with the url_density_scales parameter. For example, Wikimedia maps has several resolutions, which can be rendered in Tangram with:

    sources:
      raster:
        type: Raster
        url: https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}{r}.png
        url_density_scales: [1, 1.3, 1.5, 2, 2.6, 3]
    

    • The default value for url_density_scales is [1, 2], meaning it will load either "plain" tile URLs like tile.png, or [email protected] tiles on displays with a display density >= 2.
• zoom_offset data source parameter for down-sampling data #685
  • In some circumstances, the default tiles for a source may be either too large (in file size) or too detailed (in feature density or coordinate precision) than needed for the current application. The new zoom_offset data source parameter allows the user to request lower zooms for each zoom level, reducing tile size and visual detail.
  • For example, a zoom_offset: 1 will down-sample the tile data (for both vector and raster sources) by one level, e.g. at zoom 12, zoom 11 tiles will be loaded instead.
  • Note: sources with tile_size: 512 already do this implicitly, loading one level lower than the typical Web Mercator "view" zoom level; any zoom_offset for these data source is applied in addition to the tile size adjustment, e.g. zoom_offset: 1 with tile_size: 512 will request tiles from two zoom levels earlier (but the 512px tiles will have been designed to not show any loss in visual detail from the first zoom subtraction).
  • An example showing Mapzen terrain normal tiles with zoom_offset: 1 (as compared to full detail), automatically generalizing the terrain while also lowering network bandwidth:
• Use top-level layer name as default repeat_group name #687
  • Prior behavior for the repeat_group parameter has been to default to the full, unique combination of all layer names that a given feature matches. While designed to allow for features with identical names but different purposes (e.g. a road and nearby park with the same name) to both properly display without repeat interference between them, in practice this behavior is too granular, causing many crowded, repeated labels for more common cases such as a road that changes from major to minor classification, while retaining its name. This sub-optimal behavior has been hidden by a bug that did not properly implement the original intent.
  • In re-evaluating the desired behavior, the default has been changed so that a feature's default repeat_group is that of its top-level parent in the scene's layers. For example, for typical scene structures this means that all roads will belong to the same repeat group, as would all landuse, all POIs, etc. (assuming top-level layers of roads, landuse, pois, and so forth). This better captures the original intent. In practice (combined with the prior long-standing bug), most scenes will not be affected by this change, though it may have a subtle impact on label placement and density.

Optimizations

• Optimize GL attribute packing to lower GPU memory usage #690
• Free textures from previous scene when loading new one 2dc91b5

Bug Fixes

• Fix scene.updateConfig() memory leak #697
• Fix label default repeat groups #687
• Fix use of JS functions for font size 0221e25
• Fix repeat culling on main thread for non-collision labels #686
• Namespace built-in shader defines (to avoid collisions with user-defined shaders) #693
• Ensure static GL attributes are enabled outside VAOs #689
• Skip centroids for polygons with zero area e5ea057
• Parse data source JS functions in worker after data source change check (fixes issue where transform/preprocess changes wouldn't be picked up on updateConfig()) b3dbe72

Internal

• Re-organization of project files #694
• Introduce async/await syntax, and use fast-async for transpiled support in ES5 build 9a6faf3
• Switch linter to eslint 8cd7022
• Add debug functions for checking texture memory usage 1adb292
• Upgrade Rollup and related build and test packages

Bug Fixes

• Disable GL pixel store params when creating texture from raw data 14823db abcab8b
  • Removes Firefox warning: "Error: WebGL warning: texImage2D: Alpha-premult and y-flip are deprecated for non-DOM-Element uploads."
• Fix un-tiled GeoJSON/TopoJSON source instantiation reference to other data sources 38614ee
  • Could potentially cause unexpected behavior for rasters attached to these sources
• Labels: make sure pending meshes for new styles (not previously in tile) are picked up on first collision pass b52c1dc

Internal

• Skip unnecessary $zoom filter type check (can't be a function) 5bd8747

Build Changes

• This release has a major change in Tangram's distribution files, adding a new ES module build which is now the preferred way of loading Tangram for current browsers (in practice, almost any browser in widespread use besides IE11). This build is loaded via a <script type="module"> tag, and because all browsers that support ES modules also support the most commonly used ES6+ features, includes minimal JS code transpiling. This leads to smaller bundle sizes and faster loading, with less code for the browser to download and parse.
  • The ES module build is published with new tangram.min.mjs and tangram.debug.mjs files, following the JS community and Node.js practice of using the .mjs file extension to distinguish ES modules from CommonJS modules. This minified/zipped build is 154k.
  • A fully transpiled ES5 build is still available, under the existing tangram.min.js and tangram.debug.js files. This minified/zipped build is 170k.
  • You can use this snippet to automatically load the best build for your browser, using the module/nomodule pattern:

  <!-- modern browsers load the optimized .mjs file, older browsers (IE11) load the transpiled .js file -->
  <script type="module" src="https://unpkg.com/tangram/dist/tangram.min.mjs"></script>
  <script nomodule src="https://unpkg.com/tangram/dist/tangram.min.js"></script>
  

  • See #677 (though note PR now has outdated file names and build tooling info).
• This release also switches the build process to use Rollup, which is the leading bundler for libraries (and used by React, Vue, D3, etc.). #681
• Related build tooling changes: upgrading to Babel 7 with preset-env and "auto-polyfilling" by usage, and Terser for minification.

New Features

• Data sources can specify custom HTTP request headers with the request_headers property #670
  • For example, including an OAuth bearer token:

  sources:
      tiles:
          type: TopoJSON
          url: ...
          request_headers:
              Authorization: Bearer XXXXXX
  

• Add $source, $layer, $geometry, and $visible properties to queryFeatures() #676
  • Allows for more advanced introspection of data source features; example, querying a breakdown of features by their data source layer, geometry type, and visibility status: scene.queryFeatures({ group_by: ['$layer', '$geometry', '$visible'] })
• Scene background color can be zoom-interpolated #682
  • Matches recently added functionality for Tangram ES https://github.com/tangrams/tangram-es/pull/1885
• Tile coordinates and bounds are now available in data source transform functions #675

Bug Fixes

• Fix "sticky" global property bug when updating scene.config via JS #683
• Fix race condition leading to intermittent missing labels, usually on simple scenes (often observed in Differ tests) #646 6972e57c13bde0269ce0373c9d0aa1e1555ce2d9...c29a7cbe213f5b78b5639ec75e1ec1d519b6be9d
• Fix shader uniforms that are arrays of vectors 1b2cec83f47488861ef2f7f65f0b735fe95abc04
  • Example:

  shaders:
    uniforms:
      u_colors:
        - [0.5, 0.5, 0.5] # gray
        - [1, 0, 0] # red
        - [1, 0, 1] # purple
  

Improvements (Optimizations & Internal)

• Cache user-defined JS functions, to improve scene load performance #684
  • On Mapzen/Nextzen styles, the reduction in number of functions compiled is anywhere from 40% (on Bubble Wrap) to almost 300% (on Walkabout)
• If scene animation flag is true, still skip continuous rendering if no animated styles are visible, to improve rendering performance 7c5c799
• Simplify GLSL uniform injection c1373c0
• Remove unused shader files 0072252
• Clarify log messages re: missing sprite definitions, and downgrade to debug level (this is a valid technique for scene authoring) fb3fa62

Improvements

• Improved memory usage:
  • Reduced footprint for labels on main thread ec5257e
  • By using separate mesh variants for interactive features in lines and polygons, removing selection attributes from the VBOs of non-interactive features 1dbf46e a1131df
  • With lazily instantiated feature selection resources, cleared on scene load 068aec9 dbbc172
• Improved performance:
  • Skip feature selection rendering pass when no interactive features are visible 068aec9

Bug Fixes

• Fix labels with a composite text_source (e.g. text_source: [name, kind] should use the feature's name property for the label if available, otherwise fallback to the kind property) #672 #673
• Fix labels when style has multiple label textures per tile (observed as corrupt labels, usually only seen in dense urban areas at high zoom, on retina/high-density displays), which also sometimes caused unnecessary intermediate resources to be allocated c58f5ee 03e6b33
• Line outlines should inherit interactive property from their inline 1eeadc0
• Fix handling of label repeat_group: 0 (should default to px units and act as 0px value) 5e5ccbb
• Fix edge case where line outlines would not inherit a 0 value for miter_limit from their inline c602640
• Fix edge case for label repeat_group with a name of 0 86e2688

Bug Fixes

• Fix issue with requesting feature selection info when rendering raster styles (which don't support feature selection). #665 7c51588

Bug Fixes

• Fix cases where points-based styles are rendered with more than one texture (set in draw groups), e.g. when multiple road shield textures are used with the same rendering style. 417e4b9cdcfa26b2d5b4a87da1866136d8233c92

Internal

• Migrated tests to CircleCI 2.0. a9fad2d65a20dc722ec7296e52993021357f67c0