[GH-2830] Adds Geography dual-dispatch to ST_Centroid (#2852)

Co-authored-by: Jia Yu <jiayu@apache.org>

Author: zhangfengcdt

common/src/main/java/org/apache/sedona/common/geography/Functions.java

@@ -85,6 +85,86 @@ public static int nPoints(Geography g) {
     return toJTS(g).getNumPoints();
   }
 
+  /**
+   * Returns the spherical centroid of a geography as a {@link Geography} point. The centroid is
+   * computed on the sphere using S2 area- and length-weighting:
+   *
+   * <ul>
+   *   <li>Polygon / MultiPolygon: area-weighted centroid via {@link S2Polygon#getCentroid()}.
+   *   <li>LineString / MultiLineString: length-weighted centroid via {@link
+   *       S2Polyline#getCentroid()}.
+   *   <li>Point / MultiPoint: mean of the unit vectors.
+   *   <li>GeographyCollection: weighted sum of the children's S2 centroids.
+   * </ul>
+   *
+   * <p>Unlike a planar (lon/lat) centroid, this answer is correct for antimeridian-crossing and
+   * polar geographies. As with JTS for non-convex shapes, the centroid may lie outside the input
+   * geometry. Returns {@code null} if the input is {@code null} or if the centroid is undefined
+   * (e.g. an empty geometry, or antipodal points whose unit vectors cancel).
+   */
+  public static Geography centroid(Geography g) {
+    if (g == null) return null;
+    Geography typed = (g instanceof WKBGeography) ? ((WKBGeography) g).getS2Geography() : g;
+    S2Point weighted = sphericalCentroid(typed);
+    if (weighted == null) return null;
+    // S2 returns area- (or length-) weighted centroids; project back to the sphere.
+    double norm = weighted.norm();
+    if (!(norm > 0.0)) return null; // zero or NaN — centroid undefined
+    S2Point unit = S2Point.normalize(weighted);
+    SinglePointGeography point = new SinglePointGeography(unit);
+    point.setSRID(g.getSRID());
+    return WKBGeography.fromS2Geography(point);
+  }
+
+  /**
+   * Returns the S2-weighted centroid of {@code g} (area-weighted for polygons, length-weighted for
+   * polylines, sum of unit vectors for points). Result is {@code null} when no centroid
+   * contribution exists (empty input, unsupported kind).
+   */
+  private static S2Point sphericalCentroid(Geography g) {
+    if (g instanceof PointGeography) {
+      List<S2Point> pts = ((PointGeography) g).getPoints();
+      if (pts == null || pts.isEmpty()) return null;
+      S2Point sum = pts.get(0);
+      for (int i = 1; i < pts.size(); i++) {
+        sum = S2Point.add(sum, pts.get(i));
+      }
+      return sum;
+    }
+    if (g instanceof PolylineGeography) {
+      S2Point sum = null;
+      for (S2Polyline p : ((PolylineGeography) g).getPolylines()) {
+        sum = addOrInit(sum, p.getCentroid());
+      }
+      return sum;
+    }
+    if (g instanceof PolygonGeography) {
+      return ((PolygonGeography) g).polygon.getCentroid();
+    }
+    if (g instanceof MultiPolygonGeography) {
+      S2Point sum = null;
+      for (Geography feature : ((MultiPolygonGeography) g).getFeatures()) {
+        if (feature instanceof PolygonGeography) {
+          sum = addOrInit(sum, ((PolygonGeography) feature).polygon.getCentroid());
+        }
+      }
+      return sum;
+    }
+    if (g instanceof GeographyCollection) {
+      S2Point sum = null;
+      for (Geography feature : ((GeographyCollection) g).getFeatures()) {
+        sum = addOrInit(sum, sphericalCentroid(feature));
+      }
+      return sum;
+    }
+    return null;
+  }
+
+  private static S2Point addOrInit(S2Point sum, S2Point next) {
+    if (next == null) return sum;
+    return (sum == null) ? next : S2Point.add(sum, next);
+  }
+
   /** Return the number of sub-geometries in a geography (1 for singles). */
   public static int numGeometries(Geography g) {
     if (g == null) return 0;

common/src/test/java/org/apache/sedona/common/Geography/FunctionTest.java

@@ -148,6 +148,99 @@ public void nPoints_polygon() throws ParseException {
     assertEquals(5, Functions.nPoints(g));
   }
 
+  // S2 area-weighted centroids on small polygons differ from planar by an O(d^2/R^2)
+  // spherical correction. 5e-3 deg (~500 m) is wide enough to absorb that drift on
+  // 1°-scale shapes near origin, while still catching any real bug (a planar/JTS centroid
+  // of an antimeridian polygon would be off by ~180°, not by hundreds of metres).
+  private static final double CENTROID_TOL_DEG = 5e-3;
+
+  @Test
+  public void centroid_squarePolygon() throws ParseException {
+    Geography g = Constructors.geogFromWKT("POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))", 4326);
+    Geography c = Functions.centroid(g);
+    assertNotNull(c);
+    assertEquals(4326, c.getSRID());
+    org.locationtech.jts.geom.Point p =
+        (org.locationtech.jts.geom.Point) Constructors.geogToGeometry(c);
+    assertEquals(1.0, p.getX(), CENTROID_TOL_DEG);
+    assertEquals(1.0, p.getY(), CENTROID_TOL_DEG);
+  }
+
+  @Test
+  public void centroid_linestring() throws ParseException {
+    Geography g = Constructors.geogFromWKT("LINESTRING (0 0, 2 0)", 4326);
+    Geography c = Functions.centroid(g);
+    assertNotNull(c);
+    org.locationtech.jts.geom.Point p =
+        (org.locationtech.jts.geom.Point) Constructors.geogToGeometry(c);
+    assertEquals(1.0, p.getX(), CENTROID_TOL_DEG);
+    assertEquals(0.0, p.getY(), CENTROID_TOL_DEG);
+  }
+
+  @Test
+  public void centroid_point() throws ParseException {
+    Geography g = Constructors.geogFromWKT("POINT (3 4)", 4326);
+    Geography c = Functions.centroid(g);
+    assertNotNull(c);
+    org.locationtech.jts.geom.Point p =
+        (org.locationtech.jts.geom.Point) Constructors.geogToGeometry(c);
+    // A single point's centroid is the point itself — exact.
+    assertEquals(3.0, p.getX(), 1e-9);
+    assertEquals(4.0, p.getY(), 1e-9);
+  }
+
+  @Test
+  public void centroid_multipoint_meanOfUnitVectors() throws ParseException {
+    Geography g = Constructors.geogFromWKT("MULTIPOINT ((-1 0), (1 0))", 4326);
+    Geography c = Functions.centroid(g);
+    assertNotNull(c);
+    org.locationtech.jts.geom.Point p =
+        (org.locationtech.jts.geom.Point) Constructors.geogToGeometry(c);
+    // Mean of unit vectors at (-1, 0) and (1, 0) lands on (0, 0).
+    assertEquals(0.0, p.getX(), CENTROID_TOL_DEG);
+    assertEquals(0.0, p.getY(), CENTROID_TOL_DEG);
+  }
+
+  @Test
+  public void centroid_multipolygon() throws ParseException {
+    // Two unit squares at (0..1, 0..1) and (10..11, 0..1). Equal area, so the area-weighted
+    // centroid should sit at the midpoint between the per-polygon centroids ≈ (5.5, 0.5).
+    Geography g =
+        Constructors.geogFromWKT(
+            "MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((10 0, 11 0, 11 1, 10 1, 10 0)))", 4326);
+    Geography c = Functions.centroid(g);
+    assertNotNull(c);
+    org.locationtech.jts.geom.Point p =
+        (org.locationtech.jts.geom.Point) Constructors.geogToGeometry(c);
+    assertEquals(5.5, p.getX(), CENTROID_TOL_DEG);
+    assertEquals(0.5, p.getY(), CENTROID_TOL_DEG);
+  }
+
+  @Test
+  public void centroid_antimeridianPolygon_isOnTheAntimeridian() throws ParseException {
+    // Thin band straddling 180°E. A planar JTS centroid would average the lons and land
+    // at lon ≈ 0 (the wrong side of the planet). The spherical centroid stays near ±180.
+    Geography g =
+        Constructors.geogFromWKT("POLYGON ((170 -1, -170 -1, -170 1, 170 1, 170 -1))", 4326);
+    Geography c = Functions.centroid(g);
+    assertNotNull(c);
+    org.locationtech.jts.geom.Point p =
+        (org.locationtech.jts.geom.Point) Constructors.geogToGeometry(c);
+    double lon = p.getX();
+    double lat = p.getY();
+    // |lon| close to 180 (either side of the wrap), lat close to 0.
+    double lonDistFromAntimeridian = Math.min(Math.abs(lon - 180.0), Math.abs(lon + 180.0));
+    assertTrue(
+        "expected centroid near the antimeridian; got (" + lon + ", " + lat + ")",
+        lonDistFromAntimeridian < 0.5);
+    assertEquals(0.0, lat, 0.5);
+  }
+
+  @Test
+  public void centroid_nullHandling() {
+    assertNull(Functions.centroid(null));
+  }
+
   @Test
   public void numGeometries_point() throws ParseException {
     Geography g = Constructors.geogFromWKT("POINT (1 2)", 4326);

docs/api/sql/geography/Geography-Functions.md

@@ -44,6 +44,7 @@ These functions operate on geography type objects.
 | [ST_Area](Geography-Functions/ST_Area.md) | Double | Return the geodesic area of a geography in square meters (WGS84 spheroid). | v1.9.1 |
 | [ST_AsEWKT](Geography-Functions/ST_AsEWKT.md) | String | Return the Extended Well-Known Text representation of a geography. | v1.8.0 |
 | [ST_AsText](Geography-Functions/ST_AsText.md) | String | Return the Well-Known Text (WKT) representation of a geography. | v1.9.1 |
+| [ST_Centroid](Geography-Functions/ST_Centroid.md) | Geography | Return the planar centroid of a geography as a Geography point (computed in projected lon/lat space). | v1.9.1 |
 | [ST_Buffer](Geography-Functions/ST_Buffer.md) | Geography | Return the metric ε-buffer of a geography. Distance is always interpreted as meters along the spheroid. | v1.9.1 |
 | [ST_Envelope](Geography-Functions/ST_Envelope.md) | Geography | Return the bounding box (envelope) of a geography. Supports anti-meridian splitting. | v1.8.0 |
 | [ST_GeometryType](Geography-Functions/ST_GeometryType.md) | String | Return the type of a geography as a string (e.g., "ST_Point", "ST_Polygon"). | v1.9.1 |

docs/api/sql/geography/Geography-Functions/ST_Centroid.md

@@ -0,0 +1,56 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# ST_Centroid
+
+Introduction: Returns the spherical centroid of a geography as a Geography point, computed on the sphere using S2:
+
+- **Polygon / MultiPolygon** — area-weighted centroid via `S2Polygon.getCentroid()`.
+- **LineString / MultiLineString** — length-weighted centroid via `S2Polyline.getCentroid()`.
+- **Point / MultiPoint** — mean of the unit vectors.
+- **GeographyCollection** — recursive weighted sum across the children.
+
+The result is the unit-length centroid on the sphere. Unlike a planar (lon/lat) centroid, it is correct for antimeridian-crossing and high-latitude geographies. As with JTS for non-convex shapes, the centroid may lie outside the input geometry. Returns `NULL` when the centroid is undefined (empty geometry, or antipodal points whose unit vectors cancel).
+
+Format:
+
+`ST_Centroid (A: Geography)`
+
+Return type: `Geography`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_AsEWKT(ST_Centroid(ST_GeogFromWKT('POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))')));
+```
+
+Output (small `O(d²/R²)` spherical correction vs the planar `(1 1)`):
+
+```
+POINT (1 1)
+```
+
+For an antimeridian-crossing polygon, the spherical centroid stays on the antimeridian instead of jumping to the opposite side of the planet, which a planar centroid would do:
+
+```sql
+SELECT ST_AsEWKT(ST_Centroid(ST_GeogFromWKT('POLYGON ((170 -1, -170 -1, -170 1, 170 1, 170 -1))')));
+-- result: POINT near (180, 0) (or (-180, 0)), NOT (0, 0)
+```

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

@@ -301,7 +301,9 @@ private[apache] case class ST_Area(inputExpressions: Seq[Expression])
  * @param inputExpressions
  */
 private[apache] case class ST_Centroid(inputExpressions: Seq[Expression])
-    extends InferredExpression(Functions.getCentroid _) {
+    extends InferredExpression(
+      inferrableFunction1(Functions.getCentroid),
+      inferrableFunction1(org.apache.sedona.common.geography.Functions.centroid)) {
 
   protected def withNewChildrenInternal(newChildren: IndexedSeq[Expression]) = {
     copy(inputExpressions = newChildren)

spark/common/src/test/scala/org/apache/sedona/sql/geography/GeographyFunctionTest.scala

@@ -23,7 +23,7 @@ import org.apache.sedona.sql.TestBaseScala
 import org.apache.spark.sql.functions.{col, lit}
 import org.apache.spark.sql.sedona_sql.expressions.{st_constructors, st_functions, st_predicates}
 import org.junit.Assert.{assertEquals, assertNotNull, assertTrue}
-import org.locationtech.jts.geom.{Geometry, Point}
+import org.locationtech.jts.geom.Point
 import org.locationtech.jts.io.WKTReader
 
 /**
@@ -78,7 +78,7 @@ class GeographyFunctionTest extends TestBaseScala {
     }
   }
 
-  // ─── Level 1: ST_NPoints, ST_NumGeometries, ST_GeometryType, ST_AsText ──
+  // ─── Level 1: ST_NPoints, ST_Centroid, ST_NumGeometries, ST_GeometryType, ST_AsText ─
 
   describe("Level 1: Structural") {
 
@@ -89,6 +89,19 @@ class GeographyFunctionTest extends TestBaseScala {
       assertEquals(3, row.getInt(0))
     }
 
+    it("ST_Centroid square polygon") {
+      val row = sparkSession
+        .sql(
+          "SELECT ST_Centroid(ST_GeogFromWKT('POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))', 4326)) AS c")
+        .first()
+      val centroid = row.get(0).asInstanceOf[Geography]
+      val point = new WKTReader().read(centroid.toString).asInstanceOf[Point]
+      // Spherical area-weighted centroid of a 2x2° square at origin is ~(1, 1) with an
+      // O(d^2/R^2) spherical correction; 5e-3° is well within that band.
+      assertEquals(1.0, point.getX, 5e-3)
+      assertEquals(1.0, point.getY, 5e-3)
+    }
+
     it("ST_NumGeometries single") {
       val row = sparkSession
         .sql("SELECT ST_NumGeometries(ST_GeogFromWKT('POINT (1 2)', 4326)) AS n")