Make aggregate_polygon and filter_polygon more general

CHANGELOG.md

@@ -9,14 +9,16 @@ 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`
     - `array_filter`
     - `array_find`
     - `drop_dimension`
     - `filter_labels`
+    - `filter_spatial`
     - `labels`
     - `load_uploaded_files`
     - `mask_polygon`
@@ -35,7 +37,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comparison processes `eq`, `gt`, `gte`, `lt`, `lte`, `neq` and `between` accept all data types as input for the operands.
 - `add_dimension`: Parameter `value` renamed to `label`.
 - `apply_dimension`: Replaced with a completely new definition. [#73](https://github.com/Open-EO/openeo-processes/issues/73)
-- `aggregate_polygon`: The data cube implicitly gets restricted to the bounds of the polygons as if `filter_polygon` would have been used beforehand. [#101](https://github.com/Open-EO/openeo-processes/issues/101)
 - `aggregate_temporal`: Parameter `labels` is optional. [#19](https://github.com/Open-EO/openeo-processes/issues/19)
 - `apply_kernel`: Only supported 2D kernels on the horizontal spatial dimensions. [#69](https://github.com/Open-EO/openeo-processes/issues/69)
 - `clip`: Works on a single value instead on arrays (replaced parameter `data` with `x`). [#75](https://github.com/Open-EO/openeo-processes/issues/75)
@@ -66,12 +67,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.

aggregate_polygon.json → aggregate_spatial.json

@@ -1,34 +1,28 @@
 {
-    "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.",
+    "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 for UDFs.\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** and **lines** (line strings), the process considers all the closest pixel centers.\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 data cube.",
+            "description": "A raster data cube.",
             "schema": {
                 "type": "object",
                 "subtype": "raster-cube"
             },
             "required": true
         },
         {
-            "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"
+            },
             "required": true
         },
         {
@@ -54,7 +48,7 @@
             "required": true
         },
         {
-            "name": "name",
+            "name": "target_dimension",
             "description": "The new dimension name to be used for storing the results. Defaults to `result`.",
             "schema": {
                 "type": "string"
@@ -63,15 +57,15 @@
         }
     ],
     "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. The vector 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.\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_polygon'."
+            "message": "The number of dimensions must be reduced to three for 'aggregate_spatial'."
         }
     },
     "links": [

aggregate_polygon_binary.json → 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 passes two values to the reducer. 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** and **lines** (line strings), the process considers all the closest pixel centers.\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 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,26 +10,20 @@
     "parameters": [
         {
             "name": "data",
-            "description": "A data cube.",
+            "description": "A raster data cube.",
             "schema": {
                 "type": "object",
                 "subtype": "raster-cube"
             },
             "required": true
         },
         {
-            "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"
+            },
             "required": true
         },
         {
@@ -60,7 +54,7 @@
             "required": true
         },
         {
-            "name": "name",
+            "name": "target_dimension",
             "description": "The new dimension name to be used for storing the results. Defaults to `result`.",
             "schema": {
                 "type": "string"
@@ -69,15 +63,15 @@
         }
     ],
     "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. The vector 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.\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_polygon'."
+            "message": "The number of dimensions must be reduced to three for 'aggregate_spatial'."
         }
     },
     "links": [

aggregate_temporal.json

@@ -221,7 +221,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'."
         },
         "DimensionNotAvailable": {
             "message": "A dimension with the specified name does not exist."

filter_spatial.json

@@ -0,0 +1,42 @@
+{
+    "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** and **lines** (line strings), the filter retains all the pixel centers closest to any of the geometries.\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"
+            },
+            "required": true
+        },
+        {
+            "name": "geometries",
+            "description": "One or more geometries used for filtering, specified as GeoJSON.",
+            "schema": {
+                "type": "object",
+                "subtype": "geojson"
+            },
+            "required": true
+        }
+    ],
+    "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"
+        }
+    ]
+}

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"