2b_tiles.adoc

Tiles

Tile Matrix Introduction

There are a wide variety of commercial and open source conventions for storing, indexing, accessing and describing tiles in tile pyramids. Unfortunately, no applicable existing consensus, national or international specifications have standardized practices in this domain. In addition, various image file formats have different representational capabilities, and include different self-descriptive metadata.

The tile store data / metadata model and convention 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, SHALL store sufficient metadata to enable its intended use.

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. ^[1] “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 matrix” refers to rows and columns of tiles that all have the same spatial extent and resolution at a particular zoom level. “Tile matrix set” refers to the definition of a tile pyramid’s tiling structure.

The tables or views that implement the GeoPackage tile store data / metadata model are described and discussed individually in the following subsections.

Contents

Data

Contents Table – Tiles Row

The gpkg_contents table SHALL contain a row with a data_type column value of “tiles” for each tile pyramid user data table or view.

Zoom Levels

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 preceed 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_factor2_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 WMTS [16] Annex E for additional examples of both conventions.

Data

Zoom Times Two

In a GeoPackage that contains a tile pyramid user data table that contains tile data, by default ^[2], zoom level pixel sizes for that table SHALL vary by a factor of 2 between adjacent zoom levels in the tile matrix metadata table.

Tile Encoding PNG

Data

MIME Type PNG

In a GeoPackage that contains a tile pyramid user data table that contains tile data that is not MIME type image/jpeg [17][18][19], by default SHALL store that tile data in MIME type image/png [20][21]. ^[3]

Tile Encoding JPEG

Data

MIME Type JPEG

In a GeoPackage that contains a tile pyramid user data table that contains tile data that is not MIME type image/png [20][21], by default SHALL store that tile data in MIME type image/jpeg [17][18][19]. ^[4]

Tile Matrix Set

Data

Table Definition

A GeoPackage that contains a tile pyramid user data table SHALL contain gpkg_tile_matrix_set table or view per Table Definition, Tile Matrix Set Table or View Definition and [gpkg_tile_matrix_set_sql].

Table 1. Tile Matrix Set Table or View Definition

Column Name	Column Type	Column Description	Null	Default	Key
table_name	TEXT	Tile Pyramid User Data Table Name	no		PK, FK
srs_id	INTEGER	Spatial Reference System ID: gpkg_spatial_ref_sys.srs_id	no		FK
min_x	DOUBLE	Bounding box minimum easting or longitude for all content in table_name	no
min_y	DOUBLE	Bounding box minimum northing or latitude for all content in table_name	no
max_x	DOUBLE	Bounding box maximum easting or longitude for all content in table_name	no
max_y	DOUBLE	Bounding box maximum northing or latitude for all content in table_name	no

The gpkg_tile_matrix_set table or updateable view 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. All tiles present in the tile pyramid SHALL fall within this bounding box. However, the bounding box MAY be larger than the minimum bounding rectangle around the actual tiles in that pyramid.

See [gpkg_tile_matrix_set_sql].

Table Data Values

The minimum bounding box defined in the gpkg_tile_matrix_set table or view for a tile pyramid user data table SHALL be exact so that the bounding box coordinates for individual tiles in a tile pyramid MAY be calculated based on the column values for the user data table in the gpkg_tile_matrix table or view. For example, because 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.

Values of the gpkg_tile_matrix_set table_name column SHALL reference values in th gpkg_contents table_name column for rows with a data type of "tiles".

The gpkg_tile_matrix_set table or view 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.

Tile Matrix

Data

Table Definition

A GeoPackage that contains a tile pyramid user data table SHALL contain a gpkg_tile_matrix table or view per clause 2.2.7.1.1 Table Definition, Table Tile Matrix Metadata Table or View Definition and Table [gpkg_tile_matrix_sql].

Table 2. Tile Matrix Metadata Table or View Definition

Column Name	Column Type	Column Description	Null	Key
table_name	TEXT	Tile Pyramid User Data Table Name	no	PK, FK
zoom_level	INTEGER	0 ⇐ zoom_level ⇐ max_level for table_name	no	PK
matrix_width	INTEGER	Number of columns (>= 1) in tile matrix at this zoom level	no
matrix_height	INTEGER	Number of rows (>= 1) in tile matrix at this zoom level	no
tile_width	INTEGER	Tile width in pixels (>= 1)for this zoom level	no
tile_height	INTEGER	Tile height in pixels (>= 1) for this zoom level	no
pixel_x_size	DOUBLE	In t_table_name srid units or default meters for srid 0 (>0)	no
pixel_y_size	DOUBLE	In t_table_name srid units or default meters for srid 0 (>0)	no

