@vib3code/sdk 2.0.1 → 2.0.3-canary.6f35b4c

package/cpp/geometry/Crystal.cpp

@@ -0,0 +1,103 @@
+/**
+ * Crystal.cpp - Octahedral / Crystalline Structure in 4D
+ *
+ * Generates vertices and edge geometry for crystalline structures
+ * in 4D: the regular octahedron (cross-polytope) and its dual,
+ * extended with 4D vertices along the W axis.
+ *
+ * The 4D cross-polytope (hyperoctahedron / 16-cell) has 8 vertices
+ * at the 4 axis-aligned unit positions and their negations.
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <cmath>
+#include <numbers>
+
+namespace vib3 {
+
+/**
+ * Generate the 8 vertices of a 4D cross-polytope (hyperoctahedron / 16-cell).
+ *
+ * Vertices lie at (+-1, 0, 0, 0), (0, +-1, 0, 0), (0, 0, +-1, 0), (0, 0, 0, +-1).
+ */
+std::vector<Vec4> generateCrossPolytopeVertices() noexcept {
+    std::vector<Vec4> vertices;
+    vertices.reserve(8);
+
+    vertices.emplace_back( 1.0f,  0.0f,  0.0f,  0.0f);
+    vertices.emplace_back(-1.0f,  0.0f,  0.0f,  0.0f);
+    vertices.emplace_back( 0.0f,  1.0f,  0.0f,  0.0f);
+    vertices.emplace_back( 0.0f, -1.0f,  0.0f,  0.0f);
+    vertices.emplace_back( 0.0f,  0.0f,  1.0f,  0.0f);
+    vertices.emplace_back( 0.0f,  0.0f, -1.0f,  0.0f);
+    vertices.emplace_back( 0.0f,  0.0f,  0.0f,  1.0f);
+    vertices.emplace_back( 0.0f,  0.0f,  0.0f, -1.0f);
+
+    return vertices;
+}
+
+/**
+ * Generate crystalline geometry with edge interpolation.
+ *
+ * The 4D cross-polytope has 24 edges: every pair of non-antipodal vertices
+ * is connected (i.e., vertices i and j are connected unless they lie on
+ * the same axis). Each edge is subdivided into `resolution` segments.
+ *
+ * Additionally generates midpoint vertices for a dual-lattice structure
+ * (the 4D hypercube formed by the dual vertices at the edge midpoints).
+ *
+ * @param resolution Number of subdivisions per edge (minimum 2)
+ * @return Vector of 4D points forming the crystal wireframe
+ */
+std::vector<Vec4> generateCrystal(int resolution) noexcept {
+    if (resolution < 2) resolution = 2;
+
+    auto baseVertices = generateCrossPolytopeVertices();
+
+    // Edges of the 16-cell: connect every pair of vertices that are
+    // NOT antipodal (not on the same axis).
+    // 8 vertices, 24 edges total.
+    struct Edge { int a, b; };
+    std::vector<Edge> edges;
+    edges.reserve(24);
+
+    for (int i = 0; i < 8; ++i) {
+        for (int j = i + 1; j < 8; ++j) {
+            // Antipodal pairs: (0,1), (2,3), (4,5), (6,7)
+            // Skip if on same axis (differ by 1 and i is even)
+            if ((i ^ j) == 1 && (i % 2 == 0)) {
+                continue;
+            }
+            edges.push_back({i, j});
+        }
+    }
+
+    std::vector<Vec4> vertices;
+    vertices.reserve(edges.size() * static_cast<size_t>(resolution) + 16);
+
+    // Edge wireframe
+    for (const auto& edge : edges) {
+        const Vec4& a = baseVertices[static_cast<size_t>(edge.a)];
+        const Vec4& b = baseVertices[static_cast<size_t>(edge.b)];
+
+        for (int i = 0; i < resolution; ++i) {
+            float t = static_cast<float>(i) / static_cast<float>(resolution - 1);
+            vertices.push_back(a.lerp(b, t));
+        }
+    }
+
+    // Dual vertices (tesseract / hypercube dual): midpoints of faces
+    // These are the 16 vertices of the dual polytope at (+-0.5, +-0.5, +-0.5, +-0.5)
+    for (int i = 0; i < 16; ++i) {
+        float x = (i & 1) ? 0.5f : -0.5f;
+        float y = (i & 2) ? 0.5f : -0.5f;
+        float z = (i & 4) ? 0.5f : -0.5f;
+        float w = (i & 8) ? 0.5f : -0.5f;
+        vertices.emplace_back(x, y, z, w);
+    }
+
+    return vertices;
+}
+
+} // namespace vib3

