@vib3code/sdk 2.0.1 → 2.0.3-canary.0a63e71

package/cpp/math/Rotor4D.hpp

@@ -0,0 +1,204 @@
+/**
+ * Rotor4D.hpp - 4D Rotor for VIB3+ SDK
+ *
+ * 8-component rotor for proper 4D rotation using geometric algebra.
+ * Components: scalar + 6 bivectors (XY, XZ, YZ, XW, YW, ZW) + pseudoscalar
+ *
+ * Unlike quaternions (which work for 3D), rotors handle all 6 rotation planes.
+ */
+
+#pragma once
+
+#include "Vec4.hpp"
+#include "Mat4x4.hpp"
+#include <array>
+
+namespace vib3 {
+
+// Forward declaration
+class Mat4x4;
+
+/**
+ * Rotation plane identifiers
+ */
+enum class RotationPlane {
+    XY = 0,  // 3D rotation around Z
+    XZ = 1,  // 3D rotation around Y
+    YZ = 2,  // 3D rotation around X
+    XW = 3,  // 4D rotation (X-W plane)
+    YW = 4,  // 4D rotation (Y-W plane)
+    ZW = 5   // 4D rotation (Z-W plane)
+};
+
+/**
+ * 4D Rotor class
+ *
+ * Components:
+ * - s:    scalar part
+ * - xy:   XY bivector (rotation in XY plane)
+ * - xz:   XZ bivector (rotation in XZ plane)
+ * - yz:   YZ bivector (rotation in YZ plane)
+ * - xw:   XW bivector (rotation in XW plane)
+ * - yw:   YW bivector (rotation in YW plane)
+ * - zw:   ZW bivector (rotation in ZW plane)
+ * - xyzw: pseudoscalar (4D volume element)
+ */
+class Rotor4D {
+public:
+    float s;     // Scalar
+    float xy;    // Bivector XY
+    float xz;    // Bivector XZ
+    float yz;    // Bivector YZ
+    float xw;    // Bivector XW
+    float yw;    // Bivector YW
+    float zw;    // Bivector ZW
+    float xyzw;  // Pseudoscalar
+
+    // Constructors
+    constexpr Rotor4D() noexcept
+        : s(1), xy(0), xz(0), yz(0), xw(0), yw(0), zw(0), xyzw(0) {}
+
+    constexpr Rotor4D(float s, float xy, float xz, float yz,
+                      float xw, float yw, float zw, float xyzw) noexcept
+        : s(s), xy(xy), xz(xz), yz(yz), xw(xw), yw(yw), zw(zw), xyzw(xyzw) {}
+
+    /**
+     * Identity rotor (no rotation)
+     */
+    static constexpr Rotor4D identity() noexcept {
+        return Rotor4D(1, 0, 0, 0, 0, 0, 0, 0);
+    }
+
+    /**
+     * Create rotor from rotation in a single plane
+     * @param plane The rotation plane
+     * @param angle Rotation angle in radians
+     */
+    static Rotor4D fromPlaneAngle(RotationPlane plane, float angle) noexcept;
+
+    /**
+     * Create rotor from 6 Euler-like angles (one per plane)
+     * @param angles Array of 6 angles [XY, XZ, YZ, XW, YW, ZW]
+     */
+    static Rotor4D fromEuler6(const std::array<float, 6>& angles) noexcept;
+
+    /**
+     * Create rotor from 6 individual angles
+     */
+    static Rotor4D fromEuler6(float xy, float xz, float yz,
+                               float xw, float yw, float zw) noexcept;
+
+    /**
+     * Get all components as array
+     */
+    std::array<float, 8> toArray() const noexcept;
+
+    /**
+     * Set all components from array
+     */
+    void fromArray(const std::array<float, 8>& arr) noexcept;
+
+    // Rotor operations
+
+    /**
+     * Rotor multiplication (composition)
+     */
+    Rotor4D operator*(const Rotor4D& other) const noexcept;
+
+    /**
+     * Compound multiplication
+     */
+    Rotor4D& operator*=(const Rotor4D& other) noexcept;
+
+    /**
+     * Reverse (conjugate) - reverses rotation direction
+     */
+    Rotor4D reverse() const noexcept;
+
+    /**
+     * Squared magnitude
+     */
+    float magnitudeSquared() const noexcept;
+
+    /**
+     * Magnitude (norm)
+     */
+    float magnitude() const noexcept;
+
+    /**
+     * Normalize to unit rotor
+     */
+    Rotor4D normalized() const noexcept;
+
+    /**
+     * Normalize in place
+     */
+    void normalize() noexcept;
+
+    /**
+     * Inverse rotor
+     */
+    Rotor4D inverse() const noexcept;
+
+    /**
+     * Check if approximately unit rotor
+     */
+    bool isNormalized(float epsilon = 1e-5f) const noexcept;
+
+    // Vector rotation
+
+    /**
+     * Rotate a 4D vector: v' = R * v * R†
+     */
+    Vec4 rotate(const Vec4& v) const noexcept;
+
+    /**
+     * Rotate a 4D vector (in place)
+     */
+    void rotateInPlace(Vec4& v) const noexcept;
+
+    // Interpolation
+
+    /**
+     * Spherical linear interpolation
+     */
+    Rotor4D slerp(const Rotor4D& other, float t) const noexcept;
+
+    /**
+     * Normalized linear interpolation (faster but less accurate)
+     */
+    Rotor4D nlerp(const Rotor4D& other, float t) const noexcept;
+
+    // Matrix conversion
+
+    /**
+     * Convert to 4x4 rotation matrix
+     */
+    Mat4x4 toMatrix() const noexcept;
+
+    // Comparison
+
+    bool operator==(const Rotor4D& other) const noexcept;
+    bool operator!=(const Rotor4D& other) const noexcept;
+
+    /**
+     * Dot product between rotors (for slerp)
+     */
+    float dot(const Rotor4D& other) const noexcept;
+};
+
+/**
+ * Compose two rotations
+ */
+inline Rotor4D compose(const Rotor4D& first, const Rotor4D& second) noexcept {
+    return first * second;
+}
+
+/**
+ * Slerp free function
+ */
+inline Rotor4D slerp(const Rotor4D& a, const Rotor4D& b, float t) noexcept {
+    return a.slerp(b, t);
+}
+
+} // namespace vib3

