@3driseai/3drise-viewer 0.1.26 → 0.1.27

package/dist/utils/particleShape.js

@@ -0,0 +1,207 @@
+// =============================================================================
+// particleShape — the shared `shape` config of shape-driven particle objects
+// =============================================================================
+//
+// config.shape is a mesh-builder geometry config ({ type, ...params }): the same object the
+// core mesh builders take (createMeshByType), so meshes and particles share one builder. Only
+// closed solids are particle shapes (PARTICLE_SHAPE_TYPES). The particle objects read the
+// shape with its axis along y: the torus is laid flat and the tetrahedron stands vertex-up,
+// so every shape has a top and a bottom.
+//
+// The shape keeps its real size: SHAPE_SCALE maps builder units to particle world units, so
+// every parameter (a sphere's radius, a box's size) changes the object.
+//
+// Readers:
+//   radialMap / shapeField — R(theta, h): distance from the y axis to the outermost surface.
+//   sampleSurface          — points spread evenly over the surface (area-weighted, stratified).
+import * as THREE from 'three';
+import { createMeshByType, PARTICLE_SHAPE_DEFAULTS, PARTICLE_SHAPE_TYPES } from '@3driseai/3drise-core';
+/** Mesh-builder units -> particle world units (the builders' defaults come out ~1.6 wide). */
+export const SHAPE_SCALE = 1.6;
+/** The shape with every parameter filled in from the builder defaults (unknown types -> cone). */
+export function shapeConfig(shape) {
+    const t = shape && PARTICLE_SHAPE_TYPES.includes(shape.type) ? shape.type : 'cone';
+    return { ...PARTICLE_SHAPE_DEFAULTS[t], ...(shape || {}), type: t };
+}
+/** Geometry of a shape, built by the core mesh builders, axis along y. The caller disposes it. */
+export function shapeGeometry(shape) {
+    const c = shapeConfig(shape);
+    const built = createMeshByType({ ...c, id: 'particleShape', name: 'particleShape' });
+    let g;
+    if (built?.mesh?.geometry) {
+        g = built.mesh.geometry;
+        const m = built.mesh.material;
+        (Array.isArray(m) ? m : [m]).forEach((x) => x?.dispose());
+    }
+    else {
+        g = new THREE.ConeGeometry(0.5, 1, 32);
+    }
+    if (c.type === 'torus')
+        g.rotateX(Math.PI / 2);
+    if (c.type === 'tetrahedron') {
+        g.applyQuaternion(new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(1, 1, 1).normalize(), new THREE.Vector3(0, 1, 0)));
+    }
+    return g;
+}
+/** Radial map of a closed shape: R(theta, h) = distance from the y axis to the outermost surface,
+ *  on an nTh x nH grid (slice the triangles at each height, cast rays in the slice). The axis goes
+ *  through the vertex centroid (a tetrahedron's footprint is not centred on its bounding box). */
+export function radialMap(geometry, nTh = 96, nH = 96) {
+    const g = geometry.index ? geometry.toNonIndexed() : geometry;
+    g.computeBoundingBox();
+    const bb = g.boundingBox;
+    const P = g.attributes.position.array;
+    const nT = P.length / 9;
+    const ymin = bb.min.y, ymax = bb.max.y;
+    let cx = 0, cz = 0;
+    for (let k = 0; k < P.length; k += 3) {
+        cx += P[k];
+        cz += P[k + 2];
+    }
+    cx /= P.length / 3;
+    cz /= P.length / 3;
+    const R = new Float32Array(nTh * nH);
+    const seg = [];
+    const pts = [];
+    for (let j = 0; j < nH; j++) {
+        const h = ymin + ((j + 0.5) / nH) * (ymax - ymin);
+        seg.length = 0;
+        for (let t = 0; t < nT; t++) {
+            const o = t * 9;
+            const y0 = P[o + 1] - h, y1 = P[o + 4] - h, y2 = P[o + 7] - h;
+            if ((y0 > 0 && y1 > 0 && y2 > 0) || (y0 < 0 && y1 < 0 && y2 < 0))
+                continue;
+            pts.length = 0;
+            const edge = (a, b, ya, yb) => {
+                if ((ya > 0) === (yb > 0) || ya === yb)
+                    return;
+                const s = ya / (ya - yb);
+                pts.push(P[o + a] + (P[o + b] - P[o + a]) * s - cx, P[o + a + 2] + (P[o + b + 2] - P[o + a + 2]) * s - cz);
+            };
+            edge(0, 3, y0, y1);
+            edge(3, 6, y1, y2);
+            edge(6, 0, y2, y0);
+            if (pts.length >= 4)
+                seg.push(pts[0], pts[1], pts[2], pts[3]);
+        }
+        for (let i = 0; i < nTh; i++) {
+            const th = (i / nTh) * Math.PI * 2, dx = Math.cos(th), dz = Math.sin(th);
+            let best = 0;
+            for (let s = 0; s < seg.length; s += 4) {
+                const ax = seg[s], az = seg[s + 1], ex = seg[s + 2] - ax, ez = seg[s + 3] - az;
+                const den = dx * ez - dz * ex;
+                if (Math.abs(den) < 1e-9)
+                    continue;
+                const t = (ax * ez - az * ex) / den, u = (ax * dz - az * dx) / den;
+                if (t > best && u >= -1e-6 && u <= 1 + 1e-6)
+                    best = t;
+            }
+            R[j * nTh + i] = best;
+        }
+    }
+    if (g !== geometry)
+        g.dispose();
+    return { R, ymin, ymax, nTh, nH };
+}
+/** The shape as a surface field: R(theta, h) in world units (scale x builder units), centred on the
+ *  origin. rAt(theta, h), rmAt(h) (mean radius), Y0..Y1, RW (widest mean), rMax (widest radius). */
+export function shapeField(shape, scale = SHAPE_SCALE, nTh = 96, nH = 96) {
+    const geom = shapeGeometry(shape);
+    const map = radialMap(geom, nTh, nH);
+    geom.dispose();
+    const R = map.R;
+    let rMax = 0;
+    for (let k = 0; k < R.length; k++)
+        rMax = Math.max(rMax, R[k]);
+    const span = map.ymax - map.ymin;
+    const sc = scale;
+    for (let k = 0; k < R.length; k++)
+        R[k] *= sc;
+    const Y0 = -span * sc / 2, Y1 = span * sc / 2;
+    const Rm = new Float32Array(nH);
+    let RW = 0;
+    for (let j = 0; j < nH; j++) {
+        let s = 0;
+        for (let i = 0; i < nTh; i++)
+            s += R[j * nTh + i];
+        Rm[j] = s / nTh;
+        RW = Math.max(RW, Rm[j]);
+    }
+    const fy = (h) => {
+        const f = (h - Y0) / (Y1 - Y0) * nH - 0.5;
+        return f < 0 ? 0 : f > nH - 1.001 ? nH - 1.001 : f;
+    };
+    function rmAt(h) { const f = fy(h), j = f | 0, t = f - j; return Rm[j] + (Rm[j + 1] - Rm[j]) * t; }
+    function rAt(th, h) {
+        const f = fy(h);
+        let g = (th / (Math.PI * 2)) * nTh;
+        g -= Math.floor(g / nTh) * nTh;
+        const j = f | 0, t = f - j, i = g | 0, s = g - i, i1 = (i + 1) % nTh;
+        const a = R[j * nTh + i] + (R[j * nTh + i1] - R[j * nTh + i]) * s;
+        const b = R[(j + 1) * nTh + i] + (R[(j + 1) * nTh + i1] - R[(j + 1) * nTh + i]) * s;
+        return a + (b - a) * t;
+    }
+    return { rAt, rmAt, Y0, Y1, RW, rMax: rMax * sc, scale: sc };
+}
+/** n points spread evenly over the shape's surface (area-weighted, stratified, shuffled so any prefix
+ *  covers the whole shape), in the same world frame as shapeField. Returns Float32Array n*3. */
+export function sampleSurface(shape, n, rng, scale = SHAPE_SCALE) {
+    const geom = shapeGeometry(shape);
+    const g = geom.index ? geom.toNonIndexed() : geom;
+    g.computeBoundingBox();
+    const bb = g.boundingBox;
+    const P = g.attributes.position.array;
+    const nT = P.length / 9;
+    const cy = (bb.min.y + bb.max.y) / 2;
+    let cx = 0, cz = 0;
+    for (let k = 0; k < P.length; k += 3) {
+        cx += P[k];
+        cz += P[k + 2];
+    }
+    cx /= P.length / 3;
+    cz /= P.length / 3;
+    const sc = scale;
+    const cdf = new Float64Array(nT);
+    let acc = 0;
+    for (let t = 0; t < nT; t++) {
+        const o = t * 9;
+        const ax = P[o + 3] - P[o], ay = P[o + 4] - P[o + 1], az = P[o + 5] - P[o + 2];
+        const bx = P[o + 6] - P[o], by = P[o + 7] - P[o + 1], bz = P[o + 8] - P[o + 2];
+        acc += 0.5 * Math.hypot(ay * bz - az * by, az * bx - ax * bz, ax * by - ay * bx);
+        cdf[t] = acc;
+    }
+    const out = new Float32Array(n * 3);
+    for (let i = 0; i < n; i++) {
+        const u = ((i + rng()) / n) * acc;
+        let lo = 0, hi = nT - 1;
+        while (lo < hi) {
+            const m = (lo + hi) >> 1;
+            if (cdf[m] < u)
+                lo = m + 1;
+            else
+                hi = m;
+        }
+        let a = rng(), b = rng();
+        if (a + b > 1) {
+            a = 1 - a;
+            b = 1 - b;
+        }
+        const o = lo * 9;
+        for (let k = 0; k < 3; k++) {
+            const v = P[o + k] + (P[o + 3 + k] - P[o + k]) * a + (P[o + 6 + k] - P[o + k]) * b;
+            out[i * 3 + k] = (v - (k === 0 ? cx : k === 1 ? cy : cz)) * sc;
+        }
+    }
+    if (g !== geom)
+        g.dispose();
+    geom.dispose();
+    for (let i = n - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        for (let k = 0; k < 3; k++) {
+            const t = out[i * 3 + k];
+            out[i * 3 + k] = out[j * 3 + k];
+            out[j * 3 + k] = t;
+        }
+    }
+    return out;
+}

