Meziantou.Framework

GeoPackage Class

Namespace
Meziantou.Framework.Geo
Assembly
Meziantou.Framework.Geo.GeoPackage.dll
Package
Meziantou.Framework.Geo.GeoPackage 1.0.0
Source
GeoPackage.cs
Available in package assets
net10.0net11.0

Reads the feature tables of GeoPackage files (OGC GeoPackage 1.0 to 1.4): SQLite databases that GDAL, QGIS and ArcGIS write, with one table of features per layer and an optional R-tree spatial index.

public static class GeoPackage

Remarks

The geometries are the standard GeoPackage geometries: a header, then the WKB of the geometry, read as WellKnownBinary reads it, with the altitudes (Z) and the measures (M). An empty geometry and a null one give a feature without geometry; the extended geometries of extensions throw a FormatException. The coordinate system of the table is not read: the coordinates are expected to be longitudes and latitudes (EPSG:4326, the coordinate system of most files), and are not converted otherwise.

The identifier of a feature is the text of the primary key of the table, such as fid. The other columns are the properties, with the type their declared type gives: a Boolean for BOOLEAN, an SByte for TINYINT, a Int16 for SMALLINT, an Int32 for MEDIUMINT, a Int64 for INTEGER and INT, a Single for FLOAT, a Double for DOUBLE and REAL, a String for TEXT, a DateOnly for DATE and a DateTimeOffset for DATETIME (the text when they cannot be parsed) and an array of bytes for BLOB. A NULL value is not a property.

Reading a file needs the native SQLite library of Microsoft.Data.Sqlite, with its R-tree module to read a box.

Methods

NameDescription
GetTables(SqliteConnection)Gets the names of the feature tables of an open GeoPackage database.
GetTables(string)Gets the names of the feature tables of a GeoPackage file: the layers of the file, in the order of gpkg_contents.
Read(SqliteConnection, string?, GeoPackageReaderOptions?)Reads the features of a table of an open GeoPackage database.
Read(string, string?, GeoPackageReaderOptions?)Reads the features of a table of a GeoPackage file.
ReadFeaturesAsync(SqliteConnection, string?, GeoPackageReaderOptions?, CancellationToken)Reads the features of a table of an open GeoPackage database one at a time, with bounded memory: the rows are read as the features are enumerated, and only the row being read is kept in memory.
ReadFeaturesAsync(string, string?, GeoPackageReaderOptions?, CancellationToken)Reads the features of a table of a GeoPackage file one at a time, with bounded memory: the rows are read as the features are enumerated, and only the row being read is kept in memory.

GetTables overloads

GetTables(SqliteConnection)

GeoPackage.cs

Gets the names of the feature tables of an open GeoPackage database.

public static IReadOnlyList<string> GetTables(SqliteConnection connection)
Parameters
connection SqliteConnection
The open connection to the database.
Returns

IReadOnlyList<string> The names of the tables.

Exceptions
FormatException
The database is not a GeoPackage.

GetTables(string)

GeoPackage.cs

Gets the names of the feature tables of a GeoPackage file: the layers of the file, in the order of gpkg_contents.

public static IReadOnlyList<string> GetTables(string path)
Parameters
path string
The path of the file.
Returns

IReadOnlyList<string> The names of the tables.

Exceptions
FormatException
The file is not a GeoPackage.

Read overloads

Read(SqliteConnection, string?, GeoPackageReaderOptions?)

GeoPackage.cs

Reads the features of a table of an open GeoPackage database.

public static GeoFeatureCollection Read(SqliteConnection connection, string? tableName = null, GeoPackageReaderOptions? options = null)
Parameters
connection SqliteConnection
The open connection to the database.
tableName string?
The name of the feature table, or null when the database has a single one.
options GeoPackageReaderOptions?
The options, or null for the defaults.
Returns

GeoFeatureCollection The features, in the order of the primary key, in a collection named after the table.

Exceptions
ArgumentException
The database has no feature table named tableName.
FormatException
The database is not a GeoPackage, has no feature table, or several ones and no tableName, or a geometry is not valid.

Read(string, string?, GeoPackageReaderOptions?)

GeoPackage.cs

Reads the features of a table of a GeoPackage file.

public static GeoFeatureCollection Read(string path, string? tableName = null, GeoPackageReaderOptions? options = null)
Parameters
path string
The path of the file.
tableName string?
The name of the feature table, or null when the file has a single one.
options GeoPackageReaderOptions?
The options, or null for the defaults.
Returns

GeoFeatureCollection The features, in the order of the primary key, in a collection named after the table.

Exceptions
ArgumentException
The file has no feature table named tableName.
FormatException
The file is not a GeoPackage, has no feature table, or several ones and no tableName, or a geometry is not valid.

ReadFeaturesAsync overloads

ReadFeaturesAsync(SqliteConnection, string?, GeoPackageReaderOptions?, CancellationToken)

GeoPackage.cs

Reads the features of a table of an open GeoPackage database one at a time, with bounded memory: the rows are read as the features are enumerated, and only the row being read is kept in memory.

public static IAsyncEnumerable<GeoFeature> ReadFeaturesAsync(SqliteConnection connection, string? tableName = null, GeoPackageReaderOptions? options = null, CancellationToken cancellationToken = default)
Parameters
connection SqliteConnection
The open connection to the database. It is used until the enumeration ends.
tableName string?
The name of the feature table, or null when the database has a single one.
options GeoPackageReaderOptions?
The options, or null for the defaults.
cancellationToken CancellationToken
The token to cancel the reading.
Returns

IAsyncEnumerable<GeoFeature> The features, in the order of the primary key.

Exceptions
ArgumentException
The database has no feature table named tableName.
FormatException
The database is not a GeoPackage, has no feature table, or several ones and no tableName, or a geometry is not valid. The features read before the error are returned first.

ReadFeaturesAsync(string, string?, GeoPackageReaderOptions?, CancellationToken)

GeoPackage.cs

Reads the features of a table of a GeoPackage file one at a time, with bounded memory: the rows are read as the features are enumerated, and only the row being read is kept in memory.

public static IAsyncEnumerable<GeoFeature> ReadFeaturesAsync(string path, string? tableName = null, GeoPackageReaderOptions? options = null, CancellationToken cancellationToken = default)
Parameters
path string
The path of the file.
tableName string?
The name of the feature table, or null when the file has a single one.
options GeoPackageReaderOptions?
The options, or null for the defaults.
cancellationToken CancellationToken
The token to cancel the reading.
Returns

IAsyncEnumerable<GeoFeature> The features, in the order of the primary key. The file is opened when the enumeration starts, and closed when it ends.

Exceptions
ArgumentException
The file has no feature table named tableName.
FormatException
The file is not a GeoPackage, has no feature table, or several ones and no tableName, or a geometry is not valid. The features read before the error are returned first.