Adds support for IAU codes. #12
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -37,7 +37,7 @@ The fields in the table below can be used in these parts of STAC documents: | |
|
|
||
| | Field Name | Type | Description | | ||
| | ---------------- | ------------------------ | ----------- | | ||
| | proj:code | string\|null | Authority and specific code of the data source (e.g., ["EPSG:####"](https://epsg.org/), ["IAU:#####"](http://www.opengis.net/def/crs/IAU/2015)) | | ||
|
||
| | proj:wkt2 | string\|null | [WKT2](http://docs.opengeospatial.org/is/12-063r5/12-063r5.html) string representing the Coordinate Reference System (CRS) that the `proj:geometry` and `proj:bbox` fields represent | | ||
| | proj:projjson | [PROJJSON Object](https://proj.org/specifications/projjson.html)\|null | PROJJSON object representing the Coordinate Reference System (CRS) that the `proj:geometry` and `proj:bbox` fields represent | | ||
| | proj:geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) | Defines the footprint of this Item. | | ||
|
|
@@ -47,34 +47,59 @@ The fields in the table below can be used in these parts of STAC documents: | |
| | proj:transform | \[number] | The affine transformation coefficients for the default grid | | ||
|
|
||
| At least one of the fields MUST be specified, but it is RECOMMENDED to provide more information as detailed in the | ||
| [Best Practices section](#best-practices) so that, for example, GDAL can read your data without issues. | ||
|
|
||
| Generally, it is preferrable to provide the projection information on the Asset level | ||
| as they are specific to assets and may not apply to all assets. | ||
| For example, if you provide a smaller and unlocated thumbnail, having the projection information in the Item Properties | ||
| would imply that the projection information also applies to the thumbnail if not specified otherwise in the asset. | ||
| You may want to add the `proj:code` to the Item Properties though as this would provide an easy way to | ||
| filter for specific projection codes in an API. In this case you could override the `proj:code` for the thumbnail on the asset level. | ||
|
|
||
| ### Additional Field Information | ||
|
|
||
| #### proj:epsg | ||
|
|
||
| **Notice**: This field has been removed in V2.0.0. See [proj:epsg Migration to V2](#projepsg-migration-to-projcode). | ||
|
|
||
| #### proj:epsg migration to proj:code | ||
| `proj:epsg` is removed in version 2.0.0 of this extension. Please use `proj:code`. For example, the following: | ||
|
|
||
| ```json | ||
| { | ||
| ... | ||
| "proj:epsg": 32659, | ||
| ... | ||
| } | ||
| ``` | ||
| would be represented as: | ||
| ```json | ||
| { | ||
| ... | ||
| "proj:code": "EPSG:32659", | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| #### proj:code | ||
jlaura marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Projection codes are identified by a string. The [proj](https://proj.org/) library defines projections | ||
| using "authority:code", e.g., "EPSG:4326" or "IAU_2015:30100". Different projection authorities may define | ||
| different string formats. Examples of known projection authorities, where when can find well known codes that | ||
| clients are likely to support are listed in the following table. | ||
|
|
||
| | Authority Name | URL | | ||
|
||
| | -------------- | --- | | ||
| | European Petroleum Survey Groups (EPSG) | http://www.opengis.net/def/crs/EPSG or http://epsg.org | | ||
| | International Astronomical Union (IAU) | http://www.opengis.net/def/crs/IAU/2015 | | ||
| | Open Geospatial Consortium (OGC) | http://www.opengis.net/def/crs/OGC | | ||
|
|
||
| The `proj:code` field SHOULD be set to `null` in the following cases: | ||
| - The asset data does not have a CRS, such as in the case of non-rectified imagery with Ground Control Points. | ||
| - A CRS exists, but there is no valid EPSG code for it. In this case, the CRS should be provided in `proj:wkt2` and/or `proj:projjson`. | ||
| Clients can prefer to take either, although there may be discrepancies in how each might be interpreted. | ||
|
|
||
|
|
||
| #### proj:wkt2 | ||
|
|
||
| A Coordinate Reference System (CRS) is the data reference system (sometimes called a 'projection') | ||
|
|
@@ -98,14 +123,14 @@ This field SHOULD be set to `null` in the following cases: | |
|
|
||
| A GeoJSON Geometry object as defined in [RFC 7946, sections 3.1](https://tools.ietf.org/html/rfc7946) | ||
| representing the footprint of this Item, except not necessarily in EPSG:4326 as required by RFC7946. | ||
| Specified based on the `proj:code`, `proj:projjson` or `proj:wkt2` fields (not necessarily EPSG:4326). | ||
| Usually, this will be represented by a Polygon with five coordinates, as the item in the asset data CRS should be | ||
| a square aligned to the original CRS grid. | ||
|
|
||
| #### proj:bbox | ||
|
|
||
| Bounding box of the assets represented by this Item in the asset data CRS. Specified as 4 or 6 | ||
| coordinates based on the CRS defined in the `proj:code`, `proj:projjson` or `proj:wkt2` fields. First two numbers are coordinates | ||
| of the lower left corner, followed by coordinates of upper right corner, , e.g., \[west, south, east, north], | ||
| \[xmin, ymin, xmax, ymax], \[left, down, right, up], or \[west, south, lowest, east, north, highest]. | ||
| The length of the array must be 2\*n where n is the number of dimensions. The array contains all axes of the southwesterly | ||
|
|
@@ -170,29 +195,35 @@ This object represents the centroid of the Item Geometry. | |
| There are several projection extension fields with potentially overlapping functionality. This section attempts to | ||
| give an overview of which ones you should consider using. They fit into three general categories: | ||
|
|
||
| - **Description of the coordinate reference system:** [proj:code](#projcode) is recommended, but it is just a | ||
| reference to known projection information. [WKT2](#projwkt2) and [PROJJSON](#projprojjson) are two options to | ||
| fully describe the projection information. | ||
|
|
||
| This is typically done for projections that aren't available or fully described in a known registry | ||
| (e.g., [EPSG Registry](https://epsg.org/) or [IAU Registry](http://www.opengis.net/def/crs/IAU/2015)). | ||
|
|
||
| For example, the MODIS Sinusoidal projection does not have an EPSG code, but can be described using WKT2 or PROJJSON. | ||
| - **Description of the native geometry information:** STAC requires the geometry and bounding box, but they are only available | ||
| in lat/long (EPSG:4326, IAU_2015:30100, IAU_2015:49900, etc.). But most remote sensing data does not come in | ||
| that projection, so it is often useful for clients to have | ||
| the geometry information ([geometry](#projgeometry), [bbox](#projbbox), [centroid](#projcentroid)) in the coordinate reference system | ||
| of the asset's data, so it doesn't have to reproject (which can be lossy and takes time). | ||
| - **Information to enable cataloging of data without opening assets:** Often it is useful to be able to construct a 'virtual layer', | ||
| like GDAL's [VRT](https://gdal.org/drivers/raster/vrt.html) without having to open the actual imagery file. [shape](#projshape) and | ||
| [transform](#projtransform) together with the core description of the CRS provide enough information about the size and shape of | ||
| the data in the file so that tools don't have to open it. | ||
|
|
||
| For example, the GDAL implementation [requires](https://twitter.com/EvenRouault/status/1419752806735568902) | ||
| the following fields: | ||
| 1. `proj:wkt2` or `proj:projjson` (one of them filled with non-null values) | ||
gadomski marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| 2. Any of the following: | ||
| - `proj:transform` and `proj:shape` | ||
| - `proj:transform` and `proj:bbox` | ||
| - `proj:bbox` and `proj:shape` | ||
|
|
||
| None of these are necessary for 'search' of data, the main use case of STAC. But all enable more 'cloud native' use of data, as they | ||
| describe the metadata needed to stream data for processing and/or display on the web. We do recommend including at least the code if it's | ||
| available, as it's a fairly standard piece of metadata, and [see below](#crs-description-recommendations) for more | ||
| information about when to use WKT and PROJJSON. We do recommend including the shape and transform fields if you have cloud | ||
| optimized geotiff's or some other cloud native format, to enable online tools to work with the assets more efficiently. This is | ||
| especially useful if the data is likely to be mosaiced or otherwise processed together, so that tools don't have to open every | ||
|
|
@@ -202,15 +233,15 @@ we provide it because some modern systems are just using STAC for their entire m | |
|
|
||
| ### CRS Description Recommendations | ||
|
|
||
| WKT2 and PROJJSON are mostly recommended when you have data that is not part of a standard registry. Providing one of them | ||
| supplies the exact information for projection software to do the exact projection transform. | ||
| WKT2 and PROJJSON are equivalent to one another - more clients understand WKT2, but PROJJSON fits more nicely in the STAC JSON | ||
| structure, since they are both JSON. For now it's probably best to use both for maximum interoperability, but just using PROJJSON | ||
| is likely ok if you aren't worried about legacy client support. | ||
|
|
||
| ### Thumbnails | ||
|
|
||
| For (unlocated) thumbnails and similar imagery, it is recommended set `proj:code` to `null` and include `proj:shape` | ||
| so that | ||
| 1. clients can read the image dimensions upfront (and reserve space for them), and | ||
| 2. you explicitly state that the thumbnail is not geolocated. | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -47,7 +47,7 @@ | |
| "cool_sensor_v1" | ||
| ], | ||
| "gsd": 0.66, | ||
| "proj:code": "EPSG:32659", | ||
| "proj:shape": [ | ||
| 5558, | ||
| 9559 | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| { | ||
m-mohr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "stac_version": "1.0.0", | ||
| "stac_extensions": [ | ||
| "https://stac-extensions.github.io/projection/v1.1.0/schema.json" | ||
| ], | ||
| "type": "Feature", | ||
| "id": "20201211_223832_CS2", | ||
| "bbox": [ | ||
| 172.91173669923782, | ||
| 1.3438851951615003, | ||
| 172.95469614953714, | ||
| 1.3690476620161975 | ||
| ], | ||
| "geometry": { | ||
| "type": "Polygon", | ||
| "coordinates": [ | ||
| [ | ||
| [ | ||
| 172.91173669923782, | ||
| 1.3438851951615003 | ||
| ], | ||
| [ | ||
| 172.95469614953714, | ||
| 1.3438851951615003 | ||
| ], | ||
| [ | ||
| 172.95469614953714, | ||
| 1.3690476620161975 | ||
| ], | ||
| [ | ||
| 172.91173669923782, | ||
| 1.3690476620161975 | ||
| ], | ||
| [ | ||
| 172.91173669923782, | ||
| 1.3438851951615003 | ||
| ] | ||
| ] | ||
| ] | ||
| }, | ||
| "properties": { | ||
| "datetime": "2020-12-11T22:38:32.125Z", | ||
| "created": "2020-12-12T01:48:13.725Z", | ||
| "updated": "2020-12-12T01:48:13.725Z", | ||
| "platform": "cool_sat2", | ||
| "instruments": [ | ||
| "cool_sensor_v1" | ||
| ], | ||
| "gsd": 0.66, | ||
| "proj:code": "IAU_2015:49900", | ||
| "proj:shape": [ | ||
| 5558, | ||
| 9559 | ||
| ], | ||
| "proj:transform": [ | ||
| 0.5, | ||
| 0, | ||
| 712710, | ||
| 0, | ||
| -0.5, | ||
| 151406, | ||
| 0, | ||
| 0, | ||
| 1 | ||
| ] | ||
| }, | ||
| "links": [ | ||
| { | ||
| "href": "./collection.json", | ||
| "rel": "collection", | ||
| "type": "application/json" | ||
| } | ||
| ], | ||
| "assets": { | ||
| "analytic": { | ||
| "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic.tif", | ||
| "type": "image/tiff; application=geotiff; profile=cloud-optimized", | ||
| "title": "4-Band Analytic", | ||
| "roles": [ | ||
| "data" | ||
| ] | ||
| }, | ||
| "visual": { | ||
| "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2.tif", | ||
| "type": "image/tiff; application=geotiff; profile=cloud-optimized", | ||
| "title": "3-Band Visual", | ||
| "roles": [ | ||
| "visual" | ||
| ] | ||
| } | ||
| }, | ||
| "collection": "proj-example" | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.