[SEDONA-653] Add a lenient mode for RS_Clip and make it lenient by de…

…fault (#1586)

common/src/main/java/org/apache/sedona/common/raster/RasterBandEditors.java

@@ -29,6 +29,7 @@
 import org.apache.sedona.common.utils.RasterUtils;
 import org.geotools.coverage.GridSampleDimension;
 import org.geotools.coverage.grid.GridCoverage2D;
+import org.geotools.coverage.processing.CannotCropException;
 import org.geotools.coverage.processing.operation.Crop;
 import org.locationtech.jts.geom.Geometry;
 import org.opengis.parameter.ParameterValueGroup;
@@ -273,10 +274,17 @@ private static void ensureBandAppend(GridCoverage2D raster, int band) {
  * @param geometry Specify ROI
  * @param noDataValue no-Data value for empty cells
  * @param crop Specifies to keep the original extent or not
+ * @param lenient Return null if the raster and geometry do not intersect when set to true,
+ * otherwise will throw an exception
  * @return A clip Raster with defined ROI by the geometry
  */
  public static GridCoverage2D clip(
- GridCoverage2D raster, int band, Geometry geometry, double noDataValue, boolean crop)
+ GridCoverage2D raster,
+ int band,
+ Geometry geometry,
+ double noDataValue,
+ boolean crop,
+ boolean lenient)
  throws FactoryException, TransformException {
 
  // Selecting the band from original raster
@@ -296,7 +304,16 @@ public static GridCoverage2D clip(
  parameters.parameter(Crop.PARAMNAME_DEST_NODATA).setValue(new double[] {noDataValue});
  parameters.parameter(Crop.PARAMNAME_ROI).setValue(geometry);
 
- GridCoverage2D newRaster = (GridCoverage2D) cropObject.doOperation(parameters, null);
+ GridCoverage2D newRaster;
+ try {
+ newRaster = (GridCoverage2D) cropObject.doOperation(parameters, null);
+ } catch (CannotCropException e) {
+ if (lenient) {
+ return null;
+ } else {
+ throw e;
+ }
+ }
 
  if (!crop) {
  double[] metadataOriginal = RasterAccessors.metadata(raster);
@@ -383,6 +400,22 @@ public static GridCoverage2D clip(
  return newRaster;
  }
 
+ /**
+ * Return a clipped raster with the specified ROI by the geometry
+ *
+ * @param raster Raster to clip
+ * @param band Band number to perform clipping
+ * @param geometry Specify ROI
+ * @param noDataValue no-Data value for empty cells
+ * @param crop Specifies to keep the original extent or not
+ * @return A clip Raster with defined ROI by the geometry
+ */
+ public static GridCoverage2D clip(
+ GridCoverage2D raster, int band, Geometry geometry, double noDataValue, boolean crop)
+ throws FactoryException, TransformException {
+ return clip(raster, band, geometry, noDataValue, crop, true);
+ }
+
  /**
  * Return a clipped raster with the specified ROI by the geometry.
  *

common/src/test/java/org/apache/sedona/common/raster/RasterBandEditorsTest.java

@@ -32,6 +32,7 @@
 import org.apache.sedona.common.Constructors;
 import org.apache.sedona.common.raster.serde.Serde;
 import org.geotools.coverage.grid.GridCoverage2D;
+import org.geotools.coverage.processing.CannotCropException;
 import org.junit.Test;
 import org.locationtech.jts.geom.Geometry;
 import org.locationtech.jts.io.ParseException;
@@ -247,6 +248,29 @@ public void testClip()
  assertTrue(Arrays.equals(expectedValues, actualValues));
  }
 
+ @Test
+ public void testClipLenient()
+ throws FactoryException, IOException, ParseException, TransformException {
+ GridCoverage2D raster =
+ rasterFromGeoTiff(resourceFolder + "raster_geotiff_color/FAA_UTM18N_NAD83.tif");
+
+ // Construct a polygon that does not intersect with the raster
+ Geometry nonIntersectingGeom =
+ Constructors.geomFromWKT(
+ "POLYGON ((-78.22106647832458748 37.76411511479908967, -78.20183062098976734 37.72863564460374874, -78.18088490966962922 37.76753482276972562, -78.22106647832458748 37.76411511479908967))",
+ 0);
+
+ // Throws an exception in non-lenient mode
+ assertThrows(
+ CannotCropException.class,
+ () -> RasterBandEditors.clip(raster, 1, nonIntersectingGeom, 200, false, false));
+
+ // Returns null in lenient mode
+ GridCoverage2D result = RasterBandEditors.clip(raster, 1, nonIntersectingGeom, 200, false);
+ assertNull(result);
+ raster.dispose(true);
+ }
+
  @Test
  public void testRasterUnion() throws FactoryException {
  double[][] rasterData1 =

docs/api/sql/Raster-operators.md

@@ -1428,10 +1428,15 @@ Introduction: Returns a raster that is clipped by the given geometry.
 If `crop` is not specified then it will default to `true`, meaning it will make the resulting raster shrink to the geometry's extent and if `noDataValue` is not specified then the resulting raster will have the minimum possible value for the band pixel data type.
 
 !!!Note
- Since `v1.5.1`, if the coordinate reference system (CRS) of the input `geom` geometry differs from that of the `raster`, then `geom` will be transformed to match the CRS of the `raster`. If the `raster` or `geom` doesn't have a CRS then it will default to `4326/WGS84`.
+ - Since `v1.5.1`, if the coordinate reference system (CRS) of the input `geom` geometry differs from that of the `raster`, then `geom` will be transformed to match the CRS of the `raster`. If the `raster` or `geom` doesn't have a CRS then it will default to `4326/WGS84`.
+ - Since `v1.7.0`, `RS_Clip` function will return `null` if the `raster` and `geometry` geometry do not intersect. If you want to throw an exception in this case, you can set the `lenient` parameter to `false`.
 
 Format:
 
+```
+RS_Clip(raster: Raster, band: Integer, geom: Geometry, noDataValue: Double, crop: Boolean, lenient: Boolean)
+```
+
 ```
 RS_Clip(raster: Raster, band: Integer, geom: Geometry, noDataValue: Double, crop: Boolean)
 ```

spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/raster/RasterBandEditors.scala

@@ -59,6 +59,7 @@ case class RS_Union(inputExpressions: Seq[Expression])
 
 case class RS_Clip(inputExpressions: Seq[Expression])
  extends InferredExpression(
+ inferrableFunction6(RasterBandEditors.clip),
  inferrableFunction5(RasterBandEditors.clip),
  inferrableFunction4(RasterBandEditors.clip),
  inferrableFunction3(RasterBandEditors.clip)) {

spark/common/src/test/scala/org/apache/sedona/sql/rasteralgebraTest.scala

@@ -1027,6 +1027,13 @@ class rasteralgebraTest extends TestBaseScala with BeforeAndAfter with GivenWhen
  expectedValues = Seq(0.0, 0.0, 0.0, 0.0, null)
  assertTrue(expectedValues.equals(actualValues))
 
+ // Test with a polygon that does not intersect the raster in lenient mode
+ val actual = df
+ .selectExpr(
+ "RS_Clip(raster, 1, ST_GeomFromWKT('POLYGON((274157 4174899,263510 4174947,269859 4183348,274157 4174899))'))")
+ .first()
+ .get(0)
+ assertNull(actual)
  }
 
  it("Passed RS_AsGeoTiff") {