[GH-3048] Docs: Box3D SQL reference pages with isometric diagrams#3049
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds missing SQL reference documentation for Sedona’s Box3D type (Spark + Flink), mirroring the existing Box2D doc structure and augmenting predicate/aggregate pages with new isometric SVG diagrams to clarify 3D bounding-box semantics.
Changes:
- Adds a new Box3D SQL docs section (landing page + constructor/accessor/function references) and wires it into the MkDocs navigation (including Chinese nav translations).
- Documents Box3D-specific semantics for shared predicates (
ST_Intersects,ST_Contains), adds a dedicatedST_3DDWithinpredicate page, and documentsST_3DExtent. - Adds a set of Box3D isometric SVG diagrams used across the new/updated docs pages.
Reviewed changes
Copilot reviewed 16 out of 26 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds Box3D landing page to SQL nav + i18n nav translation. |
| docs/api/sql/Geometry-Functions.md | Adds index-table entries for ST_3DDWithin and ST_3DExtent. |
| docs/api/sql/Predicates/ST_Intersects.md | Documents Box3D overload semantics with true/false figures. |
| docs/api/sql/Predicates/ST_Contains.md | Documents Box3D overload semantics with true/false figures. |
| docs/api/sql/Predicates/ST_3DDWithin.md | New reference page for the 3D distance predicate, including optimization notes and figures. |
| docs/api/sql/Aggregate-Functions/ST_3DExtent.md | New reference page for the Box3D extent aggregate, including figure and example. |
| docs/api/sql/box3d/Box3D-Functions.md | New Box3D landing page (semantics, tables, type conversion, optimization). |
| docs/api/sql/box3d/Box3D-Functions/ST_AsText.md | Documents ST_AsText(box3d) overload and output format. |
| docs/api/sql/box3d/Box3D-Constructors/ST_Box3D.md | Documents ST_Box3D constructor and behavior for XY-only geometries. |
| docs/api/sql/box3d/Box3D-Constructors/ST_3DMakeBox.md | Documents ST_3DMakeBox constructor with example and error behavior. |
| docs/api/sql/box3d/Box3D-Accessors/ST_XMin.md | New Box3D accessor reference for ST_XMin(box3d). |
| docs/api/sql/box3d/Box3D-Accessors/ST_YMin.md | New Box3D accessor reference for ST_YMin(box3d). |
| docs/api/sql/box3d/Box3D-Accessors/ST_ZMin.md | New Box3D accessor reference for ST_ZMin(box3d). |
| docs/api/sql/box3d/Box3D-Accessors/ST_XMax.md | New Box3D accessor reference for ST_XMax(box3d). |
| docs/api/sql/box3d/Box3D-Accessors/ST_YMax.md | New Box3D accessor reference for ST_YMax(box3d). |
| docs/api/sql/box3d/Box3D-Accessors/ST_ZMax.md | New Box3D accessor reference for ST_ZMax(box3d). |
| docs/image/box3d/box3d_anatomy.svg | New Box3D anatomy diagram. |
| docs/image/box3d/st_box3d.svg | New diagram for ST_Box3D. |
| docs/image/box3d/st_3dmakebox.svg | New diagram for ST_3DMakeBox. |
| docs/image/box3d/st_3dextent.svg | New diagram for ST_3DExtent. |
| docs/image/box3d/st_intersects_box3d_true.svg | New Box3D ST_Intersects true-case diagram. |
| docs/image/box3d/st_intersects_box3d_false.svg | New Box3D ST_Intersects false-case (Z-disjoint) diagram. |
| docs/image/box3d/st_contains_box3d_true.svg | New Box3D ST_Contains true-case diagram. |
| docs/image/box3d/st_contains_box3d_false.svg | New Box3D ST_Contains false-case (Z overflow) diagram. |
| docs/image/box3d/st_3ddwithin_true.svg | New Box3D ST_3DDWithin true-case diagram. |
| docs/image/box3d/st_3ddwithin_false.svg | New Box3D ST_3DDWithin false-case diagram. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
|  | ||
|
|
||
| Format: `ST_3DMakeBox(pointLowLeft: Geometry, pointUpRight: Geometry)` |
Member
Author
There was a problem hiding this 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.
The Box3D SQL surface is fully shipped across Spark and Flink but had no
reference docs. Adds them, mirroring the Box2D doc structure, plus a set
of isometric SVG diagrams (3D is harder to grasp from prose than 2D).
Pages:
- box3d/Box3D-Functions.md landing page (added to SQL nav + 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; Box3D true/false figures also
added to the shared ST_Intersects / ST_Contains pages.
- Index rows for ST_3DExtent / ST_3DDWithin in Geometry-Functions.md.
Diagrams (docs/image/box3d/, isometric axonometric projection):
- 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 show the
XY-overlap-but-Z-disjoint scenario — the key 3D distinction that a
2D bbox diagram cannot convey.
Notes that Box3D filter pushdown and the inverse CAST(box3d AS geometry)
are not yet implemented.
a6152b5 to
bab3432
Compare
10 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Did you read the Contributor Guide?
Is this PR related to a ticket?
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.mdlanding page (semantic notes; constructor / accessor / predicate / function / aggregate tables; type conversion; query optimization). Added to the SQL nav and the Chinesenav_translations.ST_Box3D,ST_3DMakeBox.ST_XMin/ST_YMin/ST_ZMin/ST_XMax/ST_YMax/ST_ZMax.ST_AsText(box3d).Aggregate-Functions/ST_3DExtent.md.Predicates/ST_3DDWithin.md. TheST_Intersects/ST_ContainsBox3D overloads are documented on those shared pages, which also get Box3D true/false figures.ST_3DExtent/ST_3DDWithinadded toGeometry-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?
markdownlint/yamllintpre-commit hooks pass.rsvg-convert(spot-checked the anatomy, intersects, contains, and extent figures).Did this PR include necessary documentation updates?