zero2geospatial3d-sdk 0.1.0__py3-none-any.whl

zero2geospatial3d/web/src/scene/viewer.js

@@ -0,0 +1,275 @@
+// @ts-check
+// Renderer, camera, controls, lights and the render-on-demand loop.
+//
+// Axes: +x east, +y up, -z north (local scene metres). Three.js object
+// layers decide what each analysis pass sees:
+//   0 visible     drawn on screen
+//   1 SURFACE     surfaces analysed from above (terrain, roofs)
+//   2 OCCLUDER    everything that blocks sun, sky or view (adds trees, walls)
+//   3 ID          features that carry a feature key (for per-feature results)
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+export const LAYER_SURFACE = 1;
+export const LAYER_OCCLUDER = 2;
+export const LAYER_ID = 3;
+/** Feature keys are layerIndex * KEY_SHIFT + id (objects.js featureKey). */
+export const KEY_SHIFT = 1 << 20;
+
+// Feature keys in the ID pass: the layer index (1..255) in alpha, the
+// feature id (< 2^20) in RGB. Two attributes, because one float32 holds a
+// whole key (layer * 2^20 + id) exactly only up to layer 15.
+const ID_VERTEX = `
+attribute float fkey;
+attribute float flayer;
+varying float vKey;
+varying float vLayer;
+#include <common>
+void main() {
+  vKey = fkey;
+  vLayer = flayer;
+  #include <begin_vertex>
+  #include <project_vertex>
+}`;
+const ID_FRAGMENT = `
+precision highp float;
+varying float vKey;
+varying float vLayer;
+void main() {
+  float k = floor(vKey + 0.5);
+  float r = floor(k / 65536.0);
+  float g = floor((k - r * 65536.0) / 256.0);
+  float b = k - r * 65536.0 - g * 256.0;
+  gl_FragColor = vec4(r / 255.0, g / 255.0, b / 255.0, floor(vLayer + 0.5) / 255.0);
+}`;
+
+export function makeIdMaterial() {
+  return new THREE.ShaderMaterial({ vertexShader: ID_VERTEX, fragmentShader: ID_FRAGMENT, side: THREE.DoubleSide });
+}
+
+/** Feature key from an ID-pass pixel (a = layer index, rgb = feature id). */
+export function decodeKey(r, g, b, a) {
+  return a * KEY_SHIFT + r * 65536 + g * 256 + b;
+}
+
+export class Viewer {
+  /** @param {HTMLElement} container */
+  constructor(container) {
+    this.container = container;
+    const renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true, logarithmicDepthBuffer: false });
+    renderer.setPixelRatio(Math.min(2, window.devicePixelRatio || 1));
+    renderer.setSize(container.clientWidth, container.clientHeight);
+    renderer.outputColorSpace = THREE.SRGBColorSpace;
+    renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    renderer.toneMappingExposure = 1.05;
+    renderer.shadowMap.enabled = true;
+    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    container.appendChild(renderer.domElement);
+    this.renderer = renderer;
+
+    this.scene = new THREE.Scene();
+    this.scene.background = new THREE.Color(0xdfe8f0);
+    this.camera = new THREE.PerspectiveCamera(45, container.clientWidth / Math.max(1, container.clientHeight), 1, 60000);
+    this.camera.position.set(400, 500, 600);
+    this.controls = new OrbitControls(this.camera, renderer.domElement);
+    this.controls.enableDamping = true;
+    this.controls.dampingFactor = 0.12;
+    this.controls.maxPolarAngle = Math.PI * 0.495;
+    this.controls.screenSpacePanning = true;
+    this.controls.addEventListener('change', () => this.requestRender());
+
+    this.hemi = new THREE.HemisphereLight(0xeaf2ff, 0x8a8174, 1.2);
+    this.scene.add(this.hemi);
+    this.sun = new THREE.DirectionalLight(0xfff4e0, 2.4);
+    this.sun.castShadow = true;
+    this.sun.shadow.mapSize.set(4096, 4096);
+    this.sun.shadow.bias = -0.0004;
+    this.sun.shadow.normalBias = 0.6;
+    this.scene.add(this.sun);
+    this.scene.add(this.sun.target);
+    this.sunDir = new THREE.Vector3(0.3, 0.8, -0.4).normalize();
+    this.shadowsOn = true;
+
+    this.world = new THREE.Group();
+    this.scene.add(this.world);
+    this.helpers = new THREE.Group();
+    this.scene.add(this.helpers);
+
+    this.idMaterial = makeIdMaterial();
+    this._pickTarget = new THREE.WebGLRenderTarget(1, 1, { type: THREE.UnsignedByteType });
+    this._dirty = true;
+    this._frameHooks = [];
+    this.extentRadius = 1000;
+    this.stats = { fps: 0, frames: 0, last: performance.now(), drawCalls: 0, triangles: 0 };
+    this.renderHook = null; // compare views draw several panels instead of one view
+    this._postRender = []; // run right after a frame is drawn (video compositing)
+
+    window.addEventListener('resize', () => this.resize());
+    if ('ResizeObserver' in window) new ResizeObserver(() => this.resize()).observe(container);
+    renderer.setAnimationLoop(() => this._loop());
+  }
+
+  resize() {
+    const w = this.container.clientWidth;
+    const h = this.container.clientHeight;
+    if (!w || !h) return;
+    this.renderer.setSize(w, h);
+    this.camera.aspect = w / h;
+    this.camera.updateProjectionMatrix();
+    this.requestRender();
+  }
+
+  requestRender() {
+    this._dirty = true;
+  }
+
+  /** Draw the view once: one camera, or the compare panels. */
+  draw() {
+    if (this.renderHook) this.renderHook();
+    else this.renderer.render(this.scene, this.camera);
+  }
+
+  onPostRender(fn) {
+    this._postRender.push(fn);
+    return () => { this._postRender = this._postRender.filter((x) => x !== fn); };
+  }
+
+  onFrame(fn) {
+    this._frameHooks.push(fn);
+  }
+
+  _loop() {
+    const moved = this.controls.update();
+    for (const fn of this._frameHooks) if (fn()) this._dirty = true;
+    if (!this._dirty && !moved) return;
+    this._dirty = false;
+    this._fitClipping();
+    this._fitShadow();
+    this.draw();
+    for (const fn of this._postRender) fn();
+    const s = this.stats;
+    s.frames++;
+    s.drawCalls = this.renderer.info.render.calls;
+    s.triangles = this.renderer.info.render.triangles;
+    const now = performance.now();
+    if (now - s.last > 1000) { s.fps = (s.frames * 1000) / (now - s.last); s.frames = 0; s.last = now; }
+  }
+
+  /** Sun direction (unit vector towards the sun) and whether it is up. */
+  setSun(dir) {
+    this.sunDir.set(dir[0], dir[1], dir[2]).normalize();
+    const up = this.sunDir.y > 0.005;
+    this.sun.visible = up;
+    // Dimmer, warmer light near the horizon; sky ambience follows.
+    const elev = Math.asin(Math.max(-1, Math.min(1, this.sunDir.y)));
+    const k = Math.max(0, Math.min(1, elev / 0.5));
+    this.sun.intensity = up ? 0.6 + 2.0 * k : 0;
+    this.sun.color.setRGB(1, 0.82 + 0.16 * k, 0.62 + 0.3 * k);
+    this.hemi.intensity = 0.35 + 0.9 * Math.max(0, Math.min(1, (elev + 0.1) / 0.6));
+    const sky = new THREE.Color().setRGB(0.55 + 0.33 * k, 0.62 + 0.29 * k, 0.72 + 0.22 * k);
+    if (!up) sky.setRGB(0.16, 0.19, 0.26);
+    this.scene.background = sky;
+    this.requestRender();
+  }
+
+  setShadows(on) {
+    this.shadowsOn = on;
+    this.sun.castShadow = on;
+    this.requestRender();
+  }
+
+  /** Near/far planes follow the camera distance, so a 50 km scene keeps depth precision up close. */
+  _fitClipping() {
+    const cam = this.camera;
+    const dist = cam.position.distanceTo(this.controls.target);
+    const near = Math.max(0.2, Math.min(50, dist / 1500));
+    const far = Math.max(dist * 40, this.extentRadius * 6, 5000);
+    if (Math.abs(cam.near - near) / near > 0.1 || Math.abs(cam.far - far) / far > 0.1) {
+      cam.near = near;
+      cam.far = far;
+      cam.updateProjectionMatrix();
+    }
+  }
+
+  /** Fit the sun's shadow camera around the area the camera looks at. */
+  _fitShadow() {
+    if (!this.sun.visible || !this.shadowsOn) return;
+    const target = this.controls.target;
+    const dist = this.camera.position.distanceTo(target);
+    const r = Math.max(120, Math.min(this.extentRadius, dist * 1.2));
+    const cam = this.sun.shadow.camera;
+    cam.left = -r; cam.right = r; cam.top = r; cam.bottom = -r;
+    cam.near = 1; cam.far = 4 * r + 2000;
+    cam.updateProjectionMatrix();
+    this.sun.position.copy(target).addScaledVector(this.sunDir, 2 * r + 800);
+    this.sun.target.position.copy(target);
+    this.sun.target.updateMatrixWorld();
+    // Bias in proportion to the shadow-map texel: enough to avoid acne, small
+    // enough that shadows still touch the walls that cast them up close.
+    this.sun.shadow.normalBias = Math.min(1.5, Math.max(0.03, ((2 * r) / 4096) * 0.8));
+  }
+
+  /** Frame a box (three coordinates). */
+  frame(box, { pitch = 0.9, yaw = -0.6 } = {}) {
+    const centre = box.getCenter(new THREE.Vector3());
+    const size = box.getSize(new THREE.Vector3());
+    const radius = Math.max(50, Math.hypot(size.x, size.z) / 2);
+    this.extentRadius = Math.max(300, radius * 1.4);
+    const dist = radius / Math.tan((this.camera.fov * Math.PI) / 360) * 0.9;
+    this.controls.target.copy(centre);
+    this.camera.position.set(centre.x + Math.sin(yaw) * Math.cos(pitch) * dist,
+      centre.y + Math.sin(pitch) * dist, centre.z + Math.cos(yaw) * Math.cos(pitch) * dist);
+    this.camera.near = Math.max(0.5, dist / 2000);
+    this.camera.far = Math.max(20000, dist * 20);
+    this.camera.updateProjectionMatrix();
+    this.controls.maxDistance = dist * 6;
+    this.controls.update();
+    this.requestRender();
+  }
+
+  /** Feature key under a screen position (client pixels), 0 for none. */
+  pickKey(clientX, clientY) {
+    const rect = this.renderer.domElement.getBoundingClientRect();
+    const x = clientX - rect.left;
+    const y = clientY - rect.top;
+    const w = rect.width;
+    const h = rect.height;
+    const cam = this.camera;
+    cam.setViewOffset(w, h, Math.floor(x), Math.floor(y), 1, 1);
+    const prevBg = this.scene.background;
+    const prevOverride = this.scene.overrideMaterial;
+    const prevMask = cam.layers.mask;
+    this.scene.background = null;
+    this.scene.overrideMaterial = this.idMaterial;
+    cam.layers.set(LAYER_ID);
+    const r = this.renderer;
+    const prevTarget = r.getRenderTarget();
+    const clear = r.getClearColor(new THREE.Color());
+    const alpha = r.getClearAlpha();
+    r.setRenderTarget(this._pickTarget);
+    r.setClearColor(0x000000, 0);
+    r.clear();
+    r.render(this.scene, cam);
+    const px = new Uint8Array(4);
+    r.readRenderTargetPixels(this._pickTarget, 0, 0, 1, 1, px);
+    r.setRenderTarget(prevTarget);
+    r.setClearColor(clear, alpha);
+    cam.clearViewOffset();
+    cam.layers.mask = prevMask;
+    this.scene.background = prevBg;
+    this.scene.overrideMaterial = prevOverride;
+    this.requestRender();
+    return px[3] > 0 ? decodeKey(px[0], px[1], px[2], px[3]) : 0;
+  }
+
+  /** Normalised device coordinates of a client position. */
+  ndc(clientX, clientY) {
+    const rect = this.renderer.domElement.getBoundingClientRect();
+    return new THREE.Vector2(((clientX - rect.left) / rect.width) * 2 - 1, -((clientY - rect.top) / rect.height) * 2 + 1);
+  }
+
+  screenshot() {
+    this.renderer.render(this.scene, this.camera);
+    return this.renderer.domElement.toDataURL('image/png');
+  }
+}

