CLUSTER

Table of Contents

• CLUSTER
  • Description
  • Supported Layer Types
  • Mapfile Parameters
  • Supported Processing Options
  • Mapfile Snippet
  • Feature attributes
  • 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

POINT

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

Return all shapes contained by a cluster instead of a single shape. This setting affects both the drawing and the query processing.

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)

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

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