Home

Awesome

Grid Extension Specification

This document explains the Grid Extension to the SpatioTemporal Asset Catalog (STAC) specification.

The purpose of the Grid Extension is to provide fields related to gridded data products.

There are two main uses of the grid:code field defined in this specification. Both are primarily for use in supporting a path for a user exploring a dataset from a UI where there are too many results to display individually, where the user must first be presented with summary / aggregated data, and then drill down to individual items.

The first is that it allows for precise aggregation in a STAC API implementation of Items that cover the same grid area. The STAC API Aggregation Extension is a work-in-progress, but will eventually support aggregating over this field.

The second aspect is that it helps for display to a user when a gridded dataset has Items that have slightly different footprints for Items over the same grid square. For example, Landsat 8 scenes for the same path/row grid square are often off by a few pixels from each other, which makes them not match exactly. Some products with grids that are significantly different from EPSG:4326 have footprints that are far from a square after reprojection, such how MODIS sinusoidal grid squares become increasingly curved as they move away from the equator and meridan. This can make the GeoJSON Polygon large, as more points must be added to maintain an accurate reprojected shape. With a grid code defined for an Item, a UI could have a pre-determined geometry at a reasonable resolution for that grid square, and display it once for each all the Items in that grid square.

Item Properties Fields

Field NameTypeDescription
grid:codestringREQUIRED. The identifier for the grid element associated with the Item.

Additional Field Information

grid:code

The field grid:code defines a unique value for each grid square in a gridding. The code will be of the form {grid designation}-{grid square code}, where the grid designation is a short alphanumeric code for the grid (e.g., MGRS) and code is a short encoded value for a specific grid square. The encoded value for the square should consist of uppercase alphanumeric characters, underscore (_) (preferred separator), or minus sign (-).

The grid code values below are recommended for these products. Implementers may also devise proprietary systems for their own griddings.

Military Grid Reference System (MGRS)
MODIS Sinusoidal Tile Grid
Worldwide Reference System (WRS-1)
Worldwide Reference System (WRS-2)
Digital Orthophoto Quadrangle

Represents one U.S. Geological Survey (USGS) 7.5-minute quadrangle. The names are based on that of the 7.5-minute quad.

Digital Orthophoto Quarter Quadrangle

Represents one U.S. Geological Survey (USGS) 7.5-minute quadrangle. The Digital Orthophoto Quarter Quadrangle (DOQQ) represents one quarter of the quadrangle. The names are based on that of the 7.5-minute quad, followed by NE, NW, SW, or SE for the DOQQ.

Maxar ARD Tile Grid
EASE-DGGS
Copernicus Digital Elevation Model Grid

Contributing

All contributions are subject to the STAC Specification Code of Conduct. For contributions, please follow the STAC specification contributing guide Instructions for running tests are copied here for convenience.

Running tests

The same checks that run as checks on PR's are part of the repository and can be run locally to verify that changes are valid. To run tests locally, you'll need npm, which is a standard part of any node.js installation.

First you'll need to install everything with npm once. Just navigate to the root of this repository and on your command line run:

npm install

Then to check markdown formatting and test the examples against the JSON schema, you can run:

npm test

This will spit out the same texts that you see online, and you can then go and fix your markdown or examples.

If the tests reveal formatting problems with the examples, you can fix them with:

npm run format-examples

Grid Maps

This describes how to generate files that define the mapping from a grid code to a geometry / footprint. The intention with these files is that they are used in a web UI for displaying the footprint of a scene from a grid id, typically in conjunction with the STAC API Aggregation Extension.

Because these files are intended to be downloaded by a web UI, creating a file that is as small as possible is a primary concern. Compression (via either gzip or brotli) is typically handled by the web server they are served from, but we want to start with as small a file as possible before that.

A few of the optimizations these use are:

  1. The prefix is a separate field, and only the unique idenifier part is specified in the cells list. This cuts all of the duplicate instances of the prefix from the file.
  2. Instead of a complete GeoJSON geometry defintion, only the coordinates are used. This cuts all of the duplicate instances of the type field from the file.
  3. Coordinate precision is set to 2 decimal places, which means it varies by no more than 1km at the equator.
  4. JSON is output in compact mode, with no line breaks, indentation, or spaces around the : and , characters.

Landsat (WRS2)

These are defined as Polygons or MultiPolygons (across the antimeridian), and are all converted to MultiPolygons.

curl -O https://d9-wret.s3.us-west-2.amazonaws.com/assets/palladium/production/s3fs-public/atoms/files/WRS2_descending_0.zip
unzip WRS2_descending_0.zip
ogr2ogr -f GeoJSON -t_srs EPSG:4326 wrs2.geojson WRS2_descending.shp
python ./scripts/grid_maker.py WRS2 PR 2 1 wrs2.geojson > grid_maps/wrs2.json

Sentinel-2 (MGRS)

This are defined as a GeometryCollection of Polygon and Points, which this converts to MultiPolygons. Antimeridan-spanning cells are handled with multiple Polygons.

curl -O https://sentinels.copernicus.eu/documents/247904/1955685/S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml
ogr2ogr -f GeoJSON -t_srs EPSG:4326 mgrs.geojson S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml
python scripts/grid_maker.py MGRS Name 3 0 mgrs.geojson > grid_maps/mgrs.json

Copernicus DEM (CDEM)

These are all Polygons and have no antimeridian-spanning cells.

curl -O https://spacedata.copernicus.eu/documents/20123/122407/GEO1988-CopernicusDEM-RP-002_GridFile_I4.0_ESA.zip
unzip GEO1988-CopernicusDEM-RP-002_GridFile_I4.0_ESA.zip
ogr2ogr -f GeoJSON -t_srs EPSG:4326 cdem.geojson GEO1988-CopernicusDEM-RP-002_GridFile_I4.0_ESA.shp/GEO1988-CopernicusDEM-RP-002_GridFile_I4.0_ESA.shp
python scripts/grid_maker.py CDEM GeoCellID 0 0 cdem.geojson > grid_maps/cdem.json

NAIP (DOQQ)

These are all Polygons and within CONUS (no antimeridian-spanning cells).

To process:

  1. Download all 48 (AK and HI are excluded) from NAIP: NAIP Quarter Quad and Seamline Shapefiles and put them in the scripts directory.
  2. run:
cd scripts
./naip_zip_to_geojson.sh
./naip_merge.py > grid_maps/doqq.json

In the Tennessee 2018 geometries, NW3408508 is set with a null geometry. However, this grid cell overlaps with Georgia, so it's picked up from those definitions.