You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@sedona.apache.org by "jiayuasu (via GitHub)" <gi...@apache.org> on 2026/06/12 06:13:55 UTC

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

jiayuasu opened a new pull request, #3049:
URL: https://github.com/apache/sedona/pull/3049

   ## Did you read the Contributor Guide?
   
   - [x] Yes
   
   ## Is this PR related to a ticket?
   
   - [x] Yes — closes [#3048](https://github.com/apache/sedona/issues/3048); the documentation deliverable of the Box3D EPIC ([#2973](https://github.com/apache/sedona/issues/2973)).
   
   ## What changes were proposed in this PR?
   
   The Box3D SQL surface is fully shipped across Spark (Scala + Python) and Flink, but had no reference documentation. This adds it, mirroring the Box2D doc structure, plus a set of isometric SVG diagrams — 3D bbox semantics are much harder to grasp from prose alone than 2D.
   
   **Pages:**
   
   - `box3d/Box3D-Functions.md` landing page (semantic notes; constructor / accessor / predicate / function / aggregate tables; type conversion; query optimization). Added to the SQL nav and the Chinese `nav_translations`.
   - Constructors: `ST_Box3D`, `ST_3DMakeBox`.
   - Accessors: `ST_XMin` / `ST_YMin` / `ST_ZMin` / `ST_XMax` / `ST_YMax` / `ST_ZMax`.
   - Function: `ST_AsText(box3d)`.
   - Aggregate: `Aggregate-Functions/ST_3DExtent.md`.
   - Predicate: `Predicates/ST_3DDWithin.md`. The `ST_Intersects` / `ST_Contains` Box3D overloads are documented on those shared pages, which also get Box3D true/false figures.
   - Index rows for `ST_3DExtent` / `ST_3DDWithin` added to `Geometry-Functions.md`.
   
   **Diagrams** (`docs/image/box3d/`, generated with a consistent isometric axonometric projection so every cuboid is geometrically exact):
   
   - `box3d_anatomy`, `st_box3d`, `st_3dmakebox`, `st_3dextent`.
   - `st_intersects_box3d_{true,false}`, `st_contains_box3d_{true,false}`, `st_3ddwithin_{true,false}`. The **false** cases deliberately depict the XY-footprints-overlap-but-Z-ranges-disjoint scenario — the key 3D distinction a 2D bbox diagram cannot convey.
   
   The docs describe what ships today and note that Box3D filter pushdown and the inverse `CAST(box3d AS geometry)` are not yet implemented.
   
   ## How was this patch tested?
   
   - All 10 embedded image references and all cross-page links verified to resolve.
   - `markdownlint` / `yamllint` pre-commit hooks pass.
   - SVGs render correctly via `rsvg-convert` (spot-checked the anatomy, intersects, contains, and extent figures).
   
   ## Did this PR include necessary documentation updates?
   
   - [x] This PR is the documentation.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #3049:
URL: https://github.com/apache/sedona/pull/3049#discussion_r3401170707


##########
docs/api/sql/box3d/Box3D-Constructors/ST_3DMakeBox.md:
##########
@@ -0,0 +1,44 @@
+<!--
+ 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_3DMakeBox
+
+Introduction: Build a `Box3D` from two corner POINT Z geometries. Mirrors PostGIS's `ST_3DMakeBox`. The corners are taken verbatim — no swapping or validation of ordering — so inverted bounds are preserved as supplied. POINT inputs without a Z dimension contribute `z = 0`, matching PostGIS.
+
+![ST_3DMakeBox builds a cuboid from two corner POINT Z geometries](../../../../image/box3d/st_3dmakebox.svg "ST_3DMakeBox: cuboid from two corner points")
+
+Format: `ST_3DMakeBox(pointLowLeft: Geometry, pointUpRight: Geometry)`

Review Comment:
   The documented signature implies `ST_3DMakeBox` accepts arbitrary `Geometry` inputs, but the implementation throws `IllegalArgumentException` unless both arguments are POINT geometries (with missing Z folded to 0). Update the signature to `Point` to match actual behavior and the Box2D docs (`ST_MakeBox2D`).



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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

Posted by "jiayuasu (via GitHub)" <gi...@apache.org>.
jiayuasu merged PR #3049:
URL: https://github.com/apache/sedona/pull/3049


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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

Posted by "jiayuasu (via GitHub)" <gi...@apache.org>.
jiayuasu commented on code in PR #3049:
URL: https://github.com/apache/sedona/pull/3049#discussion_r3401203829


##########
docs/api/sql/box3d/Box3D-Constructors/ST_3DMakeBox.md:
##########
@@ -0,0 +1,44 @@
+<!--
+ 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_3DMakeBox
+
+Introduction: Build a `Box3D` from two corner POINT Z geometries. Mirrors PostGIS's `ST_3DMakeBox`. The corners are taken verbatim — no swapping or validation of ordering — so inverted bounds are preserved as supplied. POINT inputs without a Z dimension contribute `z = 0`, matching PostGIS.
+
+![ST_3DMakeBox builds a cuboid from two corner POINT Z geometries](../../../../image/box3d/st_3dmakebox.svg "ST_3DMakeBox: cuboid from two corner points")
+
+Format: `ST_3DMakeBox(pointLowLeft: Geometry, pointUpRight: Geometry)`

Review Comment:
   Fixed in latest push: signature is now `ST_3DMakeBox(lowerLeft: Point, upperRight: Point)`, matching the actual contract (throws `IllegalArgumentException` on non-POINT input) and the `ST_MakeBox2D` doc. The page body already noted the POINT requirement and the missing-Z-folds-to-0 behavior.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@sedona.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org