LuciadCPillar 2023.1.03
Public Member Functions | Static Public Member Functions | List of all members
luciad::GeoPackageModelDecoder Class Referencefinal
luciad » formats » geopackage

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

#include <luciad/formats/geopackage/GeoPackageModelDecoder.h>

Public Member Functions

 GeoPackageModelDecoder ()=delete
 
 ~GeoPackageModelDecoder ()=delete
 

Static Public Member Functions

static luciad::expected< std::shared_ptr< Model >, ErrorInfo > decode (const std::shared_ptr< GeoPackageDataSource > &dataSource)
 Creates a model for a OGC GeoPackage file. More...
 
static luciad::expected< std::shared_ptr< Model >, ErrorInfo > decode (const std::shared_ptr< GeoPackageDataSource > &dataSource, const GeoPackageModelDecoderOptions &options)
 Creates a model for a OGC GeoPackage file. More...
 
static luciad::expected< std::vector< GeoPackageTableMetadata >, ErrorInfo > discoverTables (const std::string &source, bool includeUnsupportedDataTypes)
 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

◆ ~GeoPackageModelDecoder()

luciad::GeoPackageModelDecoder::~GeoPackageModelDecoder ( )
delete

Member Function Documentation

◆ decode() [1/2]

static luciad::expected< std::shared_ptr< Model >, ErrorInfo > luciad::GeoPackageModelDecoder::decode ( const std::shared_ptr< GeoPackageDataSource > &  dataSource)
static

Creates a model for a OGC GeoPackage file.

Parameters
dataSourceThe data source description to use for data retrieval.
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.

◆ decode() [2/2]

static luciad::expected< std::shared_ptr< Model >, ErrorInfo > luciad::GeoPackageModelDecoder::decode ( const std::shared_ptr< GeoPackageDataSource > &  dataSource,
const GeoPackageModelDecoderOptions &  options 
)
static

Creates a model for a OGC GeoPackage file.

Supported versions

The GeoPackage decoder allows decoding files following the OGC GeoPackage specification.

  • OGC GeoPackage files, compliant with version 1.0.1 of the OGC GeoPackage specification.
  • OGC GeoPackage files, compliant with version 1.1.0 of the OGC GeoPackage specification.
  • OGC GeoPackage files, compliant with version 1.2.1 of the OGC GeoPackage specification.
  • OGC GeoPackage files, compliant with version 1.3.0 of the OGC GeoPackage specification.

Supported tables

The supported table types are

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 supports decoding features and raster data (tiles table). If no table name is specified the first table of one of the supported table types is used.

Use the method GeoPackageModelDecoder::discoverTables to retrieve the list of tables within the GeoPackage file.

Feature data

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.

Remarks
The decoder does not support the full specification. The following paragraphs list the restrictions.
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). Support is limited to decoding 2D/3D coordinates, the measure (M) value is not supported and is skipped.
Extension mechanism support
The feature model 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
A 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.
Editing
The feature model can be made editable using the GeoPackageModelDecoderOptions. The decoded model's IFeatureModel::getUpdater method will then return an IFeatureModelUpdater which can be used to modify the model. Changes to the model are not automatically persisted into the gpkg file, persisting is done using the FeatureModelPersistenceManager, accessed using IFeatureModel::getPersistenceManager.
Editing limitations
Editing currently does not change the GeoPackage's metadata, only the feature's table itself (and the related RTree tables if present). Features that would violate the constraints of the GeoPackage can't be added. Specifically:
  • Features holding a geometry that require a missing extension can't be added.
  • If the measure value is defined as mandatory by the GeoPackage file, features can't be added. This is also true for updates that don't affect the geometry. Removing features is still possible in this case.
  • If the GeoPackage file's 'geometry_type_name' restricts allowed geometry types, features holding a geometry of a disallowed type can't be added.

Raster data

Image data

The following tile formats are supported:

  • PNG
  • JPEG
Elevation data

A sub-set of the Tiled Gridded Coverage Data, version 1.0, extension is supported to read elevation data.

The following elevation data formats are supported:

  • PNG
  • TIFF
Tile Matrix Set limitations.
Only tile matrix sets with a quad-tree structure are supported.

Coordinate references

Decoding of GeoPackage files is limited to coordinate references supported by the CoordinateReferenceProvider::create method.

Example usage:

const std::string source = "test/resources/Data/GeoPackage/states10.gpkg";
luciad::expected<std::vector<GeoPackageTableMetadata>, ErrorInfo> tablesExpected = GeoPackageModelDecoder::discoverTables(source, false);
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() << "' ";
if (table.getType() == GeoPackageTableMetadata::typeFeatures()) {
std::shared_ptr<GeoPackageDataSource> datasource = GeoPackageDataSource::newBuilder().source(source).tableName(table.getName()).build();
luciad::expected<std::shared_ptr<Model>, ErrorInfo> modelExpected = GeoPackageModelDecoder::decode(datasource);
if (modelExpected.has_value()) {
auto model = std::dynamic_pointer_cast<IFeatureModel>(*modelExpected);
if (model != nullptr) {
uint32_t count = 0;
auto 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;
}
luciad::ErrorInfo
This class exposes details for a failed method call.
Definition: ErrorInfo.h:33
luciad::Feature
A Feature is a (partial) copy of a domain object.
Definition: Feature.h:34
luciad::FeatureQuery::all
static FeatureQuery all()
This method is a convenience factory method that creates a query to retrieve all features.
luciad::GeoPackageDataSource::Builder::build
std::shared_ptr< GeoPackageDataSource > build()
Build the GeoPackage data source .
luciad::GeoPackageDataSource::Builder::tableName
Builder & tableName(std::string tableName)
Sets the name of the table that needs to be decoded.
luciad::GeoPackageDataSource::Builder::source
Builder & source(std::string source)
Sets the absolute path to the GeoPackage file.
luciad::GeoPackageDataSource::newBuilder
static Builder newBuilder()
Returns the builder class for creation of the GeoPackage data source.
luciad::GeoPackageModelDecoder::discoverTables
static luciad::expected< std::vector< GeoPackageTableMetadata >, ErrorInfo > discoverTables(const std::string &source, bool includeUnsupportedDataTypes)
Discovers the available tables in the given source file.
luciad::GeoPackageModelDecoder::decode
static luciad::expected< std::shared_ptr< Model >, ErrorInfo > decode(const std::shared_ptr< GeoPackageDataSource > &dataSource, const GeoPackageModelDecoderOptions &options)
Creates a model for a OGC GeoPackage file.
luciad::GeoPackageTableMetadata
Provides information about a GeoPackage table.
Definition: GeoPackageTableMetadata.h:11
luciad::GeoPackageTableMetadata::typeFeatures
static const std::string & typeFeatures()
Type identifier for features.
luciad::IFeatureQueryCallback::create
static std::shared_ptr< IFeatureQueryCallback > create(std::function< bool(Feature)> function)
Creates a default IFeatureQueryCallback instance that delegates the IFeatureQueryCallback::handleFeat...
Parameters
dataSourceThe data source description to use for data retrieval.
optionsOptions for decoding GeoPackage data, e.g. an option to make a feature model editable.
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.

◆ discoverTables()

static luciad::expected< std::vector< GeoPackageTableMetadata >, ErrorInfo > luciad::GeoPackageModelDecoder::discoverTables ( const std::string &  source,
bool  includeUnsupportedDataTypes 
)
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'.
includeUnsupportedDataTypesWhether to include unsupported data types.
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.