zero2geospatial3d/web/src/scene/wind_streamlines.js

@@ -0,0 +1,336 @@
+// @ts-check
+// 3D animated wind streamline and particle flow visualization for the Three.js viewer.
+// Deflects wind smoothly around solid obstacles and colors lines by local pedestrian speed.
+
+import * as THREE from 'three';
+import { rampStops, rampColor } from '../core/classify.js';
+
+const getRaf = () => (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (cb) => setTimeout(cb, 16));
+const getCaf = () => (typeof cancelAnimationFrame === 'function' ? cancelAnimationFrame : (id) => clearTimeout(id));
+
+export class WindStreamlines {
+  /**
+   * @param {any} app Reference to the main 3D application instance
+   */
+  constructor(app) {
+    this.app = app;
+    this.group = new THREE.Group();
+    this.group.name = 'wind_streamlines';
+    this.active = false;
+    this._raf = 0;
+    this._lastTime = 0;
+  }
+
+  /**
+   * Generates and starts animating wind streamlines.
+   *
+   * @param {object} params
+   * @param {{ cols: number, rows: number, cell: number, minX: number, maxY: number }} params.grid Grid dimension metadata
+   * @param {Float32Array} params.values Local wind speed ratios or values per cell (NaN inside buildings)
+   * @param {Int32Array|Float32Array|Array<number>|null} [params.ids] Optional building ID mask
+   * @param {number} [params.windFromDeg] Meteorological wind direction in degrees (default 270)
+   * @param {number} [params.speed10] Reference wind speed at 10 m height in m/s (default 4)
+   * @param {number} [params.count] Total number of animated streamlines (default 450)
+   * @param {number} [params.trailSteps] Number of simulation vertices per streamline (default 14)
+   */
+  show({
+    grid,
+    values,
+    ids = null,
+    windFromDeg = 270,
+    speed10 = 4,
+    count = 450,
+    trailSteps = 14
+  }) {
+    this.hide();
+    this.active = true;
+
+    const { cols, rows, cell, minX = 0, maxY = 0 } = grid;
+    if (cols <= 0 || rows <= 0 || cell <= 0) return;
+
+    // 1. Two-pass chamfer distance field to nearest building obstacle in metres
+    const INF = 1e6;
+    const distField = new Float32Array(cols * rows);
+    for (let i = 0; i < cols * rows; i++) {
+      distField[i] = ((ids && ids[i] > 0) || !Number.isFinite(values[i])) ? 0 : INF;
+    }
+
+    const d1 = cell;
+    const d2 = cell * Math.SQRT2;
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < cols; c++) {
+        const i = r * cols + c;
+        let v = distField[i];
+        if (c > 0) v = Math.min(v, distField[i - 1] + d1);
+        if (r > 0) {
+          v = Math.min(v, distField[i - cols] + d1);
+          if (c > 0) v = Math.min(v, distField[i - cols - 1] + d2);
+          if (c < cols - 1) v = Math.min(v, distField[i - cols + 1] + d2);
+        }
+        distField[i] = v;
+      }
+    }
+    for (let r = rows - 1; r >= 0; r--) {
+      for (let c = cols - 1; c >= 0; c--) {
+        const i = r * cols + c;
+        let v = distField[i];
+        if (c < cols - 1) v = Math.min(v, distField[i + 1] + d1);
+        if (r < rows - 1) {
+          v = Math.min(v, distField[i + cols] + d1);
+          if (c < cols - 1) v = Math.min(v, distField[i + cols + 1] + d2);
+          if (c > 0) v = Math.min(v, distField[i + cols - 1] + d2);
+        }
+        distField[i] = v;
+      }
+    }
+
+    // 2. Base wind vector (blows towards toRad)
+    const toRad = (((windFromDeg + 180) % 360) * Math.PI) / 180;
+    const wx = Math.sin(toRad); // +x = east
+    const wy = Math.cos(toRad); // +y = north
+
+    // Helper to evaluate local deflected velocity and speed at world coordinate (x, y)
+    const sampleFlow = (x, y) => {
+      const col = (x - minX) / cell - 0.5;
+      const row = (maxY - y) / cell - 0.5;
+      const ic = Math.max(0, Math.min(cols - 1, Math.round(col)));
+      const ir = Math.max(0, Math.min(rows - 1, Math.round(row)));
+      const idx = ir * cols + ic;
+
+      const dVal = distField[idx];
+      const cl = Math.max(0, ic - 1);
+      const cr = Math.min(cols - 1, ic + 1);
+      const ru = Math.max(0, ir - 1);
+      const rd = Math.min(rows - 1, ir + 1);
+
+      // Distance gradient pointing away from obstacle
+      const gradX = (distField[ir * cols + cr] - distField[ir * cols + cl]) / (cell * Math.max(1, cr - cl));
+      const gradY = -(distField[rd * cols + ic] - distField[ru * cols + ic]) / (cell * Math.max(1, rd - ru));
+      const gLen = Math.hypot(gradX, gradY);
+
+      let vx = wx;
+      let vy = wy;
+
+      if (dVal < 4 * cell && gLen > 1e-4) {
+        const nx = gradX / gLen;
+        const ny = gradY / gLen;
+        const dot = wx * nx + wy * ny;
+        if (dot < 0) {
+          // Deflect along the obstacle tangent
+          const tx = -ny;
+          const ty = nx;
+          const sign = (wx * tx + wy * ty >= 0) ? 1 : -1;
+          const tanX = sign * tx;
+          const tanY = sign * ty;
+          const blend = Math.exp(-dVal / (1.5 * cell));
+          vx = (1 - blend) * wx + blend * tanX;
+          vy = (1 - blend) * wy + blend * tanY;
+        }
+      }
+
+      const vLen = Math.hypot(vx, vy);
+      if (vLen > 1e-5) {
+        vx /= vLen;
+        vy /= vLen;
+      }
+
+      const rawRatio = Number.isFinite(values[idx]) ? values[idx] : 0.8;
+      const spd = speed10 * Math.max(0.1, Math.min(2.0, rawRatio));
+      return { vx, vy, speed: spd };
+    };
+
+    // 3. Find open seed locations
+    const openCells = [];
+    for (let r = 0; r < rows; r++) {
+      for (let c = 0; c < cols; c++) {
+        if (distField[r * cols + c] > cell * 0.4) {
+          openCells.push({ c, r });
+        }
+      }
+    }
+    if (openCells.length === 0) return;
+
+    // 4. Trace count streamlines
+    const stops = rampStops('spectral-r');
+    const stepDist = cell * 1.0;
+    const streamlines = [];
+
+    for (let s = 0; s < count; s++) {
+      const seedCell = openCells[Math.floor(Math.random() * openCells.length)];
+      let curX = minX + (seedCell.c + 0.5 + (Math.random() - 0.5) * 0.6) * cell;
+      let curY = maxY - (seedCell.r + 0.5 + (Math.random() - 0.5) * 0.6) * cell;
+
+      const pts = [];
+      let speedSum = 0;
+
+      for (let step = 0; step < trailSteps; step++) {
+        const flow = sampleFlow(curX, curY);
+        speedSum += flow.speed;
+
+        const ground = (this.app?.terrain?.groundY) ? this.app.terrain.groundY(curX, curY) : 0;
+        // Three.js scene axes: +x east, +y up, -z north
+        const threeX = curX;
+        const threeY = ground + 1.8;
+        const threeZ = -curY;
+
+        const normSpeed = Math.max(0, Math.min(1, flow.speed / (speed10 * 1.6)));
+        const col = rampColor(stops, normSpeed);
+
+        pts.push({
+          pos: [threeX, threeY, threeZ],
+          col: [col[0], col[1], col[2]],
+          speed: flow.speed
+        });
+
+        curX += flow.vx * stepDist;
+        curY += flow.vy * stepDist;
+
+        // A streamline that leaves the grid ends there; respawning it inside
+        // would draw a stray segment from the edge to the new point.
+        if (curX < minX || curX > minX + cols * cell || curY < maxY - rows * cell || curY > maxY) break;
+      }
+
+      streamlines.push({
+        pts,
+        meanSpeed: speedSum / pts.length,
+        phase: Math.random()
+      });
+    }
+
+    // 5. Construct THREE.LineSegments geometry for animated streaks
+    // Each streamline renders an animated head-tail streak of sub-segments
+    const segmentsPerStreak = 3;
+    const vertexCount = count * segmentsPerStreak * 2;
+    const positions = new Float32Array(vertexCount * 3);
+    const colors = new Float32Array(vertexCount * 3);
+
+    const geometry = new THREE.BufferGeometry();
+    const posAttr = new THREE.BufferAttribute(positions, 3);
+    const colAttr = new THREE.BufferAttribute(colors, 3);
+    geometry.setAttribute('position', posAttr);
+    geometry.setAttribute('color', colAttr);
+
+    const material = new THREE.LineBasicMaterial({
+      vertexColors: true,
+      transparent: true,
+      opacity: 0.88,
+      depthWrite: false
+    });
+
+    const lines = new THREE.LineSegments(geometry, material);
+    lines.name = 'streamlines_mesh';
+    this.group.add(lines);
+
+    if (this.app?.viewer?.helpers && this.group.parent !== this.app.viewer.helpers) {
+      this.app.viewer.helpers.add(this.group);
+    }
+
+    // 6. Animation loop advancing phase along each streamline
+    this._lastTime = performance.now();
+
+    const animateLoop = (time) => {
+      if (!this.active) return;
+      // Paused while an analysis runs: every frame redraws the whole scene,
+      // which competes with the analysis for the GPU and the main thread
+      // (six times slower in a software-rendered test).
+      if (this.app?.busy) {
+        this._lastTime = time;
+        this._raf = getRaf()(animateLoop);
+        return;
+      }
+
+      const dt = Math.min(0.05, (time - this._lastTime) * 0.001);
+      this._lastTime = time;
+
+      let vOffset = 0;
+
+      for (let s = 0; s < count; s++) {
+        const sl = streamlines[s];
+        sl.phase = (sl.phase + dt * (sl.meanSpeed / Math.max(1, speed10)) * 0.35) % 1.0;
+
+        const numPts = sl.pts.length;
+        const headIdxFloat = sl.phase * (numPts - 1);
+
+        for (let seg = 0; seg < segmentsPerStreak; seg++) {
+          const tailFrac = seg / segmentsPerStreak;
+          const nextFrac = (seg + 1) / segmentsPerStreak;
+
+          const p0Index = Math.max(0, Math.min(numPts - 1, Math.floor(headIdxFloat - (1 - tailFrac) * 3)));
+          const p1Index = Math.max(0, Math.min(numPts - 1, Math.floor(headIdxFloat - (1 - nextFrac) * 3)));
+
+          const ptA = sl.pts[p0Index];
+          const ptB = sl.pts[p1Index];
+
+          const alphaA = 0.2 + 0.8 * tailFrac;
+          const alphaB = 0.2 + 0.8 * nextFrac;
+
+          // Vertex 1
+          positions[vOffset] = ptA.pos[0];
+          positions[vOffset + 1] = ptA.pos[1];
+          positions[vOffset + 2] = ptA.pos[2];
+          colors[vOffset] = ptA.col[0] * alphaA;
+          colors[vOffset + 1] = ptA.col[1] * alphaA;
+          colors[vOffset + 2] = ptA.col[2] * alphaA;
+
+          // Vertex 2
+          positions[vOffset + 3] = ptB.pos[0];
+          positions[vOffset + 4] = ptB.pos[1];
+          positions[vOffset + 5] = ptB.pos[2];
+          colors[vOffset + 3] = ptB.col[0] * alphaB;
+          colors[vOffset + 4] = ptB.col[1] * alphaB;
+          colors[vOffset + 5] = ptB.col[2] * alphaB;
+
+          vOffset += 6;
+        }
+      }
+
+      posAttr.needsUpdate = true;
+      colAttr.needsUpdate = true;
+
+      if (this.app?.viewer?.requestRender) {
+        this.app.viewer.requestRender();
+      }
+
+      this._raf = getRaf()(animateLoop);
+    };
+
+    this._raf = getRaf()(animateLoop);
+  }
+
+  /**
+   * Stops animation, clears geometry and removes streamlines from the viewer.
+   */
+  hide() {
+    this.active = false;
+    if (this._raf) {
+      getCaf()(this._raf);
+      this._raf = 0;
+    }
+
+    if (this.group.parent) {
+      this.group.parent.remove(this.group);
+    }
+
+    this._dispose();
+
+    if (this.app?.viewer?.requestRender) {
+      this.app.viewer.requestRender();
+    }
+  }
+
+  /**
+   * Internal cleanup of Three.js geometries and materials.
+   * @private
+   */
+  _dispose() {
+    while (this.group.children.length > 0) {
+      const child = /** @type {any} */ (this.group.children[0]);
+      this.group.remove(child);
+      if (child.geometry) child.geometry.dispose();
+      if (child.material) {
+        if (Array.isArray(child.material)) child.material.forEach((m) => m.dispose());
+        else child.material.dispose();
+      }
+    }
+  }
+}