luciad::GeoPackageModelDecoder Class Reference

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

dataSource

The 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.

• https://www.ogc.org/standards/geopackage
• https://www.geopackage.org/

• 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

• GeoPackageTableMetadata::typeFeatures
• GeoPackageTableMetadata::typeTiles
• GeoPackageTableMetadata::type2dGriddedCoverage

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

The 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 returns 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.

Editing and model bounds

When removing features from the feature model and querying the bounds before persisting, the bounds can potentially be larger than a tight fit. After persisting the bounds will be calculated again without the removed features being taken into account, resulting in a tight fit of the bounds.

Id conflicts

If there are any id conflicts between the in-memory data and the GeoPackage file itself, the conflicting in-memory features get new ids assigned to them when the changes are persisted. The observers are notified of these changes.

One way conflicts can happen is if features which already have an id are added to the model; for performance reasons the uniqueness of the id is only checked against the in-memory features, not against those in the GeoPackage file. Until the conflict is resolved by persisting the changes, the shadowed features in the GeoPackage file are not visible (i.e. they don't appear in query results).

Raster data

Image data

The following tile formats are supported:

• PNG
• JPEG
• WebP

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;
  }

Parameters

dataSource	The data source description to use for data retrieval.
options	Options 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

source	The absolute path to the GeoPackage file. The extension of the file should be '.gpkg'.
includeUnsupportedDataTypes	Whether 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.