extension_tiled_gridded_elevation_data.adoc

Tiled Gridded Elevation Data

Extension Title

Tiled Gridded Elevation Data

Introduction

This extension provides the ability to store 16-bit and 32-bit tiled gridded elevation data in a GeoPackage. This capability will be used to support use cases such as the following:

• Visualization

  • 2D (hillshade, color relief, slope)

  • 3D (supporting changing view angles and level of detail)

• Analysis

  • Viewshed and line-of-sight

  • Cross-country mobility (off-road routing)

  • Site suitability and planning (slope analysis such as helicopter landing zones)

  • 3D geometry representations of features (ground-based, airspace)

  • Terrain association (associating images to mapped locations)

  • Augmented reality training

This capability was designed to be relatively easy to implement and to be suitable for a wide variety of computing environments including the mobile/handheld computing environment^[1].

This extension to the OGC GeoPackage Encoding Standard leverages the existing structure for raster tiles using PNG (16-bit) and TIFF (32-bit) files as the container for the elevation values themselves. It is the data producer’s responsibility to ensure that the intended recipient is able to read GeoPackages with the elevation encoding (PNG or TIFF) being used. By default, the elevation values are assumed to be average elevation for pixel-is-area. Communities of interest may agree to use an alternative pixel encoding (such as pixel-is-point) but specifying the pixel encoding is outside of the scope of this document.

Extension Author

GeoPackage SWG, author_name gpkg.

Extension Name or Template

gpkg_elevation_tiles

Extension Type

New requirement dependent on Clause 2.2.

Applicability

This extension applies to tile pyramid user data tables that are used to hold tiled, gridded elevation data.

Scope

read-write

Requirements

Table Definitions

Coverage Ancillary

Requirement 120

A GeoPackage that contains tiled gridded elevation data SHALL contain a gpkg_2d_gridded_coverage_ancillary table or view as per Coverage Ancillary Table Definition. Subsequent extensions or custom implementations MAY add additional columns to this table. Clients SHALL ignore additional columns that are unrecognized.

Table 1. Coverage Ancillary Table Definition

Column Name	Column Type	Column Description	Null	Default	Key	Constraint
id	INTEGER	Autoincrement primary key	no		PK
tile_matrix_set_name	TEXT	Foreign key to table_name in gpkg_tile_matrix_set	no		FK	UNIQUE
datatype	TEXT	integer or float	no	integer
scale	REAL	Scale as a multiple relative to the unit of measure	no	1
offset	REAL	The offset to the 0 value	no	0
precision	REAL[2]	The smallest value that has meaning for this dataset	yes	1
data_null	REAL[3]	The value that indicates NULL	yes

Using the Scale and Offset Values

Integer elevation values MAY be scaled and offset in order to make more efficient use of 16-bit integer space available in PNG files. The scale and offset MAY be applied to the entire coverage and/or the individual tile. The scale and offset do not apply to the data_null value as defined in Coverage Ancillary Table Definition.

Actual elevation values are be calculated by:

• first multiplying the stored value by the gpkg_2d_gridded_tile_ancillary_table.scale value and then adding the gpkg_2d_gridded_tile_ancillary_table.offset,

• followed by multiplying that value by the gpkg_2d_gridded_coverage_ancillary.scale value and then adding the gpkg_2d_gridded_coverage_ancillary.offset.

In pseudo-code, this conversion would look like:

elevationInUnitOfMeasure = (SomeElevationCoverage.tile_data->pngpixels[i] * gpkg_2d_gridded_tile_ancillary.scale + gpkg_2d_gridded_tile_ancillary.offset) * gpkg_2d_gridded_coverage_ancillary.scale + gpkg_2d_gridded_coverage_ancillary.offset;

Note: integer and float refer to the values stored in the tiles. If integer values have a real scale or offset applied to them, then the resulting values will be real. The scale and offset do not apply to tiles of datatype float.

Tile Ancillary

Requirement 121

A GeoPackage that contains tiled gridded elevation data SHALL contain a gpkg_2d_gridded_tile_ancillary table or view as per Tile Ancillary Table Definition. Subsequent extensions or custom implementations MAY add additional columns to this table. Clients SHALL ignore additional columns that are unrecognized.

Table 2. Tile Ancillary Table Definition

