Geospatial Definitions

This document contains the specification of geospatial types and statistics.

Background

The Geometry and Geography class hierarchy and its Well-Known Text (WKT) and Well-Known Binary (WKB) serializations (ISO variant supporting XY, XYZ, XYM, XYZM) are defined by OpenGIS Implementation Specification for Geographic information - Simple feature access - Part 1: Common architecture, from OGC(Open Geospatial Consortium).

The version of the OGC standard first used here is 1.2.1, but future versions may also be used if the WKB representation remains wire-compatible.

Coordinate Reference System

Coordinate Reference System (CRS) is a mapping of how coordinates refer to locations on Earth.

The default CRS OGC:CRS84 means that the geospatial features must be stored in the order of longitude/latitude based on the WGS84 datum.

Custom CRS can be specified by a string value. It is recommended to use an identifier-based approach like Spatial reference identifier.

For geographic CRS, longitudes are bound by [-180, 180] and latitudes are bound by [-90, 90].

Edge Interpolation Algorithm

An algorithm for interpolating edges, and is one of the following values:

• spherical: edges are interpolated as geodesics on a sphere.
• vincenty: https://en.wikipedia.org/wiki/Vincenty%27s_formulae
• thomas: Thomas, Paul D. Spheroidal geodesics, reference systems, & local geometry. US Naval Oceanographic Office, 1970.
• andoyer: Thomas, Paul D. Mathematical models for navigation systems. US Naval Oceanographic Office, 1965.
• karney: Karney, Charles FF. “Algorithms for geodesics.” Journal of Geodesy 87 (2013): 43-55, and GeographicLib

Logical Types

Two geospatial logical type annotations are supported:

• GEOMETRY: geospatial features in the WKB format with linear/planar edges interpolation. See Geometry
• GEOGRAPHY: geospatial features in the WKB format with an explicit (non-linear/non-planar) edges interpolation algorithm. See Geography

Statistics

GeospatialStatistics is a struct specific for GEOMETRY and GEOGRAPHY logical types to store statistics of a column chunk. It is an optional field in the ColumnMetaData and contains Bounding Box and Geospatial Types that are described below in detail.

Bounding Box

A geospatial instance has at least two coordinate dimensions: X and Y for 2D coordinates of each point. Please note that X is longitude/easting and Y is latitude/northing. A geospatial instance can optionally have Z and/or M values associated with each point.

The Z values introduce the third dimension coordinate. Usually they are used to indicate the height, or elevation.

M values are an opportunity for a geospatial instance to track a value in a fourth dimension. These values can be used as a linear reference value (e.g., highway milepost value), a timestamp, or some other value as defined by the CRS.

Bounding box is defined as the thrift struct below in the representation of min/max value pair of coordinates from each axis. Note that X and Y Values are always present. Z and M are omitted for 2D geospatial instances.

When calculating a bounding box, null or NaN values in a coordinate dimension are skipped. For example, POINT (1 NaN) contributes a value to X but no values to Y, Z, or M dimension of the bounding box. If a dimension has only null or NaN values, that dimension is omitted from the bounding box. If either the X or Y dimension is missing, then the bounding box itself is not produced.

For the X values only, xmin may be greater than xmax. In this case, an object in this bounding box may match if it contains an X such that x >= xmin OR x <= xmax. This wraparound occurs only when the corresponding bounding box crosses the antimeridian line. In geographic terminology, the concepts of xmin, xmax, ymin, and ymax are also known as westernmost, easternmost, southernmost and northernmost, respectively.

For GEOGRAPHY types, X and Y values are restricted to the canonical ranges of [-180, 180] for X and [-90, 90] for Y.

struct BoundingBox {
  1: required double xmin;
  2: required double xmax;
  3: required double ymin;
  4: required double ymax;
  5: optional double zmin;
  6: optional double zmax;
  7: optional double mmin;
  8: optional double mmax;
}

Geospatial Types

A list of geospatial types from all instances in the GEOMETRY or GEOGRAPHY column, or an empty list if they are not known.

This is borrowed from geometry_types of GeoParquet except that values in the list are WKB (ISO-variant) integer codes. Table below shows the most common geospatial types and their codes:

In addition, the following rules are applied:

• A list of multiple values indicates that multiple geospatial types are present (e.g. [0003, 0006]).
• An empty array explicitly signals that the geospatial types are not known.
• The geospatial types in the list must be unique (e.g. [0001, 0001] is not valid).

CRS Customization

CRS is represented as a string value. Writer and reader implementations are responsible for serializing and deserializing the CRS, respectively.

As a convention to maximize the interoperability, custom CRS values can be specified by a string of the format type:identifier, where type is one of the following values:

• srid: Spatial reference identifier, identifier is the SRID itself.
• projjson: PROJJSON, identifier is the name of a table property or a file property where the projjson string is stored.

Coordinate axis order

The axis order of the coordinates in WKB and bounding box stored in Parquet follows the de facto standard for axis order in WKB and is therefore always (x, y) where x is easting or longitude and y is northing or latitude. This ordering explicitly overrides the axis order as specified in the CRS.