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


Creation

Factory Description
Wrld.heatmap(<Point Data> pointData, <Heatmap options> options?) Instantiates a heatmap object for a given array of geographical points. See Point Data for further details about how the point data contributes to the heatmap, and Options for available options.


Options

Options Type Default Description
densityStops <Density Stop>[] [
{ stop: 0.0, radius: 5.0, gain: 1.0 },
{ stop: 1.0, radius: 15.0, gain: 1.0 }
]
Sets one or more density stop for the heatmap. Each density stop determines how the point data should be drawn as a heatmap of specified density.
See Density Stops for further details.
densityBlend Number 0.0 Controls which of the densityStops heatmap images is displayed, by linearly interpolating between the two adjacent stops whose stop value is closest to densityBlend. The property is clamped to the range [0..1].
interpolateDensityByZoom Boolean false If true, blending between density stops is performed based on current map camera zoom level. In this case, densityBlend is ignored. Options zoomMin and zoomMax control the extents over which heatmap density will change with map zoom, linearly interpolating between them.
zoomMin Number 15.0 The camera zoom level at which the highest density stop is displayed (with stop of 1.0). Ignored if interpolateDensityByZoom is false.
zoomMax Number 18.0 The camera zoom level at which the lowest density stop is displayed (with stop of 0.0). Ignored if interpolateDensityByZoom is false.
weightMin Number 0.0 Defines a domain mapping from heatmap intensity value [weightMin..weightMax] to colorGradient stop function input [0..1].
weightMax Number 1.0 Defines a domain mapping from heatmap intensity value [weightMin..weightMax] to colorGradient stop function input [0..1].
colorGradient <Color Stop>[] [ {
stop: 0.0, color: "#ffffff00" }, { stop: 0.2, color: "#ffffb2ff" }, { stop: 0.4, color: "#fecc5cff" }, { stop: 0.6, color: "#fd8d3cff" }, { stop: 0.8, color: "#f03b20ff" }, { stop: 1.0, color: "#bd0026ff"
} ]
The color ramp applied to each pixel of the heatmap intensity image, from minimum intensity weightMin at stop: 0.0 to maximum intensity weightMax at stop: 1.0. See Color Gradient for further details.
opacity Number 1.0 The overall opacity of the heatmap. The property is clamped to the range [0..1].
resolutionPixels Number 512 Defines the maximum dimension, in pixels, of the intensity image calculated for each heatmap density stop. A higher value allows more detail to be visible in the heatmap, but requires more computational resources.
intensityBias Number 0.0 Determines the normative value of the data represented by the heatmap, corresponding to a point on the colorGradient function. This is useful when displaying weighted point data that diverges around some center value, for example temperatures above or below freezing point. In this case, intensityBias might be set to 0.5 to correspond with the mid-point of the colorGradient function. This would correspond to a normative temperature value at the mid-point between weightMin and weightMax. The property is clamped to the range [0..1].
intensityScale Number 1.0 An additional overall intensity multiplier. The scaling value is applied relative to the normative value determined by intensityBias.
indoorMapId String '' The identifier of the indoor map on which the heatmap will be drawn. If empty, the heatmap is drawn on the outdoor map.
indoorMapFloorId Number 0 The identifier of the indoor map floor on which the heatmap will be drawn. In the WRLD Indoor Map Format, this corresponds to the z_order field of the Level object.
elevation Number 0.0 The height of the heatmap above ground or sea level in meters.
elevationMode String heightAboveGround Indicates whether elevation is relative to ground level (heightAboveGround) or sea level (heightAboveSeaLevel).
occludedMapFeatures <Heatmap Occlusion Map Feature>[] ["buildings", "trees"] The map feature types that, if occluding areas of the heatmap, will cause those areas of the heatmap to be drawn with an alternate style. See Occluded Map Feature Styling for further details.
occludedAlpha Number 0.85 The opacity of occluded areas of the heatmap, clamped to the range [0..1]. See Occluded Map Feature Styling for further details.
occludedSaturation Number 0.7 The color saturation of occluded areas of the heatmap, clamped to the range [0..1], where 0.0 is fully desaturated (grayscale), and 1.0 has no effect. See Occluded Map Feature Styling for further details.
occludedBrightness Number 0.7 The color brightness of occluded areas of the heatmap, clamped to the range [0..1], where 0.0 is fully darkened (black), and 1.0 has no effect. See Occluded Map Feature Styling for further details.
polygonPoints <Polygon Points> [] Geographical points to define the vertices of a clipping polygon for the heatmap. If empty, the heatmap is drawn as a quadrilateral polygon, automatically sized to encompass all the point data coordinates.
dataCoordProperty String latLng The name of a property on each input data object to be interpreted as the point’s geographical coordinate.
dataWeightProperty String weight The name of a property on each input data object to be interpreted as the point’s weight.
textureBorderPercent Number 0.05 The size of a gutter at the edges of the heatmap images, around the bounds of the data points. Specified as a percentage of the image dimensions.
useApproximation Boolean true If false, uses a slightly more accurate but computationally costly method for calculating the heatmap.


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:

Property Type Description
stop Number A stop function input value in the range [0..1].
radius Number The radius of the circle drawn for each point, in meters. A larger radius generates a smoother heatmap, good for showing spatial trends rather than fine-grain detail. The circle has a blurred edge, with maximum intensity at its center, and falls gradually to zero intensity at approximately 3x radius.
gain? Number Optional intensity multiplier. The default value is 1.0. This can be useful to adjust the appearance of the heatmap when multiple density stops are used.


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:

Type Example Description
String #d20057 An Html hex color code, in the form #RRGGBB or #RRGGBBAA. Emmet-style abbreviations are also supported (#RGB and #RGBA).
Number[] [210, 0, 87] A Number array, in the form [<RED>, <GREEN>, <BLUE>] or [<RED>, <GREEN>, <BLUE>, <ALPHA>]. All components are in the range [0..255].
{ r: <RED>, g: <GREEN>, b: <BLUE>, a?: <ALPHA> } { r: 210, g: 0, b: 87 } An object with r, g, b and optional a properties, each with Number values in the range [0..255].


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

Method Returns Description
setData(<Point Data> pointData) this Sets geographical point data with optional weights on this heatmap.
getData() <Point Data> The array of point data currently set on this heatmap, in the form [{ <Wrld.LatLng> latLng: <latLng>, <Number> weight: <weight> }]

Options getter methods

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

Method Returns Description
getDensityStops() <Density Stop>[] Returns options.densityStops.
getDensityBlend() Number Returns options.densityBlend.
getInterpolateDensityByZoom() Boolean Returns options.interpolateDensityByZoom.
getZoomMin() Number Returns options.zoomMin.
getZoomMax() Number Returns options.zoomMax.
getWeightMin() Number Returns options.weightMin.
getWeightMax() Number Returns options.weightMax.
getColorGradient() <Color Stop>[] Returns options.getColorGradient.
getOpacity() Number Returns options.getOpacity.
getResolutionPixels() Number Returns options.resolutionPixels.
getIntensityBias() Number Returns options.getIntensityBias.
getIntensityScale() Number Returns options.getIntensityScale.
getIndoorMapId() String Returns options.indoorMapId.
getIndoorMapFloorId() Number Returns options.indoorMapFloorId.
getElevation() Number Returns options.elevation.
getElevationMode() String Returns options.elevationMode.
getOccludedMapFeatures() String[] Returns options.getOccludedMapFeatures.
getOccludedAlpha() Number Returns options.getOccludedAlpha.
getOccludedSaturation() Number Returns options.getOccludedSaturation.
getOccludedBrightness() Number Returns options.getOccludedBrightness.
getPolygonPoints() <Polygon Points> Returns options.polygonPoints.
getTextureBorderPercent() Number Returns options.textureBorderPercent.
getUseApproximation() Boolean Returns options.useApproximation.

Options setter methods

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

Method Returns Description
setOptions(<Object> options) this Merges the supplied properties into the options of this heatmap object.
setDensityStops(<Density Stop>[] densityStops) this Sets options.densityStops.
setDensityBlend(<Number> densityBlend) this Sets options.densityBlend.
setInterpolateDensityByZoom(<Boolean> interpolateDensityByZoom) this Sets options.interpolateDensityByZoom.
setZoomMin(<Number> zoomMin) this Sets options.zoomMin.
setZoomMax(<Number> zoomMax) this Sets options.zoomMax.
setWeightMin(<Number> weightMin) this Sets options.weightMin.
setWeightMax(<Number> weightMax) this Sets options.weightMax.
setColorGradient(<Color Stop>[] colorGradient) this Sets options.colorGradient.
setOpacity(<Number> opacity) this Sets options.opacity.
setResolution(<Number> resolutionPixels) this Sets options.resolutionPixels.
setIntensityBias(<Number> intensityBias) this Sets options.intensityBias.
setIntensityScale(<Number> intensityScale) this Sets options.intensityScale.
setIndoorMapWithFloorId(<String> indoorMapId, <Number> indoorMapFloorId) this Sets options.indoorMapId and options.indoorMapFloorId.
setElevation(<Number> elevation) this Sets options.elevation.
setElevationMode(<Number> mode) this Sets options.elevationMode.
setPolygonPoints(<Polygon Points> polygonPoints) this Sets options.polygonPoints.
setUseApproximation(<Boolean> useApproximation) this Sets options.useApproximation.

Methods inherited from L.Layer

Method Returns Description
addTo(<Wrld.Map> map) this Adds the heatmap to the given map.
remove() this Removes the heatmap from the map it is currently active on.


HeatmapOcclusionMapFeature

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

Property Description
GROUND Terrain geometry.
BUILDINGS Exterior building geometry.
TREES Trees and forest geometry.
TRANSPORT Road and rail geometry.
v1.1.0
Props Wrld.Prop
Themes Wrld.themes
Heatmaps Wrld.Heatmap
Events Event objects
Services (Optional) WrldPoiApi