You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sedona.apache.org by ji...@apache.org on 2026/05/02 05:26:43 UTC

(sedona) branch master updated: [GH-2877] Add Box2D type and Box2DUDT (#2878)

This is an automated email from the ASF dual-hosted git repository.

jiayuasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git


The following commit(s) were added to refs/heads/master by this push:
     new 1786a14024 [GH-2877] Add Box2D type and Box2DUDT (#2878)
1786a14024 is described below

commit 1786a1402422a4fed31935f4b911422970ab5b84
Author: Jia Yu <ji...@apache.org>
AuthorDate: Fri May 1 22:26:38 2026 -0700

    [GH-2877] Add Box2D type and Box2DUDT (#2878)
---
 .../sedona/common/geometryObjects/Box2D.java       | 107 +++++++++++++++++++++
 python/sedona/spark/__init__.py                    |   7 +-
 python/sedona/spark/core/geom/box2d.py             |  47 +++++++++
 python/sedona/spark/sql/__init__.py                |   7 +-
 python/sedona/spark/sql/types.py                   |  40 +++++++-
 .../apache/spark/sql/sedona_sql/UDT/Box2DUDT.scala |  81 ++++++++++++++++
 .../sql/sedona_sql/UDT/UdtRegistratorWrapper.scala |   2 +
 .../org/apache/sedona/sql/Box2DUDTSuite.scala      |  82 ++++++++++++++++
 8 files changed, 370 insertions(+), 3 deletions(-)

diff --git a/common/src/main/java/org/apache/sedona/common/geometryObjects/Box2D.java b/common/src/main/java/org/apache/sedona/common/geometryObjects/Box2D.java
new file mode 100644
index 0000000000..b691e6d7c9
--- /dev/null
+++ b/common/src/main/java/org/apache/sedona/common/geometryObjects/Box2D.java
@@ -0,0 +1,107 @@
+/*
+ * 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.
+ */
+package org.apache.sedona.common.geometryObjects;
+
+import java.io.Serializable;
+import java.util.Objects;
+import org.locationtech.jts.geom.Envelope;
+import org.locationtech.jts.geom.Geometry;
+
+/**
+ * Planar 2D bounding box with min/max X and Y. Always a valid finite bbox; absence of a bbox (e.g.
+ * bbox of an empty geometry, extent over zero rows) is represented by SQL NULL at the column level
+ * rather than by an in-band sentinel. This matches PostGIS behavior and leaves {@code xmin > xmax}
+ * free for a future antimeridian-wraparound semantics on geography bboxes (cf. sedona-db's {@code
+ * WraparoundInterval}).
+ */
+public final class Box2D implements Serializable {
+
+  private final double xmin;
+  private final double ymin;
+  private final double xmax;
+  private final double ymax;
+
+  public Box2D(double xmin, double ymin, double xmax, double ymax) {
+    this.xmin = xmin;
+    this.ymin = ymin;
+    this.xmax = xmax;
+    this.ymax = ymax;
+  }
+
+  /** Returns the bbox of {@code geometry}, or {@code null} for null/empty geometry. */
+  public static Box2D fromGeometry(Geometry geometry) {
+    if (geometry == null || geometry.isEmpty()) {
+      return null;
+    }
+    Envelope env = geometry.getEnvelopeInternal();
+    return new Box2D(env.getMinX(), env.getMinY(), env.getMaxX(), env.getMaxY());
+  }
+
+  public double getXMin() {
+    return xmin;
+  }
+
+  public double getYMin() {
+    return ymin;
+  }
+
+  public double getXMax() {
+    return xmax;
+  }
+
+  public double getYMax() {
+    return ymax;
+  }
+
+  /**
+   * Returns the union of {@code this} and {@code other}. {@code other == null} is treated as a
+   * no-op, returning {@code this}, so callers can fold over a stream that may include nulls.
+   */
+  public Box2D expandToInclude(Box2D other) {
+    if (other == null) {
+      return this;
+    }
+    return new Box2D(
+        Math.min(xmin, other.xmin),
+        Math.min(ymin, other.ymin),
+        Math.max(xmax, other.xmax),
+        Math.max(ymax, other.ymax));
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof Box2D)) return false;
+    Box2D other = (Box2D) o;
+    return Double.compare(xmin, other.xmin) == 0
+        && Double.compare(ymin, other.ymin) == 0
+        && Double.compare(xmax, other.xmax) == 0
+        && Double.compare(ymax, other.ymax) == 0;
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(xmin, ymin, xmax, ymax);
+  }
+
+  @Override
+  public String toString() {
+    return "BOX(" + xmin + " " + ymin + ", " + xmax + " " + ymax + ")";
+  }
+}
diff --git a/python/sedona/spark/__init__.py b/python/sedona/spark/__init__.py
index 707aa24c95..70abbaf690 100644
--- a/python/sedona/spark/__init__.py
+++ b/python/sedona/spark/__init__.py
@@ -55,7 +55,12 @@ from sedona.spark.sql.st_aggregates import *
 from sedona.spark.sql.st_constructors import *
 from sedona.spark.sql.st_functions import *
 from sedona.spark.sql.st_predicates import *
-from sedona.spark.sql.types import GeometryType, GeographyType, RasterType
+from sedona.spark.sql.types import (
+    Box2DType,
+    GeometryType,
+    GeographyType,
+    RasterType,
+)
 from sedona.spark.stac import Client
 from sedona.spark.stac.collection_client import CollectionClient
 from sedona.spark.stats.clustering.dbscan import dbscan
diff --git a/python/sedona/spark/core/geom/box2d.py b/python/sedona/spark/core/geom/box2d.py
new file mode 100644
index 0000000000..1a1748e538
--- /dev/null
+++ b/python/sedona/spark/core/geom/box2d.py
@@ -0,0 +1,47 @@
+# 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.
+
+
+class Box2D:
+    """Planar 2D bounding box. Always a valid finite bbox; absence of a bbox
+    is represented by ``None`` (SQL NULL) at the column level rather than by an
+    in-band sentinel. This matches PostGIS behavior and leaves ``xmin > xmax``
+    free for a future antimeridian-wraparound semantics on geography bboxes."""
+
+    __slots__ = ("xmin", "ymin", "xmax", "ymax")
+
+    def __init__(self, xmin: float, ymin: float, xmax: float, ymax: float):
+        self.xmin = float(xmin)
+        self.ymin = float(ymin)
+        self.xmax = float(xmax)
+        self.ymax = float(ymax)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Box2D):
+            return NotImplemented
+        return (
+            self.xmin == other.xmin
+            and self.ymin == other.ymin
+            and self.xmax == other.xmax
+            and self.ymax == other.ymax
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.xmin, self.ymin, self.xmax, self.ymax))
+
+    def __repr__(self) -> str:
+        return f"Box2D({self.xmin}, {self.ymin}, {self.xmax}, {self.ymax})"
diff --git a/python/sedona/spark/sql/__init__.py b/python/sedona/spark/sql/__init__.py
index f193b1ce5e..ef3cf7df00 100644
--- a/python/sedona/spark/sql/__init__.py
+++ b/python/sedona/spark/sql/__init__.py
@@ -30,7 +30,12 @@ from sedona.spark.sql.st_aggregates import *
 from sedona.spark.sql.st_constructors import *
 from sedona.spark.sql.st_functions import *
 from sedona.spark.sql.st_predicates import *
