LuciadCPillar  2020.0.04
luciad::GeoPackageModelDecoder Class Referencefinal

This class is a factory that provides new instances of a luciad::Model. More...

Public Member Functions

 GeoPackageModelDecoder ()=delete
 

Static Public Member Functions

static luciad::expected< std::shared_ptr< Model >, ErrorInfodecode (const std::string &source, const std::string &tableName="")
 Creates a model for a 'Features' or 'Tiles' table in a GeoPackage file. More...
 
static luciad::expected< std::vector< GeoPackageTableMetadata >, ErrorInfodiscoverTables (const std::string &source)
 Discovers the available tables in the given source file. More...
 

Detailed Description

This class is a factory that provides new instances of a luciad::Model.

This specific model can be either a luciad::IFeatureModel or a luciad::IRasterModel giving the ability to access the data within a GeoPackage file.

Constructor & Destructor Documentation

◆ GeoPackageModelDecoder()

luciad::GeoPackageModelDecoder::GeoPackageModelDecoder ( )
delete

Member Function Documentation

◆ decode()

static luciad::expected<std::shared_ptr<Model>, ErrorInfo> luciad::GeoPackageModelDecoder::decode ( const std::string &  source,
const std::string &  tableName = "" 
)
static

Creates a model for a 'Features' or 'Tiles' table in a GeoPackage file.

The GeoPackage decoder is following the GeoPackage specification. To have more information, please follow this link http://www.geopackage.org/spec/. Note that version 1.2 of the specification is supported.

Parameters
sourceThe absolute path to the GeoPackage file. The extension of the file should be '.gpkg'.
tableNameThe name of the table that needs to be decoded. If not specified, the first features table is used.
Returns
either the new created model, either error information. The possible error codes are :
  • FileNotFound: when the file does not exist.
  • UnsupportedFeatureError: when a GeoPackage file decoded that we don't support yet.
  • RuntimeError: in case of an error encountered while decoding the file, or the given table name does not exist.

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

Remarks
The decoder does not support the full specification. The following paragraphs list the restrictions.
One table at a time
A GeoPackage file is a SQLite database file which can contain several tables with different kinds of information such as Features, Attributes and Tiles. The model only supports decoding features tables. If no table name is specified, the first features table is used. If you have more than one features table then they are ignored for now.
Supported type of table
The supported table types are GeoPackageTableMetadata::TableType::Features, GeoPackageTableMetadata::TableType::Tiles and GeoPackageTableMetadata::TableType::GriddedCoverage.
Supported geometries
The basic simple geometry types as defined in the GeoPackage specification as Geometry Type Codes (Core) are all supported. The table below lists all supported geometry types and how their geometry is available in the feature model.
Geometry Type Codes Description for geometry in model
Point Point
LineString Polyline
CircularString CircularArcBy3Points (or a collection of...)
Polygon Polygon
MultiPoint MultiGeometry with Point sub-geometries
MultiLineString MultiGeometry with Polyline sub-geometries
MultiPolygon MultiGeometry with Polygon sub-geometries
GeometryCollection MultiGeometry
Custom geometries extension
On top of the geometries from the GeoPackage specifications a few additional geometries are supported by Luciad.
Custom Geometry Type Codes Description for geometry in model
LcdCircle Patch with CircleByCenterPoint as base geometry
LcdEllipse Patch with Ellipse as base geometry
LcdEllipticalArc EllipticalArc

For curve geometries there is an implicit curve interpolation based on the type of Coordinate Reference System (CRS). When the CRS is a geodetic coordinate reference, e.g. WGS84, the interpolation is geodesic, otherwise the curve interpolation is linear.

Tile Matrix Set limitations.
Only tile matrix sets with a quad-tree structure are supported.
CRS limitations
Decoding of GeoPackage files is limited to coordinates references supported by the luciad::CoordinateReferenceProvider::create
Type conversions
The data model supports a set of basic data types, i.e., Integer, Double and Text. The SQLite data types are converted into data model types in a way that you don't lose information except for the following types INTEGER 6,8 and TEXT UTF-16BE, UTF-16LE.
Elevation & measure
GeoPackage can store feature table geometries with or without optional elevation (Z) and/or measure (M). This feature is not supported by the current model. Support is limited to decoding 2D coordinates.
Extension mechanism support
The current feature model only supports the "gpkg_rtree_index" (embedded rtree spatial indices) GeoPackage extension to generate more efficient SQL spatial queries. Other GeoPackage extensions are not supported or exploited at this stage.
Query filtering support
luciad::FeatureQuery expression filter can be used to order and filter the features that has to be loaded in memory. The filtering is done by the database and only the resulted features are loaded in memory.
Caching
Current implementation of the GeoPackage model does not perform any internal caching to improve performance. It means that all the consecutive queries (even if they are identical) are always executed against the database. It may result in a poor visual performance in some scenarios where the big number of features are constantly queried.
Note
Example usage:
const std::string source = "test/resources/Data/GeoPackage/states10.gpkg";
luciad::expected<std::vector<GeoPackageTableMetadata>, ErrorInfo> tablesExpected = GeoPackageModelDecoder::discoverTables(source);
if (!tablesExpected.has_value()) {
std::cout << "Failed to load GeoPackage file " << source << ": " << tablesExpected.error().getMessage() << std::endl;
return;
}
const std::vector<GeoPackageTableMetadata>& tables = tablesExpected.value();
std::cout << "The GeoPackage file contains " << tables.size() << " table(s):" << std::endl;
for (const GeoPackageTableMetadata& table : tables) {
std::cout << " * Table '" << table.getName() << "' ";
luciad::expected<std::shared_ptr<Model>, ErrorInfo> modelExpected = GeoPackageModelDecoder::decode(source, table.getName());
if (modelExpected.has_value()) {
auto model = std::dynamic_pointer_cast<IFeatureModel>(*modelExpected);
if (model != nullptr) {
uint32_t count = 0;
std::unique_ptr<IFeatureQueryCallback> callback = IFeatureQueryCallback::create([&](const Feature& /*f*/) {
count++;
return true;
});
model->query(FeatureQuery::all(), *callback);
std::cout << "contains " << count << " features.";
}
} else {
ErrorInfo errorInfo = modelExpected.error();
std::cout << "could not be decoded: " << errorInfo.getMessage();
}
} else {
std::cout << "contains raster data.";
}
std::cout << std::endl;
}

◆ discoverTables()

static luciad::expected<std::vector<GeoPackageTableMetadata>, ErrorInfo> luciad::GeoPackageModelDecoder::discoverTables ( const std::string &  source)
static

Discovers the available tables in the given source file.

Parameters
sourceThe absolute path to the GeoPackage file. The extension of the file should be '.gpkg'.
Returns
the available tables, or error information if decoding fails. The possible error codes are:
  • FileNotFound: when the file does not exist.
  • RuntimeError: in case of an error encountered while decoding the file.

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