Options
All
  • Public
  • Public/Protected
  • All
Menu

Class ClusterTileLayer

The ClusterTileLayer class is a specialized TileLayer designed to efficiently handle clustering of GeoJSON data from various DataSources/DataProviders.

This layer aggregates data points within map tiles to reduce visual clutter and improve performance, particularly when dealing with large datasets. When features are being added or removed from the DataSources, the ClusterTileLayer automatically updates to reflect the changes. Data will be clustered for each zoom level optimally from min up to clusterMaxZoom. For zoom levels below clusterMaxZoom and upto min, the untouched source data features will be displayed.

Additionally, the ClusterTileLayer supports cluster property aggregation, allowing developers to customize how properties are aggregated when features are added or removed from the cluster. The following methods are available for property aggregation:

  • createProperties(featureProperties: { [propertyName: string]: any }): { [propertyName: string]: any }: Creates initial properties for a cluster based on the properties of a feature.

  • addProperties(clusterProperties: { [propertyName: string]: any }, featureProperties: { [propertyName: string]: any }): void: Updates cluster properties when a feature is added to the cluster.

  • removeProperties(clusterProperties: { [propertyName: string]: any }, featureProperties: { [propertyName: string]: any }): void: Updates cluster properties when a feature is removed from the cluster.

This layer also utilizes the ClusterFeature class to represent clusters.

see

ClusterFeature

example
// Create a new ClusterTileLayer with specified options
const myLayer = new ClusterTileLayer({
    min: 2,        // Minimum zoom level to cluster and display the layer
    max: 20,       // Maximum zoom level the layer will be displayed
    clusterMaxZoom:13, // the maximum zoom level data will be clustered
    clusterRadius: 15, // Cluster radius in pixels
    provider: myDataProvider // The data provider that data should be clustered
});

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Properties

Readonly id

id: string

The identifier of the Layer.

Protected margin

margin: number

default tile margin in pixel

max

max: number

maximum zoom level at which data from the Layer will be displayed.

min

min: number

minimum zoom level at which data from the Layer is displayed.

name

name: string = ""

The name of the Layer

Methods

addEventListener

  • addEventListener(type: string, listener: (event: CustomEvent) => void): any

  • Add an EventListener to the layer. Valid events: "featureAdd", "featureRemove", "featureCoordinatesChange", "clear", "styleGroupChange", "styleChange", and "viewportReady"

    The detail property of the Event gives additional information about the event. detail.layer is a reference to the layer onto which the event was dispatched and is set for all events.

    Parameters

    • type: string

      A string representing the event type to listen for

    • listener: (event: CustomEvent) => void

      the listener function that will be called when an event of the specific type occurs

        • (event: CustomEvent): void

        • Parameters

          • event: CustomEvent

          Returns void

    Returns any

addFeature

  • Add a feature to the layer.

    example
    // add a feature that will be displayed with the default style of the layer.
layer.addFeature({
   type: "Feature"
   geometry: {
       coordinates: [[-122.49373, 37.78202, 0], [-122.49263, 37.78602, 0]],
       type: "LineString"
   }
});
    example
    // add a feature that will be displayed with a specific style.
layer.addFeature({
   type: "Feature"
   geometry: {
       coordinates: [[-122.49373, 37.78202, 0], [-122.49263, 37.78602, 0]],
       type: "LineString"
   }
}, [{
   zIndex: 0, type: "Line", stroke: "#DDCB97", "strokeWidth": 18
}]);

    Parameters

    • feature: GeoJSONFeature | Feature

      the feature to be added to the layer

    • Optional style: Style[]

      optional style the feature should be displayed with.

    Returns Feature

  • Add features to the layer.

    example
    // add multiple features to the layer.
layer.addFeature([{
   type: "Feature"
   geometry: {
       coordinates: [[-122.49373, 37.78202], [-122.49263, 37.78602]],
       type: "LineString"
   }
},{
   type: "Feature"
   geometry: {
       coordinates: [[-122.49375, 37.78203], [-122.49265, 37.78604]],
       type: "LineString"
   }
}]);

    Parameters

    Returns Feature[]

clear

  • Clears the source data provider and all associated clusters, optionally within a specified bounding box.

    If no bounding box is provided, all features in the source dataProvider and all clusters will be cleared.

    Parameters

    Returns any

