Heatmap

Package: com.eegeo.mapapi.heatmaps

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

Type argument Description
List<WeightedLatLngAlt> weightedPoints The input data points.
double weightMin The intensity corresponding to the lowest color gradient value.
double weightMax The intensity corresponding to the heighest color gradient value.

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.

Type argument Description
float heatmapDensityStops An array of stop function input value in the range [0..1].
double heatmapRadiiMeters An array with an element for each density stop, providing the radius of the circledrawn for each point, in meters.
double heatmapGains An array with an element for each density stop, providing an intensity multiplier. This can be useful to adjust the appearance of the heatmap when multiple density stops are used.

void setDensityBlend(float densityBlend)

Sets the interpolation parameter between density stops.

Type argument Description
float densityBlend The density stop interpolation parameter, clamped to the range [0..1].

void setInterpolateDensityByZoom(boolean interpolateDensityByZoom)

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

Type argument Description
boolean interpolateDensityByZoom The option value.

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.

Type argument Description
double zoomMin The camera zoom level at which the highest density stop is displayed (with stop of 1.0)
double zoomMax The camera zoom level at which the lowest density stop is displayed (with stop of 0.0)

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

Type argument Description
float gradientStops Stop function input values in the range [0..1].
int gradientColors The color value for each stop, as 32-bit ARGB color.

void setOpacity(float opacity)

Sets the overall opacity of the heatmap.

Type argument Description
float opacity The opacity, clamped to the range [0..1].

void setResolutionPixels(int resolutionPixels)

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

Type argument Description
int resolutionPixels The intensity image size in pixels, clamped to the range [HeatmapOptions.RESOLUTION_PIXELS_MIN..HeatmapOptions.RESOLUTION_PIXELS_MAX]

void setIntensityBias(float intensityBias)

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

Type argument Description
float intensityBias The value, clamped to the range [0..1].

void setIntensityScale(float intensityScale)

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

Type argument Description
float intensityScale The intensity multiplier value.

void setIndoorMapId(String indoorMapId)

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

Type argument Description
String indoorMapId The indoor map id, or emptry string for an outdoor map.

void setIndoorFloorId(int indoorFloorId)

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

Type argument Description
int indoorFloorId The indoor map floor id.

void setElevation(double elevation)

Sets the elevation of this heatmap.

Type argument Description
double elevation A height in meters. Interpretation depends on the current HeatmapOptions.MarkerElevationMode.

void setElevationMode(ElevationMode elevationMode)

Sets the elevation mode for this heatmap.

Type argument Description
ElevationMode elevationMode The mode specifying how to interpret the Elevation property.

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.

Type argument Description
HeatmapOcclusionMapFeature occludedMapFeatures The array of occluded map features.

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

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

Type argument Description
float alpha The opacity, clamped to the range [0..1].
float saturation The color saturation, clamped to the range [0..1].
float brightness The color brightness, clamped to the range [0..1].

void setOccludedStyleAlpha(float alpha)

Sets the occluded style alpha property.

Type argument Description
float alpha The opacity, clamped to the range [0..1].

void setOccludedStyleSaturation(float saturation)

Sets the occluded style saturation property.

Type argument Description
float saturation The color saturation, clamped to the range [0..1].

void setOccludedStyleBrightness(float brightness)

Sets the occluded style brightness property.

Type argument Description
float brightness The color brightness, clamped to the range [0..1].

void setUseApproximation(boolean useApproximation)

Sets the useApproximation option. See HeatmapOptions.useApproximation()

Type argument Description
boolean useApproximation The option value.
v0.0.1467
Overview Introduction
Picking PickResult
Widgets (Optional) BlueSphere
Tag Service (Optional) TagService OnTagsLoadCompletedListener
RouteView Widget (Optional) RouteView RouteViewOptions