Skip to content

[DOCS] Correct geography area/length radius wording: spherical mean radius, not authalic or WGS84 spheroid#3079

Merged
jiayuasu merged 1 commit into
apache:masterfrom
jiayuasu:fix-geography-area-doc-spheroid
Jun 22, 2026
Merged

[DOCS] Correct geography area/length radius wording: spherical mean radius, not authalic or WGS84 spheroid#3079
jiayuasu merged 1 commit into
apache:masterfrom
jiayuasu:fix-geography-area-doc-spheroid

Conversation

@jiayuasu

@jiayuasu jiayuasu commented Jun 22, 2026

Copy link
Copy Markdown
Member

Did you read the Contributor Guide?

Is this PR related to a ticket?

  • No:
    • this is a documentation update. The PR name follows the format [DOCS] my subject

What changes were proposed in this PR?

Corrects the radius wording in the geography area/length docs to match the implementation.

common/src/main/java/org/apache/sedona/common/geography/Functions.java computes ST_Area and ST_Length on a sphere, scaling by org.apache.sedona.common.sphere.Haversine.AVG_EARTH_RADIUS, which is defined as 6371008.0 meters. That value is the mean Earth radius (IUGG R1 = (2a + b) / 3 ≈ 6 371 008.8 m), and the constant is named AVG_EARTH_RADIUS accordingly. It is not the WGS84 ellipsoid, and it is not the authalic radius (R2 ≈ 6 371 007.2 m).

Two inaccuracies are fixed:

  • The ST_Area overview row in docs/api/sql/geography/Geography-Functions.md said "WGS84 spheroid" — the computation is spherical, not ellipsoidal.
  • Several pages labeled R = 6 371 008 m as the "authalic Earth radius" — that value is the mean radius. Reworded to "mean Earth radius" in the Spark ST_Area/ST_Length pages and the SedonaFlink geography overview and ST_Area page.

How was this patch tested?

mkdocs build succeeds; the changed pages have no new warnings and all links resolve.

Did this PR include necessary documentation updates?

  • Yes, I have updated the documentation.

@jiayuasu jiayuasu force-pushed the fix-geography-area-doc-spheroid branch 2 times, most recently from bef0ad4 to b236b2c Compare June 22, 2026 16:50
@jiayuasu jiayuasu changed the title [DOCS] Correct ST_Area geography description: spherical, not WGS84 spheroid [DOCS] Correct geography area/length radius wording: spherical mean radius, not authalic or WGS84 spheroid Jun 22, 2026
@jiayuasu jiayuasu requested a review from Copilot June 22, 2026 17:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates Sedona geography documentation to correctly describe the Earth model and radius used by ST_Area/ST_Length, aligning docs with the spherical implementation (mean Earth radius R = 6 371 008 m) rather than WGS84/authalic wording.

Changes:

  • Reword ST_Area / ST_Length docs to label R = 6 371 008 m as the mean Earth radius (not authalic).
  • Correct ST_Area overview wording to reflect spherical (not WGS84 ellipsoidal) computation.
  • Align SedonaFlink geography overview and ST_Area page wording with the spherical mean-radius model.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
docs/api/sql/geography/Geography-Functions/ST_Length.md Updates ST_Length intro to “mean Earth radius”.
docs/api/sql/geography/Geography-Functions/ST_Area.md Updates ST_Area intro to “mean Earth radius”.
docs/api/sql/geography/Geography-Functions.md Fixes ST_Area summary row to describe spherical mean-radius computation (not WGS84).
docs/api/flink/Geography-Functions/ST_Area.md Updates Flink ST_Area intro to “mean Earth radius”.
docs/api/flink/Geography-Functions.md Updates Flink geography overview to “mean Earth radius”.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

| Function | Return type | Description | Since |
| :--- | :--- | :--- | :--- |
| [ST_Area](Geography-Functions/ST_Area.md) | Double | Return the geodesic area of a geography in square meters (WGS84 spheroid). | v1.9.1 |
| [ST_Area](Geography-Functions/ST_Area.md) | Double | Return the spherical area of a geography in square meters, computed on a sphere of mean Earth radius (~6,371,008 m), not the WGS84 ellipsoid. | v1.9.1 |

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reformatted to R = 6 371 008 m (inline code, space-separated) to match the ST_Area/ST_Length pages and the SedonaFlink geography docs. All six radius mentions across the geography docs now use the same style. Commit cf5385a.

@jiayuasu jiayuasu force-pushed the fix-geography-area-doc-spheroid branch from b236b2c to cf5385a Compare June 22, 2026 18:24
@jiayuasu jiayuasu added this to the sedona-1.9.1 milestone Jun 22, 2026
@jiayuasu jiayuasu merged commit 817793b into apache:master Jun 22, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants