[GH-3048] Docs: Box3D SQL reference pages with isometric diagrams

docs/api/sql/Aggregate-Functions/ST_3DExtent.md

@@ -0,0 +1,50 @@
+<!--
+ 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_3DExtent
+
+Introduction: Return the 3D bounding box of all geometries in `A` as a typed [Box3D](../box3d/Box3D-Functions.md). Empty geometries and null values are skipped. If all inputs are empty or null, the result is null. Geometries without a Z dimension fold into `z = 0`. Mirrors PostGIS `ST_3DExtent`.
+
+`ST_3DExtent` is the 3D counterpart to [ST_Extent](ST_Extent.md), which returns a `Box2D`.
+
+![ST_3DExtent aggregates a column of geometries into the enclosing cuboid](../../../image/box3d/st_3dextent.svg "ST_3DExtent: enclosing cuboid over a column")
+
+Format: `ST_3DExtent(A: geometryColumn)`
+
+Return type: `Box3D`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_AsText(ST_3DExtent(geom))
+FROM VALUES
+    (ST_GeomFromText('POINT Z (1 2 3)')),
+    (ST_GeomFromText('POINT Z (4 5 -1)')),
+    (ST_GeomFromText('LINESTRING (-3 0, 0 0)')) AS t(geom)
+```
+
+Output:
+
+```
+BOX3D(-3.0 0.0 -1.0, 4.0 5.0 3.0)
+```
+
+The XY-only linestring contributes `z = 0`, which sits between the `-1` and `3` of the two POINT Z rows, so it does not move either Z bound.

docs/api/sql/Geometry-Functions.md

@@ -166,6 +166,7 @@ These functions test spatial relationships between geometries, returning boolean
 | [ST_Crosses](Predicates/ST_Crosses.md) | Boolean | Return true if A crosses B | v1.0.0 |
 | [ST_Disjoint](Predicates/ST_Disjoint.md) | Boolean | Return true if A and B are disjoint | v1.2.1 |
 | [ST_DWithin](Predicates/ST_DWithin.md) | Boolean | Returns true if 'leftGeometry' and 'rightGeometry' are within a specified 'distance'. | v1.5.1 |
+| [ST_3DDWithin](Predicates/ST_3DDWithin.md) | Boolean | Returns true if A and B are within a specified 3D Euclidean 'distance'. Accepts Geometry or Box3D inputs. | v1.9.1 |
 | [ST_Equals](Predicates/ST_Equals.md) | Boolean | Return true if A equals to B | v1.0.0 |
 | [ST_Intersects](Predicates/ST_Intersects.md) | Boolean | Return true if A intersects B | v1.0.0 |
 | [ST_OrderingEquals](Predicates/ST_OrderingEquals.md) | Boolean | Returns true if the geometries are equal and the coordinates are in the same order | v1.2.1 |
@@ -275,6 +276,7 @@ These functions perform aggregate operations on groups of geometries.
 | [ST_Collect_Agg](Aggregate-Functions/ST_Collect_Agg.md) | Geometry | Collects all geometries in a geometry column into a single multi-geometry (MultiPoint, MultiLineString, MultiPolygon, or GeometryCollection). Unlike `ST_Union_Agg`, this function does not dissolve ... | v1.8.1 |
 | [ST_Envelope_Agg](Aggregate-Functions/ST_Envelope_Agg.md) | Geometry | Return the entire envelope boundary of all geometries in A. Empty geometries and null values are skipped. If all inputs are empty or null, the result is null. This behavior is consistent with PostG... | v1.0.0 |
 | [ST_Extent](Aggregate-Functions/ST_Extent.md) | Box2D | Return the planar bounding box of all geometries in A as a typed Box2D. Empty geometries and NULL values are skipped. Mirrors PostGIS `ST_Extent`. | v1.9.1 |
+| [ST_3DExtent](Aggregate-Functions/ST_3DExtent.md) | Box3D | Return the 3D bounding box of all geometries in A as a typed Box3D. Empty/NULL skipped; geometries without Z fold to z=0. Mirrors PostGIS `ST_3DExtent`. | v1.9.1 |
 | [ST_Intersection_Agg](Aggregate-Functions/ST_Intersection_Agg.md) | Geometry | Return the polygon intersection of all polygons in A | v1.0.0 |
 | [ST_Union_Agg](Aggregate-Functions/ST_Union_Agg.md) | Geometry | Return the polygon union of all polygons in A | v1.0.0 |
 

docs/api/sql/Predicates/ST_3DDWithin.md

@@ -0,0 +1,69 @@
+<!--
+ 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_3DDWithin
+
+Introduction: Return true if the 3D Euclidean distance between `A` and `B` is less than or equal to `distance`. Mirrors PostGIS `ST_3DDWithin`. Polymorphic over input type:
+
+- `(Geometry, Geometry, Double)` — 3D distance via JTS; coordinates without a Z dimension are treated as `z = 0`.
+- `(Box3D, Box3D, Double)` — closed-interval 3D distance between two axis-aligned cuboids. Throws `IllegalArgumentException` on inverted bounds (`xmin > xmax`, `ymin > ymax`, or `zmin > zmax`).
+
+This is distinct from [ST_DWithin](ST_DWithin.md), which always measures planar (2D) distance regardless of input dimensionality — matching the PostGIS distinction between `ST_DWithin` and `ST_3DDWithin`.
+
+![ST_3DDWithin returning true: the 3D gap is within the distance](../../../image/box3d/st_3ddwithin_true.svg "ST_3DDWithin returning true")
+![ST_3DDWithin returning false: the 3D gap exceeds the distance](../../../image/box3d/st_3ddwithin_false.svg "ST_3DDWithin returning false")
+
+Format:
+
+- `ST_3DDWithin(A: Geometry, B: Geometry, distance: Double)`
+- `ST_3DDWithin(A: Box3D, B: Box3D, distance: Double)`
+
+Return type: `Boolean`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_3DDWithin(ST_PointZ(0, 0, 0), ST_PointZ(0, 0, 3), 3.0)
+```
+
+Output:
+
+```
+true
+```
+
+The same points are not within 2.9 units in 3D:
+
+```sql
+SELECT ST_3DDWithin(ST_PointZ(0, 0, 0), ST_PointZ(0, 0, 3), 2.9)
+```
+
+Output:
+
+```
+false
+```
+
+Returns `NULL` if any argument is `NULL`.
+
+## Optimization
+
+`ST_3DDWithin(a, b, distance)` between two `Box3D` columns (or two geometry columns) is planned as a distance join. The planner expands each shape's XY footprint by `distance` for the R-tree pass — a valid superset filter, since the XY distance between two shapes is no greater than their 3D distance — and re-checks the full 3D distance per candidate pair. See [Query optimization](../Optimizer.md).

