AggregatingLayer Class
Aggregates visualizations generated from point features in a hierarchical organization to avoid overlap.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class AggregatingLayer : LayerSetRemarks
This layer can be used to show or hide visualization generated from point features in a hierarchical organization/command structure to avoid overlap. One example where this can be useful is in military applications where units are organized in an order of battle (ORBAT) and you want to show units at higher levels as you zoom out and vice versa. However, it is important to note that the AggregatingLayer does not differentiate between different kinds of visualizations, only that the corresponding point features can be organized into hierarchies.
The hierarchical organization of the features is implied by two feature attributes. The names of these attributes are specified by the IdAttribute and the ParentIdAttribute. The ID attribute on each feature should contain a unique value that identifies the feature, typically a string, atom or integer. The parent ID attribute should contain the id of the parent feature, if one exists.
 |
The image above illustrates how a hierarchy is built from four features: A, B, C and D. Feature A is the parent node of the other features.
It is possible to construct invalid hierarchies by introducing loops where one feature specifies a descendant feature as its parent. For example, a loop can be introduced in the hierarchy in the image above if feature A specifies either feature B, C or D as a parent. Carmenta Engine will detect such errors and make sure the hierarchy is well-formed by removing an edge in the loop, but it is undefined which edge is removed.
Default aggregation
After all features and their associated visualization have been organized into hierarchies, the default aggregation proceeds as follows (this is a simplified explanation): First the layer calculates the bounds of each feature's visualization. Then each hierarchy is examined from the leafs towards the root and the layer displays the deepest parts of the tree that do not cause any overlap between siblings and hides the rest.
 |
In this example we have added three child features to feature C, namely features: E, F and G. The visualization of feature E and F overlap each other and since they have the same parent they and all their siblings (in this case feature G) are hidden and replaced by their parent, feature C. This makes the final result without any overlap between siblings:
 |
