Nokia Maps API Reference

Contents

Class nokia.maps.clustering.ClusterProvider

Class Summary

This class works on a set of data points (locations) and organizes them into clusters to optimize their display on the map.

new nokia.maps.clustering.ClusterProvider (display, [options])
Options This interface defines the configuration options for nokia.maps.clustering.ClusterProvider
Method Summary
add (dataPoint) This method adds a data point to the list of data points to be considered for clustering.
addAll (dataPoints, [callback]) This method adds a list of data points to the list of objects for clustering.
addObserver (key, callback, [context]) : nokia.maps.util.OObject This method registers an observer for the property named by the caller.
clean () This method removes clusters and noise points from display.
cluster () This method starts the clustering process.
destroy () This method cleans up all internal objects and prepares the given instance of this class to be destroyed.
get (key) : Variant This method retrieves the value of the property with the name provided by the caller.
getCopyrights (area, zoom) : Object[] To get copyright information for a specified geographical area and zoom level.
getDataLength () : Number This method retrieves a numeric value indicating the number of data points in the data set available to the given instance of the class.
getEps () : Number This method retrieves the current epsilon value, which represents the area within which data points are considered for clustering.
getMinPts () : Number This method retrieves a value indicating the smallest number of points within the epsilon radius that are required to form a cluster.
invalidate () This method invalidates the current results of clustering and sets the state to nokia.maps.clustering.ClusterProvider.STATE_INITIAL.
numberOfClusters () : Number This method retrieves the number of clusters in the data set available to the given instance of the class.
numberOfNoisePoints () : Number This method retrieves a numeric value indicating the number of noise points in the data set available to the given instance of this class.
remove (dataPoint) This method removes a data point from the list of objects to be considered for clustering.
remove (key) : nokia.maps.util.OObject This method removes the property with the name provided by the caller.
removeObserver (key, callback, context) : nokia.maps.util.OObject This method removes the observer for the property named by the caller.
set (nameOrObject, [value, [force]]) : nokia.maps.util.OObject This method sets property values, using the property names and values supplied by the caller.
setEps (epsilon) This method sets a new epsilon value (in pixels), which represents the area within which data points are considered for clustering.
setMinPts (minPts) This method sets a new value indicating the smallest number of points within the epsilon radius that are required to form a cluster.
setTheme (theme) This method sets the theme to use while rendering clusters on the map.
update () This method set the internal "updated at" time-stamp and publishes a message with topic "updated".
Field Summary
static string STATE_CLUSTERED This constant indicates a state which an instance of ClusterProvider enters when it has completed clustering and rendering of the markers on the map can begin (is about to begin).
static string STATE_INITIAL This constant identifies the initial state of an instance of this class after the instance has been created, or after invocation of nokia.maps.clustering.ClusterProvider#clean and nokia.maps.clustering.ClusterProvider#invalidate methods.
static string STATE_READY This constant indicates a state which an instance of ClusterProvider enters when it has determined clusters and noise points and their representation for display on the map.
static string STATE_STARTED This constant indicates a state which an instance of ClusterProvider enters when clustering has started.
String description This property holds a description of the provider to be used in the user interface, for example in tool tips.
Number id This property holds the id of the Provider instance.
String label This property represents a label for the provider to be displayed in the user interface.
Number max This property indicates the maximum zoom level.
Number min This property indicates the minimum zoom level.
Constructor Detail

This method creates new instance of ClusterProvider.

new nokia.maps.clustering.ClusterProvider(display, [options])
Parameters:
{nokia.maps.map.Display} display Display The object on which markers are to be drawn
{nokia.maps.clustering.ClusterProvider.Options} [options] An object specifying the configuration settings for the clustering provider instance
Method Detail
add (dataPoint)
This method adds a data point to the list of data points to be considered for clustering. Note that the method does not perform input validation to boost performance, therefore the caller must ensure that the object passed to the method contains the properties "latitude" and "longitude".
Parameters:
{nokia.maps.clustering.IClusterPoint} dataPoint An object containing the latitude and longitude of a location; it may additionally contain the property "value" if you wish to position the cluster marker according to the "weight" center of the cluster (see also nokia.maps.clustering.IClusterPoint ).
addAll (dataPoints, [callback])

This method adds a list of data points to the list of objects for clustering.

Note that to ensure optimal performance, it is best to invoke the method nokia.maps.clustering.ClusterProvider#cluster after all the data have been added. Otherwise, as in database systems, addition of new data points means that indices may have to be modified, which incurs a performance penalty.

Parameters:
{nokia.maps.clustering.IClusterPoint[]} dataPoints A collection of data points represented by objects containing latitude and longitude; each point may additionally contain the property "value" if you wish to position the cluster marker according to the "weight" center of the cluster (see also nokia.maps.clustering.IClusterPoint ).
{Function} [callback]: A callback function to be invoked when all data points (see dataPoints above) have been added to the list of items to be considered for clustering
clean ()
This method removes clusters and noise points from display. It removes all the data points and sets the class state to nokia.maps.clustering.ClusterProvider.STATE_INITIAL.
cluster ()

