Merge branch 'v0.2.0'

Author: sdpopov-keyvariable

Package.resolved

@@ -19,16 +19,17 @@
 
 import PackageDescription
 
+
 let targets: [Target] = [
     .target(
         name: "kvGeometry",
-        dependencies: [ .product(name: "kvKit", package: "kvKit-Swift") ]
+        dependencies: [ .product(name: "kvKit", package: "kvKit.swift") ]
     ),
     .target(
         name: "kvCSG",
         dependencies: [ "kvGeometry" ]
     ),
-    .testTarget(name: "kvGeometryTests", dependencies: [ "kvGeometry", .product(name: "kvTestKit", package: "kvKit-Swift") ]),
+    .testTarget(name: "kvGeometryTests", dependencies: [ "kvGeometry", .product(name: "kvTestKit", package: "kvKit.swift") ]),
 ]
 
 let package = Package(
@@ -43,7 +44,7 @@ let package = Package(
     ],
 
     dependencies: [
-        .package(url: "https://github.com/keyvariable/kvKit-Swift.git", from: "3.1.0"),
+        .package(url: "https://github.com/keyvariable/kvKit.swift.git", from: "4.0.0"),
     ],
 
     targets: targets

Package.swift

@@ -1,4 +1,4 @@
-# kvGeometry
+# kvGeometry.swift
 
 ![Swift 5.2](https://img.shields.io/badge/swift-5.2-green.svg)
 ![Linux](https://img.shields.io/badge/os-linux-green.svg)
@@ -25,7 +25,7 @@ This package is completely crossplatform.
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/keyvariable/kvGeometry.swift.git", from: "0.1.1"),
+    .package(url: "https://github.com/keyvariable/kvGeometry.swift.git", from: "0.2.0"),
 ]
 ```
 

README.md

@@ -294,7 +294,7 @@ public struct KvAABB3<Math : KvMathScope> {
     /// - Returns: An AABB produced applying scale to the receiver.
     ///
     /// - Note: It's faster then apply an arbitrary transformation.
-    @inlinable public func scaled(by scale: Vector) -> Self { Self(over: min * scale, max * scale) }
+    @inlinable public func scaled(by scale: Vector) -> Self { Self(over: (min * scale) as Vector, (max * scale) as Vector) }
 
 
     /// Changes the receiver to enclose box produced as result of transformation of the receiver.

Sources/kvGeometry/KvAABB3.swift

@@ -81,7 +81,7 @@ public struct KvAffineTransform3<Math : KvMathScope> {
     /// Initializes product of rotation and scale transformations.
     @inlinable
     public init(quaternion: Math.Quaternion, scale: Vector) {
-        let scale⁻¹ = 1 / scale
+        let scale⁻¹ = (1.0 as Scalar) / scale
 
         var m = Matrix(quaternion)
         var m⁻¹ = m.transpose
@@ -104,7 +104,7 @@ public struct KvAffineTransform3<Math : KvMathScope> {
     /// Initializes a scale transformation.
     @inlinable
     public init(scale: Vector) {
-        let scale⁻¹ = 1 / scale
+        let scale⁻¹ = (1.0 as Scalar) / scale
 
         self.init(Matrix(diagonal: scale),
                   Matrix(diagonal: scale⁻¹),
@@ -123,10 +123,11 @@ public struct KvAffineTransform3<Math : KvMathScope> {
 
     /// - Returns: Scale component of given tranform matrix.
     ///
+    /// - Warning: Assuming the receiver has no shear component. Consider ``decompose(_:)`` method to extract scale from transformations having non-trivial shear component.
     /// - Note: If determinant of the matrix is negative then X scale element is negative and other elements are non-negative.
     @inlinable
     public static func scale(from m: Matrix) -> Vector {
-        Vector(x: Math.length(m[0]) * (KvIsNotNegative(m.determinant) ? 1 : -1),
+        Vector(x: Math.length(m[0]) * (KvIsNotNegative(m.determinant) ? (1.0 as Scalar) : (-1.0 as Scalar)),
                y: Math.length(m[1]),
                z: Math.length(m[2]))
     }
@@ -177,6 +178,54 @@ public struct KvAffineTransform3<Math : KvMathScope> {
 
 
 
+    // MARK: Decomposition
+
+    /// - Returns: Rotation, shear and scale components of the receiver.
+    ///
+    /// See: ``decompose()``.
+    public static func decompose(_ matrix: Matrix) -> (rotation: Matrix, shear: (xy: Scalar, xz: Scalar, yz: Scalar), scale: Vector) {
+        var (m0, m1, m2) = matrix.columns
+
+        let sx = Math.length(m0)
+        m0 /= sx
+
+        var sxy = Math.dot(m0, m1)
+        m1 -= sxy * m0
+
+        let sy = Math.length(m1)
+        do {
+            let sy⁻¹ = (1.0 as Scalar) / sy
+            m1 *= sy⁻¹
+            sxy *= sy⁻¹
+        }
+
+        var sxz = Math.dot(m0, m2)
+        var syz = Math.dot(m1, m2)
+        m2 -= sxz * m0
+        m2 -= syz * m1
+
+        let sz = Math.length(m2)
+        do {
+            let sz⁻¹ = (1.0 as Scalar) / sz
+            m2 *= sz⁻¹
+            sxz *= sz⁻¹
+            syz *= sz⁻¹
+        }
+
+        return (rotation: .init(m0, m1, m2), shear: (xy: sxy, xz: sxz, yz: syz), scale: .init(sx, sy, sz))
+    }
+
+
+    /// - Returns: Rotation, shear and scale components of the receiver.
+    ///
+    /// See: ``decompose(_:)``.
+    @inlinable
+    public func decompose() -> (rotation: Matrix, shear: (xy: Scalar, xz: Scalar, yz: Scalar), scale: Vector) {
+        Self.decompose(matrix)
+    }
+
+
+
     // MARK: Operations
 
     /// Transformed X basis vector.
@@ -203,6 +252,7 @@ public struct KvAffineTransform3<Math : KvMathScope> {
 
     /// Scale component of the receiver.
     ///
+    /// - Warning: Assuming the receiver has no shear component. Consider ``decompose()`` method to extract scale from transformations having non-trivial shear component.
     /// - Note: If determinant of the matrix is negative then X scale element is negative and other elements are non-negative.
     @inlinable public var scale: Vector { KvAffineTransform3.scale(from: matrix) }
 

Sources/kvGeometry/KvAffineTransform3.swift

@@ -16,7 +16,7 @@
 //===----------------------------------------------------------------------===//
 //
 //  KvLine2.swift
-//  kvKit
+//  kvGeometry
 //
 //  Created by Svyatoslav Popov on 21.09.2022.
 //
@@ -157,15 +157,15 @@ public struct KvLine2<Math : KvMathScope> {
     public func y(x: Scalar) -> Scalar? {
         guard KvIsNonzero(normal.y) else { return nil }
 
-        return -(c + normal.x * x) as Scalar / normal.y
+        return (-(c + normal.x * x)) as Scalar / normal.y
     }
 
     /// - Returns: X coodinate where horizontal line at *y* intersects the receiver.
     @inlinable
     public func x(y: Scalar) -> Scalar? {
         guard KvIsNonzero(normal.x) else { return nil }
 
-        return -(c + normal.y * y) as Scalar / normal.x
+        return (-(c + normal.y * y)) as Scalar / normal.x
     }
 
 
@@ -283,6 +283,8 @@ public struct KvLine2<Math : KvMathScope> {
     }
 
 
+    // MARK: Transformations
+
     /// Translates all the receiver's ponts by *offset*.
     ///
     /// - Note: It's faster then apply an arbitrary transformation.

Sources/kvGeometry/KvLine2.swift

@@ -117,12 +117,16 @@ public struct KvLine3<Math : KvMathScope> {
 
 
     /// - Returns: The distance from the receiver to given coordinate.
+    ///
+    /// See: ``distanceEpsArg(_:)``.
     @inlinable
     public func distance(to x: Coordinate) -> Scalar {
         Math.length(Math.cross(x - origin, front))
     }
 
     /// - Returns: The distance from the receiver to given vertex.
+    ///
+    /// See: ``distanceEpsArg(_:)``.
     @inlinable
     public func distance<V>(to v: V) -> Scalar
     where V : KvVertex3Protocol, V.Math == Math {
@@ -131,20 +135,30 @@ public struct KvLine3<Math : KvMathScope> {
 
 
     /// - Returns: A boolean value indicating whether the receiver contains given coordinate.
+    ///
+    /// See: ``distanceEpsArg(_:)``.
     @inlinable
     public func contains(_ c: Coordinate) -> Bool {
-        let c = c - origin
-        return Math.isZero(Math.cross(front, c), eps: Math.epsArg(front).cross(Math.epsArg(c)).tolerance)
+        Math.isZero(Math.cross(front, c - origin), eps: distanceEpsArg(c).tolerance)
     }
 
     /// - Returns: A boolean value indicating whether the receiver contains given coordinate.
+    ///
+    /// See: ``distanceEpsArg(_:)``.
     @inlinable
     public func contains<V>(_ v: V) -> Bool
     where V : KvVertex3Protocol, V.Math == Math {
         contains(v.coordinate)
     }
 
 
+    /// - Returns: The tolerance argument for the distance calculation.
+    @inlinable
+    public func distanceEpsArg(_ c: Coordinate) -> Math.EpsArg3 {
+        Math.epsArg(front).cross(Math.epsArg(c) - Math.epsArg(origin))
+    }
+
+
     /// - Returns: Receivers coordinate having minimum distance to to given line or *nil* if the receiver and given line are parallel.
     ///
     /// - See  ``projection(of:)``.
@@ -171,6 +185,8 @@ public struct KvLine3<Math : KvMathScope> {
     @inlinable public func projection(of c: Coordinate) -> Coordinate { at(Math.dot((c - origin), front)) }
 
 
+    // MARK: Transformations
+
     /// - Returns: A line produced applying translation by *offset* to all the receiver's ponts.
     ///
     /// - Note: It's faster then apply an arbitrary transformation.

Sources/kvGeometry/KvLine3.swift

@@ -115,6 +115,14 @@ public struct KvPlane3<Math : KvMathScope> {
     @inlinable public var isDegenerate: Bool { Math.isZero(normal) }
 
 
+    /// Length of the receiver's normal.
+    /// E.g. it can be used to convert offsets of non-normalized planes to distances.
+    ///
+    /// - Note: Use it as less as possible.
+    /// - Note: There no need to use it when the receiver is normalized.
+    @inlinable public var scale: Scalar { Math.length(normal) }
+
+
     /// A transformation matrix from z = 0 plane to the receiver.
     ///
     /// - Note: Result is undefined when the receiver is degenerate.
@@ -169,7 +177,7 @@ public struct KvPlane3<Math : KvMathScope> {
     @inlinable public func signedOffset(to x: Coordinate) -> Scalar { at(x) }
 
 
-    /// - Returns: The distance from the receiver to *x* divided by length of the normal.
+    /// - Returns: The distance from the receiver to *x* scaled by length of the receiver's normal.
     @inlinable public func offset(to x: Coordinate) -> Scalar { abs(at(x)) }