Heatmap

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.

Density Stops
An intensity image is created by drawing a blurred circle at each input data point. The heatmapDensityStops, heatmapRadii and heatmapGains properties determine the radius and intensity of each circle drawn, and so in turn control the visual density of the heatmap. 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. The heatmapGains supply an intensity multiplier for each density stop. This can be useful to adjust the appearance of the heatmap when multiple density stops are used.
By specifying multiple density stops, multiple intensity images are created, one for each stop.
The densityBlend option controls which of these density images is displayed, by linearly interpolating between the two density stops with the closest stop parameter.

Color Gradient
A color gradient 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).

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.

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 density stops 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 other properties causes regeneration, as listed below.

• setDensityStops()
• setIntensityBias()
• setWeightMin()
• setWeightMax()
• setResolutionPixels()
• setIntensityBias()
• setPolygonOptions()
• setUseApproximation()

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.

Public methods in this class must be called on the Android UI thread.

See Also: HeatmapOptions.

Methods

List<WeightedLatLngAlt> getWeightedPoints()

Returns: The current data points to be drawn by this heatmap.

float getHeatmapDensityStops()

Returns: The stop parameter array for the density stops.

double getHeatmapRadii()

Returns: The circle radius array for the density stops.

double getHeatmapGains()

Returns: The gains array for the density stops.

float getDensityBlend()

Returns: The heatmap density stop blend parameter.

boolean getInterpolateDensityByZoom()

Returns: The interpolateDensityByZoom option.

double getZoomMin()

Returns: The zoomMin property.

double getZoomMax()

Returns: The zoomMax property.

double getWeightMin()

Returns: The weightMin property.

double getWeightMax()

Returns: The weightMax property.

float getGradientStops()

Returns: The stop parameter array for the color gradient.

int getGradientColors()

Returns: The color array for the color gradient.

float getOpacity()

Returns: The heatmap opacity.

int getResolutionPixels()

Returns: The heatmap intensity image resolution in pixels.

float getIntensityBias()

Returns: The intensity bias parameter.

float getIntensityScale()

Returns: The intensity scale parameter.

String getIndoorMapId()

Gets the identifier of an indoor map on which this heatmap should be displayed, if any.

Returns: For a heatmap on an indoor map, the string identifier of the indoor map; otherwise an empty string.

int getIndoorFloorId()

Gets the identifier of an indoor map floor on which this heatmap should be displayed, if any.

Returns: The indoor map floor id.

double getElevation()

Returns the current elevation of the heatmap. The property is interpreted differently, depending on the ElevationMode property.

Returns: A height, in meters.

ElevationMode getElevationMode()

Returns the mode specifying how the Elevation property is interpreted.

Returns: An enumerated value indicating whether Elevation is specified as a height above terrain, or an absolute altitude above sea level.

HeatmapOcclusionMapFeature getOccludedMapFeatures()

Returns: 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.

float getOccludedStyleAlpha()

Returns: The opacity of occluded areas of the heatmap.

float getOccludedStyleSaturation()

Returns: The color saturation of occluded areas of the heatmap.

float getOccludedStyleBrightness()

Returns: The color brightness of occluded areas of the heatmap.

List<LatLng> getPolygonPoints()

Gets the outline points of the heatmap polygon.

Returns: The vertices of the exterior ring (outline) of this heatmap.

List<List> getPolygonHoles()

Gets the points that define holes for the heatmap polygon.

Returns: A list of lists - each inner list contains the vertices of an interior ring (hole) of this heatmap.

float getTextureBorderPercent()

Returns: The size of a gutter at the edges of the heatmap images, around the bounds of the data points./

boolean getUseApproximation()

Returns: The useApproximation option.

void setData(List<WeightedLatLngAlt> weightedPoints, double weightMin, double weightMax)

Sets the array of data points to draw for this heatmap. The WeightedLatLngAlt.intensity field is used as a weighting value. A weight of N is equivalent to placing N points all at the same coordinate, each with a weight of 1. The weightMin and weightMax parameters specify a domain mapping from heatmap intensity value [weightMin..weightMax] to color gradient stop function input [0..1].

void setDensityStops(float heatmapDensityStops, double heatmapRadiiMeters, double heatmapGains)

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.

void setDensityBlend(float densityBlend)

Sets the interpolation parameter between density stops.

void setInterpolateDensityByZoom(boolean interpolateDensityByZoom)

Sets the option to blend between density stops based on current map camera zoom level. If true, densityBlend is ignored.

void setZoomExtents(double zoomMin, double zoomMax)

Sets the extents over which heatmap density will change with map zoom, linearly interpolating between them. The values are ignored if interpolateDensityByZoom is false.

void setGradient(float gradientStops, int gradientColors)

Sets 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

void setOpacity(float opacity)

Sets the overall opacity of the heatmap.

void setResolutionPixels(int resolutionPixels)

Sets the intensity image dimensions. See HeatmapOptions.resolutionPixels().

void setIntensityBias(float intensityBias)

Sets the intensity bias parameter. See HeatmapOptions.intensityBias().

void setIntensityScale(float intensityScale)

Sets the intensity scale parameter. See HeatmapOptions.intensityScale().

void setIndoorMapId(String indoorMapId)

Sets the identifier of an indoor map on which this heatmap should be displayed, if any.

void setIndoorFloorId(int indoorFloorId)

Sets the identifier of an indoor map floor on which this heatmap should be displayed, if any.

void setElevation(double elevation)

Sets the elevation of this heatmap.

void setElevationMode(ElevationMode elevationMode)

Sets the elevation mode for this heatmap.

void setOccludedMapFeatures(HeatmapOcclusionMapFeature occludedMapFeatures)

Sets 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.

void setOccludedStyle(float alpha, float saturation, float brightness)

Set style parameters used for drawing areas of the heatmap occluded by map features.

void setOccludedStyleAlpha(float alpha)

Sets the occluded style alpha property.

void setOccludedStyleSaturation(float saturation)

Sets the occluded style saturation property.

void setOccludedStyleBrightness(float brightness)

Sets the occluded style brightness property.

void setUseApproximation(boolean useApproximation)

Sets the useApproximation option. See HeatmapOptions.useApproximation()