@vib3code/sdk 2.0.1 → 2.0.3-canary.91a95f3

package/cpp/math/Mat4x4.hpp

@@ -0,0 +1,209 @@
+/**
+ * Mat4x4.hpp - 4x4 Matrix for VIB3+ SDK
+ *
+ * Column-major layout for direct GPU upload.
+ * All 6 rotation plane matrices for 4D rotation.
+ */
+
+#pragma once
+
+#include "Vec4.hpp"
+#include <array>
+
+namespace vib3 {
+
+// Forward declaration
+class Rotor4D;
+
+/**
+ * 4x4 Matrix class (column-major)
+ *
+ * Layout: [col0, col1, col2, col3] where each column is Vec4
+ * Element access: m[col][row] or m.at(row, col)
+ */
+class alignas(64) Mat4x4 {
+public:
+    std::array<float, 16> data;
+
+    // Constructors
+    Mat4x4() noexcept;
+    explicit Mat4x4(float diagonal) noexcept;
+    Mat4x4(const std::array<float, 16>& elements) noexcept;
+    Mat4x4(const Vec4& col0, const Vec4& col1, const Vec4& col2, const Vec4& col3) noexcept;
+
+    // Static factories
+    static Mat4x4 identity() noexcept;
+    static Mat4x4 zero() noexcept;
+
+    /**
+     * Create rotation matrix for XY plane (around Z axis in 3D)
+     */
+    static Mat4x4 rotationXY(float angle) noexcept;
+
+    /**
+     * Create rotation matrix for XZ plane (around Y axis in 3D)
+     */
+    static Mat4x4 rotationXZ(float angle) noexcept;
+
+    /**
+     * Create rotation matrix for YZ plane (around X axis in 3D)
+     */
+    static Mat4x4 rotationYZ(float angle) noexcept;
+
+    /**
+     * Create rotation matrix for XW plane (4D rotation)
+     */
+    static Mat4x4 rotationXW(float angle) noexcept;
+
+    /**
+     * Create rotation matrix for YW plane (4D rotation)
+     */
+    static Mat4x4 rotationYW(float angle) noexcept;
+
+    /**
+     * Create rotation matrix for ZW plane (4D rotation)
+     */
+    static Mat4x4 rotationZW(float angle) noexcept;
+
+    /**
+     * Create combined rotation from all 6 angles
+     * Order: XY * XZ * YZ * XW * YW * ZW
+     */
+    static Mat4x4 rotationFromAngles(float xy, float xz, float yz,
+                                      float xw, float yw, float zw) noexcept;
+
+    /**
+     * Create combined rotation from angle array
+     */
+    static Mat4x4 rotationFromAngles(const std::array<float, 6>& angles) noexcept;
+
+    /**
+     * Create scale matrix
+     */
+    static Mat4x4 scale(float sx, float sy, float sz, float sw) noexcept;
+    static Mat4x4 scale(float uniform) noexcept;
+    static Mat4x4 scale(const Vec4& s) noexcept;
+
+    /**
+     * Create translation matrix (in homogeneous coordinates)
+     * Note: Standard 4D doesn't use translation matrices the same way
+     */
+    static Mat4x4 translation(float tx, float ty, float tz, float tw = 0) noexcept;
+    static Mat4x4 translation(const Vec4& t) noexcept;
+
+    // Element access
+
+    /**
+     * Access element (row, col) - note: stored column-major
+     */
+    float& at(size_t row, size_t col) noexcept;
+    const float& at(size_t row, size_t col) const noexcept;
+
+    /**
+     * Get column as Vec4
+     */
+    Vec4 column(size_t col) const noexcept;
+
+    /**
+     * Set column from Vec4
+     */
+    void setColumn(size_t col, const Vec4& v) noexcept;
+
+    /**
+     * Get row as Vec4
+     */
+    Vec4 row(size_t row) const noexcept;
+
+    /**
+     * Set row from Vec4
+     */
+    void setRow(size_t row, const Vec4& v) noexcept;
+
+    // Matrix operations
+
+    /**
+     * Matrix multiplication
+     */
+    Mat4x4 operator*(const Mat4x4& other) const noexcept;
+
+    /**
+     * Compound multiplication
+     */
+    Mat4x4& operator*=(const Mat4x4& other) noexcept;
+
+    /**
+     * Transform a Vec4
+     */
+    Vec4 operator*(const Vec4& v) const noexcept;
+
+    /**
+     * Scalar multiplication
+     */
+    Mat4x4 operator*(float scalar) const noexcept;
+    Mat4x4& operator*=(float scalar) noexcept;
+
+    /**
+     * Matrix addition
+     */
+    Mat4x4 operator+(const Mat4x4& other) const noexcept;
+    Mat4x4& operator+=(const Mat4x4& other) noexcept;
+
+    /**
+     * Matrix subtraction
+     */
+    Mat4x4 operator-(const Mat4x4& other) const noexcept;
+    Mat4x4& operator-=(const Mat4x4& other) noexcept;
+
+    /**
+     * Transpose
+     */
+    Mat4x4 transposed() const noexcept;
+
+    /**
+     * Transpose in place
+     */
+    void transpose() noexcept;
+
+    /**
+     * Determinant
+     */
+    float determinant() const noexcept;
+
+    /**
+     * Inverse (returns identity if singular)
+     */
+    Mat4x4 inverse() const noexcept;
+
+    /**
+     * Check if orthogonal (columns are orthonormal)
+     */
+    bool isOrthogonal(float epsilon = 1e-5f) const noexcept;
+
+    /**
+     * Check if identity matrix
+     */
+    bool isIdentity(float epsilon = 1e-5f) const noexcept;
+
+    // Comparison
+
+    bool operator==(const Mat4x4& other) const noexcept;
+    bool operator!=(const Mat4x4& other) const noexcept;
+
+    /**
+     * Get pointer to data for GPU upload
+     */
+    const float* ptr() const noexcept { return data.data(); }
+    float* ptr() noexcept { return data.data(); }
+
+    /**
+     * Transform Vec4 (same as operator*)
+     */
+    Vec4 multiplyVec4(const Vec4& v) const noexcept;
+};
+
+// Free function operators
+inline Mat4x4 operator*(float scalar, const Mat4x4& m) noexcept {
+    return m * scalar;
+}
+
+} // namespace vib3

