Starting with GDAL 2.0, this driver implements full read/creation/update of tables containing raster tiles in the OGC GeoPackage format standard. The GeoPackage standard uses a SQLite database file as a generic container, and the standard defines:
gpkg_contents,
gpkg_spatial_ref_sys, gpkg_tile_matrix,
gpkg_tile_matrix_set, ...)This driver reads and writes SQLite files from the file system, so it must be run by a user with read/write access to the files it is working with.
The driver can also handle GeoPackage vectors. See GeoPackage vector documentation page
Various kind of input datasets can be converted to GeoPackage raster :
All raster extensions standardized by the GeoPackage specification are supported in read and creation :
By default, the driver will expose a GeoPackage dataset as a four band (Red,Green, Blue,Alpha) dataset, which gives the maximum compatibility with the various encodings of tiles that can be stored. It is possible to specify an explicit number of bands with the BAND_COUNT opening option.
The driver will use the geographic/projected extent indicated in the gpkg_contents table, and do necessary clipping, if needed, to respect that extent. However that information being optional, if omitted, the driver will use the extent provided by the gpkg_tile_matrix_set, which covers the extent at all zoom levels. The user can also specify the USE_TILE_EXTENT=YES open option to use the actual extent of tiles at the maximum zoom level. Or it can specify any of MINX/MINY/MAXX/MAXY to have a custom extent.
The following open options are available:
Depending of the number of bands of the input dataset and the tile format selected, the driver will do the necessary conversions to be compatible with the tile format.
To add several tile tables to a GeoPackage dataset (seen as GDAL subdatasets), or to add a tile table to an existing vector-only GeoPackage, the generic APPEND_SUBDATASET=YES creation option must be provided.
Fully transparent tiles will not be written to the database, as allowed by the format.
The driver implements the Create() and IWriteBlock() methods, so that arbitrary writing of raster blocks is possible, enabling the direct use of GeoPackage as the output dataset of utilities such as gdalwarp.
On creation, raster blocks can be written only if the geotransformation matrix has been set with SetGeoTransform() This is effectively needed to determine the zoom level of the full resolution dataset based on the pixel resolution, dataset and tile dimensions.
Technical/implementation note: when a dataset is opened with a non-default area of interest (i.e. use of MINX,MINY,MAXX,MAXY or USE_TILE_EXTENT open option), or when creating/ opening a dataset with a non-custom tiling scheme, it is possible that GDAL blocks do not exactly match a single GeoPackage tile. In which case, each GDAL block will overlap four GeoPackage tiles. This is easily handled on the read side, but on creation/update side, such configuration could cause numerous decompression/ recompression of tiles to be done, which might cause unnecessary quality loss when using lossy compression (JPEG, WebP). To avoid that, the driver will create a temporary database next to the main GeoPackage file to store partial GeoPackage tiles in a lossless (and uncompressed) way. Once a tile has received data for its four quadrants and for all the bands (or the dataset is closed or explicitly flushed with FlushCache()), those uncompressed tiles are definitely transferred to the GeoPackage file with the appropriate compression. All of this is transparent to the user of GDAL API/utilities
GeoPackage can store tiles in different formats, PNG and/or JPEG for the baseline specification, and WebP for extended GeoPackage. Support for those tile formats depend if the underlying drivers are available in GDAL, which is generally the case for PNG and JPEG, but not necessarily for WebP since it requires GDAL to be compiled against the optional libwebp.
By default, GDAL will use a mix of PNG and JPEG tiles (PNG_JPEG tile format, or AUTO). PNG tiles will be used to store tiles that are not completely opaque, either because input dataset has an alpha channel with non fully opaque content, or because tiles are partial due to clipping at the right or bottom edges of the raster, or when a dataset is opened with a non-default area of interest, or with a non-custom tiling scheme. On the contrary, for fully opaque tiles, JPEG format will be used.
It is possible to select one unique tile format by setting the creation/open option TILE_FORMAT to one of PNG, JPEG or WEBP. When using JPEG, the alpha channel will not be stored. When using WebP, the gpkg_webp extension will be registered. The lossy compression of WebP is used. Note that a recent enough libwebp (>=0.1.4) must be used to support alpha channel in WebP tiles.
PNG8 can be selected to use 8-bit PNG with a color table up to 256 colors. On creation, an optimized color table is computed for each tile. The DITHER option can be set to YES to use Floyd/Steinberg dithering algorithm, which spreads the quantization error on neighbouring pixels for better rendering (note however than when zooming in, this can cause non desirable visual artifacts). Setting it to YES will generally cause less effective compression. Note that at that time, such an 8-bit PNG formulation is only used for fully opaque tiles, as the median-cut algorithm currently implemented to compute the optimal color table does not support alpha channel (even if PNG8 format would potentially allow color table with transparency). So when selecting PNG8, non fully opaque tiles will be stored as 32-bit PNG.
Since GDAL 2.3, tiled gridded coverage data can be stored using PNG unsigned 16bit tiles (with potential offset and scaling so as to be able to represent floating point data) or TIFF 32-bit floating-point LZW compressed tiles.
When converting a GDAL Int16 or UInt16 dataset, PNG tiles will be used. When converting a GDAL Float32 dataset, TIFF tiles will be used by default, unless PNG is explicitly selected, in which case scaling and offsetting will be automatically computed for each tile.
WARNING: the tiled gridded extension initially implemented in GDAL 2.2 was not officially adopted and had been later reworked by OGC. The adopted tiled gridded coverage data has a few differences that will make GDAL 2.2 datasets not be compliant with the final extension. GDAL 2.3 can open those GDAL 2.2-generated files.
By default, conversion to GeoPackage will create a custom tiling scheme, such that the input dataset can be losslessly converted, both at the pixel and georeferencing level (if using a lossless tile format such as PNG). That tiling scheme is such that its origin (min_x, max_y) in the gpkg_tile_matrix_set table perfectly matches the top left corner of the dataset, and the selected resolution (pixel_x_size, pixel_y_size) at the computed maximum zoom_level of the gpkg_tile_matrix table will match the pixel width and height of the raster.
However to ease interoperability with other implementations, and enable use of GeoPackage with tile servicing software, it is possible to select a predefined tiling scheme that has world coverage. The available tiling schemes are :
In all the above tiling schemes, consecutive zoom levels defer by a resolution of a factor of two.
The concept of the nodata value is only supported for tiled gridded elevation datasets. For regular tiled rasters, the alpha band must rather be used.
For Float32 datasets with TIFF tiles, the concepts of nodata in GDAL and null_value in the GeoPackage internals perfectly match.
For Int16, UInt16 or Float32 with PNG tiles, GDAL will generally remap the input nodata value to another value.
On writing, for PNG tiles, the behaviour is the following one:
| GDAL data type | Input GDAL nodata value | null_value in GPKG gpkg_2d_gridded_coverage_ancillary |
| Int16 | Any | 65535 |
| UInt16 | X (if coverage offset == 0 and coverage scale == 1) | X |
| Float32 | Any | 65535 |
On reading, for PNG tiles, the behaviour is the following one:
| GDAL data type | null_value in GPKG gpkg_2d_gridded_coverage_ancillary | Exposed GDAL nodata value |
| Int16 | >= 32768 | -32768 |
| Int16 | X <= 32767 | X |
| UInt16 | X | X |
| Float32 | X | X |
Thus, perfect roundtripping is achieved in the following cases:
| GDAL data type | GDAL nodata value | null_value in GPKG gpkg_2d_gridded_coverage_ancillary |
| Int16 | -32768 | 65535 |
| UInt16 | X (if coverage offset == 0 and coverage scale == 1) | X |
| Float32 | 65535 | 65535 |
The following creation options are available:
gdaladdo / BuildOverviews() can be used to compute overviews. Power-of-two overview factors (2,4,8,16,...) should be favored to be conformant with the baseline GeoPackage specification. Use of other overview factors will work with the GDAL driver, and cause the gpkg_zoom_other extension to be registered, but that could potentially cause interoperability problems with other implementations that do not support that extension.
Overviews can also be cleared with the -clean option of gdaladdo (or BuildOverviews() with nOverviews=0)
GDAL uses the standardized
gpkg_metadata and
gpkg_metadata_reference tables to read and write metadata.
GDAL metadata, from the default metadata domain and possibly other metadata domains, is serialized in a single XML document, conformant with the format used in GDAL PAM (Persistent Auxiliary Metadata) .aux.xml files, and registered with md_scope=dataset and md_standard_uri=http://gdal.org in gpkg_metadata. In gpkg_metadata_reference, this entry is referenced with a reference_scope=table and table_name={name of the raster table}
It is possible to read and write metadata that applies to the global GeoPackage, and not only to the raster table, by using the GEOPACKAGE metadata domain.
Metadata not originating from GDAL can be read by the driver and will be exposed as metadata items with keys of the form GPKG_METADATA_ITEM_XXX and values the content of the metadata columns of the gpkg_metadata table. Update of such metadata is not currently supported through GDAL interfaces ( although it can be through direct SQL commands).
The specific DESCRIPTION and IDENTIFIER metadata item of the default metadata domain can be used in read/write to read from/update the corresponding columns of the gpkg_contents table.
You can set the CREATE_METADATA_TABLES configuration option to NO to avoid creating and filling the metadata tables.
| Extension name | OGC adopted extension ? | Supported by GDAL? |
|---|---|---|
| Zoom Other intervals | Yes | Yes, since GDAL 2.0 |
| Tiles Encoding WebP | Yes | Yes, since GDAL 2.0 |
| Metadata | Yes | Yes, since GDAL 1.11 |
| WKT for Coordinate Reference Systems (WKT v2) | Yes | Partially, since GDAL 2.2. GDAL can read databases using this extension, but cannot interpret a SRS entry that has only a WKT v2 entry. |
| Tiled Gridded Coverage Data | Yes | Yes, since GDAL 2.3 (GDAL 2.2 supported a preliminary version of this extension) |
% gdal_translate -of GPKG byte.tif byte.gpkg
% gdal_translate -of GPKG byte.tif byte.gpkg -co TILE_FORMAT=WEBP
% gdal_translate -of GPKG byte.tif byte.gpkg -co TILING_SCHEME=GoogleMapsCompatible
% gdaladdo -r cubic -oo TILE_FORMAT=JPEG my.gpkg 2 4 8 16 32 64
% gdal_translate -of GPKG new.tif existing.gpkg -co APPEND_SUBDATASET=YES -co RASTER_TABLE=new_table
% gdalwarp -of GPKG in.tif out.gpkg -t_srs EPSG:3857
% gdalinfo my.gpkg -oo TABLE=a_table
Development of raster support in the GeoPackage driver was financially supported by Safe Software.