package/cpp/geometry/Fractal.cpp

@@ -0,0 +1,136 @@
+/**
+ * Fractal.cpp - 4D Iterated Function System Fractal
+ *
+ * Generates recursive subdivision geometry in 4D using an IFS approach.
+ * Starts from an initial set of points and iteratively applies affine
+ * contractions toward attractor vertices, building a self-similar
+ * fractal structure (a 4D analogue of the Sierpinski tetrahedron).
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <cmath>
+#include <numbers>
+#include <cstdint>
+
+namespace vib3 {
+
+namespace {
+
+/**
+ * 4D Sierpinski-style attractor vertices.
+ *
+ * Five vertices of a regular 5-cell (pentatope) provide a natural
+ * set of contraction centers for a 4D IFS.
+ */
+constexpr int kNumAttractors = 5;
+
+Vec4 getAttractorVertex(int index) noexcept {
+    // Regular pentatope vertices (5-cell), embedded in R4
+    // These are the vertices of a regular simplex in 4D.
+    switch (index) {
+        case 0: return Vec4( 1.0f,  1.0f,  1.0f, -1.0f / std::numbers::sqrt2_v<float>);
+        case 1: return Vec4( 1.0f, -1.0f, -1.0f, -1.0f / std::numbers::sqrt2_v<float>);
+        case 2: return Vec4(-1.0f,  1.0f, -1.0f, -1.0f / std::numbers::sqrt2_v<float>);
+        case 3: return Vec4(-1.0f, -1.0f,  1.0f, -1.0f / std::numbers::sqrt2_v<float>);
+        case 4: return Vec4( 0.0f,  0.0f,  0.0f,  4.0f / std::numbers::sqrt2_v<float>);
+        default: return Vec4::zero();
+    }
+}
+
+/**
+ * Simple deterministic hash for reproducible pseudo-random attractor selection.
+ */
+constexpr uint32_t hashStep(uint32_t seed) noexcept {
+    seed ^= seed << 13;
+    seed ^= seed >> 17;
+    seed ^= seed << 5;
+    return seed;
+}
+
+} // anonymous namespace
+
+/**
+ * Generate a 4D IFS fractal via the chaos game.
+ *
+ * Uses the classic chaos game algorithm: starting from a seed point,
+ * repeatedly pick a random attractor and move halfway toward it.
+ * After a warm-up period, the trajectory traces out the fractal.
+ *
+ * @param resolution Controls the number of output points (resolution^2 points)
+ * @return Vector of 4D fractal points
+ */
+std::vector<Vec4> generateFractal(int resolution) noexcept {
+    if (resolution < 4) resolution = 4;
+
+    int numPoints = resolution * resolution;
+    constexpr int warmUp = 64;
+    constexpr float contractionFactor = 0.5f;
+
+    std::vector<Vec4> vertices;
+    vertices.reserve(static_cast<size_t>(numPoints));
+
+    // Start at the origin
+    Vec4 current = Vec4::zero();
+    uint32_t seed = 0xDEADBEEF;
+
+    // Warm-up iterations (discard to converge onto attractor)
+    for (int i = 0; i < warmUp; ++i) {
+        seed = hashStep(seed);
+        int attIdx = static_cast<int>(seed % kNumAttractors);
+        Vec4 target = getAttractorVertex(attIdx);
+        current = current.lerp(target, contractionFactor);
+    }
+
+    // Generate fractal points
+    for (int i = 0; i < numPoints; ++i) {
+        seed = hashStep(seed);
+        int attIdx = static_cast<int>(seed % kNumAttractors);
+        Vec4 target = getAttractorVertex(attIdx);
+        current = current.lerp(target, contractionFactor);
+        vertices.push_back(current);
+    }
+
+    return vertices;
+}
+
+/**
+ * Generate a 4D IFS fractal via recursive subdivision.
+ *
+ * Starts from attractor vertices and recursively subdivides midpoints
+ * to a given depth, producing a deterministic point set.
+ *
+ * @param depth Recursion depth (0 = just vertices, each level multiplies points by 5)
+ * @return Vector of 4D fractal points
+ */
+std::vector<Vec4> generateFractalSubdivision(int depth) noexcept {
+    if (depth < 0) depth = 0;
+    if (depth > 6) depth = 6; // Cap to avoid excessive memory
+
+    std::vector<Vec4> current;
+    current.reserve(static_cast<size_t>(kNumAttractors));
+
+    // Seed with attractor vertices
+    for (int i = 0; i < kNumAttractors; ++i) {
+        current.push_back(getAttractorVertex(i));
+    }
+
+    // Recursive subdivision
+    for (int d = 0; d < depth; ++d) {
+        std::vector<Vec4> next;
+        next.reserve(current.size() * static_cast<size_t>(kNumAttractors));
+
+        for (const auto& point : current) {
+            for (int a = 0; a < kNumAttractors; ++a) {
+                Vec4 target = getAttractorVertex(a);
+                next.push_back(point.lerp(target, 0.5f));
+            }
+        }
+
+        current = std::move(next);
+    }
+
+    return current;
+}
+
+} // namespace vib3

