com.luciad.format.sqlite.geopackage

LuciadLightspeedClass TLcdGeoPackageModelDecoder

java.lang.Object

com.luciad.format.sqlite.geopackage.TLcdGeoPackageModelDecoder

All Implemented Interfaces:

ILcdDataSourceModelDecoder , ILcdModelDecoder

@LcdService(service=ILcdModelDecoder.class,
            priority=20000)
public class TLcdGeoPackageModelDecoder
extends Object
implements ILcdModelDecoder, 
ILcdDataSourceModelDecoder

A model decoder that decodes OGC GeoPackage files.

Input Files

File	Required	Entry point	Description
*.gpkg	X	X	The database file

Supported file transfer protocols

• This model decoder supports all transfer protocols that are supported by java.io.File.

Model structure

• If there is only one dataset, the model is a TLcdDatabaseModel for vector data and ILcdModel for raster and elevation data.
• If there are multiple datasets, returns an ILcdModelTreeNode that contains a model for each dataset as described above.

Model descriptor

• All models returned by this model decoder have a TLcdGeoPackageModelDescriptor.
  • Model descriptors for tile (raster) datasets also implement the ILcdEarthModelDescriptor interface.
  • Model descriptors for tile (elevation) datasets also implement the ILcdImageModelDescriptor interface.
  • Model descriptors for feature (vector) datasets also implements the ILcdDatabaseModelDescriptor interface. This exposes a data model with one data type. Each non-geometry column of the GeoPackage table is available as a property on the data type. The GeoPackage data type of the column is mapped on the corresponding Java type.

Model reference

• All models returned by this model decoder have a com.luciad.reference.ILcdGridReference or com.luciad.reference.ILcdGeodeticReference.

Model elements

• Feature (vector) data:
  • GeoPackage geometry objects are mapped to ILcdShape objects:

    FROM GeoPackage geometry	TO ILcdShape
    POINT	ILcdShapeList with a single ILcdPoint object
    LINESTRING	ILcdShapeList with a single ILcdPolyline object
    POLYGON	ILcdShapeList with a single ILcdComplexPolygon object
    CIRCULARARCSTRING	ILcdShapeList with a single ILcd2DEditableCircularArcBy3Points object
    LCDELLIPTICALARC	ILcdShapeList with a single ILcd2DEditableArc object
    LCDCIRCLE	ILcdShapeList with a single ILcd2DEditableCircle object
    LCDELLIPSE	ILcdShapeList with a single ILcd2DEditableEllipse object
    MULTIPOINT	ILcdShapeList with a single ILcdPolypoint object
    MULTILINESTRING	ILcdShapeList with a single ILcdShapeList with ILcdPolyline objects
    MULTIPOLYGON	ILcdShapeList with a single ILcdShapeList with ILcdComplexPolygon objects
    GEOMETRYCOLLECTION	ILcdShapeList with objects from this table (also recursive)

  • Elements also implement ILcdDataObject with the data type described above.
  • See also setMaxCacheSize(int) to learn how caching can affect performance.
  • Other geometry types, for example MULTISURFACE and CURVEPOLYGON, are not supported.
  LCDELLIPTICALARC, LCDCIRCLE, LCDELLIPSE are geometry types that are added as extensions to GeoPackage. These extensions allow you to store the corresponding shape in a GeoPackage. GeoPackage files containing these geometry types can only be opened with Luciad software products.
• Tile (raster) data:
  • Each decoded model contains a single implementation of ALcdImage and ILcdEarthTileSet. The tiling structure of this tile set matches the tile matrix set defined by the OGC GeoPackage dataset.
• Tile (elevation) data:
  • Each decoded model contains a single implementation of ALcdMultilevelImageMosaic. The tiling structure of this tile set matches the tile matrix set defined by the OGC GeoPackage dataset.
  • The sampling modes are mapped on ELcdImageSamplingMode according to the following table.

    Grid Cell Encoding	Sampling Mode
    grid-value-is-center	AREA
    grid-value-is-area	AREA
    grid-value-is-corner	POINT

  grid-value-is-center actually has no matching sample mode, so AREA is used

Updating the model

