Helpers

src/helpers/vectorlayerhelpers.ts

Example

  maptilersdk.helpers.addPolyline(map, { 
    // dataset UUID, a URL (relative or absolute) 
    data: "some-trace.geojson",
  });

  import { helpers } from "@maptiler/sdk";

  helpers.addPolyline(map, { 
    // dataset UUID, a URL (relative or absolute) 
    data: "some-trace.geojson",
  });

Vector Layer Helpers

Vector Layer Helpers:

• Polyline Layer Helper
• Polygon Layer Helper
• Point Layer Helper
• Heatmap Layer Helper

Shared logic

Helpers come with a lot of built-in defaults and some fail-proof logic that makes creating vector layers much easier! As a result, a dataset can be displayed in one call, creating both the datasource and the layer(s) in one go!

Depending on the type of feature to add (point, polyline, polygon or heatmap), a different helper function needs to be used, but datasource could contain mixed types of feature and the helper will only display a specific type. Example: we have a geoJSON file that contains both polygons and point and we use it as the data property on the helpers.addPoint(map, {options}), this will only add the points.

In addition to easy styling, helper's datasource can be:

• a URL to a geoJSON file or its string content
• a URL to a GPX or KML file (only for the polyline helper) or its string content
• a UUID of a MapTiler Cloud dataset

Multiple Layers

The key design principle of these vector layers helpers is it's easy to make what you want. Helpers can create multiple layers to represent the symbolization of a layer, if necessary.

Example

To create a road with an outline with the Polyline Layer Helper, you just say if you want an outline and specify its size (or even a zoom dependant size) and everything is handled for you. As a result, the helpers.addPolyline method will return an object with multiple IDs: ID of the top/main layer, ID of the outline layer (could be null) and the ID of the data source. This makes further layer and source manipulation possible.

Without the helpers to create a road with an outline, one must draw two layers: a wider base layer and a narrower top layer, fueled by the same polyline data. This requires ordering the layers properly and computing not the width of the outline, but rather the width of the polyline underneath so that it outgrows the top road layer of the desired number of pixels.

CommonShapeLayerOptions

The vector layer helper also share some I/O logic: each of them can take many options but a subset of them is common across all the helpers:

Polyline Layer Helper

The polyline helper makes it easy to create vector layers that contain polylines. Whenever it's possible and it makes sense, we use the same terminology across the different helpers.

Methods

The method helpers.addPolyline is not only compatible with the traditionnal GeoJSON source but also with GPX and KML files and the data option can be a MapTiler Cloud dataset UUID and will be resolved automatically.

Minimal usage, with the default line width and a random color (withing a selected list)

  import { helpers } from "@maptiler/sdk";

  helpers.addPolyline(map, { 
    // dataset UUID, a URL (relative or absolute) 
    data: "some-trace.geojson",
  });

PolylineLayerOptions

Extends CommonShapeLayerOptions

Examples

Check out the full list of examples

We can add many options, such a a specific color, a custom width or a dash pattern, this time sourcing the data from MapTiler Cloud, using the UUID of a dataset:

  import { helpers } from "@maptiler/sdk";

  helpers.addPolyline(map, { 
    data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
    lineColor: "#FF6666",
    lineWidth: 4,
    lineDashArray: "____ _ ",
    lineCap: "butt",
  });

As you can see, we've come up with a fun and easy way to create dash arrays, just use underscores and white spaces and this pattern will repeat!

Adding an outline is also pretty straightforward:

  import { helpers } from "@maptiler/sdk";

  helpers.addPolyline(map, { 
    data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
    lineColor: "#880000",
    outline: true,
  });

Endless possibilities, what about a glowing wire?

  import { helpers } from "@maptiler/sdk";

  helpers.addPolyline(map, { 
    data: "74003ba7-215a-4b7e-8e26-5bbe3aa70b05",
    lineColor: "#fff",
    lineWidth: 1,
    outline: true,
    outlineColor: "#ca57ff",
    outlineWidth: 2,
    outlineWidth: 10,
    outlineBlur: 10,
    outlineOpacity: 0.5,
  });

View more Polyline Layer Helper examples

Polygon Layer Helper

The polygon helper makes it easy to create vector layers that contain polygons, whether they are multipolygons, holedpolygons or just simple polygons. Whenever it's possible and it makes sense, we use the same terminology across the different helpers.

Methods

Minimal usage, with a half-transparent and a random color (withing a selected list) polygon of Switzerland, from a local file:

  import { helpers } from "@maptiler/sdk";

  helpers.addPolygon(map, {
    data: "switzerland.geojson",
    fillOpacity: 0.5,
  });

PolygonLayerOptions

Extends CommonShapeLayerOptions

Examples

Check out the full list of examples