package/dist/utils/particleTrails.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"particleTrails.d.ts","sourceRoot":"","sources":["../../src/utils/particleTrails.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAc/B,eAAO,MAAM,WAAW,UAAsC,CAAC;AAK/D,wBAAgB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;EAWlC;AAED,wBAAgB,gBAAgB,CAAC,CAAC,KAAA,EAAE,CAAC,KAAA,QAKpC;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,MAAM,KAAA;;;YAES,CAAC,MAAM,CAAC,MAAM,CAAC,SAAU;YAAE,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS;YAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAQ;;;;;;;;;;;;;;;;;;;;EAMjH;AAuID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,KAAA,EAAE,IAAI,KAAA;;;;;;;EAyJxC"}
+{"version":3,"file":"particleTrails.d.ts","sourceRoot":"","sources":["../../src/utils/particleTrails.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAc/B,eAAO,MAAM,WAAW,UAAsC,CAAC;AAK/D,wBAAgB,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;EAWlC;AAED,wBAAgB,gBAAgB,CAAC,CAAC,KAAA,EAAE,CAAC,KAAA,QAKpC;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,MAAM,KAAA;;;YAES,CAAC,MAAM,CAAC,MAAM,CAAC,SAAU;YAAE,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS;YAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAQ;;;;;;;;;;;;;;;;;;;;EAMjH;AAuID;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,KAAA,EAAE,IAAI,KAAA;;;;;;;EA+JxC"}

package/dist/utils/particleTrails.js

@@ -81,7 +81,7 @@ void main() {
 }
 `;
 // shared tail of every trail vertex shader: shade, tint toward trailColor, size, project
-function finish(sizePx) {
+function finish(sizePx, alpha = 1) {
     return /* glsl */ `
   vec3 light = trailShade(p, f);
   vCol = light * mix(vec3(1.0), uTrailColor * 1.25, smoothstep(0.0, 0.8, f)) * uIntensity;
@@ -89,7 +89,7 @@ function finish(sizePx) {
   float mag;
   vec3 mv = trailView(mvp.xyz, mag);
   vCol *= mag;
-  vA = clamp(vA, 0.0, 1.0) * uOpacity * uTrailOpacity;
+  vA = clamp(vA * ${alpha.toFixed(3)}, 0.0, 1.0) * uOpacity * uTrailOpacity;
   gl_PointSize = clamp(uSize * uViewH * ${sizePx.toFixed(4)} * (1.0 - 0.5 * f) * sqrt(mag) / -mv.z, 1.0, 40.0);
   gl_Position = projectionMatrix * vec4(mv, 1.0);
 `;
@@ -103,7 +103,7 @@ function setTemplate(g, tpl) {
 }
 const K_ON = '#define TRAIL_K aK\nattribute float aK;\n';
 const K_OFF = '#define TRAIL_K 1.0\n';
-function streakShader(glsl, sizePx, spacing, kdef) {
+function streakShader(glsl, sizePx, spacing, kdef, alpha = 1) {
     const S = 24;
     return {
         S,
@@ -121,12 +121,12 @@ void main() {
   vec3 p = aP - dv * f;
   float stepLen = len / ${(S - 1).toFixed(1)};
   vA = 1.2 * pow(1.0 - f, 1.4) * clamp(stepLen / ${spacing.toFixed(4)}, 0.0, 1.0) * step(0.001, f);
-  ${finish(sizePx)}
+  ${finish(sizePx, alpha)}
 }
 `,
     };
 }