• Updating the model is only possible for feature (vector) data.
• Changes (ILcdModel.addElement(java.lang.Object, int), ILcdModel.removeElement(java.lang.Object, int), ILcdModel.elementChanged(java.lang.Object, int) etc.) are only applied in-memory, they are not automatically saved in the database.
• Use TLcdDatabaseModel.commit() to make the changes persistent.

Thread safety

• Use TLcdLockUtil.readLock(Object) when accessing elements in the model.
• Use TLcdLockUtil.writeLock(Object) when changing elements in the model.

Sample code

Decoding GeoPackage data and visualizing it on a Lightspeed map:

    //First create the model
    ILcdModelDecoder decoder =
        new TLcdCompositeModelDecoder(TLcdServiceLoader.getInstance(ILcdModelDecoder.class));
    ILcdModel model = decoder.decode("Data/GeoPackage/states.gpkg");

    //Create a layer for the model
    ILspLayer layer = createGeoPackageLayer(model);

    //Add the layer to the Lightspeed view (an ILspView)
    view.addLayer(layer);

Decoding GeoPackage data and visualizing it on a GXY map:

    //First create the model
    ILcdModelDecoder decoder =
        new TLcdCompositeModelDecoder(TLcdServiceLoader.getInstance(ILcdModelDecoder.class));
    ILcdModel model = decoder.decode("Data/GeoPackage/states.gpkg");

    //Create a layer for the model with default styling
    ILcdGXYLayer layer = createGXYGeoPackageLayer(model);
    //Wrap the layer with an async layer wrapper to ensure
    //that the view remains responsive while data is being painted
    layer = ILcdGXYAsynchronousLayerWrapper.create(layer);

    //Add the async layer to the GXY view (an ILcdGXYView)
    view.addGXYLayer(layer);

Supported versions

• OGC GeoPackage files, compliant with version 1.0.1 of the OGC GeoPackage specification.
• OGC GeoPackage files, compliant with version 1.1 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.

These files have a .gpkg extension.

Since:

2013.1

Field Summary

Fields

Modifier and Type	Field and Description
static String	FEATURES_TYPE_NAME Type name constant for GeoPackage models containing feature data.
static String	TILES_TYPE_NAME Type name constant for GeoPackage models containing tiled raster (RGBA) data.

Constructor Summary

Constructors

Constructor and Description
TLcdGeoPackageModelDecoder() Creates a new GeoPackage model decoder.

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeSource(ILcdDataSource aDataSource) Checks whether the given data source can be decoded with this model decoder.
boolean	canDecodeSource(String aSource) Checks whether the given source can be decoded with this model decoder.
ILcdModel	decode(String aSource) Decodes all data sets in a GeoPackage file.
ILcdModel	decodeSource(ILcdDataSource aDataSource) Creates a model for the given data source.
List<TLcdGeoPackageDataSource>	discoverDataSources(String aPath) This interface method delegates its work to getDataSources(String).
List<TLcdGeoPackageDataSource>	getDataSources(String aSource) Returns all possible data sources in the given GeoPackage file.
String	getDisplayName() Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
int	getMaxCacheSize() Returns the maximum number of features (domain objects) that decoded models can store using hard references.
void	setMaxCacheSize(int aMaxCacheSize) Sets the maximum number of features (domain objects) that decoded models can store using hard references.

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.luciad.model.ILcdModelDecoder

decodeModelMetadata, decodeModelMetadata

Field Detail

FEATURES_TYPE_NAME

public static final String FEATURES_TYPE_NAME

Type name constant for GeoPackage models containing feature data.

See Also:

Constant Field Values

TILES_TYPE_NAME

public static final String TILES_TYPE_NAME

Type name constant for GeoPackage models containing tiled raster (RGBA) data.

See Also:

Constant Field Values

Constructor Detail

TLcdGeoPackageModelDecoder

public TLcdGeoPackageModelDecoder()

Creates a new GeoPackage model decoder.

Method Detail

setMaxCacheSize

public void setMaxCacheSize(int aMaxCacheSize)

Sets the maximum number of features (domain objects) that decoded models can store using hard references.

Each individual decoded model (or sub-model when there are multiple datasets in the source) can store this many domain objects. More objects can be stored using soft references.

The default value is 300.

Strategies: caching affects mainly spatial query performance.

