-
Title: Grid
-
Identifier: https://stac-extensions.github.io/grid/v1.1.0/schema.json
-
Field Name Prefix: grid
-
Scope: Item
-
Extension Maturity Classification: Pilot
-
Owners: @philvarner, @drwelby
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.
- Examples:
- Item example: Shows the basic usage of the extension in a STAC Item
- JSON Schema
- Changelog
Field Name | Type | Description |
---|---|---|
grid:code | string | REQUIRED. The identifier for the grid element associated with the Item. |
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.
- Format String: MGRS-{grid zone designator}{latitude band}{square}
- Examples: MGRS-35NKA, MGRS-35NKA1234, MGRS-35NKA123456, MGRS-35NKA12345678, MGRS-35NKA1234567890
- Components:
- grid zone designator: UTM grid zone
- latitude band: latitude band, lettered C-X (omitting the letters "I" and "O")
- square: a pair of letters designating one of the 100km side grid squares within the grid zone and latitude band square, and optionally either 2, 4, 6, 8, or 10 additional digits
- Products: Sentinel-2
- Reference: https://en.wikipedia.org/wiki/Military_Grid_Reference_System
- Related Extensions: https://github.com/stac-extensions/mgrs
- Format String: MSIN-{horizontal}{vertical}
- Example: MSIN-2506
- Components:
- horizontal: horizontal tile number
- vertical: vertical tile number
- Products: many MODIS products, including MCD43A4, MxD11A1, and MxD13A1
- Reference: https://modis-land.gsfc.nasa.gov/MODLAND_grid.html
- Related Extensions: none
- Format String: WRS1-{path}{row}
- Example: WRS1-097073
- Components:
- path: path number for nominal satellite orbital track
- row: latitudinal center line of a frame of imagery
- Products: Landsat 1-3
- Reference: https://landsat.gsfc.nasa.gov/about/the-worldwide-reference-system/
- Related Extensions: none
- Format String: WRS2-{path}{row}
- Example: WRS2-097073
- Components:
- path: path number for nominal satellite orbital tracks
- row: latitudinal center line of a frame of imagery
- Products: Landsat 4, 5, 7, 8, and 9
- Reference: https://landsat.gsfc.nasa.gov/about/the-worldwide-reference-system/
- Related Extensions: none
- Format String: DOQ-{quadrangle}
- Example: DOQ-3510836
- Components:
- quadrangle: code for the 7.5-minute quad
- Products: early USGS digital aerial photographs and satellite images
- Reference: https://en.wikipedia.org/wiki/Digital_orthophoto_quadrangle
- Related Extensions: none
Represents one U.S. Geological Survey (USGS) 7.5-minute quadrangle. The names are based on that of the 7.5-minute quad.
- Format String: DOQQ-{quadrangle}{quarter}
- Example: DOQQ-3510836SE
- Components:
- quadrangle: code for the 7.5-minute quad
- quarter: NW, NE, SE, SW
- Products: NAIP
- Reference: https://en.wikipedia.org/wiki/Digital_orthophoto_quadrangle
- Related Extensions: none
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.
- Format String: MXRA-Z{zone}-{quadkey}
- Example: MXRA-Z14-120200003323
- Components:
- zone: UTM zone
- quadkey: 12-digit quadkey identifier
- Products: Maxar ARD images and derivatives
- Reference: Maxar ARD Documentation
- Related Extensions: none
- Format String: EASE-DGGS-L{level}.{row-column for each level}
- Example: EASE-DGGS-L0.405963, EASE-DGGS-L6.405963.33.22.22.99.99.99
- Components:
- level: Grid refinement level. Ranges from 0 to 6 with 6 being the most granular level.
- row-column for each level: Grid cell row-column for each level in ascending level order (level 0 first), separated by ".".
- Products:
- Reference: https://www.tandfonline.com/doi/pdf/10.1080/20964471.2021.2017539
- Related Extensions: none
- Format String: CDEM-{northing}{easting}
- Example: CDEM-S90W178
- Components:
- northing: latitude coordinate in decimal degrees without the decimal
_00
part, e.g.,S50
. - easting: longitude coordinate in decimal degrees without the decimal
_00
part, e.g.,W125
.
- northing: latitude coordinate in decimal degrees without the decimal
- Products: Copernicus DEM GLO-30, GLO-90, and EEA-10 products in DGED format
- Reference: Copernicus DEM Product Handbook
- Related Extensions: none
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.
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
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:
- 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. - 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.
- Coordinate precision is set to 2 decimal places, which means it varies by no more than 1km at the equator.
- JSON is output in compact mode, with no line breaks, indentation, or spaces around the
:
and,
characters.
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
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
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
These are all Polygons and within CONUS (no antimeridian-spanning cells).
To process:
- Download all 48 (AK and HI are excluded) from NAIP: NAIP Quarter Quad and Seamline Shapefiles and put them in the scripts directory.
- 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.