-from sedona.spark.sql.types import GeometryType, GeographyType, RasterType
+from sedona.spark.sql.types import (
+    Box2DType,
+    GeometryType,
+    GeographyType,
+    RasterType,
+)
 
 __all__ = (
     [
diff --git a/python/sedona/spark/sql/types.py b/python/sedona/spark/sql/types.py
index 63267a1d5c..e5460673b6 100644
--- a/python/sedona/spark/sql/types.py
+++ b/python/sedona/spark/sql/types.py
@@ -15,7 +15,13 @@
 # specific language governing permissions and limitations
 # under the License.
 
-from pyspark.sql.types import BinaryType, UserDefinedType
+from pyspark.sql.types import (
+    BinaryType,
+    DoubleType,
+    StructField,
+    StructType,
+    UserDefinedType,
+)
 
 # Only support RasterType when rasterio is installed
 try:
@@ -34,6 +40,7 @@ else:
 
 from sedona.spark.utils import geometry_serde
 from sedona.spark.core.geom.geography import Geography
+from sedona.spark.core.geom.box2d import Box2D
 
 
 class GeometryType(UserDefinedType):
@@ -86,6 +93,37 @@ class GeographyType(UserDefinedType):
         return "org.apache.spark.sql.sedona_sql.UDT.GeographyUDT"
 
 
+class Box2DType(UserDefinedType):
+
+    @classmethod
+    def sqlType(cls):
+        return StructType(
+            [
+                StructField("xmin", DoubleType(), nullable=False),
+                StructField("ymin", DoubleType(), nullable=False),
+                StructField("xmax", DoubleType(), nullable=False),
+                StructField("ymax", DoubleType(), nullable=False),
+            ]
+        )
+
+    def serialize(self, obj):
+        return (obj.xmin, obj.ymin, obj.xmax, obj.ymax)
+
+    def deserialize(self, datum):
+        return Box2D(datum[0], datum[1], datum[2], datum[3])
+
+    @classmethod
+    def module(cls):
+        return "sedona.spark.sql.types"
+
+    def needConversion(self):
+        return True
+
+    @classmethod
+    def scalaUDT(cls):
+        return "org.apache.spark.sql.sedona_sql.UDT.Box2DUDT"
+
+
 class RasterType(UserDefinedType):
 
     @classmethod
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/Box2DUDT.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/Box2DUDT.scala
new file mode 100644
index 0000000000..c771dc0999
--- /dev/null
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/Box2DUDT.scala
@@ -0,0 +1,81 @@
+/*
+ * 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.
+ */
+package org.apache.spark.sql.sedona_sql.UDT
+
+import org.apache.sedona.common.geometryObjects.Box2D
+import org.apache.spark.sql.catalyst.InternalRow
+import org.apache.spark.sql.catalyst.expressions.GenericInternalRow
+import org.apache.spark.sql.types._
+import org.json4s.JsonAST.JValue
+import org.json4s.JsonDSL._
+
+/**
+ * UDT for [[Box2D]]. Stored as a Spark struct of four non-nullable doubles (`xmin`, `ymin`,
+ * `xmax`, `ymax`) so values round-trip natively to Parquet and align with GeoParquet 1.1 bbox
+ * covering columns.
+ */
+class Box2DUDT extends UserDefinedType[Box2D] {
+
+  override def sqlType: DataType = StructType(
+    Seq(
+      StructField("xmin", DoubleType, nullable = false),
+      StructField("ymin", DoubleType, nullable = false),
+      StructField("xmax", DoubleType, nullable = false),
+      StructField("ymax", DoubleType, nullable = false)))
+
+  override def pyUDT: String = "sedona.spark.sql.types.Box2DType"
+
+  override def userClass: Class[Box2D] = classOf[Box2D]
+
+  override def serialize(obj: Box2D): InternalRow = {
+    val row = new GenericInternalRow(4)
+    row.setDouble(0, obj.getXMin)
+    row.setDouble(1, obj.getYMin)
+    row.setDouble(2, obj.getXMax)
+    row.setDouble(3, obj.getYMax)
+    row
+  }
+
+  override def deserialize(datum: Any): Box2D = datum match {
+    case row: InternalRow =>
+      new Box2D(row.getDouble(0), row.getDouble(1), row.getDouble(2), row.getDouble(3))
+  }
+
+  override private[sql] def jsonValue: JValue = {
+    super.jsonValue mapField {
+      case ("class", _) => "class" -> this.getClass.getName.stripSuffix("$")
+      case other: Any => other
+    }
+  }
+
+  override def equals(other: Any): Boolean = other match {
+    case _: UserDefinedType[_] => other.isInstanceOf[Box2DUDT]
+    case _ => false
+  }
+
+  override def hashCode(): Int = userClass.hashCode()
+
+  override def toString: String = "Box2DUDT"
+}
+
+case object Box2DUDT
+    extends org.apache.spark.sql.sedona_sql.UDT.Box2DUDT
+    with scala.Serializable {
+  def apply(): Box2DUDT = new Box2DUDT()
+}
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/UdtRegistratorWrapper.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/UdtRegistratorWrapper.scala
index 9b0179fce6..cf9a44aa97 100644
--- a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/UdtRegistratorWrapper.scala
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/UdtRegistratorWrapper.scala
@@ -19,6 +19,7 @@
 package org.apache.spark.sql.sedona_sql.UDT
 
 import org.apache.sedona.common.S2Geography.Geography
+import org.apache.sedona.common.geometryObjects.Box2D
 import org.apache.spark.sql.types.UDTRegistration
 import org.locationtech.jts.geom.Geometry
 import org.locationtech.jts.index.SpatialIndex
@@ -28,6 +29,7 @@ object UdtRegistratorWrapper {
   def registerAll(): Unit = {
     registerIfNotExists(classOf[Geometry].getName, classOf[GeometryUDT].getName)
     registerIfNotExists(classOf[Geography].getName, classOf[GeographyUDT].getName)
+    registerIfNotExists(classOf[Box2D].getName, classOf[Box2DUDT].getName)
     registerIfNotExists(classOf[SpatialIndex].getName, classOf[IndexUDT].getName)
   }
 
diff --git a/spark/common/src/test/scala/org/apache/sedona/sql/Box2DUDTSuite.scala b/spark/common/src/test/scala/org/apache/sedona/sql/Box2DUDTSuite.scala
new file mode 100644
index 0000000000..0779d675ff
--- /dev/null
+++ b/spark/common/src/test/scala/org/apache/sedona/sql/Box2DUDTSuite.scala
@@ -0,0 +1,82 @@
+/*
+ * 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.
+ */
+package org.apache.sedona.sql
+
+import org.apache.sedona.common.geometryObjects.Box2D
+import org.apache.spark.sql.Row
+import org.apache.spark.sql.sedona_sql.UDT.Box2DUDT
+import org.apache.spark.sql.types.{DataType, IntegerType, StructType, UDTRegistration}
+import org.junit.rules.TemporaryFolder
+import org.scalatest.BeforeAndAfter
+
+class Box2DUDTSuite extends TestBaseScala with BeforeAndAfter {
+
+  val tempFolder: TemporaryFolder = new TemporaryFolder
+
+  before {
+    tempFolder.create()
+  }
+
+  after {
+    tempFolder.delete()
+  }
+
+  describe("Box2DUDT") {
+    it("registers Box2D via UdtRegistratorWrapper") {
+      assert(UDTRegistration.exists(classOf[Box2D].getName))
+    }
+
+    it("renders and parses a JSON schema round-trip") {
+      val schema = new StructType().add("box", new Box2DUDT())
+      assert(DataType.fromJson(schema.json).asInstanceOf[StructType] == schema)
+    }
+
+    it("serializes and deserializes a Box2D round-trip") {
+      val udt = new Box2DUDT()
+      val box = new Box2D(-10.0, -20.0, 30.0, 40.0)
+      assert(udt.deserialize(udt.serialize(box)) == box)
+    }
+
+    it("case object equals a fresh instance") {
+      val instance = new Box2DUDT()
+      assert(Box2DUDT == Box2DUDT)
+      assert(instance.equals(instance))
+      assert(instance.equals(Box2DUDT))
+      assert(Box2DUDT.equals(instance))
+      assert(instance.hashCode() == Box2DUDT.hashCode())
+    }
+
+    it("writes and reads a Box2D column via Parquet") {
+      val box = new Box2D(1.0, 2.0, 3.0, 4.0)
+      val schema = new StructType()
+        .add("id", IntegerType, nullable = false)
+        .add("bbox", new Box2DUDT(), nullable = false)
+      val rdd = sparkSession.sparkContext.parallelize(Seq(Row(1, box)))
+      val df = sparkSession.createDataFrame(rdd, schema)
+
+      val path = tempFolder.getRoot.getPath + "/box2d-parquet"
+      df.write.parquet(path)
+
+      val read = sparkSession.read.parquet(path)
+      val row = read.collect()(0)
+      assert(row.getAs[Int]("id") == 1)
+      assert(row.getAs[Box2D]("bbox") == box)
+    }
+  }
+}