| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# CLUSTER

Table of Contents

- CLUSTER

  - Description

  - Supported Layer Types

  - Mapfile Parameters

  - Supported Processing Options

  - Mapfile Snippet

  - Feature attributes

  - Handling GetFeatureInfo

  - PHP MapScript Usage

  - Example: Clustering Railway Stations

## Description

Since version 6.0, MapServer has the ability to combine multiple features from a point layer into single (aggregated) features based on their relative positions. Only POINT layers are supported. This feature was added through MS RFC 69: Support for clustering of features in point layers.

## Supported Layer Types

Only layers of `TYPE POINT` are supported.

## Mapfile Parameters

MAXDISTANCE [double]

  Specifies the distance of the search region (rectangle or ellipse) in pixel positions.

REGION [string]

  Defines the search region around a feature in which the neighbouring features are negotiated. Can be ‘rectangle’ or ‘ellipse’.

BUFFER [double]

  Defines a buffer region around the map extent in pixels. Default is 0. Using a buffer allows that the neighbouring shapes around the map are also considered during the cluster creation.

GROUP [string]

  This expression evaluates to a string and only the features that have the same group value are negotiated. This parameter can be omitted. The evaluated group value is available in the ‘Cluster_Group’ feature attribute.

FILTER [string]

  We can define the FILTER expression filter some of the features from the final output. This expression evaluates to a boolean value and if this value is false the corresponding shape is filtered out. This expression is evaluated after the the feature negotiation is completed, therefore the ‘Cluster_FeatureCount’ parameter can also be used, which provides the option to filter the shapes having too many or to few neighbors within the search region.

## Supported Processing Options

The following processing options can be used with the cluster layers:

CLUSTER_GET_ALL_SHAPES=ON

  Return all shapes contained by a cluster instead of a single shape. This setting affects both the drawing and the query processing (especially useful for GetFeatureInfo requests). Example usage: PROCESSING “CLUSTER_GET_ALL_SHAPES=ON”

CLUSTER_KEEP_LOCATIONS=ON

  Set whether the location of the cluster shape should be preserved (setting this will show all points in the cluster). Example usage: PROCESSING “CLUSTER_KEEP_LOCATIONS=ON”

CLUSTER_ALGORITHM=SIMPLE

  From Mapserver 6.2 we can choose a more simplified clustering algorithm which performs better that the original (more accurate) approach. usage: PROCESSING “CLUSTER_ALGORITHM=SIMPLE” For more information see:

Bug 5503

CLUSTER_USE_MAP_UNITS=ON

  Provide scale independent clustering (maxdistance and the buffer parameters are specified in map units). Example usage: PROCESSING “CLUSTER_USE_MAP_UNITS=ON”

ITEMS

  Specify the feature attributes in the cluster to expose during a query, separated by a comma. Example usage: PROCESSING “ITEMS=attribute_x,attribute_y,attribute_z”

## Mapfile Snippet

    LAYER
      NAME "my-cluster"
      TYPE POINT
      ...
      CLUSTER
         MAXDISTANCE 20  # in pixels
         REGION "ellipse"  # can be rectangle or ellipse
         GROUP (expression)  # an expression to create separate groups for each value
         FILTER (expression) # a logical expression to specify the grouping condition
      END
      LABELITEM "Cluster_FeatureCount"
      CLASS
        ...
        LABEL
         ...
        END
      END
      ...
    END

## Feature attributes

The clustered layer itself provides the following aggregated attributes:

1. Cluster_FeatureCount - count of the features in the clustered shape

2. Cluster_Group - The group value of the cluster (to which the group expression is evaluated)

> Note

> If you are using MapServer version 6.x these attributes contain a “:” in their names instead, such as `Cluster:FeatureCount` & `Cluster:Group`. The “_” was changed in MapServer 7.

These attributes (in addition to the attributes provided by the original data source) can be used to configure the labels of the features and can also be used in expressions. The ITEMS processing option can be used to specify a subset of the attributes from the original layer in the query operations according to the user’s preference.