Column Name	Column Type	Column Description	Null	Default	Key
id	INTEGER	Autoincrement primary key	no		PK
tpudt_name	TEXT	Name of tile pyramid user data table	no		UNIQUE[4]
tpudt_id	INTEGER	Foreign key to id in tile pyramid user data table	no		UNIQUE[5]
scale	REAL	Scale as a multiple relative to the unit of measure	no	1
offset	REAL	The offset to the 0 value	no	0
min	REAL[6]	Minimum value of this tile	yes
max	REAL[7]	Maximum value of this tile	yes
mean	REAL	The arithmetic mean of values in this tile	yes
std_dev	REAL	The standard deviation of values in this tile	yes

The min, max, and mean values are natural, i.e., not scaled or offset. Similarly, the std_dev is calculated based on the natural values. The scale and offset do not apply to tiles of datatype float.

Table Values

gpkg_spatial_ref_sys

Requirement 122

GeoPackages complying with this extension SHALL have a row in the gpkg_spatial_ref_sys table as described in Spatial Ref Sys Table Record:

Because of limitations in expressing 3D coordinate reference systems in Well-known Text [32], it is recommended that GeoPackages complying with this extension also comply with [extension_crs_wkt].

Table 3. Spatial Ref Sys Table Record

srs_name	srs_id	organization	organization_coordsys_id	definition
description	any	4979	EPSG or epsg	4979

Requirement 123

The gpkg_spatial_ref_sys table in a GeoPackage SHALL contain records to define all spatial reference systems used by tiled gridded elevation data in a GeoPackage. The spatial reference system SHALL be used to define the vertical datum, reference geoid, and units of measure for the tiled gridded elevation data.

gpkg_contents

Requirement 124

(extends GPKG-34) The gpkg_contents table SHALL contain a row with a data_type column value of '2d-gridded-coverage' for each tile pyramid containing tiled gridded elevation data. The srs_id column value for that row SHOULD reference an SRS that has a vertical datum^[8].

gpkg_extensions

Requirement 125

GeoPackages complying with this extension SHALL have rows in the gpkg_extensions table as described in Extensions Table Record.

Table 4. Extensions Table Record

table_name	column_name	extension_name	definition	scope
gpkg_2d_gridded_coverage_ancillary	null	gpkg_elevation_tiles	http://www.geopackage.org/spec/#extension_tiled_gridded_elevation_data	read-write
gpkg_2d_gridded_tile_ancillary	null	gpkg_elevation_tiles	http://www.geopackage.org/spec/#extension_tiled_gridded_elevation_data	read-write
name of actual tile pyramid user data table containing elevation data	tile_data	gpkg_elevation_tiles	http://www.geopackage.org/spec/#extension_tiled_gridded_elevation_data	read-write

gpkg_2d_gridded_coverage_ancillary

The following requirements refer to the gpkg_2d_gridded_coverage_ancillary table as per Coverage Ancillary Table Definition.

Requirement 126

For each row in gpkg_contents with a data_type column value of '2d-gridded-coverage', there SHALL be a row in gpkg_2d_gridded_coverage_ancillary. Values of the tile_matrix_set_name column SHALL reference values in the gpkg_contents table_name column.

Requirement 127

Values of the tile_matrix_set_name column SHALL reference values in the gpkg_tile_matrix_set table_name column.

Requirement 128

Values of the datatype column MAY be integer or float. When the datatype is float, the scale and offset values SHALL be set to the defaults.

gpkg_2d_gridded_tile_ancillary

The following requirements refer to the gpkg_2d_gridded_tile_ancillary table as per Tile Ancillary Table Definition.

Requirement 129

For each row in a tile pyramid user data table corresponding to tiled, gridded elevation data, there SHALL be a row in gpkg_2d_gridded_tile_ancillary.

Requirement 130

Values of the tpudt_name column SHALL reference existing tile pyramid user data tables and rows in gpkg_2d_gridded_coverage_ancillary. When the datatype of the corresponding gpkg_2d_gridded_coverage_ancillary row is float, the scale and offset values SHALL be set to the defaults.

Requirement 131

Values of the tpudt_id column SHALL reference values in id column of the table referenced in tpudt_name.

Tile Pyramid User Data Tables

Requirement 132

For data where the datatype column of the corresponding row in the gpkg_2d_gridded_coverage_ancillary table is integer, the tile_data BLOB in the tile pyramid user data table containing tiled, gridded elevation data SHALL be of MIME type image/png and the data SHALL be 16-bit unsigned integer (single channel - "greyscale").

Requirement 133

For data where the datatype column of the corresponding row in the gpkg_2d_gridded_coverage_ancillary table is float, the tile_data BLOB in the tile pyramid user data table containing tiled, gridded elevation data SHALL be of MIME type image/tiff and the data SHALL be 32-bit floating point as described by the TIFF Encoding ([tiff_encoding]).