package/cpp/math/Vec4.cpp

@@ -0,0 +1,303 @@
+/**
+ * Vec4.cpp - 4D Vector Implementation
+ */
+
+#include "Vec4.hpp"
+#include <random>
+#include <limits>
+
+namespace vib3 {
+
+// Static random generator for randomUnit()
+static std::mt19937& getRandomEngine() {
+    static std::random_device rd;
+    static std::mt19937 gen(rd());
+    return gen;
+}
+
+Vec4 Vec4::randomUnit() noexcept {
+    // Marsaglia method for uniform distribution on S³
+    std::normal_distribution<float> dist(0.0f, 1.0f);
+    auto& gen = getRandomEngine();
+
+    Vec4 v(dist(gen), dist(gen), dist(gen), dist(gen));
+    v.normalize();
+    return v;
+}
+
+// Arithmetic operators
+
+#if defined(VIB3_HAS_SSE41)
+
+Vec4 Vec4::operator+(const Vec4& other) const noexcept {
+    return Vec4(_mm_add_ps(simd, other.simd));
+}
+
+Vec4 Vec4::operator-(const Vec4& other) const noexcept {
+    return Vec4(_mm_sub_ps(simd, other.simd));
+}
+
+Vec4 Vec4::operator*(float scalar) const noexcept {
+    return Vec4(_mm_mul_ps(simd, _mm_set1_ps(scalar)));
+}
+
+Vec4 Vec4::operator/(float scalar) const noexcept {
+    return Vec4(_mm_div_ps(simd, _mm_set1_ps(scalar)));
+}
+
+Vec4 Vec4::operator-() const noexcept {
+    return Vec4(_mm_xor_ps(simd, _mm_set1_ps(-0.0f)));
+}
+
+float Vec4::dot(const Vec4& other) const noexcept {
+    __m128 mul = _mm_mul_ps(simd, other.simd);
+    __m128 sum = _mm_hadd_ps(mul, mul);
+    sum = _mm_hadd_ps(sum, sum);
+    return _mm_cvtss_f32(sum);
+}
+
+Vec4 Vec4::min(const Vec4& other) const noexcept {
+    return Vec4(_mm_min_ps(simd, other.simd));
+}
+
+Vec4 Vec4::max(const Vec4& other) const noexcept {
+    return Vec4(_mm_max_ps(simd, other.simd));
+}
+
+Vec4 Vec4::abs() const noexcept {
+    __m128 mask = _mm_castsi128_ps(_mm_set1_epi32(0x7FFFFFFF));
+    return Vec4(_mm_and_ps(simd, mask));
+}
+
+#elif defined(__EMSCRIPTEN__)
+
+Vec4 Vec4::operator+(const Vec4& other) const noexcept {
+    return Vec4(wasm_f32x4_add(simd, other.simd));
+}
+
+Vec4 Vec4::operator-(const Vec4& other) const noexcept {
+    return Vec4(wasm_f32x4_sub(simd, other.simd));
+}
+
+Vec4 Vec4::operator*(float scalar) const noexcept {
+    return Vec4(wasm_f32x4_mul(simd, wasm_f32x4_splat(scalar)));
+}
+
+Vec4 Vec4::operator/(float scalar) const noexcept {
+    return Vec4(wasm_f32x4_div(simd, wasm_f32x4_splat(scalar)));
+}
+
+Vec4 Vec4::operator-() const noexcept {
+    return Vec4(wasm_f32x4_neg(simd));
+}
+
+float Vec4::dot(const Vec4& other) const noexcept {
+    v128_t mul = wasm_f32x4_mul(simd, other.simd);
+    return wasm_f32x4_extract_lane(mul, 0) +
+           wasm_f32x4_extract_lane(mul, 1) +
+           wasm_f32x4_extract_lane(mul, 2) +
+           wasm_f32x4_extract_lane(mul, 3);
+}
+
+Vec4 Vec4::min(const Vec4& other) const noexcept {
+    return Vec4(wasm_f32x4_min(simd, other.simd));
+}
+
+Vec4 Vec4::max(const Vec4& other) const noexcept {
+    return Vec4(wasm_f32x4_max(simd, other.simd));
+}
+
+Vec4 Vec4::abs() const noexcept {
+    return Vec4(wasm_f32x4_abs(simd));
+}
+
+#else
+// Scalar fallback
+
+Vec4 Vec4::operator+(const Vec4& other) const noexcept {
+    return Vec4(x + other.x, y + other.y, z + other.z, w + other.w);
+}
+
+Vec4 Vec4::operator-(const Vec4& other) const noexcept {
+    return Vec4(x - other.x, y - other.y, z - other.z, w - other.w);
+}
+
+Vec4 Vec4::operator*(float scalar) const noexcept {
+    return Vec4(x * scalar, y * scalar, z * scalar, w * scalar);
+}
+
+Vec4 Vec4::operator/(float scalar) const noexcept {
+    float inv = 1.0f / scalar;
+    return Vec4(x * inv, y * inv, z * inv, w * inv);
+}
+
+Vec4 Vec4::operator-() const noexcept {
+    return Vec4(-x, -y, -z, -w);
+}
+
+float Vec4::dot(const Vec4& other) const noexcept {
+    return x * other.x + y * other.y + z * other.z + w * other.w;
+}
+
+Vec4 Vec4::min(const Vec4& other) const noexcept {
+    return Vec4(
+        std::min(x, other.x),
+        std::min(y, other.y),
+        std::min(z, other.z),
+        std::min(w, other.w)
+    );
+}
+
+Vec4 Vec4::max(const Vec4& other) const noexcept {
+    return Vec4(
+        std::max(x, other.x),
+        std::max(y, other.y),
+        std::max(z, other.z),
+        std::max(w, other.w)
+    );
+}
+
+Vec4 Vec4::abs() const noexcept {
+    return Vec4(std::abs(x), std::abs(y), std::abs(z), std::abs(w));
+}
+
+#endif
+
+// Compound assignment (always scalar for simplicity)
+
+Vec4& Vec4::operator+=(const Vec4& other) noexcept {
+    *this = *this + other;
+    return *this;
+}
+
+Vec4& Vec4::operator-=(const Vec4& other) noexcept {
+    *this = *this - other;
+    return *this;
+}
+
+Vec4& Vec4::operator*=(float scalar) noexcept {
+    *this = *this * scalar;
+    return *this;
+}
+
+Vec4& Vec4::operator/=(float scalar) noexcept {
+    *this = *this / scalar;
+    return *this;
+}
+
+// Comparison
+
+bool Vec4::operator==(const Vec4& other) const noexcept {
+    return x == other.x && y == other.y && z == other.z && w == other.w;
+}
+
+bool Vec4::operator!=(const Vec4& other) const noexcept {
+    return !(*this == other);
+}
+
+// Length and normalization
+
+float Vec4::lengthSquared() const noexcept {
+    return dot(*this);
+}
+
+float Vec4::length() const noexcept {
+    return std::sqrt(lengthSquared());
+}
+
+Vec4 Vec4::normalized() const noexcept {
+    float len = length();
+    if (len > 0) {
+        return *this / len;
+    }
+    return Vec4::zero();
+}
+
+void Vec4::normalize() noexcept {
+    float len = length();
+    if (len > 0) {
+        *this /= len;
+    }
+}
+
+// Distance
+
+float Vec4::distanceTo(const Vec4& other) const noexcept {
+    return (*this - other).length();
+}
+
+float Vec4::distanceSquaredTo(const Vec4& other) const noexcept {
+    return (*this - other).lengthSquared();
+}
+
+// Interpolation
+
+Vec4 Vec4::lerp(const Vec4& other, float t) const noexcept {
+    return *this + (other - *this) * t;
+}
+
+// Clamp
+
+Vec4 Vec4::clamp(const Vec4& minVal, const Vec4& maxVal) const noexcept {
+    return this->max(minVal).min(maxVal);
+}
+
+// Projection and reflection
+
+Vec4 Vec4::projectOnto(const Vec4& other) const noexcept {
+    float d = other.dot(other);
+    if (d > 0) {
+        return other * (dot(other) / d);
+    }
+    return Vec4::zero();
+}
+
+Vec4 Vec4::reflect(const Vec4& normal) const noexcept {
+    return *this - normal * (2.0f * dot(normal));
+}
+
+// Validation
+
+bool Vec4::isZero(float epsilon) const noexcept {
+    return lengthSquared() < epsilon * epsilon;
+}
+
+bool Vec4::isNormalized(float epsilon) const noexcept {
+    return std::abs(lengthSquared() - 1.0f) < epsilon;
+}
+
+// 4D -> 3D Projections
+
+std::array<float, 3> Vec4::projectPerspective(float distance) const noexcept {
+    float denom = distance - w;
+
+    // Handle singularity
+    if (std::abs(denom) < 1e-6f) {
+        float sign = (denom >= 0) ? 1.0f : -1.0f;
+        constexpr float large = 1e6f;
+        return {x * sign * large, y * sign * large, z * sign * large};
+    }
+
+    float factor = distance / denom;
+    return {x * factor, y * factor, z * factor};
+}
+
+std::array<float, 3> Vec4::projectStereographic() const noexcept {
+    float denom = 1.0f - w;
+
+    // Handle singularity at w = 1
+    if (std::abs(denom) < 1e-6f) {
+        constexpr float large = 1e6f;
+        float sign = (x + y + z >= 0) ? 1.0f : -1.0f;
+        return {sign * large, sign * large, sign * large};
+    }
+
+    float factor = 1.0f / denom;
+    return {x * factor, y * factor, z * factor};
+}
+
+std::array<float, 3> Vec4::projectOrthographic() const noexcept {
+    return {x, y, z};
+}
+
+} // namespace vib3