Merge pull request #19 from dastrobu/readme-updates-for-release

add example to README on azimuths computation

Author: dastrobu

README.md

@@ -19,7 +19,11 @@ Here is an example to compute the distance between two points (the poles in this
     import vincenty
     let d = try distance((lat: Double.pi / 2,lon: 0), (lat: -Double.pi / 2, lon: 0))
 
-and that's it. 
+To compute azimuths (also known as initial and final bearings) 
+
+    let (d, (a, b)) = try solveInverse((lat: Double.pi / 2,lon: 0), (lat: -Double.pi / 2, lon: 0))
+
+where `(a, b)` are the azimuths.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -47,7 +51,7 @@ There are no dependencies on macOS.
 ```swift
 let package = Package(
     dependencies: [
-        .package(url: "https://github.com/dastrobu/vincenty.git", from: "1.0.4"),
+        .package(url: "https://github.com/dastrobu/vincenty.git", from: "1.1.0"),
     ]
 )
 ```

Sources/vincenty/vincenty.swift

@@ -62,12 +62,12 @@ public func distance(_ x: (lat: Double, lon: Double),
 /// - Throws:
 ///   - `VincentyError.notConverged` if the distance computation does not converge within `maxIter` iterations.
 public func solveInverse(_ x: (lat: Double, lon: Double),
-                     _ y: (lat: Double, lon: Double),
-                     tol: Double = 1e-12,
-                     maxIter: UInt = 200,
-                     ellipsoid: (a: Double, f: Double) = wgs84
-) throws -> (distance:Double,azimuths:(Double,Double)) {
-    
+                         _ y: (lat: Double, lon: Double),
+                         tol: Double = 1e-12,
+                         maxIter: UInt = 200,
+                         ellipsoid: (a: Double, f: Double) = wgs84
+) throws -> (distance: Double, azimuths: (Double, Double)) {
+
     assert(tol > 0, "tol '\(tol)' ≤ 0")
 
     // validate lat and lon values
@@ -151,43 +151,42 @@ public func solveInverse(_ x: (lat: Double, lon: Double),
         - 1.0 / 6.0 * b * cos_2sigma
         * (-3 + 4 * sin_sigma * sin_sigma)
         * (-3 + 4 * cos_2sigma * cos_2sigma))))
-    
+
     let distance = B * a * (sigma - delta_sigma)
-    
+
     //Azimuth calculations:
     let sinSq_sigma = q * q + p * p
     // note special handling of exactly antipodal points where sin²σ = 0 (due to discontinuity
     // atan2(0, 0) = 0 but atan2(ε, 0) = π/2 / 90°) - in which case bearing is always meridional,
     // due north (or due south!)
     // α = azimuths of the geodesic; α2 the direction P₁ P₂ produced
-    let a1 = abs(sinSq_sigma) < Double.leastNonzeroMagnitude ? 0 : atan2(cos_u_y*sin(lambda),  cos_u_x*sin_u_y-sin_u_x*cos_u_y*cos(lambda))
-    let a2 = abs(sinSq_sigma) < Double.leastNonzeroMagnitude ? Double.pi : atan2(cos_u_x*sin(lambda), -sin_u_x*cos_u_y+cos_u_x*sin_u_y*cos(lambda))
-    
+    let a1 = abs(sinSq_sigma) < Double.leastNonzeroMagnitude ? 0 : atan2(cos_u_y * sin(lambda), cos_u_x * sin_u_y - sin_u_x * cos_u_y * cos(lambda))
+    let a2 = abs(sinSq_sigma) < Double.leastNonzeroMagnitude ? Double.pi : atan2(cos_u_x * sin(lambda), -sin_u_x * cos_u_y + cos_u_x * sin_u_y * cos(lambda))
+
     let initialTrueTrack = abs(distance) < Double.leastNonzeroMagnitude ? Double.nan : wrap2pi(a1)
     let finalTrueTrack = abs(distance) < Double.leastNonzeroMagnitude ? Double.nan : wrap2pi(a2)
-    
+
     return (distance: distance, azimuths: (initialTrueTrack, finalTrueTrack))
-    
+
 }
 
 /* Source: https://www.movable-type.co.uk/scripts/geodesy/docs/dms.js.html */
 
