GroupDataSet Class
Represents an in-memory cache of features that can be organized into groups.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CETactical assembly)
Syntax
public class GroupDataSet : MemoryDataSetRemarks
A GroupDataSet inherits from MemoryDataSet and adds the concept of groups that are used to organize features, and groups, into a tree like structure. One scenario where a GroupDataSet makes sense is to organize features that represent military units into a tree structure that reflects the order of battle.
 |
When Carmenta Engine 5 reads from a GroupDataSet it returns one feature for every group that is visible (a group is visible if its convex hull overlaps the update rectangle). The GroupDataSet will also add an attribute called groupId set to the identity of the property of the group that the feature represents.
Each group also has a set of attributes that are inherited by the feature that represents the group and by any features that belong to the group. This can be used to customize the visualization of both features and groups. For example, groups can be given individual colors and values that should be set on all features in a group can instead be set on the group.
Additionally, the Group.ShowChildren property provides an easy way of filtering which features are read from a GroupDataSet.
Carmenta Engine 5 can use background threads to read from a GroupDataSet and the application must lock the dataset, by using an instance of the Guard class, before it or any feature or group it contains are modified.
More information can be found in Carmenta Engine Threading Model.
The default behavior of a GroupDataSet can be modified by setting a GroupDataSetQuery on the ReadOperator that reads from the dataset.
Performance considerations
A GroupDataSet that contains many features that belong to groups will be slower than using a MemoryDataSet. The main cost comes from the fact that features far outside the visible portion of a View, in fact all features in a group and its descendant groups, must be considered when the dataset calculates if the group is visible or not.
Test your application with a realistic amount of features and groups on a target machine to determine whether the performance is acceptable or not.
Other limitations
Saving the contents of a GroupDataSet with the Save method will only save the features in the dataset and not the group hierarchy.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
DataSet
MemoryDataSet
GroupDataSet
Platforms
Windows, Linux, Android
GroupDataSet Members
The GroupDataSet type has the following members.
Constructors
| Name | Description |
|---|---|
| GroupDataSet | Initializes a new instance of the GroupDataSet class. |
Properties
| Name | Description |
|---|---|
| Bounds | Gets or sets the bounding rectangle of the dataset. Inherited from DataSet |
| Crs | Gets or sets the coordinate reference system of the GroupDataSet. Inherited from DataSet |
| Description | Gets or sets a short description of the dataset. Inherited from DataSet |
| DisplayName | Gets or sets a display name for the dataset. Inherited from DataSet |
| EnableEvents | Gets or sets a value that determines whether the GroupDataSet fires events. Inherited from MemoryDataSet |
| FeatureCount | Gets the number of features in the GroupDataSet. Inherited from MemoryDataSet |
| GroupCount | Gets the number of groups in the GroupDataSet. |
| Id | Gets a unique identifier for this dataset instance. Inherited from DataSet |
| IsDisposed | Gets a value that tells whether the current GroupDataSet has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the dataset. Inherited from DataSet |
| Name | Gets or sets the name of the GroupDataSet. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current GroupDataSet represents. Inherited from EngineObject |
| SuppressInitializationErrors | Gets or sets a flag indicating how errors during dataset initialization are handled. Inherited from DataSet |
| Time | Gets or sets the GroupDataSet time value. Inherited from MemoryDataSet |
| TimeFactor | Gets or sets a value specifying how fast the Time property changes. Inherited from MemoryDataSet |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clear | Removes all features from the MemoryDataSet. Inherited from MemoryDataSet |
| Clone | Creates a copy of an object. Inherited from EngineObject |
| CreateGroup | Overloaded. Creates a new Group in the GroupDataSet. |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from DataSet |
| FireFeatureChanged | Fires the FeatureChanged event for the specified Feature. Inherited from MemoryDataSet |
| FireGroupChanged | Fires the GroupChanged event for the specified Group. |
| FlushCache | Frees any information the dataset may have cached, including all cached features. Inherited from DataSet |
 FromFile | Constructs a MemoryDataSet from the specified file. Inherited from MemoryDataSet |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from DataSet |
