Harmonise Cartesian_Datum & Cartesian_ReferenceFrame

Adds Cartesian_Datum.convertDatum(), deprecates Cartesian_Datum.toLatLon() datum
param.

Plus some general tidy-up.

Author: chrisveness

latlon-ellipsoidal-datum.js

@@ -184,7 +184,7 @@ class LatLonEllipsoidal_Datum extends LatLonEllipsoidal {
      * @param   {number|string|Object} lat|latlon - Geodetic Latitude (in degrees) or comma-separated lat/lon or lat/lon object.
      * @param   {number}               [lon] - Longitude in degrees.
      * @param   {number}               [height=0] - Height above ellipsoid in metres.
-     * @param   {LatLon.datums}        [datum=LatLon.datums.WGS84] - Datum this point is defined within.
+     * @param   {LatLon.datums}        [datum=WGS84] - Datum this point is defined within.
      * @returns {LatLon} Latitude/longitude point on ellipsoidal model earth using given datum.
      * @throws  {TypeError} Unrecognised datum.
      *
@@ -221,26 +221,9 @@ class LatLonEllipsoidal_Datum extends LatLonEllipsoidal {
     convertDatum(toDatum) {
         if (!toDatum || toDatum.ellipsoid==undefined) throw new TypeError(`unrecognised datum ‘${toDatum}’`);
 
-        let oldLatLon = this;
-        let transform = null;
-
-        if (oldLatLon.datum == datums.WGS84) {
-            // converting from WGS 84
-            transform = toDatum.transform;
-        }
-        if (toDatum == datums.WGS84) {
-            // converting to WGS 84; use inverse transform
-            transform = oldLatLon.datum.transform.map(p => -p);
-        }
-        if (transform == null) {
-            // neither this.datum nor toDatum are WGS84: convert this to WGS84 first
-            oldLatLon = this.convertDatum(datums.WGS84);
-            transform = toDatum.transform;
-        }
-
-        const oldCartesian = oldLatLon.toCartesian();                // convert geodetic to cartesian...
-        const newCartesian = oldCartesian.applyTransform(transform); // ...apply transform...
-        const newLatLon = newCartesian.toLatLon(toDatum);            // ...and convert cartesian to geodetic
+        const oldCartesian = this.toCartesian();                 // convert geodetic to cartesian
+        const newCartesian = oldCartesian.convertDatum(toDatum); // convert datum
+        const newLatLon = newCartesian.toLatLon();               // convert cartesian back to geodetic
 
         return newLatLon;
     }
@@ -255,7 +238,7 @@ class LatLonEllipsoidal_Datum extends LatLonEllipsoidal {
      */
     toCartesian() {
         const cartesian = super.toCartesian();
-        const cartesianDatum = new Cartesian_Datum(cartesian.x, cartesian.y, cartesian.z);
+        const cartesianDatum = new Cartesian_Datum(cartesian.x, cartesian.y, cartesian.z, this.datum);
         return cartesianDatum;
     }
 
@@ -266,31 +249,117 @@ class LatLonEllipsoidal_Datum extends LatLonEllipsoidal {
 
 
 /**
- * Converts geocentric ECEF (earth-centered earth-fixed) cartesian coordinates to latitude/longitude points,
- * applies Helmert transformations.
+ * Augments Cartesian with datum the cooordinate is based on, and methods to convert between datums
+ * (using Helmert 7-parameter transforms) and to convert cartesian to geodetic latitude/longitude
+ * point.
  *
  * @extends Cartesian
  */
 class Cartesian_Datum extends Cartesian {
 
+    /**
+     * Creates cartesian coordinate representing ECEF (earth-centric earth-fixed) point, on a given
+     * datum. The datum will identify the primary meridian (for the x-coordinate), and is also
+     * useful in transforming to/from geodetic (lat/lon) coordinates.
+     *
+     * @param  {number} x - X coordinate in metres (=> 0°N,0°E).
+     * @param  {number} y - Y coordinate in metres (=> 0°N,90°E).
+     * @param  {number} z - Z coordinate in metres (=> 90°N).
+     * @param  {LatLon.datums} [datum] - Datum this coordinate is defined within.
+     * @throws {TypeError} Unrecognised datum.
+     *
+     * @example
+     *   import { Cartesian } from '/js/geodesy/latlon-ellipsoidal-datum.js';
+     *   const coord = new Cartesian(3980581.210, -111.159, 4966824.522);
+     */
+    constructor(x, y, z, datum=undefined) {
+        if (datum && datum.ellipsoid==undefined) throw new TypeError(`unrecognised datum ‘${datum}’`);
+
+        super(x, y, z);
+
+        if (datum) this._datum = datum;
+    }
+
+
+    /**
+     * Datum this point is defined within.
+     */
+    get datum() {
+        return this._datum;
+    }
+    set datum(datum) {
+        if (!datum || datum.ellipsoid==undefined) throw new TypeError(`unrecognised datum ‘${datum}’`);
+        this._datum = datum;
+    }
+
+
     /**
      * Converts ‘this’ (geocentric) cartesian (x/y/z) coordinate to (geodetic) latitude/longitude
-     * point on specified datum.
+     * point (based on the same datum, or WGS84 if unset).
      *
-     * Shadow of Cartesian.toLatLon(), returning LatLon augmented with LatLonEllipsoidal_Datum methods
-     * convertDatum, toCartesian, etc.
+     * Shadow of Cartesian.toLatLon(), returning LatLon augmented with LatLonEllipsoidal_Datum
+     * methods convertDatum, toCartesian, etc.
      *
-     * @param   {LatLon.datums} [datum=LatLon.datums.WGS84] - Datum to use when converting point.
-     * @returns {LatLon} Latitude/longitude point defined by cartesian coordinates, in given datum.
+     * @returns {LatLon} Latitude/longitude point defined by cartesian coordinates.
+     * @throws  {TypeError} Unrecognised datum
      *
      * @example
-     *   const c = new Cartesian(4027893.924, 307041.993, 4919474.294)
-     *   const p = c.toLatLon().convertDatum(LatLon.datums.OSGB36); // 50.7971°N, 004.3612°E
+     *   const c = new Cartesian(4027893.924, 307041.993, 4919474.294);
+     *   const p = c.toLatLon(); // 50.7978°N, 004.3592°E
      */
-    toLatLon(datum=datums.WGS84) {
+    toLatLon(deprecatedDatum=undefined) {
+        if (deprecatedDatum) {
+            console.info('datum parameter to Cartesian_Datum.toLatLon is deprecated: set datum before calling toLatLon()');
+            this.datum = deprecatedDatum;
+        }
+        const datum = this.datum || datums.WGS84;
         if (!datum || datum.ellipsoid==undefined) throw new TypeError(`unrecognised datum ‘${datum}’`);
-        const latLon = super.toLatLon(datum.ellipsoid);
-        return new LatLonEllipsoidal_Datum(latLon.lat, latLon.lon, latLon.height, datum);
+
+        const latLon = super.toLatLon(datum.ellipsoid); // TODO: what if datum is not geocentric?
+        const point = new LatLonEllipsoidal_Datum(latLon.lat, latLon.lon, latLon.height, this.datum);
+        return point;
+    }
+
+
+    /**
+     * Converts ‘this’ cartesian coordinate to new datum using Helmert 7-parameter transformation.
+     *
+     * @param   {LatLon.datums} toDatum - Datum this coordinate is to be converted to.
+     * @returns {Cartesian} This point converted to new datum.
+     * @throws  {Error} Undefined datum.
+     *
+     * @example
+     *   const c = new Cartesian(3980574.247, -102.127, 4966830.065, LatLon.datums.OSGB36);
+     *   c.convertDatum(LatLon.datums.Irl1975); // [??,??,??]
+     */
+    convertDatum(toDatum) {
+        // TODO: what if datum is not geocentric?
+        if (!toDatum || toDatum.ellipsoid == undefined) throw new TypeError(`unrecognised datum ‘${toDatum}’`);
+        if (!this.datum) throw new TypeError('cartesian coordinate has no datum');
+
+        let oldCartesian = null;
+        let transform = null;
+
+        if (this.datum == undefined || this.datum == datums.WGS84) {
+            // converting from WGS 84
+            oldCartesian = this;
+            transform = toDatum.transform;
+        }
+        if (toDatum == datums.WGS84) {
+            // converting to WGS 84; use inverse transform
+            oldCartesian = this;
+            transform = this.datum.transform.map(p => -p);
+        }
+        if (transform == null) {
+            // neither this.datum nor toDatum are WGS84: convert this to WGS84 first
+            oldCartesian = this.convertDatum(datums.WGS84);
+            transform = toDatum.transform;
+        }
+
+        const newCartesian = oldCartesian.applyTransform(transform);
+        newCartesian.datum = toDatum;
+
+        return newCartesian;
     }
 
 

latlon-ellipsoidal-referenceframe.js

@@ -267,7 +267,8 @@ class LatLonEllipsoidal_ReferenceFrame extends LatLonEllipsoidal {
      */
     toCartesian() {
         const cartesian = super.toCartesian();
-        return new Cartesian_ReferenceFrame(cartesian.x, cartesian.y, cartesian.z, this.referenceFrame, this.epoch);
+        const cartesianReferenceFrame = new Cartesian_ReferenceFrame(cartesian.x, cartesian.y, cartesian.z, this.referenceFrame, this.epoch);
+        return cartesianReferenceFrame;
     }
 
 
@@ -305,16 +306,17 @@ class LatLonEllipsoidal_ReferenceFrame extends LatLonEllipsoidal {
 
 /**
  * Augments Cartesian with reference frame and observation epoch the cooordinate is based on, and
- * methods to convert between reference frames (using Helmert 14-parameter transforms), and to
- * convert to geodetic latitude/longitude points.
+ * methods to convert between reference frames (using Helmert 14-parameter transforms) and to
+ * convert cartesian to geodetic latitude/longitude point.
  *
  * @extends Cartesian
  */
 class Cartesian_ReferenceFrame extends Cartesian {
 
     /**
-     * Creates cartesian coordinate representing ECEF (earth-centric earth-fixed) point on a given
-     * reference frame.
+     * Creates cartesian coordinate representing ECEF (earth-centric earth-fixed) point, on a given
+     * reference frame. The reference frame will identify the primary meridian (for the x-coordinate),
+     * and is also useful in transforming to/from geodetic (lat/lon) coordinates.
      *
      * @param  {number} x - X coordinate in metres (=> 0°N,0°E).
      * @param  {number} y - Y coordinate in metres (=> 0°N,90°E).
@@ -324,7 +326,7 @@ class Cartesian_ReferenceFrame extends Cartesian {
      * @throws {TypeError} Unrecognised reference frame, Invalid epoch.
      *
      * @example
-     *   import { Cartesian } from '/js/geodesy/latlon-ellipsoidal.js';
+     *   import { Cartesian } from '/js/geodesy/latlon-ellipsoidal-referenceframe.js';
      *   const coord = new Cartesian(3980581.210, -111.159, 4966824.522);
      */
     constructor(x, y, z, referenceFrame=undefined, epoch=undefined) {
@@ -363,24 +365,23 @@ class Cartesian_ReferenceFrame extends Cartesian {
 
     /**
      * Converts ‘this’ (geocentric) cartesian (x/y/z) coordinate to (geodetic) latitude/longitude
-     * point.
+     * point (based on the same reference frame).
      *
-     * Shadow of Cartesian.toLatLon(), returning LatLon augmented with
-     * LatLonEllipsoidal_ReferenceFrame methods.
+     * Shadow of Cartesian.toLatLon(), returning LatLon augmented with LatLonEllipsoidal_ReferenceFrame
+     * methods convertReferenceFrame, toCartesian, etc.
      *
-     * @param   {LatLon.referenceFrames} [referenceFrame] - Reference frame to use when converting point.
      * @returns {LatLon} Latitude/longitude point defined by cartesian coordinates, in given reference frame.
      * @throws  {Error} No reference frame defined.
      *
      * @example
-     *   const p = new Cartesian(4027893.924, 307041.993, 4919474.294, LatLon.referenceFrames.ITRF2000).toLatLon();
+     *   const c = new Cartesian(4027893.924, 307041.993, 4919474.294, LatLon.referenceFrames.ITRF2000);
+     *   const p = c.toLatLon(); // 50.7978°N, 004.3592°E
      */
     toLatLon() {
         if (!this.referenceFrame) throw new Error('cartesian reference frame not defined');
 
         const latLon = super.toLatLon(this.referenceFrame.ellipsoid);
-        const point = new LatLonEllipsoidal_ReferenceFrame(latLon.lat, latLon.lon, latLon.height, this.referenceFrame);
-        if (this.epoch) point._epoch = this.epoch;
+        const point = new LatLonEllipsoidal_ReferenceFrame(latLon.lat, latLon.lon, latLon.height, this.referenceFrame, this.epoch);
         return point;
     }
 
@@ -390,7 +391,7 @@ class Cartesian_ReferenceFrame extends Cartesian {
      * transformation. The observation epoch is unchanged.
      *
      * Note that different conversions have different tolerences; refer to the literature if
-     * tolerances are singnificant.
+     * tolerances are significant.
      *
      * @param   {LatLon.referenceFrames} toReferenceFrame - Reference frame this coordinate is to be converted to.
      * @returns {Cartesian} This point converted to new reference frame.

latlon-ellipsoidal.js

@@ -29,6 +29,8 @@ import Vector3d from './vector3d.js';
 
 /*
  * Ellipsoid parameters; exposed through static getter below.
+ *
+ * The only ellipsoid defined is WGS84, for use in utm/mgrs, vincenty, nvector.
  */
 const ellipsoids = {
     WGS84: { a: 6378137, b: 6356752.314245, f: 1/298.257223563 },
@@ -37,6 +39,8 @@ const ellipsoids = {
 
 /*
  * Datums; exposed through static getter below.
+ *
+ * The only datum defined is WGS84, for use in utm/mgrs, vincenty, nvector.
  */
 const datums = {
     WGS84: { ellipsoid: ellipsoids.WGS84 },
@@ -332,8 +336,7 @@ class LatLonEllipsoidal {
 
 
 /**
- * Converts ECEF (earth-centered earth-fixed) geocentric cartesian coordinates to latitude/longitude
- * points, applies Helmert transformations.
+ * ECEF (earth-centered earth-fixed) geocentric cartesian coordinates.
  *
  * @extends Vector3d
  */
@@ -364,19 +367,16 @@ class Cartesian extends Vector3d {
      *
      * @param   {LatLon.ellipsoids} [ellipsoid=WGS84] - Ellipsoid to use when converting point.
      * @returns {LatLon} Latitude/longitude point defined by cartesian coordinates, on given ellipsoid.
-     * @throws  {TypeError} Invalid ellipsoid
+     * @throws  {TypeError} Invalid ellipsoid.
      *
      * @example
-     *   const p = new Cartesian(4027893.924, 307041.993, 4919474.294).toLatLon(); // 50.7978°N, 004.3592°E
-     *
-     * FORTHCOMING CHANGE NOTICE: Cartesian is not normally imported directly from latlon-ellipsoidal.js
-     * (rather from latlon-ellipsoidal-datum.js), but if it is, the toLatLon() method takes an
-     * ellipsoid as a parameter rather than a datum. This will be corrected in the next semver-major
-     * release.
+     *   const c = new Cartesian(4027893.924, 307041.993, 4919474.294);
+     *   const p = c.toLatLon(); // 50.7978°N, 004.3592°E
      */
-    toLatLon(ellipsoid=ellipsoids.WGS84) { // TODO: make parameter datum for consistency with Cartesian_Datum.toLatLon()
-        // note ellipsoid is available as a parameter for when toLatLon gets subclassed.
-        if (!ellipsoid || !ellipsoid.a) throw new TypeError('invalid ellipsoid');
+    toLatLon(ellipsoid=ellipsoids.WGS84) {
+        // note ellipsoid is available as a parameter for when toLatLon gets subclassed to
+        // Ellipsoidal_Datum / Ellipsoidal_Referenceframe.
+        if (!ellipsoid || !ellipsoid.a) throw new TypeError(`invalid ellipsoid ‘${ellipsoid}’`);
 
         const { x, y, z } = this;
         const { a, b, f } = ellipsoid;

test/latlon-ellipsoidal-datum-tests.js

@@ -67,7 +67,6 @@ describe('latlon-ellipsoidal-datum', function() {
         test('toCartesian', () => p.toCartesian().toString().should.equal('[3194419,3194419,4487348]'));
         const c = new Cartesian(3194419, 3194419, 4487348);
         test('toLatLon', () => c.toLatLon().toString().should.equal('45.0000°N, 045.0000°E'));
-        test('toLatLon fail', () => should.Throw(function() { c.toLatLon(null); }, TypeError, 'unrecognised datum ‘null’'));
         test('toLatLon fail', () => should.Throw(function() { c.toLatLon('xx'); }, TypeError, 'unrecognised datum ‘xx’'));
     });
 });

test/latlon-ellipsoidal-tests.js

@@ -126,9 +126,11 @@ describe('latlon-ellipsoidal', function() {
 
     describe('cartesian', function() {
         const p = new LatLon(45, 45);
-        test('toCartesian',   () => p.toCartesian().toString().should.equal('[3194419,3194419,4487348]'));
+        test('toCartesian',          () => p.toCartesian().toString().should.equal('[3194419,3194419,4487348]'));
         const c = new Cartesian(3194419, 3194419, 4487348);
-        test('toLatLon',      () => c.toLatLon().toString().should.equal('45.0000°N, 045.0000°E'));
-        test('toLatLon fail', () => should.Throw(function() { c.toLatLon(null); }, TypeError, 'invalid ellipsoid'));
+        test('toLatLon',             () => c.toLatLon().toString().should.equal('45.0000°N, 045.0000°E'));
+        test('toLatLon w/ ellipse',  () => c.toLatLon(LatLon.datums.WGS84.ellipsoid).toString().should.equal('45.0000°N, 045.0000°E'));
+        test('toLatLon fail (null)', () => should.Throw(function() { c.toLatLon(null); }, TypeError, 'invalid ellipsoid ‘null’'));
+        test('toLatLon fail (str)',  () => should.Throw(function() { c.toLatLon('WGS84'); }, TypeError, 'invalid ellipsoid ‘WGS84’'));
     });
 });