Merge pull request #886 from Open-EO/883-predefined-tilegrid-splitter

add support for predefinedtilegrid in split_area #883

Author: HansVRP

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add public `split_area` function for tile-grid based job splitting
+
 ### Changed
 
 ### Removed

docs/cookbook/job_manager.rst

@@ -227,6 +227,44 @@ You can implement your own storage backend by subclassing
 :py:class:`~openeo.extra.job_management.JobDatabaseInterface`.
 See the :ref:`API reference below <job-manager-api-reference>` for the full interface.
 
+Job Splitting
+============
+
+The :py:func:`~openeo.extra.job_management._job_splitting.split_area` helper function allows you to split a large area of interest into smaller areas, which can then be processed as separate jobs.
+A user may have a large spatial extent, in the form of a bounding box or polygon, that exceeds the processing limits of a single job on the backend.
+The results are returned as a :py:class:`geopandas.GeoDataFrame` with one row per tile, which can be used as the starting point for a job database where each row corresponds to a manageable job.
+
+The spatial extent can either be split into a regular grid of square tiles, with fixed size and projection, or into a custom grid of variable tiles provided by the user. 
+
+Example: splitting a bounding box into 10x10 km tiles in EPSG:3857:
+
+.. code-block:: python
+
+    from openeo.extra.job_management import split_area
+
+    # Define the bounding box to split
+    bbox = {"west": 5.0, "south": 51.0, "east": 5.2, "north": 51.2, "crs": "EPSG:4326"}
+
+    # Split into 10x10 km tiles in EPSG:3857
+    gdf = split_area(
+        aoi=bbox,
+        tile_size=10_000,  # tile size in meters (units of the projection)
+        projection="EPSG:3857",  # projection for tiling
+    )
+
+This will create a GeoDataFrame with one row per tile, and a geometry column containing the tile polygons.
+
+.. code-block:: pycon
+
+   >>> gdf.head()
+                                              geometry
+   0  POLYGON ((566597.454 6621293.723, 566597.454 6...
+   1  POLYGON ((566597.454 6631293.723, 566597.454 6...
+   2  POLYGON ((566597.454 6641293.723, 566597.454 6...
+   3  POLYGON ((566597.454 6651293.723, 566597.454 6...
+   4  POLYGON ((576597.454 6621293.723, 576597.454 6...
+
+Note that while the original bounding box was in EPSG:4326, the resulting GeoDataFrame is in the tiling projection (EPSG:3857 in this case).
 
 Customizing Job Handling
 ========================

openeo/extra/job_management/__init__.py

@@ -6,6 +6,7 @@
     create_job_db,
     get_job_db,
 )
+from openeo.extra.job_management._job_splitting import split_area
 from openeo.extra.job_management._manager import MultiBackendJobManager
 from openeo.extra.job_management.process_based import ProcessBasedJobCreator
 
@@ -17,5 +18,6 @@
     "ProcessBasedJobCreator",
     "create_job_db",
     "get_job_db",
+    "split_area",
     "MultiBackendJobManager",
 ]