Draw object clustering(GDK5)

Overview

Draw object clustering is used to

• Make complex situations easier to comprehend
• Increase performance by reducing information in map

Clustering allows a very large amount of objects to be displayed, without decoding the object data.

Currently, two clustering modes are available:

• Grid clustering, groups dense clusters of point and area objects and display these as circular or bounded areas
• Time fade clustering/filter will only display objects that are available within a time window. Fade times can be set globally or per object.

Grid clustering

Usage from MariaApplication

Clustering is controlled from "Draw" tab, "Clustering". Select algorithm and set parameters. Note that depending on selected algorithm, only some parameters may be actively used.

Clustering control in MariaApplication

Usage from API

The Maria API "DrawObjectLayer" contains a property "ClusterSettings". Set properties on this object to control clustering

/// <summary>
/// Cluster algorithm definitions
/// </summary>
public enum ClusteringAlgorithm
{
    /// <summary>
    /// No clustering.
    /// </summary>
    None,
    /// <summary>
    /// Grid clustering (not used)
    /// </summary>
    GridClustering,

    /// <summary>
    /// TimeFilterClustering is used to only show objects within a time range.
    /// Note that this can also be done using styling. Cluster version is much faster
    /// </summary>
    TimeFilterClustering = 3
}

/// <summary>
/// Interface for draw object clustering. 
/// </summary>
public interface IDrawObjectClustering
{
    /// <summary>
    /// Get or set clustering type.
    /// </summary>
    ClusteringAlgorithm Algorithm { get; set; }     // Algorithm controlling clustering type

    // Grid clustering specific
    int MinItemCount { get; set; }                  // Minimum item cont per cluster in order to perform clustering
    int DetailedObjectInfoThreshold { get; set; }   // If a cluster items <= x, detailed info is included in clustered, including positions and sidc
    int MaxAreaPixelExtent { get; set; }            // Only areas with extent <= this value are considered for clustering
    bool GenerateItemBoundary { get; set; }         // If clustering method supports this, generate cluster boundaries
    bool IncludePoints { get; set; }                // If clustering method supports this, include points in clusters

    int MaxZoomLevelPoints { get; set; }            // For larger scales than this, do not cluster points. Primarily for use in supercluster (currently not used)
    int MaxZoomLevelAreas { get; set; }             // For larger scales than this, do not cluster points. Primarily for use in supercluster (currently not used)
    int CellSize { get; set; }                      // Cell size in pixels

    // TimeFilterClustering specific
    string IsoStartTimeString { get; set; }         // String representation (ISO8601) of filter start time
    DateTimeOffset StartTime { get; set; }          // Filter start time
    uint DefaultFadeTime { get; set; }              // Default fade time in seconds. Used if not set directly on object
    int OffsetSeconds { get; set; }                 // Offset in seconds from StartTime. Actual filtering is StartTime + OffsetSeconds to StartTime + OffsetSeconds + Fade time
}

Bitfield coding for time clustering

In order to use time clustering, the geo store must be created so that time values are encoded into the geo index. Note that this must be set when the store is created.

var storeInfo = new StoreInfo() { Id = "SomeStore", IsInProcessStore = true|false,
    BitFieldCodingSpec = BitFieldCoder.GenerateTimeFadeCodingSpec(
        "APP6D",
        "timeStamp",
        "timeFade")
};
DrawObjectLayer = _drawObjectSystemFactory.CreateLayer(GeoControlViewModel, storeInfo);

The encoding specification required for time fading (provided by GenerateTimeFadeCodingSpec):

public static BitFieldDefinitions GenerateTimeFadeCodingSpec(string app6DField, string timeStampField, string fadeTimeField)
{
    return new BitFieldDefinitions
    {
        Fields =
        [
            new BitFieldDefinition
            {
                Id="App6d_Sidc",
                FieldRef=app6DField,
                DataType = BitFieldDataType.App6DSidcType
            },
            new BitFieldDefinition
            {
                Id="TimeStamp",
                FieldRef=timeStampField,
                DataType = BitFieldDataType.UtcTimeStamp1970,
                FirstBit = 0,
                LastBit = 39,
                IntScaleFactor = 10
            },
            new BitFieldDefinition
            {
                Id="FadeTime",
                FieldRef=fadeTimeField,
                DataType = BitFieldDataType.IntType,
                FirstBit = 40,
                LastBit = 49,
                IntScaleFactor = 10
            }
        ]
    };
}