DataSetInfo Class
Contains information about a DataSet or about data files.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class DataSetInfo : EngineObjectRemarks
A DataSetInfo is a structure that contains metadata and other information about a DataSet or about data files.
The contents of a DataSetInfo
The structure contains some basic properties that are relevant for most kinds of data:
as well as some other properties that are relevant for raster data:
and one property that is relevant for vector data:
There may also be additional, format-specific metadata stored in an attribute set:
as well as additional metadata according to some specific metadata standard:
Finally, each instance of a DataSetInfo can also have
which are a collection of other DataSetInfo instances. Since the children may have their own children, it is possible to make a hierarchical structure, which is useful to represent information about some kinds of geodata that are hierarchically organized. The most common case is a MultiFileDataSet that refers to more than one file: its main DataSetInfo will represent information about the entire dataset, and each of its children will represent information about a file.
How to get a DataSetInfo
There are three ways to get a DataSetInfo.
If you already have a dataset instance, you can get a DataSetInfo for it by calling DataSet.GetDataSetInfo.
If you want to study the geodata in a specific file, you can get a DataSetInfo for the file by calling the static method FromFile.
If you want to explore the geodata in a whole directory, you can call the static method FromDirectory, which will give you a collection of DataSetInfo instances.
How to use a DataSetInfo
If you got your DataSetInfo from an already existing dataset, you can simply use its information.
If you got it from a file or a directory, you have a possibility to create a corresponding dataset by calling the method
Often, this method can be called from your main DataSetInfo. But sometimes, the method must be called from one of the Children. The latter happens, for example, if a DataSetInfo has been created from a GeoPackage or Map Package file. The main DataSetInfo will then represent the entire file, which has no corresponding dataset, while each child will in its AdditionalInfo have a TableName string, which is necessary to specify when creating a MapPackageDataSet. The reverse situation is also possible: that the main DataSetInfo can create a dataset, while some of its children or grandchildren cannot.
The property
tells whether a DataSetInfo can call CreateDataSet.
Work flow
This class makes it easier for your Carmenta Engine application to use new geodata. If you just know that some new geodata is in a certain file or directory, it is not obvious what kind of DataSet that should be used to read it. So, your application can call FromFile or FromDirectory to get one or several DataSetInfo instances. Each instance represents one way to make a dataset for the data files, or for a subset of them. You can study the information in the instances and choose one to call CreateDataSet from.
The created dataset will not yet be initialized, so you have a chance to modify it before you use it. For example, if the dataset is a MultiFileDataSet - which is very likely - then you should specify an indexPath for it. To do so, you must cast the dataset object from the base class DataSet to the derived class MultiFileDataSet. Furthermore, if the dataset is an ArincDataSet, ShapefileDataSet or VpfDataSet, you should also specify a featureIndexPath.
If you have created a RaveGeoDataSet (data format code: "RaveGeo") from a DataSetInfo, then there is more work to do, because a ReadOperator with a RaveGeoDataSet must also be given a RaveGeoQuery that provides a className. To find the possible class names, examine the children of the DataSetInfo that you created the dataset from. Each child will have a string attribute className in its AdditionalInfo, so choose one child and retrieve the value of the className attribute, then use the string as the className property of a new RaveGeoQuery, which you attach to your ReadOperator.
Carmenta Engine may be unable to find the Crs from the new geodata files. In this case, the predefined Crs.NonGeoreferenced will be the Crs of the DataSetInfo and of the dataset that it creates. A non-georeferenced dataset can be displayed, but only in a non-georeferenced View, so this is mainly useful for a preview in a separate map window. To use the geodata for real, you must find the correct Crs in some way, and specify it for the dataset. Note: the Crs, too, can be specified only before the dataset is initialized, so if a preview map window has used the dataset as non-georeferenced, you will then have to create a fresh copy of the dataset from your DataSetInfo.
To use the created dataset, the application must put it in a layer. Some raster data have built-in visualization: in this case, the HasVisualization flag will be true on the DataSetInfo, which tells you that no VisualizationOperator will be needed in the operator chain. Otherwise, a visualization operator is necessary, and the DataRepresentation property will tell you if the operator needs a RasterVisualizer or some visualizers for vector data.
Some geodata are intended only for detailed map scales, having no overviews that can be used when zooming out. If such geodata are displayed in a map scale that is zoomed-out too much, Carmenta Engine is forced to retrieve a huge amount of data for each update, which will slow down the application and consume a lot of memory. To avoid this, one should set an appropriate Layer.MaxScale, and the EstimatedMaxScale property suggests a possible value. But note that this is just an estimate - for vector data, the estimate may be wrong by a factor 10 or more, but it can be used as a first attempt.
To display the data for the first time, you need to set a suitable View.Center and either the View.Scale or the View.NominalScale. The center can be placed in the middle of the data Bounds, but note that the data bounds are expressed in the Crs of the DataSetInfo, so the bounds center must be reprojected to the View.Crs first.
The view scale to set depends on whether you want maximal zoom-out to display the extent of the geodata but not any details, or if you care more about how the geodata look in their intended display scale. If you want maximal zoom-out, you can use the EstimatedMaxScale also as View.Scale or as View.NominalScale, but you should decrease the value a bit, because a Layer.MaxScale that is exactly equal to the View.NominalScale will disable the layer. If you want to see details, the view scale can instead be taken from the EstimatedScale property. But note that this estimate, too, can be wrong by a factor of 10 or more for vector data.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
DataSetInfo
Platforms
Windows, Linux, Android
DataSetInfo Members
The DataSetInfo type has the following members.
Constructors
| Name | Description |
|---|---|
| DataSetInfo | Initializes a new instance of the DataSetInfo class. |
Properties
| Name | Description |
|---|---|
| AdditionalInfo | Gets an attribute set containing additional metadata, which can depend on the data format. |
| Bounds | Gets or sets the bounding rectangle of the data, expressed in the Crs. |
| CanCreateDataSet | Gets or sets a flag that tells whether the method CreateDataSet can succeed. |
| CellHeight | Gets or sets the height of a raster cell, expressed in Crs units, or zero for vector data. |
| CellWidth | Gets or sets the width of a raster cell, expressed in Crs units, or zero for vector data. |
| Children | Gets a collection of other DataSetInfo instances, containing more specific metadata for parts of the data. |
| ColorTable | Gets the color table that maps raster cell values to colors. |
| Crs | Gets or sets the Crs of the data, if homogeneous, but the Crs that a multi-file dataset has or would have, for heterogeneous data. |
| DataFormatCode | Gets or sets a short string that identifies the data format, for example "JPEG2000" or "Shapefile". |
| DataFormatDescription | Gets or sets a string that describes the data format. |
| DataRepresentation | Gets or sets a value that tells whether the data is raster data or vector data, or a mixture. |
| EstimatedMaxScale | Gets or sets an estimate of the maximal appropriate view scale to display the data. |
| EstimatedScale | Gets or sets an estimate of the view scale appropriate to display the data. |
| FeatureAttributes | Gets information about all attributes that may be present on features. |
| FileName | Gets or sets the file name of the data source; may be empty if the data source is not a file. |
| HasVisualization | Gets or sets a flag that tells if the data have built-in visualization. |
| IsDisposed | Gets a value that tells whether the current DataSetInfo has been disposed. Inherited from EngineObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current DataSetInfo represents. Inherited from EngineObject |
| Path | Gets or sets the path for the data source. |
| ProfileSpecificInfo | Gets additional metadata according to some specific metadata standard. |
| RasterAttributeTable | Gets or sets the raster attribute table that maps raster cell values into sets of attributes. |
| RasterFormat | Gets or sets the raster format of raster data. |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| CreateDataSet | Returns a new dataset that corresponds to this DataSetInfo, or null on failure. |
| 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 |
 FromDirectory | Returns a new collection of DataSetInfo instances with information about the geodata in the given directory. |
| FromDirectoryAsync | Makes an asynchronous call to FromDirectory. |
| FromFile | Returns a new DataSetInfo from the given file. |
| FromFileAsync | Makes an asynchronous call to FromFile. |