We can add many options, such a a specific color, a custom width or a pattern, this time sourcing the data from MapTiler Cloud, using the UUID of a dataset:

  import { helpers } from "@maptiler/sdk";

  helpers.addPolygon(map, { 
    data: "aa203ccf-25ee-4447-bef3-55f90916897a",
    pattern: "cheese512.png",
    outline: true,
    outlineWidth: 3,
    outlineColor: "white",
    outlineDashArray: "_ ",
    fillOpacity: 0.7,
  });

View more Polygon Layer Helper examples

Point Layer Helper

A point visualisation may appear like the simplest of all, but we noticed this is where people get the most creative: cluster, data-drive variable radius, but also scaled with zoom, with or without labels, data-driven colors, etc. Our helper supports all of these and will fill-in with built-in default for what's missing. Whenever it's possible and it makes sense, we use the same terminology across the different helpers.

Methods

Here is the simplest example, with a dataset loaded from a local file (if no color is specified, a random color is used and the default radius is ramped over the zoom level):

  import { helpers } from "@maptiler/sdk";

  helpers.addPoint(map, {
    data: "public-schools.geojson",
  });

PointLayerOptions

Extends CommonShapeLayerOptions

Examples

Check out the full list of examples

Here is the same dataset, but with point clustering enabled:

  import { helpers } from "@maptiler/sdk";

  helpers.addPoint(map, {
    data: "public-schools.geojson",
    cluster: true,
  });

On the other hand, if clusters are enabled, the default color is fueled by the color ramp TURBO scaled from 10 to 10000 non-linearly resampled with the method "ease-out-square". The size also varies from minPointradius (default: 10) to maxPointRadius (default: 50):

With the point helper, it's also possible to adapt the color and theradius based on a property. In the following example, we display a point for each public school, with the scaling factor being the number of students:

  import { helpers } from "@maptiler/sdk";

  helpers.addPoint(map, {
    data: "public-schools.geojson",
    property: "students",
    pointColor: ColorRampCollection.PORTLAND.scale(200, 2000).resample("ease-out-sqrt"),
    pointOpacity: 0.8,
    minPointRadius: 6,
    maxPointRadius: 30,
    showLabel: true,
    zoomCompensation: false,
  })

Here, the PORTLAND color ramp is going to be used so that schools with 200 students or less will have the colors at the very begining of the color ramp and schools with 2000 or more will have the color defined at the very end. Schools in between will be attributed a colors in a non-linear fashion, following the "ease-out-sqrt" method (read Color Ramps section for more info).

View more Point Layer Helper examples

Heatmap Layer Helper

The heatmap layer is a great alternative for visualizing a collection of sparse data, but they can be challenging to use, especially when one has to come up with their own color ramp from scratch. The helper makes this much easier! Whenever it's possible and it makes sense, we use the same terminology across the different helpers.

Methods

Here is a minimalist example, using the default built-in TURBO color ramp:

  import { helpers } from "@maptiler/sdk";

  helpers.addHeatmap(map, {
    data: "public-schools.geojson",
  });

HeatmapLayerOptions

Examples

Check out the full list of examples

Some visualisations are created with a fixed geographic extent or zoom level in mind, whether it's a survey at the scale of a single neigbohood, or statitics at country scale. In this case, we want to tailor the color, radius, weight and intensity of the heatmap blobs exactely for this precise settings. In the following example, we disable the zoom compensation to make sure radii and intensity is never zoom-dependant:

  import { helpers } from "@maptiler/sdk";

  helpers.addHeatmap(map, {
    data: "public-schools.geojson",
    property: "students",
    // radius: how wide are the blobs
    radius: [
      {propertyValue: 100, value: 15},
      {propertyValue: 800, value: 50},
    ],
    // weight: how intense are the blob, as fueled by a property
    weight: [
      {propertyValue: 100, value: 0.1},
      {propertyValue: 800, value: 1},
    ],
    // A custom color ramp, must be used with its default interval of [0, 1]
    colorRamp: ColorRampCollection.MAGMA,
    zoomCompensation: false,
    opacity: 0.6,
    // a global factor applied to all the blobs, regardless of the property or zoom
    intensity: 1.2,
  });

Turning off zoom compensation allows for more accurate adjustments to the visualization at a specific zoom level, but it may not adapt as smoothly when zooming in or out.

View more Heatmap Layer Helper examples

Types and Interfaces

ZoomStringValues

  Array<{
    zoom: number, // Zoom level
    value: string // Value for the given zoom level
  }>

ZoomNumberValues

  Array<{
    zoom: number, // Zoom level
    value: number // Value for the given zoom level
  }>

PropertyValues

  Array<{
    propertyValue: number, // Value of the property (input)
    value: number // Value to associate it with (output)
  }>