Table Definition SQL

Coverage Ancillary Table Definition SQL

CREATE TABLE 'gpkg_2d_gridded_coverage_ancillary' (
  id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
  tile_matrix_set_name TEXT NOT NULL UNIQUE,
  datatype TEXT NOT NULL DEFAULT 'integer',
  scale REAL NOT NULL DEFAULT 1.0,
  offset REAL NOT NULL DEFAULT 0.0,
  precision REAL DEFAULT 1.0,
  data_null REAL,
  CONSTRAINT fk_g2dgtct_name FOREIGN KEY('tile_matrix_set_name') REFERENCES gpkg_tile_matrix_set ( table_name )
  CHECK (datatype in ('integer','float')));

Tile Ancillary Table Definition SQL

CREATE TABLE gpkg_2d_gridded_tile_ancillary (
  id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
  tpudt_name TEXT NOT NULL,
  tpudt_id INTEGER NOT NULL,
  scale REAL NOT NULL DEFAULT 1.0,
  offset REAL NOT NULL DEFAULT 0.0,
  min REAL DEFAULT NULL,
  max REAL DEFAULT NULL,
  mean REAL DEFAULT NULL,
  std_dev REAL DEFAULT NULL,
  CONSTRAINT fk_g2dgtat_name FOREIGN KEY (tpudt_name) REFERENCES gpkg_contents(table_name),
  UNIQUE (tpudt_name, tpudt_id));

TIFF Encoding

Because of the variance in possible TIFF encodings for a tile, the encoding has been constrained for the sake of interoperability and best practice.

TIFF-encoding a tile as a single-band image using one 32-bit floating point component per pixel implies a number of constraints. These are listed below.

Each TIFF encoded tile SHALL be a baseline TIFF as defined in the Part 1 of TIFF[35]. The only allowed encoding extensions are :

• By setting TAG 339 (SampleFormat) to be 3, the producer indicates that the Sample Value is IEEE floating point as defined in Part 2 (TIFF Extensions) Section 19: Data Sample Format TIFF[35].

• LZW compression MAY be used as defined in Section 13: LZW Compression TIFF[35].

In addition to conforming to the baseline and listed conventions, tiles encoded as TIFF are expected to conform to the following implied or dictated constraints :

• By setting TAG 277 (SamplesPerPixel) to be 1, the producer indicates that there is a single sample per pixel.

• There is only one band per TIFF tile i.e. for any pixel in the TIFF tile, there SHALL be only one component.

• All 65536 pixels in the tile SHALL be set with a valid component value. The mechanisms defined in this extension SHALL be used to indicate a missing value for a pixel.

• Other TIFF tags are derived from the other constraints in this extension e.g. TAG 258 (BitsPerSample), if included SHALL be 32.

• No multi-image/tiling extensions defined in TIFF[35] shall be used.

Requirement 134

A TIFF file used for storing tiled gridded elevation data SHALL conform to the TIFF specification [35].

Requirement 135

(constrains TIFF[35] Section 2) A TIFF file storing tiled gridded elevation data SHALL have one sample per pixel.

Requirement 136

(constrains TIFF[35] Section 19) A TIFF file storing tiled gridded elevation data SHALL have the 32-bit floating (FLOAT – 11) data type.

Requirement 137

A TIFF file storing tiled gridded elevation data MAY use the LZW compression option as per TIFF[35] Section 13.

Client applications that support the TIFF encoding are expected to support this option.

Requirement 138

(constrains TIFF[35] Section 2) A TIFF file storing tiled gridded elevation data SHALL NOT contain multiple images per TIFF file.

Requirement 139

(constrains TIFF[35] Section 15) A TIFF file storing tiled gridded elevation data SHALL NOT contain internal tiles as per TIFF Section 15.

---

1. We acknowledge that this approach will not support certain applications that require a high degree of precision and/or accuracy (e.g., targeting).

2. This is a REAL to support extensions that use non-integer data.

3. This is a REAL to support extensions that use non-integer data.

4. These two values are designed to be jointly unique so that they refer to a single row in a single table.

5. These two values are designed to be jointly unique so that they refer to a single row in a single table.

6. This is a REAL to support extensions that use non-integer data.

7. This is a REAL to support extensions that use non-integer data.

8. Ideally the vertical datum for each pyramid of elevation will be specified. However, it is impractical to mandate this for a number of reasons, including the difficulty in testing whether a specific SRS has a valid vertical datum.