package/cpp/geometry/GeometryGenerator.cpp

@@ -0,0 +1,262 @@
+/**
+ * GeometryGenerator.cpp - Main Geometry Factory
+ *
+ * Dispatches to individual geometry generators based on geometry index.
+ * Uses the VIB3+ encoding: index = coreType * 8 + baseGeometry
+ *
+ * Core types:
+ *   0 = Base (index 0-7)      - Pure base geometry
+ *   1 = Hypersphere (index 8-15)  - Projected onto 3-sphere
+ *   2 = Hypertetrahedron (index 16-23) - Warped toward pentatope
+ *
+ * Base geometries (0-7):
+ *   0 = Tetrahedron    4 = Klein Bottle
+ *   1 = Hypercube      5 = Fractal
+ *   2 = Sphere         6 = Wave
+ *   3 = Torus          7 = Crystal
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <algorithm>
+
+namespace vib3 {
+
+// ---- Forward declarations of individual generators ----
+
+// geometry/Tetrahedron.cpp
+std::vector<Vec4> generateTetrahedron(int resolution) noexcept;
+
+// geometry/Tesseract.cpp
+std::vector<Vec4> generateTesseract(int resolution) noexcept;
+
+// geometry/Sphere.cpp
+std::vector<Vec4> generateSphere(int resolution) noexcept;
+
+// geometry/Torus.cpp
+std::vector<Vec4> generateTorus(int resolution) noexcept;
+
+// geometry/KleinBottle.cpp
+std::vector<Vec4> generateKleinBottle(int resolution) noexcept;
+
+// geometry/Fractal.cpp
+std::vector<Vec4> generateFractal(int resolution) noexcept;
+
+// geometry/Wave.cpp
+std::vector<Vec4> generateWave(int resolution) noexcept;
+
+// geometry/Crystal.cpp
+std::vector<Vec4> generateCrystal(int resolution) noexcept;
+
+// geometry/WarpFunctions.cpp
+Vec4 warpHypersphere(Vec4 point, float radius) noexcept;
+std::vector<Vec4> warpHypersphereBatch(const std::vector<Vec4>& points, float radius) noexcept;
+Vec4 warpHypertetra(Vec4 point) noexcept;
+std::vector<Vec4> warpHypertetraBatch(const std::vector<Vec4>& points) noexcept;
+
+// ---- Geometry index encoding ----
+
+/**
+ * Maximum valid geometry index (3 core types x 8 base geometries - 1).
+ */
+constexpr int kMaxGeometryIndex = 23;
+
+/**
+ * Number of base geometry types.
+ */
+constexpr int kBaseGeometryCount = 8;
+
+/**
+ * Decompose a geometry index into core type and base geometry.
+ *
+ * @param geometryIndex Combined index (0-23)
+ * @param coreType Output: 0=Base, 1=Hypersphere, 2=Hypertetrahedron
+ * @param baseGeometry Output: 0-7 base geometry type
+ */
+constexpr void decodeGeometryIndex(int geometryIndex,
+                                    int& coreType,
+                                    int& baseGeometry) noexcept {
+    coreType = geometryIndex / kBaseGeometryCount;
+    baseGeometry = geometryIndex % kBaseGeometryCount;
+}
+
+/**
+ * Encode core type and base geometry into a geometry index.
+ *
+ * @param coreType 0=Base, 1=Hypersphere, 2=Hypertetrahedron
+ * @param baseGeometry 0-7 base geometry type
+ * @return Combined geometry index (0-23)
+ */
+constexpr int encodeGeometryIndex(int coreType, int baseGeometry) noexcept {
+    return coreType * kBaseGeometryCount + baseGeometry;
+}
+
+// ---- Internal dispatch ----
+
+namespace {
+
+/**
+ * Generate base geometry vertices for a given base type.
+ */
+std::vector<Vec4> generateBaseGeometry(int baseGeometry, int resolution) noexcept {
+    switch (baseGeometry) {
+        case 0: return generateTetrahedron(resolution);
+        case 1: return generateTesseract(resolution);
+        case 2: return generateSphere(resolution);
+        case 3: return generateTorus(resolution);
+        case 4: return generateKleinBottle(resolution);
+        case 5: return generateFractal(resolution);
+        case 6: return generateWave(resolution);
+        case 7: return generateCrystal(resolution);
+        default:
+            // Unknown base geometry, return empty
+            return {};
+    }
+}
+
+/**
+ * Apply core type warp to a set of base vertices.
+ */
+std::vector<Vec4> applyWarp(int coreType, std::vector<Vec4> vertices) noexcept {
+    switch (coreType) {
+        case 0:
+            // Base: no warp
+            return vertices;
+
+        case 1:
+            // Hypersphere: project all vertices onto S3
+            return warpHypersphereBatch(vertices, 1.0f);
+
+        case 2:
+            // Hypertetrahedron: warp toward pentatope vertices
+            return warpHypertetraBatch(vertices);
+
+        default:
+            // Unknown core type, return unmodified
+            return vertices;
+    }
+}
+
+} // anonymous namespace
+
+// ---- Public API ----
+
+/**
+ * Generate 4D geometry for a given geometry index.
+ *
+ * This is the main entry point for the geometry library. It decodes the
+ * geometry index into a base geometry type and core type warp, generates
+ * the base geometry, and then applies the appropriate warp transformation.
+ *
+ * @param geometryIndex Combined geometry index (0-23)
+ *   - 0-7:   Base geometries (no warp)
+ *   - 8-15:  Hypersphere-warped geometries
+ *   - 16-23: Hypertetrahedron-warped geometries
+ *
+ * @param resolution Controls the level of detail. Higher values produce
+ *   more vertices. The exact meaning varies by geometry type but generally
+ *   represents subdivisions per dimension. Typical range: 4-100.
+ *
+ * @return Vector of 4D vertices. Empty if geometryIndex is out of range.
+ */
+std::vector<Vec4> generateGeometry(int geometryIndex, int resolution) noexcept {
+    // Clamp to valid range
+    if (geometryIndex < 0 || geometryIndex > kMaxGeometryIndex) {
+        return {};
+    }
+
+    if (resolution < 2) resolution = 2;
+    if (resolution > 256) resolution = 256;
+
+    int coreType = 0;
+    int baseGeometry = 0;
+    decodeGeometryIndex(geometryIndex, coreType, baseGeometry);
+
+    // Generate base geometry
+    std::vector<Vec4> vertices = generateBaseGeometry(baseGeometry, resolution);
+
+    // Apply core type warp
+    return applyWarp(coreType, std::move(vertices));
+}
+
+/**
+ * Get the name string for a base geometry type.
+ *
+ * @param baseGeometry Base geometry index (0-7)
+ * @return Human-readable name, or "Unknown" if out of range
+ */
+const char* getBaseGeometryName(int baseGeometry) noexcept {
+    switch (baseGeometry) {
+        case 0: return "Tetrahedron";
+        case 1: return "Hypercube";
+        case 2: return "Sphere";
+        case 3: return "Torus";
+        case 4: return "Klein Bottle";
+        case 5: return "Fractal";
+        case 6: return "Wave";
+        case 7: return "Crystal";
+        default: return "Unknown";
+    }
+}
+
+/**
+ * Get the name string for a core type.
+ *
+ * @param coreType Core type index (0-2)
+ * @return Human-readable name, or "Unknown" if out of range
+ */
+const char* getCoreTypeName(int coreType) noexcept {
+    switch (coreType) {
+        case 0: return "Base";
+        case 1: return "Hypersphere";
+        case 2: return "Hypertetrahedron";
+        default: return "Unknown";
+    }
+}
+
+/**
+ * Get a full descriptive name for a geometry index.
+ *
+ * Combines core type and base geometry names, e.g.
+ * "Hypersphere Torus" for index 11.
+ *
+ * @param geometryIndex Combined index (0-23)
+ * @param buffer Output buffer (must be at least 64 chars)
+ * @param bufferSize Size of the output buffer
+ * @return Number of characters written (excluding null terminator)
+ */
+int getGeometryName(int geometryIndex, char* buffer, int bufferSize) noexcept {
+    if (!buffer || bufferSize <= 0) return 0;
+
+    int coreType = 0;
+    int baseGeometry = 0;
+    decodeGeometryIndex(geometryIndex, coreType, baseGeometry);
+
+    const char* coreName = getCoreTypeName(coreType);
+    const char* baseName = getBaseGeometryName(baseGeometry);
+
+    int written = 0;
+
+    if (coreType == 0) {
+        // Base type: just use geometry name
+        for (int i = 0; baseName[i] != '\0' && written < bufferSize - 1; ++i) {
+            buffer[written++] = baseName[i];
+        }
+    } else {
+        // Compound name: "CoreType BaseGeometry"
+        for (int i = 0; coreName[i] != '\0' && written < bufferSize - 1; ++i) {
+            buffer[written++] = coreName[i];
+        }
+        if (written < bufferSize - 1) {
+            buffer[written++] = ' ';
+        }
+        for (int i = 0; baseName[i] != '\0' && written < bufferSize - 1; ++i) {
+            buffer[written++] = baseName[i];
+        }
+    }
+
+    buffer[written] = '\0';
+    return written;
+}
+
+} // namespace vib3

