The Tiles option specifies a mechanism for storing raster data in tile pyramids. "Tile pyramid" refers to the concept of pyramid structure of tiles of different spatial extent and resolution at different zoom levels, and the tile data itself. "Tile" refers to an individual raster image such as a PNG or JPEG that covers a specific geographic area. "Tile matrix" refers to rows and columns of tiles that all have the same spatial extent and resolution at a particular zoom level[K14] "Tile matrix set" refers to the definition of a tile pyramid’s tiling structure. This mechanism is based on the model for tile matrix sets described in Section 6 of [I16].
The GeoPackage tile store data model MAY be implemented directly as SQL tables in a SQLite database for maximum performance, or as SQL views on top of tables in an existing SQLite tile store for maximum adaptability and loose coupling to enable widespread implementation. A GeoPackage CAN store multiple raster and tile pyramid data sets in different tables or views in the same container. The tables or views that implement the GeoPackage tile store data / metadata model are described and discussed individually in the following subsections.
The tile store data / metadata model and conventions described below support direct use of tiles in a GeoPackage in two ways. First, they specify how existing application MAY create SQL Views of the data / metadata model on top of existing application tables that that follow different interface conventions. Second, they include and expose enough metadata information at both the dataset and record level to allow applications that use GeoPackage data to discover its characteristics without having to parse all of the stored images. Applications that store GeoPackage tile data, which are presumed to have this information available, should store sufficient metadata to enable its intended use.
In a GeoPackage, zoom levels are integers in sequence from 0 to n that identify tile matrix layers in a tile matrix set that contain tiles of decreasing spatial extent and finer spatial resolution. Adjacent zoom levels immediately precede or follow each other and differ by a value of 1. Pixel sizes are real numbers in the terrain units of the spatial reference system of a tile image specifying the dimensions of the real world area represented by one pixel. Pixel size MAY vary by a constant factor or by different factors or intervals between some or all adjacent zoom levels in a tile matrix set. In the commonly used "zoom times two" convention, pixel sizes vary by a factor of 2 between all adjacent zoom levels, as shown in the example in [tiles_example_appendix]. Other "zoom other intervals" conventions use different factors or irregular intervals with pixel sizes chosen for intuitive cartographic representation of raster data, or to coincide with the original pixel size of commonly used global image products. See Web Map Tile Service (WMTS) [I16] Annex E for additional examples of both conventions.
In a GeoPackage that contains a tile pyramid user data table that contains tile data, by default [K15], zoom level pixel sizes for that table SHALL vary by a factor of 2 between adjacent zoom levels in the tile matrix metadata table.
|
Note
|
Requirements 36 and 37 in combination allow a tile pyramid user data table to contain PNG or JPG tiles. They may be mixed and matched within the same table. |
The gpkg_tile_matrix_set table defines the spatial reference system (srs_id) and the maximum bounding box (min_x, min_y, max_x, max_y) for all possible tiles in a tile pyramid user data table.
A GeoPackage that contains a tile pyramid user data table SHALL contain gpkg_tile_matrix_set table per Table Definition, Table 1 and [gpkg_tile_matrix_set_sql].
| Column Name | Column Type | Column Description | Null | Default | Key |
|---|---|---|---|---|---|
|
TEXT |
Tile Pyramid User Data Table Name |
no |
PK, FK |
|
|
INTEGER |
Spatial Reference System ID: gpkg_spatial_ref_sys.srs_id |
no |
FK |
|
|
DOUBLE |
Bounding box minimum easting or longitude for the tile matrix set |
no |
||
|
DOUBLE |
Bounding box minimum northing or latitude for the tile matrix set |
no |
||
|
DOUBLE |
Bounding box maximum easting or longitude for the tile matrix set |
no |
||
|
DOUBLE |
Bounding box maximum northing or latitude for the tile matrix set |
no |
The bounding box defined by min_x, max_x, min_y, and max_y SHALL be exact so that the bounding box coordinates for individual tiles in a tile pyramid MAY be calculated from those values. All tiles present in the tile pyramid SHALL fall within this bounding box.
Since GeoPackages use the upper left tile origin convention defined in clause Table Data Values below, the gpkg_tile_matrix_set (min_x, max_y) ordinate is the upper-left corner of tile (0,0) for all zoom levels in a table_name tile pyramid user data table.
A bounding box MAY be larger than the minimum bounding rectangle around the actual tiles in that pyramid. This allows tile matrix pyramids to be sparsely populated or even empty.
Values of the gpkg_tile_matrix_set table_name column SHALL reference values in the gpkg_contents table_name column for rows with a data type of "tiles"[K18].
The gpkg_tile_matrix_set table SHALL contain one row record for each tile pyramid user data table.
Values of the gpkg_tile_matrix_set srs_id column SHALL reference values in the gpkg_spatial_ref_sys srs_id column.
The srs_id value in a gpkg_tile_matrix_set table row SHALL match the srs_id column value from the corresponding row in the gpkg_contents table.
A GeoPackage that contains a tile pyramid user data table SHALL contain a gpkg_tile_matrix table per clause 2.2.7.1.1 Table Definition, Table Table 2 and Table [gpkg_tile_matrix_sql].
| Column Name | Column Type | Column Description | Null | Key |
|---|---|---|---|---|
|
TEXT |
Tile Pyramid User Data Table Name |
no |
PK, FK |
|
INTEGER |
0 <= |
no |
PK |
|
INTEGER |
Number of columns (>= 1) in tile matrix at this zoom level |
no |
|
|
INTEGER |
Number of rows (>= 1) in tile matrix at this zoom level |
no |
|
|
INTEGER |
Tile width in pixels (>= 1)for this zoom level |
no |
|
|
INTEGER |
Tile height in pixels (>= 1) for this zoom level |
no |
|
|
DOUBLE |
In |
no |
|
|
DOUBLE |
In |
no |
The gpkg_tile_matrix table documents the structure of the tile matrix at each zoom level in each tiles table.
It allows GeoPackages to contain rectangular as well as square tiles (e.g., for better representation of polar regions).
It allows tile pyramids with zoom levels that differ in resolution by factors of 2, irregular intervals, or regular intervals other than factors of 2.
Values of the gpkg_tile_matrix table_name column SHALL reference values in the gpkg_contents table_name column for rows with a data_type of "tiles".[K19]
The gpkg_tile_matrix table SHALL contain one row record for each zoom level that contains one or more tiles in each tile pyramid user data table or view.
The width of a tile matrix (the difference between min_x and max_x in gpkg_tile_matrix_set) SHALL equal the product of matrix_width, tile_width, and pixel_x_size for that zoom level.
Similarly, height of a tile matrix (the difference between min_y and max_y in gpkg_tile_matrix_set) SHALL equal the product of matrix_height, tile_height, and pixel_y_size for that zoom level.
Tile matrices are numbered from top left to bottom right (zero-indexed) so the top left tile is (0,0). (This follows the convention used by by WMTS [I16].) Tile matrices may be sparsely populated – no specific tile or even tile matrix must be present. If the global tile matrix set covers the whole earth, then zoom level 0, tile (0,0) is the whole world.
The zoom_level column value in a gpkg_tile_matrix table row SHALL not be negative.
The matrix_width column value in a gpkg_tile_matrix table row SHALL be greater than 0.
The matrix_height column value in a gpkg_tile_matrix table row SHALL be greater than 0.
The tile_width column value in a gpkg_tile_matrix table row SHALL be greater than 0.
The tile_height column value in a gpkg_tile_matrix table row SHALL be greater than 0.
The pixel_x_size column value in a gpkg_tile_matrix table row SHALL be greater than 0.
The pixel_y_size column value in a gpkg_tile_matrix table row SHALL be greater than 0.
When zoom_level column values in the gpkg_tile_matrix table are sorted in ascending order, the pixel_x_size and pixel_y_size column values in the gpkg_tile_matrix table SHALL appear sorted in descending order.
Tiles MAY or MAY NOT be provided for level 0 or any other particular zoom level. [K21]
This means that a tile matrix set can be sparse, i.e. not contain a tile for any particular position at a certain tile zoom level.
[K22] This does not affect the informative spatial extent stated by the min/max x/y columns values in the gpkg_contents record for the same table_name, the exact spatial extent stated by the min/max x/y columns values in the gpkg_tile_matrix_set record for the same table name, or the tile matrix width and height at that level. [K23]
A GeoPackage MAY contain tables containing tile pyramid user data for a single tile matrix set.
Every such tile pyramid user data table SHALL be structured consistently with Table Definition and [example_tiles_table_sql].
A table SHALL have a primary key column of type INTEGER and that column SHALL act as a rowid alias.
|
Note
|
The integer primary key of a tile pyramid user data table allows tiles to be linked to row level metadata records in the |
A GeoPackage MAY contain views containing tile pyramid user data for a single tile matrix set. Every such tile pyramid user data view SHALL have a first column of type INTEGER and that column SHALL contain unique values for each row.
|
Note
|
Since the concept of primary keys does not exist for views in SQLite, this requirement provides a way to produce a compliant tile pyramid user data view with a discoverable key-like column[K17]. |
| Column Name | Column Type | Column Description | Null | Key |
|---|---|---|---|---|
|
INTEGER |
Autoincrement[K6a] primary key |
N/A[K6b] |
PK |
|
INTEGER |
min(zoom_level) <= |
no |
UK |
|
INTEGER |
0 to |
no |
UK |
|
INTEGER |
0 to |
no |
UK |
|
BLOB |
Of an image MIME type specified in clauses Tile Encoding PNG, Tile Encoding JPEG, [extension_tiles_webp] |
no |
|
Warning
|
Though this standard does not technically mandate the use of an indexing mechanism in a tiles table, the lack of such an index, e.g., a |
Each tile pyramid user data table or view [K24] MAY contain tile matrices at zero or more zoom levels of different spatial resolution (map scale).
For each distinct table_name from the gpkg_tile_matrix (tm) table, the tile pyramid (tp) user data table zoom_level column value in a GeoPackage SHALL be in the range min(tm.zoom_level) <= tp.zoom_level <= max(tm.zoom_level).
For each distinct table_name from the gpkg_tile_matrix (tm) table, the tile pyramid (tp) user data table tile_column column value in a GeoPackage SHALL be in the range 0 <= tp.tile_column <= tm.matrix_width – 1 where the tm and tp zoom_level column values are equal.
For each distinct table_name from the gpkg_tile_matrix (tm) table, the tile pyramid (tp) user data table tile_row column value in a GeoPackage SHALL be in the range 0 <= tp.tile_row <= tm.matrix_height – 1 where the tm and tp zoom_level column values are equal.
All tiles at a particular zoom level have the same pixel_x_size and pixel_y_size values specified in the gpkg_tile_matrix row record for that tiles table and zoom level. [K25]