[SEDONA-498] Add Spheroidal ST_Buffer

common/src/main/java/org/apache/sedona/common/FunctionsGeoTools.java

@@ -20,6 +20,8 @@
 import org.locationtech.jts.geom.Envelope;
 import org.locationtech.jts.geom.Geometry;
 import org.locationtech.jts.geom.GeometryFactory;
+import org.locationtech.jts.operation.buffer.BufferOp;
+import org.locationtech.jts.operation.buffer.BufferParameters;
 import org.locationtech.jts.triangulate.VoronoiDiagramBuilder;
 import org.opengis.referencing.FactoryException;
 import org.opengis.referencing.NoSuchAuthorityCodeException;
@@ -134,4 +136,39 @@ public static Geometry voronoiPolygons(Geometry geom, double tolerance, Geometry
         }
         return builder.getDiagram(FunctionsGeoTools.GEOMETRY_FACTORY);
     }
+
+    public static Geometry bufferSpheroid(Geometry geometry, double radius, BufferParameters params) throws IllegalArgumentException {
+        // Determine the best SRID for spheroidal calculations
+        int bestCRS = Functions.bestSRID(geometry);
+        int originalCRS = geometry.getSRID();
+        final int WGS84CRS = 4326;
+
+        // Shift longitude if geometry crosses dateline
+        if (Functions.crossesDateLine(geometry)) {
+            Functions.shiftLongitude(geometry);
+        }
+//        geometry = (Predicates.crossesDateLine(geometry)) ? Functions.shiftLongitude(geometry) : geometry;
+
+        // If originalCRS is not set, use WGS84 as the originalCRS for transformation
+        String sourceCRSCode = (originalCRS == 0) ? "EPSG:" + WGS84CRS : "EPSG:" + originalCRS;
+        String targetCRSCode = "EPSG:" + bestCRS;
+
+        try {
+            // Transform the geometry to the selected SRID
+            Geometry transformedGeometry = transform(geometry, sourceCRSCode, targetCRSCode);
+            // Apply the buffer operation in the selected SRID
+            Geometry bufferedGeometry = BufferOp.bufferOp(transformedGeometry, radius, params);
+
+            // Transform back to the original SRID or to WGS 84 if original SRID was not set
+            int backTransformCRSCode = (originalCRS == 0) ? WGS84CRS : originalCRS;
+            Geometry bufferedResult = transform(bufferedGeometry, targetCRSCode, "EPSG:" + backTransformCRSCode);
+            bufferedResult.setSRID(backTransformCRSCode);
+
+            // Normalize longitudes between -180 and 180
+            Functions.normalizeLongitude(bufferedResult);
+            return bufferedResult;
+        } catch (FactoryException | TransformException e) {
+            throw new RuntimeException(e);
+        }
+    }
 }

common/src/main/java/org/apache/sedona/common/Predicates.java

@@ -16,8 +16,6 @@
 import org.locationtech.jts.geom.*;
 import org.apache.sedona.common.sphere.Spheroid;
 
