[GH-3021] Python Box3DType UDT bindings (#3022)

Author: jiayuasu

python/sedona/spark/__init__.py

@@ -57,6 +57,7 @@
 from sedona.spark.sql.st_predicates import *
 from sedona.spark.sql.types import (
     Box2DType,
+    Box3DType,
     GeometryType,
     GeographyType,
     RasterType,

python/sedona/spark/core/geom/box3d.py

@@ -0,0 +1,64 @@
+# 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 Box3D:
+    """Planar 3D 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. Matches PostGIS ``box3d`` semantics. Geometries without a
+    Z dimension contribute ``z = 0``; inverted bounds (``xmin > xmax`` etc.)
+    are rejected by the Box3D predicates since Z has no wraparound
+    convention."""
+
+    __slots__ = ("xmin", "ymin", "zmin", "xmax", "ymax", "zmax")
+
+    def __init__(
+        self,
+        xmin: float,
+        ymin: float,
+        zmin: float,
+        xmax: float,
+        ymax: float,
+        zmax: float,
+    ):
+        self.xmin = float(xmin)
+        self.ymin = float(ymin)
+        self.zmin = float(zmin)
+        self.xmax = float(xmax)
+        self.ymax = float(ymax)
+        self.zmax = float(zmax)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Box3D):
+            return NotImplemented
+        return (
+            self.xmin == other.xmin
+            and self.ymin == other.ymin
+            and self.zmin == other.zmin
+            and self.xmax == other.xmax
+            and self.ymax == other.ymax
+            and self.zmax == other.zmax
+        )
+
+    def __hash__(self) -> int:
+        return hash((self.xmin, self.ymin, self.zmin, self.xmax, self.ymax, self.zmax))
+
+    def __repr__(self) -> str:
+        return (
+            f"Box3D({self.xmin}, {self.ymin}, {self.zmin}, "
+            f"{self.xmax}, {self.ymax}, {self.zmax})"
+        )

python/sedona/spark/sql/__init__.py

@@ -32,6 +32,7 @@
 from sedona.spark.sql.st_predicates import *
 from sedona.spark.sql.types import (
     Box2DType,
+    Box3DType,
     GeometryType,
     GeographyType,
     RasterType,

python/sedona/spark/sql/types.py

@@ -41,6 +41,7 @@
 from sedona.spark.utils import geometry_serde
 from sedona.spark.core.geom.geography import Geography
 from sedona.spark.core.geom.box2d import Box2D
+from sedona.spark.core.geom.box3d import Box3D
 
 
 class GeometryType(UserDefinedType):
@@ -124,6 +125,39 @@ def scalaUDT(cls):
         return "org.apache.spark.sql.sedona_sql.UDT.Box2DUDT"
 
 
+class Box3DType(UserDefinedType):
+
+    @classmethod
+    def sqlType(cls):
+        return StructType(
+            [
+                StructField("xmin", DoubleType(), nullable=False),
+                StructField("ymin", DoubleType(), nullable=False),
+                StructField("zmin", DoubleType(), nullable=False),
+                StructField("xmax", DoubleType(), nullable=False),
+                StructField("ymax", DoubleType(), nullable=False),
+                StructField("zmax", DoubleType(), nullable=False),
+            ]
+        )
+
+    def serialize(self, obj):
+        return (obj.xmin, obj.ymin, obj.zmin, obj.xmax, obj.ymax, obj.zmax)
+
+    def deserialize(self, datum):
+        return Box3D(datum[0], datum[1], datum[2], datum[3], datum[4], datum[5])
+
+    @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.Box3DUDT"
+
+
 class RasterType(UserDefinedType):
 
     @classmethod

python/tests/sql/test_dataframe_api.py

@@ -27,6 +27,7 @@
 from tests.test_base import TestBase
 
 from sedona.spark.core.geom.box2d import Box2D
+from sedona.spark.core.geom.box3d import Box3D
 from sedona.spark.core.geom.geography import Geography
 from sedona.spark.sql import st_aggregates as sta
 from sedona.spark.sql import st_constructors as stc
@@ -181,9 +182,9 @@
         stc.ST_3DMakeBox,
         ("a", "b"),
         "two_points",
-        # Box3DType has no Python UDT yet; cast to STRING uses Box3D.toString for comparison.
-        "CAST(geom AS STRING)",
-        "BOX3D(0.0 0.0 0.0, 3.0 0.0 4.0)",
+        "",
+        # two_points has a=(0,0,0), b=(3,0,4).
+        Box3D(0.0, 0.0, 0.0, 3.0, 0.0, 4.0),
     ),
     (
         stc.ST_GeomFromBox2D,
@@ -559,10 +560,9 @@
         stf.ST_Box3D,
         ("line",),
         "linestring_geom",
-        # Box3DType has no Python UDT yet; cast to STRING uses Box3D.toString for comparison.
-        "CAST(geom AS STRING)",
+        "",
         # linestring_geom is 2D so Z folds to 0 per PostGIS semantics.
-        "BOX3D(0.0 0.0 0.0, 5.0 0.0 0.0)",
+        Box3D(0.0, 0.0, 0.0, 5.0, 0.0, 0.0),
     ),
     (
         stf.ST_Envelope,
@@ -1359,10 +1359,9 @@
         sta.ST_3DExtent,
         ("geom",),
         "exploded_points",
-        # Box3DType has no Python UDT yet; cast to STRING uses Box3D.toString for comparison.
-        "CAST(geom AS STRING)",
+        "",
         # 2D inputs fold Z=0 per PostGIS semantics.
-        "BOX3D(0.0 0.0 0.0, 1.0 1.0 0.0)",
+        Box3D(0.0, 0.0, 0.0, 1.0, 1.0, 0.0),
     ),
     # Test aliases for *_Aggr functions with *_Agg suffix
     (

spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/UDT/Box3DUDT.scala

@@ -40,9 +40,7 @@ class Box3DUDT extends UserDefinedType[Box3D] {
       StructField("ymax", DoubleType, nullable = false),
       StructField("zmax", DoubleType, nullable = false)))
 
-  // No `pyUDT` override yet — the Python `Box3DType` class is intentionally out of scope for
-  // Phase 1 (see #2973). It will be added together with the Python bindings follow-up, the
-  // same way Box2D paired `Box2DUDT.pyUDT` with `python/sedona/spark/sql/types.py::Box2DType`.
+  override def pyUDT: String = "sedona.spark.sql.types.Box3DType"
 
   override def userClass: Class[Box3D] = classOf[Box3D]