Change resample_cube_temporal, align with GDAL and improve resampling descriptions in general

CHANGELOG.md

@@ -29,6 +29,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Exception messages have been aligned always use ` instead of '. Tooling could render it with CommonMark.
 - `load_collection`  and `mask_polygon`: Also support multi polygons instead of just polygons. [#237](https://github.com/Open-EO/openeo-processes/issues/237)
 - `run_udf` and `run_udf_externally`: Specify specific (extensible) protocols for UDF URIs.
+- `resample_cube_spatial` and `resample_spatial`: Aligned with GDAL and added `rms` and `sum` options to methods. Also added better descriptions.
+- `resample_cube_temporal`: Process has been simplified and only offers the nearest neighbor method now. The `process` parameter has been removed, the `dimension` parameter was made less restrictive, the parameter `valid_within` was added. [#194](https://github.com/Open-EO/openeo-processes/issues/194)
 
 ### Deprecated
 - `GeometryCollection`s are discouraged in all relevant processes.

proposals/resample_cube_temporal.json

@@ -1,7 +1,7 @@
 {
     "id": "resample_cube_temporal",
-    "summary": "Resample a temporal dimension to match a target data cube",
-    "description": "Resamples the given temporal dimension from a source data cube to align with the corresponding dimension of the given target data cube. Returns a new data cube with the resampled dimension.\n\nIf the dimension is not set or is set to `null`, the data cube is expected to have one temporal dimension only.",
+    "summary": "Resample temporal dimensions to match a target data cube",
+    "description": "Resamples one or more given temporal dimensions from a source data cube to align with the corresponding dimensions of the given target data cube using the nearest neighbor method. Returns a new data cube with the resampled dimensions.\n\nBy default, this process simply takes the nearest neighbor independent of the value (including values such as no-data / `null`). Depending on the data cubes this may lead to values being assigned to two target timestamps. To only consider valid values in a specific range around the target timestamps, use the parameter `valid_within`.\n\nThe rare case of ties is resolved by choosing the earlier timestamps.",
     "categories": [
         "cubes",
         "aggregate & resample"
@@ -10,7 +10,7 @@
     "parameters": [
         {
             "name": "data",
-            "description": "A data cube.",
+            "description": "A data cube with one or more temporal dimensions.",
             "schema": {
                 "type": "object",
                 "subtype": "raster-cube"
@@ -24,45 +24,9 @@
                 "subtype": "raster-cube"
             }
         },
-        {
-            "name": "method",
-            "description": "A resampling method to be applied, could be a reducer for downsampling or other methods for upsampling. 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 elements of any type.",
-                        "schema": {
-                            "type": "array",
-                            "subtype": "labeled-array",
-                            "items": {
-                                "description": "Any data type."
-                            }
-                        }
-                    },
-                    {
-                        "name": "context",
-                        "description": "Additional data passed by the user.",
-                        "schema": {
-                            "description": "Any data type."
-                        },
-                        "optional": true,
-                        "default": null
-                    }
-                ],
-                "returns": {
-                    "description": "The value to be set in the resampled data cube.",
-                    "schema": {
-                        "description": "Any data type."
-                    }
-                }
-            }
-        },
         {
             "name": "dimension",
-            "description": "The name of the temporal dimension to resample, which must exist with this name in both data cubes. If the dimension is not set or is set to `null`, the data cube is expected to only have one temporal dimension. Fails with a `TooManyDimensions` exception if it has more dimensions. Fails with a `DimensionNotAvailable` exception if the specified dimension does not exist.",
+            "description": "The name of the temporal dimension to resample, which must exist with this name in both data cubes. If the dimension is not set or is set to `null`, the process resamples all temporal dimensions that exist with the same names in both data cubes.\n\nThe following exceptions may occur:\n\n* A dimension is given, but it does not exist in any of the data cubes: `DimensionNotAvailable`\n* A dimension is given, but one of them is not temporal: `DimensionMismatch`\n\n* No specific dimension name is given and there are no temporal dimensions with the same name in the data: `DimensionMismatch`",
             "schema": {
                 "type": [
                     "string",
@@ -73,25 +37,28 @@
             "optional": true
         },
         {
-            "name": "context",
-            "description": "Additional data to be passed to the process specified for the parameter `method`.",
+            "name": "valid_within",
+            "description": "Setting this parameter to a numerical value enables that the process searches for valid values within the given period of days before and after the target timestamps. Valid values are determined based on the function ``is_valid()``. For example, the limit of `7` for the target timestamps `2020-01-15 12:00:00` looks for a nearest neighbor after `2020-01-08 12:00:00` and before `2020-01-22 12:00:00`. If no valid value is found within the given period, the value will be set to no-data (`null`).",
             "schema": {
-                "description": "Any data type."
+                "type": [
+                    "number",
+                    "null"
+                ]
             },
-            "optional": true,
-            "default": null
+            "default": null,
+            "optional": true
         }
     ],
     "returns": {
-        "description": "A raster data cube with the same dimensions and the same dimension properties (name, type, labels, reference system and resolution) for all non-temporal dimensions. For the temporal dimension, the name and type remain unchanged, but the reference system changes and the labels and resolution may change.",
+        "description": "A raster data cube with the same dimensions and the same dimension properties (name, type, labels, reference system and resolution) for all non-temporal dimensions. For the temporal dimension, the name and type remain unchanged, but the dimension labels, resolution and reference system may change.",
         "schema": {
             "type": "object",
             "subtype": "raster-cube"
         }
     },
     "exceptions": {
-        "TooManyDimensions": {
-            "message": "The number of temporal dimensions must be reduced to one for `resample_cube_temporal`."
+        "DimensionMismatch": {
+            "message": "The temporal dimensions for resampling don't match."
         },
         "DimensionNotAvailable": {
             "message": "A dimension with the specified name does not exist."

resample_cube_spatial.json

@@ -25,22 +25,24 @@
         },
         {
             "name": "method",
-            "description": "Resampling method. Methods are inspired by GDAL, see [`gdalwarp`](https://www.gdal.org/gdalwarp.html) for more information.",
+            "description": "Resampling method to use. The following options are available and are meant to align with [`gdalwarp`](https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r):\n\n* `average`: average (mean) resampling, computes the weighted average of all valid pixels\n* `bilinear`: bilinear resampling\n* `cubic`: cubic resampling\n* `cubicspline`: cubic spline resampling\n* `lanczos`: Lanczos windowed sinc resampling\n* `max`: maximum resampling, selects the maximum value from all valid pixels\n* `med`: median resampling, selects the median value of all valid pixels\n* `min`: minimum resampling, selects the minimum value from all valid pixels\n* `mode`: mode resampling, selects the value which appears most often of all the sampled points\n* `near`: nearest neighbour resampling (default)\n* `q1`: first quartile resampling, selects the first quartile value of all valid pixels\n* `q3`: third quartile resampling, selects the third quartile value of all valid pixels\n* `rms` root mean square (quadratic mean) of all valid pixels\n* `sum`: compute the weighted sum of all valid pixels\n\nValid pixels are determined based on the function ``is_valid()``.",
             "schema": {
                 "type": "string",
                 "enum": [
-                    "near",
+                    "average",
                     "bilinear",
                     "cubic",
                     "cubicspline",
                     "lanczos",
-                    "average",
-                    "mode",
                     "max",
-                    "min",
                     "med",
+                    "min",
+                    "mode",
+                    "near",
                     "q1",
-                    "q3"
+                    "q3",
+                    "rms",
+                    "sum"
                 ]
             },
             "default": "near",

resample_spatial.json

@@ -72,22 +72,24 @@
         },
         {
             "name": "method",
-            "description": "Resampling method. Methods are inspired by GDAL, see [`gdalwarp`](https://www.gdal.org/gdalwarp.html) for more information.",
+            "description": "Resampling method to use. The following options are available and are meant to align with [`gdalwarp`](https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r):\n\n* `average`: average (mean) resampling, computes the weighted average of all valid pixels\n* `bilinear`: bilinear resampling\n* `cubic`: cubic resampling\n* `cubicspline`: cubic spline resampling\n* `lanczos`: Lanczos windowed sinc resampling\n* `max`: maximum resampling, selects the maximum value from all valid pixels\n* `med`: median resampling, selects the median value of all valid pixels\n* `min`: minimum resampling, selects the minimum value from all valid pixels\n* `mode`: mode resampling, selects the value which appears most often of all the sampled points\n* `near`: nearest neighbour resampling (default)\n* `q1`: first quartile resampling, selects the first quartile value of all valid pixels\n* `q3`: third quartile resampling, selects the third quartile value of all valid pixels\n* `rms` root mean square (quadratic mean) of all valid pixels\n* `sum`: compute the weighted sum of all valid pixels\n\nValid pixels are determined based on the function ``is_valid()``.",
             "schema": {
                 "type": "string",
                 "enum": [
-                    "near",
+                    "average",
                     "bilinear",
                     "cubic",
                     "cubicspline",
                     "lanczos",
-                    "average",
-                    "mode",
                     "max",
-                    "min",
                     "med",
+                    "min",
+                    "mode",
+                    "near",
                     "q1",
-                    "q3"
+                    "q3",
+                    "rms",
+                    "sum"
                 ]
             },
             "default": "near",
@@ -136,6 +138,11 @@
             "rel": "about",
             "href": "http://www.epsg.io",
             "title": "Unofficial EPSG code database"
+        },
+        {
+            "href": "https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r",
+            "rel": "about",
+            "title": "gdalwarp resampling methods"
         }
     ]
 }

tests/.words

@@ -13,6 +13,7 @@ GeoJSON
 labeled
 MathWorld
 n-ary
+neighbor
 neighborhood
 neighborhoods
 openEO
@@ -22,6 +23,7 @@ radiometrically
 reflectances
 resample
 resampled
+resamples
 Resamples
 resampling
 Sentinel-2
@@ -31,4 +33,7 @@ signum
 STAC
 summand
 UDFs
+gdalwarp
+Lanczos
+sinc
 interpolants