-function cometShader(glsl, sizePx, spacing, kdef, SUB) {
+function cometShader(glsl, sizePx, spacing, kdef, SUB, alpha = 1) {
     const slots = Array.from({ length: SLOTS }, (_, i) => `attribute vec3 h${i};`).join('\n');
     const pick = Array.from({ length: SLOTS }, (_, i) => `  ${i === 0 ? 'if' : 'else if'} (i == ${i}) return h${i};`).join('\n');
     return /* glsl */ `
@@ -161,11 +161,11 @@ void main() {
   float f = clamp(age / uTrailLength, 0.0, 1.0);
   float stepLen = length(p2 - p1) / ${SUB.toFixed(1)};
   vA = pow(1.0 - f, 1.3) * clamp(stepLen / ${spacing.toFixed(4)}, 0.0, 1.0) * step(0.0001, s);
-  ${finish(sizePx)}
+  ${finish(sizePx, alpha)}
 }
 `;
 }
-function echoShader(glsl, sizePx, kdef) {
+function echoShader(glsl, sizePx, kdef, alpha = 1) {
     return /* glsl */ `
 ${HEAD}
 attribute vec4 aE0; // emitted position xyz, birth time
@@ -181,7 +181,7 @@ void main() {
   vec3 p = aE0.xyz + aE1.xyz * uVelScale * carry * 0.6 + dir * 0.03 * sqrt(max(age, 0.0)) * uTrailLength;
   vA = (f < 0.0 || f > 1.0) ? 0.0 : smoothstep(0.0, 0.08, f) * pow(1.0 - f, 2.0) * 0.55;
   f = clamp(f, 0.0, 1.0);
-  ${finish(sizePx * 1.4).replace('(1.0 - 0.5 * f)', '(1.0 + 1.2 * f)')}
+  ${finish(sizePx * 1.4, alpha).replace('(1.0 - 0.5 * f)', '(1.0 + 1.2 * f)')}
 }
 `;
 }
@@ -197,6 +197,8 @@ export function createCpuTrail(mode, opts) {
     const kArr = opts.k || null;
     const kdef = kArr ? K_ON : K_OFF;
     const sizePx = opts.sizePx ?? 0.006;
+    // per-object alpha gain: colour saturates at 1 on 8-bit targets, so faint trails need alpha, not colour
+    const alpha = opts.alpha ?? 1;
     const spacing = opts.spacing ?? 0.004;
     const nSub = Math.max(1, Math.min(CAPS[mode], Math.round(n * Math.min(Math.max(u.uTrailShare.value, 0), 1))));
     const object = new THREE.Group();
@@ -211,7 +213,7 @@ export function createCpuTrail(mode, opts) {
         return m;
     };
     if (mode === 'streak') {
-        const sh = streakShader(glsl, sizePx, spacing, kdef);
+        const sh = streakShader(glsl, sizePx, spacing, kdef, alpha);
         const g = new THREE.InstancedBufferGeometry();
         const tpl = new Float32Array(sh.S);
         for (let i = 0; i < sh.S; i++)
@@ -260,7 +262,7 @@ export function createCpuTrail(mode, opts) {
         }
         g.instanceCount = nSub;
         geos.push(g);
-        const pts = new THREE.Points(g, mk(cometShader(glsl, sizePx, spacing, kdef, SUBn)));
+        const pts = new THREE.Points(g, mk(cometShader(glsl, sizePx, spacing, kdef, SUBn, alpha)));
         pts.frustumCulled = false;
         object.add(pts);
         let head = 0, acc = 0, dirtyReset = false;
@@ -322,7 +324,7 @@ export function createCpuTrail(mode, opts) {
     if (a2)
         g.setAttribute('aK', a2);
     geos.push(g);
-    const pts = new THREE.Points(g, mk(echoShader(glsl, sizePx, kdef)));
+    const pts = new THREE.Points(g, mk(echoShader(glsl, sizePx, kdef, alpha)));
     pts.frustumCulled = false;
     object.add(pts);
     let write = 0, src = 0, emitAcc = 0;
@@ -355,21 +357,34 @@ export function createCpuTrail(mode, opts) {
             }
             // partial uploads (two ranges when the ring wraps)
             const first = Math.min(k, P - start);
-            a0.clearUpdateRanges();
-            a1.clearUpdateRanges();
+            // ranges add up until three uploads (and clears) them, so several updates between two renders all
+            // reach the GPU; a long backlog (the object was hidden) collapses into one full upload
+            let full = false;
+            if (a0.updateRanges.length > 32) {
+                a0.clearUpdateRanges();
+                a1.clearUpdateRanges();
+                if (a2)
+                    a2.clearUpdateRanges();
+                full = true;
+            }
             a0.addUpdateRange(start * 4, first * 4);
             a1.addUpdateRange(start * 4, first * 4);
             if (k > first) {
                 a0.addUpdateRange(0, (k - first) * 4);
                 a1.addUpdateRange(0, (k - first) * 4);
             }
+            if (full) {
+                a0.clearUpdateRanges();
+                a1.clearUpdateRanges();
+            }
             a0.needsUpdate = true;
             a1.needsUpdate = true;
             if (a2) {
-                a2.clearUpdateRanges();
                 a2.addUpdateRange(start, first);
                 if (k > first)
                     a2.addUpdateRange(0, k - first);
+                if (full)
+                    a2.clearUpdateRanges();
                 a2.needsUpdate = true;
             }
         },

package/dist/utils/terrainUniforms.d.ts

@@ -1,5 +1,5 @@
 import * as THREE from 'three';
-import type { TerrainConfig, TerrainQualityConfig } from '../types/terrainConfigs';
+import type { TerrainConfig, TerrainQualityConfig } from '@3driseai/3drise-core';
 import type { CloudSunState } from '../hooks/useCloudSun';
 export declare function applyTerrainUniforms(material: THREE.ShaderMaterial, config: TerrainConfig, quality: TerrainQualityConfig): void;
 export default applyTerrainUniforms;

package/dist/utils/terrainUniforms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"terrainUniforms.d.ts","sourceRoot":"","sources":["../../src/utils/terrainUniforms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAe,MAAM,yBAAyB,CAAC;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoD1D,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,oBAAoB,GAC9B,IAAI,CAwDN;AAED,eAAe,oBAAoB,CAAC;AAiCpC,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CA4BlG;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAwC5F"}
+{"version":3,"file":"terrainUniforms.d.ts","sourceRoot":"","sources":["../../src/utils/terrainUniforms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAe,MAAM,uBAAuB,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAoD1D,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,oBAAoB,GAC9B,IAAI,CAwDN;AAED,eAAe,oBAAoB,CAAC;AAiCpC,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CA4BlG;AAMD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI,CAwC5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@3driseai/3drise-viewer",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,6 @@
   },
   "dependencies": {
     "@3driseai/3drise-common": "^1.0.1",
-    "@3driseai/3drise-core": "^1.0.19"
+    "@3driseai/3drise-core": "^1.0.20"
   }
 }