diff --git a/CHANGELOG.md b/CHANGELOG.md index ed8d1e4b..7c382511 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Processes: - `add` - - `aggregate_polygon_binary` + - `aggregate_spatial` + - `aggregate_spatial_binary` - `all` - `any` - `array_apply` @@ -20,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `dimension_labels` - `drop_dimension` - `filter_labels` + - `filter_spatial - `load_uploaded_files` - `mask_polygon` - `reduce_dimension` @@ -72,12 +74,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - The following processes don't support `ignore_nodata` any longer: `and`, `divide`, `multiply`, `or`, `subtract`, `xor`. [#85](https://github.com/Open-EO/openeo-processes/issues/85) - The following processes don't support `binary` any longer: `aggregate_temporal`, `merge_cubes`, `resample_cube_temporal`. [#94](https://github.com/Open-EO/openeo-processes/issues/94) - Support for vector data cubes, except for the processes `aggregate_poylgon` and `save_result`. [#68](https://github.com/Open-EO/openeo-processes/issues/68) -- `aggregate_polygon`: Doesn't allow returning a GeoJSON any longer. - `filter_temporal` and `load_collection`: Temporal extents don't support time-only intervals any longer. [#88](https://github.com/Open-EO/openeo-processes/issues/88) - `mask`: The mask parameter doesn't accept vectors (polygons) any longer. Use process `mask_polygon` instead. [#110](https://github.com/Open-EO/openeo-processes/issues/110) - Processes: + - `aggregate_polygon`. Use `aggregate_spatial` or `aggregate_spatial_binary` instead. [#62](https://github.com/Open-EO/openeo-processes/issues/62) - `find_collections`: Use `load_collection` and manual data discovery through the clients. [API#52](https://github.com/Open-EO/openeo-api/issues/52) - `filter`: Use `filter_labels` instead. + - `filter_polygon`. Use `filter_spatial` instead. [#37](https://github.com/Open-EO/openeo-processes/issues/37) - `output`: Use `debug` instead. - `property` [#84](https://github.com/Open-EO/openeo-processes/issues/84) - `reduce`: Use `reduce_dimension` or `drop_dimension` instead. diff --git a/aggregate_polygon.json b/aggregate_polygon.json deleted file mode 100644 index 9e9759a4..00000000 --- a/aggregate_polygon.json +++ /dev/null @@ -1,87 +0,0 @@ -{ - "id": "aggregate_polygon", - "summary": "Zonal statistics for polygons", - "description": "Aggregates zonal statistics for one or multiple polygons over the spatial dimensions. This process passes a list of values to the reducer. In contrast, ``aggregate_polygon_binary()`` passes two values, which may be better suited for UDFs.\n\nThe 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\nThe data cube must have been reduced to only contain two spatial dimensions and a third dimension the values are aggregated for, for example the temporal dimension to get a time series. Otherwise this process fails with the `TooManyDimensions` error.\n\nThe number of total and valid pixels is returned together with the calculated values.", - "categories": [ - "cubes", - "aggregate & resample" - ], - "parameters": [ - { - "name": "data", - "description": "A data cube.", - "schema": { - "type": "object", - "subtype": "raster-cube" - } - }, - { - "name": "polygons", - "description": "One or more polygons to calculate zonal statistics for. Either specified as GeoJSON or vector data cube.\n\nFor GeoJSON this can be one of the following GeoJSON types:\n\n* A `Polygon` geometry,\n* a `GeometryCollection` containing Polygons,\n* a `Feature` with a `Polygon` geometry or\n* a `FeatureCollection` containing `Feature`s with a `Polygon` geometry.", - "schema": [ - { - "type": "object", - "subtype": "geojson" - }, - { - "type": "object", - "subtype": "vector-cube" - } - ] - }, - { - "name": "reducer", - "description": "A reducer to be applied on all values of each geometry. A reducer is a single process such as ``mean()`` or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes.", - "schema": { - "type": "object", - "subtype": "process-graph", - "parameters": [ - { - "name": "data", - "description": "A labeled array with values of any type.", - "schema": { - "type": "array", - "subtype": "labeled-array", - "items": { - "description": "Any data type." - } - } - } - ] - } - }, - { - "name": "name", - "description": "The new dimension name to be used for storing the results. Defaults to `result`.", - "schema": { - "type": "string" - }, - "default": "result", - "optional": true - } - ], - "returns": { - "description": "A vector data cube with the computed results. The vector data cube implicitly gets restricted to the bounds of the polygons as if ``filter_polygon()`` would have been used with the same values for the corresponding parameters immediately before this process.\n\nThe computed value is stored in dimension with the name that was specified in the parameter `name`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) in each geometry. These values are stored as attributes of the result value with the attribute names `total_count` and `valid_count`.", - "schema": { - "type": "object", - "subtype": "vector-cube" - } - }, - "exceptions": { - "TooManyDimensions": { - "message": "The number of dimensions must be reduced to three for 'aggregate_polygon'." - } - }, - "links": [ - { - "href": "https://open-eo.github.io/openeo-api/glossary/#aggregation-and-resampling", - "rel": "about", - "title": "Aggregation explained in the openEO glossary" - }, - { - "href": "http://www.opengeospatial.org/standards/sfa", - "rel": "about", - "title": "Simple Features standard by the OGC" - } - ] -} \ No newline at end of file diff --git a/aggregate_spatial.json b/aggregate_spatial.json new file mode 100644 index 00000000..7cf3aa13 --- /dev/null +++ b/aggregate_spatial.json @@ -0,0 +1,80 @@ +{ + "id": "aggregate_spatial", + "summary": "Zonal statistics for geometries", + "description": "Aggregates statistics for one or more geometries (e.g. zonal statistics for polygons) over the spatial dimensions. This process passes a list of values to the reducer. In contrast, ``aggregate_spatial_binary()`` passes two values, which may be better suited especially for UDFs in case the number of values gets too large to be processed at once.\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\nThe data cube must have been reduced to only contain two spatial dimensions and a third dimension the values are aggregated for, for example the temporal dimension to get a time series. Otherwise this process fails with the `TooManyDimensions` error.\n\nThe number of total and valid pixels is returned together with the calculated values.", + "categories": [ + "cubes", + "aggregate & resample" + ], + "parameters": [ + { + "name": "data", + "description": "A raster data cube. The data cube implicitly gets restricted to the bounds of the geometries as if ``filter_spatial()`` would have been used with the same values for the corresponding parameters immediately before this process.", + "schema": { + "type": "object", + "subtype": "raster-cube" + } + }, + { + "name": "geometries", + "description": "Geometries as GeoJSON on which the aggregation will be based.", + "schema": { + "type": "object", + "subtype": "geojson" + } + }, + { + "name": "reducer", + "description": "A reducer to be applied on all values of each geometry. A reducer is a single process such as ``mean()`` or a set of processes, which computes a single value for a list of values, see the category 'reducer' for such processes.", + "schema": { + "type": "object", + "subtype": "process-graph", + "parameters": [ + { + "name": "data", + "description": "An array with elements of any type.", + "schema": { + "type": "array", + "items": { + "description": "Any data type." + } + } + } + ] + } + }, + { + "name": "target_dimension", + "description": "The new dimension name to be used for storing the results. Defaults to `result`.", + "schema": { + "type": "string" + }, + "default": "result", + "optional": true + } + ], + "returns": { + "description": "A vector data cube with the computed results and restricted to the bounds of the geometries.\n\nThe computed value is stored in dimension with the name that was specified in the parameter `target_dimension`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) for each geometry. These values are stored as new dimension with a dimension name derived from `target_dimension` by adding the suffix `_meta`. The new dimension has the dimension labels `total_count` and `valid_count`.", + "schema": { + "type": "object", + "subtype": "vector-cube" + } + }, + "exceptions": { + "TooManyDimensions": { + "message": "The number of dimensions must be reduced to three for 'aggregate_spatial'." + } + }, + "links": [ + { + "href": "https://open-eo.github.io/openeo-api/glossary/#aggregation-and-resampling", + "rel": "about", + "title": "Aggregation explained in the openEO glossary" + }, + { + "href": "http://www.opengeospatial.org/standards/sfa", + "rel": "about", + "title": "Simple Features standard by the OGC" + } + ] +} \ No newline at end of file diff --git a/aggregate_polygon_binary.json b/aggregate_spatial_binary.json similarity index 52% rename from aggregate_polygon_binary.json rename to aggregate_spatial_binary.json index 55d8eee2..035ef114 100644 --- a/aggregate_polygon_binary.json +++ b/aggregate_spatial_binary.json @@ -1,7 +1,7 @@ { - "id": "aggregate_polygon_binary", - "summary": "Zonal statistics for polygons using binary aggregation", - "description": "Aggregates zonal statistics for one or multiple polygons over the spatial dimensions. This process passes two values to the reducer. In contrast, ``aggregate_polygon()`` passes a list of values.\n\nThe 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\nThe data cube must have been reduced to only contain two raster dimensions and a third dimension the values are aggregated for, for example the temporal dimension to get a time series. Otherwise this process fails with the `TooManyDimensions` error.\n\nThe number of total and valid pixels is returned together with the calculated values.", + "id": "aggregate_spatial_binary", + "summary": "Zonal statistics for geometries by binary aggregation", + "description": "Aggregates statistics for one or more geometries (e.g. zonal statistics for polygons) over the spatial dimensions. This process consecutively passes a pair of values to the reducer. This may be better suited especially for UDFs in case the number of values gets too large to be processed at once. In contrast, ``aggregate_spatial()`` passes a list of values.\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\nThe data cube must have been reduced to only contain two raster dimensions and a third dimension the values are aggregated for, for example the temporal dimension to get a time series. Otherwise this process fails with the `TooManyDimensions` error.\n\nThe number of total and valid pixels is returned together with the calculated values.", "categories": [ "cubes", "aggregate & resample" @@ -10,25 +10,19 @@ "parameters": [ { "name": "data", - "description": "A data cube.", + "description": "A raster data cube. The data cube implicitly gets restricted to the bounds of the geometries as if ``filter_spatial()`` would have been used with the same values for the corresponding parameters immediately before this process.", "schema": { "type": "object", "subtype": "raster-cube" } }, { - "name": "polygons", - "description": "One or more polygons to calculate zonal statistics for. Either specified as GeoJSON or vector data cube.\n\nFor GeoJSON this can be one of the following GeoJSON types:\n\n* A `Polygon` geometry,\n* a `GeometryCollection` containing Polygons,\n* a `Feature` with a `Polygon` geometry or\n* a `FeatureCollection` containing `Feature`s with a `Polygon` geometry.", - "schema": [ - { - "type": "object", - "subtype": "geojson" - }, - { - "type": "object", - "subtype": "vector-cube" - } - ] + "name": "geometries", + "description": "Geometries as GeoJSON on which the aggregation will be based.", + "schema": { + "type": "object", + "subtype": "geojson" + } }, { "name": "reducer", @@ -55,7 +49,7 @@ } }, { - "name": "name", + "name": "target_dimension", "description": "The new dimension name to be used for storing the results. Defaults to `result`.", "schema": { "type": "string" @@ -65,7 +59,7 @@ } ], "returns": { - "description": "A vector data cube with the computed results. The vector data cube implicitly gets restricted to the bounds of the polygons as if ``filter_polygon()`` would have been used with the same values for the corresponding parameters immediately before this process.\n\nThe computed value is stored in dimension with the name that was specified in the parameter `name`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) in each geometry. These values are stored as attributes of the result value with the attribute names `total_count` and `valid_count`.", + "description": "A vector data cube with the computed results and restricted to the bounds of the geometries.\n\nThe computed value is stored in dimension with the name that was specified in the parameter `target_dimension`.\n\nThe computation also stores information about the total count of pixels (valid + invalid pixels) and the number of valid pixels (see ``is_valid()``) for each geometry. These values are stored as new dimension with a dimension name derived from `target_dimension` by adding the suffix `_meta`. The new dimension has the dimension labels `total_count` and `valid_count`.", "schema": { "type": "object", "subtype": "vector-cube" @@ -73,7 +67,7 @@ }, "exceptions": { "TooManyDimensions": { - "message": "The number of dimensions must be reduced to three for 'aggregate_polygon'." + "message": "The number of dimensions must be reduced to three for 'aggregate_spatial_binary'." } }, "links": [ diff --git a/aggregate_temporal.json b/aggregate_temporal.json index 28c3eb1e..a3d2027e 100644 --- a/aggregate_temporal.json +++ b/aggregate_temporal.json @@ -209,7 +209,7 @@ ], "exceptions": { "TooManyDimensions": { - "message": "The number of dimensions must be reduced to three for 'aggregate_polygon'." + "message": "The number of dimensions must be reduced to three for 'aggregate_temporal'." }, "DimensionNotAvailable": { "message": "A dimension with the specified name does not exist." diff --git a/filter_polygon.json b/filter_polygon.json deleted file mode 100644 index f2ae6ac9..00000000 --- a/filter_polygon.json +++ /dev/null @@ -1,40 +0,0 @@ -{ - "id": "filter_polygon", - "summary": "Spatial filter using polygons", - "description": "Limits the data cube over the spatial dimensions to the specified polygons.\n\nThe 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).", - "categories": [ - "filter" - ], - "parameters": [ - { - "name": "data", - "description": "A data cube.", - "schema": { - "type": "object", - "subtype": "raster-cube" - } - }, - { - "name": "polygons", - "description": "One or more polygons used for filtering, either specified as GeoJSON or vector data cube.\n\nFor GeoJSON this can be one of the following GeoJSON types:\n\n* A `Polygon` geometry,\n* a `GeometryCollection` containing Polygons,\n* a `Feature` with a `Polygon` geometry or\n* a `FeatureCollection` containing `Feature`s with a `Polygon` geometry.", - "schema": { - "type": "object", - "subtype": "geojson" - } - } - ], - "returns": { - "description": "A data cube restricted to the specified polygons. Therefore, the cardinality is potentially lower, but the resolution and the number of dimensions are the same as for the original data cube.", - "schema": { - "type": "object", - "subtype": "raster-cube" - } - }, - "links": [ - { - "href": "http://www.opengeospatial.org/standards/sfa", - "rel": "about", - "title": "Simple Features standard by the OGC" - } - ] -} \ No newline at end of file diff --git a/filter_spatial.json b/filter_spatial.json new file mode 100644 index 00000000..d9a8ec77 --- /dev/null +++ b/filter_spatial.json @@ -0,0 +1,40 @@ +{ + "id": "filter_spatial", + "summary": "Spatial filter using geometries", + "description": "Limits the 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).", + "categories": [ + "filter" + ], + "parameters": [ + { + "name": "data", + "description": "A data cube.", + "schema": { + "type": "object", + "subtype": "raster-cube" + } + }, + { + "name": "geometries", + "description": "One or more geometries used for filtering, specified as GeoJSON.", + "schema": { + "type": "object", + "subtype": "geojson" + } + } + ], + "returns": { + "description": "A data cube restricted to the specified geometries. Therefore, the cardinality is potentially lower, but the resolution and the number of dimensions are the same as for the original data cube.", + "schema": { + "type": "object", + "subtype": "raster-cube" + } + }, + "links": [ + { + "href": "http://www.opengeospatial.org/standards/sfa", + "rel": "about", + "title": "Simple Features standard by the OGC" + } + ] +} \ No newline at end of file diff --git a/reduce_dimension.json b/reduce_dimension.json index e4869962..6564652f 100644 --- a/reduce_dimension.json +++ b/reduce_dimension.json @@ -1,7 +1,7 @@ { "id": "reduce_dimension", "summary": "Reduce dimensions", - "description": "Applies a unary reducer to a data cube dimension by collapsing all the pixel values along the specified dimension into an output value computed by the reducer. This process passes a list of values to the reducer. In contrast, ``reduce_dimension_binary()`` passes two values, which may be better suited for UDFs.\n\nThe dimension is dropped. To avoid this, use ``apply_dimension()`` instead.", + "description": "Applies a unary reducer to a data cube dimension by collapsing all the pixel values along the specified dimension into an output value computed by the reducer. This process passes a list of values to the reducer. In contrast, ``reduce_dimension_binary()`` passes two values, which may be better suited especially for UDFs in case the number of values gets too large to be processed at once.\n\nThe dimension is dropped. To avoid this, use ``apply_dimension()`` instead.", "categories": [ "cubes", "reducer" diff --git a/reduce_dimension_binary.json b/reduce_dimension_binary.json index b13f4085..42be6d00 100644 --- a/reduce_dimension_binary.json +++ b/reduce_dimension_binary.json @@ -1,7 +1,7 @@ { "id": "reduce_dimension_binary", "summary": "Reduce dimensions using binary reduction", - "description": "Applies a binary reducer to a data cube dimension by collapsing all the pixel values along the specified dimension into an output value computed by the reducer. This process consecutively passes a pair of values to the reducer. In contrast, ``reduce_dimension()`` passes a list of values.\n\nThe dimension is dropped. To avoid this, use ``apply_dimension()`` instead.", + "description": "Applies a binary reducer to a data cube dimension by collapsing all the pixel values along the specified dimension into an output value computed by the reducer. This process consecutively passes a pair of values to the reducer. This may be better suited especially for UDFs in case the number of values gets too large to be processed at once. In contrast, ``reduce_dimension()`` passes a list of values.\n\nThe dimension is dropped. To avoid this, use ``apply_dimension()`` instead.", "categories": [ "cubes", "reducer" diff --git a/run_udf.json b/run_udf.json index bc8a58b1..e41c3eb8 100644 --- a/run_udf.json +++ b/run_udf.json @@ -1,7 +1,7 @@ { "id": "run_udf", "summary": "Run an UDF", - "description": "Runs an UDF in one of the supported runtime environments.\n\nThe process can either:\n\n1. load and run a locally stored UDF from a file in the workspace of the authenticated user. The path to the UDF file must be relative to the root directory of the user's workspace.\n2. fetch and run a remotely stored and published UDF by absolute URI, for example from [openEO Hub](https://hub.openeo.org)).\n3. run the source code specified inline as string.\n\nThe loaded UDF can be executed in several processes such as ``aggregate_polygon()``, ``apply()``, ``apply_dimension()`` and ``reduce_dimension()``. In this case an array is passed instead of a raster data cube. The user must ensure that the data is properly passed as an array so that the UDF can make sense of it.", + "description": "Runs an UDF in one of the supported runtime environments.\n\nThe process can either:\n\n1. load and run a locally stored UDF from a file in the workspace of the authenticated user. The path to the UDF file must be relative to the root directory of the user's workspace.\n2. fetch and run a remotely stored and published UDF by absolute URI, for example from [openEO Hub](https://hub.openeo.org)).\n3. run the source code specified inline as string.\n\nThe loaded UDF can be executed in several processes such as ``aggregate_spatial()``, ``apply()``, ``apply_dimension()`` and ``reduce_dimension()``. In this case an array is passed instead of a raster data cube. The user must ensure that the data is properly passed as an array so that the UDF can make sense of it.", "categories": [ "import", "udf" diff --git a/run_udf_externally.json b/run_udf_externally.json index ac65a7c1..36e65785 100644 --- a/run_udf_externally.json +++ b/run_udf_externally.json @@ -1,7 +1,7 @@ { "id": "run_udf_externally", "summary": "Run an externally hosted UDF container", - "description": "Runs a compatible UDF container that is either externally hosted by a service provider or running on a local machine of the user. The UDF container must follow the [openEO UDF specification](https://open-eo.github.io/openeo-udf/).\n\nThe referenced UDF service can be executed in several processes such as ``aggregate_polygon()``, ``apply()``, ``apply_dimension()`` and ``reduce_dimension()``. In this case an array is passed instead of a raster data cube. The user must ensure that the data is properly passed as an array so that the UDF can make sense of it.", + "description": "Runs a compatible UDF container that is either externally hosted by a service provider or running on a local machine of the user. The UDF container must follow the [openEO UDF specification](https://open-eo.github.io/openeo-udf/).\n\nThe referenced UDF service can be executed in several processes such as ``aggregate_spatial()``, ``apply()``, ``apply_dimension()`` and ``reduce_dimension()``. In this case an array is passed instead of a raster data cube. The user must ensure that the data is properly passed as an array so that the UDF can make sense of it.", "categories": [ "import", "udf" diff --git a/tests/.words b/tests/.words index e17cfa15..eff41394 100644 --- a/tests/.words +++ b/tests/.words @@ -29,4 +29,5 @@ outputMax Sentinel-2 Sentinel-2A Sentinel-2B -labeled \ No newline at end of file +labeled +centers \ No newline at end of file