There are two other aggregation policies available, called aggressive and relaxed, that alter how the layer aggregates branches in a hierarchy. The aggressive policy removes not only sibling conflicts, but also conflicts between cousins, uncles and other relatives in the same hierarchy. The relaxed policy removes sibling conflicts only when all siblings conflict. See the AggregationPolicy property for more information.
Modifying the feature hierarchy at runtime
Some of the state that the AggregatingLayer works with is maintained inside the MemoryDataSet that contains all features being aggregated by the layer. It is important that this state is kept up-to-date whenever you make changes to the feature hierarchy.
Specifically, if you modify the id, parent id or aggregate attribute of a feature that has been inserted into the MemoryDataSet, you must call either MemoryDataSet.RefreshFeaturePresentation with the feature that was modified or FlushCache on the AggregatingLayer. The first method is preferable because it can be more efficient.
It is not necessary to call MemoryDataSet.RefreshFeaturePresentation or explicitly flush the layer when you insert features into or remove features from a MemoryDataSet.
You must also call FlushCache on the layer if you change the value of either the GenerateConvexHulls or GenerateNetworks properties at runtime.
Additional functionality
The AggregatingLayer has more functionality can be enabled through the following properties:
AggregateAttribute - Lets you specify the name of a feature attribute whose value will let you override if individual features can aggregate descendants or not.
GenerateConvexHulls - Makes it possible to visualize the convex hulls around features and their descendants.
GenerateNetworks - Makes it possible to visualize the edges between features and their descendants.
Performance considerations and limitations
The recommended practice is that an AggregatingLayer only reads features from a single MemoryDataSet. It can read and aggregate features from several datasets but, for the final result to be correct, you must make sure that entire feature hierarchies belong to the same dataset.
The best performance is achieved by aggregating features visualized by an OrdinaryLayer that uses the dynamic cache mode. This avoids processing all features through the entire operator chain and generating the visualization during each update. However, the convex hulls and/or hierarchical networks can not be displayed using the dynamic cache mode.
You can not combine an AggregatingLayer with a TileLayer, either as the parent or the child layer.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Layer
LayerSet
AggregatingLayer
Platforms
Windows, Linux, Android
AggregatingLayer Members
The AggregatingLayer type has the following members.
Constructors
| Name | Description |
|---|---|
| AggregatingLayer | Initializes a new instance of the AggregatingLayer class. |
Properties
| Name | Description |
|---|---|
| Aggregate | Gets or sets a value that determines whether the layer tries to aggregate visualization. |
| AggregateAttribute | Gets or sets the feature attribute whose value can override when or if a feature is hidden by the layer. |
| AggregationPolicy | Gets or sets the aggregation policy used by the AggregatingLayer. |
| BlendMode | Gets or sets the blend mode that determines how the layer is combined with previously rendered layers. Inherited from Layer |
| Condition | Gets or sets the Condition that determines whether the AggregatingLayer is drawn or not. Inherited from Layer |
| CoverageHint | Gets or sets a value that can assert that the visualization is fully opaque within the data extent. Inherited from Layer |
| Description | Gets or sets a short description of the layer. Inherited from Layer |
| DisableOnError | Gets or sets a value specifying if an error within the layer should automatically disable the layer, or throw an exception. Inherited from Layer |
| DisplayName | Gets or sets a display name for the layer. Inherited from Layer |
| Effects | List of effects Inherited from Layer |
| Enabled | Determines whether the AggregatingLayer is enabled or not. Inherited from Layer |
| EnabledDuringQuickUpdates | Determines whether the AggregatingLayer is temporarily turned off during mouse interactions. Inherited from Layer |
| GenerateConvexHulls | Gets or sets a value that determines whether convex hulls representing the hierarchical topography are generated. |
| GenerateNetworks | Gets or sets a value that determines whether lines representing the hierarchical topography are generated. |
| IdAttribute | Gets or sets the feature attribute that contains a value that identifies the feature. |
| IsDisposed | Gets a value that tells whether the current AggregatingLayer has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path or URL to an ISO 19139 metadata document for the layer. Inherited from Layer |
| Layers | Gets the child layers of this AggregatingLayer. Inherited from LayerSet |
| Legend | Gets or sets a map legend associated with this layer. Inherited from Layer |
| MaxScale | Gets or sets the highest inverted nominal scale in a 2D view, or the furthest distance in a 3D globe view, at which objects from this AggregatingLayer should be drawn. Inherited from Layer |
| MinScale | Gets or sets the lowest inverted nominal scale this AggregatingLayer should be drawn at. Inherited from Layer |
| Name | Gets or sets the name of the layer. Inherited from Layer |
| NamedStyles | Gets the list of named styles that can be enabled for the layer. Inherited from Layer |
| NativeHandle | Gets the native Carmenta Engine kernel object the current AggregatingLayer represents. Inherited from EngineObject |
| Opacity | Gets or sets a value that specifies the opacity of the layer. Inherited from Layer |
| ParentIdAttribute | Gets or sets the feature attribute that contains a value that identifies the parent feature. |
| Selectable | Gets or sets a value that determines whether features in this AggregatingLayer can be selected. Inherited from Layer |
| ShowAncestors | Gets or sets a value that determines whether the layer displays ancestor features in aggregated branches. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| EnableStyle | Enables or disables a named style for the layer. Inherited from Layer |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from Layer |
| FlushCache | Marks the layer as flushed which will release cached resources during the next update. Inherited from Layer |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from Layer |
| GetDataBounds | Calculates the bounds of all dataset coverages in the layer. Inherited from Layer |
| GetFeatureAttributes | Gets information about all attributes that may be present on features in this layer. Inherited from Layer |
| GetFeatures | Overloaded. Gets features from the layer and any child layers. Inherited from Layer |
| GetLastError | Gets the error message for the last error that occurred within the layer. Inherited from Layer |
| GetLocalizedDescription | Gets a localized version of the layer description in a specific language. Inherited from Layer |
| GetLocalizedDisplayName | Gets a localized version of the layer display name in a specific language. Inherited from Layer |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from Layer |
| HasLocalizedDescription | Checks if a localized version of the layer description is available in a specific language. Inherited from Layer |
| HasLocalizedDisplayName | Checks if a localized version of the layer display name is available in a specific language. Inherited from Layer |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from Layer |
| IsStyleEnabled | Checks if a certain style is enabled for the layer or not. Inherited from Layer |
| MoveLayer | Moves a child layer to a new position. Inherited from LayerSet |
| SetLocalizedDescription | Sets a layer description in a specific language. Inherited from Layer |
| SetLocalizedDisplayName | Sets a layer display name in a specific language. Inherited from Layer |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the layer, for a specific language. Inherited from Layer |
Events
| Name | Description |
|---|---|
| EnabledChanged | Occurs when the value of the Enabled property has changed. Inherited from Layer |