getCachedTile

  • getCachedTile(quadkey: string): Tile

  • Get a locally cached tile by quadkey.

    Parameters

    • quadkey: string

      the quadkey of the tile

    Returns Tile

getCluster

  • Retrieves the cluster to which the specified feature belongs at the given zoom level.

    Parameters

    • feature: Feature<"Point">

      The feature for which to retrieve the cluster.

    • Default value zoom: number = this.clusterMaxZoom

      The zoom level. If not specified, the current map zoom level will be used.

    Returns ClusterFeature

    The cluster feature to which the specified feature belongs, or undefined if no cluster exists.

getClusters

  • getClusters(feature: Feature<"Point">): any[]

  • Retrieves all clusters to which the specified feature belongs across all zoom levels. The returned array is ordered by zoom level in descending order, starting from the ClusterTileLayerOptions.clusterMaxZoom.

    Parameters

    • feature: Feature<"Point">

      The feature for which to retrieve all clusters.

    Returns any[]

    An array of cluster features to which the specified feature belongs, ordered by zoom level.

getDataProvider

  • Retrieves the data provider associated with this ClusterTileLayer.

    The data provider is responsible for supplying the features that are to be clustered and displayed within the ClusterTileLayer.

    Returns FeatureProvider

    The FeatureProvider instance used by this layer.

getProvider

getStyle

getStyleGroup

  • getStyleGroup(feature: Feature, zoomlevel?: number, layerDefault?: boolean): readonly Style[]

  • Get styleGroup for the feature.

    This method retrieves a StyleGroup for a given feature, optionally based on the specified zoom level and whether to use the layer default styles.

    Parameters

    • feature: Feature

      The feature for which to get the styles.

    • Optional zoomlevel: number

      The zoom level to use for determining the styles. This parameter should be set as it determines how styles are applied based on zoom. It is only optional if the style definition supports being applied without a specific zoom level.

    • Optional layerDefault: boolean

      (Optional) A boolean indicating whether to use the layer's default styles. If true, any custom styles set via TileLayer.setStyleGroup are ignored and the default layer styles are returned. If false, the method will return the custom styles set for the feature if available; otherwise, it returns the default layer styles. Default is false.

    Returns readonly Style[]

    A readonly StyleGroup representing the styles for the given feature at the specified zoom level. If no styles are found, a falsy value is returned, indicating that the feature is not displayed/visible.

getTile

  • getTile(quadkey: string, callback: (tile: Tile) => void): Tile | undefined

  • Get a tile by quadkey.

    Parameters

    • quadkey: string

      quadkey of the tile

    • callback: (tile: Tile) => void

      callback function

        • (tile: Tile): void

        • Parameters

          Returns void

    Returns Tile | undefined

    the Tile is returned if its already cached locally

isVisible

  • isVisible(): boolean

  • Checks whether the xyz-maps tile layer is currently visible.

    example
    if (layer.isVisible()) {
  console.log("Layer is visible");
} else {
  console.log("Layer is not visible");
}

    Returns boolean

    • Returns true if the layer is visible, otherwise false.

pointerEvents

  • pointerEvents(active?: boolean): boolean

  • Enable or disable pointer-event triggering for all features of the layer.

    Parameters

    • Optional active: boolean

      boolean to enable or disable posinter-events.

    Returns boolean

    boolean indicating if pointer-event triggering is active or disabled.

removeEventListener

  • removeEventListener(type: string, listener: (event: CustomEvent) => void): any

  • Remove an EventListener from the layer. Valid events: "featureAdd", "featureRemove", "featureCoordinatesChange", "clear", "styleGroupChange", "styleChange", and "viewportReady"

    Parameters

    • type: string

      A string which specifies the type of event for which to remove an event listener.

    • listener: (event: CustomEvent) => void

      The listener function of the event handler to remove from the TileLayer.

        • (event: CustomEvent): void

        • Parameters

          • event: CustomEvent

          Returns void

    Returns any

removeFeature

search

  • search(options: { id: number | string; onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature | null) => void; remote?: boolean }): Feature
  • search(options: { ids?: number[] | string[]; onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature[] | null) => void; point?: GeoPoint; radius?: number; rect?: GeoRect | GeoJSONBBox; remote?: boolean }): Feature[]
  • search(rect: GeoRect | GeoJSONBBox, options?: { onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature[] | null) => void; remote?: boolean }): Feature[]
  • search(point: GeoPoint, options: { onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature) => void; radius?: number; remote?: boolean }): Feature[]
  • search(id: string | number, options?: { onload?: (result: Feature) => void; remote?: boolean }): Feature

  • Search for feature(s) in the layer.

    example
    // searching by id:
layer.search({id: 1058507462})

// remote search:
layer.search({
    id: 1058507462,
    remote: true, // force layer to do remote search if feature/search area is not cached locally
    onload: (result) => {...}
})

    Parameters

    • options: { id: number | string; onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature | null) => void; remote?: boolean }

      configure the search

      • id: number | string

        search a feature by id.

      • Optional onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void

        Function to be called when a request of a "remote search" fails.

          • (error: { message: string; name: "NetworkError"; responseText: string; status: number }): void

          • Parameters

            • error: { message: string; name: "NetworkError"; responseText: string; status: number }
              • message: string

                The error message of the failing request.

              • name: "NetworkError"

                The name property represents a name for the type of error. The value is "NetworkError".

              • responseText: string

                The responseText which contains the textual data received of the failing request.

              • status: number

                The numerical HTTP status code of the failing request.

            Returns void

      • Optional onload?: (result: Feature | null) => void

        Callback function for "remote" search.

          • Parameters

            Returns void

      • Optional remote?: boolean

        Force the data provider(s) to do remote search if no result is found in local cache.

    Returns Feature

    array of features

  • Search for feature(s) in the layer.

    example
    // searching features by id:
layer.search({ids: [1058507462, 1058507464]})

// searching by point and radius:
layer.search({
    point: {longitude: 72.84205, latitude: 18.97172},
    radius: 100
})

// searching by Rect:
layer.search({
    rect:  {minLon: 72.83584, maxLat: 18.97299, maxLon: 72.84443, minLat: 18.96876}
})

// remote search:
layer.search({
    rect:  {minLon: 72.83584, maxLat: 18.97299, maxLon: 72.84443, minLat: 18.96876},
    remote: true, // force layer to do remote search if feature/search area is not cached locally
    onload: (result) => {...}
})

    Parameters

    • options: { ids?: number[] | string[]; onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature[] | null) => void; point?: GeoPoint; radius?: number; rect?: GeoRect | GeoJSONBBox; remote?: boolean }

      configure the search

      • Optional ids?: number[] | string[]

        Array of feature ids to search.

      • Optional onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void

        Function to be called when a request of a "remote search" fails.

          • (error: { message: string; name: "NetworkError"; responseText: string; status: number }): void

          • Parameters

            • error: { message: string; name: "NetworkError"; responseText: string; status: number }
              • message: string

                The error message of the failing request.

              • name: "NetworkError"

                The name property represents a name for the type of error. The value is "NetworkError".

              • responseText: string

                The responseText which contains the textual data received of the failing request.

              • status: number

                The numerical HTTP status code of the failing request.

            Returns void

      • Optional onload?: (result: Feature[] | null) => void

        Callback function for "remote" search.

          • Parameters

            Returns void

      • Optional point?: GeoPoint

        Geographical center point of the circle to search in. options.radius must be defined.

      • Optional radius?: number

        Radius of the circle in meters, it is used in "point" search.

      • Optional rect?: GeoRect | GeoJSONBBox

        Geographical Rectangle to search in. [minLon, minLat, maxLon, maxLat] | GeoRect.

      • Optional remote?: boolean

        Force the data provider(s) to do remote search if no result is found in local cache.

    Returns Feature[]

    array of features

  • Rectangle Search for feature(s) in the layer.

    example
    layer.search({minLon: 72.83584, maxLat: 18.97299, maxLon: 72.84443, minLat: 18.96876})
// or:
layer.search([72.83584, 18.96876, 72.84443,18.97299])