docs/api/sql/Predicates/ST_Contains.md

@@ -66,6 +66,11 @@ Output:
 true
 ```
 
+For `Box3D` inputs containment must hold on all three axes — a box contained within another's XY footprint but extending past it in Z is **not** contained:
+
+![Box3D ST_Contains returning true: B lies fully inside A](../../../image/box3d/st_contains_box3d_true.svg "Box3D ST_Contains returning true")
+![Box3D ST_Contains returning false: B is inside in XY but extends past A in Z](../../../image/box3d/st_contains_box3d_false.svg "Box3D ST_Contains returning false")
+
 ## Box2D optimization
 
 `ST_Contains(box_col, lit_box)` over a `Box2D` column and a literal `Box2D` (and the reversed form) is recognised by Sedona's spatial optimizer:

docs/api/sql/Predicates/ST_Intersects.md

@@ -66,6 +66,11 @@ Output:
 true
 ```
 
+For `Box3D` inputs the test covers all three axes — two boxes whose XY footprints overlap but whose Z ranges are disjoint do **not** intersect:
+
+![Box3D ST_Intersects returning true: boxes overlap on all three axes](../../../image/box3d/st_intersects_box3d_true.svg "Box3D ST_Intersects returning true")
+![Box3D ST_Intersects returning false: XY overlaps but Z is disjoint](../../../image/box3d/st_intersects_box3d_false.svg "Box3D ST_Intersects returning false")
+
 ## Box2D optimization
 
 `ST_Intersects(box_col, lit_box)` over a `Box2D` column and a literal `Box2D` is recognised by Sedona's spatial optimizer:

docs/api/sql/box3d/Box3D-Accessors/ST_XMax.md

@@ -0,0 +1,42 @@
+<!--
+ 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_XMax
+
+Introduction: Return the maximum X coordinate of a `Box3D` value. This is the same function as the [Geometry-input form](../../Bounding-Box-Functions/ST_XMax.md), overloaded to accept a `Box3D`.
+
+Format: `ST_XMax(box: Box3D)`
+
+Return type: `Double`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_XMax(ST_3DMakeBox(ST_PointZ(0.0, 0.0, -3.0), ST_PointZ(5.0, 10.0, 7.0)))
+```
+
+Output:
+
+```
+5.0
+```
+
+Returns `NULL` on `NULL` input.

docs/api/sql/box3d/Box3D-Accessors/ST_XMin.md

@@ -0,0 +1,42 @@
+<!--
+ 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_XMin
+
+Introduction: Return the minimum X coordinate of a `Box3D` value. This is the same function as the [Geometry-input form](../../Bounding-Box-Functions/ST_XMin.md), overloaded to accept a `Box3D`.
+
+Format: `ST_XMin(box: Box3D)`
+
+Return type: `Double`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_XMin(ST_3DMakeBox(ST_PointZ(0.0, 0.0, -3.0), ST_PointZ(5.0, 10.0, 7.0)))
+```
+
+Output:
+
+```
+0.0
+```
+
+Returns `NULL` on `NULL` input.

docs/api/sql/box3d/Box3D-Accessors/ST_YMax.md

@@ -0,0 +1,42 @@
+<!--
+ 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_YMax
+
+Introduction: Return the maximum Y coordinate of a `Box3D` value. This is the same function as the [Geometry-input form](../../Bounding-Box-Functions/ST_YMax.md), overloaded to accept a `Box3D`.
+
+Format: `ST_YMax(box: Box3D)`
+
+Return type: `Double`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_YMax(ST_3DMakeBox(ST_PointZ(0.0, 0.0, -3.0), ST_PointZ(5.0, 10.0, 7.0)))
+```
+
+Output:
+
+```
+10.0
+```
+
+Returns `NULL` on `NULL` input.

docs/api/sql/box3d/Box3D-Accessors/ST_YMin.md

@@ -0,0 +1,42 @@
+<!--
+ 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_YMin
+
+Introduction: Return the minimum Y coordinate of a `Box3D` value. This is the same function as the [Geometry-input form](../../Bounding-Box-Functions/ST_YMin.md), overloaded to accept a `Box3D`.
+
+Format: `ST_YMin(box: Box3D)`
+
+Return type: `Double`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_YMin(ST_3DMakeBox(ST_PointZ(0.0, 0.0, -3.0), ST_PointZ(5.0, 10.0, 7.0)))
+```
+
+Output:
+
+```
+0.0
+```
+
+Returns `NULL` on `NULL` input.

docs/api/sql/box3d/Box3D-Accessors/ST_ZMax.md

@@ -0,0 +1,42 @@
+<!--
+ 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_ZMax
+
+Introduction: Return the maximum Z coordinate of a `Box3D` value. This is the same function as the [Geometry-input form](../../Bounding-Box-Functions/ST_ZMax.md), overloaded to accept a `Box3D`.
+
+Format: `ST_ZMax(box: Box3D)`
+
+Return type: `Double`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_ZMax(ST_3DMakeBox(ST_PointZ(0.0, 0.0, -3.0), ST_PointZ(5.0, 10.0, 7.0)))
+```
+
+Output:
+
+```
+7.0
+```
+
+Returns `NULL` on `NULL` input.