package/cpp/geometry/KleinBottle.cpp

@@ -0,0 +1,71 @@
+/**
+ * KleinBottle.cpp - Non-Orientable Surface in 4D
+ *
+ * Generates points on the Klein bottle immersed in R4.
+ *
+ * The Klein bottle cannot be embedded in R3 without self-intersection,
+ * but it can be properly embedded in R4. We use the standard
+ * figure-eight parametrization lifted into the 4th dimension:
+ *
+ *   x = (a + b*cos(v)) * cos(u)
+ *   y = (a + b*cos(v)) * sin(u)
+ *   z = b * sin(v) * cos(u/2)
+ *   w = b * sin(v) * sin(u/2)
+ *
+ * where u in [0, 2*pi), v in [0, 2*pi), and a > b > 0.
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <cmath>
+#include <numbers>
+
+namespace vib3 {
+
+/**
+ * Generate Klein bottle surface points in 4D.
+ *
+ * Uses the figure-eight immersion lifted to R4, which avoids
+ * the self-intersection that occurs in R3.
+ *
+ * @param resolution Number of subdivisions for each parameter (total points = resolution^2)
+ * @return Vector of 4D points on the Klein bottle surface
+ */
+std::vector<Vec4> generateKleinBottle(int resolution) noexcept {
+    if (resolution < 4) resolution = 4;
+
+    constexpr float twoPi = 2.0f * std::numbers::pi_v<float>;
+    constexpr float a = 2.0f;  // Major radius
+    constexpr float b = 1.0f;  // Minor radius
+
+    std::vector<Vec4> vertices;
+    vertices.reserve(static_cast<size_t>(resolution) * static_cast<size_t>(resolution));
+
+    for (int iu = 0; iu < resolution; ++iu) {
+        float u = twoPi * static_cast<float>(iu) / static_cast<float>(resolution);
+        float cosU = std::cos(u);
+        float sinU = std::sin(u);
+        float halfU = u * 0.5f;
+        float cosHalfU = std::cos(halfU);
+        float sinHalfU = std::sin(halfU);
+
+        for (int iv = 0; iv < resolution; ++iv) {
+            float v = twoPi * static_cast<float>(iv) / static_cast<float>(resolution);
+            float cosV = std::cos(v);
+            float sinV = std::sin(v);
+
+            float r = a + b * cosV;
+
+            vertices.emplace_back(
+                r * cosU,
+                r * sinU,
+                b * sinV * cosHalfU,
+                b * sinV * sinHalfU
+            );
+        }
+    }
+
+    return vertices;
+}
+
+} // namespace vib3

