Package com.luciad.formats.geopackage

Class GeoPackageModelDecoder

java.lang.Object
com.luciad.formats.geopackage.GeoPackageModelDecoder
public final class GeoPackageModelDecoder extends Object
This class is a factory that provides new instances of a Model.

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

  • Method Details

    • discoverTables

      @NotNull public static List<GeoPackageTableMetadata> discoverTables(@NotNull String source, boolean includeUnsupportedDataTypes) throws IOException
      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 discovered tables.
      Throws:
      IOException - when discovering the tables fails.

    • decode

      @NotNull public static Model decode(@NotNull GeoPackageDataSource dataSource) throws IOException
      Creates a model for a OGC GeoPackage file.
      Parameters:
      dataSource - The data source description to use for data retrieval.
      Returns:
      the decoded model for the GeoPackage table.
      Throws:
      IOException - when decoding the GeoPackage file fails.

    • decode

      @NotNull public static Model decode(@NotNull GeoPackageDataSource dataSource, @NotNull GeoPackageModelDecoderOptions options) throws IOException
      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 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.
      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 wich 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:

          String source = "test/resources/Data/GeoPackage/states10.gpkg";
    try {
      List<GeoPackageTableMetadata> tables = GeoPackageModelDecoder.discoverTables(source, false);
      Log.i("gpkg", "The GeoPackage file contains " + tables.size() + " table(s):");

      for (GeoPackageTableMetadata table : tables) {
        Log.i("gpkg", " * Table '" + table.getName() + "' ");
        if (GeoPackageTableMetadata.TypeFeatures.equals(table.getType())) {
          GeoPackageDataSource datasource = GeoPackageDataSource.newBuilder()
                                                                .source(source)
                                                                .tableName(table.getName())
                                                                .build();
          try {
            Model model = GeoPackageModelDecoder.decode(datasource);
            if (model instanceof IFeatureModel) {
              IFeatureModel featureModel = (IFeatureModel) model;
              AtomicLong count = new AtomicLong(0);
              IFeatureQueryCallback callback = feature -> {
                count.incrementAndGet();
                return true;
              };
              featureModel.query(FeatureQuery.all(), callback);
              Log.i("gpkg", "contains " + count + " features.");
            }
          } catch (Exception e) {
            Log.w("gpkg", "could not be decoded: " + e.getMessage());
          }
        } else {
          Log.i("gpkg", "contains raster data.");
        }
      }
    } catch (Exception e) {
      Log.w("gpkg", "Failed to load GeoPackage file " + source + ": " + e.getMessage());
    }
      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:
      the decoded model for the GeoPackage table.
      Throws:
      IOException - when decoding the GeoPackage file fails.