From a9dfb72cbebe8d423064c2bae9a5d2f446217fa3 Mon Sep 17 00:00:00 2001
From: Johannes Vollmer <32042925+johannesvollmer@users.noreply.github.com>
Date: Wed, 13 Aug 2025 10:34:43 +0200
Subject: [PATCH] Fixed documentation (it said radians, but code uses degrees)

---
 dev-docs/RFCs/math-monorepo-rfc.md                 |  4 ++--
 docs/modules/geospatial/README.md                  |  8 ++++----
 docs/modules/geospatial/api-reference/ellipsoid.md | 12 ++++++------
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/dev-docs/RFCs/math-monorepo-rfc.md b/dev-docs/RFCs/math-monorepo-rfc.md
index 9b5ae0b2..9905f832 100644
--- a/dev-docs/RFCs/math-monorepo-rfc.md
+++ b/dev-docs/RFCs/math-monorepo-rfc.md
@@ -30,7 +30,7 @@ Using with pure javascript `Array`
 
 ```js
 import {Ellipsoid} from '@math.gl/geospatial';
-const cartesian = Ellipsoid.WSG84.cartographicToCartesian([lng, lat, z]);
+const cartesian = Ellipsoid.WSG84.cartographicToCartesian([lngDegrees, latDegress, zMetresFromEllipsoid]);
 ```
 
 Using with math.gl `Vector3`:
@@ -38,7 +38,7 @@ Using with math.gl `Vector3`:
 ```js
 import {Ellipsoid} from '@math.gl/geospatial';
 import {Vector3} from '@math.gl/core';
-const cartesian = Ellipsoid.WSG84.cartographicToCartesian(new Vector3(lng, lat, z));
+const cartesian = Ellipsoid.WSG84.cartographicToCartesian(new Vector3(lngDegrees, latDegress, zMetresFromEllipsoid));
 ```
 
 ### Dependencies and Bundle Size
diff --git a/docs/modules/geospatial/README.md b/docs/modules/geospatial/README.md
index ebf80998..c3c5d3b4 100644
--- a/docs/modules/geospatial/README.md
+++ b/docs/modules/geospatial/README.md
@@ -22,16 +22,15 @@ Attribution: From <a href="https://en.wikipedia.org/wiki/World_Geodetic_System#/
 
 ## Usage Examples
 
-A major use of this library is to convert between "cartesian" (`x`, `y`, `z`) and "cartographic" (`longitude`, `latitude`, `height`) representations of WSG84 coordinates. The `Ellipsoid` class implements these calculations.
+A major use of this library is to convert between "cartesian" (`x`, `y`, `z`) and "cartographic" (`longitude degrees`, `latitude degrees`, `height in metres from ellipsoid`) representations of WSG84 coordinates. The `Ellipsoid` class implements these calculations.
 
 ## Usage
 
 Determine the Cartesian representation of a Cartographic position on a WGS84 ellipsoid.
 
 ```js
-import {toRadians} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
-const cartographicPosition = [toRadians(21), toRadians(78), 5000];
+const cartographicPosition = [21, 78, 5000]; // longitude degrees, latitude degrees, meters above ellipsoid
 const cartesianPosition = Ellipsoid.WGS84.cartographicToCartesian(cartographicPosition);
 ```
 
@@ -47,7 +46,8 @@ Get the transform from local east-north-up at cartographic (0.0, 0.0) to Earth's
 
 ```js
 import {Ellipsoid} from '@math.gl/geospatial';
-const transformMatrix = Ellipsoid.WGS84.eastNorthUpToFixedFrame([0, 0, 0]);
+const cartesianOrigin = [17832.12, 83234.52, 952313.73]
+const transformMatrix = Ellipsoid.WGS84.eastNorthUpToFixedFrame(cartesianOrigin);
 ```
 
 ## Framework Independence
diff --git a/docs/modules/geospatial/api-reference/ellipsoid.md b/docs/modules/geospatial/api-reference/ellipsoid.md
index 10f52913..2db3d792 100644
--- a/docs/modules/geospatial/api-reference/ellipsoid.md
+++ b/docs/modules/geospatial/api-reference/ellipsoid.md
@@ -15,9 +15,8 @@ Rather than constructing this object directly, one of the provided constants is
 Determine the Cartesian representation of a Cartographic position on a WGS84 ellipsoid.
 
 ```js
-import {toRadians} from '@math.gl/core';
 import {Ellipsoid} from '@math.gl/geospatial';
-const cartographicPosition = [toRadians(21), toRadians(78), 5000];
+const cartographicPosition = [21, 78, 5000]; // longitude degrees, latitude degrees, meters above ellipsoid
 const cartesianPosition = Ellipsoid.WGS84.cartographicToCartesian(cartographicPosition);
 ```
 
@@ -33,7 +32,8 @@ Get the transform from local east-north-up at cartographic (0.0, 0.0) to Earth's
 
 ```js
 import {Ellipsoid} from '@math.gl/geospatial';
-const transformMatrix = Ellipsoid.WGS84.eastNorthUpToFixedFrame([0, 0, 0]);
+const cartesianOrigin = [17832.12, 83234.52, 952313.73]
+const transformMatrix = Ellipsoid.WGS84.eastNorthUpToFixedFrame(cartesianOrigin);
 ```
 
 ## Static Fields
@@ -116,7 +116,7 @@ Returns
 
 Converts the provided cartographic to Cartesian representation.
 
-- `cartographic` The cartographic position.
+- `cartographic` The cartographic position (degrees).
 - `result` Optional object onto which to store the result.
 
 Returns
@@ -144,7 +144,7 @@ The local axes are defined as:
 - The `y` axis points in the local north direction.
 - The `z` axis points in the direction of the ellipsoid surface normal which passes through the position.
 
-- `origin` The center point of the local reference frame.
+- `origin` The cartesian coordinate of the center point of the local reference frame.
 - `ellipsoid`=`Ellipsoid.WGS84` The ellipsoid whose fixed frame is used in the transformation.
 - `result` Optional object onto which to store the result.
 
@@ -163,7 +163,7 @@ Computes a 4x4 transformation matrix from a reference frame centered at the prov
 - `firstAxis` name of the first axis of the local reference frame. Must be 'east', 'north', 'up', 'west', 'south' or 'down'.
 - `secondAxis` name of the second axis of the local reference frame.
 - `thirdAxis` name of the third axis of the local reference frame. Can be omitted as it is implied by the cross product of the first two axis.
-- `origin` The center point of the local reference frame.
+- `origin` The cartesian coordinate of the center point of the local reference frame.
 - `result` Optional object onto which to store the result.
 
 Returns