package/cpp/geometry/Sphere.cpp

@@ -0,0 +1,134 @@
+/**
+ * Sphere.cpp - 3-Sphere (S3) Surface Points
+ *
+ * Generates points on the 3-sphere (hypersphere) in 4D using
+ * Hopf coordinates (psi, theta, phi) parametrization.
+ */
+
+#include "math/Vec4.hpp"
+#include <vector>
+#include <cmath>
+#include <numbers>
+
+namespace vib3 {
+
+/**
+ * Generate points on S3 using Hopf coordinate parametrization.
+ *
+ * The 3-sphere is parametrized by three angles:
+ *   x = cos(psi) * cos(theta)
+ *   y = cos(psi) * sin(theta)
+ *   z = sin(psi) * cos(phi)
+ *   w = sin(psi) * sin(phi)
+ *
+ * where psi in [0, pi/2], theta in [0, 2pi), phi in [0, 2pi).
+ *
+ * @param resolution Controls sampling density. Total points = resolution^2 * resolution/2
+ * @return Vector of 4D points on the unit 3-sphere
+ */
+std::vector<Vec4> generateSphere(int resolution) noexcept {
+    if (resolution < 4) resolution = 4;
+
+    constexpr float pi = std::numbers::pi_v<float>;
+    constexpr float twoPi = 2.0f * std::numbers::pi_v<float>;
+    constexpr float halfPi = std::numbers::pi_v<float> / 2.0f;
+
+    // Number of steps for each angle
+    int psiSteps = resolution / 2;
+    int thetaSteps = resolution;
+    int phiSteps = resolution;
+
+    if (psiSteps < 2) psiSteps = 2;
+
+    std::vector<Vec4> vertices;
+    vertices.reserve(static_cast<size_t>(psiSteps) *
+                     static_cast<size_t>(thetaSteps) *
+                     static_cast<size_t>(phiSteps));
+
+    for (int ip = 0; ip < psiSteps; ++ip) {
+        float psi = halfPi * static_cast<float>(ip) / static_cast<float>(psiSteps - 1);
+        float cosPsi = std::cos(psi);
+        float sinPsi = std::sin(psi);
+
+        for (int it = 0; it < thetaSteps; ++it) {
+            float theta = twoPi * static_cast<float>(it) / static_cast<float>(thetaSteps);
+            float cosTheta = std::cos(theta);
+            float sinTheta = std::sin(theta);
+
+            for (int iphi = 0; iphi < phiSteps; ++iphi) {
+                float phi = twoPi * static_cast<float>(iphi) / static_cast<float>(phiSteps);
+                float cosPhi = std::cos(phi);
+                float sinPhi = std::sin(phi);
+
+                vertices.emplace_back(
+                    cosPsi * cosTheta,
+                    cosPsi * sinTheta,
+                    sinPsi * cosPhi,
+                    sinPsi * sinPhi
+                );
+            }
+        }
+    }
+
+    return vertices;
+}
+
+/**
+ * Generate points on S3 using the Hopf fibration structure.
+ *
+ * The Hopf fibration maps S3 -> S2, with each fiber being a great circle.
+ * This produces points organized along Hopf fibers, useful for
+ * visualizing the fibration structure.
+ *
+ * @param numFibers Number of base points on S2
+ * @param pointsPerFiber Number of points along each Hopf circle
+ * @return Vector of 4D points on the unit 3-sphere
+ */
+std::vector<Vec4> generateHopfFibration(int numFibers, int pointsPerFiber) noexcept {
+    if (numFibers < 4) numFibers = 4;
+    if (pointsPerFiber < 8) pointsPerFiber = 8;
+
+    constexpr float pi = std::numbers::pi_v<float>;
+    constexpr float twoPi = 2.0f * std::numbers::pi_v<float>;
+
+    // Distribute base points on S2 using a spiral
+    int sqrtFibers = static_cast<int>(std::sqrt(static_cast<float>(numFibers)));
+    if (sqrtFibers < 2) sqrtFibers = 2;
+
+    std::vector<Vec4> vertices;
+    vertices.reserve(static_cast<size_t>(numFibers) * static_cast<size_t>(pointsPerFiber));
+
+    for (int fi = 0; fi < sqrtFibers; ++fi) {
+        float baseTheta = pi * static_cast<float>(fi) / static_cast<float>(sqrtFibers - 1);
+
+        for (int fj = 0; fj < sqrtFibers; ++fj) {
+            float basePhi = twoPi * static_cast<float>(fj) / static_cast<float>(sqrtFibers);
+
+            // Base point on S2
+            float halfTheta = baseTheta * 0.5f;
+            float cosHalf = std::cos(halfTheta);
+            float sinHalf = std::sin(halfTheta);
+
+            // Trace the Hopf fiber (great circle in S3) for this base point
+            for (int p = 0; p < pointsPerFiber; ++p) {
+                float t = twoPi * static_cast<float>(p) / static_cast<float>(pointsPerFiber);
+
+                float cosT = std::cos(t);
+                float sinT = std::sin(t);
+                float cosBP = std::cos(basePhi + t);
+                float sinBP = std::sin(basePhi + t);
+
+                vertices.emplace_back(
+                    cosHalf * cosT,
+                    cosHalf * sinT,
+                    sinHalf * cosBP,
+                    sinHalf * sinBP
+                );
+            }
+        }
+    }
+
+    return vertices;
+}
+
+} // namespace vib3