We can use simple aggregate functions (Min, Max, Sum, Count) to specify how the clustered attribute should be calculated from the original attributes. The aggregate function should be specified as a prefix separated by ‘:’ in the attribute definition, like: [Max:itemname]. If we don’t specify aggregate functions for the source layer attributes, then the actual value of the cluster attribute will be non-deterministic if the cluster contains multiple shapes with different values. The Count aggregate function in fact provides the same value as Cluster_FeatureCount.

## Handling GetFeatureInfo

If you want to allow WMS GetFeatureInfo on all features inside a cluster, you must 1) set the “wms_include_items” metadata as usual, and 2) set the following PROCESSING parameters in the layer:

    PROCESSING "CLUSTER_GET_ALL_SHAPES=ON"
    PROCESSING "ITEMS=attribute_x,attribute_y,attribute_z"

So your layer might look like the following:

    LAYER
      NAME "my-cluster"
      TYPE POINT
      METADATA
        "wms_title"    "myttitle"
        "wms_include_items" "all"
      END
      ...
      CLUSTER
         ...
      END
      LABELITEM "Cluster_FeatureCount"
      CLASS
        ...
        LABEL
         ...
        END
      END
      ...
      PROCESSING "CLUSTER_GET_ALL_SHAPES=ON"
      PROCESSING "ITEMS=name,description"
    END

## PHP MapScript Usage

The CLUSTER object is exposed through PHP MapScript. An example follows:

    $map = ms_newMapobj("/var/www/vhosts/mysite/httpdocs/test.map");
    $layer1=$map->getLayerByName("test1");
    $layer1->cluster;

## Example: Clustering Railway Stations

The following example uses a point datasource, in this case in KML format, to display clusters of railway stations. Two classes are used: one to style and label the cluster, and one to style and label the single railway station.

Note

Since we can’t declare 2 labelitems, for the single railway class we use the TEXT parameter to label the station.

### Mapfile Layer

    ####################
    # Lightrail Stations
    ####################
    SYMBOL
      NAME "lightrail"
      TYPE PIXMAP
      IMAGE "../etc/lightrail.png"
    END
    LAYER
        NAME "lightrail"
        GROUP "default"
        STATUS DEFAULT
        TYPE POINT
        CONNECTIONTYPE OGR
        CONNECTION "lightrail-stations.kml"
        DATA "lightrail-stations"
        LABELITEM "Cluster_FeatureCount"
        CLASSITEM "Cluster_FeatureCount"
        ###########################
        # Define the cluster object
        ###########################
        CLUSTER
          MAXDISTANCE 50
          REGION "ellipse"
        END
        ################################
        # Class1: For the cluster symbol
        ################################
        CLASS
          NAME "Clustered Lightrail Stations"
          EXPRESSION ("[Cluster_FeatureCount]" != "1")
          STYLE
            SIZE 30
            SYMBOL "citycircle"
            COLOR 255 0 0
          END
          LABEL
            FONT scb
            TYPE TRUETYPE
            SIZE 8
            COLOR 255 255 255
            ALIGN CENTER
            PRIORITY 10
            BUFFER 1
            PARTIALS TRUE
            POSITION cc
          END
        END
        ################################
        # Class2: For the single station
        ################################
        CLASS
          NAME "Lightrail Stations"
          EXPRESSION "1"
          STYLE
            SIZE 30
            SYMBOL "lightrail"
          END
          TEXT "[Name]"
          LABEL
            FONT scb
            TYPE TRUETYPE
            SIZE 8
            COLOR 0 0 0
            OUTLINECOLOR 255 255 255
            ALIGN CENTER
            PRIORITY 9
            BUFFER 1
            PARTIALS FALSE
            POSITION ur
          END
        END
        # the following is used for a query
        TOLERANCE 50
        UNITS PIXELS
        HEADER "../htdocs/templates/cluster_header.html"
        FOOTER "../htdocs/templates/cluster_footer.html"
        TEMPLATE "../htdocs/templates/cluster_query.html"
    END

### Map Image