Wrld.Heatmap

Extends: L.Layer

A class for drawing heatmap overlays on a map, displaying the density of geographical points over an area.

The heatmap is generated by drawing a blurred circle at each of the data points supplied. The radius of each circle can be controlled, allowing the heatmap to visualize spatial trends in the point data at different granularities. A larger radius will tend to cause circles to overlap with nearby neighbors allowing overall trends to be seen, whereas a smaller radius will allow localized detail to be visible.

Basic Usage

var heatmap = Wrld.heatmap(
  [
    [37.78, -122.40, 2.0], // lat, lng, weight
    [37.77, -122.41, 5.0],
  ], {
    densityStops: [{stop:0.0, radius:30.0}]
  }
).addTo(map);

Examples

• Add a heatmap to an outdoor map.
• Add a heatmap to an indoor map.

Creation

Options

Point Data

Each point in the input pointData array can be provided as an array of form:

[<Number> latitude_degrees, <Number> longitude_degrees, <Number> weight?]

The optional third element allows a weighting value to be supplied. A weight of N is equivalent to placing N points all at the same coordinate, each with a weight of 1. The default weight is 1.0.

Alternatively, pointData can be loaded from an array of objects with named properties for the coordinate and optional weight. The property names are specified by dataCoordProperty and dataWeightProperty. The coordinate can be any of the forms accepted for Wrld.LatLng creation.

For example:

[
  { latLng: {lat: 37.78, lng: -122.40}, weight: 2.0 },
  { latLng: {lat: 37.77, lng: -122.41}, weight: 5.0 },
  ...
]

Density Stops

An intensity image is created by drawing a blurred circle at each input data point. The densityStops option determines the radius and intensity of each circle drawn, and so in turn controls the visual density of the heatmap.

By specifying multiple density stops, multiple intensity images are created, one for each array element.

The densityBlend option controls which of these density images is displayed, by linearly interpolating between the two density stops with the closest stop parameter.

The densityStops option can be supplied as an array of objects, each with the following properties:

Alternatively, densityStops can be supplied as an array of Number arrays, of form:

[
  [stop, radius, gain?],
  ...
]

Color Gradient

The colorGradient option allows heatmap intensity to be visualized with different colors, helping to emphasize the information that you want to convey about your point data.

The color gradient defines a continuous color ramp to be applied to the intensity image pixels, from minimum intensity to maximum intensity.

The input domain is 0.0 (corresponding to a heatmap intensity of weightMin) to 1.0 (corresponding to a heatmap intensity of weightMax).

The colorGradient option is supplied as an array of objects of form:

[
  {stop: <Number>, color: <Color>},
  ...
]

<Color> can be in any of the following forms:

The Color Brewer website is a useful reference when making color gradient design choices.

Occluded Map Feature Styling

When displaying a heatmap on an outdoor map, 3d map features such as tall buildings can obscure areas of the ground, particularly at oblique (non-overhead) camera viewpoints. To aid visual understanding of the heatmap when viewed in these circumstances, an optional styling is applied to areas of the heatmap that are obscured by other map features, akin to a kind of x-ray effect.

This styling can be defined with the occludedMapFeatures, occludedAlpha, occludedSaturation and occludedBrightness options.

Setting occludedMapFeatures to an empty array disables the styling.

Setting occludedAlpha to 0.0 will cause the specified map features to fully occlude areas of the heatmap.

Polygon Points

The polygonPoints option allows a clipping polygon for the heatmap to be specified. These points are supplied as an array of clockwise ordered vertices, each in any of the forms accepted for Wrld.LatLng creation.

For example:

[
    [37.786617, -122.404654],
    [37.797843, -122.407057],
    [37.798962, -122.398260],
    [37.794299, -122.395234]
]

Additionally, for complex polygons with holes, vertices can be supplied as an array of arrays. The first inner array specifies the exterior (outer) ring of vertices, with subsequent inner arrays specifying interior (hole) rings.

For example:

[
  [[37.786617, -122.404654], //outer ring
  [37.797843, -122.407057],
  [37.798962, -122.398260],
  [37.794299, -122.395234]],

  [[37.795168, -122.402665], //hole
  [37.792300, -122.403781],
  [37.792656, -122.400420]],

  [[37.790979, -122.403028], //another hole
  [37.790404, -122.401272],
  [37.788705, -122.402579],
  [37.789706, -122.403516]]
]

Performance

Internally, the class generates graphical resources for the intensity images used to draw the heatmap, which can be computationally intensive. The algorithmic performance time, for densityStops with N entries and M input data points, grows asymptotically no faster than N * resolutionPixels^2 + M.

These resources are regenerated whenever the point data is changed, via setData(). In addition, changing the value of some options causes regeneration, as listed below.

• densityStops
• intensityBias
• weightMin
• weightMax
• resolutionPixels
• intensityBias
• polygonPoints
• textureBorderPercent
• useApproximation

Options not in the above list are suitable for changing at interactive rates, for example via UI slider controls.

If these performance characteristics are constraining your application then please get in touch, we’d love to hear from you! Contact us via support, or by opening a new issue.

Methods

Point Data methods

Options getter methods

Convenience methods for getting options on this heatmap. See Options for further details.

Options setter methods

Methods for setting options on this heatmap. See Options for further details.

Methods inherited from L.Layer

HeatmapOcclusionMapFeature

Represents a category of visual feature on an outdoor map, used when styling how heatmaps are drawn when occluded by a map feature.