Package com.luciad.formats.geopackage

Class GeoPackageModelEncoder

java.lang.Object

com.luciad.formats.geopackage.GeoPackageModelEncoder

public final class GeoPackageModelEncoder
extends Object

The GeoPackageModelEncoder allows for exporting existing feature models as well as creating entirely new GeoPackage feature models.

Both can be done to an existing GeoPackage file and to a new file.

Since:

2024.0

Method Summary

Modifier and Type	Method	Description
static IFeatureModel	createEmptyGeoPackageDataSet(String path, GeoPackageFeatureModelCreateOptions options)	Creates a new empty table in the GeoPackage located at the specified path according to the data type specified in the options, and immediately decodes it as a feature model that can be edited.
static void	exportFeatureModel(String path, IFeatureModel model)	Exports the given IFeatureModel to the GeoPackage located at the specified path, using default options.
static void	exportFeatureModel(String path, IFeatureModel model, GeoPackageFeatureModelExportOptions options)	Exports the given IFeatureModel to the GeoPackage located at the specified path.
static String	getCompliantName(String name)	This function adds an underscore at the start if it starts with a digit, and converts all non alphanumeric characters to underscores.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

exportFeatureModel

public static void exportFeatureModel(@NotNull
 String path,
 @NotNull
 IFeatureModel model)
                               throws IOException

Exports the given IFeatureModel to the GeoPackage located at the specified path, using default options.

Parameters:

path - the path of the (new) GeoPackage file.

model - the IFeatureModel to export.

Throws:

IOException - when exporting fails.

exportFeatureModel

public static void exportFeatureModel(@NotNull
 String path,
 @NotNull
 IFeatureModel model,
 @NotNull
 GeoPackageFeatureModelExportOptions options)
                               throws IOException

Exports the given IFeatureModel to the GeoPackage located at the specified path.

File creation and overwriting data

If no file exists, it is created. If an error occurs during exporting, the file is deleted again.

If the file already exists, the new data is added to it. In the case of a name conflict (that is, there already exists a table with the same name), the existing data is only overwritten if the corresponding option is set to true. If overwriting is disabled (default) it results in an error instead and the export is aborted.

If overwriting is enabled, any deleted data isn't recovered in case of failure.

Data types with no features

Each data type with associated features gets exported; no empty feature tables are created when exporting (use createEmptyGeoPackageDataSet instead for that). Attempting to export an empty IFeatureModel, that is, one without any features, results in an error.

Multiple data types

When a single IFeatureModel contains multiple data types, a feature table is created for each. However, keep in mind that when decoding, only a single table is loaded per IFeatureModel.

Name conversions

The data property names must only consist of alphanumeric characters and underscores. Furthermore the first character must not be a digit.

Additionally, the table name must satisfy the same requirements. The table name can be manually specified for each data type using the table name option, otherwise it will be derived by default from the data type itself. In the latter case, if the name does not comply, it is automatically converted as described in GeoPackageModelEncoder#getCompliantName. This function can be used to do the same conversion as is done internally.

If converted names overlap this results in an error.

Coordinate reference

The coordinate reference is inferred from the features contained in the model. All features belonging to a certain data type must have the same reference, the export fails otherwise.

gpkg_geometry_columns settings

The GeoPackage feature tables are made with the least restrictive settings in the gpkg_geometry_columns table: A geometry_type_name of "GEOMETRY" and a z and m of 2 (optional).

Extensions

The rtree index and circularstring extensions are always enabled, these are official extensions that respectively improve performance and allow adding the CircularArcBy3Points geometry. The Luciad circle, ellipse and ellipticalarc extensions are only enabled if the corresponding option is set to true (which is the default).

With these extensions the geopackage accepts the following geometries:

• a Patch containing a CircleByCenterPoint
• a Patch containing a Ellipse
• an EllipticalArc

Supported Geometry types

GeoPackage files only support a subset of the Geometry types present in LuciadCPillar. The following types can be encoded and decoded without loss of semantics, i.e. their geometry type does not change when encoding and then decoding again.

