Skip to content

Latest commit

 

History

History
164 lines (125 loc) · 7.44 KB

Geospatial.md

File metadata and controls

164 lines (125 loc) · 7.44 KB

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:

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 express a fourth dimension as a coordinate value. 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.

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:

Type XY XYZ XYM XYZM
Point 0001 1001 2001 3001
LineString 0002 1002 2002 3002
Polygon 0003 1003 2003 3003
MultiPoint 0004 1004 2004 3004
MultiLineString 0005 1005 2005 3005
MultiPolygon 0006 1006 2006 3006
GeometryCollection 0007 1007 2007 3007

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.