The gpkg_tile_matrix table or updateable view 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.

See [gpkg_tile_matrix_sql]

Table Data Values

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”.

The gpkg_tile_matrix table or view 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.

The gpkg_tile_matrix table or view MAY contain row records for zoom levels in a tile pyramid user data table that do not contain tiles.

GeoPackages follow the most frequently used conventions of a tile origin at the upper left and a zoom-out-level of 0 for the smallest map scale “whole world” zoom level view ^[5], as specified by WMTS [16]. The tile coordinate (0,0) always refers to the tile in the upper left corner of the tile matrix at any zoom level, regardless of the actual availability of that tile.

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.

The pixel_x_size and pixel_y_size column values for zoom_level column values in a gpkg_tile_matrix table sorted in ascending order SHALL be sorted in descending order.

Tiles MAY or MAY NOT be provided for level 0 or any other particular zoom level. ^[6] 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. ^[7] 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. ^[8]

Tile Pyramid User Data Tables

Data

Table Definition

Each tile matrix set in a GeoPackage SHALL be stored in a different tile pyramid user data table or updateable view with a unique name that SHALL have a column named "id" with column type INTEGER and 'PRIMARY KEY AUTOINCREMENT' column constraints per Clause 2.2.8.1.1 Table Definition, Tiles Table or View Definition and [example_tiles_table_sql].

Table 3. Tiles Table or View Definition

Column Name	Column Type	Column Description	Null	Default	Key
id	INTEGER	Autoincrement primary key	no		PK
zoom_level	INTEGER	min(zoom_level) ⇐ zoom_level ⇐ max(zoom_level) for t_table_name	no	0	UK
tile_column	INTEGER	0 to tile_matrix matrix_width – 1	no	0	UK
tile_row	INTEGER	0 to tile_matrix matrix_height - 1	no	0	UK
tile_data	BLOB	Of an image MIME type specified in clauses Tile Encoding PNG, Tile Encoding JPEG, [tile_enc_webp]	no

See [example_tiles_table_sql].

Table Data Values

Each tile pyramid user data table or view ^[9] 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. ^[10]

---

1. Images of multiple MIME types MAY be stored in given table. For example, in a tiles table, image/png format tiles COULD be used for transparency where there is no data on the tile edges, and image/jpeg format tiles COULD be used for storage efficiency where there is image data for all pixels. Images of multiple bit depths of the same MIME type MAY also be stored in a given table, for example image/png tiles in both 8 and 24 bit depths.

2. See clause 3.2.1.1.1 for use of other zoom levels as a registered extensions.

3. See Clause 3.2.2 regarding use of the WebP alternative tile MIME type as a registered extension.

4. See Clause 3.2.2 regarding use of the WebP alternative tile MIME type as a registered extension.

5. GeoPackage applications MAY query the gpkg_tile_matrix table or the tile pyramid user data table to determine the minimum and maximum zoom levels for a given tile pyramid table.

6. GeoPackage applications MAY query a tile pyramid user data table to determine which tiles are available at each zoom level.

7. GeoPackage applications that insert, update, or delete tile pyramid user data table tiles row records are responsible for maintaining the corresponding descriptive contents of the gpkg_tile_matrix_metadata table.

8. The `gpkg_tile_matrix_set` table contains coordinates that define a bounding box as the exact stated spatial extent for all tiles in a tile (matrix set) table. If the geographic extent of the image data contained in tiles at a particular zoom level is within but not equal to this bounding box, then the non-image area of matrix edge tiles must be padded with no-data values, preferably transparent ones.

9. A GeoPackage is not required to contain any tile pyramid user data tables. Tile pyramid user data tables in a GeoPackage MAY be empty.

10. The zoom_level / tile_column / tile_row unique key is automatically indexed, and allows tiles to be selected and accessed by "z, x, y", a common convention used by some implementations. This table / view definition MAY also allow tiles to be selected based on a spatially indexed bounding box in a separate metadata table.