-private func wrap2pi(_ radians:Double) -> Double
-{
+private func wrap2pi(_ radians: Double) -> Double {
     // avoid rounding due to arithmetic ops if within range
-    guard radians < 0 || radians >= 2*Double.pi  else {
+    guard radians < 0 || radians >= 2 * Double.pi else {
         return radians
     }
-    
+
     // bearing wrapping requires a sawtooth wave function with a vertical offset equal to the
     // amplitude and a corresponding phase shift; this changes the general sawtooth wave function from
     //     f(x) = (2ax/p - p/2) % p - a
     // to
     //     f(x) = (2ax/p) % p
     // where a = amplitude, p = period, % = modulo; however, Swift '%' is a remainder operator
     // not a modulo operator - for modulo, replace 'x%n' with '((x%n)+n)%n'
-    let x = radians, a = Double.pi, p = 2*Double.pi
-    
-    return ((2*a*x/p).truncatingRemainder(dividingBy: p)+p).truncatingRemainder(dividingBy: p)
+    let x = radians, a = Double.pi, p = 2 * Double.pi
+
+    return ((2 * a * x / p).truncatingRemainder(dividingBy: p) + p).truncatingRemainder(dividingBy: p)
 }
 

Tests/vincentyTests/vincentyTests.swift

@@ -13,10 +13,12 @@ private let pi: Double = Double.pi
 private func rad<T: BinaryFloatingPoint>(fromDegree d: T) -> T {
     return d * T.pi / 180
 }
+
 /// - Returns: radians converted to degrees
 private func deg<T: BinaryFloatingPoint>(fromRadian r: T) -> T {
     return r * 180 / T.pi
 }
+
 /// - Returns: meters converted to nautical miles
 private func nm<T: BinaryFloatingPoint>(fromMeters m: T) -> T {
     return m / 1852.0
@@ -39,7 +41,17 @@ private extension BinaryFloatingPoint {
 }
 
 final class VincentyTests: XCTestCase {
-    
+
+    /// example code as shown in the Readme.md
+    func testRreadmeExamples() {
+        do {
+            let d = try! vincenty.distance((lat: Double.pi / 2, lon: 0), (lat: -Double.pi / 2, lon: 0))
+        }
+        do {
+            let (d, (a, b)) = try! solveInverse((lat: Double.pi / 2, lon: 0), (lat: -Double.pi / 2, lon: 0))
+        }
+
+    }
 
     func testShortcutForEqualPoints() {
         // make sure, points are equal and not identical, to check if the shortcut works correctly
@@ -98,7 +110,7 @@ final class VincentyTests: XCTestCase {
         x = (lat: 0.asRad, lon: -0.5.asRad)
         y = (lat: 0.asRad, lon: 0.5.asRad)
         XCTAssertEqual(try! vincenty.solveInverse(x, y).distance, 111319.491, accuracy: delta)
-        
+
         //Test Cardinals
         x = (lat: 0.0, lon: 0.0)
         y = (lat: pi/2,lon: 0.0) //north pole
@@ -110,23 +122,23 @@ final class VincentyTests: XCTestCase {
         (_, azimuths: (initialTrueTrack, finalTrueTrack)) = try! vincenty.solveInverse(x, y)
         XCTAssertEqual(initialTrueTrack, Double.pi/2, accuracy: delta)
         XCTAssertEqual(finalTrueTrack, Double.pi/2, accuracy: delta)
-           
+
         y = (lat: -pi/2,lon: 0.0) //south pole
         (_, azimuths: (initialTrueTrack, finalTrueTrack)) = try! vincenty.solveInverse(x, y)
         XCTAssertEqual(initialTrueTrack, Double.pi, accuracy: delta)
         XCTAssertEqual(finalTrueTrack, Double.pi, accuracy: delta)
-           
+
         y = (lat: 0.0,lon: -pi/2) //west
         (_, azimuths: (initialTrueTrack, finalTrueTrack)) = try! vincenty.solveInverse(x, y)
         XCTAssertEqual(initialTrueTrack, 3*Double.pi/2, accuracy: delta)
         XCTAssertEqual(finalTrueTrack, 3*Double.pi/2, accuracy: delta)
-        
+
     }
-    
+
     /// Test against A330 FMS
     let fmsAcc = 0.49 //within half nm or degree
     func testNavigationAccurracy() {
-        
+
         var x: (lat: Double, lon: Double), y: (lat: Double, lon: Double)
 
         //Urabi to Bumat
@@ -135,8 +147,8 @@ final class VincentyTests: XCTestCase {
         var (distance, azimuths: (initialTrueTrack, _)) = try! vincenty.solveInverse(x, y)
         XCTAssertEqual(distance.inNm, 197, accuracy: fmsAcc)
         XCTAssertEqual(initialTrueTrack.asDegrees, 058, accuracy: fmsAcc)
-        
-       
+
+
         //Dacey is N5933.6 / W12604.5
         x = (lat: (59+33.6/60).asRad, lon: -(126+04.5/60).asRad)
         //MCT is N5321.4 / W00215.7
@@ -149,9 +161,9 @@ final class VincentyTests: XCTestCase {
         print("vincenty: \(distance), geodesic: \(gDist), delta: \(fabs(distance - gDist))")
         XCTAssertEqual(distance, gDist, accuracy: 1e-3)
         XCTAssertEqual(initialTrueTrack.asDegrees, 036, accuracy: fmsAcc)
-        
+
     }
-    
+
 
     /// use geodesic as reference and test vincenty distance.
     func testAgainstGeodesic() {