• Point
• Polyline (with a possibly different interpolation type)
• Polygon (with a possibly different interpolation type)
• CircularArcBy3Points
• EllipticalArc
• MultiGeometry
• Ellipse wrapped in a Patch
• CircleByCenterPoint wrapped in a Patch

However, when possible, LuciadCPillar also implicitly converts certain Geometry types to one of the previously listed supported types when this does not affect the overall shape of the Geometry, namely:

Geometry type	Converted to
Line	Polyline
PolylineRing (optionally wrapped in a Patch)	Polygon
CircularArcByBulge	CircularArcBy3Points
CircularArcByCenterPoint	CircularArcBy3Points
CircleBy3Points (optionally wrapped in a Patch)	CircleByCenterPoint wrapped in a Patch
Ellipse not wrapped in a Patch	Ellipse wrapped in a Patch
CircleByCenterPoint not wrapped in a Patch	CircleByCenterPoint wrapped in a Patch

Although the overall shape is preserved, it is therefore possible that certain shapes that originally did not have a filled surface (i.e. they were not wrapped in a Patch) will have a filled surface after encoding and then decoding again. If your IFeaturePainter is not aware of this, the shapes will possibly be styled differently. To opt out of this behavior, simply do not include any of these types in your IFeatureModel.

If any other Geometry types are present in the IFeatureModel, the encoding aborts and an error is returned.

Parameters:

path - the path of the (new) GeoPackage file.

model - the IFeatureModel to export.

options - export options.

Throws:

IOException - when exporting fails.

createEmptyGeoPackageDataSet

@NotNull
public static IFeatureModel createEmptyGeoPackageDataSet(@NotNull
 String path,
 @NotNull
 GeoPackageFeatureModelCreateOptions options)
                                                  throws IOException

Creates a new empty table in the GeoPackage located at the specified path according to the data type specified in the options, and immediately decodes it as a feature model that can be edited.

File creation and overwriting data

If no file exists, it is created. If an error occurs during creation, the file is deleted again.

If the file already exists, a new table is added to it. In the case of a name conflict (that is, there already exists a table with the same name), the existing data is only overwritten if the corresponding option is set to true. If overwriting is disabled (default) it results in an error instead and the creation is aborted.

If overwriting is enabled, any deleted data isn't recovered in case of failure.

Invalid names

The table name and data property names must only consist of alphanumeric characters and underscores. Furthermore the first character must not be a digit.

If a name does not comply with this, encoding fails.

The table name can be manually specified using the table name option, otherwise it will be derived by default from the data type itself.

gpkg_geometry_columns settings

The GeoPackage feature tables are made with the least restrictive settings in the gpkg_geometry_columns table: A geometry_type_name of "GEOMETRY" and a z and m of 2 (optional).

Extensions

The rtree index and circularstring extensions are always enabled, these are official extensions that respectively improve performance and allow adding the CircularArcBy3Points geometry. The Luciad circle, ellipse and ellipticalarc extensions are only enabled if the corresponding option is set to true (which is the default).

With these extensions the geopackage accepts the following geometries:

• a Patch containing a CircleByCenterPoint
• a Patch containing a Ellipse
• an EllipticalArc

Parameters:

path - the path of the (new) GeoPackage file.

options - create options.

Returns:

a decoded IFeatureModel of the new table.

Throws:

IOException - when creation fails.

getCompliantName

@NotNull
public static String getCompliantName(@NotNull
 String name)

This function adds an underscore at the start if it starts with a digit, and converts all non alphanumeric characters to underscores.

Sequences of underscores are reduced to a single underscore.

The names of data types and data properties that do not comply are changed automatically in the case of an export. This function can be used to reliably get the new names based on the old ones.

In the case of createEmptyGeoPackageDataSet, the presence of non-compliant names results in an error.

Parameters:

name - a name (of a data type or a data property).

Returns:

the name after encoding to the GeoPackage.