@srsergio/taptapp-ar 1.0.88 → 1.0.90

package/src/core/detector/detector-lite.js

@@ -13,13 +13,15 @@
 import { FREAKPOINTS } from "./freak.js";
 import { gpuCompute } from "../utils/gpu-compute.js";
 import { computeLSH64, computeFullFREAK, packLSHIntoDescriptor } from "../utils/lsh-direct.js";
+import { generateBasis, projectDescriptor, compressToSignature } from "../matching/hdc.js";
+import { HDC_SEED } from "../protocol.js";
 
 const PYRAMID_MIN_SIZE = 4; // Restored to 4 for better small-scale detection
 // PYRAMID_MAX_OCTAVE ya no es necesario, el límite lo da PYRAMID_MIN_SIZE
 
 
-const NUM_BUCKETS_PER_DIMENSION = 10;
-const DEFAULT_MAX_FEATURES_PER_BUCKET = 8;
+const NUM_BUCKETS_PER_DIMENSION = 15; // Increased from 10 to 15 for better local detail
+const DEFAULT_MAX_FEATURES_PER_BUCKET = 12; // Increased from 8 to 12
 
 
 const ORIENTATION_NUM_BINS = 36;
@@ -46,6 +48,7 @@ export class DetectorLite {
         this.useGPU = options.useGPU !== undefined ? options.useGPU : globalUseGPU;
         // Protocol V6 (Moonshot): 64-bit LSH is the standard descriptor format
         this.useLSH = options.useLSH !== undefined ? options.useLSH : true;
+        this.useHDC = options.useHDC !== undefined ? options.useHDC : true; // Enabled by default for Moonshot
         this.maxFeaturesPerBucket = options.maxFeaturesPerBucket !== undefined ? options.maxFeaturesPerBucket : DEFAULT_MAX_FEATURES_PER_BUCKET;
 
         let numOctaves = 0;
@@ -96,6 +99,17 @@ export class DetectorLite {
         // 6. Calcular descriptores FREAK
         this._computeFreakDescriptors(prunedExtremas, pyramidImages);
 
+        // 7. 🚀 MOONSHOT: HDC Hyper-projection
+        if (this.useHDC) {
+            const hdcBasis = generateBasis(HDC_SEED, 1024);
+            for (const ext of prunedExtremas) {
+                if (ext.lsh) {
+                    const hv = projectDescriptor(ext.lsh, hdcBasis);
+                    ext.hdcSignature = compressToSignature(hv);
+                }
+            }
+        }
+
         // Convertir a formato de salida
         const featurePoints = prunedExtremas.map(ext => {
             const scale = Math.pow(2, ext.octave);
@@ -105,7 +119,9 @@ export class DetectorLite {
                 y: ext.y * scale + scale * 0.5 - 0.5,
                 scale: scale,
                 angle: ext.angle || 0,
-                descriptors: (this.useLSH && ext.lsh) ? ext.lsh : (ext.descriptors || [])
+                descriptors: (this.useLSH && ext.lsh) ? ext.lsh : (ext.descriptors || []),
+                hdcSignature: ext.hdcSignature || 0,
+                imageData: data // Pass source image for refinement
             };
         });
 
@@ -182,9 +198,10 @@ export class DetectorLite {
         for (let y = 0; y < height; y++) {
             const rowOffset = y * width;
 
-            // Left border
-            temp[rowOffset] = data[rowOffset] * (k0 + k1 + k2) + data[rowOffset + 1] * k1 + data[rowOffset + 2] * k0;
-            temp[rowOffset + 1] = data[rowOffset] * k1 + data[rowOffset + 1] * k2 + data[rowOffset + 2] * k1 + data[rowOffset + 3] * k0;
+            // Left border (Normalized)
+            const sumL0 = k0 + k1 + k2 + k1 + k0; // Ideal sum
+            temp[rowOffset] = (data[rowOffset] * (k0 + k1 + k2) + data[rowOffset + 1] * k1 + data[rowOffset + 2] * k0) * (1.0 / (k0 + k1 + k2));
+            temp[rowOffset + 1] = (data[rowOffset] * k1 + data[rowOffset + 1] * k2 + data[rowOffset + 2] * k1 + data[rowOffset + 3] * k0) * (1.0 / (k1 + k2 + k1 + k0));
 
             // Main loop - NO boundary checks
             for (let x = 2; x < width - 2; x++) {
@@ -192,18 +209,18 @@ export class DetectorLite {
                 temp[pos] = data[pos - 2] * k0 + data[pos - 1] * k1 + data[pos] * k2 + data[pos + 1] * k1 + data[pos + 2] * k0;
             }
 
-            // Right border
+            // Right border (Normalized)
             const r2 = rowOffset + width - 2;
             const r1 = rowOffset + width - 1;
-            temp[r2] = data[r2 - 2] * k0 + data[r2 - 1] * k1 + data[r2] * k2 + data[r1] * k1;
-            temp[r1] = data[r1 - 2] * k0 + data[r1 - 1] * k1 + data[r1] * (k2 + k1 + k0);
+            temp[r2] = (data[r2 - 2] * k0 + data[r2 - 1] * k1 + data[r2] * k2 + data[r1] * k1) * (1.0 / (k0 + k1 + k2 + k1));
+            temp[r1] = (data[r1 - 2] * k0 + data[r1 - 1] * k1 + data[r1] * (k2 + k1 + k0)) * (1.0 / (k0 + k1 + k2));
         }
 
         // Vertical pass - Speed optimized
         for (let x = 0; x < width; x++) {
-            // Top border
-            output[x] = temp[x] * (k0 + k1 + k2) + temp[x + width] * k1 + temp[x + width * 2] * k0;
-            output[x + width] = temp[x] * k1 + temp[x + width] * k2 + temp[x + width * 2] * k1 + temp[x + width * 3] * k0;
+            // Top border (Normalized)
+            output[x] = (temp[x] * (k0 + k1 + k2) + temp[x + width] * k1 + temp[x + width * 2] * k0) * (1.0 / (k0 + k1 + k2));
+            output[x + width] = (temp[x] * k1 + temp[x + width] * k2 + temp[x + width * 2] * k1 + temp[x + width * 3] * k0) * (1.0 / (k1 + k2 + k1 + k0));
 
             // Main loop - NO boundary checks
             for (let y = 2; y < height - 2; y++) {
@@ -211,11 +228,11 @@ export class DetectorLite {
                 output[p] = temp[p - width * 2] * k0 + temp[p - width] * k1 + temp[p] * k2 + temp[p + width] * k1 + temp[p + width * 2] * k0;
             }
 
-            // Bottom border
+            // Bottom border (Normalized)
             const b2 = (height - 2) * width + x;
             const b1 = (height - 1) * width + x;
-            output[b2] = temp[b2 - width * 2] * k0 + temp[b2 - width] * k1 + temp[b2] * k2 + temp[b1] * k1;
-            output[b1] = temp[b1 - width * 2] * k0 + temp[b1 - width] * k1 + temp[b1] * (k2 + k1 + k0);
+            output[b2] = (temp[b2 - width * 2] * k0 + temp[b2 - width] * k1 + temp[b2] * k2 + temp[b1] * k1) * (1.0 / (k0 + k1 + k2 + k1));
+            output[b1] = (temp[b1 - width * 2] * k0 + temp[b1 - width] * k1 + temp[b1] * (k2 + k1 + k0)) * (1.0 / (k0 + k1 + k2));
         }
 
         return { data: output, width, height };

package/src/core/estimation/estimate.js

@@ -1,67 +1,18 @@
-import { Matrix, inverse } from "ml-matrix";
-import { solveHomography } from "../utils/homography.js";
-
-// build world matrix with list of matching worldCoords|screenCoords
-//
-// Step 1. estimate homography with list of pairs
-// Ref: https://www.uio.no/studier/emner/matnat/its/TEK5030/v19/lect/lecture_4_3-estimating-homographies-from-feature-correspondences.pdf  (Basic homography estimation from points)
-//
-// Step 2. decompose homography into rotation and translation matrixes (i.e. world matrix)
-// Ref: can anyone provide reference?
+import { solvePosePnP } from "./pnp-solver.js";
+
+/**
+ * 🚀 MOONSHOT: Direct PnP Solver for AR
+ * 
+ * Instead of estimating a 2D Homography and decomposing it, 
+ * we solve for the 3D Pose [R|t] directly using the 
+ * Perspective-n-Point algorithm.
+ */
 const estimate = ({ screenCoords, worldCoords, projectionTransform }) => {
-  const Harray = solveHomography(
-    worldCoords.map((p) => [p.x, p.y]),
-    screenCoords.map((p) => [p.x, p.y]),
-  );
-  const H = new Matrix([
-    [Harray[0], Harray[1], Harray[2]],
-    [Harray[3], Harray[4], Harray[5]],
-    [Harray[6], Harray[7], Harray[8]],
-  ]);
-
-  const K = new Matrix(projectionTransform);
-  const KInv = inverse(K);
-
-  const _KInvH = KInv.mmul(H);
-  const KInvH = _KInvH.to1DArray();
-
-  const norm1 = Math.sqrt(KInvH[0] * KInvH[0] + KInvH[3] * KInvH[3] + KInvH[6] * KInvH[6]);
-  const norm2 = Math.sqrt(KInvH[1] * KInvH[1] + KInvH[4] * KInvH[4] + KInvH[7] * KInvH[7]);
-  const tnorm = (norm1 + norm2) / 2;
-
-  const rotate = [];
-  rotate[0] = KInvH[0] / norm1;
-  rotate[3] = KInvH[3] / norm1;
-  rotate[6] = KInvH[6] / norm1;
-
-  rotate[1] = KInvH[1] / norm2;
-  rotate[4] = KInvH[4] / norm2;
-  rotate[7] = KInvH[7] / norm2;
-
-  rotate[2] = rotate[3] * rotate[7] - rotate[6] * rotate[4];
-  rotate[5] = rotate[6] * rotate[1] - rotate[0] * rotate[7];
-  rotate[8] = rotate[0] * rotate[4] - rotate[1] * rotate[3];
-
-  const norm3 = Math.sqrt(rotate[2] * rotate[2] + rotate[5] * rotate[5] + rotate[8] * rotate[8]);
-  rotate[2] /= norm3;
-  rotate[5] /= norm3;
-  rotate[8] /= norm3;
-
-  // TODO: artoolkit has check_rotation() that somehow switch the rotate vector. not sure what that does. Can anyone advice?
-  // https://github.com/artoolkitx/artoolkit5/blob/5bf0b671ff16ead527b9b892e6aeb1a2771f97be/lib/SRC/ARICP/icpUtil.c#L215
-
-  const tran = [];
-  tran[0] = KInvH[2] / tnorm;
-  tran[1] = KInvH[5] / tnorm;
-  tran[2] = KInvH[8] / tnorm;
-
-  let initialModelViewTransform = [
-    [rotate[0], rotate[1], rotate[2], tran[0]],
-    [rotate[3], rotate[4], rotate[5], tran[1]],
-    [rotate[6], rotate[7], rotate[8], tran[2]],
-  ];
-
-  return initialModelViewTransform;
+  return solvePosePnP({
+    screenCoords,
+    worldCoords,
+    projectionTransform
+  });
 };
 
 export { estimate };

package/src/core/estimation/morph-refinement.js

@@ -0,0 +1,139 @@
+/**
+ * Morphological Refinement - "Active Edge Alignment"
+ * 
+ * This Moonshot algorithm snaps the projected target to the real image edges.
+ * It solves the "Small Box / Drift" problem by maximizing alignment with 
+ * local image gradients using a Spring-Mass optimization system.
+ */
+
+import { Matrix, SingularValueDecomposition } from "ml-matrix";
+
+export function refineWithMorphology({
+    imageData,
+    width,
+    height,
+    targetData,
+    initialH,
+    iterations = 3
+}) {
+    let currentH = [...initialH];
+
+    // 1. Boundary Points (The "Anchors" of our elastic malla)
+    const boundaryPoints = [];
+    const step = 0.05;
+    for (let i = 0; i <= 1.0; i += step) {
+        boundaryPoints.push({ x: i * targetData.w, y: 0 });
+        boundaryPoints.push({ x: i * targetData.w, y: targetData.h });
+        boundaryPoints.push({ x: 0, y: i * targetData.h });
+        boundaryPoints.push({ x: targetData.w, y: i * targetData.h });
+    }
+
+    for (let iter = 0; iter < iterations; iter++) {
+        const correspondences = [];
+
+        for (const pt of boundaryPoints) {
+            // Project
+            const w = currentH[6] * pt.x + currentH[7] * pt.y + currentH[8];
+            const sx = (currentH[0] * pt.x + currentH[1] * pt.y + currentH[2]) / w;
+            const sy = (currentH[3] * pt.x + currentH[4] * pt.y + currentH[5]) / w;
+
+            if (sx < 2 || sx >= width - 2 || sy < 2 || sy >= height - 2) continue;
+
+            // 2. Local Gradient Search (The "Pull" of the image)
+            const searchDist = 10;
+            let bestX = sx;
+            let bestY = sy;
+            let maxGrad = -1;
+
+            for (let dy = -searchDist; dy <= searchDist; dy += 2) {
+                for (let dx = -searchDist; dx <= searchDist; dx += 2) {
+                    const nx = Math.floor(sx + dx);
+                    const ny = Math.floor(sy + dy);
+
+                    const idx = ny * width + nx;
+                    // Sobel-like gradient magnitude
+                    const gx = imageData[idx + 1] - imageData[idx - 1];
+                    const gy = imageData[idx + width] - imageData[idx - width];
+                    const grad = gx * gx + gy * gy;
+
+                    if (grad > maxGrad) {
+                        maxGrad = grad;
+                        bestX = nx;
+                        bestY = ny;
+                    }
+                }
+            }
+
+            if (maxGrad > 500) {
+                correspondences.push({
+                    src: pt,
+                    dst: { x: bestX, y: bestY },
+                    weight: Math.min(1.0, maxGrad / 15000)
+                });
+            }
+        }
+
+        if (correspondences.length < 10) break;
+
+        // 3. Solve for best Homography using SVD
+        const nextH = solveDLTWeight(correspondences);
+        if (nextH) {
+            // Soft-Update (Momentum)
+            for (let i = 0; i < 9; i++) {
+                currentH[i] = currentH[i] * 0.5 + nextH[i] * 0.5;
+            }
+        }
+    }
+
+    return currentH;
+}
+
+/**
+ * Direct Linear Transform with Weights
+ */
+function solveDLTWeight(pairs) {
+    const n = pairs.length;
+    const A = new Matrix(n * 2, 9);
+
+    for (let i = 0; i < n; i++) {
+        const { src, dst, weight: w } = pairs[i];
+        const x = src.x;
+        const y = src.y;
+        const xp = dst.x;
+        const yp = dst.y;
+
+        // Row 1
+        A.set(i * 2, 0, 0);
+        A.set(i * 2, 1, 0);
+        A.set(i * 2, 2, 0);
+        A.set(i * 2, 3, -x * w);
+        A.set(i * 2, 4, -y * w);
+        A.set(i * 2, 5, -w);
+        A.set(i * 2, 6, yp * x * w);
+        A.set(i * 2, 7, yp * y * w);
+        A.set(i * 2, 8, yp * w);
+
+        // Row 2
+        A.set(i * 2 + 1, 0, x * w);
+        A.set(i * 2 + 1, 1, y * w);
+        A.set(i * 2 + 1, 2, w);
+        A.set(i * 2 + 1, 3, 0);
+        A.set(i * 2 + 1, 4, 0);
+        A.set(i * 2 + 1, 5, 0);
+        A.set(i * 2 + 1, 6, -xp * x * w);
+        A.set(i * 2 + 1, 7, -xp * y * w);
+        A.set(i * 2 + 1, 8, -xp * w);
+    }
+
+    try {
+        const svd = new SingularValueDecomposition(A);
+        const V = svd.rightSingularVectors;
+        // Last column of V is the solution
+        const h = V.getColumn(8);
+        // Normalize H[8] to 1
+        const scale = 1.0 / h[8];
+        return h.map(v => v * scale);
+    } catch (e) {
+        return null;
+    }
+}

package/src/core/estimation/pnp-solver.js

@@ -0,0 +1,131 @@
+/**
+ * Direct PnP (Perspective-n-Point) Solver for Planar Targets
+ * 
+ * This Moonshot algorithm ignores octave-relative scales and works 
+ * purely in Physical World Units. It uses the Camera Matrix (K) 
+ * to deduce the real-world distance (Z).
+ */
+
+import { Matrix, SingularValueDecomposition } from "ml-matrix";
+
+export function solvePosePnP({
+    screenCoords,
+    worldCoords,
+    projectionTransform
+}) {
+    const K = new Matrix(projectionTransform);
+    const n = screenCoords.length;
+
+    // 1. Build the DLT matrix for Pose (Directly estimating [R|t])
+    // We assume worldCoords are [X, Y, 0]
+    // Eq: x = K * [R|t] * X
+    // K^-1 * x = [r1 r2 t] * [X Y 1]^T
+
+    const KI = Inverse3x3(projectionTransform);
+
+    const A = new Matrix(n * 2, 9);
+    for (let i = 0; i < n; i++) {
+        const sci = screenCoords[i];
+        const wci = worldCoords[i];
+
+        // Normalized camera coordinates
+        const nx = KI[0] * sci.x + KI[1] * sci.y + KI[2];
+        const ny = KI[3] * sci.x + KI[4] * sci.y + KI[5];
+        const nz = KI[6] * sci.x + KI[7] * sci.y + KI[8];
+        const unx = nx / nz;
+        const uny = ny / nz;
+
+        // DLT equations for [r11 r12 r21 r22 r31 r32 t1 t2 t3]
+        const X = wci.x;
+        const Y = wci.y;
+
+        // Row 1: X*r11 + Y*r12 + t1 - unx*(X*r31 + Y*r32 + t3) = 0
+        A.set(i * 2, 0, X);
+        A.set(i * 2, 1, Y);
+        A.set(i * 2, 2, 1);
+        A.set(i * 2, 3, 0);
+        A.set(i * 2, 4, 0);
+        A.set(i * 2, 5, 0);
+        A.set(i * 2, 6, -unx * X);
+        A.set(i * 2, 7, -unx * Y);
+        A.set(i * 2, 8, -unx);
+
+        // Row 2: X*r21 + Y*r22 + t2 - uny*(X*r31 + Y*r32 + t3) = 0
+        A.set(i * 2 + 1, 0, 0);
+        A.set(i * 2 + 1, 1, 0);
+        A.set(i * 2 + 1, 2, 0);
+        A.set(i * 2 + 1, 3, X);
+        A.set(i * 2 + 1, 4, Y);
+        A.set(i * 2 + 1, 5, 1);
+        A.set(i * 2 + 1, 6, -uny * X);
+        A.set(i * 2 + 1, 7, -uny * Y);
+        A.set(i * 2 + 1, 8, -uny);
+    }
+
+    // Solve via SVD
+    const svd = new SingularValueDecomposition(A);
+    const V = svd.rightSingularVectors;
+    const sol = V.getColumn(8); // last column
+
+    // 3. Extract r1, r2 and t from the DLT solution
+    // Standard DLT has an overall sign ambiguity. We force sol[8] (t3) to be positive.
+    if (sol[8] < 0) {
+        for (let i = 0; i < 9; i++) sol[i] = -sol[i];
+    }
+
+    const r1_raw = [sol[0], sol[3], sol[6]];
+    const r2_raw = [sol[1], sol[4], sol[7]];
+    const t_raw = [sol[2], sol[5], sol[8]];
+
+    const scale1 = Math.sqrt(r1_raw[0] ** 2 + r1_raw[1] ** 2 + r1_raw[2] ** 2);
+    const scale2 = Math.sqrt(r2_raw[0] ** 2 + r2_raw[1] ** 2 + r2_raw[2] ** 2);
+    const scale = (scale1 + scale2) / 2;
+
+    // 4. Construct Rotation Matrix and orthogonalize via SVD
+    const R_approx = new Matrix([
+        [r1_raw[0] / scale1, r2_raw[0] / scale2, 0],
+        [r1_raw[1] / scale1, r2_raw[1] / scale2, 0],
+        [r1_raw[2] / scale1, r2_raw[2] / scale2, 0]
+    ]);
+
+    // R3 = R1 x R2
+    R_approx.set(0, 2, R_approx.get(1, 0) * R_approx.get(2, 1) - R_approx.get(2, 0) * R_approx.get(1, 1));
+    R_approx.set(1, 2, R_approx.get(2, 0) * R_approx.get(0, 1) - R_approx.get(0, 0) * R_approx.get(2, 1));
+    R_approx.set(2, 2, R_approx.get(0, 0) * R_approx.get(1, 1) - R_approx.get(1, 0) * R_approx.get(0, 1));
+
+    const svdRot = new SingularValueDecomposition(R_approx);
+    const U = svdRot.leftSingularVectors;
+    const Vrot = svdRot.rightSingularVectors;
+    let R = U.mmul(Vrot.transpose());
+
+    const getDet3 = (m) => {
+        return m.get(0, 0) * (m.get(1, 1) * m.get(2, 2) - m.get(1, 2) * m.get(2, 1)) -
+            m.get(0, 1) * (m.get(1, 0) * m.get(2, 2) - m.get(1, 2) * m.get(2, 0)) +
+            m.get(0, 2) * (m.get(1, 0) * m.get(2, 1) - m.get(1, 1) * m.get(2, 0));
+    };
+
+    if (getDet3(R) < 0) {
+        const U_mat = U.clone();
+        for (let i = 0; i < 3; i++) U_mat.set(i, 2, -U_mat.get(i, 2));
+        R = U_mat.mmul(Vrot.transpose());
+    }
+
+    return [
+        [R.get(0, 0), R.get(0, 1), R.get(0, 2), t_raw[0] / scale],
+        [R.get(1, 0), R.get(1, 1), R.get(1, 2), t_raw[1] / scale],
+        [R.get(2, 0), R.get(2, 1), R.get(2, 2), t_raw[2] / scale]
+    ];
+}
+
+function Inverse3x3(m) {
+    const k00 = m[0][0], k01 = m[0][1], k02 = m[0][2];
+    const k10 = m[1][0], k11 = m[1][1], k12 = m[1][2];
+    const k20 = m[2][0], k21 = m[2][1], k22 = m[2][2];
+    const det = k00 * (k11 * k22 - k21 * k12) - k01 * (k10 * k22 - k12 * k20) + k02 * (k10 * k21 - k11 * k20);
+    const invDet = 1.0 / det;
+    return [
+        (k11 * k22 - k12 * k21) * invDet, (k02 * k21 - k01 * k22) * invDet, (k01 * k12 - k02 * k11) * invDet,
+        (k12 * k20 - k10 * k22) * invDet, (k00 * k22 - k02 * k20) * invDet, (k10 * k02 - k00 * k12) * invDet,
+        (k10 * k21 - k11 * k20) * invDet, (k20 * k01 - k21 * k00) * invDet, (k00 * k11 - k10 * k01) * invDet
+    ];
+}

package/src/core/input-loader.js

@@ -38,14 +38,33 @@ class InputLoader {
 
       const isInputRotated = input.width === this.height && input.height === this.width;
 
+      const inputW = isInputRotated ? input.height : input.width;
+      const inputH = isInputRotated ? input.width : input.height;
+      const inputAspect = inputW / inputH;
+      const canvasAspect = this.width / this.height;
+
+      let sx = 0, sy = 0, sw = inputW, sh = inputH;
+
+      if (inputAspect > canvasAspect) {
+        // Input is wider than canvas - crop sides
+        sw = inputH * canvasAspect;
+        sx = (inputW - sw) / 2;
+      } else if (inputAspect < canvasAspect) {
+        // Input is taller than canvas - crop top/bottom
+        sh = inputW / canvasAspect;
+        sy = (inputH - sh) / 2;
+      }
+
       if (isInputRotated) {
         this.context.save();
         this.context.translate(this.width / 2, this.height / 2);
         this.context.rotate(Math.PI / 2);
-        this.context.drawImage(input, -input.width / 2, -input.height / 2);
+        // Map source crop (relative to rotated input)
+        // Since input is already rotated, we crop based on the rotated dimensions
+        this.context.drawImage(input, sx, sy, sw, sh, -this.height / 2, -this.width / 2, this.height, this.width);
         this.context.restore();
       } else {
-        this.context.drawImage(input, 0, 0, this.width, this.height);
+        this.context.drawImage(input, sx, sy, sw, sh, 0, 0, this.width, this.height);
       }
 
       const imageData = this.context.getImageData(0, 0, this.width, this.height);

package/src/core/matching/hdc.ts

@@ -0,0 +1,117 @@
+/**
+ * Hyperdimensional Computing (HDC) Core for AR
+ * 
+ * Provides ultra-fast, ultra-compressed feature matching using 
+ * High-Dimensional Random Vectors.
+ */
+
+export const HDC_DIMENSION = 1024; // bits
+export const HDC_WORDS = HDC_DIMENSION / 32;
+
+/**
+ * Deterministic Random Number Generator (PCG-like)
+ */
+class PRNG {
+    state: number;
+    constructor(seed: number) {
+        this.state = seed;
+    }
+    next() {
+        this.state = (this.state * 1664525 + 1013904223) >>> 0;
+        return this.state / 0xFFFFFFFF;
+    }
+}
+
+/**
+ * Generates a deterministic basis of Hypervectors
+ */
+export function generateBasis(seed: number, count: number): Uint32Array[] {
+    const prng = new PRNG(seed);
+    const basis: Uint32Array[] = [];
+    for (let i = 0; i < count; i++) {
+        const hv = new Uint32Array(HDC_WORDS);
+        for (let j = 0; j < HDC_WORDS; j++) {
+            hv[j] = (prng.next() * 0xFFFFFFFF) >>> 0;
+        }
+        basis.push(hv);
+    }
+    return basis;
+}
+
+/**
+ * Projects a 64-bit descriptor into the Hyperdimensional Space
+ * Uses "Random Projection" logic (Locality Sensitive Hashing in HDC)
+ */
+export function projectDescriptor(desc: Uint32Array, basis: Uint32Array[]): Uint32Array {
+    const result = new Uint32Array(HDC_WORDS);
+
+    // For each bit in the HDC space
+    for (let i = 0; i < HDC_DIMENSION; i++) {
+        const wordIdx = i >>> 5;
+        const bitIdx = i & 31;
+
+        // This is a simplified random projection
+        // In a real HDC system, we'd use more complex binding
+        // But for Vanilla JS performance, we use bitwise voting
+        let sum = 0;
+        const b = basis[i % basis.length];
+
+        // Dot product between descriptor and basis vector (subset)
+        // desc[0] and desc[1] are the 64 bits
+        for (let j = 0; j < 2; j++) {
+            sum += popcount(desc[j] & b[j]);
+        }
+
+        if (sum > 16) { // Threshold for "firing"
+            result[wordIdx] |= (1 << bitIdx);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Compresses an HDC vector into an "Ultra-Short Signature" (32 bits)
+ * This allows storing 1000 points in just 4KB of descriptors.
+ */
+export function compressToSignature(hv: Uint32Array): number {
+    // FNV-1a Hash for robust 32-bit compression
+    let h1 = 0x811c9dc5;
+    for (let i = 0; i < hv.length; i++) {
+        h1 ^= hv[i];
+        h1 = Math.imul(h1, 0x01000193);
+    }
+    return h1 >>> 0;
+}
+
+function popcount(n: number): number {
+    n = n - ((n >> 1) & 0x55555555);
+    n = (n & 0x33333333) + ((n >> 2) & 0x33333333);
+    return (((n + (n >> 4)) & 0x0F0F0F0F) * 0x01010101) >> 24;
+}
+
+/**
+ * Bundles multiple points into a single Global Hypervector (The "Image DNA")
+ * This allows checking if an image is present with ONE vector comparison.
+ */
+export function bundle(hvs: Uint32Array[]): Uint32Array {
+    const global = new Uint32Array(HDC_WORDS);
+    const threshold = hvs.length / 2;
+    const counters = new Uint16Array(HDC_DIMENSION);
+
+    for (const hv of hvs) {
+        for (let i = 0; i < HDC_DIMENSION; i++) {
+            if (hv[i >>> 5] & (1 << (i & 31))) {
+                counters[i]++;
+            }
+        }
+    }
+
+    for (let i = 0; i < HDC_DIMENSION; i++) {
+        if (counters[i] > threshold) {
+            global[i >>> 5] |= (1 << (i & 31));
+        }
+    }
+
+    return global;
+}