@pirireis/webglobeplugins 0.15.2-3.alpha → 0.15.3-alpha

package/Math/arc-generate-points copy.js

@@ -0,0 +1,366 @@
+// TODO: Delete this file if it is not needed anymore.
+// import { normilze as vec3Normalize, dot as vec3Dot, cross as vec3Cross, scale as vec3Scale, add as vec3Add, sub as vec3Sub } from './vec3';
+// --- Utility Functions for 3D Vector Operations ---
+/**
+ * Normalizes a 3D vector to unit length.
+ * @param v The input vector.
+ * @returns The normalized vector. Returns [0,0,0] if the input vector is a zero vector.
+ */
+function vec3Normalize(v) {
+    const len = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+    if (len < 1e-9) { // Use a small epsilon to handle near-zero vectors
+        return [0, 0, 0];
+    }
+    return [v[0] / len, v[1] / len, v[2] / len];
+}
+/**
+ * Calculates the dot product of two 3D vectors.
+ * @param v1 The first vector.
+ * @param v2 The second vector.
+ * @returns The dot product.
+ */
+function vec3Dot(v1, v2) {
+    return v1[0] * v2[0] + v1[1] * v2[1] + v1[2] * v2[2];
+}
+/**
+ * Calculates the cross product of two 3D vectors.
+ * @param v1 The first vector.
+ * @param v2 The second vector.
+ * @returns The cross product vector.
+ */
+function vec3Cross(v1, v2) {
+    return [
+        v1[1] * v2[2] - v1[2] * v2[1],
+        v1[2] * v2[0] - v1[0] * v2[2],
+        v1[0] * v2[1] - v1[1] * v2[0]
+    ];
+}
+/**
+ * Scales a 3D vector by a scalar.
+ * @param v The input vector.
+ * @param s The scalar value.
+ * @returns The scaled vector.
+ */
+function vec3Scale(v, s) {
+    return [v[0] * s, v[1] * s, v[2] * s];
+}
+/**
+ * Adds two 3D vectors.
+ * @param v1 The first vector.
+ * @param v2 The second vector.
+ * @returns The resulting vector.
+ */
+function vec3Add(v1, v2) {
+    return [v1[0] + v2[0], v1[1] + v2[1], v1[2] + v2[2]];
+}
+/**
+ * Subtracts the second 3D vector from the first.
+ * @param v1 The first vector.
+ * @param v2 The second vector.
+ * @returns The resulting vector.
+ */
+function vec3Sub(v1, v2) {
+    return [v1[0] - v2[0], v1[1] - v2[1], v1[2] - v2[2]];
+}
+/**
+ * Clamps a numerical value within a specified range.
+ * @param value The value to clamp.
+ * @param min The minimum allowed value.
+ * @param max The maximum allowed value.
+ * @returns The clamped value.
+ */
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, max));
+}
+function vec3Distance(v1, v2) {
+    const dx = v1[0] - v2[0];
+    const dy = v1[1] - v2[1];
+    const dz = v1[2] - v2[2];
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+/**
+ * Rotates a vector around a given axis by a specified angle using Rodrigues' rotation formula.
+ * The axis must be a unit vector for correct results.
+ * @param v The vector to rotate.
+ * @param axis The unit axis of rotation.
+ * @param angle The angle of rotation in radians.
+ * @returns The rotated vector.
+ */
+function rotateVector(v, axis, angle) {
+    const cosAngle = Math.cos(angle);
+    const sinAngle = Math.sin(angle);
+    const oneMinusCos = 1.0 - cosAngle;
+    const dotAxisV = vec3Dot(axis, v);
+    const crossAxisV = vec3Cross(axis, v);
+    // Rodrigues' rotation formula:
+    // v' = v * cos(angle) + (axis x v) * sin(angle) + axis * (axis . v) * (1 - cos(angle))
+    const term1 = vec3Scale(v, cosAngle);
+    const term2 = vec3Scale(crossAxisV, sinAngle);
+    const term3 = vec3Scale(axis, dotAxisV * oneMinusCos);
+    return vec3Add(vec3Add(term1, term2), term3);
+}
+/**
+ * Solves a quadratic equation Ax^2 + Bx + C = 0 for x, returning a root within a specified range.
+ * Handles linear cases (A approx 0) and multiple roots, selecting the most appropriate one for CDF inversion.
+ * @param a Coefficient A.
+ * @param b Coefficient B.
+ * @param c Coefficient C.
+ * @param minVal The minimum expected value for the root.
+ * @param maxVal The maximum expected value for the root.
+ * @returns The selected root within the range, or null if no valid real root.
+ */
+function solveQuadratic(a, b, c, minVal, maxVal) {
+    const epsilon = 1e-12; // Small value for floating point comparisons
+    // Case 1: Linear equation (A is close to zero)
+    if (Math.abs(a) < epsilon) {
+        if (Math.abs(b) < epsilon) {
+            // Both A and B are zero. If C is also zero, infinitely many solutions, pick minVal.
+            // Otherwise, no solutions.
+            return Math.abs(c) < epsilon ? minVal : null;
+        }
+        const x = -c / b;
+        // Check if the linear solution is within the expected range
+        return (x >= minVal - epsilon && x <= maxVal + epsilon) ? x : null;
+    }
+    // Case 2: Quadratic equation
+    const discriminant = b * b - 4 * a * c;
+    if (discriminant < -epsilon) { // No real roots (discriminant is significantly negative)
+        console.log("No real roots for the quadratic equation.");
+        return null;
+    }
+    if (discriminant < epsilon) { // One real root (discriminant is close to zero)
+        const x = -b / (2 * a);
+        return (x >= minVal - epsilon && x <= maxVal + epsilon) ? x : null;
+    }
+    // Case 3: Two distinct real roots
+    const sqrtDisc = Math.sqrt(discriminant);
+    const x1 = (-b + sqrtDisc) / (2 * a);
+    const x2 = (-b - sqrtDisc) / (2 * a);
+    const validX1 = (x1 >= minVal - epsilon && x1 <= maxVal + epsilon);
+    const validX2 = (x2 >= minVal - epsilon && x2 <= maxVal + epsilon);
+    if (validX1 && validX2) {
+        // If both roots are valid, pick the one that is logically correct for CDF inversion.
+        // For an increasing CDF, we generally want the smallest valid non-negative root.
+        return Math.min(x1, x2);
+    }
+    else if (validX1) {
+        return x1;
+    }
+    else if (validX2) {
+        return x2;
+    }
+    else {
+        return null; // No valid roots within the range
+    }
+}
+// --- Main Function for Arc Point Generation ---
+/**
+ * Generates points on the shortest arc between p0 and p1 on a unit sphere.
+ * The arc is formed by rotating p0 around axisA. The density of points
+ * is higher closer to the attractionPoint.
+ *
+ * @param p0 The starting point of the arc (will be normalized).
+ * @param p1 The ending point of the arc (will be normalized).
+ * @param axisA The axis of rotation (will be normalized).
+ * @param attractionPoint The point on the unit sphere that attracts sampled points (will be normalized).
+ * @param pointCount The total number of points to generate on the arc, including p0 and p1.
+ * @param strength Controls the density bias. A value of 0 means uniform sampling.
+ * Higher positive values (e.g., 1 to 10) result in stronger attraction.
+ * @returns An array of `Vec3` representing the deterministically sampled points on the arc.
+ */
+export function generateArcPoints(p0, p1, axisA, attractionPoint, pointCount, strength) {
+    const sampledPoints = [];
+    const epsilon = 1e-7; // General epsilon for vector comparisons
+    // 1. Normalize all input vectors
+    let nP0 = vec3Normalize(p0);
+    let nP1 = vec3Normalize(p1);
+    let nAxisA = vec3Normalize(axisA);
+    let nAttractionPoint = vec3Normalize(attractionPoint);
+    // Handle edge cases for pointCount
+    if (pointCount < 1) {
+        return sampledPoints;
+    }
+    if (pointCount === 1) {
+        sampledPoints.push(nP0);
+        return sampledPoints;
+    }
+    // 2. Determine the total rotation angle required to go from p0 to p1 around axisA
+    // Project p0 and p1 onto the plane perpendicular to axisA
+    const p0Projected = vec3Sub(nP0, vec3Scale(nAxisA, vec3Dot(nP0, nAxisA)));
+    const p1Projected = vec3Sub(nP1, vec3Scale(nAxisA, vec3Dot(nP1, nAxisA)));
+    const lenP0Proj = Math.sqrt(vec3Dot(p0Projected, p0Projected));
+    const lenP1Proj = Math.sqrt(vec3Dot(p1Projected, p1Projected));
+    // Handle cases where p0 or p1 are colinear with the rotation axis
+    if (lenP0Proj < epsilon || lenP1Proj < epsilon) {
+        // If start and end points are effectively the same (on or very near the axis)
+        if (Math.abs(vec3Dot(nP0, nP1) - 1.0) < epsilon) {
+            for (let i = 0; i < pointCount; i++) {
+                sampledPoints.push(nP0); // Return identical points as no meaningful arc exists
+            }
+            return sampledPoints;
+        }
+        else {
+            console.warn("generateArcPoints: p0 or p1 is colinear with axisA. Cannot form a valid arc by rotation around axisA to reach p1. Falling back to linear interpolation.");
+            // Fallback: simple linear interpolation and normalize
+            for (let i = 0; i < pointCount; i++) {
+                const t = i / (pointCount - 1);
+                const interpolated = vec3Add(vec3Scale(nP0, (1 - t)), vec3Scale(nP1, t));
+                sampledPoints.push(vec3Normalize(interpolated));
+            }
+            return sampledPoints;
+        }
+    }
+    const nP0Projected = vec3Normalize(p0Projected);
+    const nP1Projected = vec3Normalize(p1Projected);
+    // Calculate total rotation angle using atan2 for a signed angle
+    const crossProj = vec3Cross(nP0Projected, nP1Projected);
+    const totalRotationAngle = Math.atan2(vec3Dot(crossProj, nAxisA), vec3Dot(nP0Projected, nP1Projected));
+    // If total rotation angle is negligible, all points are essentially p0
+    if (Math.abs(totalRotationAngle) < epsilon) {
+        for (let i = 0; i < pointCount; i++) {
+            sampledPoints.push(nP0);
+        }
+        return sampledPoints;
+    }
+    // 3. Find alpha_A: the angle parameter (from p0) where the arc point is closest to attractionPoint
+    // We search over `t` from 0 to 1, and map to actual rotation angles.
+    let alpha_A = 0.0; // This will be the actual rotation angle
+    let minAngleToAttraction = Math.PI; // Initialize with max possible angle
+    // TODO: USE GEOMETRY INSTEAD OF MARKOV CHOICE
+    const testSteps = 1000; // Granularity for finding alpha_A
+    for (let i = 0; i <= testSteps; i++) {
+        const t_test = i / testSteps; // Normalized parameter [0, 1]
+        const currentAlpha = totalRotationAngle * t_test; // Actual rotation angle
+        const pArcTest = rotateVector(nP0, nAxisA, currentAlpha); // Point on arc
+        const dotProduct = clamp(vec3Dot(pArcTest, nAttractionPoint), -1.0, 1.0);
+        const currentAngle = Math.acos(dotProduct);
+        if (currentAngle < minAngleToAttraction) {
+            minAngleToAttraction = currentAngle;
+            alpha_A = currentAlpha;
+        }
+    }
+    // minAngleToAttraction = 0.0;
+    console.log("generated alpha_A:", alpha_A, "minAngleToAttraction:", minAngleToAttraction);
+    // 4. Define the PDF parameters (for normalized parameter t in [0,1])
+    // The density function for 't' (normalized angle from 0 to 1)
+    const minDensity = 1.0;
+    // Strength ensures positive density. Higher strength gives more pronounced peak.
+    const maxDensity = minDensity + Math.max(0, strength);
+    // Normalize alpha_A to the [0, 1] range for the PDF/CDF calculations
+    // This represents the peak position (t_peak) within the normalized parameter space.
+    const alpha_A_normalized = totalRotationAngle !== 0 ? clamp(alpha_A / totalRotationAngle, 0, 1) : 0;
+    // Normalization constant for the PDF (integral over [0,1] must be 1)
+    // Area of trapezoid = 0.5 * (base1 + base2) * height
+    // In our case, the "bases" are minDensity and maxDensity, "height" is 1 (the t-interval length)
+    const pdfArea = 0.5 * (minDensity + maxDensity);
+    const pdfNormalizationConstant = 1.0 / pdfArea;
+    // Calculate CDF value at the peak point (alpha_A_normalized)
+    // This splits the CDF into two regions for the quadratic solver
+    const cdfAtAlphaA_norm = pdfNormalizationConstant * (minDensity * alpha_A_normalized + 0.5 * (maxDensity - minDensity) * alpha_A_normalized);
+    // 5. Generate deterministic points using inverse transform sampling
+    for (let i = 0; i < pointCount; i++) {
+        // Generate uniformly spaced values `u` in [0, 1]
+        const u = i / (pointCount - 1);
+        let t_sampled; // This will be the sampled normalized parameter [0, 1]
+        if (u <= cdfAtAlphaA_norm) {
+            // Case 1: The sampled point falls in the first part of the PDF (0 to alpha_A_normalized)
+            // F(t) = normConst * (minDensity * t + 0.5 * (maxDensity - minDensity) / alpha_A_normalized * t^2)
+            // Rearrange to A*t^2 + B*t + C = 0 for solving:
+            const A = (alpha_A_normalized !== 0) ? pdfNormalizationConstant * 0.5 * (maxDensity - minDensity) / alpha_A_normalized : 0;
+            const B = pdfNormalizationConstant * minDensity;
+            const C = -u;
+            const result = solveQuadratic(A, B, C, 0, alpha_A_normalized);
+            // Fallback for unexpected null (e.g., numerical issues)
+            t_sampled = result !== null ? result : (u / (cdfAtAlphaA_norm || epsilon)) * alpha_A_normalized;
+        }
+        else {
+            // Case 2: The sampled point falls in the second part of the PDF (alpha_A_normalized to 1)
+            // F(t) - cdfAtAlphaA_norm = normConst * [ maxDensity * (t - alpha_A_normalized) - 0.5 * (maxDensity - minDensity) / (1 - alpha_A_normalized) * (t - alpha_A_normalized)^2 ]
+            // Let x = t - alpha_A_normalized. Solve for x: A'*x^2 + B'*x + C' = 0
+            const rangeAfterA = 1 - alpha_A_normalized;
+            const A_prime = (rangeAfterA !== 0) ? -pdfNormalizationConstant * 0.5 * (maxDensity - minDensity) / rangeAfterA : 0;
+            const B_prime = pdfNormalizationConstant * maxDensity;
+            const C_prime = -(u - cdfAtAlphaA_norm);
+            const result_x = solveQuadratic(A_prime, B_prime, C_prime, 0, rangeAfterA);
+            // Fallback for unexpected null
+            t_sampled = (result_x !== null ? alpha_A_normalized + result_x :
+                alpha_A_normalized + (u - cdfAtAlphaA_norm) / ((1 - cdfAtAlphaA_norm) || epsilon) * rangeAfterA);
+        }
+        // Ensure t_sampled is within [0, 1] due to potential float inaccuracies
+        t_sampled = clamp(t_sampled, 0, 1);
+        // Convert the normalized parameter 't_sampled' back to the actual rotation angle
+        const actualRotationAngle = totalRotationAngle * t_sampled;
+        // Rotate the starting point p0 by this angle around axisA to get the final point
+        const currentPoint = rotateVector(nP0, nAxisA, actualRotationAngle);
+        sampledPoints.push(currentPoint);
+    }
+    return sampledPoints;
+}
+// --- Example Usage (for demonstration and testing) ---
+// Example 1: Basic arc, attraction point in the middle
+const p0_ex1 = [1, 0, 0];
+const p1_ex1 = [0, 1, 0]; // 90 deg rotation around Z-axis
+const axisA_ex1 = [0, 0, 1];
+const attractionPoint_ex1 = [Math.sqrt(0.5), Math.sqrt(0.5), 0]; // On the arc, middle of P0-P1
+const numPoints_ex1 = 50;
+const strength_ex1 = 100.0; // Strong attraction
+console.log("--- Example 1: Attraction point in the middle of the arc ---");
+const points1 = generateArcPoints(p0_ex1, p1_ex1, axisA_ex1, attractionPoint_ex1, numPoints_ex1, strength_ex1);
+console.log(`Generated ${points1.length} points.`);
+// To observe concentration, you might visualize these points or calculate their 't' parameter distribution.
+// For console output, let's print a few:
+console.log("First 5 points:", points1.slice(0, 5).map(p => p.map(coord => coord.toFixed(4))));
+console.log("Last 5 points:", points1.slice(-5).map(p => p.map(coord => coord.toFixed(4))));
+// Expected: Points should be denser around [0.707, 0.707, 0]
+const sequentialDistances1 = points1.map((p, i) => {
+    if (i === 0)
+        return 0; // Skip the first point
+    return vec3Distance(points1[i - 1], p);
+});
+console.log("Sequential distances between points (should be roughly equal for uniform distribution):", sequentialDistances1.map(d => d.toFixed(4)));
+// Example 2: Attraction point near p0
+const p0_ex2 = [1, 0, 0];
+const p1_ex2 = [0, 1, 0];
+const axisA_ex2 = [0, 0, 1];
+const attractionPoint_ex2 = [0.99, 0.01, 0]; // Very close to P0
+const numPoints_ex2 = 50;
+const strength_ex2 = 10.0; // Very strong attraction
+console.log("\n--- Example 2: Attraction point near the start (p0) ---");
+const points2 = generateArcPoints(p0_ex2, p1_ex2, axisA_ex2, attractionPoint_ex2, numPoints_ex2, strength_ex2);
+console.log(`Generated ${points2.length} points.`);
+console.log("First 5 points:", points2.slice(0, 5).map(p => p.map(coord => coord.toFixed(4))));
+console.log("Last 5 points:", points2.slice(-5).map(p => p.map(coord => coord.toFixed(4))));
+// Expected: Points should be denser near [1, 0, 0]
+// Example 3: Attraction point away from the arc (expect less concentration)
+const p0_ex3 = [1, 0, 0];
+const p1_ex3 = [0, 1, 0];
+const axisA_ex3 = [0, 0, 1];
+const attractionPoint_ex3 = [0, 0, 1]; // North pole, away from the XY plane arc
+const numPoints_ex3 = 50;
+const strength_ex3 = 5.0;
+console.log("\n--- Example 3: Attraction point away from the arc ---");
+const points3 = generateArcPoints(p0_ex3, p1_ex3, axisA_ex3, attractionPoint_ex3, numPoints_ex3, strength_ex3);
+console.log(`Generated ${points3.length} points.`);
+console.log("First 5 points:", points3.slice(0, 5).map(p => p.map(coord => coord.toFixed(4))));
+console.log("Last 5 points:", points3.slice(-5).map(p => p.map(coord => coord.toFixed(4))));
+// Expected: Points should be relatively uniformly distributed, as no point on the arc is significantly closer.
+// The "closest point" on the arc will likely be determined by its closest angular projection.
+// Example 4: No attraction (uniform distribution)
+const p0_ex4 = [1, 0, 0];
+const p1_ex4 = [0, 1, 0];
+const axisA_ex4 = [0, 0, 1];
+const attractionPoint_ex4 = [Math.sqrt(1 / 2), Math.sqrt(1 / 2), 0]; // Irrelevant when strength is 0
+const numPoints_ex4 = 50;
+const strength_ex4 = 4.0; // No attraction (uniform)
+console.log("\n--- Example 4: Uniform distribution (strength = 0) ---");
+const points4 = generateArcPoints(p0_ex4, p1_ex4, axisA_ex4, attractionPoint_ex4, numPoints_ex4, strength_ex4);
+console.log(`Generated ${points4.length} points.`);
+console.log("First 5 points:", points4.slice(0, 5).map(p => p.map(coord => coord.toFixed(4))));
+console.log("Last 5 points:", points4.slice(-5).map(p => p.map(coord => coord.toFixed(4))));
+// Expected: Points should be uniformly spaced.
+const sequentialDistances = points4.map((p, i) => {
+    if (i === 0)
+        return 0; // Skip the first point
+    return vec3Distance(points4[i - 1], p);
+});
+console.log("Sequential distances between points (should be roughly equal for uniform distribution):", sequentialDistances.map(d => d.toFixed(4)));

package/Math/arc.js

@@ -143,7 +143,8 @@ function _populatePointsWithClosestPointInsideArc(out, arc, count, closestPoint)
  * @param {Vec3} cameraPosition - The position of the camera.
  * @param {number} quaternionReuseCount - The number of times to apply the same rotation before recalculating. Higher is faster but less accurate.
  */
-function _distanceSampling(out, count, inArc, cameraPosition = vec3create(0, 0, 0), quaternionReuseCount = 1) {
+function _distanceSampling(out, count, inArc, cameraPosition = vec3create(0, 0, 0), // TODO
+quaternionReuseCount = 1) {
     if (count === 0) {
         return;
     }

package/Math/circle-cdf-points.js

@@ -1,4 +1,168 @@
 import { RADIANS } from "./methods";
+function createTemplate(intervalCount, strength = 1.0) {
+    const out = new Array(intervalCount);
+    const TOTAL = 1;
+    let cummulative = 0;
+    if (strength <= 0) {
+        // If strength is 0, distribute evenly.
+        const step = TOTAL / (intervalCount - 1);
+        for (let i = 0; i < intervalCount; i++) {
+            out[i] = cummulative;
+            cummulative += step;
+        }
+        out[intervalCount - 1] = TOTAL; // Ensure the last value is exactly TOTAL
+        return out;
+    }
+    // If strength is greater than 0, bias towards the start.
+    const weights = new Array(intervalCount);
+    let currentStep = 1;
+    let totalWeight = 0;
+    // Calculate weights for each interval, decreasing for later intervals.
+    for (let i = 0; i < intervalCount; i++) {
+        // Using (i + 1) in the denominator gives earlier intervals the highest weight.
+        totalWeight += currentStep;
+        weights[i] = totalWeight;
+        currentStep += strength;
+    }
+    // Distribute the total angle based on the weights.
+    for (let i = 0; i < intervalCount; i++) {
+        // Round to the nearest whole number for this interval.
+        out[i] = (weights[i] / totalWeight) * TOTAL;
+    }
+    if (out[intervalCount - 1] !== TOTAL) {
+        out[intervalCount - 1] = TOTAL;
+    }
+    // console.log("createTemplate", "strength", strength, "intervalCount", intervalCount, "out", out);
+    return out;
+}
+function interpolation(a, b, t) {
+    return a + (b - a) * t;
+}
+/**
+ * Populates the `out` array with values from the `template` array,
+ * distributing the surplus length as interpolated values between the template samples.
+ *
+ * @param out The destination array to be filled. Its length must be >= template.length.
+ * @param template An ordered array of numbers to be placed in the `out` array.
+ * @param strength A parameter controlling the distribution bias of surplus samples.
+ * - strength = 0: Surplus samples are distributed evenly.
+ * - strength > 0: Surplus samples are biased towards the start of the template.
+ * - Higher values create a stronger bias.
+ */
+function increasePopulation(// TODO: THERE IS A BUG
+out, template, strength = 1.0) {
+    const sourceLength = template.length;
+    const destinationLength = out.length;
+    const outLengthAtStart = out.length;
+    // --- Handle Edge Cases ---
+    // If the template is empty, there is nothing to interpolate from.
+    if (sourceLength === 0) {
+        return;
+    }
+    // If the template has only one value, fill the output array with that value.
+    if (sourceLength === 1) {
+        out.fill(template[0]);
+        return;
+    }
+    // If the destination is not larger than the source, just copy the template values.
+    if (destinationLength <= sourceLength) {
+        for (let i = 0; i < destinationLength; i++) {
+            out[i] = template[i];
+        }
+        return;
+    }
+    // --- Main Logic ---
+    const surplus = destinationLength - sourceLength;
+    const numGaps = sourceLength - 1;
+    // This array will hold the number of extra samples to add in each gap.
+    const surplusPerGap = new Array(numGaps).fill(0);
+    if (surplus > 0) {
+        // --- Step 1: Determine the distribution of surplus items ---
+        // If strength is 0, distribute surplus items as evenly as possible.
+        if (strength <= 0) {
+            const baseToAdd = Math.floor(surplus / numGaps);
+            const remainder = surplus % numGaps;
+            for (let i = 0; i < numGaps; i++) {
+                // Distribute the remainder one by one to the first gaps.
+                surplusPerGap[i] = baseToAdd + (i < remainder ? 1 : 0);
+            }
+        }
+        else {
+            // Biased Distribution: more items in earlier gaps.
+            const weights = new Array(numGaps);
+            let totalWeight = 0;
+            // A. Calculate a weight for each gap. The weight decreases for later gaps.
+            // The `strength` parameter makes this decay steeper.
+            for (let i = 0; i < numGaps; i++) {
+                // Using (i + 1) in the denominator gives earlier gaps (i=0) the highest weight.
+                const weight = Math.pow(1 / (i + 1), strength);
+                weights[i] = weight;
+                totalWeight += weight;
+            }
+            // B. Distribute the surplus based on the calculated weights.
+            // This method ensures the total distributed count equals the surplus.
+            let distributedCount = 0;
+            for (let i = 0; i < numGaps - 1; i++) {
+                const idealCount = (weights[i] / totalWeight) * surplus;
+                // Round to the nearest whole number for this gap.
+                const countForThisGap = Math.ceil(idealCount);
+                surplusPerGap[i] = countForThisGap;
+                distributedCount += countForThisGap;
+            }
+            // Assign the remainder to the last gap to guarantee the sum is correct.
+            //surplusPerGap[numGaps - 1] = surplus - distributedCount; 
+            // add to first 
+            const leftover = surplus - distributedCount;
+            if (leftover > 0) {
+                surplusPerGap[0] += leftover; // Add any leftover to the first gap.
+            }
+            console.log("leftover", leftover, "distributedCount", distributedCount, "surplus", surplus);
+        }
+    }
+    // --- Step 2: Populate the `out` array ---
+    let outIndex = 0;
+    for (let i = 0; i < surplusPerGap.length; i++) {
+        if (typeof surplusPerGap[i] !== "number" || isNaN(surplusPerGap[i]) || !isFinite(surplusPerGap[i])) {
+            console.warn("increasePopulation: Invalid surplusPerGap value at index", i, ":", surplusPerGap[i]);
+        }
+    }
+    for (let i = 0; i < sourceLength; i++) {
+        // A. Add the original template item.
+        out[outIndex++] = template[i];
+        // B. If this is not the last template item, fill the gap after it.
+        if (i < numGaps) {
+            const numToAdd = surplusPerGap[i];
+            if (numToAdd <= 0)
+                continue;
+            const startVal = template[i];
+            const endVal = template[i + 1];
+            // C. Add the interpolated ("surplus") items for this gap.
+            // The total number of intervals in this gap is numToAdd + 1.
+            const totalIntervals = numToAdd + 1;
+            for (let j = 1; j <= numToAdd; j++) {
+                const t = j / totalIntervals; // The interpolation factor (0 < t < 1)
+                // Linear interpolation: out = start * (1 - t) + end * t
+                const interpolatedValue = startVal * (1 - t) + endVal * t;
+                out[outIndex++] = interpolatedValue;
+                if (outIndex >= out.length) {
+                    console.warn("increasePopulation: Output array overflow. Stopping early.");
+                    console.warn("processeed item ratio:", i, "/", sourceLength);
+                    let count = numToAdd - j;
+                    console.log("count", count);
+                    for (let _i = i; _i < sourceLength; _i++) {
+                        count += surplusPerGap[_i];
+                    }
+                    console.warn("increasePopulation: Not enough space to add", count, "more items.");
+                    return; // Prevent overflow if the output array is not large enough.
+                }
+            }
+        }
+    }
+    // --- Step 3: Ensure the output length is correct ---
+    if (outLengthAtStart !== out.length) {
+        console.warn("increasePopulation: Output length mismatch. Expected", outLengthAtStart, "but got", out.length);
+    }
+}
 function createCummulativeTemplate(numberOfPoints, strength, denseRatio = 0.5 // Ratio of points to be densely packed at the start.
 ) {
     // Handle edge cases for the number of points.
@@ -75,4 +239,9 @@ function globeFindPointByPolarHalfCircle(out, globe, centerLong, centerLat, radi
         offset -= 2;
     }
 }
-export { createCummulativeTemplateStash, globeFindPointByPolar, globeFindPointByPolarHalfCircle };
+export { 
+// createTemplate,
+// increasePopulation,
+// interpolation,
+// createCummulativeTemplate,
+createCummulativeTemplateStash, globeFindPointByPolar, globeFindPointByPolarHalfCircle };

package/Math/circle.js

@@ -29,5 +29,30 @@ function createCircleClosestAzimuthAngleProperties(circle) {
         normal: normal,
         northPointProjectedToOriginPlaneNormalized: N,
     };
+    // const distance = normal[2]; //dot(normal, [0, 0, 1] as Vec3)
+    // const N: Vec3 = [0, 0, 0];
+    // if (Math.abs(distance) < 1e-6) {
+    //     N[0] = -1;
+    //     N[1] = 0;
+    //     N[2] = 0;
+    // } else {
+    //     // TODO: add cases for 8 parts of the sphere
+    //     copy(N, normal);
+    //     multiplyScalar(N, N, distance);
+    //     if (N[2] >= 0) {
+    //         N[0] = -N[0];
+    //         N[1] = -N[1];
+    //         N[2] = 1 - N[2];
+    //     } else {
+    //         N[2] = -N[2];
+    //         N[0] = -N[0];
+    //         N[1] = -N[1];
+    //     }
+    // }
+    // normalize(N, N);
+    // return {
+    //     normal: normal,
+    //     northPointProjectedToOriginPlaneNormalized: N,
+    // }
 }
 export { closestAzimuthAngle, createCircleClosestAzimuthAngleProperties };