package/cpp/math/Projection.cpp

@@ -0,0 +1,142 @@
+/**
+ * Projection.cpp - 4D to 3D Projection Implementation
+ */
+
+#include "Projection.hpp"
+#include <cmath>
+#include <algorithm>
+
+namespace vib3 {
+
+constexpr float LARGE_VALUE = 1e6f;
+constexpr float EPSILON = 1e-6f;
+
+Projection3D projectPerspective(const Vec4& v, float distance) noexcept {
+    float denom = distance - v.w;
+
+    // Handle singularity
+    if (std::abs(denom) < EPSILON) {
+        float sign = (denom >= 0) ? 1.0f : -1.0f;
+        return Projection3D(
+            v.x * sign * LARGE_VALUE,
+            v.y * sign * LARGE_VALUE,
+            v.z * sign * LARGE_VALUE
+        );
+    }
+
+    float factor = distance / denom;
+    return Projection3D(v.x * factor, v.y * factor, v.z * factor);
+}
+
+Projection3D projectStereographic(const Vec4& v) noexcept {
+    float denom = 1.0f - v.w;
+
+    // Handle singularity at w = 1 (north pole of hypersphere)
+    if (std::abs(denom) < EPSILON) {
+        // Return direction at infinity
+        float sign = (v.x + v.y + v.z >= 0) ? 1.0f : -1.0f;
+        return Projection3D(sign * LARGE_VALUE, sign * LARGE_VALUE, sign * LARGE_VALUE);
+    }
+
+    float factor = 1.0f / denom;
+    return Projection3D(v.x * factor, v.y * factor, v.z * factor);
+}
+
+Projection3D projectOrthographic(const Vec4& v) noexcept {
+    return Projection3D(v.x, v.y, v.z);
+}
+
+Projection3D projectOblique(const Vec4& v,
+                             float shearX,
+                             float shearY,
+                             float shearZ) noexcept {
+    return Projection3D(
+        v.x + shearX * v.w,
+        v.y + shearY * v.w,
+        v.z + shearZ * v.w
+    );
+}
+
+SliceResult projectSlice(const Vec4& v,
+                          float sliceW,
+                          float thickness,
+                          bool fade) noexcept {
+    float dist = std::abs(v.w - sliceW);
+
+    if (dist > thickness) {
+        return SliceResult::invalid();
+    }
+
+    float alpha = 1.0f;
+    if (fade && thickness > 0) {
+        alpha = 1.0f - (dist / thickness);
+        alpha = std::max(0.0f, std::min(1.0f, alpha));
+    }
+
+    return SliceResult{
+        Projection3D(v.x, v.y, v.z),
+        alpha,
+        true
+    };
+}
+
+// Batch projections
+
+std::vector<Projection3D> projectPerspectiveBatch(
+    const std::vector<Vec4>& points,
+    float distance
+) noexcept {
+    std::vector<Projection3D> result;
+    result.reserve(points.size());
+
+    for (const auto& p : points) {
+        result.push_back(projectPerspective(p, distance));
+    }
+
+    return result;
+}
+
+std::vector<Projection3D> projectStereographicBatch(
+    const std::vector<Vec4>& points
+) noexcept {
+    std::vector<Projection3D> result;
+    result.reserve(points.size());
+
+    for (const auto& p : points) {
+        result.push_back(projectStereographic(p));
+    }
+
+    return result;
+}
+
+std::vector<Projection3D> projectOrthographicBatch(
+    const std::vector<Vec4>& points
+) noexcept {
+    std::vector<Projection3D> result;
+    result.reserve(points.size());
+
+    for (const auto& p : points) {
+        result.push_back(projectOrthographic(p));
+    }
+
+    return result;
+}
+
+std::vector<float> projectToFloatArray(
+    const std::vector<Vec4>& points,
+    float distance
+) noexcept {
+    std::vector<float> result;
+    result.reserve(points.size() * 3);
+
+    for (const auto& p : points) {
+        auto proj = projectPerspective(p, distance);
+        result.push_back(proj.x);
+        result.push_back(proj.y);
+        result.push_back(proj.z);
+    }
+
+    return result;
+}
+
+} // namespace vib3

