XYZ Maps Documentation
    Preparing search index...

    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.

    ClusterFeature

    // 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 (View Summary)

    Index
    constructor
    id margin max maxDataZoom min name
    addEventListener addFeature clear getCachedTile getCluster getClusters getDataProvider getProvider getStyle getStyleGroup getTile isVisible pointerEvents removeEventListener removeFeature search setFeatureCoordinates setMargin setStyle setStyleGroup setVisible
    id: string

    The identifier of the Layer.

    margin: number

    default tile margin in pixel

    max: number

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

    maxDataZoom: number

    Maximum zoom level at which actual tile data is available from the data source. When the map is zoomed beyond this level, the display loads tiles at maxDataZoom and scales them up.

    Same as max

    min: number

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

    name: string = ''

    The name of the Layer

    • 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

      Returns any

    • Add a feature to the layer.

      Parameters

      • feature: Feature<string> | GeoJSONFeature<string>

        the feature to be added to the layer

      • Optionalstyle: CommonStyle[]

        optional style the feature should be displayed with.

      Returns Feature

      // 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"
         }
      });

      // 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
      }]);

    • Add features to the layer.

      Parameters

      Returns Feature<string>[]

      // 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"
         }
      }]);

    • 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

      • Optionalbbox: GeoJSONBBox

        Optional. The bounding box defining the area to clear.

      Returns any

    • 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

      • Optionalbbox: GeoJSONBBox

        Optional. The bounding box defining the area to clear.

      • OptionalclearDataProvider: boolean

      Returns any

    • Get a locally cached tile by quadkey.

      Parameters

      • quadkey: string

        the quadkey of the tile

      Returns Tile

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

      • zoom: number = ...

        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.

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

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

    • Get provider(s) of this layer.

      Parameters

      • zoom: number = ...

      Returns ClusterProvider

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

      • Optionalzoomlevel: 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.

      • OptionallayerDefault: 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 CommonStyle[]

      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.

    • Get a tile by quadkey.

      Parameters

      • quadkey: string

        quadkey of the tile

      • callback: (tile: Tile) => void

        callback function

      Returns Tile

      the Tile is returned if its already cached locally

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

      Returns boolean

      • Returns true if the layer is visible, otherwise false.
      if (layer.isVisible()) {
        console.log("Layer is visible");
      } else {
        console.log("Layer is not visible");
      }

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

      Parameters

      • OptionalzoomLevel: number

      Returns boolean

      • Returns true if the layer is visible, otherwise false.
      if (layer.isVisible()) {
        console.log("Layer is visible");
      } else {
        console.log("Layer is not visible");
      }

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

      Parameters

      • Optionalactive: boolean

        boolean to enable or disable posinter-events.

      Returns boolean

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

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

      Returns any

    • Search for feature(s) in the layer.

      Parameters

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

        configure the search

        • id: string | number

          search a feature by id.

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

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

        • Optionalonload?: (result: Feature<string>) => void

          Callback function for "remote" search.

        • Optionalremote?: boolean

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

      Returns Feature

      array of features

      // 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) => {...}
      })

    • Search for feature(s) in the layer.

      Parameters

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

        configure the search

        • Optionalids?: number[] | string[]

          Array of feature ids to search.

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

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

        • Optionalonload?: (result: Feature<string>[]) => void

          Callback function for "remote" search.

        • Optionalpoint?: GeoPoint

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

        • Optionalradius?: number

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

        • Optionalrect?: GeoRect | GeoJSONBBox

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

        • Optionalremote?: boolean

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

      Returns Feature<string>[]

      array of features

      // 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) => {...}
      })

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

      Parameters

      • rect: GeoRect | GeoJSONBBox

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

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

        configure the search

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

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

        • Optionalonload?: (result: Feature<string>[]) => void

          Callback function for "remote" search.

        • Optionalremote?: boolean

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

      Returns Feature<string>[]

      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) => {...}
      })

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

      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

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

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

        • Optionalonload?: (result: Feature) => void

          Callback function for "remote" search.

        • Optionalradius?: number

          the radius is mandatory for circle search.

        • Optionalremote?: boolean

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

      Returns Feature<string>[]

      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.
       }
      })

    • Search for feature by id in the layer.

      Parameters

      • id: string | number

        id of the feature to search for

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

        configure the search

        • Optionalonload?: (result: Feature) => void

          Callback function for "remote" search.

        • Optionalremote?: boolean

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

      Returns Feature

      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.
      }
      })

    • Set the tile margin in pixel.

      Parameters

      • tileMargin: number = 0

        the tileMargin

      Returns number

    • Set layer with given style.

      Parameters

      • layerStyle: RuntimeLayerStyle | LayerStyle

        the layerStyle

      • keepCustom: boolean = false

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

      Returns 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

      • OptionalstyleGroup: false | CommonStyle[]

        the styleGroup that feature should be displayed with

      Returns void

    • Sets the visibility of the Layer.

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

      Parameters

      • OptionalisVisible: boolean

        A boolean value indicating whether the tile layer should be visible (true) or hidden (false).

      Returns void

      • The current visibility state of the tile layer.
      // Create a new tile layer
      let tileLayer = new XYZMapsTileLayer();

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

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

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods