Merge pull request #232 from markuswntr/quaternion/argument

Allow direct access to `halfAngle` on quaternions

Author: stephentyrone

Sources/QuaternionModule/Polar.swift

@@ -49,7 +49,7 @@ extension Quaternion {
   /// - If a quaternion is not finite, its `.length` is `infinity`.
   ///
   /// See also `.magnitude`, `.lengthSquared`, `.polar` and
-  /// `init(length:,phase:,axis:)`.
+  /// `init(length:halfAngle:axis:)`.
   @_transparent
   public var length: RealType {
     let naive = lengthSquared
@@ -70,131 +70,130 @@ extension Quaternion {
   /// The squared length `(r*r + x*x + y*y + z*z)`.
   ///
   /// This value is highly prone to overflow or underflow.
-  /// 
+  ///
   /// For many cases, `.magnitude` can be used instead, which is similarly
   /// cheap to compute and always returns a representable value.
   ///
   /// This property is more efficient to compute than `length`.
   ///
   /// See also `.magnitude`, `.length`, `.polar` and
-  /// `init(length:,phase:,axis:)`.
+  /// `init(length:halfAngle:axis:)`.
   @_transparent
   public var lengthSquared: RealType {
     (components * components).sum()
   }
 
+  /// The half rotation angle in radians within *[0, π]* range.
+  ///
+  /// Edge cases:
+  /// - If the quaternion is zero or non-finite, halfAngle is `nan`.
+  @inlinable
+  public var halfAngle: RealType {
+    guard isFinite else { return .nan }
+    // A zero quaternion does not encode transformation properties.
+    // If imaginary is zero, real must be non-zero or nan is returned.
+    guard !isReal else { return isPure ? .nan : .zero }
+    // If lengthSquared computes without over/underflow, everything is fine
+    // and the result is correct. If not, we have to do the computation
+    // carefully and unscale the quaternion first.
+    let lenSq = imaginary.lengthSquared
+    guard lenSq.isNormal else { return divided(by: magnitude).halfAngle }
+    return .atan2(y: .sqrt(lenSq), x: real)
+  }
+
   /// The [polar decomposition][wiki].
   ///
-  /// Returns the length of this quaternion, phase in radians of range *[0, π]*
-  /// and the rotation axis as SIMD3 vector of unit length.
+  /// Returns the length of this quaternion, halfAngle in radians of range
+  /// *[0, π]* and the rotation axis as SIMD3 vector of unit length.
   ///
   /// Edge cases:
-  /// - If the quaternion is zero, length is `.zero` and angle and axis
+  /// - If the quaternion is zero, length is `.zero` and halfAngle and axis
   /// are `nan`.
-  /// - If the quaternion is non-finite, length is `.infinity` and angle and
+  /// - If the quaternion is non-finite, length is `.infinity` and halfAngle and
   /// axis are `nan`.
-  /// - For any length other than `.zero` or `.infinity`, if angle is zero, axis
-  /// is `nan`.
+  /// - For any length other than `.zero` or `.infinity`, if halfAngle is zero,
+  /// axis is `nan`.
   ///
   /// See also `.magnitude`, `.length`, `.lengthSquared` and
-  /// `init(length:,phase:,axis:)`.
+  /// `init(length:halfAngle:axis:)`.
   ///
   /// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
-  public var polar: (length: RealType, phase: RealType, axis: SIMD3<RealType>) {
+  public var polar: (
+    length: RealType,
+    halfAngle: RealType,
+    axis: SIMD3<RealType>
+  ) {
     (length, halfAngle, axis)
   }
 
+  /// Creates a new quaternion from given half rotation angle about given
+  /// rotation axis.
+  ///
+  /// The angle-axis values are transformed using the following equation:
+  ///
+  ///     Q = (cos(halfAngle), unitAxis * sin(halfAngle))
+  ///
+  /// - Parameters:
+  ///   - halfAngle: The half rotation angle
+  ///   - unitAxis: The rotation axis of unit length
+  @usableFromInline @inline(__always)
+  internal init(halfAngle: RealType, unitAxis: SIMD3<RealType>) {
+    self.init(real: .cos(halfAngle), imaginary: unitAxis * .sin(halfAngle))
+  }
+
   /// Creates a quaternion specified with [polar coordinates][wiki].
   ///
-  /// This initializer reads given `length`, `phase` and `axis` values and
+  /// This initializer reads given `length`, `halfAngle` and `axis` values and
   /// creates a quaternion of equal rotation properties and specified *length*
   /// using the following equation:
   ///
-  ///     Q = (cos(phase), axis * sin(phase)) * length
-  ///
-  /// - Note: `axis` must be of unit length, or an assertion failure occurs.
+  ///     Q = (cos(halfAngle), axis * sin(halfAngle)) * length
   ///
   /// Edge cases:
   /// - Negative lengths are interpreted as reflecting the point through the
   ///   origin, i.e.:
   ///   ```
-  ///   Quaternion(length: -r, phase: θ, axis: axis) == -Quaternion(length: r, phase: θ, axis: axis)
+  ///   Quaternion(length: -r, halfAngle: θ, axis: axis) == -Quaternion(length: r, halfAngle: θ, axis: axis)
   ///   ```
   /// - For any `θ` and any `axis`, even `.infinity` or `.nan`:
   ///   ```
-  ///   Quaternion(length: .zero, phase: θ, axis: axis) == .zero
+  ///   Quaternion(length: .zero, halfAngle: θ, axis: axis) == .zero
   ///   ```
   /// - For any `θ` and any `axis`, even `.infinity` or `.nan`:
   ///   ```
-  ///   Quaternion(length: .infinity, phase: θ, axis: axis) == .infinity
+  ///   Quaternion(length: .infinity, halfAngle: θ, axis: axis) == .infinity
   ///   ```
-  /// - Otherwise, `θ` must be finite, or a precondition failure occurs.
+  /// - Otherwise, `θ` must be finite, or a precondition failure occurs and
+  ///   `axis` must be of unit length, or an assertion failure occurs.
   ///
   /// See also `.magnitude`, `.length`, `.lengthSquared` and `.polar`.
   ///
   /// [wiki]: https://en.wikipedia.org/wiki/Polar_decomposition#Quaternion_polar_decomposition
   @inlinable
-  public init(length: RealType, phase: RealType, axis: SIMD3<RealType>) {
+  public init(length: RealType, halfAngle: RealType, axis: SIMD3<RealType>) {
     guard !length.isZero, length.isFinite else {
       self = Quaternion(length)
       return
     }
 
     // Length is finite and non-zero, therefore
-    // 1. `phase` must be finite or a precondition failure needs to occur; as
-    //    this is not representable.
+    // 1. `halfAngle` must be finite or a precondition failure needs to occur;
+    //    as this is not representable.
     // 2. `axis` must be of unit length or an assertion failure occurs; while
     //    "wrong" by definition, it is representable.
     precondition(
-      phase.isFinite,
-      "Either phase must be finite, or length must be zero or infinite."
+      halfAngle.isFinite,
+      "Either halfAngle must be finite, or length must be zero or infinite."
     )
     assert(
       // TODO: Replace with `approximateEquality()`
       abs(.sqrt(axis.lengthSquared)-1) < max(.sqrt(axis.lengthSquared), 1)*RealType.ulpOfOne.squareRoot(),
       "Given axis must be of unit length."
     )
 
-    self = Quaternion(halfAngle: phase, unitAxis: axis).multiplied(by: length)
-  }
-}
-
-// MARK: - Operations for working with polar form
-
-extension Quaternion {
-  /// The half rotation angle in radians within *[0, π]* range.
-  ///
-  /// Edge cases:
-  /// - If the quaternion is zero or non-finite, halfAngle is `nan`.
-  @usableFromInline @inline(__always)
-  internal var halfAngle: RealType {
-    guard isFinite else { return .nan }
-    guard imaginary != .zero else {
-      // A zero quaternion does not encode transformation properties.
-      // If imaginary is zero, real must be non-zero or nan is returned.
-      return real.isZero ? .nan : .zero
-    }
-
-    // If lengthSquared computes without over/underflow, everything is fine
-    // and the result is correct. If not, we have to do the computation
-    // carefully and unscale the quaternion first.
-    let lenSq = imaginary.lengthSquared
-    guard lenSq.isNormal else { return divided(by: magnitude).halfAngle }
-    return .atan2(y: .sqrt(lenSq), x: real)
-  }
-
-  /// Creates a new quaternion from given half rotation angle about given
-  /// rotation axis.
-  ///
-  /// The angle-axis values are transformed using the following equation:
-  ///
-  ///     Q = (cos(halfAngle), unitAxis * sin(halfAngle))
-  ///
-  /// - Parameters:
-  ///   - halfAngle: The half rotation angle
-  ///   - unitAxis: The rotation axis of unit length
-  @usableFromInline @inline(__always)
-  internal init(halfAngle: RealType, unitAxis: SIMD3<RealType>) {
-    self.init(real: .cos(halfAngle), imaginary: unitAxis * .sin(halfAngle))
+    self = Quaternion(
+      halfAngle: halfAngle,
+      unitAxis: axis
+    ).multiplied(by: length)
   }
 }

Tests/QuaternionTests/TransformationTests.swift

@@ -181,12 +181,12 @@ final class TransformationTests: XCTestCase {
   func testPolarDecomposition<T: Real & SIMDScalar>(_ type: T.Type) {
     let axis = SIMD3<T>(0,-1,0)
 
-    let q = Quaternion<T>(length: 5, phase: .pi, axis: axis)
+    let q = Quaternion<T>(length: 5, halfAngle: .pi, axis: axis)
     XCTAssertEqual(q.axis, axis)
     XCTAssertEqual(q.angle, .pi * 2)
 
     XCTAssertEqual(q.polar.length, 5)
-    XCTAssertEqual(q.polar.phase, .pi)
+    XCTAssertEqual(q.polar.halfAngle, .pi)
     XCTAssertEqual(q.polar.axis, axis)
   }
 
@@ -196,18 +196,18 @@ final class TransformationTests: XCTestCase {
   }
 
   func testPolarDecompositionEdgeCases<T: Real & SIMDScalar>(_ type: T.Type) {
-    XCTAssertEqual(Quaternion<T>(length: .zero, phase: .zero    , axis:  .zero    ), .zero)
-    XCTAssertEqual(Quaternion<T>(length: .zero, phase: .infinity, axis:  .infinity), .zero)
-    XCTAssertEqual(Quaternion<T>(length: .zero, phase:-.infinity, axis: -.infinity), .zero)
-    XCTAssertEqual(Quaternion<T>(length: .zero, phase: .nan     , axis:  .nan     ), .zero)
-    XCTAssertEqual(Quaternion<T>(length: .infinity, phase: .zero    , axis:  .zero    ), .infinity)
-    XCTAssertEqual(Quaternion<T>(length: .infinity, phase: .infinity, axis:  .infinity), .infinity)
-    XCTAssertEqual(Quaternion<T>(length: .infinity, phase:-.infinity, axis: -.infinity), .infinity)
-    XCTAssertEqual(Quaternion<T>(length: .infinity, phase: .nan     , axis:  .infinity), .infinity)
-    XCTAssertEqual(Quaternion<T>(length:-.infinity, phase: .zero    , axis:  .zero    ), .infinity)
-    XCTAssertEqual(Quaternion<T>(length:-.infinity, phase: .infinity, axis:  .infinity), .infinity)
-    XCTAssertEqual(Quaternion<T>(length:-.infinity, phase:-.infinity, axis: -.infinity), .infinity)
-    XCTAssertEqual(Quaternion<T>(length:-.infinity, phase: .nan     , axis:  .infinity), .infinity)
+    XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle: .zero,     axis: .zero),     .zero)
+    XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle: .infinity, axis: .infinity), .zero)
+    XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle:-.infinity, axis:-.infinity), .zero)
+    XCTAssertEqual(Quaternion<T>(length: .zero, halfAngle: .nan,      axis: .nan),      .zero)
+    XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle: .zero,     axis: .zero),     .infinity)
+    XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle: .infinity, axis: .infinity), .infinity)
+    XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle:-.infinity, axis:-.infinity), .infinity)
+    XCTAssertEqual(Quaternion<T>(length: .infinity, halfAngle: .nan,      axis: .infinity), .infinity)
+    XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle: .zero,     axis: .zero),     .infinity)
+    XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle: .infinity, axis: .infinity), .infinity)
+    XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle:-.infinity, axis:-.infinity), .infinity)
+    XCTAssertEqual(Quaternion<T>(length:-.infinity, halfAngle: .nan,      axis: .infinity), .infinity)
   }
 
   func testPolarDecompositionEdgeCases() {