package/cpp/math/Projection.hpp

@@ -0,0 +1,148 @@
+/**
+ * Projection.hpp - 4D to 3D Projection Functions
+ *
+ * Various projection methods for visualizing 4D geometry in 3D.
+ */
+
+#pragma once
+
+#include "Vec4.hpp"
+#include <array>
+#include <vector>
+
+namespace vib3 {
+
+/**
+ * 4D to 3D projection result
+ */
+struct Projection3D {
+    float x, y, z;
+
+    constexpr Projection3D() noexcept : x(0), y(0), z(0) {}
+    constexpr Projection3D(float x, float y, float z) noexcept : x(x), y(y), z(z) {}
+
+    /**
+     * Convert to array
+     */
+    constexpr std::array<float, 3> toArray() const noexcept {
+        return {x, y, z};
+    }
+};
+
+/**
+ * Projection parameters
+ */
+struct ProjectionParams {
+    float distance = 2.0f;      // For perspective projection
+    float viewerW = 0.0f;       // Viewer position in W
+    float sliceW = 0.0f;        // For slice projection
+    float sliceThickness = 0.1f;
+
+    static ProjectionParams defaults() noexcept {
+        return ProjectionParams{};
+    }
+};
+
+/**
+ * Perspective projection: X = x * d / (d - w)
+ *
+ * Projects 4D points as if viewed from w = distance.
+ * Objects farther in w appear smaller (like depth in 3D).
+ *
+ * @param v 4D point
+ * @param distance Projection distance
+ * @return 3D projected point
+ */
+Projection3D projectPerspective(const Vec4& v, float distance = 2.0f) noexcept;
+
+/**
+ * Stereographic projection: X = x / (1 - w)
+ *
+ * Conformal projection from S³ (unit hypersphere).
+ * Preserves angles but not distances.
+ * Pole at w = 1 maps to infinity.
+ *
+ * @param v 4D point (ideally on unit hypersphere)
+ * @return 3D projected point
+ */
+Projection3D projectStereographic(const Vec4& v) noexcept;
+
+/**
+ * Orthographic projection: X = x, Y = y, Z = z
+ *
+ * Simple parallel projection, discarding W.
+ *
+ * @param v 4D point
+ * @return 3D projected point
+ */
+Projection3D projectOrthographic(const Vec4& v) noexcept;
+
+/**
+ * Oblique (cavalier) projection: X = x + shear.x * w, etc.
+ *
+ * @param v 4D point
+ * @param shearX X shear factor
+ * @param shearY Y shear factor
+ * @param shearZ Z shear factor
+ * @return 3D projected point
+ */
+Projection3D projectOblique(const Vec4& v,
+                             float shearX = 0.5f,
+                             float shearY = 0.5f,
+                             float shearZ = 0.0f) noexcept;
+
+/**
+ * Cross-sectional slice projection
+ *
+ * Returns empty if point is outside the slice.
+ *
+ * @param v 4D point
+ * @param sliceW W coordinate of the slice plane
+ * @param thickness Half-thickness of the slice
+ * @param fade If true, fade points near edges
+ * @return 3D point if in slice, or empty optional
+ */
+struct SliceResult {
+    Projection3D point;
+    float alpha;  // 1.0 = center of slice, 0.0 = edge
+    bool valid;
+
+    static SliceResult invalid() noexcept {
+        return SliceResult{{}, 0.0f, false};
+    }
+};
+
+SliceResult projectSlice(const Vec4& v,
+                          float sliceW = 0.0f,
+                          float thickness = 0.1f,
+                          bool fade = true) noexcept;
+
+/**
+ * Batch projection for efficiency
+ */
+std::vector<Projection3D> projectPerspectiveBatch(
+    const std::vector<Vec4>& points,
+    float distance = 2.0f
+) noexcept;
+
+std::vector<Projection3D> projectStereographicBatch(
+    const std::vector<Vec4>& points
+) noexcept;
+
+std::vector<Projection3D> projectOrthographicBatch(
+    const std::vector<Vec4>& points
+) noexcept;
+
+/**
+ * Project to flat array (for GPU upload)
+ *
+ * @param points Input 4D points
+ * @param distance Projection distance
+ * @return Flat array [x0,y0,z0, x1,y1,z1, ...]
+ */
+std::vector<float> projectToFloatArray(
+    const std::vector<Vec4>& points,
+    float distance = 2.0f
+) noexcept;
+
+} // namespace vib3