DataSet Class
Abstract base class for all datasets.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public abstract class DataSet : ResourceObjectRemarks
A DataSet is an object that stores features. There are several kinds of dataset and each type reads features from a specific source, for example the ShapefileDataSet that reads features from Shapefile data or the MySqlDataSet that reads features from a MySql database.
Dataset initialization
All dataset classes in Carmenta Engine support a form of "lazy" initialization. The constructors typically only record the construction parameters, but the real initialization is deferred until the Initialize method is called.
An advantage with this is that it gives the application an opportunity to set some properties that would otherwise have been necessary to pass to the constructor. These properties are read/write until the dataset is initialized, but after initialization they become read-only. The properties with these special semantics are marked in the documentation with a small padlock icon.
An application may explicitly initialize a dataset by calling the initialize method, but this is not mandatory. The dataset will be automatically initialized when some of the other methods are called, usually the first time the view is updated.
Initialization of datasets loaded from configuration files can be controlled by specifying a DataSetInitialization flag to the Configuration constructor.
It's hard to say whether an application should initialize all its datasets during startup, or delay this until the datasets are actually used. For instance, if a dataset needs to be indexed the first time, this might take some time, and it might be better to do this during application startup rather than risking a long delay later on. On the other hand, initializing a dataset means that it might reserve space in the global cache, possibly affecting the performance of other datasets.
Error handling
Errors that occur during dataset initialization, maybe because of missing data, are normally reported to the application by throwing exceptions. In some cases this may not be desirable. Perhaps some of the geographic data used by an application is optional, and may not be installed when the application is started. The application could still work without this data, only certain map layers may not contain any visible data.
To handle this case, the SuppressInitializationErrors property may be specified. If True, any errors that occur during initialization are reported by raising the Runtime.Error event, but no exceptions are thrown. The dataset will still function, but it will act as if empty, and will never return any features.
For compatibility reasons, passing the OnDemandSuppressErrors flag when loading a configuration also has the side effect of setting SuppressInitializationErrors to True for all loaded datasets.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
DataSet
CatalogDataSet
CM93RasterDataSet
CM93VectorDataSet
CoverageDataSet
CustomDataSetProxy
DatabaseDataSet
DataSetSet
DensityDataSet
FileDataSet
HttpDataSet
MemoryDataSet
RaveGeoDataSet
Platforms
Windows, Linux, Android
DataSet Members
The DataSet type has the following members.
Properties
| Name | Description |
|---|---|
| Bounds | Gets or sets the bounding rectangle of the dataset. |
| Crs | Gets or sets the coordinate reference system of the DataSet. |
| Description | Gets or sets a short description of the dataset. |
| DisplayName | Gets or sets a display name for the dataset. |
| Id | Gets a unique identifier for this dataset instance. |
| IsDisposed | Gets a value that tells whether the current DataSet has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the dataset. |
| Name | Gets or sets the name of the DataSet. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current DataSet represents. Inherited from EngineObject |
| SuppressInitializationErrors | Gets or sets a flag indicating how errors during dataset initialization are handled. |
| 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 |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |
| FindChildObject | Overloaded. Finds the child object with the specified name. |
| FlushCache | Frees any information the dataset may have cached, including all cached features. |
| GetChildObjects | Overloaded. Gets the child objects of the current object. |
| GetDataCoverage | Gets coverage information for this dataset in a given area. |
 GetDataSetById | Looks up an existing dataset instance from a dataset identity. |
| GetDataSetInfo | Returns a dataset info that describes the contents of this dataset. |
| GetDataSetInfoAsync | Makes an asynchronous call to GetDataSetInfo. |
| GetFeature | Gets the feature with the specified identity. |
| GetFeatures | Overloaded. Gets features from the dataset. |
| GetFloatValueAt | Overloaded. Gets the float raster value from a cell at the specified position. |
| GetFloatValuesAt | Overloaded. Gets a number of float raster values. |
| GetLocalizedDescription | Gets a localized version of the dataset description in a specific language. |
| GetLocalizedDisplayName | Gets a localized version of the dataset display name in a specific language. |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. |
| GetNormalizedFloatValueAt | Overloaded. Gets the raster value from a cell at the specified position, normalized by Scale and Offset. |
| GetNormalizedFloatValuesAt | Overloaded. Gets a number of raster values, normalized by Scale and Offset. |
| GetValueAt | Overloaded. Gets the integer value from a raster cell at the specified position. |
| GetValuesAt | Overloaded. Gets a number of raster values. |
| HasLocalizedDescription | Checks if a localized version of the dataset description is available in a specific language. |
| HasLocalizedDisplayName | Checks if a localized version of the dataset display name is available in a specific language. |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. |
| HighestRasterValue | Finds the highest raster value inside the given polygon. |
| Initialize | Initializes the dataset. |
| SetLocalizedDescription | Sets a dataset description in a specific language. |
| SetLocalizedDisplayName | Sets a dataset display name in a specific language. |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the dataset, for a specific language. |
| TryGetFloatValueAt | Overloaded. Gets the float value from a raster cell at the specified position. |
| TryGetNormalizedFloatValueAt | Overloaded. Gets the float value from a raster cell at the specified position, normalized by Scale and Offset. |
| TryGetValueAt | Overloaded. Gets the integer value from a raster cell at the specified position. |