| GetDataCoverage | Gets coverage information for this dataset in a given area. Inherited from DataSet |
| GetDataSetById | Looks up an existing dataset instance from a dataset identity. Inherited from DataSet |
| GetDataSetInfo | Returns a dataset info that describes the contents of this dataset. Inherited from DataSet |
| GetDataSetInfoAsync | Makes an asynchronous call to GetDataSetInfo. Inherited from DataSet |
| GetFeature | Gets the feature with the specified identity. Inherited from DataSet |
| GetFeatures | Overloaded. Gets features from the dataset. Inherited from DataSet |
| GetFloatValueAt | Overloaded. Gets the float raster value from a cell at the specified position. Inherited from DataSet |
| GetFloatValuesAt | Overloaded. Gets a number of float raster values. Inherited from DataSet |
| GetGroup | Gets the Group with the specified identity. |
| GetGroups | Gets a GroupEnumerator that enumerates all groups in a GroupDataSet. |
| GetLocalizedDescription | Gets a localized version of the dataset description in a specific language. Inherited from DataSet |
| GetLocalizedDisplayName | Gets a localized version of the dataset display name in a specific language. Inherited from DataSet |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from DataSet |
| GetNormalizedFloatValueAt | Overloaded. Gets the raster value from a cell at the specified position, normalized by Scale and Offset. Inherited from DataSet |
| GetNormalizedFloatValuesAt | Overloaded. Gets a number of raster values, normalized by Scale and Offset. Inherited from DataSet |
| GetReferencingGroups | Gets a collection that contains all groups that a Feature belongs to. |
| GetValueAt | Overloaded. Gets the integer value from a raster cell at the specified position. Inherited from DataSet |
| GetValuesAt | Overloaded. Gets a number of raster values. Inherited from DataSet |
| HasLocalizedDescription | Checks if a localized version of the dataset description is available in a specific language. Inherited from DataSet |
| HasLocalizedDisplayName | Checks if a localized version of the dataset display name is available in a specific language. Inherited from DataSet |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from DataSet |
| HighestRasterValue | Finds the highest raster value inside the given polygon. Inherited from DataSet |
| Initialize | Initializes the dataset. Inherited from DataSet |
| Insert | Inserts a feature into the MemoryDataSet. Inherited from MemoryDataSet |
| Load | Loads all features from the specified file. Inherited from MemoryDataSet |
| RefreshAllFeaturePresentation | Informs the dataset and the containing layer that all of the features have been modified and any cached presentation needs to be updated. Inherited from MemoryDataSet |
| RefreshFeaturePresentation | Informs the dataset and the containing layer that the feature has been modified and any cached presentation needs to be updated. Inherited from MemoryDataSet |
| Remove | Removes a feature from the MemoryDataSet. Inherited from MemoryDataSet |
| RemoveGroup | Overloaded. Removes a Group from a GroupDataSet. |
| RestartVisualizationAnimation | Restarts visualization animations for a feature. Inherited from MemoryDataSet |
| Save | Overloaded. Saves features to a file that Load can read. Inherited from MemoryDataSet |
| SetLocalizedDescription | Sets a dataset description in a specific language. Inherited from DataSet |
| SetLocalizedDisplayName | Sets a dataset display name in a specific language. Inherited from DataSet |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the dataset, for a specific language. Inherited from DataSet |
| StartFeatureAnimation | Overloaded. Starts a feature animation. Inherited from MemoryDataSet |
| StopFeatureAnimation | Stops an ongoing feature animation. Inherited from MemoryDataSet |
| TryGetFloatValueAt | Overloaded. Gets the float value from a raster cell at the specified position. Inherited from DataSet |
| TryGetNormalizedFloatValueAt | Overloaded. Gets the float value from a raster cell at the specified position, normalized by Scale and Offset. Inherited from DataSet |
| TryGetValueAt | Overloaded. Gets the integer value from a raster cell at the specified position. Inherited from DataSet |
Events
| Name | Description |
|---|---|
| FeatureChanged | Occurs when FireFeatureChanged is called with a Feature that belongs in the MemoryDataSet. Inherited from MemoryDataSet |
| FeatureInserted | Occurs when a Feature is inserted into the MemoryDataSet. Inherited from MemoryDataSet |
| FeatureRemoved | Occurs when a Feature is removed from the MemoryDataSet. Inherited from MemoryDataSet |
| GroupChanged | Occurs when the contents of a Group in the GroupDataSet is modified or when FireGroupChanged is called with a group that belongs in the dataset. |
| GroupInserted | Occurs when a Group is inserted into the GroupDataSet. |
| GroupRemoved | Occurs when a Group is removed from the GroupDataSet. |