Add EllipsoidRhumb class similar to EllipsoidGeodesic

Source/Core/EllipsoidRhumbLine.js

@@ -98,17 +98,13 @@ define([
         return Math.log(Math.tan(0.5 * (CesiumMath.PI_OVER_TWO + latitude))) - (ellipticity / 2.0 * Math.log((1 + eSinL) / (1 - eSinL)));
     }
 
-    function calculateHeading(ellipsoidRhumbLine, major, minor, firstLongitude, firstLatitude, secondLongitude, secondLatitude) {
+    function calculateHeading(ellipsoidRhumbLine, firstLongitude, firstLatitude, secondLongitude, secondLatitude) {
         var sigma1 = calculateSigma(ellipsoidRhumbLine._ellipticity, firstLatitude);
         var sigma2 = calculateSigma(ellipsoidRhumbLine._ellipticity, secondLatitude);
         return Math.atan2(CesiumMath.negativePiToPi(secondLongitude - firstLongitude), sigma2 - sigma1);
     }
 
     function calculateArcLength(ellipsoidRhumbLine, major, minor, firstLongitude, firstLatitude, secondLongitude, secondLatitude) {
-        //>>includeStart('debug', pragmas.debug);
-        Check.defined('heading', ellipsoidRhumbLine._heading);
-        //>>includeEnd('debug');
-
         var heading = ellipsoidRhumbLine._heading;
         var deltaLongitude = secondLongitude - firstLongitude;
 
@@ -135,7 +131,7 @@ define([
     var scratchCart1 = new Cartesian3();
     var scratchCart2 = new Cartesian3();
 
-    function initiailize(ellipsoidRhumbLine, start, end, ellipsoid) {
+    function initialize(ellipsoidRhumbLine, start, end, ellipsoid) {
         var major = ellipsoid.maximumRadius;
         var minor = ellipsoid.minimumRadius;
         var majorSquared = major * major;
@@ -161,10 +157,9 @@ define([
         Check.typeOf.number.greaterThanOrEquals('value', Math.abs(Math.abs(Cartesian3.angleBetween(firstCartesian, lastCartesian)) - Math.PI), 0.0125);
         //>>includeEnd('debug');
 
-        initiailize(ellipsoidRhumbLine, start, end, ellipsoid);
+        initialize(ellipsoidRhumbLine, start, end, ellipsoid);
 
-        ellipsoidRhumbLine._heading = calculateHeading(ellipsoidRhumbLine, ellipsoid.maximumRadius, ellipsoid.minimumRadius,
-                                                       start.longitude, start.latitude, end.longitude, end.latitude);
+        ellipsoidRhumbLine._heading = calculateHeading(ellipsoidRhumbLine, start.longitude, start.latitude, end.longitude, end.latitude);
         ellipsoidRhumbLine._distance = calculateArcLength(ellipsoidRhumbLine, ellipsoid.maximumRadius, ellipsoid.minimumRadius,
                                                           start.longitude, start.latitude, end.longitude, end.latitude);
     }
@@ -271,7 +266,7 @@ define([
      * @param {Cartographic} start The initial planetodetic point on the path.
      * @param {Cartographic} end The final planetodetic point on the path.
      * @param {Ellipsoid} [ellipsoid=Ellipsoid.WGS84] The ellipsoid on which the rhumb line lies.
-     * @param {EllipsoidRhumbLine} [result] The object in whice to store the result.
+     * @param {EllipsoidRhumbLine} [result] The object in which to store the result.
      * @returns {EllipsoidRhumbLine} The EllipsoidRhumbLine object.
      */
     EllipsoidRhumbLine.fromStartAndEnd = function(start, end, ellipsoid, result) {
@@ -305,27 +300,21 @@ define([
         Check.defined('start', start);
         Check.defined('heading', heading);
         Check.defined('distance', distance);
+        Check.typeOf.number.greaterThan('distance', distance, 0.0);
         //>>includeEnd('debug');
 
         var e = defaultValue(ellipsoid, Ellipsoid.WGS84);
 
-        if (defined(result)) {
-            result._ellipsoid = e;
-            initiailize(result, start, undefined, e);
-            result._heading = CesiumMath.negativePiToPi(heading);
-            result._distance = distance;
-
-            result._end = result.interpolateUsingSurfaceDistance(distance, new Cartographic());
-            return result;
+        if (!defined(result)) {
+            result = new EllipsoidRhumbLine(undefined, undefined, e);
         }
 
-        var rhumbLine = new EllipsoidRhumbLine(undefined, undefined, e);
-        initiailize(rhumbLine, start, undefined, e);
-        rhumbLine._heading = CesiumMath.negativePiToPi(heading);
-        rhumbLine._distance = distance;
-        rhumbLine._end = rhumbLine.interpolateUsingSurfaceDistance(distance, new Cartographic());
+        initialize(result, start, undefined, e);
+        result._heading = CesiumMath.negativePiToPi(heading);
+        result._distance = distance;
 
-        return rhumbLine;
+        result._end = result.interpolateUsingSurfaceDistance(distance, new Cartographic());
+        return result;
     };
 
     /**
@@ -347,29 +336,26 @@ define([
      * Provides the location of a point at the indicated portion along the rhumb line.
      *
      * @param {Number} fraction The portion of the distance between the initial and final points.
-     * @param {Cartographic} result The object in which to store the result.
+     * @param {Cartographic} [result] The object in which to store the result.
      * @returns {Cartographic} The location of the point along the rhumb line.
      */
     EllipsoidRhumbLine.prototype.interpolateUsingFraction = function(fraction, result) {
-        //>>includeStart('debug', pragmas.debug);
-        Check.typeOf.number('distance', this._distance);
-        //>>includeEnd('debug');
-
         return this.interpolateUsingSurfaceDistance(fraction * this._distance, result);
     };
 
     /**
      * Provides the location of a point at the indicated distance along the rhumb line.
      *
      * @param {Number} distance The distance from the inital point to the point of interest along the rhumbLine.
-     * @param {Cartographic} result The object in which to store the result.
+     * @param {Cartographic} [result] The object in which to store the result.
      * @returns {Cartographic} The location of the point along the rhumb line.
      *
      * @exception {DeveloperError} start and end must be set before calling function interpolateUsingSurfaceDistance
      */
     EllipsoidRhumbLine.prototype.interpolateUsingSurfaceDistance = function(distance, result) {
         //>>includeStart('debug', pragmas.debug);
-        Check.defined('distance', this._distance);
+        Check.defined('distance', distance);
+        Check.typeOf.number.greaterThan('this._distance', this._distance, CesiumMath.EPSILON12);
         //>>includeEnd('debug');
 
         var ellipsoid = this._ellipsoid;
@@ -427,5 +413,111 @@ define([
         return new Cartographic(longitude, latitude, 0);
     };
 
+    /**
+     * Provides the location of a point at the indicated longitude along the rhumb line.
+     *
+     * @param {Number} intersectionLongitude The longitude, in radians, at which to find the intersection point from the starting point using the heading.
+     * @param {Cartographic} [result] The object in which to store the result.
+     * @returns {Cartographic} The location of the intersection point along the rhumb line.
+     *
+     * @exception {DeveloperError} start and end must be set before calling function findIntersectionWithLongitude.
+     */
+    EllipsoidRhumbLine.prototype.findIntersectionWithLongitude = function(intersectionLongitude, result) {
+        //>>includeStart('debug', pragmas.debug);
+        Check.defined('intersectionLongitude', intersectionLongitude);
+        Check.defined('distance', this._distance);
+        //>>includeEnd('debug');
+
+        var ellipticity = this._ellipticity;
+        var heading = this._heading;
+        var absHeading = Math.abs(heading);
+        var start = this._start;
+
+        intersectionLongitude = CesiumMath.negativePiToPi(intersectionLongitude);
+
+        if (!defined(result)) {
+            result = new Cartographic();
+        }
+
+        // If heading is -PI/2 or PI/2, this is an E-W rhumb line
+        // If heading is 0 or PI, this is an N-S rhumb line
+        if (Math.abs(CesiumMath.PI_OVER_TWO - absHeading) <= CesiumMath.EPSILON8) {
+            result.longitude = intersectionLongitude;
+            result.latitude = start.latitude;
+            result.height = 0;
+            return result;
+        } else if (CesiumMath.equalsEpsilon(Math.abs(CesiumMath.PI_OVER_TWO - absHeading), CesiumMath.PI_OVER_TWO, CesiumMath.EPSILON8)) {
+            if (CesiumMath.equalsEpsilon(intersectionLongitude, start.longitude, CesiumMath.EPSILON12)) {
+                return undefined;
+            }
+
+            result.longitude = intersectionLongitude;
+            result.latitude = CesiumMath.PI_OVER_TWO * Math.sign(heading);
+            result.height = 0;
+            return result;
+        }
+
+        // Use iterative solver from Equation 9 from http://edwilliams.org/ellipsoid/ellipsoid.pdf
+        var phi1 = start.latitude;
+        var eSinPhi1 = ellipticity * Math.sin(phi1);
+        var leftComponent = Math.tan(0.5 * (CesiumMath.PI_OVER_TWO + phi1)) * Math.exp((intersectionLongitude - start.longitude) / Math.tan(heading));
+        var denominator = (1 + eSinPhi1) / (1 - eSinPhi1);
+
+        var newPhi = start.latitude;
+        var phi;
+        do {
+            phi = newPhi;
+            var eSinPhi = ellipticity * Math.sin(phi);
+            var numerator = (1 + eSinPhi) / (1 - eSinPhi);
+            newPhi = 2 * Math.atan(leftComponent * Math.pow(numerator / denominator, ellipticity / 2)) - CesiumMath.PI_OVER_TWO;
+        } while (!CesiumMath.equalsEpsilon(newPhi, phi, CesiumMath.EPSILON12));
+
+        result.longitude = intersectionLongitude;
+        result.latitude = phi;
+        result.height = 0;
+        return result;
+    };
+
+    /**
+     * Provides the location of a point at the indicated latitude along the rhumb line.
+     *
+     * @param {Number} intersectionLatitude The latitude, in radians, at which to find the intersection point from the starting point using the heading.
+     * @param {Cartographic} [result] The object in which to store the result.
+     * @returns {Cartographic} The location of the intersection point along the rhumb line, undefined if there is no intersection, infinite intersections or if intersection point is not between start and end.
+     *
+     * @exception {DeveloperError} start and end must be set before calling function findIntersectionWithLongitude.
+     */
+    EllipsoidRhumbLine.prototype.findIntersectionWithLatitude = function(intersectionLatitude, result) {
+        //>>includeStart('debug', pragmas.debug);
+        Check.defined('intersectionLatitude', intersectionLatitude);
+        Check.defined('distance', this._distance);
+        //>>includeEnd('debug');
+
+        var ellipticity = this._ellipticity;
+        var heading = this._heading;
+        var start = this._start;
+
+        // If start and end have same latitude, return undefined since it's either no intersection or infinite intersections
+        if (CesiumMath.equalsEpsilon(Math.abs(heading), CesiumMath.PI_OVER_TWO, CesiumMath.EPSILON8)) {
+            return;
+        }
+
+        // Can be solved using the same equations from interpolateUsingSurfaceDistance
+        var sigma1 = calculateSigma(ellipticity, start.latitude);
+        var sigma2 = calculateSigma(ellipticity, intersectionLatitude);
+        var deltaLongitude = Math.tan(heading) * (sigma2 - sigma1);
+        var longitude = CesiumMath.negativePiToPi(start.longitude + deltaLongitude);
+
+        if (defined(result)) {
+            result.longitude = longitude;
+            result.latitude = intersectionLatitude;
+            result.height = 0;
+
+            return result;
+        }
+
+        return new Cartographic(longitude, intersectionLatitude, 0);
+    };
+
     return EllipsoidRhumbLine;
 });