-import java.util.concurrent.atomic.AtomicBoolean;
-
 public class Predicates {
     public static boolean contains(Geometry leftGeometry, Geometry rightGeometry) {
         return leftGeometry.contains(rightGeometry);

common/src/main/java/org/apache/sedona/common/sphere/Spheroid.java

@@ -26,6 +26,7 @@
 import org.locationtech.jts.geom.Envelope;
 import org.locationtech.jts.geom.Geometry;
 
+import static java.lang.Float.NaN;
 import static java.lang.Math.abs;
 
 public class Spheroid
@@ -131,7 +132,7 @@ else if (geomType.equals("MultiPolygon") || geomType.equals("GeometryCollection"
         }
     }
 
-    public static double angularWidth(Envelope envelope) {
+    public static Double angularWidth(Envelope envelope) {
         double lon1 = envelope.getMinX();
         double lon2 = envelope.getMaxX();
         double lat = (envelope.getMinY() + envelope.getMaxY()) / 2; // Mid-latitude for width calculation
@@ -141,12 +142,12 @@ public static double angularWidth(Envelope envelope) {
         double distance = g.s12; // Distance in meters
 
         // Convert distance to angular width in degrees
-        double angularWidth = Math.toDegrees(distance / (Geodesic.WGS84.EquatorialRadius() * Math.PI / 180));
+        Double angularWidth = Math.toDegrees(distance / (Geodesic.WGS84.EquatorialRadius() * Math.PI / 180));
 
         return angularWidth;
     }
 
-    public static double angularHeight(Envelope envelope) {
+    public static Double angularHeight(Envelope envelope) {
         double lat1 = envelope.getMinY();
         double lat2 = envelope.getMaxY();
         double lon = (envelope.getMinX() + envelope.getMaxX()) / 2; // Mid-longitude for height calculation
@@ -156,7 +157,7 @@ public static double angularHeight(Envelope envelope) {
         double distance = g.s12; // Distance in meters
 
         // Convert distance to angular height in degrees
-        double angularHeight = Math.toDegrees(distance / (Geodesic.WGS84.EquatorialRadius() * Math.PI / 180));
+        Double angularHeight = Math.toDegrees(distance / (Geodesic.WGS84.EquatorialRadius() * Math.PI / 180));
 
         return angularHeight;
     }

docs/api/flink/Function.md

@@ -553,9 +553,28 @@ Output: `LINESTRING Z(-1 -1 0, 10 5 5)`
 
 ## ST_Buffer
 
-Introduction: Returns a geometry/geography that represents all points whose distance from this Geometry/geography is less than or equal to distance.
+Introduction: Returns a geometry/geography that represents all points whose distance from this Geometry/geography is less than or equal to distance. The function supports both Planar/Euclidean and Spheroidal/Geodesic buffering (Since v1.6.0). Spheroidal buffer also supports geometries crossing the International Date Line (IDL).
 
-The optional third parameter controls the buffer accuracy and style. Buffer accuracy is specified by the number of line segments approximating a quarter circle, with a default of 8 segments. Buffer style can be set by providing blank-separated key=value pairs in a list format.
+Mode of buffer calculation (Since: `v1.6.0`):
+
+The optional third parameter, `useSpheroid`, controls the mode of buffer calculation.
+
+- Planar Buffering (default): When `useSpheroid` is false, `ST_Buffer` performs standard planar buffering based on the provided parameters.
+- Spheroidal Buffering:
+    - When `useSpheroid` is set to true, the function returns the spheroidal buffer polygon for more accurate representation over the Earth.
+    - ST_Buffer first determines the most appropriate Spatial Reference Identifier (SRID) for a given geometry, based on its spatial extent and location, using `ST_BestSRID`.
+    - The geometry is then transformed from its original SRID to the selected SRID. If the input geometry does not have a set SRID, `ST_Buffer` defaults to using WGS 84 (SRID 4326) as its original SRID.
+    - The standard planar buffer operation is then applied in this coordinate system.
+    - Finally, the buffered geometry is transformed back to its original SRID, or to WGS 84 if the original SRID was not set.
+
+!!!note
+    Spheroidal buffering only supports lon/lat coordinate systems and will throw an `IllegalArgumentException` for input geometries in meter based coordinate systems.
+!!!note
+    Spheroidal buffering may not produce accurate output buffer for input geometries larger than a UTM zone.
+
+Buffer Style Parameters:
+
+The optional forth parameter controls the buffer accuracy and style. Buffer accuracy is specified by the number of line segments approximating a quarter circle, with a default of 8 segments. Buffer style can be set by providing blank-separated key=value pairs in a list format.
 
 - `quad_segs=#` : Number of line segments utilized to approximate a quarter circle (default is 8).
 - `endcap=round|flat|square` : End cap style (default is `round`). `butt` is an accepted synonym for `flat`.
@@ -569,16 +588,22 @@ The optional third parameter controls the buffer accuracy and style. Buffer accu
 Format:
 
 ```
-ST_Buffer (A: Geometry, buffer: Double, bufferStyleParameters: String [Optional])
+ST_Buffer (A: Geometry, buffer: Double)
+```
+```
+ST_Buffer (A: Geometry, buffer: Double, useSpheroid: Boolean)
+```
+```
+ST_Buffer (A: Geometry, buffer: Double, useSpheroid: Boolean, bufferStyleParameters: String)
 ```
 
 Since: `v1.5.1`
 
-Example:
+SQL Example:
 
 ```sql
 SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10)
-SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10, 'quad_segs=2')
+SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10, false, 'quad_segs=2')
 ```
 
 Output:
@@ -588,10 +613,10 @@ Output:
 
 8 Segments   2 Segments
 
-Example:
+SQL Example:
 
 ```sql
-SELECT ST_Buffer(ST_GeomFromWKT('LINESTRING(0 0, 50 70, 100 100)'), 10, 'side=left')
+SELECT ST_Buffer(ST_GeomFromWKT('LINESTRING(0 0, 50 70, 100 100)'), 10, false, 'side=left')
 ```
 
 Output:

docs/api/snowflake/vector-data/Function.md

@@ -389,16 +389,79 @@ Output: `LINESTRING Z(-1 -1 0, 10 5 5)`
 
 ## ST_Buffer
 
-Introduction: Returns a geometry/geography that represents all points whose distance from this Geometry/geography is less than or equal to distance.
+Introduction: Returns a geometry/geography that represents all points whose distance from this Geometry/geography is less than or equal to distance. The function supports both Planar/Euclidean and Spheroidal/Geodesic buffering (Since v1.6.0). Spheroidal buffer also supports geometries crossing the International Date Line (IDL).
 
-Format: `ST_Buffer (A:geometry, buffer: Double)`
+Mode of buffer calculation (Since: `v1.6.0`):
 
-SQL example:
-```SQL
-SELECT ST_Buffer(polygondf.countyshape, 1)
-FROM polygondf
+The optional third parameter, `useSpheroid`, controls the mode of buffer calculation.
+
+- Planar Buffering (default): When `useSpheroid` is false, `ST_Buffer` performs standard planar buffering based on the provided parameters.
+- Spheroidal Buffering:
+    - When `useSpheroid` is set to true, the function returns the spheroidal buffer polygon for more accurate representation over the Earth.
+    - ST_Buffer first determines the most appropriate Spatial Reference Identifier (SRID) for a given geometry, based on its spatial extent and location, using `ST_BestSRID`.
+    - The geometry is then transformed from its original SRID to the selected SRID. If the input geometry does not have a set SRID, `ST_Buffer` defaults to using WGS 84 (SRID 4326) as its original SRID.
+    - The standard planar buffer operation is then applied in this coordinate system.
+    - Finally, the buffered geometry is transformed back to its original SRID, or to WGS 84 if the original SRID was not set.
+
+!!!note
+    Spheroidal buffering only supports lon/lat coordinate systems and will throw an `IllegalArgumentException` for input geometries in meter based coordinate systems.
+!!!note
+    Spheroidal buffering may not produce accurate output buffer for input geometries larger than a UTM zone.
+
+Buffer Style Parameters:
+
+The optional forth parameter controls the buffer accuracy and style. Buffer accuracy is specified by the number of line segments approximating a quarter circle, with a default of 8 segments. Buffer style can be set by providing blank-separated key=value pairs in a list format.
+
+- `quad_segs=#` : Number of line segments utilized to approximate a quarter circle (default is 8).
+- `endcap=round|flat|square` : End cap style (default is `round`). `butt` is an accepted synonym for `flat`.
+- `join=round|mitre|bevel` : Join style (default is `round`). `miter` is an accepted synonym for `mitre`.
+- `mitre_limit=#.#` : mitre ratio limit and it only affects mitred join style. `miter_limit` is an accepted synonym for `mitre_limit`.
+- `side=both|left|right` : The option `left` or `right` enables a single-sided buffer operation on the geometry, with the buffered side aligned according to the direction of the line. This functionality is specific to LINESTRING geometry and has no impact on POINT or POLYGON geometries. By default, square end caps are applied.
+
+!!!note
+    `ST_Buffer` throws an `IllegalArgumentException` if the correct format, parameters, or options are not provided.
+
+Format:
+
+```
+ST_Buffer (A: Geometry, buffer: Double)
+```
+```
+ST_Buffer (A: Geometry, buffer: Double, useSpheroid: Boolean)
+```
+```
+ST_Buffer (A: Geometry, buffer: Double, useSpheroid: Boolean, bufferStyleParameters: String)
 ```
 
+Since: `v1.5.1`
+
+SQL Example:
+
+```sql
+SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10)
+SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10, false, 'quad_segs=2')
+```
+
+Output:
+
+<img alt="Point buffer with 8 quadrant segments" src="../../../image/point-buffer-quad-8.png" width="100" height=""/>
+<img alt="Point buffer with 2 quadrant segments" src="../../../image/point-buffer-quad-2.png" width="100" height=""/>
+
+8 Segments &ensp; 2 Segments
+
+SQL Example:
+
+```sql
+SELECT ST_Buffer(ST_GeomFromWKT('LINESTRING(0 0, 50 70, 100 100)'), 10, false, 'side=left')
+```
+
+Output:
+
+<img alt="Original Linestring" src="../../../image/linestring-og.png" width="150"/>
+<img alt="Original Linestring with buffer on the left side" src="../../../image/linestring-left-side.png" width="150"/>
+
+Original Linestring &emsp; Left side buffed Linestring
+
 ## ST_BuildArea
 
 Introduction: Returns the areal geometry formed by the constituent linework of the input geometry.

docs/api/sql/Function.md

@@ -551,9 +551,28 @@ Output: `LINESTRING Z(-1 -1 0, 10 5 5)`
 
 ## ST_Buffer
 
-Introduction: Returns a geometry/geography that represents all points whose distance from this Geometry/geography is less than or equal to distance.
+Introduction: Returns a geometry/geography that represents all points whose distance from this Geometry/geography is less than or equal to distance. The function supports both Planar/Euclidean and Spheroidal/Geodesic buffering (Since v1.6.0). Spheroidal buffer also supports geometries crossing the International Date Line (IDL).
 
-The optional third parameter controls the buffer accuracy and style. Buffer accuracy is specified by the number of line segments approximating a quarter circle, with a default of 8 segments. Buffer style can be set by providing blank-separated key=value pairs in a list format.
+Mode of buffer calculation (Since: `v1.6.0`):
+
+The optional third parameter, `useSpheroid`, controls the mode of buffer calculation.
+
+- Planar Buffering (default): When `useSpheroid` is false, `ST_Buffer` performs standard planar buffering based on the provided parameters.
+- Spheroidal Buffering:
+    - When `useSpheroid` is set to true, the function returns the spheroidal buffer polygon for more accurate representation over the Earth.
+    - ST_Buffer first determines the most appropriate Spatial Reference Identifier (SRID) for a given geometry, based on its spatial extent and location, using `ST_BestSRID`.
+    - The geometry is then transformed from its original SRID to the selected SRID. If the input geometry does not have a set SRID, `ST_Buffer` defaults to using WGS 84 (SRID 4326) as its original SRID.
+    - The standard planar buffer operation is then applied in this coordinate system.
+    - Finally, the buffered geometry is transformed back to its original SRID, or to WGS 84 if the original SRID was not set.
+
+!!!note
+    As of now, spheroidal buffering only supports lon/lat coordinate systems and will throw an `IllegalArgumentException` for input geometries in meter based coordinate systems.
+!!!note
+    Spheroidal buffering may not produce accurate output buffer for input geometries larger than a UTM zone.
+
+Buffer Style Parameters:
+
+The optional forth parameter controls the buffer accuracy and style. Buffer accuracy is specified by the number of line segments approximating a quarter circle, with a default of 8 segments. Buffer style can be set by providing blank-separated key=value pairs in a list format.
 
 - `quad_segs=#` : Number of line segments utilized to approximate a quarter circle (default is 8).
 - `endcap=round|flat|square` : End cap style (default is `round`). `butt` is an accepted synonym for `flat`.
@@ -567,16 +586,22 @@ The optional third parameter controls the buffer accuracy and style. Buffer accu
 Format:
 
 ```
-ST_Buffer (A: Geometry, buffer: Double, bufferStyleParameters: String [Optional])
+ST_Buffer (A: Geometry, buffer: Double)
+```
+```
+ST_Buffer (A: Geometry, buffer: Double, useSpheroid: Boolean)
+```
+```
+ST_Buffer (A: Geometry, buffer: Double, useSpheroid: Boolean, bufferStyleParameters: String)
 ```
 
 Since: `v1.5.1`
 
-Spark SQL Example:
+SQL Example:
 
 ```sql
 SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10)
-SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10, 'quad_segs=2')
+SELECT ST_Buffer(ST_GeomFromWKT('POINT(0 0)'), 10, false, 'quad_segs=2')
 ```
 
 Output:
@@ -586,10 +611,10 @@ Output:
 
 8 Segments   2 Segments
 
-Spark SQL Example:
+SQL Example:
 
 ```sql
-SELECT ST_Buffer(ST_GeomFromWKT('LINESTRING(0 0, 50 70, 100 100)'), 10, 'side=left')
+SELECT ST_Buffer(ST_GeomFromWKT('LINESTRING(0 0, 50 70, 100 100)'), 10, false, 'side=left')
 ```
 
 Output:

flink/src/main/java/org/apache/sedona/flink/expressions/Functions.java

@@ -13,13 +13,16 @@
  */
 package org.apache.sedona.flink.expressions;
 
+import org.apache.calcite.runtime.Geometries;
 import org.apache.commons.lang3.tuple.Pair;
 import org.apache.flink.table.annotation.DataTypeHint;
 import org.apache.flink.table.annotation.InputGroup;
 import org.apache.flink.table.functions.ScalarFunction;
 import org.apache.sedona.common.FunctionsGeoTools;
 import org.locationtech.jts.geom.Geometry;
 import org.locationtech.jts.operation.buffer.BufferParameters;
+import org.opengis.referencing.FactoryException;
+import org.opengis.referencing.operation.TransformException;
 
 import java.util.Arrays;
 
@@ -69,16 +72,23 @@ public Geometry eval(@DataTypeHint(value = "RAW", bridgedTo = org.locationtech.j
     public static class ST_Buffer extends ScalarFunction {
         @DataTypeHint(value = "RAW", bridgedTo = org.locationtech.jts.geom.Geometry.class)
         public Geometry eval(@DataTypeHint(value = "RAW", bridgedTo = org.locationtech.jts.geom.Geometry.class)
-        Object o, @DataTypeHint("Double") Double radius) {
+        Object o, @DataTypeHint("Double") Double radius) throws FactoryException, TransformException {
             Geometry geom = (Geometry) o;
             return org.apache.sedona.common.Functions.buffer(geom, radius);
         }
 
         @DataTypeHint(value = "RAW", bridgedTo = org.locationtech.jts.geom.Geometry.class)
         public Geometry eval(@DataTypeHint(value = "RAW", bridgedTo = org.locationtech.jts.geom.Geometry.class)
-                             Object o, @DataTypeHint("Double") Double radius, @DataTypeHint("String") String params) {
+                             Object o, @DataTypeHint("Double") Double radius, @DataTypeHint("Boolean") Boolean useSpheroid) throws FactoryException, TransformException {
             Geometry geom = (Geometry) o;
-            return org.apache.sedona.common.Functions.buffer(geom, radius, params);
+            return org.apache.sedona.common.Functions.buffer(geom, radius, useSpheroid);
+        }
+
+        @DataTypeHint(value = "RAW", bridgedTo = org.locationtech.jts.geom.Geometry.class)
+        public Geometry eval(@DataTypeHint(value = "RAW", bridgedTo = org.locationtech.jts.geom.Geometry.class)
+                             Object o, @DataTypeHint("Double") Double radius, @DataTypeHint("Boolean") Boolean useSpheroid, @DataTypeHint("String") String params) throws FactoryException, TransformException {
+            Geometry geom = (Geometry) o;
+            return org.apache.sedona.common.Functions.buffer(geom, radius, useSpheroid, params);
         }
     }