ImageDataSet Class
A dataset that reads georeferenced images.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEDataSets assembly)
Syntax
public class ImageDataSet : MultiFileDataSetRemarks
This dataset creates raster features from georeferenced files in the basic Supported Image Formats.
External overviews (.ovr files)
ImageDataSet can read overviews from external .ovr files, typically created with GDAL tools or other software based on GDAL. The name of the overview files should be the full name of the image files, plus an additional extension ".ovr". ImageDataSet cannot create such files: if you need to create new overviews, you should instead use the RasterCachePolicy, which will create overviews on a different format. But if you already have image data with corresponding .ovr files, then ImageDataSet will use them.
ImageDataSet can also read the internal overviews that may be stored in TIFF files.
TIFF formats
Most common TIFF variants can be read. Supported single-band raster types include 1, 2, 4, 8, 16 or 32 bit integer rasters, and 32-bit float rasters, with or without color tables. 64-bit double rasters can also be read, but the values will be truncated to 32-bit floats. Supported multi-band raster types include RGB, RGBA, CMYK and YCbCr rasters.
PackBits, LZW and JPEG compression schemes can be used.
Internal striping and tiling is supported. Tiling is preferred, since it makes reading large files much more efficient when only a small part of the entire image is extracted.
If a TIFF file contains overviews ("Pyramid TIFFs") these will be used, unless the dataset is also using an external raster cache, see the RasterCachePolicy property. Depending on the view scale, the ImageDataSet may choose to return one of the down-sampled overviews instead of the main image.
Transparency masks (.msk files)
ImageDataSet can read transparency masks ("nodata masks") from internal bands in TIFF files or from external .msk files. The name of the mask files should be the full name of the image files, plus an additional extension ".msk", and, if overviews are also used, ".msk.ovr". The masks must have the same size and tiling properties as the main image file and its overviews, otherwise they will not be used. The masks must be 1-bit or 8-bit integer rasters.
When a mask is found for an image (main or overview), the image will be modified. Wherever a pixel in the mask has the value 0, the corresponding pixel in the image will be set to the undefined value of the raster. If the image raster does not have an undefined value, an unused value will be selected as undefined; if necessary the bit depth of the raster will be increased. RGB rasters will be expanded to RGBA, zeros in the mask will set the alpha channel to 0 for the corresponding pixels in the RGBA image.
Even though .msk files are also a GDAL extension, they are currently not supported by GdalDataSet.
Metadata
Geographic metadata such as bounds and coordinate reference system (datum and projection) is set from either GeoTIFF tags, "World files" (e.g .tfw for TIFF files) or a single bounds rectangle passed to the dataset during construction.
Unless GeoTIFF metadata is used, the coordinate reference system information is not stored in the file and must be specified at construction. If there is neither GeoTIFF data nor accompanying world files (e.g. tfw) then the geographic extent rectangle must be specified at construction.
A thematic raster file may also have a raster attribute table that can be read from an auxiliary file.
Other notes
A RasterVisualizer is created and connected to the raster features when they are read from the image files. The RasterFilter property is transferred to the visualizer.
For monochrome and gray-scale images, a color table will be created. For images with a color table, the color table will be copied to the visualizer. For RGB(A) and other multi-band formats, no color table is needed.
This means that you do not need to add a VisualizationOperator in the operator chain, unless you want to override any of the visualizer properties. Please see VisualizationOperator.Mode for how to replace and merge visualizers.
The undefinedValue property is used to specify the undefined property for created rasters. Areas of connected (merged) rasters where there is no data will take on this value.
Multiple images in a single file is not supported.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
DataSet
FileDataSet
MultiFileDataSet
ImageDataSet
Platforms
Windows, Linux, Android
ImageDataSet Members
The ImageDataSet type has the following members.
Constructors
| Name | Description |
|---|---|
| ImageDataSet | Initializes a new instance of the ImageDataSet class. |
Properties
| Name | Description |
|---|---|
| Bounds | Gets or sets the bounding rectangle of the dataset. Inherited from DataSet |
| Continuous | Gets or sets a flag indicating if rasters created by this dataset should be interpreted as continuous or discrete. |
| Crs | Gets or sets the coordinate reference system of the ImageDataSet. Inherited from DataSet |
| DatumShiftChoice | Gets or sets a flag that tells how to choose a default datum shift for the Crs. |
| 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 |
| FileName | Gets or sets the name of the file to read from. Inherited from FileDataSet |
| Id | Gets a unique identifier for this dataset instance. Inherited from DataSet |
| IndexFileName | Gets or sets an explicit index file name used for the generated index files in IndexPath. Inherited from MultiFileDataSet |
| IndexPath | Gets or sets the directory where the dataset index files are saved. Inherited from MultiFileDataSet |
| IsDisposed | Gets a value that tells whether the current ImageDataSet 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 ImageDataSet. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current ImageDataSet represents. Inherited from EngineObject |
| Path | Gets or sets the path to the file or files to read from. Inherited from FileDataSet |
| RasterCacheCompression | Gets or sets a value that controls which method is used to compress the tiles in a raster cache. |
| RasterCacheFilter | Gets or sets the down-sampling filter to use when creating raster overviews. |
| RasterCachePolicy | Gets or sets a value indicating the type of raster caching the dataset should use. |
| RasterFilter | Gets or sets the filter that will be used by the RasterVisualizer attached to rasters created by the dataset. |
| SearchSubdirectories | Gets or sets a flag indicating if the dataset will search for data files recursively. Inherited from MultiFileDataSet |
| SuppressInitializationErrors | Gets or sets a flag indicating how errors during dataset initialization are handled. Inherited from DataSet |
| UndefinedValue | Gets or sets the cell value that should be interpreted as "no data". |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
| VerifyIndexFiles | Gets or sets a flag indicating if the contents of index files should be verified before use. Inherited from MultiFileDataSet |
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. Inherited from DataSet |
| FlushCache | Frees any information the dataset may have cached, including all cached features. Inherited from DataSet |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |