Apply fixes to apply_neighborhood #385, #386, #387

Open-EO · Oct 9, 2022 · 0707981 · 0707981
1 parent 2518953
commit 0707981
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 15 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -27,7 +27,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `array_concat`
     - `array_modify`
 - Renamed `text_merge` to `text_concat` for better alignment with `array_concat` and existing implementations.
-- `apply_neighborhood`: Allow `null` as default value for units.
+- `apply_neighborhood`:
+    - Allow `null` as default value for units.
+    - Input and Output for the `process` can either be data cubes or arrays (if one-dimensional). [#387](https://github.com/Open-EO/openeo-processes/issues/387)
 - `run_udf`: Allow all data types instead of just objects in the `context` parameter. [#376](https://github.com/Open-EO/openeo-processes/issues/376)
 - `load_collection` and `load_result`:
     - Require at least one band if not set to `null`. [#372](https://github.com/Open-EO/openeo-processes/issues/372)
@@ -42,10 +44,13 @@ 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 a `TargetDimensionExists` exception is thrown if the target dimension exists.
+    - 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 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.
+- `apply_neighborhood`:
+    - Parameter `overlap` was optional but had no default value and no schena for the default value  defined.
+    - Clarified that the overlap must be included in the returned data cube and can't be modified. [#386](https://github.com/Open-EO/openeo-processes/issues/386)
+    - Removed a conflicting statement that dimension labels can be changed. [#385](https://github.com/Open-EO/openeo-processes/issues/385)
 - `array_contains` and `array_find`: Clarify that giving `null` as `value` always returns `false` or `null` respectively, also fixed the incorrect examples. [#348](https://github.com/Open-EO/openeo-processes/issues/348)
 - `array_interpolate_linear`: Return value was incorrectly specified as `number` or `null`. It must return an array instead. [#333](https://github.com/Open-EO/openeo-processes/issues/333)
 - `is_nan`: Fixed a wrong description of the return value and simplified/clarified the process descriptions overall. [#360](https://github.com/Open-EO/openeo-processes/issues/360)

diff --git a/apply_neighborhood.json b/apply_neighborhood.json
@@ -1,7 +1,7 @@
 {
     "id": "apply_neighborhood",
     "summary": "Apply a process to pixels in a n-dimensional neighborhood",
-    "description": "Applies a focal process to a data cube.\n\nA focal process is a process that works on a 'neighborhood' of pixels. The neighborhood can extend into multiple dimensions, this extent is specified by the `size` argument. It is not only (part of) the size of the input window, but also the size of the output for a given position of the sliding window. The sliding window moves with multiples of `size`.\n\nAn overlap can be specified so that neighborhoods can have overlapping boundaries. This allows for continuity of the output. The values included in the data cube as overlap can't be modified by the given `process`. The missing overlap at the borders of the original data cube are made available as no-data (`null`) in the sub data cubes.\n\nThe neighborhood size should be kept small enough, to avoid running beyond computational resources, but a too small size will result in a larger number of process invocations, which may slow down processing. Window sizes for spatial dimensions typically are in the range of 64 to 512 pixels, while overlaps of 8 to 32 pixels are common.\n\nThe process must not add new dimensions, or remove entire dimensions, but the result can have different dimension labels.\n\nFor the special case of 2D convolution, it is recommended to use ``apply_kernel()``.",
+    "description": "Applies a focal process to a data cube.\n\nA focal process is a process that works on a 'neighborhood' of pixels. The neighborhood can extend into multiple dimensions, this extent is specified by the `size` argument. It is not only (part of) the size of the input window, but also the size of the output for a given position of the sliding window. The sliding window moves with multiples of `size`.\n\nAn overlap can be specified so that neighborhoods can have overlapping boundaries. This allows for continuity of the output. The values included in the data cube or array as overlap must also be included in the data cube or array returned from `process` but shouldn't be modified as any changes to the overlap will be discarded. The missing overlap at the borders of the original data cube are made available as no-data (`null`) in the sub data cubes.\n\nThe neighborhood size should be kept small enough, to avoid running beyond computational resources, but a too small size will result in a larger number of process invocations, which may slow down processing. Window sizes for spatial dimensions typically are in the range of 64 to 512 pixels, while overlaps of 8 to 32 pixels are common.\n\nFor the special case of 2D convolution, it is recommended to use ``apply_kernel()``.",
     "categories": [
         "cubes"
     ],
@@ -23,11 +23,19 @@
                 "parameters": [
                     {
                         "name": "data",
-                        "description": "A subset of the data cube as specified in `size` and `overlap`.",
-                        "schema": {
-                            "type": "object",
-                            "subtype": "raster-cube"
-                        }
+                        "description": "The input data, which is a subset of the data cube as specified in `size` and `overlap`. If the given size and overlap result in a one-dimensional data cube it is converted to a labeled array.",
+                        "schema": [
+                            {
+                                "title": "Multi-dimensional data",
+                                "type": "object",
+                                "subtype": "raster-cube"
+                            },
+                            {
+                                "title": "One-dimensional data",
+                                "type": "array",
+                                "subtype": "labeled-array"
+                            }
+                        ]
                     },
                     {
                         "name": "context",
@@ -40,11 +48,18 @@
                     }
                 ],
                 "returns": {
-                    "description": "The data cube with the newly computed values and the same dimensions. The dimension properties (name, type, labels, reference system and resolution) must remain unchanged, otherwise a `DataCubePropertiesImmutable` exception will be thrown.",
-                    "schema": {
-                        "type": "object",
-                        "subtype": "raster-cube"
-                    }
+                    "description": "An array or data cube with the newly computed values. The data type and dimensionality must correspond to the input data.\n\n* Data cubes must have the same dimensions and the dimension properties (name, type, labels, reference system and resolution) must remain unchanged. Otherwise, a `DataCubePropertiesImmutable` exception will be thrown.\n* Arrays can be returned with or without labels.",
+                    "schema": [
+                        {
+                            "title": "Multi-dimensional data",
+                            "type": "object",
+                            "subtype": "raster-cube"
+                        },
+                        {
+                            "title": "One-dimensional data",
+                            "type": "array"
+                        }
+                    ]
                 }
             }
         },