From 849b6115de2f0d74471f8f27d150d771d6806111 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 18 Jan 2023 17:52:35 +0100 Subject: [PATCH] Update processes according to discussions --- CHANGELOG.md | 4 ++-- add_dimension.json | 2 +- aggregate_spatial.json | 8 ++++---- filter_bbox.json | 4 ++-- filter_spatial.json | 4 ++-- load_collection.json | 2 +- mask.json | 2 +- mask_polygon.json | 5 ++--- merge_cubes.json | 5 ++++- proposals/filter_labels.json | 2 +- proposals/filter_vector.json | 14 +++++--------- proposals/fit_class_random_forest.json | 4 ++-- proposals/fit_regr_random_forest.json | 4 ++-- proposals/load_result.json | 2 +- proposals/vector_buffer.json | 6 +++--- proposals/vector_to_random_points.json | 6 +++--- proposals/vector_to_regular_points.json | 6 +++--- tests/testHelpers.js | 4 ++-- 18 files changed, 41 insertions(+), 43 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b465fc2..a386952c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Update the processes based on `raster-cube` or `vector-cube` to work with `datacube` instead - Rename `create_raster_cube` to `create_data_cube` -- `add_dimension`: Added new dimension type `vector` +- `add_dimension`: Added new dimension type `geometries` - New definition for `aggregate_spatial`: - Allows more than 3 input dimensions - Allow to not export statistics by changing the parameter `target_dimension` @@ -53,7 +53,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed - `aggregate_spatial`: - - Clarified that vector properties are preserved for vector data cubes and all GeoJSON Features. [#270](https://github.com/Open-EO/openeo-processes/issues/270) + - Clarified that feature properties are preserved for vector data cubes and all GeoJSON Features. [#270](https://github.com/Open-EO/openeo-processes/issues/270) - Clarified that a `TargetDimensionExists` exception is thrown if the target dimension exists. - `apply` and `array_apply`: Fixed broken references to the `absolute` process - `apply_neighborhood`: Parameter `overlap` was optional but had no default value and no schena for the default value defined. diff --git a/add_dimension.json b/add_dimension.json index a7c76d13..b156846b 100644 --- a/add_dimension.json +++ b/add_dimension.json @@ -40,9 +40,9 @@ "type": "string", "enum": [ "bands", + "geometries", "spatial", "temporal", - "vector", "other" ] }, diff --git a/aggregate_spatial.json b/aggregate_spatial.json index 1842649d..bda108dc 100644 --- a/aggregate_spatial.json +++ b/aggregate_spatial.json @@ -26,7 +26,7 @@ }, { "name": "geometries", - "description": "Geometries for which the aggregation will be computed. Vector properties are preserved for vector data cubes and all GeoJSON Features.\n\nOne value will be computed per label in the dimension of type `vector`, GeoJSON `Feature`, `Geometry` or `GeometryCollection`. For a `FeatureCollection` multiple values will be computed, one value per contained `Feature`. For example, a single value will be computed for a `MultiPolygon`, but two values will be computed for a `FeatureCollection` containing two polygons.\n\n- For **polygons**, the process considers all pixels for which the point at the pixel center intersects with the corresponding polygon (as defined in the Simple Features standard by the OGC).\n- For **points**, the process considers the closest pixel center.\n- For **lines** (line strings), the process considers all the pixels whose centers are closest to at least one point on the line.\n\nThus, pixels may be part of multiple geometries and be part of multiple aggregations.\n\nTo maximize interoperability, a nested `GeometryCollection` should be avoided. Furthermore, a `GeometryCollection` composed of a single type of geometries should be avoided in favour of the corresponding multi-part type (e.g. `MultiPolygon`).", + "description": "Geometries for which the aggregation will be computed. Feature properties are preserved for vector data cubes and all GeoJSON Features.\n\nOne value will be computed per label in the dimension of type `geometries`, GeoJSON `Feature`, `Geometry` or `GeometryCollection`. For a `FeatureCollection` multiple values will be computed, one value per contained `Feature`. For example, a single value will be computed for a `MultiPolygon`, but two values will be computed for a `FeatureCollection` containing two polygons.\n\n- For **polygons**, the process considers all pixels for which the point at the pixel center intersects with the corresponding polygon (as defined in the Simple Features standard by the OGC).\n- For **points**, the process considers the closest pixel center.\n- For **lines** (line strings), the process considers all the pixels whose centers are closest to at least one point on the line.\n\nThus, pixels may be part of multiple geometries and be part of multiple aggregations. No operation is applied to geometries that are outside of the bounds of the data.\n\nTo maximize interoperability, a nested `GeometryCollection` should be avoided. Furthermore, a `GeometryCollection` composed of a single type of geometries should be avoided in favour of the corresponding type (e.g. `MultiPolygon`).", "schema": [ { "type": "object", @@ -37,7 +37,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -101,13 +101,13 @@ } ], "returns": { - "description": "A vector data cube with the computed results and restricted to the bounds of the geometries. The spatial dimensions is replaced by a vector dimension and if `target_dimension` is not `null`, a new dimension is added.", + "description": "A vector data cube with the computed results and restricted to the bounds of the geometries. The spatial dimensions is replaced by a geometries dimension and if `target_dimension` is not `null`, a new dimension is added.", "schema": { "type": "object", "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } diff --git a/filter_bbox.json b/filter_bbox.json index 436833c7..818bcaaa 100644 --- a/filter_bbox.json +++ b/filter_bbox.json @@ -31,7 +31,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -135,7 +135,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } diff --git a/filter_spatial.json b/filter_spatial.json index 8d9db74b..1e0a1e49 100644 --- a/filter_spatial.json +++ b/filter_spatial.json @@ -1,7 +1,7 @@ { "id": "filter_spatial", "summary": "Spatial filter raster data cubes using geometries", - "description": "Limits the raster data cube over the spatial dimensions to the specified geometries.\n\n- For **polygons**, the filter retains a pixel in the data cube if the point at the pixel center intersects with at least one of the polygons (as defined in the Simple Features standard by the OGC).\n- For **points**, the process considers the closest pixel center.\n- For **lines** (line strings), the process considers all the pixels whose centers are closest to at least one point on the line.\n\nMore specifically, pixels outside of the bounding box of the given geometry will not be available after filtering. All pixels inside the bounding box that are not retained will be set to `null` (no data).", + "description": "Limits the raster data cube over the spatial dimensions to the specified geometries.\n\n- For **polygons**, the filter retains a pixel in the data cube if the point at the pixel center intersects with at least one of the polygons (as defined in the Simple Features standard by the OGC).\n- For **points**, the process considers the closest pixel center.\n- For **lines** (line strings), the process considers all the pixels whose centers are closest to at least one point on the line.\n\nMore specifically, pixels outside of the bounding box of the given geometry will not be available after filtering. All pixels inside the bounding box that are not retained will be set to `null` (no data).\n\n Alternatively, use ``filter_bbox()`` to filter by bounding box.", "categories": [ "cubes", "filter" @@ -37,7 +37,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } diff --git a/load_collection.json b/load_collection.json index 3759ab56..d9fdc5d6 100644 --- a/load_collection.json +++ b/load_collection.json @@ -104,7 +104,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] }, diff --git a/mask.json b/mask.json index 06e43d67..d5940b25 100644 --- a/mask.json +++ b/mask.json @@ -1,7 +1,7 @@ { "id": "mask", "summary": "Apply a raster mask", - "description": "Applies a mask to a raster data cube. To apply a vector mask use ``mask_polygon()``.\n\nA mask is a raster data cube for which corresponding pixels among `data` and `mask` are compared and those pixels in `data` are replaced whose pixels in `mask` are non-zero (for numbers) or `true` (for boolean values). The pixel values are replaced with the value specified for `replacement`, which defaults to `null` (no data).\n\nThe data cubes have to be compatible so that each dimension in the mask must also be available in the raster data cube with the same name, type, reference system, resolution and labels. Dimensions can be missing in the mask with the result that the mask is applied to each label of the dimension in `data` that is missing in the data cube of the mask. The process fails if there's an incompatibility found between the raster data cube and the mask.", + "description": "Applies a mask to a raster data cube. To apply a polygon as a mask, use ``mask_polygon()``.\n\nA mask is a raster data cube for which corresponding pixels among `data` and `mask` are compared and those pixels in `data` are replaced whose pixels in `mask` are non-zero (for numbers) or `true` (for boolean values). The pixel values are replaced with the value specified for `replacement`, which defaults to `null` (no data).\n\nThe data cubes have to be compatible so that each dimension in the mask must also be available in the raster data cube with the same name, type, reference system, resolution and labels. Dimensions can be missing in the mask with the result that the mask is applied to each label of the dimension in `data` that is missing in the data cube of the mask. The process fails if there's an incompatibility found between the raster data cube and the mask.", "categories": [ "cubes", "masks" diff --git a/mask_polygon.json b/mask_polygon.json index c46d17af..be545ae8 100644 --- a/mask_polygon.json +++ b/mask_polygon.json @@ -37,11 +37,10 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector", + "type": "geometries", "geometry_type": [ "Polygon", - "MultiPolygon", - "GeometryCollection" + "MultiPolygon" ] } ] diff --git a/merge_cubes.json b/merge_cubes.json index 655609bb..e41d5f2e 100644 --- a/merge_cubes.json +++ b/merge_cubes.json @@ -1,7 +1,7 @@ { "id": "merge_cubes", "summary": "Merge two data cubes", - "description": "The process performs the join on overlapping dimensions. The data cubes have to be compatible. A merge operation without overlap should be reversible with (a set of) filter operations for each of the two cubes. As such it is not possible to merge a vector and a raster data cube.\n\nOverlapping dimensions have the same name, type, reference system and resolution, but can have different labels. One of the dimensions can have different labels, for all other dimensions the labels must be equal. Equality for vector labels follows the definition in the Simple Features standard by the OGC. If data overlaps, the parameter `overlap_resolver` must be specified to resolve the overlap.\n\n**Examples for merging two data cubes:**\n\n1. Data cubes with the dimensions (`x`, `y`, `t`, `bands`) have the same dimension labels in `x`, `y` and `t`, but the labels for the dimension `bands` are `B1` and `B2` for the first cube and `B3` and `B4`. An overlap resolver is *not needed*. The merged data cube has the dimensions `x`, `y`, `t` and `bands` and the dimension `bands` has four dimension labels: `B1`, `B2`, `B3`, `B4`.\n2. Data cubes with the dimensions (`x`, `y`, `t`, `bands`) have the same dimension labels in `x`, `y` and `t`, but the labels for the dimension `bands` are `B1` and `B2` for the first data cube and `B2` and `B3` for the second. An overlap resolver is *required* to resolve overlap in band `B2`. The merged data cube has the dimensions `x`, `y`, `t` and `bands` and the dimension `bands` has three dimension labels: `B1`, `B2`, `B3`.\n3. Data cubes with the dimensions (`x`, `y`, `t`) have the same dimension labels in `x`, `y` and `t`. There are two options:\n 1. Keep the overlapping values separately in the merged data cube: An overlap resolver is *not needed*, but for each data cube you need to add a new dimension using ``add_dimension()``. The new dimensions must be equal, except that the labels for the new dimensions must differ by name. The merged data cube has the same dimensions and labels as the original data cubes, plus the dimension added with ``add_dimension()``, which has the two dimension labels after the merge.\n 2. Combine the overlapping values into a single value: An overlap resolver is *required* to resolve the overlap for all values. The merged data cube has the same dimensions and labels as the original data cubes, but all values have been processed by the overlap resolver.\n4. A data cube with dimensions (`x`, `y`, `t` / `bands`) or (`x`, `y`, `t`, `bands`) and another data cube with dimensions (`x`, `y`) have the same dimension labels in `x` and `y`. Merging them will join dimensions `x` and `y`, so the lower dimension cube is merged with each time step and band available in the higher dimensional cube. This can for instance be used to apply a digital elevation model to a spatio-temporal data cube. An overlap resolver is *required* to resolve the overlap for all pixels.\n\nAfter the merge, the dimensions with a natural/inherent label order (with a reference system this is each spatial and temporal dimensions) still have all dimension labels sorted. For other dimensions where there is no inherent order, including bands, the dimension labels keep the order in which they are present in the original data cubes and the dimension labels of `cube2` are appended to the dimension labels of `cube1`.", + "description": "The process performs the join on overlapping dimensions. The data cubes have to be compatible. A merge operation without overlap should be reversible with (a set of) filter operations for each of the two cubes. As such it is not possible to merge a vector and a raster data cube. It is also not possible to merge vector data cubes that contain different base geometry types (points, lines/line strings, polygons). The base geometry types can be merged with their corresponding multi geometry types. In case of such a conflict, the `IncompatibleGeometryTypes` exception is thrown.\n\nOverlapping dimensions have the same name, type, reference system and resolution, but can have different labels. One of the dimensions can have different labels, for all other dimensions the labels must be equal. Equality for geometries follows the definition in the Simple Features standard by the OGC. If data overlaps, the parameter `overlap_resolver` must be specified to resolve the overlap.\n\n**Examples for merging two data cubes:**\n\n1. Data cubes with the dimensions (`x`, `y`, `t`, `bands`) have the same dimension labels in `x`, `y` and `t`, but the labels for the dimension `bands` are `B1` and `B2` for the first cube and `B3` and `B4`. An overlap resolver is *not needed*. The merged data cube has the dimensions `x`, `y`, `t` and `bands` and the dimension `bands` has four dimension labels: `B1`, `B2`, `B3`, `B4`.\n2. Data cubes with the dimensions (`x`, `y`, `t`, `bands`) have the same dimension labels in `x`, `y` and `t`, but the labels for the dimension `bands` are `B1` and `B2` for the first data cube and `B2` and `B3` for the second. An overlap resolver is *required* to resolve overlap in band `B2`. The merged data cube has the dimensions `x`, `y`, `t` and `bands` and the dimension `bands` has three dimension labels: `B1`, `B2`, `B3`.\n3. Data cubes with the dimensions (`x`, `y`, `t`) have the same dimension labels in `x`, `y` and `t`. There are two options:\n 1. Keep the overlapping values separately in the merged data cube: An overlap resolver is *not needed*, but for each data cube you need to add a new dimension using ``add_dimension()``. The new dimensions must be equal, except that the labels for the new dimensions must differ by name. The merged data cube has the same dimensions and labels as the original data cubes, plus the dimension added with ``add_dimension()``, which has the two dimension labels after the merge.\n 2. Combine the overlapping values into a single value: An overlap resolver is *required* to resolve the overlap for all values. The merged data cube has the same dimensions and labels as the original data cubes, but all values have been processed by the overlap resolver.\n4. A data cube with dimensions (`x`, `y`, `t` / `bands`) or (`x`, `y`, `t`, `bands`) and another data cube with dimensions (`x`, `y`) have the same dimension labels in `x` and `y`. Merging them will join dimensions `x` and `y`, so the lower dimension cube is merged with each time step and band available in the higher dimensional cube. This can for instance be used to apply a digital elevation model to a spatio-temporal data cube. An overlap resolver is *required* to resolve the overlap for all pixels.\n\nAfter the merge, the dimensions with a natural/inherent label order (with a reference system this is each spatial and temporal dimensions) still have all dimension labels sorted. For other dimensions where there is no inherent order, including bands, the dimension labels keep the order in which they are present in the original data cubes and the dimension labels of `cube2` are appended to the dimension labels of `cube1`.", "categories": [ "cubes" ], @@ -83,6 +83,9 @@ "exceptions": { "OverlapResolverMissing": { "message": "Overlapping data cubes, but no overlap resolver has been specified." + }, + "IncompatibleGeometryTypes": { + "message": "The geometry types are not compatible and can't be merged." } }, "links": [ diff --git a/proposals/filter_labels.json b/proposals/filter_labels.json index cd077306..4b26fb1d 100644 --- a/proposals/filter_labels.json +++ b/proposals/filter_labels.json @@ -25,7 +25,7 @@ "parameters": [ { "name": "value", - "description": "A single dimension label to compare against. The data type of the parameter depends on the dimension labels set for the dimension.", + "description": "A single dimension label to compare against. The data type of the parameter depends on the dimension labels set for the dimension. Please note that for some dimension types a representation is used, e.g.\n\n* dates and/or times are usually strings compliant to [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601),\n* geometries can be a WKT string or an identifier.", "schema": [ { "type": "number" diff --git a/proposals/filter_vector.json b/proposals/filter_vector.json index 47cc2cc1..701a5549 100644 --- a/proposals/filter_vector.json +++ b/proposals/filter_vector.json @@ -1,7 +1,7 @@ { "id": "filter_vector", "summary": "Spatial vector filter using geometries", - "description": "Limits the vector data cube to the specified geometries. The process works on geometries as defined in the Simple Features standard by the OGC.", + "description": "Limits the vector data cube to the specified geometries. The process works on geometries as defined in the Simple Features standard by the OGC. Alternatively, use ``filter_bbox()`` to filter by bounding box.", "categories": [ "cubes", "filter", @@ -17,7 +17,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -35,7 +35,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -62,17 +62,13 @@ } ], "returns": { - "description": "A vector data cube restricted to the specified geometries. The dimensions and dimension properties (name, type, labels, reference system and resolution) remain unchanged, except that the vector dimension has less (or the same) dimension labels.", + "description": "A vector data cube restricted to the specified geometries. The dimensions and dimension properties (name, type, labels, reference system and resolution) remain unchanged, except that the geometries dimension has less (or the same) dimension labels.", "schema": { "type": "object", "subtype": "datacube", "dimensions": [ { - "type": "spatial", - "axis": [ - "x", - "y" - ] + "type": "geometries" } ] } diff --git a/proposals/fit_class_random_forest.json b/proposals/fit_class_random_forest.json index 11f0c9b9..f5995330 100644 --- a/proposals/fit_class_random_forest.json +++ b/proposals/fit_class_random_forest.json @@ -15,7 +15,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -28,7 +28,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } diff --git a/proposals/fit_regr_random_forest.json b/proposals/fit_regr_random_forest.json index f2a97ca7..a185e6d9 100644 --- a/proposals/fit_regr_random_forest.json +++ b/proposals/fit_regr_random_forest.json @@ -15,7 +15,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -28,7 +28,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } diff --git a/proposals/load_result.json b/proposals/load_result.json index 7906fd29..b2951740 100644 --- a/proposals/load_result.json +++ b/proposals/load_result.json @@ -115,7 +115,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] }, diff --git a/proposals/vector_buffer.json b/proposals/vector_buffer.json index 9ee12fa6..a7163964 100644 --- a/proposals/vector_buffer.json +++ b/proposals/vector_buffer.json @@ -9,7 +9,7 @@ "parameters": [ { "name": "geometries", - "description": "Geometries to apply the buffer on. Vector properties are preserved for vector data cubes and all GeoJSON Features.\n\nTo maximize interoperability, a nested `GeometryCollection` should be avoided. Furthermore, a `GeometryCollection` composed of a single type of geometries should be avoided in favour of the corresponding multi-part type (e.g. `MultiPolygon`).", + "description": "Geometries to apply the buffer on. Feature properties are preserved for vector data cubes and all GeoJSON Features.\n\nTo maximize interoperability, a nested `GeometryCollection` should be avoided. Furthermore, a `GeometryCollection` composed of a single type of geometries should be avoided in favour of the corresponding multi-part type (e.g. `MultiPolygon`).", "schema": [ { "type": "object", @@ -20,7 +20,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -44,7 +44,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } diff --git a/proposals/vector_to_random_points.json b/proposals/vector_to_random_points.json index 600ed547..f060b3c9 100644 --- a/proposals/vector_to_random_points.json +++ b/proposals/vector_to_random_points.json @@ -1,7 +1,7 @@ { "id": "vector_to_random_points", "summary": "Sample random points from geometries", - "description": "Generate a vector data cube of points by sampling random points from input geometries. At least one point is sampled per input geometry. Vector properties are preserved.\n\nIf `geometry_count` and `total_count` are both unrestricted (i.e. set to `null`, which is the default), one sample per geometry is used.", + "description": "Generate a vector data cube of points by sampling random points from input geometries. At least one point is sampled per input geometry. Feature properties are preserved.\n\nIf `geometry_count` and `total_count` are both unrestricted (i.e. set to `null`, which is the default), one sample per geometry is used.", "categories": [ "cubes", "vector" @@ -21,7 +21,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -88,7 +88,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector", + "type": "geometries", "geometry_type": [ "Point", "MultiPoint" diff --git a/proposals/vector_to_regular_points.json b/proposals/vector_to_regular_points.json index 20b44d9a..992b7ef9 100644 --- a/proposals/vector_to_regular_points.json +++ b/proposals/vector_to_regular_points.json @@ -1,7 +1,7 @@ { "id": "vector_to_regular_points", "summary": "Sample regular points from geometries", - "description": "Generate a vector data cube of points by sampling regularly-spaced points from input geometries. Vector properties are preserved.", + "description": "Generate a vector data cube of points by sampling regularly-spaced points from input geometries. Feature properties are preserved.", "categories": [ "cubes", "vector" @@ -21,7 +21,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector" + "type": "geometries" } ] } @@ -52,7 +52,7 @@ "subtype": "datacube", "dimensions": [ { - "type": "vector", + "type": "geometries", "geometry_type": [ "Point", "MultiPoint" diff --git a/tests/testHelpers.js b/tests/testHelpers.js index 4d7a224f..6305049b 100644 --- a/tests/testHelpers.js +++ b/tests/testHelpers.js @@ -147,14 +147,14 @@ async function getAjv() { properties: { type: { type: "string", - const: "vector" + const: "geometries" }, geometry_type: { type: "array", minItems: 1, items: { type: "string", - enum: ["Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon", "GeometryCollection"] + enum: ["Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon"] } } }