luciad::GdalModelDecoder Class Reference

This class is a factory that provides new instances of a Model that are decoded using the GDAL library. More...

#include <luciad/formats/gdal/GdalModelDecoder.h>

Public Member Functions
	GdalModelDecoder ()=delete
	~GdalModelDecoder ()=delete

Static Public Member Functions
static luciad::expected< std::shared_ptr< Model >, ErrorInfo >	decode (const std::string &source)
	Creates a model for a raster or vector file supported by the GDAL library. More...

Detailed Description

This class is a factory that provides new instances of a Model that are decoded using the GDAL library.

The created model is either an IRasterModel or an IFeatureModel giving the ability to access the data within files of the following supported formats:

• GeoTIFF (*.tif, *.tiff)
• Esri Shapefile (*.shp)

Since

2020.1

Constructor & Destructor Documentation

GdalModelDecoder()

luciad::GdalModelDecoder::GdalModelDecoder ( )

delete

~GdalModelDecoder()

luciad::GdalModelDecoder::~GdalModelDecoder ( )

delete

Member Function Documentation

decode()

static luciad::expected< std::shared_ptr< Model >, ErrorInfo > luciad::GdalModelDecoder::decode ( const std::string &  source )

static

Creates a model for a raster or vector file supported by the GDAL library.

See class documentation for more information on the supported file formats.

Raster data

Raster limitations

Currently, the following features are supported:

• the raster can be positioned on the world using
  • a translation and a (positive, non-mirror) scaling
  • a translation, scaling, and rotation
  • tie points, i.e., a mapping between raster pixel locations and a location in a coordinate reference system
    • the number of tie points must be at least 3
    • 3 tie points: an affine transformation is derived
    • 4 or more tie points: an affine transformation is derived using a least-squares approach
  • Rational Polynomial Coefficients (RPC)
• supported data formats
  • RGB(A) data, 8-bit per band
  • Indexed color data, 8-bit index band data (256 colors)
  • Single band data, 32-bit float or 16-bit integer

This model decoder considers single band data, using either 32-bit float or 16-bit signed integer, as raster elevation data.

Raster elevation data using single unsigned 16-bit integers are supported under the following conditions:

• The dataset contains information about the raster unit type to indicate that raster data should be interpreted as elevation data.
• The raster unit type is either "m" for an elevation model in meters, "ft" for feet or "us-ft" for US survey feet.

For more information, please read the related article: Elevation support.

Example usage:

  luciad::expected<std::shared_ptr<Model>, ErrorInfo> modelExpected = GdalModelDecoder::decode(source);
  if (modelExpected.has_value()) {
    auto model = std::dynamic_pointer_cast<IRasterModel>(*modelExpected);
    if (model != nullptr) {
      // ...
    }
  } else {
    ErrorInfo errorInfo = modelExpected.error();
    std::cout << "could not be decoded: " << errorInfo.getMessage();
  }
  std::cout << std::endl;

Note

External overviews in GeoTIFF format:

This model decoder supports external overviews created in GeoTIFF format, i.e. overviews generated in an external .ovr file. Please note that the external overview file must have the same name as the GeoTIFF file, but the extension .ovr appended and it must be in the same folder. For more information on GeoTIFF overviews, please read the gdal documentation.

Feature data

Supported geometries

Geometry Type	Description for geometry in model
Point	Point
Polyline	Polyline
Polygon	Polygon
MultiPoint	MultiGeometry with Point sub-geometries
MultiPolyline	MultiGeometry with Polyline sub-geometries
MultiPolygon	MultiGeometry with Polygon sub-geometries
Point Z	Point
Polyline Z	Polyline
Polygon Z	Polygon
MultiPoint Z	MultiGeometry with Point sub-geometries
MultiPolyline Z	MultiGeometry with Polyline sub-geometries
MultiPolygon Z	MultiGeometry with Polygon sub-geometries

SHP geometry types having measurement values are not supported!

Coordinate reference for SHP files

The ESRI SHP file must have a corresponding .prj file containing the WKT representation of the Coordinate Reference System. If it does not exist this decoder attempts to read the Coordinate Reference System from a .epsg file containing an EPSG code, e.g. EPSG:4326.

Query filtering support

FeatureQuery expression filter can be used to filter the features that have to be loaded in memory. It supports filtering by ID, using a bounding box, and using a condition.

Note that when the condition contains expressions using a spatial bbox operator the filtering cannot be propagated efficiently to GDAL. In this case a best effort is done to translate the condition towards GDAL and a post filtering step in memory is performed.

Use of index files for SHP files

When available the decoder uses the ESRI spatial index files (.sbn / .sbx) or spatial index files (in .qix format). When no spatial index files are available the decoder creates a spatial index file using the .qix format.

When the index file (*.shx) or one of the spatial index files (*.sbx,*.sbn or *.qix) is missing, the decoder creates them at runtime. The index files are stored next to the source data. If the record index file *.shx cannot be written next to the source data (e.g. no write permission) the decoding fails. If the spatial index file *.qix cannot be written next to the source data (e.g. no write permission) the decoding continues but spatial filtering will be slower.

Example usage:

  luciad::expected<std::shared_ptr<Model>, ErrorInfo> modelExpected = GdalModelDecoder::decode(source);
  if (modelExpected.has_value()) {
    auto model = std::dynamic_pointer_cast<IFeatureModel>(*modelExpected);
    if (model != nullptr) {
      // ...
    }
  } else {
    ErrorInfo errorInfo = modelExpected.error();
    std::cout << "could not be decoded: " << errorInfo.getMessage();
  }
  std::cout << std::endl;

Parameters

source

The absolute path to the file.

Returns

either the new model or error information. The possible error codes are :

• FileNotFound: when the file does not exist.
• UnsupportedFeatureError: when a file is decoded that we don't support yet.
• RuntimeError: if an error is encountered while decoding the file.

The error information contains a textual description that gives more information about the issue.