1. aMaxCacheSize > 0: two queries are performed: one to determine overlapping object IDs, one to retrieve the geometry and properties of each object that is not yet in cache. This maximally reduces the amount of geometries and features that have to be read from file.
2. aMaxCacheSize == 0: all overlapping objects (geometries and properties) are read from file in one query. This maximally reduces the number of queries that have to be made to the database, which is useful if the round-trip time is high.
3. If all the elements of the database model fit in memory, you can create a new local model and copy all database model elements over. This results in a single large query upfront, and the database model can then be disposed.

Parameters:

aMaxCacheSize - the max number of objects cached with hard references.

getMaxCacheSize

public int getMaxCacheSize()

Returns the maximum number of features (domain objects) that decoded models can store using hard references.

The default value is 300.

Returns:

the maximum number of objects that will be stored using hard references.

See Also:

setMaxCacheSize for more information

getDisplayName

public String getDisplayName()

Description copied from interface: ILcdModelDecoder

Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.

Specified by:

getDisplayName in interface ILcdModelDecoder

Returns:

the displayable name of this ILcdModelDecoder.

canDecodeSource

public boolean canDecodeSource(ILcdDataSource aDataSource)

Checks whether the given data source can be decoded with this model decoder.

This model decoder handles TLcdGeoPackageDataSource data sources and TLcdDataSource data sourcees. The latter case delegates the source to the canDecodeSource(String) method.

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aDataSource - the dataset to be decoded.

Returns:

true if the data source is a TLcdGeoPackageDataSource or a TLcdDataSource, false otherwise

See Also:

decodeSource(com.luciad.model.ILcdDataSource)

decodeSource

public ILcdModel decodeSource(ILcdDataSource aDataSource)
                       throws IOException

Creates a model for the given data source.

The data source must be a TLcdGeoPackageDataSource, which represents one data set in the GeoPackage file.

Specified by:

decodeSource in interface ILcdModelDecoder

Parameters:

aDataSource - the dataset to be decoded.

Returns:

A model with the structure described in the class javadoc

Throws:

IOException - if the dataset cannot be loaded.

See Also:

canDecodeSource(com.luciad.model.ILcdDataSource)

canDecodeSource

public boolean canDecodeSource(String aSource)

Checks whether the given source can be decoded with this model decoder.

This model decoder handles only .gpkg files.

Specified by:

canDecodeSource in interface ILcdModelDecoder

Parameters:

aSource - the data source to be verified; typically a file name or a URL.

Returns:

true if the source has .gpkg extension.

See Also:

decode(String)

decode

public ILcdModel decode(String aSource)
                 throws IOException

Decodes all data sets in a GeoPackage file.

• If there is only one dataset, returns a model structured as described in the class javadoc
• If there are multiple datasets, returns a TLcdModelTreeNode that contains a model for each dataset.

Specified by:

decode in interface ILcdModelDecoder

Parameters:

aSource - the GeoPackage file to be decoded.

Returns:

A model with the structure described above

Throws:

IOException - if the file cannot be loaded.

See Also:

canDecodeSource(String)

getDataSources

public List<TLcdGeoPackageDataSource> getDataSources(String aSource)
                                              throws IOException

Returns all possible data sources in the given GeoPackage file.

Each data source corresponds to a single dataset in the file.

You can use decodeSource(com.luciad.model.ILcdDataSource) to create a model for an individual data source.

Parameters:

aSource - The GeoPackage file

Returns:

The datasets in the file

Throws:

IOException - if the file cannot be read

See Also:

decodeSource(com.luciad.model.ILcdDataSource)

discoverDataSources

public List<TLcdGeoPackageDataSource> discoverDataSources(String aPath)
                                                   throws IOException

This interface method delegates its work to getDataSources(String). It is identical in behavior an exists only to be compatible with the ILcdModelDecoder.discoverDataSources(String) interface method.

Returns all possible data sources in the given GeoPackage file.

Each data source corresponds to a single dataset in the file.

You can use decodeSource(com.luciad.model.ILcdDataSource) to create a model for an individual data source.

Specified by:

discoverDataSources in interface ILcdModelDecoder

Parameters:

aPath - A path to the data source to be decoded; typically a file name or a URL.

Returns:

A list of datasets in the given file.

Throws:

IOException - if the file cannot be read