diff --git a/CHANGELOG.md b/CHANGELOG.md index 0632361..64ebc51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- A new Spatial Vector Cube Dimension for geometries + ## [v2.1.0] - 2022-07-26 ### Added diff --git a/README.md b/README.md index 87064a3..90dcb2d 100644 --- a/README.md +++ b/README.md @@ -41,14 +41,14 @@ certain values, too. `extent`, `values` and `step` share the same definition, bu depending on the type of dimension. Whenever it's useful to specify these fields, the objects add the additional fields `reference_system` and `unit` with very similar definitions across the objects. -### Horizontal Spatial Dimension Object +### Horizontal Spatial Raster Dimension Object -A spatial dimension in one of the horizontal (x or y) directions. +A spatial raster dimension in one of the horizontal (x or y) directions. | Field Name | Type | Description | | ---------------- | -------------- | ------------------------------------------------------------ | | type | string | **REQUIRED.** Type of the dimension, always `spatial`. | -| axis | string | **REQUIRED.** Axis of the spatial dimension (`x`, `y`). | +| axis | string | **REQUIRED.** Axis of the spatial raster dimension (`x`, `y`). | | description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | extent | \[number] | **REQUIRED.** Extent (lower and upper bounds) of the dimension as two-element array. Open intervals with `null` are not allowed. | | values | \[number] | Optionally, an ordered list of all values. | @@ -85,13 +85,29 @@ A temporal dimension based on the ISO 8601 standard. The temporal reference syst | values | \[string] | If the dimension consists of an ordered list of specific values they can be listed here. The dates and/or times must be strings compliant to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | | step | string\|null | The space between the temporal instances as [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations), e.g. `P1D`. Use `null` for irregularly spaced steps. | +### Spatial Vector Dimension Object + +A vector dimension that defines a spatial dimension based on geometries. + +| Field Name | Type | Description | +| ---------------- | -------------- | ------------------------------------------------------------ | +| type | string | **REQUIRED.** Type of the dimension, always `geometries`. | +| axes | \[string] | Axes of the vector dimension as an ordered set of `x`, `y` and `z`. Defaults to `x` and `y`. | +| description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| bbox | \[number] | **REQUIRED.** A single bounding box of the geometries as defined for [STAC Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#spatial-extent-object), but not nested. | +| values | \[string\] | Optionally, a representation of the geometries. This could be a list of WKT strings or other identifiers. | +| geometry_types | \[[GeoJSON Types](https://www.rfc-editor.org/rfc/rfc7946#section-1.4)] | A set of geometry types. If not present, mixed geometry types must be assumed. | +| reference_system | string\|number\|object | The spatial reference system for the data, specified as [numerical EPSG code](http://www.epsg-registry.org/), [WKT2 (ISO 19162) string](http://docs.opengeospatial.org/is/18-010r7/18-010r7.html) or [PROJJSON object](https://proj.org/specifications/projjson.html). Defaults to EPSG code 4326. | + +For a general explanation what a vector datacube and a vector dimension is, please read the article "[Vector Data Cubes](https://r-spatial.org/r/2022/09/12/vdc.html)". + ### Additional Dimension Object An additional dimension that is not `spatial`, but may be `temporal` if the data is not compliant with ISO 8601 (see below). | Field Name | Type | Description | | ---------------- | ----------------- | ------------------------------------------------------------ | -| type | string | **REQUIRED.** Custom type of the dimension, never `spatial`. | +| type | string | **REQUIRED.** Custom type of the dimension, never `spatial` or `geometries`. | | description | string | Detailed multi-line description to explain the dimension. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | extent | \[number\|null] | If the dimension consists of [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values, the extent (lower and upper bounds) of the values as two-element array. Use `null` for open intervals. | | values | \[number\|string] | An ordered list of all values, especially useful for [nominal](https://en.wikipedia.org/wiki/Level_of_measurement#Nominal_level) values. | diff --git a/examples/vector.json b/examples/vector.json new file mode 100644 index 0000000..9a5eabd --- /dev/null +++ b/examples/vector.json @@ -0,0 +1,176 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/datacube/v2.1.0/schema.json" + ], + "id": "vector-datacube", + "type": "Feature", + "geometry": { + "type": "MultiPolygon", + "coordinates": [ + [ + [ + [ + -122.40863800048828, + 37.60280825923639 + ], + [ + -122.35301971435545, + 37.60280825923639 + ], + [ + -122.35301971435545, + 37.641694203264265 + ], + [ + -122.40863800048828, + 37.641694203264265 + ], + [ + -122.40863800048828, + 37.60280825923639 + ] + ] + ], + [ + [ + [ + -122.51575469970703, + 37.50373410549169 + ], + [ + -122.48313903808594, + 37.50373410549169 + ], + [ + -122.48313903808594, + 37.52443079581378 + ], + [ + -122.51575469970703, + 37.52443079581378 + ], + [ + -122.51575469970703, + 37.50373410549169 + ] + ] + ], + [ + [ + [ + -122.26203918457031, + 37.69726847113855 + ], + [ + -122.19577789306639, + 37.69726847113855 + ], + [ + -122.19577789306639, + 37.747507619675595 + ], + [ + -122.26203918457031, + 37.747507619675595 + ], + [ + -122.26203918457031, + 37.69726847113855 + ] + ] + ], + [ + [ + [ + -122.13415145874025, + 37.65175228874552 + ], + [ + -122.10994720458984, + 37.65175228874552 + ], + [ + -122.10994720458984, + 37.66765215806202 + ], + [ + -122.13415145874025, + 37.66765215806202 + ], + [ + -122.13415145874025, + 37.65175228874552 + ] + ] + ] + ] + }, + "bbox": [ + -122.51575469970703, + 37.50373410549169, + -122.10994720458984, + 37.747507619675595 + ], + "properties": { + "title": "Multi-dimensional vector data cube in a STAC Item.", + "start_datetime": "2016-01-01T00:00:00Z", + "datetime": "2017-01-01T00:00:00Z", + "end_datetime": "2018-01-01T00:00:00Z", + "cube:dimensions": { + "vector": { + "type": "geometries", + "bbox": [ + -122.51575469970703, + 37.50373410549169, + -122.10994720458984, + 37.747507619675595 + ], + "values": [ + "POLYGON ((-122.40863800048828 37.60280825923639, -122.35301971435545 37.60280825923639, -122.35301971435545 37.641694203264265, -122.40863800048828 37.641694203264265, -122.40863800048828 37.60280825923639))", + "POLYGON ((-122.51575469970703 37.50373410549169, -122.48313903808594 37.50373410549169, -122.48313903808594 37.52443079581378, -122.51575469970703 37.52443079581378, -122.51575469970703 37.50373410549169))", + "POLYGON ((-122.26203918457031 37.69726847113855, -122.19577789306639 37.69726847113855, -122.19577789306639 37.747507619675595, -122.26203918457031 37.747507619675595, -122.26203918457031 37.69726847113855))", + "POLYGON ((-122.13415145874025 37.65175228874552, -122.10994720458984 37.65175228874552, -122.10994720458984 37.66765215806202, -122.13415145874025 37.66765215806202, -122.13415145874025 37.65175228874552))" + ], + "geometry_types": [ + "Polygon" + ], + "reference_system": 4326 + }, + "t": { + "type": "temporal", + "values": [ + "2016-01-01T00:00:00Z", + "2017-01-01T00:00:00Z", + "2018-01-01T00:00:00Z" + ] + }, + "stats": { + "type": "statistics", + "values": [ + "min", + "max", + "mean" + ] + } + } + }, + "assets": { + "data": { + "href": "http://cool-sat.com/catalog/datacube/data.nc", + "type": "application/netcdf", + "title": "netCDF Data cube" + }, + "thumbnail": { + "href": "http://cool-sat.com/catalog/datacube/thumbnail.png", + "type": "image/png", + "title": "Thumbnail" + } + }, + "links": [ + { + "rel": "self", + "href": "http://cool-sat.com/catalog/datacube/vector.json" + } + ] +} \ No newline at end of file diff --git a/json-schema/schema.json b/json-schema/schema.json index 68db0ae..7d611b8 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -210,7 +210,7 @@ "additionalProperties": { "anyOf": [ { - "$ref": "#/definitions/additional_dimension" + "$ref": "#/definitions/vector_dimension" }, { "$ref": "#/definitions/horizontal_spatial_dimension" @@ -220,6 +220,9 @@ }, { "$ref": "#/definitions/temporal_dimension" + }, + { + "$ref": "#/definitions/additional_dimension" } ] } @@ -254,17 +257,13 @@ }, "properties": { "type": { - "allOf": [ - { - "type": "string" - }, - { - "not": { - "type": "string", - "const": "spatial" - } - } - ] + "type": "string", + "not": { + "enum": [ + "spatial", + "geometries" + ] + } }, "description": { "$ref": "#/definitions/description" @@ -295,7 +294,7 @@ } }, "horizontal_spatial_dimension": { - "title": "Horizontal Spatial Dimension Object", + "title": "Horizontal Spatial Raster Dimension Object", "type": "object", "required": [ "type", @@ -372,6 +371,86 @@ } } }, + "vector_dimension": { + "title": "Spatial Vector Dimension Object", + "type": "object", + "required": [ + "type", + "bbox" + ], + "properties": { + "type": { + "type": "string", + "const": "geometries" + }, + "axes": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "enum": [ + "x", + "y", + "z" + ] + } + }, + "description": { + "$ref": "#/definitions/description" + }, + "bbox": { + "title": "Spatial extent", + "type": "array", + "oneOf": [ + { + "minItems":4, + "maxItems":4 + }, + { + "minItems":6, + "maxItems":6 + } + ], + "items": { + "type": "number" + } + }, + "values": { + "type": "array", + "minItems": 1, + "items": { + "oneOf": [ + { + "$ref": "https://geojson.org/schema/GeoJSON.json" + }, + { + "description": "ID or WKT", + "type": "string" + } + ] + } + }, + "geometry_types": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "enum": [ + "Point", + "MultiPoint", + "LineString", + "MultiLineString", + "Polygon", + "MultiPolygon", + "GeometryCollection" + ] + } + }, + "reference_system": { + "$ref": "#/definitions/reference_system_spatial" + } + } + }, "temporal_dimension": { "title": "Temporal Dimension Object", "type": "object",