This method starts the clustering process. Note that the process is asynchronous, therefore to receive notification of its completion, you need to attach an observer to the instance of this class, using the method nokia.maps.util.OObject#addObserver. The observer function must be triggered when the ClusterProvider state changes to nokia.maps.clustering.ClusterProvider.STATE_CLUSTERED.

 var ClusterProvider = nokia.maps.clustering.ClusterProvider; 
 clusterProvider = new ClusterProvider(map, {
	  dataPoints: [PASS YOUR DATA POINTS HERE]
 });
 clusterProvider.addObserver("state", function (obj, key, state, oldValue) {
	  if (state == ClusterProvider.STATE_CLUSTERED) {
		  console.log("Clustering is done!");
	  }
 });
 clusterProvider.cluster();
destroy ()
This method cleans up all internal objects and prepares the given instance of this class to be destroyed.
getDataLength () : Number
This method retrieves a numeric value indicating the number of data points in the data set available to the given instance of the class.
Returns:
{Number} A value representing the number of data points
getEps () : Number
This method retrieves the current epsilon value, which represents the area within which data points are considered for clustering.
Returns:
{Number} The current epsilon value
getMinPts () : Number
This method retrieves a value indicating the smallest number of points within the epsilon radius that are required to form a cluster.
Returns:
{Number} The current value of minimum points
invalidate ()
This method invalidates the current results of clustering and sets the state to nokia.maps.clustering.ClusterProvider.STATE_INITIAL. Note that the method does not remove objects from the display: in order to do that, please use the nokia.maps.clustering.ClusterProvider#clean.
numberOfClusters () : Number
This method retrieves the number of clusters in the data set available to the given instance of the class.
Exceptions:
A run-time error if nokia.maps.clustering.ClusterProvider#cluster method has not been called (no clusters have been determined).
Returns:
{Number} A value representing the number of clusters
numberOfNoisePoints () : Number
This method retrieves a numeric value indicating the number of noise points in the data set available to the given instance of this class.
Exceptions:
A run-time error if nokia.maps.clustering.ClusterProvider#cluster method has not been called (no noise points have been determined)
Returns:
{Number} A value indicating the number of noise points
remove (dataPoint)
This method removes a data point from the list of objects to be considered for clustering.
Parameters:
{nokia.maps.clustering.IClusterProvider} dataPoint An object containing latitude and longitude (a data point) to be removed from the list of objects to be considered for clustering
Exceptions:
If indexing is enabled, the method throws a run-time error exception as described for nokia.maps.clustering.Index#remove
setEps (epsilon)

This method sets a new epsilon value (in pixels), which represents the area within which data points are considered for clustering. Depending from the clustering algorithm used, area might be a circle with epsilon radius, or a minimum bounding rectangle of that circle. (DBSCAN algorithm with RTree based index)

Note that clusters should be recalculated when the epsilon value changes. Please call the method nokia.maps.clustering.ClusterProvider#cluster explicitly to force a recalculation.

Parameters:
{Number} epsilon A new epsilon value; it should be a value no smaller than 10
setMinPts (minPts)
This method sets a new value indicating the smallest number of points within the epsilon radius that are required to form a cluster.

Note that clusters should be recalculated whenever this method has been called. Please call the method nokia.maps.clustering.ClusterProvider#cluster explicitly to force a recalculation.

Parameters:
{Number} minPts A value indicating the largest number of data points within the epsilon radius that can exist as individual noise points (that are not subject to clustering); the value must be no smaller than 1
setTheme (theme)
This method sets the theme to use while rendering clusters on the map. Please note, that theme modification triggers the cluster() method.
Parameters:
{nokia.maps.clustering.ITheme} theme An object representing the new theme to use
Exceptions:
A run-time error if the theme object does not conform to the interface nokia.maps.clustering.ITheme
Field Detail
static string STATE_CLUSTERED
This constant indicates a state which an instance of ClusterProvider enters when it has completed clustering and rendering of the markers on the map can begin (is about to begin). Please note that, because clustering may be repeated on every zoom level change, this state might be set multiple times.
static string STATE_INITIAL
This constant identifies the initial state of an instance of this class after the instance has been created, or after invocation of nokia.maps.clustering.ClusterProvider#clean and nokia.maps.clustering.ClusterProvider#invalidate methods.
static string STATE_READY
This constant indicates a state which an instance of ClusterProvider enters when it has determined clusters and noise points and their representation for display on the map. Note that when this state is set, clusters and noise points may not be visible on the map yet. The rendering engine needs some additional time to draw them on the map.
static string STATE_STARTED
This constant indicates a state which an instance of ClusterProvider enters when clustering has started. Please note that, because clustering may be repeated on every zoom level change, this state might be set multiple times.
Documentation generated on Thu Aug 30 2012 10:10:54 GMT+0200 (CEST).