// remote search:
layer.search({ minLon: 72.83584, maxLat: 18.97299, maxLon: 72.84443, minLat: 18.96876 }, {
    remote: true, // force layer to do remote search if search area is not cached locally
    onload: (result) => {...}
})

    Parameters

    • rect: GeoRect | GeoJSONBBox

      Geographical Rectangle to search in. [minLon, minLat, maxLon, maxLat] | GeoRect.

    • Optional options: { onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature[] | null) => void; remote?: boolean }

      configure the search

      • Optional onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void

        Function to be called when a request of a "remote search" fails.

          • (error: { message: string; name: "NetworkError"; responseText: string; status: number }): void

          • Parameters

            • error: { message: string; name: "NetworkError"; responseText: string; status: number }
              • message: string

                The error message of the failing request.

              • name: "NetworkError"

                The name property represents a name for the type of error. The value is "NetworkError".

              • responseText: string

                The responseText which contains the textual data received of the failing request.

              • status: number

                The numerical HTTP status code of the failing request.

            Returns void

      • Optional onload?: (result: Feature[] | null) => void

        Callback function for "remote" search.

          • Parameters

            Returns void

      • Optional remote?: boolean

        Force the data provider(s) to do remote search if no result is found in local cache.

    Returns Feature[]

  • Circle Search for feature(s) in the layer.

    example
    layer.search({longitude: 72.84205, latitude: 18.97172},{
 radius: 100
})
// or:
layer.search([72.84205, 18.97172], {
 radius: 100
})

// remote search:
layer.search([72.84205, 18.97172], {
 radius: 100,
 remote: true, // force layer to do remote search if search area is not cached locally
 onload: function(result){
  // search result is only return in this callback function if features are not found in cache.
 }
})

    Parameters

    • point: GeoPoint

      Geographical center point of the circle to search in. options.radius must be defined.

    • options: { onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void; onload?: (result: Feature) => void; radius?: number; remote?: boolean }

      configure the search

      • Optional onerror?: (error: { message: string; name: "NetworkError"; responseText: string; status: number }) => void

        Function to be called when a request of a "remote search" fails.

          • (error: { message: string; name: "NetworkError"; responseText: string; status: number }): void

          • Parameters

            • error: { message: string; name: "NetworkError"; responseText: string; status: number }
              • message: string

                The error message of the failing request.

              • name: "NetworkError"

                The name property represents a name for the type of error. The value is "NetworkError".

              • responseText: string

                The responseText which contains the textual data received of the failing request.

              • status: number

                The numerical HTTP status code of the failing request.

            Returns void

      • Optional onload?: (result: Feature) => void

        Callback function for "remote" search.

      • Optional radius?: number

        the radius is mandatory for circle search.

      • Optional remote?: boolean

        Force the data provider(s) to do remote search if no result is found in local cache.

    Returns Feature[]

  • Search for feature by id in the layer.

    example
    layer.search(1058507462)

// remote search:
layer.search(1058507462,{
remote: true, // force layer to do remote search if search area is not cached locally
onload: function(feature){
 // search result is only return in this callback function if features are not found in cache.
}
})

    Parameters

    • id: string | number

      id of the feature to search for

    • Optional options: { onload?: (result: Feature) => void; remote?: boolean }

      configure the search

      • Optional onload?: (result: Feature) => void

        Callback function for "remote" search.

      • Optional remote?: boolean

        Force the data provider(s) to do remote search if no result is found in local cache.

    Returns Feature

setFeatureCoordinates

setMargin

  • setMargin(tileMargin?: number): number

  • Set the tile margin in pixel.

    Parameters

    • Default value tileMargin: number = 0

      the tileMargin

    Returns number

setStyle

  • setStyle(layerStyle: LayerStyle | XYZLayerStyle, keepCustom?: boolean): void

  • Set layer with given style.

    Parameters

    • layerStyle: LayerStyle | XYZLayerStyle

      the layerStyle

    • Default value keepCustom: boolean = false

      keep and reuse custom set feature styles that have been set via TileLayer.setStyleGroup

    Returns void

setStyleGroup

  • setStyleGroup(feature: Feature, styleGroup?: Style[] | false | null): void

  • Set StyleGroup the feature should be rendered with. Pass styleGroup = false|null to hide the feature. If no styleGroup is passed, custom feature style will be cleared and layer default style will be set.

    Parameters

    • feature: Feature

      the feature that's styleGroup should be set

    • Optional styleGroup: Style[] | false | null

      the styleGroup that feature should be displayed with

    Returns void

setVisible

  • setVisible(isVisible?: boolean): void

  • Sets the visibility of the Layer.

    This function controls whether the tile layer is currently displayed or hidden.

    example
    // Create a new tile layer
let tileLayer = new XYZMapsTileLayer();

// Hide the tile layer
tileLayer.visible(false);

// Show the tile layer
tileLayer.visible(true);

    Parameters

    • Optional isVisible: boolean

    Returns void

    • The current visibility state of the tile layer.

Generated using TypeDoc