@d5techs/3dgs-lib 1.1.0 → 1.1.1

package/dist/3dgs-lib.js

@@ -53,7 +53,7 @@ function computeBoundingBox$1(positions) {
     };
   }
   const min = [positions[0], positions[1], positions[2]];
-  const max = [positions[0], positions[1], positions[2]];
+  const max2 = [positions[0], positions[1], positions[2]];
   for (let i = 3; i < positions.length; i += 3) {
     const x = positions[i];
     const y = positions[i + 1];
@@ -61,20 +61,20 @@ function computeBoundingBox$1(positions) {
     min[0] = Math.min(min[0], x);
     min[1] = Math.min(min[1], y);
     min[2] = Math.min(min[2], z);
-    max[0] = Math.max(max[0], x);
-    max[1] = Math.max(max[1], y);
-    max[2] = Math.max(max[2], z);
+    max2[0] = Math.max(max2[0], x);
+    max2[1] = Math.max(max2[1], y);
+    max2[2] = Math.max(max2[2], z);
   }
   const center = [
-    (min[0] + max[0]) / 2,
-    (min[1] + max[1]) / 2,
-    (min[2] + max[2]) / 2
+    (min[0] + max2[0]) / 2,
+    (min[1] + max2[1]) / 2,
+    (min[2] + max2[2]) / 2
   ];
-  const dx = max[0] - min[0];
-  const dy = max[1] - min[1];
-  const dz = max[2] - min[2];
+  const dx = max2[0] - min[0];
+  const dy = max2[1] - min[1];
+  const dz = max2[2] - min[2];
   const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
-  return { min, max, center, radius };
+  return { min, max: max2, center, radius };
 }
 function mergeBoundingBoxes(boxes) {
   if (boxes.length === 0) return null;
@@ -100,17 +100,17 @@ function mergeBoundingBoxes(boxes) {
   const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
   return { min: combinedMin, max: combinedMax, center, radius };
 }
-function createBoundingBoxFromMinMax(min, max) {
+function createBoundingBoxFromMinMax(min, max2) {
   const center = [
-    (min[0] + max[0]) / 2,
-    (min[1] + max[1]) / 2,
-    (min[2] + max[2]) / 2
+    (min[0] + max2[0]) / 2,
+    (min[1] + max2[1]) / 2,
+    (min[2] + max2[2]) / 2
   ];
-  const dx = max[0] - min[0];
-  const dy = max[1] - min[1];
-  const dz = max[2] - min[2];
+  const dx = max2[0] - min[0];
+  const dy = max2[1] - min[1];
+  const dz = max2[2] - min[2];
   const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
-  return { min, max, center, radius };
+  return { min, max: max2, center, radius };
 }
 function transformBoundingBox(bbox, modelMatrix) {
   const corners = [
@@ -438,10 +438,8 @@ class Camera {
     __publicField(this, "fov", Math.PI / 4);
     // 45度
     __publicField(this, "aspect", 1);
-    __publicField(this, "near", 0.1);
-    // 增大近平面以提高深度精度 (参考实现使用 0.1)
-    __publicField(this, "far", 1e3);
-    // 减小远平面以提高深度精度
+    __publicField(this, "near", 0.01);
+    __publicField(this, "far", 9e3);
     // 矩阵
     __publicField(this, "viewMatrix", new Float32Array(16));
     __publicField(this, "projectionMatrix", new Float32Array(16));
@@ -550,9 +548,7 @@ class OrbitControls {
     // 球坐标参数
     __publicField(this, "distance", 5);
     __publicField(this, "theta", 0);
-    // 水平角 (绕Y轴)
     __publicField(this, "phi", Math.PI / 4);
-    // 垂直角 (从Y轴向下)
     // 限制
     __publicField(this, "minDistance", 1e-3);
     __publicField(this, "maxDistance", Infinity);
@@ -565,10 +561,20 @@ class OrbitControls {
     // 移动端触摸灵敏度
     __publicField(this, "touchZoomSpeed", 0.01);
     __publicField(this, "touchPanSpeed", 3e-3);
+    // 阻尼（值越大越灵敏，越小越丝滑；0.12 约 5 帧消化 50% 增量）
+    __publicField(this, "enableDamping", true);
+    __publicField(this, "dampingFactor", 0.12);
     // 状态
     __publicField(this, "isDragging", false);
     __publicField(this, "lastX", 0);
     __publicField(this, "lastY", 0);
+    // 阻尼速度
+    __publicField(this, "velocityTheta", 0);
+    __publicField(this, "velocityPhi", 0);
+    __publicField(this, "velocityDistance", 0);
+    __publicField(this, "velocityPanX", 0);
+    __publicField(this, "velocityPanY", 0);
+    __publicField(this, "velocityPanZ", 0);
     // 触摸手势状态
     __publicField(this, "touchMode", "none");
     __publicField(this, "lastTouchDistance", 0);
@@ -595,11 +601,8 @@ class OrbitControls {
     this.boundOnTouchEnd = this.onTouchEnd.bind(this);
     this.boundOnContextMenu = (e) => e.preventDefault();
     this.setupEventListeners();
-    this.update();
+    this.applySpherical();
   }
-  /**
-   * 设置事件监听
-   */
   setupEventListeners() {
     this.canvas.addEventListener("mousedown", this.boundOnMouseDown);
     this.canvas.addEventListener("mousemove", this.boundOnMouseMove);
@@ -617,9 +620,6 @@ class OrbitControls {
     this.canvas.addEventListener("touchend", this.boundOnTouchEnd);
     this.canvas.addEventListener("contextmenu", this.boundOnContextMenu);
   }
-  /**
-   * 移除事件监听
-   */
   removeEventListeners() {
     this.canvas.removeEventListener("mousedown", this.boundOnMouseDown);
     this.canvas.removeEventListener("mousemove", this.boundOnMouseMove);
@@ -631,12 +631,37 @@ class OrbitControls {
     this.canvas.removeEventListener("touchend", this.boundOnTouchEnd);
     this.canvas.removeEventListener("contextmenu", this.boundOnContextMenu);
   }
-  /**
-   * 销毁控制器
-   */
   destroy() {
     this.removeEventListeners();
   }
+  /**
+   * 从视图矩阵提取相机的 right 和 up 向量，用于屏幕空间平移
+   */
+  getCameraAxes() {
+    const m = this.camera.viewMatrix;
+    return {
+      right: [m[0], m[4], m[8]],
+      up: [m[1], m[5], m[9]]
+    };
+  }
+  /**
+   * 屏幕空间平移：将屏幕 delta 映射到相机 right/up 方向
+   */
+  panByScreenDelta(deltaX, deltaY) {
+    const { right, up } = this.getCameraAxes();
+    const scale = this.panSpeed * this.distance;
+    const dx = -deltaX * scale;
+    const dy = deltaY * scale;
+    if (this.enableDamping) {
+      this.velocityPanX += dx * right[0] + dy * up[0];
+      this.velocityPanY += dx * right[1] + dy * up[1];
+      this.velocityPanZ += dx * right[2] + dy * up[2];
+    } else {
+      this.camera.target[0] += dx * right[0] + dy * up[0];
+      this.camera.target[1] += dx * right[1] + dy * up[1];
+      this.camera.target[2] += dx * right[2] + dy * up[2];
+    }
+  }
   onMouseDown(e) {
     if (!this.enabled) return;
     this.isDragging = true;
@@ -650,19 +675,20 @@ class OrbitControls {
     this.lastX = e.clientX;
     this.lastY = e.clientY;
     if (e.buttons === 1) {
-      this.theta -= deltaX * this.rotateSpeed;
-      this.phi -= deltaY * this.rotateSpeed;
-      this.phi = Math.max(this.minPhi, Math.min(this.maxPhi, this.phi));
-    } else if (e.buttons === 2) {
-      const panX = -deltaX * this.panSpeed * this.distance;
-      const panY = deltaY * this.panSpeed * this.distance;
-      const sinTheta = Math.sin(this.theta);
-      const cosTheta = Math.cos(this.theta);
-      this.camera.target[0] += panX * cosTheta;
-      this.camera.target[2] += panX * sinTheta;
-      this.camera.target[1] += panY;
+      if (this.enableDamping) {
+        this.velocityTheta += -deltaX * this.rotateSpeed;
+        this.velocityPhi += -deltaY * this.rotateSpeed;
+      } else {
+        this.theta -= deltaX * this.rotateSpeed;
+        this.phi -= deltaY * this.rotateSpeed;
+        this.phi = Math.max(this.minPhi, Math.min(this.maxPhi, this.phi));
+      }
+    } else if (e.buttons === 2 || e.buttons === 4) {
+      this.panByScreenDelta(deltaX, deltaY);
+    }
+    if (!this.enableDamping) {
+      this.applySpherical();
     }
-    this.update();
   }
   onMouseUp() {
     this.isDragging = false;
@@ -670,12 +696,17 @@ class OrbitControls {
   onWheel(e) {
     e.preventDefault();
     if (!this.enabled) return;
-    this.distance += e.deltaY * this.zoomSpeed * this.distance;
-    this.distance = Math.max(
-      this.minDistance,
-      Math.min(this.maxDistance, this.distance)
-    );
-    this.update();
+    const zoomDelta = e.deltaY * this.zoomSpeed;
+    if (this.enableDamping) {
+      this.velocityDistance += zoomDelta;
+    } else {
+      this.distance *= Math.exp(zoomDelta);
+      this.distance = Math.max(
+        this.minDistance,
+        Math.min(this.maxDistance, this.distance)
+      );
+      this.applySpherical();
+    }
   }
   onTouchStart(e) {
     e.preventDefault();
@@ -700,33 +731,51 @@ class OrbitControls {
       const deltaY = e.touches[0].clientY - this.lastY;
       this.lastX = e.touches[0].clientX;
       this.lastY = e.touches[0].clientY;
-      this.theta -= deltaX * this.rotateSpeed;
-      this.phi -= deltaY * this.rotateSpeed;
-      this.phi = Math.max(this.minPhi, Math.min(this.maxPhi, this.phi));
-      this.update();
+      if (this.enableDamping) {
+        this.velocityTheta += -deltaX * this.rotateSpeed;
+        this.velocityPhi += -deltaY * this.rotateSpeed;
+      } else {
+        this.theta -= deltaX * this.rotateSpeed;
+        this.phi -= deltaY * this.rotateSpeed;
+        this.phi = Math.max(this.minPhi, Math.min(this.maxPhi, this.phi));
+        this.applySpherical();
+      }
     } else if (e.touches.length === 2) {
       const currentDistance = this.getTouchDistance(e.touches);
       const currentCenter = this.getTouchCenter(e.touches);
       if (this.lastTouchDistance > 0) {
-        const scale = this.lastTouchDistance / currentDistance;
-        this.distance *= Math.pow(scale, this.touchZoomSpeed * 100);
-        this.distance = Math.max(
-          this.minDistance,
-          Math.min(this.maxDistance, this.distance)
-        );
+        const ratio = currentDistance / this.lastTouchDistance;
+        const zoomDelta = -Math.log(ratio) / (this.touchZoomSpeed * 100);
+        if (this.enableDamping) {
+          this.velocityDistance += zoomDelta;
+        } else {
+          this.distance *= Math.exp(zoomDelta);
+          this.distance = Math.max(
+            this.minDistance,
+            Math.min(this.maxDistance, this.distance)
+          );
+        }
       }
       const deltaX = currentCenter.x - this.lastTouchCenter.x;
       const deltaY = currentCenter.y - this.lastTouchCenter.y;
-      const panX = -deltaX * this.touchPanSpeed * this.distance;
-      const panY = deltaY * this.touchPanSpeed * this.distance;
-      const sinTheta = Math.sin(this.theta);
-      const cosTheta = Math.cos(this.theta);
-      this.camera.target[0] += panX * cosTheta;
-      this.camera.target[2] += panX * sinTheta;
-      this.camera.target[1] += panY;
+      const { right, up } = this.getCameraAxes();
+      const scale = this.touchPanSpeed * this.distance;
+      const dx = -deltaX * scale;
+      const dy = deltaY * scale;
+      if (this.enableDamping) {
+        this.velocityPanX += dx * right[0] + dy * up[0];
+        this.velocityPanY += dx * right[1] + dy * up[1];
+        this.velocityPanZ += dx * right[2] + dy * up[2];
+      } else {
+        this.camera.target[0] += dx * right[0] + dy * up[0];
+        this.camera.target[1] += dx * right[1] + dy * up[1];
+        this.camera.target[2] += dx * right[2] + dy * up[2];
+      }
       this.lastTouchDistance = currentDistance;
       this.lastTouchCenter = currentCenter;
-      this.update();
+      if (!this.enableDamping) {
+        this.applySpherical();
+      }
     }
   }
   onTouchEnd(e) {
@@ -740,17 +789,11 @@ class OrbitControls {
       this.lastY = e.touches[0].clientY;
     }
   }
-  /**
-   * 计算双指之间的距离
-   */
   getTouchDistance(touches) {
     const dx = touches[0].clientX - touches[1].clientX;
     const dy = touches[0].clientY - touches[1].clientY;
     return Math.sqrt(dx * dx + dy * dy);
   }
-  /**
-   * 计算双指的中心点
-   */
   getTouchCenter(touches) {
     return {
       x: (touches[0].clientX + touches[1].clientX) / 2,
@@ -758,9 +801,9 @@ class OrbitControls {
     };
   }
   /**
-   * 根据球坐标更新相机位置
+   * 将球坐标写入相机位置（内部方法，不处理阻尼）
    */
-  update() {
+  applySpherical() {
     const sinPhi = Math.sin(this.phi);
     const cosPhi = Math.cos(this.phi);
     const sinTheta = Math.sin(this.theta);
@@ -771,12 +814,42 @@ class OrbitControls {
     this.camera.updateMatrix();
   }
   /**
-   * 切换到标准视图
-   * @param axis 轴 'X' | 'Y' | 'Z'
-   * @param positive 是否正向
-   * @param animate 是否动画过渡
+   * 每帧调用：应用阻尼衰减并更新相机
+   * 在渲染循环中调用此方法以获得平滑惯性效果
    */
+  update() {
+    if (this.enableDamping) {
+      const EPS = 1e-6;
+      const f = this.dampingFactor;
+      this.theta += this.velocityTheta * f;
+      this.phi += this.velocityPhi * f;
+      this.phi = Math.max(this.minPhi, Math.min(this.maxPhi, this.phi));
+      this.distance *= Math.exp(this.velocityDistance * f);
+      this.distance = Math.max(
+        this.minDistance,
+        Math.min(this.maxDistance, this.distance)
+      );
+      this.camera.target[0] += this.velocityPanX * f;
+      this.camera.target[1] += this.velocityPanY * f;
+      this.camera.target[2] += this.velocityPanZ * f;
+      const decay = 1 - f;
+      this.velocityTheta *= decay;
+      this.velocityPhi *= decay;
+      this.velocityDistance *= decay;
+      this.velocityPanX *= decay;
+      this.velocityPanY *= decay;
+      this.velocityPanZ *= decay;
+      if (Math.abs(this.velocityTheta) < EPS) this.velocityTheta = 0;
+      if (Math.abs(this.velocityPhi) < EPS) this.velocityPhi = 0;
+      if (Math.abs(this.velocityDistance) < EPS) this.velocityDistance = 0;
+      if (Math.abs(this.velocityPanX) < EPS) this.velocityPanX = 0;
+      if (Math.abs(this.velocityPanY) < EPS) this.velocityPanY = 0;
+      if (Math.abs(this.velocityPanZ) < EPS) this.velocityPanZ = 0;
+    }
+    this.applySpherical();
+  }
   setViewAxis(axis, positive, animate = true) {
+    this.clearVelocity();
     let targetTheta = this.theta;
     let targetPhi = this.phi;
     switch (axis) {
@@ -797,12 +870,9 @@ class OrbitControls {
     } else {
       this.theta = targetTheta;
       this.phi = targetPhi;
-      this.update();
+      this.applySpherical();
     }
   }
-  /**
-   * 动画过渡到目标视图
-   */
   animateToView(targetTheta, targetPhi) {
     const startTheta = this.theta;
     const startPhi = this.phi;
@@ -817,28 +887,20 @@ class OrbitControls {
       const eased = 1 - Math.pow(1 - progress, 3);
       this.theta = startTheta + deltaTheta * eased;
       this.phi = startPhi + (targetPhi - startPhi) * eased;
-      this.update();
+      this.applySpherical();
       if (progress < 1) {
         requestAnimationFrame(animate);
       }
     };
     requestAnimationFrame(animate);
   }
-  /**
-   * 设置相机目标点（控制器旋转中心）
-   * @param x X 坐标
-   * @param y Y 坐标
-   * @param z Z 坐标
-   */
   setTarget(x, y, z) {
+    this.clearVelocity();
     this.camera.target[0] = x;
     this.camera.target[1] = y;
     this.camera.target[2] = z;
-    this.update();
+    this.applySpherical();
   }
-  /**
-   * 获取当前目标点
-   */
   getTarget() {
     return [
       this.camera.target[0],
@@ -846,13 +908,8 @@ class OrbitControls {
       this.camera.target[2]
     ];
   }
-  /**
-   * 根据模型参数自动调整相机位置和参数
-   * @param center 模型中心点
-   * @param radius 模型包围球半径
-   * @param animate 是否使用动画过渡
-   */
   frameModel(center, radius, animate = true) {
+    this.clearVelocity();
     const fovRad = this.camera.fov;
     const halfFov = fovRad / 2;
     const marginFactor = 1.5;
@@ -865,12 +922,9 @@ class OrbitControls {
       this.camera.target[1] = center[1];
       this.camera.target[2] = center[2];
       this.distance = clampedDistance;
-      this.update();
+      this.applySpherical();
     }
   }
-  /**
-   * 动画过渡到目标帧（包含目标点和距离）
-   */
   animateToFrame(targetCenter, targetDistance) {
     const startTarget = [
       this.camera.target[0],
@@ -888,13 +942,21 @@ class OrbitControls {
       this.camera.target[1] = startTarget[1] + (targetCenter[1] - startTarget[1]) * eased;
       this.camera.target[2] = startTarget[2] + (targetCenter[2] - startTarget[2]) * eased;
       this.distance = startDistance + (targetDistance - startDistance) * eased;
-      this.update();
+      this.applySpherical();
       if (progress < 1) {
         requestAnimationFrame(animate);
       }
     };
     requestAnimationFrame(animate);
   }
+  clearVelocity() {
+    this.velocityTheta = 0;
+    this.velocityPhi = 0;
+    this.velocityDistance = 0;
+    this.velocityPanX = 0;
+    this.velocityPanY = 0;
+    this.velocityPanZ = 0;
+  }
 }
 const gizmoShaderCode = (
   /* wgsl */
@@ -1557,11 +1619,11 @@ class BoundingBoxRenderer {
    * 生成顶点数据
    */
   generateVertices(box) {
-    const { min, max } = box;
+    const { min, max: max2 } = box;
     const [r, g, b] = this.lineColor;
-    const dx = max[0] - min[0];
-    const dy = max[1] - min[1];
-    const dz = max[2] - min[2];
+    const dx = max2[0] - min[0];
+    const dy = max2[1] - min[1];
+    const dz = max2[2] - min[2];
     const lx = dx * this.cornerRatio;
     const ly = dy * this.cornerRatio;
     const lz = dz * this.cornerRatio;
@@ -1573,27 +1635,27 @@ class BoundingBoxRenderer {
     addLine(min[0], min[1], min[2], min[0] + lx, min[1], min[2]);
     addLine(min[0], min[1], min[2], min[0], min[1] + ly, min[2]);
     addLine(min[0], min[1], min[2], min[0], min[1], min[2] + lz);
-    addLine(max[0], min[1], min[2], max[0] - lx, min[1], min[2]);
-    addLine(max[0], min[1], min[2], max[0], min[1] + ly, min[2]);
-    addLine(max[0], min[1], min[2], max[0], min[1], min[2] + lz);
-    addLine(min[0], max[1], min[2], min[0] + lx, max[1], min[2]);
-    addLine(min[0], max[1], min[2], min[0], max[1] - ly, min[2]);
-    addLine(min[0], max[1], min[2], min[0], max[1], min[2] + lz);
-    addLine(max[0], max[1], min[2], max[0] - lx, max[1], min[2]);
-    addLine(max[0], max[1], min[2], max[0], max[1] - ly, min[2]);
-    addLine(max[0], max[1], min[2], max[0], max[1], min[2] + lz);
-    addLine(min[0], min[1], max[2], min[0] + lx, min[1], max[2]);
-    addLine(min[0], min[1], max[2], min[0], min[1] + ly, max[2]);
-    addLine(min[0], min[1], max[2], min[0], min[1], max[2] - lz);
-    addLine(max[0], min[1], max[2], max[0] - lx, min[1], max[2]);
-    addLine(max[0], min[1], max[2], max[0], min[1] + ly, max[2]);
-    addLine(max[0], min[1], max[2], max[0], min[1], max[2] - lz);
-    addLine(min[0], max[1], max[2], min[0] + lx, max[1], max[2]);
-    addLine(min[0], max[1], max[2], min[0], max[1] - ly, max[2]);
-    addLine(min[0], max[1], max[2], min[0], max[1], max[2] - lz);
-    addLine(max[0], max[1], max[2], max[0] - lx, max[1], max[2]);
-    addLine(max[0], max[1], max[2], max[0], max[1] - ly, max[2]);
-    addLine(max[0], max[1], max[2], max[0], max[1], max[2] - lz);
+    addLine(max2[0], min[1], min[2], max2[0] - lx, min[1], min[2]);
+    addLine(max2[0], min[1], min[2], max2[0], min[1] + ly, min[2]);
+    addLine(max2[0], min[1], min[2], max2[0], min[1], min[2] + lz);
+    addLine(min[0], max2[1], min[2], min[0] + lx, max2[1], min[2]);
+    addLine(min[0], max2[1], min[2], min[0], max2[1] - ly, min[2]);
+    addLine(min[0], max2[1], min[2], min[0], max2[1], min[2] + lz);
+    addLine(max2[0], max2[1], min[2], max2[0] - lx, max2[1], min[2]);
+    addLine(max2[0], max2[1], min[2], max2[0], max2[1] - ly, min[2]);
+    addLine(max2[0], max2[1], min[2], max2[0], max2[1], min[2] + lz);
+    addLine(min[0], min[1], max2[2], min[0] + lx, min[1], max2[2]);
+    addLine(min[0], min[1], max2[2], min[0], min[1] + ly, max2[2]);
+    addLine(min[0], min[1], max2[2], min[0], min[1], max2[2] - lz);
+    addLine(max2[0], min[1], max2[2], max2[0] - lx, min[1], max2[2]);
+    addLine(max2[0], min[1], max2[2], max2[0], min[1] + ly, max2[2]);
+    addLine(max2[0], min[1], max2[2], max2[0], min[1], max2[2] - lz);
+    addLine(min[0], max2[1], max2[2], min[0] + lx, max2[1], max2[2]);
+    addLine(min[0], max2[1], max2[2], min[0], max2[1] - ly, max2[2]);
+    addLine(min[0], max2[1], max2[2], min[0], max2[1], max2[2] - lz);
+    addLine(max2[0], max2[1], max2[2], max2[0] - lx, max2[1], max2[2]);
+    addLine(max2[0], max2[1], max2[2], max2[0], max2[1] - ly, max2[2]);
+    addLine(max2[0], max2[1], max2[2], max2[0], max2[1], max2[2] - lz);
     return new Float32Array(vertices);
   }
   /**
@@ -1906,6 +1968,7 @@ class MeshRenderer {
     __publicField(this, "renderer");
     __publicField(this, "camera");
     __publicField(this, "items", []);
+    __publicField(this, "overlayItems", []);
     // 有纹理的管线
     __publicField(this, "pipelineTextured");
     __publicField(this, "pipelineTexturedDoubleSided");
@@ -1914,6 +1977,11 @@ class MeshRenderer {
     __publicField(this, "pipelineUntextured");
     __publicField(this, "pipelineUntexturedDoubleSided");
     __publicField(this, "bindGroupLayoutUntextured");
+    // 覆盖层管线（带 depthBias，用于贴面热点/指示器）
+    __publicField(this, "overlayPipelineTextured");
+    __publicField(this, "overlayPipelineTexturedDoubleSided");
+    __publicField(this, "overlayPipelineUntextured");
+    __publicField(this, "overlayPipelineUntexturedDoubleSided");
     __publicField(this, "sampler");
     __publicField(this, "defaultTexture");
     // 光照方向
@@ -1967,6 +2035,19 @@ class MeshRenderer {
         { shaderLocation: 2, offset: 24, format: "float32x2" }
       ]
     };
+    const depthStencilNormal = {
+      format: this.renderer.depthFormat,
+      depthWriteEnabled: true,
+      depthCompare: "less"
+    };
+    const depthStencilOverlay = {
+      format: this.renderer.depthFormat,
+      depthWriteEnabled: false,
+      depthCompare: "less",
+      depthBias: -2e3,
+      depthBiasSlopeScale: -4,
+      depthBiasClamp: 0
+    };
     const basePipelineDescTextured = {
       layout: pipelineLayoutTextured,
       vertex: {
@@ -1980,7 +2061,7 @@ class MeshRenderer {
         targets: [{ format: this.renderer.format }]
       },
       primitive: { topology: "triangle-list", frontFace: "ccw" },
-      depthStencil: { format: this.renderer.depthFormat, depthWriteEnabled: true, depthCompare: "less" }
+      depthStencil: depthStencilNormal
     };
     this.pipelineTextured = device.createRenderPipeline({
       ...basePipelineDescTextured,
@@ -1990,6 +2071,15 @@ class MeshRenderer {
       ...basePipelineDescTextured,
       primitive: { ...basePipelineDescTextured.primitive, cullMode: "none" }
     });
+    const overlayDescTextured = { ...basePipelineDescTextured, depthStencil: depthStencilOverlay };
+    this.overlayPipelineTextured = device.createRenderPipeline({
+      ...overlayDescTextured,
+      primitive: { ...overlayDescTextured.primitive, cullMode: "back" }
+    });
+    this.overlayPipelineTexturedDoubleSided = device.createRenderPipeline({
+      ...overlayDescTextured,
+      primitive: { ...overlayDescTextured.primitive, cullMode: "none" }
+    });
     const shaderModuleUntextured = device.createShaderModule({ code: shaderCodeUntextured });
     this.bindGroupLayoutUntextured = device.createBindGroupLayout({
       entries: [
@@ -2019,7 +2109,7 @@ class MeshRenderer {
         targets: [{ format: this.renderer.format }]
       },
       primitive: { topology: "triangle-list", frontFace: "ccw" },
-      depthStencil: { format: this.renderer.depthFormat, depthWriteEnabled: true, depthCompare: "less" }
+      depthStencil: depthStencilNormal
     };
     this.pipelineUntextured = device.createRenderPipeline({
       ...basePipelineDescUntextured,
@@ -2029,6 +2119,15 @@ class MeshRenderer {
       ...basePipelineDescUntextured,
       primitive: { ...basePipelineDescUntextured.primitive, cullMode: "none" }
     });
+    const overlayDescUntextured = { ...basePipelineDescUntextured, depthStencil: depthStencilOverlay };
+    this.overlayPipelineUntextured = device.createRenderPipeline({
+      ...overlayDescUntextured,
+      primitive: { ...overlayDescUntextured.primitive, cullMode: "back" }
+    });
+    this.overlayPipelineUntexturedDoubleSided = device.createRenderPipeline({
+      ...overlayDescUntextured,
+      primitive: { ...overlayDescUntextured.primitive, cullMode: "none" }
+    });
   }
   /**
    * 添加网格（带材质）- 每个 mesh 创建独立的 uniform buffer
@@ -2068,7 +2167,7 @@ class MeshRenderer {
     this.items.push({ mesh, material: mat, uniformBuffer, bindGroup });
   }
   /**
-   * 移除网格
+   * 移除网格（销毁 GPU 资源）
    */
   removeMesh(mesh) {
     const index = this.items.findIndex((item) => item.mesh === mesh);
@@ -2079,6 +2178,65 @@ class MeshRenderer {
       this.items.splice(index, 1);
     }
   }
+  /**
+   * 从渲染列表中分离网格（不销毁 GPU 资源，可重新添加）
+   */
+  detachMesh(mesh) {
+    const index = this.items.findIndex((item) => item.mesh === mesh);
+    if (index !== -1) {
+      const item = this.items[index];
+      item.uniformBuffer.destroy();
+      this.items.splice(index, 1);
+    }
+  }
+  /**
+   * 添加覆盖层网格（使用带 depthBias 的管线，贴面不被 3DGS 深度遮挡）
+   */
+  addOverlayMesh(mesh, material) {
+    const device = this.renderer.device;
+    const mat = material || {
+      baseColorFactor: [0.8, 0.8, 0.8, 1],
+      baseColorTexture: null,
+      metallicFactor: 0,
+      roughnessFactor: 0.5,
+      doubleSided: false
+    };
+    const uniformBuffer = device.createBuffer({
+      size: UNIFORM_BUFFER_SIZE,
+      usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+    });
+    let bindGroup;
+    if (mesh.hasUV) {
+      const texture = mat.baseColorTexture || this.defaultTexture;
+      bindGroup = device.createBindGroup({
+        layout: this.bindGroupLayoutTextured,
+        entries: [
+          { binding: 0, resource: { buffer: uniformBuffer } },
+          { binding: 1, resource: this.sampler },
+          { binding: 2, resource: texture.createView() }
+        ]
+      });
+    } else {
+      bindGroup = device.createBindGroup({
+        layout: this.bindGroupLayoutUntextured,
+        entries: [
+          { binding: 0, resource: { buffer: uniformBuffer } }
+        ]
+      });
+    }
+    this.overlayItems.push({ mesh, material: mat, uniformBuffer, bindGroup });
+  }
+  /**
+   * 从覆盖层列表中分离网格（不销毁 vertex/index buffer）
+   */
+  detachOverlayMesh(mesh) {
+    const index = this.overlayItems.findIndex((item) => item.mesh === mesh);
+    if (index !== -1) {
+      const item = this.overlayItems[index];
+      item.uniformBuffer.destroy();
+      this.overlayItems.splice(index, 1);
+    }
+  }
   /**
    * 按索引移除网格
    */
@@ -2093,7 +2251,7 @@ class MeshRenderer {
     return false;
   }
   /**
-   * 清空所有网格
+   * 清空所有网格（含覆盖层）
    */
   clear() {
     for (const item of this.items) {
@@ -2101,6 +2259,11 @@ class MeshRenderer {
       item.uniformBuffer.destroy();
     }
     this.items = [];
+    for (const item of this.overlayItems) {
+      item.mesh.destroy();
+      item.uniformBuffer.destroy();
+    }
+    this.overlayItems = [];
   }
   /**
    * 设置光照方向
@@ -2124,10 +2287,9 @@ class MeshRenderer {
     return this.ambientIntensity;
   }
   /**
-   * 渲染所有网格
+   * 渲染所有网格（普通 + 覆盖层）
    */
   render(pass) {
-    if (this.items.length === 0) return;
     const device = this.renderer.device;
     const vpMatrix = new Float32Array(this.camera.viewProjectionMatrix);
     const lightData = new Float32Array([
@@ -2136,7 +2298,12 @@ class MeshRenderer {
       this.lightDir[2],
       this.ambientIntensity
     ]);
-    for (const item of this.items) {
+    this.renderItems(pass, this.items, device, vpMatrix, lightData, false);
+    this.renderItems(pass, this.overlayItems, device, vpMatrix, lightData, true);
+  }
+  renderItems(pass, items, device, vpMatrix, lightData, overlay) {
+    if (items.length === 0) return;
+    for (const item of items) {
       const { mesh, material, uniformBuffer, bindGroup } = item;
       device.queue.writeBuffer(uniformBuffer, 0, vpMatrix.buffer);
       device.queue.writeBuffer(uniformBuffer, 64, mesh.modelMatrix.buffer);
@@ -2144,10 +2311,18 @@ class MeshRenderer {
       device.queue.writeBuffer(uniformBuffer, 128, colorData.buffer);
       device.queue.writeBuffer(uniformBuffer, 144, lightData.buffer);
       let pipeline;
-      if (mesh.hasUV) {
-        pipeline = material.doubleSided ? this.pipelineTexturedDoubleSided : this.pipelineTextured;
+      if (overlay) {
+        if (mesh.hasUV) {
+          pipeline = material.doubleSided ? this.overlayPipelineTexturedDoubleSided : this.overlayPipelineTextured;
+        } else {
+          pipeline = material.doubleSided ? this.overlayPipelineUntexturedDoubleSided : this.overlayPipelineUntextured;
+        }
       } else {
-        pipeline = material.doubleSided ? this.pipelineUntexturedDoubleSided : this.pipelineUntextured;
+        if (mesh.hasUV) {
+          pipeline = material.doubleSided ? this.pipelineTexturedDoubleSided : this.pipelineTextured;
+        } else {
+          pipeline = material.doubleSided ? this.pipelineUntexturedDoubleSided : this.pipelineUntextured;
+        }
       }
       pass.setPipeline(pipeline);
       pass.setBindGroup(0, bindGroup);
@@ -2169,18 +2344,12 @@ class MeshRenderer {
     }
     return null;
   }
-  /**
-   * 获取指定索引网格的材质颜色
-   */
   getMeshColor(index) {
     if (index >= 0 && index < this.items.length) {
       return [...this.items[index].material.baseColorFactor];
     }
     return null;
   }
-  /**
-   * 设置指定索引网格的材质颜色
-   */
   setMeshColor(index, r, g, b, a = 1) {
     if (index >= 0 && index < this.items.length) {
       this.items[index].material.baseColorFactor = [r, g, b, a];
@@ -2188,9 +2357,6 @@ class MeshRenderer {
     }
     return false;
   }
-  /**
-   * 设置指定范围内所有网格的材质颜色
-   */
   setMeshRangeColor(startIndex, count, r, g, b, a = 1) {
     let modified = 0;
     for (let i = 0; i < count; i++) {
@@ -2200,6 +2366,50 @@ class MeshRenderer {
     }
     return modified;
   }
+  // ============================================
+  // 覆盖层网格查询 / 颜色 / 删除
+  // ============================================
+  getOverlayMeshCount() {
+    return this.overlayItems.length;
+  }
+  getOverlayMeshByIndex(index) {
+    if (index >= 0 && index < this.overlayItems.length) {
+      return this.overlayItems[index].mesh;
+    }
+    return null;
+  }
+  removeOverlayMeshByIndex(index) {
+    if (index >= 0 && index < this.overlayItems.length) {
+      const item = this.overlayItems[index];
+      item.mesh.destroy();
+      item.uniformBuffer.destroy();
+      this.overlayItems.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  getOverlayMeshColor(index) {
+    if (index >= 0 && index < this.overlayItems.length) {
+      return [...this.overlayItems[index].material.baseColorFactor];
+    }
+    return null;
+  }
+  setOverlayMeshColor(index, r, g, b, a = 1) {
+    if (index >= 0 && index < this.overlayItems.length) {
+      this.overlayItems[index].material.baseColorFactor = [r, g, b, a];
+      return true;
+    }
+    return false;
+  }
+  setOverlayMeshRangeColor(startIndex, count, r, g, b, a = 1) {
+    let modified = 0;
+    for (let i = 0; i < count; i++) {
+      if (this.setOverlayMeshColor(startIndex + i, r, g, b, a)) {
+        modified++;
+      }
+    }
+    return modified;
+  }
   getCombinedBoundingBox() {
     if (this.items.length === 0) return null;
     let combinedMin = null;
@@ -3187,12 +3397,12 @@ class OBJParser {
    * 解析材质引用 (usemtl name)
    */
   parseUseMaterial(parts) {
-    var _a;
+    var _a2;
     if (parts.length > 1) {
       this.currentMaterial = parts.slice(1).join(" ");
       if (this.currentObject && this.currentObject.indices.length > 0) {
         this.finalizeCurrentObject();
-        this.createNewObject(((_a = this.currentObject) == null ? void 0 : _a.name) || "default");
+        this.createNewObject(((_a2 = this.currentObject) == null ? void 0 : _a2.name) || "default");
       }
       if (this.currentObject) {
         this.currentObject.materialName = this.currentMaterial;
@@ -3519,11 +3729,14 @@ class OBJLoader {
       this.device.queue.writeBuffer(indexBuffer, 0, indexData);
     } else {
       const indexData = new Uint16Array(obj.indices);
+      const alignedSize = Math.ceil(indexData.byteLength / 4) * 4;
+      const alignedBuffer = new Uint8Array(alignedSize);
+      alignedBuffer.set(new Uint8Array(indexData.buffer, indexData.byteOffset, indexData.byteLength));
       indexBuffer = this.device.createBuffer({
-        size: indexData.byteLength,
+        size: alignedSize,
         usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST
       });
-      this.device.queue.writeBuffer(indexBuffer, 0, indexData);
+      this.device.queue.writeBuffer(indexBuffer, 0, alignedBuffer);
     }
     const boundingBox = this.computeBoundingBoxFromPositions(obj.positions);
     const mesh = new Mesh(vertexBuffer, vertexCount, indexBuffer, indexCount, boundingBox);
@@ -4009,7 +4222,7 @@ function createSeededRandom(seed) {
     return ((t ^ t >>> 14) >>> 0) / 4294967296;
   };
 }
-const SH_C0 = 0.28209479177387814;
+const SH_C0$1 = 0.28209479177387814;
 function computeImportanceSampling(buffer, dataOffset, stride, totalCount, sampleCount, opacityOffset, opacityType, scale0Offset, scale0Type, scale1Offset, scale1Type, scale2Offset, scale2Type, littleEndian, seed) {
   const dataView = new DataView(buffer, dataOffset);
   const random = createSeededRandom(seed);
@@ -4084,12 +4297,12 @@ async function parsePLYBuffer(buffer, options = {}) {
     propMap.set(prop.name, prop);
   }
   const getOffset = (name) => {
-    var _a;
-    return ((_a = propMap.get(name)) == null ? void 0 : _a.byteOffset) ?? -1;
+    var _a2;
+    return ((_a2 = propMap.get(name)) == null ? void 0 : _a2.byteOffset) ?? -1;
   };
   const getType = (name) => {
-    var _a;
-    return ((_a = propMap.get(name)) == null ? void 0 : _a.type) ?? "float";
+    var _a2;
+    return ((_a2 = propMap.get(name)) == null ? void 0 : _a2.type) ?? "float";
   };
   const offsets = {
     x: getOffset("x"),
@@ -4184,9 +4397,9 @@ async function parsePLYBuffer(buffer, options = {}) {
     const f_dc_0 = offsets.f_dc_0 >= 0 ? readProperty(dataView, base + offsets.f_dc_0, types.f_dc_0, littleEndian) : 0;
     const f_dc_1 = offsets.f_dc_1 >= 0 ? readProperty(dataView, base + offsets.f_dc_1, types.f_dc_1, littleEndian) : 0;
     const f_dc_2 = offsets.f_dc_2 >= 0 ? readProperty(dataView, base + offsets.f_dc_2, types.f_dc_2, littleEndian) : 0;
-    colors[outputIdx * 3 + 0] = 0.5 + SH_C0 * f_dc_0;
-    colors[outputIdx * 3 + 1] = 0.5 + SH_C0 * f_dc_1;
-    colors[outputIdx * 3 + 2] = 0.5 + SH_C0 * f_dc_2;
+    colors[outputIdx * 3 + 0] = 0.5 + SH_C0$1 * f_dc_0;
+    colors[outputIdx * 3 + 1] = 0.5 + SH_C0$1 * f_dc_1;
+    colors[outputIdx * 3 + 2] = 0.5 + SH_C0$1 * f_dc_2;
     const rawOpacity = offsets.opacity >= 0 ? readProperty(dataView, base + offsets.opacity, types.opacity, littleEndian) : 0;
     opacities[outputIdx] = sigmoid(rawOpacity);
     if (shCoeffs && shProps.length > 0) {
@@ -4375,6 +4588,605 @@ function deserializeSplat(data) {
   }
   return splats;
 }
+var u8 = Uint8Array, u16 = Uint16Array, i32 = Int32Array;
+var fleb = new u8([
+  0,
+  0,
+  0,
+  0,
+  0,
+  0,
+  0,
+  0,
+  1,
+  1,
+  1,
+  1,
+  2,
+  2,
+  2,
+  2,
+  3,
+  3,
+  3,
+  3,
+  4,
+  4,
+  4,
+  4,
+  5,
+  5,
+  5,
+  5,
+  0,
+  /* unused */
+  0,
+  0,
+  /* impossible */
+  0
+]);
+var fdeb = new u8([
+  0,
+  0,
+  0,
+  0,
+  1,
+  1,
+  2,
+  2,
+  3,
+  3,
+  4,
+  4,
+  5,
+  5,
+  6,
+  6,
+  7,
+  7,
+  8,
+  8,
+  9,
+  9,
+  10,
+  10,
+  11,
+  11,
+  12,
+  12,
+  13,
+  13,
+  /* unused */
+  0,
+  0
+]);
+var clim = new u8([16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15]);
+var freb = function(eb, start) {
+  var b = new u16(31);
+  for (var i = 0; i < 31; ++i) {
+    b[i] = start += 1 << eb[i - 1];
+  }
+  var r = new i32(b[30]);
+  for (var i = 1; i < 30; ++i) {
+    for (var j = b[i]; j < b[i + 1]; ++j) {
+      r[j] = j - b[i] << 5 | i;
+    }
+  }
+  return { b, r };
+};
+var _a = freb(fleb, 2), fl = _a.b, revfl = _a.r;
+fl[28] = 258, revfl[258] = 28;
+var _b = freb(fdeb, 0), fd = _b.b;
+var rev = new u16(32768);
+for (var i = 0; i < 32768; ++i) {
+  var x = (i & 43690) >> 1 | (i & 21845) << 1;
+  x = (x & 52428) >> 2 | (x & 13107) << 2;
+  x = (x & 61680) >> 4 | (x & 3855) << 4;
+  rev[i] = ((x & 65280) >> 8 | (x & 255) << 8) >> 1;
+}
+var hMap = function(cd, mb, r) {
+  var s = cd.length;
+  var i = 0;
+  var l = new u16(mb);
+  for (; i < s; ++i) {
+    if (cd[i])
+      ++l[cd[i] - 1];
+  }
+  var le = new u16(mb);
+  for (i = 1; i < mb; ++i) {
+    le[i] = le[i - 1] + l[i - 1] << 1;
+  }
+  var co;
+  if (r) {
+    co = new u16(1 << mb);
+    var rvb = 15 - mb;
+    for (i = 0; i < s; ++i) {
+      if (cd[i]) {
+        var sv = i << 4 | cd[i];
+        var r_1 = mb - cd[i];
+        var v = le[cd[i] - 1]++ << r_1;
+        for (var m = v | (1 << r_1) - 1; v <= m; ++v) {
+          co[rev[v] >> rvb] = sv;
+        }
+      }
+    }
+  } else {
+    co = new u16(s);
+    for (i = 0; i < s; ++i) {
+      if (cd[i]) {
+        co[i] = rev[le[cd[i] - 1]++] >> 15 - cd[i];
+      }
+    }
+  }
+  return co;
+};
+var flt = new u8(288);
+for (var i = 0; i < 144; ++i)
+  flt[i] = 8;
+for (var i = 144; i < 256; ++i)
+  flt[i] = 9;
+for (var i = 256; i < 280; ++i)
+  flt[i] = 7;
+for (var i = 280; i < 288; ++i)
+  flt[i] = 8;
+var fdt = new u8(32);
+for (var i = 0; i < 32; ++i)
+  fdt[i] = 5;
+var flrm = /* @__PURE__ */ hMap(flt, 9, 1);
+var fdrm = /* @__PURE__ */ hMap(fdt, 5, 1);
+var max = function(a) {
+  var m = a[0];
+  for (var i = 1; i < a.length; ++i) {
+    if (a[i] > m)
+      m = a[i];
+  }
+  return m;
+};
+var bits = function(d, p, m) {
+  var o = p / 8 | 0;
+  return (d[o] | d[o + 1] << 8) >> (p & 7) & m;
+};
+var bits16 = function(d, p) {
+  var o = p / 8 | 0;
+  return (d[o] | d[o + 1] << 8 | d[o + 2] << 16) >> (p & 7);
+};
+var shft = function(p) {
+  return (p + 7) / 8 | 0;
+};
+var slc = function(v, s, e) {
+  if (s == null || s < 0)
+    s = 0;
+  if (e == null || e > v.length)
+    e = v.length;
+  return new u8(v.subarray(s, e));
+};
+var ec = [
+  "unexpected EOF",
+  "invalid block type",
+  "invalid length/literal",
+  "invalid distance",
+  "stream finished",
+  "no stream handler",
+  ,
+  "no callback",
+  "invalid UTF-8 data",
+  "extra field too long",
+  "date not in range 1980-2099",
+  "filename too long",
+  "stream finishing",
+  "invalid zip data"
+  // determined by unknown compression method
+];
+var err = function(ind, msg, nt) {
+  var e = new Error(msg || ec[ind]);
+  e.code = ind;
+  if (Error.captureStackTrace)
+    Error.captureStackTrace(e, err);
+  if (!nt)
+    throw e;
+  return e;
+};
+var inflt = function(dat, st, buf, dict) {
+  var sl = dat.length, dl = dict ? dict.length : 0;
+  if (!sl || st.f && !st.l)
+    return buf || new u8(0);
+  var noBuf = !buf;
+  var resize = noBuf || st.i != 2;
+  var noSt = st.i;
+  if (noBuf)
+    buf = new u8(sl * 3);
+  var cbuf = function(l2) {
+    var bl = buf.length;
+    if (l2 > bl) {
+      var nbuf = new u8(Math.max(bl * 2, l2));
+      nbuf.set(buf);
+      buf = nbuf;
+    }
+  };
+  var final = st.f || 0, pos = st.p || 0, bt = st.b || 0, lm = st.l, dm = st.d, lbt = st.m, dbt = st.n;
+  var tbts = sl * 8;
+  do {
+    if (!lm) {
+      final = bits(dat, pos, 1);
+      var type = bits(dat, pos + 1, 3);
+      pos += 3;
+      if (!type) {
+        var s = shft(pos) + 4, l = dat[s - 4] | dat[s - 3] << 8, t = s + l;
+        if (t > sl) {
+          if (noSt)
+            err(0);
+          break;
+        }
+        if (resize)
+          cbuf(bt + l);
+        buf.set(dat.subarray(s, t), bt);
+        st.b = bt += l, st.p = pos = t * 8, st.f = final;
+        continue;
+      } else if (type == 1)
+        lm = flrm, dm = fdrm, lbt = 9, dbt = 5;
+      else if (type == 2) {
+        var hLit = bits(dat, pos, 31) + 257, hcLen = bits(dat, pos + 10, 15) + 4;
+        var tl = hLit + bits(dat, pos + 5, 31) + 1;
+        pos += 14;
+        var ldt = new u8(tl);
+        var clt = new u8(19);
+        for (var i = 0; i < hcLen; ++i) {
+          clt[clim[i]] = bits(dat, pos + i * 3, 7);
+        }
+        pos += hcLen * 3;
+        var clb = max(clt), clbmsk = (1 << clb) - 1;
+        var clm = hMap(clt, clb, 1);
+        for (var i = 0; i < tl; ) {
+          var r = clm[bits(dat, pos, clbmsk)];
+          pos += r & 15;
+          var s = r >> 4;
+          if (s < 16) {
+            ldt[i++] = s;
+          } else {
+            var c = 0, n = 0;
+            if (s == 16)
+              n = 3 + bits(dat, pos, 3), pos += 2, c = ldt[i - 1];
+            else if (s == 17)
+              n = 3 + bits(dat, pos, 7), pos += 3;
+            else if (s == 18)
+              n = 11 + bits(dat, pos, 127), pos += 7;
+            while (n--)
+              ldt[i++] = c;
+          }
+        }
+        var lt = ldt.subarray(0, hLit), dt = ldt.subarray(hLit);
+        lbt = max(lt);
+        dbt = max(dt);
+        lm = hMap(lt, lbt, 1);
+        dm = hMap(dt, dbt, 1);
+      } else
+        err(1);
+      if (pos > tbts) {
+        if (noSt)
+          err(0);
+        break;
+      }
+    }
+    if (resize)
+      cbuf(bt + 131072);
+    var lms = (1 << lbt) - 1, dms = (1 << dbt) - 1;
+    var lpos = pos;
+    for (; ; lpos = pos) {
+      var c = lm[bits16(dat, pos) & lms], sym = c >> 4;
+      pos += c & 15;
+      if (pos > tbts) {
+        if (noSt)
+          err(0);
+        break;
+      }
+      if (!c)
+        err(2);
+      if (sym < 256)
+        buf[bt++] = sym;
+      else if (sym == 256) {
+        lpos = pos, lm = null;
+        break;
+      } else {
+        var add = sym - 254;
+        if (sym > 264) {
+          var i = sym - 257, b = fleb[i];
+          add = bits(dat, pos, (1 << b) - 1) + fl[i];
+          pos += b;
+        }
+        var d = dm[bits16(dat, pos) & dms], dsym = d >> 4;
+        if (!d)
+          err(3);
+        pos += d & 15;
+        var dt = fd[dsym];
+        if (dsym > 3) {
+          var b = fdeb[dsym];
+          dt += bits16(dat, pos) & (1 << b) - 1, pos += b;
+        }
+        if (pos > tbts) {
+          if (noSt)
+            err(0);
+          break;
+        }
+        if (resize)
+          cbuf(bt + 131072);
+        var end = bt + add;
+        if (bt < dt) {
+          var shift = dl - dt, dend = Math.min(dt, end);
+          if (shift + bt < 0)
+            err(3);
+          for (; bt < dend; ++bt)
+            buf[bt] = dict[shift + bt];
+        }
+        for (; bt < end; ++bt)
+          buf[bt] = buf[bt - dt];
+      }
+    }
+    st.l = lm, st.p = lpos, st.b = bt, st.f = final;
+    if (lm)
+      final = 1, st.m = lbt, st.d = dm, st.n = dbt;
+  } while (!final);
+  return bt != buf.length && noBuf ? slc(buf, 0, bt) : buf.subarray(0, bt);
+};
+var et = /* @__PURE__ */ new u8(0);
+var b2 = function(d, b) {
+  return d[b] | d[b + 1] << 8;
+};
+var b4 = function(d, b) {
+  return (d[b] | d[b + 1] << 8 | d[b + 2] << 16 | d[b + 3] << 24) >>> 0;
+};
+var b8 = function(d, b) {
+  return b4(d, b) + b4(d, b + 4) * 4294967296;
+};
+function inflateSync(data, opts) {
+  return inflt(data, { i: 2 }, opts && opts.out, opts && opts.dictionary);
+}
+var td = typeof TextDecoder != "undefined" && /* @__PURE__ */ new TextDecoder();
+var tds = 0;
+try {
+  td.decode(et, { stream: true });
+  tds = 1;
+} catch (e) {
+}
+var dutf8 = function(d) {
+  for (var r = "", i = 0; ; ) {
+    var c = d[i++];
+    var eb = (c > 127) + (c > 223) + (c > 239);
+    if (i + eb > d.length)
+      return { s: r, r: slc(d, i - 1) };
+    if (!eb)
+      r += String.fromCharCode(c);
+    else if (eb == 3) {
+      c = ((c & 15) << 18 | (d[i++] & 63) << 12 | (d[i++] & 63) << 6 | d[i++] & 63) - 65536, r += String.fromCharCode(55296 | c >> 10, 56320 | c & 1023);
+    } else if (eb & 1)
+      r += String.fromCharCode((c & 31) << 6 | d[i++] & 63);
+    else
+      r += String.fromCharCode((c & 15) << 12 | (d[i++] & 63) << 6 | d[i++] & 63);
+  }
+};
+function strFromU8(dat, latin1) {
+  if (latin1) {
+    var r = "";
+    for (var i = 0; i < dat.length; i += 16384)
+      r += String.fromCharCode.apply(null, dat.subarray(i, i + 16384));
+    return r;
+  } else if (td) {
+    return td.decode(dat);
+  } else {
+    var _a2 = dutf8(dat), s = _a2.s, r = _a2.r;
+    if (r.length)
+      err(8);
+    return s;
+  }
+}
+var slzh = function(d, b) {
+  return b + 30 + b2(d, b + 26) + b2(d, b + 28);
+};
+var zh = function(d, b, z) {
+  var fnl = b2(d, b + 28), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl, bs = b4(d, b + 20);
+  var _a2 = z && bs == 4294967295 ? z64e(d, es) : [bs, b4(d, b + 24), b4(d, b + 42)], sc = _a2[0], su = _a2[1], off = _a2[2];
+  return [b2(d, b + 10), sc, su, fn, es + b2(d, b + 30) + b2(d, b + 32), off];
+};
+var z64e = function(d, b) {
+  for (; b2(d, b) != 1; b += 4 + b2(d, b + 2))
+    ;
+  return [b8(d, b + 12), b8(d, b + 4), b8(d, b + 20)];
+};
+function unzipSync(data, opts) {
+  var files = {};
+  var e = data.length - 22;
+  for (; b4(data, e) != 101010256; --e) {
+    if (!e || data.length - e > 65558)
+      err(13);
+  }
+  var c = b2(data, e + 8);
+  if (!c)
+    return {};
+  var o = b4(data, e + 16);
+  var z = o == 4294967295 || c == 65535;
+  if (z) {
+    var ze = b4(data, e - 12);
+    z = b4(data, ze) == 101075792;
+    if (z) {
+      c = b4(data, ze + 32);
+      o = b4(data, ze + 48);
+    }
+  }
+  for (var i = 0; i < c; ++i) {
+    var _a2 = zh(data, o, z), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
+    o = no;
+    {
+      if (!c_2)
+        files[fn] = slc(data, b, b + sc);
+      else if (c_2 == 8)
+        files[fn] = inflateSync(data.subarray(b, b + sc), { out: new u8(su) });
+      else
+        err(14, "unknown compression type " + c_2);
+    }
+  }
+  return files;
+}
+const SH_C0 = 0.28209479177387814;
+const COEFFS_PER_BAND = [3, 8, 15];
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+function symUnlog(n) {
+  return Math.sign(n) * (Math.exp(Math.abs(n)) - 1);
+}
+async function decodeWebP(bytes) {
+  const blob = new Blob([bytes], { type: "image/webp" });
+  const bitmap = await createImageBitmap(blob, {
+    colorSpaceConversion: "none",
+    premultiplyAlpha: "none"
+  });
+  const w = bitmap.width;
+  const h = bitmap.height;
+  const canvas = new OffscreenCanvas(w, h);
+  const ctx = canvas.getContext("2d");
+  ctx.drawImage(bitmap, 0, 0);
+  bitmap.close();
+  return { width: w, height: h, data: ctx.getImageData(0, 0, w, h).data };
+}
+function decodeSHPalette(centroidsImg, codebook, paletteSize, bands) {
+  const numCoeffs = COEFFS_PER_BAND[bands - 1];
+  const palette = new Array(paletteSize);
+  for (let n = 0; n < paletteSize; n++) {
+    const entry = new Float32Array(numCoeffs * 3);
+    for (let c = 0; c < numCoeffs; c++) {
+      const u = n % 64 * numCoeffs + c;
+      const v = Math.floor(n / 64);
+      const off = (v * centroidsImg.width + u) * 4;
+      entry[c * 3 + 0] = codebook[centroidsImg.data[off + 0]];
+      entry[c * 3 + 1] = codebook[centroidsImg.data[off + 1]];
+      entry[c * 3 + 2] = codebook[centroidsImg.data[off + 2]];
+    }
+    palette[n] = entry;
+  }
+  return palette;
+}
+async function loadSOG(url, onProgress) {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`无法加载 SOG 文件: ${url}`);
+  const buffer = await response.arrayBuffer();
+  return deserializeSOG(buffer, onProgress);
+}
+async function deserializeSOG(data, onProgress) {
+  if (onProgress) onProgress(0, "parse");
+  const zipEntries = unzipSync(new Uint8Array(data));
+  const metaKey = Object.keys(zipEntries).find((k) => k.endsWith("meta.json"));
+  if (!metaKey) throw new Error("无效的 SOG 文件: 缺少 meta.json");
+  const meta = JSON.parse(new TextDecoder().decode(zipEntries[metaKey]));
+  if (meta.version !== 2) {
+    throw new Error(`不支持的 SOG 版本: ${meta.version}，仅支持版本 2`);
+  }
+  const prefix = metaKey.includes("/") ? metaKey.substring(0, metaKey.lastIndexOf("/") + 1) : "";
+  const findFile = (name) => {
+    const entry = zipEntries[prefix + name] ?? zipEntries[name];
+    if (!entry) throw new Error(`SOG 缺少文件: ${name}`);
+    return entry;
+  };
+  if (onProgress) onProgress(5, "parse");
+  const decodeList = [
+    decodeWebP(findFile(meta.means.files[0])),
+    // 0: means_l
+    decodeWebP(findFile(meta.means.files[1])),
+    // 1: means_u
+    decodeWebP(findFile(meta.scales.files[0])),
+    // 2: scales
+    decodeWebP(findFile(meta.quats.files[0])),
+    // 3: quats
+    decodeWebP(findFile(meta.sh0.files[0]))
+    // 4: sh0
+  ];
+  const hasHigherSH = !!meta.shN;
+  if (hasHigherSH) {
+    decodeList.push(
+      decodeWebP(findFile(meta.shN.files[0])),
+      // 5: shN_centroids
+      decodeWebP(findFile(meta.shN.files[1]))
+      // 6: shN_labels
+    );
+  }
+  const imgs = await Promise.all(decodeList);
+  const [meansL, meansU, scalesImg, quatsImg, sh0Img] = imgs;
+  const centroidsImg = hasHigherSH ? imgs[5] : null;
+  const labelsImg = hasHigherSH ? imgs[6] : null;
+  if (onProgress) onProgress(35, "parse");
+  let shPalette = null;
+  let shBandCoeffs = 0;
+  if (meta.shN && centroidsImg) {
+    shBandCoeffs = COEFFS_PER_BAND[meta.shN.bands - 1];
+    shPalette = decodeSHPalette(
+      centroidsImg,
+      meta.shN.codebook,
+      meta.shN.count,
+      meta.shN.bands
+    );
+  }
+  if (onProgress) onProgress(45, "parse");
+  const count = meta.count;
+  const positions = new Float32Array(count * 3);
+  const scales = new Float32Array(count * 3);
+  const rotations = new Float32Array(count * 4);
+  const colors = new Float32Array(count * 3);
+  const opacities = new Float32Array(count);
+  const shCoeffs = shPalette ? new Float32Array(count * 45) : void 0;
+  const scCBExp = meta.scales.codebook.map((x) => Math.exp(x));
+  const dcCB = meta.sh0.codebook;
+  const SQRT2 = Math.SQRT2;
+  const quatLookup = new Float64Array(256);
+  for (let i = 0; i < 256; i++) {
+    quatLookup[i] = (i / 255 - 0.5) * SQRT2;
+  }
+  for (let i = 0; i < count; i++) {
+    const px = i % meansL.width;
+    const py = Math.floor(i / meansL.width);
+    const off = (py * meansL.width + px) * 4;
+    const qx = meansU.data[off + 0] << 8 | meansL.data[off + 0];
+    const qy = meansU.data[off + 1] << 8 | meansL.data[off + 1];
+    const qz = meansU.data[off + 2] << 8 | meansL.data[off + 2];
+    positions[i * 3 + 0] = symUnlog(lerp(meta.means.mins[0], meta.means.maxs[0], qx / 65535));
+    positions[i * 3 + 1] = symUnlog(lerp(meta.means.mins[1], meta.means.maxs[1], qy / 65535));
+    positions[i * 3 + 2] = symUnlog(lerp(meta.means.mins[2], meta.means.maxs[2], qz / 65535));
+    scales[i * 3 + 0] = scCBExp[scalesImg.data[off + 0]];
+    scales[i * 3 + 1] = scCBExp[scalesImg.data[off + 1]];
+    scales[i * 3 + 2] = scCBExp[scalesImg.data[off + 2]];
+    const r0 = quatLookup[quatsImg.data[off + 0]];
+    const r1 = quatLookup[quatsImg.data[off + 1]];
+    const r2 = quatLookup[quatsImg.data[off + 2]];
+    const rr = Math.sqrt(Math.max(0, 1 - r0 * r0 - r1 * r1 - r2 * r2));
+    const rOrder = quatsImg.data[off + 3] - 252;
+    const qX = rOrder === 0 ? r0 : rOrder === 1 ? rr : r1;
+    const qY = rOrder <= 1 ? r1 : rOrder === 2 ? rr : r2;
+    const qZ = rOrder <= 2 ? r2 : rr;
+    const qW = rOrder === 0 ? rr : r0;
+    rotations[i * 4 + 0] = qW;
+    rotations[i * 4 + 1] = qX;
+    rotations[i * 4 + 2] = qY;
+    rotations[i * 4 + 3] = qZ;
+    colors[i * 3 + 0] = 0.5 + dcCB[sh0Img.data[off + 0]] * SH_C0;
+    colors[i * 3 + 1] = 0.5 + dcCB[sh0Img.data[off + 1]] * SH_C0;
+    colors[i * 3 + 2] = 0.5 + dcCB[sh0Img.data[off + 2]] * SH_C0;
+    opacities[i] = sh0Img.data[off + 3] / 255;
+    if (shCoeffs && shPalette && labelsImg) {
+      const lOff = (py * labelsImg.width + px) * 4;
+      const label = labelsImg.data[lOff + 0] | labelsImg.data[lOff + 1] << 8;
+      const entry = shPalette[label];
+      if (entry) {
+        const base = i * 45;
+        const len = shBandCoeffs * 3;
+        for (let j = 0; j < len; j++) {
+          shCoeffs[base + j] = entry[j];
+        }
+      }
+    }
+    if (onProgress && (i & 131071) === 0) {
+      onProgress(45 + i / count * 50, "parse");
+    }
+  }
+  if (onProgress) onProgress(95, "parse");
+  return { count, positions, scales, rotations, colors, opacities, shCoeffs };
+}
 const WORKGROUP_SIZE$1 = 256;
 const RADIX_BITS = 8;
 const RADIX_SIZE = 256;
@@ -4419,7 +5231,7 @@ struct CullingParams {
   screenHeight: f32,
   frustumDilation: f32,
   pixelThreshold: f32,
-  _pad1: f32,
+  maxVisibleCount: u32,
 }
 
 @group(0) @binding(0) var<storage, read> splats: array<Splat>;
@@ -4482,6 +5294,15 @@ fn projectAndCull(@builtin(global_invocation_id) gid: vec3<u32>) {
   // 视锥剔除
   if !isInFrustum(clipPos, params.frustumDilation) { return; }
   
+  // 亚像素剔除：Gaussian 可见范围小于阈值的 splat 跳过渲染和排序
+  // scale 是 σ（标准差），Gaussian 可见范围约 3σ（覆盖 99.7%）
+  if params.pixelThreshold > 0.0 {
+    let splatSigma = maxScale(splat.scale) * getModelMaxScale(camera.model);
+    let focalY = abs(camera.proj[1][1]) * params.screenHeight * 0.5;
+    let projectedExtent = splatSigma * 3.0 * focalY / max(abs(viewPos.z), 0.001);
+    if projectedExtent < params.pixelThreshold { return; }
+  }
+  
   // 深度编码 (viewPos.z 是负数)
   let depth = viewPos.z;
   let sortableDepth = encodeDepthKey(depth);
@@ -4503,6 +5324,18 @@ fn initIndirectBuffer() {
   atomicStore(&indirectBuffer[2], 0u);
   atomicStore(&indirectBuffer[3], 0u);
 }
+
+// 排序后截断：只保留最近的 maxVisibleCount 个 splat
+// 因为 radix sort 是按深度从近到远排序，截断尾部等于丢弃被遮挡的远处 splat
+@compute @workgroup_size(1)
+fn clampDrawCount() {
+  let maxCount = params.maxVisibleCount;
+  if maxCount == 0u { return; }
+  let count = atomicLoad(&indirectBuffer[1]);
+  if count > maxCount {
+    atomicStore(&indirectBuffer[1], maxCount);
+  }
+}
 `
   );
 }
@@ -4717,7 +5550,9 @@ fn spine(
 }
 
 // ============================================================================
-// Pass 3: Downsweep - 使用偏移量散射元素 (稳定排序)
+// Pass 3: Downsweep - 并行稳定散射
+// 所有 256 个线程同时工作，通过局部排名计算保持稳定性
+// 相比原始单线程版本，workgroup 完成时间提升约 20-40 倍
 // ============================================================================
 
 @group(0) @binding(0) var<uniform> downsweepParams: SortParams;
@@ -4732,6 +5567,7 @@ fn spine(
 var<workgroup> localKeys: array<u32, BLOCK_SIZE>;
 var<workgroup> localValues: array<u32, BLOCK_SIZE>;
 var<workgroup> localBins: array<u32, BLOCK_SIZE>;
+var<workgroup> binBasePos: array<u32, RADIX_SIZE>;
 
 @compute @workgroup_size(256, 1, 1)
 fn downsweep(
@@ -4747,8 +5583,10 @@ fn downsweep(
   let tid = localId.x;
   let partitionStart = partitionId * BLOCK_SIZE;
   let shift = downsweepParams.bitShift;
+  let partitionEnd = min(partitionStart + BLOCK_SIZE, numKeys);
+  let elemsInPartition = partitionEnd - partitionStart;
   
-  // 加载元素到共享内存
+  // Phase 1: 所有线程并行加载元素到共享内存
   for (var j = 0u; j < ELEMENTS_PER_THREAD; j++) {
     let keyIdx = partitionStart + tid * ELEMENTS_PER_THREAD + j;
     let localIdx = tid * ELEMENTS_PER_THREAD + j;
@@ -4763,36 +5601,35 @@ fn downsweep(
     }
   }
   
+  // Phase 2: 初始化 bin 基础写入位置（利用 256 线程并行）
+  if tid < RADIX_SIZE {
+    let passIdx = downsweepParams.passIndex;
+    binBasePos[tid] = globalHistogramDownsweep[RADIX_SIZE * passIdx + tid] + 
+                      partitionHistogramDownsweep[RADIX_SIZE * partitionId + tid];
+  }
+  
   workgroupBarrier();
   
-  // 线程 0 执行顺序散射以保持稳定性
-  // 这是 rfs-gsplat-render 的关键设计，确保稳定排序
-  if tid == 0u {
-    var binWritePos: array<u32, RADIX_SIZE>;
+  // Phase 3: 并行计算排名并散射
+  // 稳定性保证：rank = 当前元素之前具有相同 bin 的元素数量
+  // 每个线程处理自己的 4 个元素，通过扫描 localBins 确定排名
+  for (var j = 0u; j < ELEMENTS_PER_THREAD; j++) {
+    let localIdx = tid * ELEMENTS_PER_THREAD + j;
+    if localIdx >= elemsInPartition { break; }
     
-    let passIdx = downsweepParams.passIndex;
+    let b = localBins[localIdx];
+    if b == 0xFFFFFFFFu { continue; }
     
-    // 从全局 + 分区偏移初始化写入位置
-    for (var b = 0u; b < RADIX_SIZE; b++) {
-      binWritePos[b] = globalHistogramDownsweep[RADIX_SIZE * passIdx + b] + 
-                       partitionHistogramDownsweep[RADIX_SIZE * partitionId + b];
+    // 计算 rank：扫描本分区中在当前元素之前、且属于同一 bin 的元素数
+    var rank = 0u;
+    for (var p = 0u; p < localIdx; p++) {
+      if localBins[p] == b { rank++; }
     }
     
-    // 按输入顺序顺序写入 (稳定)
-    let partitionEnd = min(partitionStart + BLOCK_SIZE, numKeys);
-    for (var k = 0u; k < BLOCK_SIZE; k++) {
-      let keyIdx = partitionStart + k;
-      if keyIdx < partitionEnd {
-        let b = localBins[k];
-        if b != 0xFFFFFFFFu {
-          let writePos = binWritePos[b];
-          if writePos < numKeys {
-            downsweepKeysOut[writePos] = localKeys[k];
-            downsweepValuesOut[writePos] = localValues[k];
-            binWritePos[b]++;
-          }
-        }
-      }
+    let writePos = binBasePos[b] + rank;
+    if writePos < numKeys {
+      downsweepKeysOut[writePos] = localKeys[localIdx];
+      downsweepValuesOut[writePos] = localValues[localIdx];
     }
   }
 }
@@ -4820,6 +5657,7 @@ class GSSplatSorter {
     // Culling Pipelines
     __publicField(this, "initIndirectPipeline");
     __publicField(this, "projectCullPipeline");
+    __publicField(this, "clampDrawCountPipeline");
     __publicField(this, "cullingBindGroupLayout");
     __publicField(this, "cullingBindGroup");
     // Radix Sort Pipelines
@@ -4939,6 +5777,11 @@ class GSSplatSorter {
       compute: { module: cullingModule, entryPoint: "projectAndCull" },
       label: "project-cull-pipeline"
     });
+    this.clampDrawCountPipeline = device.createComputePipeline({
+      layout: cullingPipelineLayout,
+      compute: { module: cullingModule, entryPoint: "clampDrawCount" },
+      label: "clamp-draw-count-pipeline"
+    });
     this.cullingBindGroup = device.createBindGroup({
       layout: this.cullingBindGroupLayout,
       entries: [
@@ -5088,15 +5931,10 @@ class GSSplatSorter {
     view.setFloat32(16, this.screenHeight, true);
     view.setFloat32(20, this.cullingOptions.frustumDilation ?? 0.2, true);
     view.setFloat32(24, this.cullingOptions.pixelThreshold, true);
-    view.setFloat32(28, 0, true);
+    view.setUint32(28, this.cullingOptions.maxVisibleCount ?? 0, true);
     this.device.queue.writeBuffer(this.cullingParamsBuffer, 0, cullingParamsData);
     const encoder = this.device.createCommandEncoder({ label: "splat-sort-encoder" });
-    encoder.clearBuffer(this.depthKeysBuffer);
-    encoder.clearBuffer(this.visibleIndicesBuffer);
-    encoder.clearBuffer(this.keysTempBuffer);
-    encoder.clearBuffer(this.valuesTempBuffer);
     encoder.clearBuffer(this.globalHistogramBuffer);
-    encoder.clearBuffer(this.partitionHistogramBuffer);
     {
       const pass = encoder.beginComputePass({ label: "init-indirect" });
       pass.setPipeline(this.initIndirectPipeline);
@@ -5134,6 +5972,13 @@ class GSSplatSorter {
         pass.end();
       }
     }
+    {
+      const pass = encoder.beginComputePass({ label: "clamp-draw-count" });
+      pass.setPipeline(this.clampDrawCountPipeline);
+      pass.setBindGroup(0, this.cullingBindGroup);
+      pass.dispatchWorkgroups(1);
+      pass.end();
+    }
     this.device.queue.submit([encoder.finish()]);
   }
   /**
@@ -5177,18 +6022,38 @@ const gsOptimizedShader = (
   `
 /**
  * 优化的 3D Gaussian Splatting Shader
- * 参考 rfs-gsplat-render 实现，修复颜色和抗锯齿问题
+ * 支持完整 L3 球谐函数（SH）视角相关颜色
+ * 参考 rfs-gsplat-render / PlayCanvas SuperSplat 实现
  */
 
 const SQRT_8: f32 = 2.82842712475;
 const SH_C0: f32 = 0.28209479177387814;
 const SH_C1: f32 = 0.4886025119029199;
-// Normalized Gaussian 常量 (匹配 SuperSplat)
-const EXP_NEG4: f32 = 0.01831563888873418;
-const INV_ONE_MINUS_EXP_NEG4: f32 = 1.01865736036377408;
-// 低通滤波器 (正则化协方差矩阵)
+// L2 SH 系数
+const SH_C2_0: f32 = 1.0925484305920792;
+const SH_C2_1: f32 = -1.0925484305920792;
+const SH_C2_2: f32 = 0.31539156525252005;
+const SH_C2_3: f32 = -1.0925484305920792;
+const SH_C2_4: f32 = 0.5462742152960396;
+// L3 SH 系数
+const SH_C3_0: f32 = -0.5900435899266435;
+const SH_C3_1: f32 = 2.890611442640554;
+const SH_C3_2: f32 = -0.4570457994644658;
+const SH_C3_3: f32 = 0.3731763325901154;
+const SH_C3_4: f32 = -0.4570457994644658;
+const SH_C3_5: f32 = 1.4453057213202769;
+const SH_C3_6: f32 = -0.5900435899266435;
+// 低通滤波器 (正则化协方差矩阵，避免数值问题)
 const LOW_PASS_FILTER: f32 = 0.3;
+// Alpha 剔除阈值 (1/255)
 const ALPHA_CULL_THRESHOLD: f32 = 0.00392156863;
+// Normalized Gaussian 常量 (用于消除边缘雾化)
+// 使用 k=4 的 Gaussian: exp(-4*A)
+// EXP_NEG_K = exp(-4) ≈ 0.0183
+// INV_ONE_MINUS_EXP_NEG_K = 1 / (1 - exp(-4)) ≈ 1.0187
+const GAUSSIAN_K: f32 = 4.0;
+const EXP_NEG_K: f32 = 0.01831563888873418;
+const INV_ONE_MINUS_EXP_NEG_K: f32 = 1.01865736036377408;
 
 struct Uniforms {
   view: mat4x4<f32>,
@@ -5212,14 +6077,51 @@ struct Splat {
   _pad2: array<f32, 3>,
 }
 
-@group(0) @binding(0) var<uniform> uniforms: Uniforms;
-@group(0) @binding(1) var<storage, read> splats: array<Splat>;
-@group(0) @binding(2) var<storage, read> sortedIndices: array<u32>;
+// 完整 L3 球谐函数求值 (匹配原始 3DGS Python 实现)
+// SH 系数以 interleaved 格式存储: [R0,G0,B0, R1,G1,B1, ...]
+// dir: 从相机指向 splat 的归一化方向向量（模型空间）
+fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
+  let x = dir.x;
+  let y = dir.y;
+  let z = dir.z;
 
-struct VertexOutput {
-  @builtin(position) position: vec4<f32>,
-  @location(0) fragPos: vec2<f32>,
-  @location(1) color: vec3<f32>,
+  var result = vec3<f32>(0.0);
+
+  // L1: 3 个基函数
+  result += (-SH_C1 * y) * vec3<f32>(splat.sh1[0], splat.sh1[1], splat.sh1[2]);
+  result += ( SH_C1 * z) * vec3<f32>(splat.sh1[3], splat.sh1[4], splat.sh1[5]);
+  result += (-SH_C1 * x) * vec3<f32>(splat.sh1[6], splat.sh1[7], splat.sh1[8]);
+
+  // L2: 5 个基函数
+  let xx = x * x; let yy = y * y; let zz = z * z;
+  let xy = x * y; let yz = y * z; let xz = x * z;
+
+  result += (SH_C2_0 * xy)                    * vec3<f32>(splat.sh2[0],  splat.sh2[1],  splat.sh2[2]);
+  result += (SH_C2_1 * yz)                    * vec3<f32>(splat.sh2[3],  splat.sh2[4],  splat.sh2[5]);
+  result += (SH_C2_2 * (2.0 * zz - xx - yy)) * vec3<f32>(splat.sh2[6],  splat.sh2[7],  splat.sh2[8]);
+  result += (SH_C2_3 * xz)                    * vec3<f32>(splat.sh2[9],  splat.sh2[10], splat.sh2[11]);
+  result += (SH_C2_4 * (xx - yy))             * vec3<f32>(splat.sh2[12], splat.sh2[13], splat.sh2[14]);
+
+  // L3: 7 个基函数
+  result += (SH_C3_0 * y * (3.0 * xx - yy))             * vec3<f32>(splat.sh3[0],  splat.sh3[1],  splat.sh3[2]);
+  result += (SH_C3_1 * xy * z)                           * vec3<f32>(splat.sh3[3],  splat.sh3[4],  splat.sh3[5]);
+  result += (SH_C3_2 * y * (4.0 * zz - xx - yy))        * vec3<f32>(splat.sh3[6],  splat.sh3[7],  splat.sh3[8]);
+  result += (SH_C3_3 * z * (2.0 * zz - 3.0 * xx - 3.0 * yy)) * vec3<f32>(splat.sh3[9],  splat.sh3[10], splat.sh3[11]);
+  result += (SH_C3_4 * x * (4.0 * zz - xx - yy))        * vec3<f32>(splat.sh3[12], splat.sh3[13], splat.sh3[14]);
+  result += (SH_C3_5 * z * (xx - yy))                    * vec3<f32>(splat.sh3[15], splat.sh3[16], splat.sh3[17]);
+  result += (SH_C3_6 * x * (xx - 3.0 * yy))             * vec3<f32>(splat.sh3[18], splat.sh3[19], splat.sh3[20]);
+
+  return result;
+}
+
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+@group(0) @binding(1) var<storage, read> splats: array<Splat>;
+@group(0) @binding(2) var<storage, read> sortedIndices: array<u32>;
+
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) fragPos: vec2<f32>,
+  @location(1) color: vec3<f32>,
   @location(2) opacity: f32,
 }
 
@@ -5228,16 +6130,24 @@ const QUAD_POSITIONS = array<vec2<f32>, 4>(
   vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
 );
 
-// ClipCorner 优化 (精确匹配 PlayCanvas/SuperSplat)
-// 从 PlayCanvas: clip = min(1.0, sqrt(-log(1.0 / (255.0 * alpha))) / 2.0)
-// 这根据透明度缩小 quad，排除 alpha < 1/255 的 Gaussian 区域
+// ClipCorner 优化：根据透明度缩小 quad，排除低于阈值的 Gaussian 区域
+// 使用 Normalized Gaussian: weight = (exp(-k*A) - exp(-k)) / (1 - exp(-k))
+// 需要找到 A 使得 alpha * weight >= 1/255
+// 即 weight >= 1/(255*alpha)
+// (exp(-k*A) - exp(-k)) / (1 - exp(-k)) >= 1/(255*alpha)
+// exp(-k*A) >= 1/(255*alpha) * (1 - exp(-k)) + exp(-k)
+// -k*A >= ln(1/(255*alpha) * (1 - exp(-k)) + exp(-k))
+// A <= -ln(1/(255*alpha) * (1 - exp(-k)) + exp(-k)) / k
 fn computeClipFactor(alpha: f32) -> f32 {
-  // 保护非常小的 alpha 值
-  // 当 alpha <= 1/255 时，splat 不可见
   if alpha <= ALPHA_CULL_THRESHOLD { return 0.0; }
-  // PlayCanvas 公式: clip = min(1.0, sqrt(-log(1.0 / (255.0 * alpha))) / 2.0)
-  // 简化: -log(1/(255*a)) = log(255*a)
-  return min(1.0, sqrt(log(255.0 * alpha)) / 2.0);
+  let threshold = 1.0 / (255.0 * alpha);
+  // 如果 threshold >= 1.0，整个 splat 都低于可见阈值
+  if threshold >= 1.0 { return 0.0; }
+  // 计算 clip 因子：找到 normalized gaussian = threshold 的位置
+  let targetExp = threshold * (1.0 - EXP_NEG_K) + EXP_NEG_K;
+  if targetExp >= 1.0 { return 0.0; }
+  let A = -log(targetExp) / GAUSSIAN_K;
+  return min(1.0, sqrt(A));
 }
 
 // 四元数转旋转矩阵 (PLY 格式: w, x, y, z)
@@ -5310,9 +6220,9 @@ fn computeExtentBasisAA(cov2dIn: vec3<f32>, opacity: f32, viewportSize: vec2<f32
   let radius = length(vec2<f32>((a - d) * 0.5, b));
   
   let lambda1 = mid + radius;
-  let lambda2 = max(mid - radius, 0.1);  // PlayCanvas 使用 0.1 最小值
+  let lambda2 = mid - radius;
   
-  // 检查特征值是否有效
+  // 非正定协方差矩阵直接剔除
   if lambda2 <= 0.0 { 
     result.basis = vec4<f32>(0.0);
     result.adjustedOpacity = 0.0;
@@ -5322,14 +6232,15 @@ fn computeExtentBasisAA(cov2dIn: vec3<f32>, opacity: f32, viewportSize: vec2<f32
   // 使用基于视口的最大限制 (匹配 PlayCanvas)
   let vmin = min(1024.0, min(viewportSize.x, viewportSize.y));
   
-  // 计算轴长度: l = 2.0 * min(sqrt(2.0 * lambda), vmin)
-  // 这等价于 std_dev * sqrt(lambda)，因为 std_dev = sqrt(8) ≈ 2.83
-  let l1 = 2.0 * min(sqrt(2.0 * lambda1), vmin);
-  let l2 = 2.0 * min(sqrt(2.0 * lambda2), vmin);
+  // 计算轴长度: l = 2 * sqrt(2 * lambda) ≈ 2.83 * sqrt(lambda)
+  // 这与 GAUSSIAN_K=4 配套使用：
+  // 在 UV=1 边界，对应 2*sqrt(2) 个标准差的位置
+  // exp(-4 * 1) = exp(-4) ≈ 0.018，Normalized 后精确为 0
+  let l1 = min(2.0 * sqrt(2.0 * lambda1), vmin);
+  let l2 = min(2.0 * sqrt(2.0 * lambda2), vmin);
   
-  // 关键: 剔除小于 2 像素的 Gaussian (匹配 PlayCanvas)
-  // 这消除了导致"雾化"伪影的亚像素 splat
-  if l1 < 2.0 && l2 < 2.0 { 
+  // 剔除小于 2 像素的 Gaussian（消除亚像素 splat 造成的雾化）
+  if l1 < 0.5 && l2 < 0.5 { 
     result.basis = vec4<f32>(0.0);
     result.adjustedOpacity = 0.0;
     return result;
@@ -5410,7 +6321,7 @@ fn vs_main(@builtin(vertex_index) vertexIndex: u32, @builtin(instance_index) ins
   
   // 视锥边缘剔除 (匹配 PlayCanvas)
   let maxExtentPixels = max(length(basis.xy), length(basis.zw));
-  let pixelToClip = vec2<f32>(clipPos.w, clipPos.w) / uniforms.screenSize;
+  let pixelToClip = 2.0 * vec2<f32>(clipPos.w, clipPos.w) / uniforms.screenSize;
   let splatExtentClip = vec2<f32>(maxExtentPixels, maxExtentPixels) * pixelToClip;
   if any((abs(clipPos.xy) - splatExtentClip) > vec2<f32>(clipPos.w, clipPos.w)) {
     output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output;
@@ -5437,9 +6348,18 @@ fn vs_main(@builtin(vertex_index) vertexIndex: u32, @builtin(instance_index) ins
   // UV 输出 - 用 clipFactor 缩放以获得正确的 Gaussian 权重
   output.fragPos = quadPos * clipFactor;
   
-  // 颜色已在 CPU 端预处理为 (dc * SH_C0 + 0.5)，直接使用
-  // 这是 3DGS 的标准颜色格式，在 sRGB 空间中
-  output.color = splat.colorDC;
+  // 球谐函数颜色计算:
+  // colorDC 已在 CPU 端预处理为 (dc * SH_C0 + 0.5)
+  // evalSH() 计算 L1~L3 的视角相关色彩贡献
+  // 方向需要在模型空间计算（SH 系数在模型空间定义）
+  let shDir = normalize(
+    vec3<f32>(
+      dot(worldPos.xyz - uniforms.cameraPos, uniforms.model[0].xyz),
+      dot(worldPos.xyz - uniforms.cameraPos, uniforms.model[1].xyz),
+      dot(worldPos.xyz - uniforms.cameraPos, uniforms.model[2].xyz)
+    )
+  );
+  output.color = splat.colorDC + evalSH(splat, shDir);
   output.opacity = adjustedOpacity;
   return output;
 }
@@ -5449,35 +6369,284 @@ fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
   if input.opacity <= 0.0 { discard; }
   
   // A = 到中心的平方距离，在 UV 空间中
-  // 由于 clipCorner 优化，fragPos 在 [-clip, clip] 范围内
   let A = dot(input.fragPos, input.fragPos);
   
   // 丢弃单位圆外的片段
   if A > 1.0 { discard; }
   
-  // Normalized Gaussian 衰减 (精确匹配 SuperSplat normExp)
-  // 关键修复: 在 A=1 (边界) 时返回精确的 0.0，消除边缘雾化
-  // 在 A=0 (中心): weight = 1.0
-  // 在 A=1 (边界): weight = 精确的 0.0 (而不是标准 exp(-4) ≈ 0.018)
-  let weight = (exp(-4.0 * A) - EXP_NEG4) * INV_ONE_MINUS_EXP_NEG4;
+  // Normalized Gaussian 衰减 (关键：消除边缘雾化)
+  // 标准 Gaussian exp(-k*A) 在边界 A=1 时不为 0，会产生累积雾化
+  // Normalized 公式: (exp(-k*A) - exp(-k)) / (1 - exp(-k))
+  // 在 A=0 时 = 1.0，在 A=1 时 = 精确的 0.0
+  let weight = (exp(-GAUSSIAN_K * A) - EXP_NEG_K) * INV_ONE_MINUS_EXP_NEG_K;
   
   // 组合 splat 透明度
   let opacity = weight * input.opacity;
   
-  // Alpha 阈值丢弃 (匹配 SuperSplat: if (alpha < 1.0 / 255.0) discard)
+  // Alpha 阈值丢弃
   if opacity < ALPHA_CULL_THRESHOLD { discard; }
   
   // 颜色 clamp 到有效范围 (防止负值)
   let color = max(input.color, vec3<f32>(0.0));
   
   // 预乘 alpha 输出 (匹配 blend mode: src=ONE, dst=ONE_MINUS_SRC_ALPHA)
-  // 这是 3DGS 渲染的标准混合模式
   return vec4<f32>(color * opacity, opacity);
 }
 `
 );
+const gsDepthNormalShader = (
+  /* wgsl */
+  `
+const SQRT_8: f32 = 2.82842712475;
+const LOW_PASS_FILTER: f32 = 0.3;
+const ALPHA_CULL_THRESHOLD: f32 = 0.00392156863;
+const GAUSSIAN_K: f32 = 4.0;
+const EXP_NEG_K: f32 = 0.01831563888873418;
+const INV_ONE_MINUS_EXP_NEG_K: f32 = 1.01865736036377408;
+
+struct Uniforms {
+  view: mat4x4<f32>,
+  proj: mat4x4<f32>,
+  model: mat4x4<f32>,
+  cameraPos: vec3<f32>,
+  _pad: f32,
+  screenSize: vec2<f32>,
+  _pad2: vec2<f32>,
+}
+
+struct Splat {
+  mean: vec3<f32>, _pad0: f32,
+  scale: vec3<f32>, _pad1: f32,
+  rotation: vec4<f32>,
+  colorDC: vec3<f32>,
+  opacity: f32,
+  sh1: array<f32, 9>,
+  sh2: array<f32, 15>,
+  sh3: array<f32, 21>,
+  _pad2: array<f32, 3>,
+}
+
+@group(0) @binding(0) var<uniform> uniforms: Uniforms;
+@group(0) @binding(1) var<storage, read> splats: array<Splat>;
+@group(0) @binding(2) var<storage, read> sortedIndices: array<u32>;
+
+struct VertexOutput {
+  @builtin(position) position: vec4<f32>,
+  @location(0) fragPos: vec2<f32>,
+  @location(1) opacity: f32,
+  @location(2) viewDepth: f32,
+  @location(3) worldNormal: vec3<f32>,
+}
+
+const QUAD_POSITIONS = array<vec2<f32>, 4>(
+  vec2<f32>(-1.0, -1.0), vec2<f32>(-1.0, 1.0),
+  vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
+);
+
+fn computeClipFactor(alpha: f32) -> f32 {
+  if alpha <= ALPHA_CULL_THRESHOLD { return 0.0; }
+  let threshold = 1.0 / (255.0 * alpha);
+  if threshold >= 1.0 { return 0.0; }
+  let targetExp = threshold * (1.0 - EXP_NEG_K) + EXP_NEG_K;
+  if targetExp >= 1.0 { return 0.0; }
+  let A = -log(targetExp) / GAUSSIAN_K;
+  return min(1.0, sqrt(A));
+}
+
+fn quatToMat3(q: vec4<f32>) -> mat3x3<f32> {
+  let r = q.x; let x = q.y; let y = q.z; let z = q.w;
+  return mat3x3<f32>(
+    vec3<f32>(1.0 - 2.0 * (y * y + z * z), 2.0 * (x * y + r * z), 2.0 * (x * z - r * y)),
+    vec3<f32>(2.0 * (x * y - r * z), 1.0 - 2.0 * (x * x + z * z), 2.0 * (y * z + r * x)),
+    vec3<f32>(2.0 * (x * z + r * y), 2.0 * (y * z - r * x), 1.0 - 2.0 * (x * x + y * y))
+  );
+}
+
+fn computeCovariance3D(scale: vec3<f32>, rotation: vec4<f32>) -> mat3x3<f32> {
+  let R = quatToMat3(rotation);
+  let S = mat3x3<f32>(vec3<f32>(scale.x, 0.0, 0.0), vec3<f32>(0.0, scale.y, 0.0), vec3<f32>(0.0, 0.0, scale.z));
+  let M = R * S;
+  return M * transpose(M);
+}
+
+fn projectCovariance(cov3d: mat3x3<f32>, viewCenter: vec4<f32>, focal: vec2<f32>, modelViewMat: mat4x4<f32>) -> vec3<f32> {
+  let v = viewCenter.xyz;
+  let s = 1.0 / (v.z * v.z);
+  let J = mat3x3<f32>(
+    vec3<f32>(focal.x / v.z, 0.0, 0.0),
+    vec3<f32>(0.0, focal.y / v.z, 0.0),
+    vec3<f32>(-(focal.x * v.x) * s, -(focal.y * v.y) * s, 0.0)
+  );
+  let W = mat3x3<f32>(
+    vec3<f32>(modelViewMat[0][0], modelViewMat[0][1], modelViewMat[0][2]),
+    vec3<f32>(modelViewMat[1][0], modelViewMat[1][1], modelViewMat[1][2]),
+    vec3<f32>(modelViewMat[2][0], modelViewMat[2][1], modelViewMat[2][2])
+  );
+  let T = J * W;
+  let cov2d = T * cov3d * transpose(T);
+  return vec3<f32>(cov2d[0][0], cov2d[0][1], cov2d[1][1]);
+}
+
+struct ExtentResult {
+  basis: vec4<f32>,
+  adjustedOpacity: f32,
+}
+
+fn computeExtentBasisAA(cov2dIn: vec3<f32>, opacity: f32, viewportSize: vec2<f32>) -> ExtentResult {
+  var result: ExtentResult;
+  var cov2d = cov2dIn;
+  var alpha = opacity;
+  cov2d.x += LOW_PASS_FILTER;
+  cov2d.z += LOW_PASS_FILTER;
+  let a = cov2d.x;
+  let d = cov2d.z;
+  let b = cov2d.y;
+  let mid = 0.5 * (a + d);
+  let radius = length(vec2<f32>((a - d) * 0.5, b));
+  let lambda1 = mid + radius;
+  let lambda2 = mid - radius;
+  if lambda2 <= 0.0 {
+    result.basis = vec4<f32>(0.0);
+    result.adjustedOpacity = 0.0;
+    return result;
+  }
+  let vmin = min(1024.0, min(viewportSize.x, viewportSize.y));
+  let l1 = min(2.0 * sqrt(2.0 * lambda1), vmin);
+  let l2 = min(2.0 * sqrt(2.0 * lambda2), vmin);
+  if l1 < 0.5 && l2 < 0.5 {
+    result.basis = vec4<f32>(0.0);
+    result.adjustedOpacity = 0.0;
+    return result;
+  }
+  let diagVec = normalize(vec2<f32>(b, lambda1 - a));
+  let eigenvector1 = diagVec;
+  let eigenvector2 = vec2<f32>(diagVec.y, -diagVec.x);
+  result.basis = vec4<f32>(eigenvector1 * l1, eigenvector2 * l2);
+  result.adjustedOpacity = alpha;
+  return result;
+}
+
+// Extract the normal of a gaussian ellipsoid from its scale and rotation.
+// The normal is the axis corresponding to the smallest scale (shortest axis).
+// After rotation, this gives the world-space normal of the local surface.
+fn computeSplatNormal(scale: vec3<f32>, rotation: vec4<f32>, modelMat: mat4x4<f32>) -> vec3<f32> {
+  let R = quatToMat3(rotation);
+  // Find the axis with smallest scale
+  var minAxis: vec3<f32>;
+  if scale.x <= scale.y && scale.x <= scale.z {
+    minAxis = R[0]; // column 0
+  } else if scale.y <= scale.z {
+    minAxis = R[1]; // column 1
+  } else {
+    minAxis = R[2]; // column 2
+  }
+  // Transform to world space via model matrix 3x3 part
+  let worldNormal = vec3<f32>(
+    modelMat[0][0] * minAxis.x + modelMat[1][0] * minAxis.y + modelMat[2][0] * minAxis.z,
+    modelMat[0][1] * minAxis.x + modelMat[1][1] * minAxis.y + modelMat[2][1] * minAxis.z,
+    modelMat[0][2] * minAxis.x + modelMat[1][2] * minAxis.y + modelMat[2][2] * minAxis.z
+  );
+  let len = length(worldNormal);
+  if len < 1e-8 { return vec3<f32>(0.0, 1.0, 0.0); }
+  return worldNormal / len;
+}
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertexIndex: u32, @builtin(instance_index) instanceIndex: u32) -> VertexOutput {
+  var output: VertexOutput;
+  let splatIndex = sortedIndices[instanceIndex];
+  let splat = splats[splatIndex];
+  let quadPos = QUAD_POSITIONS[vertexIndex];
+
+  if splat.opacity < ALPHA_CULL_THRESHOLD { output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output; }
+  let quatNormSqr = dot(splat.rotation, splat.rotation);
+  if quatNormSqr < 1e-6 { output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output; }
+
+  let worldPos = uniforms.model * vec4<f32>(splat.mean, 1.0);
+  let viewPos = uniforms.view * worldPos;
+  let clipPos = uniforms.proj * viewPos;
+
+  if viewPos.z >= 0.0 { output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output; }
+
+  let pW = 1.0 / (clipPos.w + 0.0000001);
+  let ndcPos = clipPos * pW;
+
+  let clipBound = 1.3;
+  if abs(ndcPos.x) > clipBound || abs(ndcPos.y) > clipBound || ndcPos.z < -0.2 || ndcPos.z > 1.0 {
+    output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output;
+  }
+
+  let cov3d = computeCovariance3D(splat.scale, splat.rotation);
+  let focal = vec2<f32>(
+    abs(uniforms.proj[0][0]) * 0.5 * uniforms.screenSize.x,
+    abs(uniforms.proj[1][1]) * 0.5 * uniforms.screenSize.y
+  );
+  let modelViewMat = uniforms.view * uniforms.model;
+  let cov2d = projectCovariance(cov3d, viewPos, focal, modelViewMat);
+
+  let extentResult = computeExtentBasisAA(cov2d, splat.opacity, uniforms.screenSize);
+  let basis = extentResult.basis;
+  let adjustedOpacity = extentResult.adjustedOpacity;
+
+  if basis.x == 0.0 && basis.y == 0.0 && basis.z == 0.0 && basis.w == 0.0 {
+    output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output;
+  }
+
+  let maxExtentPixels = max(length(basis.xy), length(basis.zw));
+  let pixelToClip = 2.0 * vec2<f32>(clipPos.w, clipPos.w) / uniforms.screenSize;
+  let splatExtentClip = vec2<f32>(maxExtentPixels, maxExtentPixels) * pixelToClip;
+  if any((abs(clipPos.xy) - splatExtentClip) > vec2<f32>(clipPos.w, clipPos.w)) {
+    output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output;
+  }
+
+  let clipFactor = computeClipFactor(adjustedOpacity);
+  if clipFactor <= 0.0 { output.position = vec4<f32>(0.0, 0.0, 2.0, 1.0); return output; }
+
+  let basisViewport = vec2<f32>(1.0 / uniforms.screenSize.x, 1.0 / uniforms.screenSize.y);
+  let basisVector1 = basis.xy * clipFactor;
+  let basisVector2 = basis.zw * clipFactor;
+  let ndcOffset = (quadPos.x * basisVector1 + quadPos.y * basisVector2) * basisViewport * 2.0;
+  output.position = vec4<f32>(ndcPos.xy + ndcOffset, ndcPos.z, 1.0);
+
+  output.fragPos = quadPos * clipFactor;
+  output.opacity = adjustedOpacity;
+  output.viewDepth = -viewPos.z;
+
+  // Normal from shortest ellipsoid axis, oriented toward camera
+  var normal = computeSplatNormal(splat.scale, splat.rotation, uniforms.model);
+  let toCamera = uniforms.cameraPos - worldPos.xyz;
+  if dot(normal, toCamera) < 0.0 {
+    normal = -normal;
+  }
+  output.worldNormal = normal;
+  return output;
+}
+
+struct FragOutput {
+  @location(0) depthOut: vec4<f32>,
+  @location(1) normalOut: vec4<f32>,
+}
+
+@fragment
+fn fs_depth_normal(input: VertexOutput) -> FragOutput {
+  if input.opacity <= 0.0 { discard; }
+  let A = dot(input.fragPos, input.fragPos);
+  if A > 1.0 { discard; }
+  let weight = (exp(-GAUSSIAN_K * A) - EXP_NEG_K) * INV_ONE_MINUS_EXP_NEG_K;
+  let opacity = weight * input.opacity;
+  if opacity < ALPHA_CULL_THRESHOLD { discard; }
+
+  var out: FragOutput;
+  // RT0: depth + opacity — RGB blend 1·src+(1-α)·dst accumulates depth, Alpha blend 0·src+(1-α)·dst accumulates transmittance
+  out.depthOut = vec4<f32>(input.viewDepth * opacity, 0.0, 0.0, opacity);
+  // RT1: normal — same blend, RGB accumulates weighted normal, Alpha accumulates transmittance
+  out.normalOut = vec4<f32>(input.worldNormal * opacity, opacity);
+  return out;
+}
+`
+);
 const SPLAT_FLOAT_COUNT = 64;
-class GSSplatRenderer {
+const _GSSplatRenderer = class _GSSplatRenderer {
   constructor(renderer, camera) {
     __publicField(this, "renderer");
     __publicField(this, "camera");
@@ -5488,8 +6657,9 @@ class GSSplatRenderer {
     __publicField(this, "splatCount", 0);
     __publicField(this, "bindGroup", null);
     __publicField(this, "sorter", null);
-    __publicField(this, "shMode", SHMode.L0);
+    __publicField(this, "shMode", SHMode.L3);
     __publicField(this, "boundingBox", null);
+    __publicField(this, "cpuPositions", null);
     // Transform
     __publicField(this, "position", [0, 0, 0]);
     __publicField(this, "rotation", [0, 0, 0]);
@@ -5498,6 +6668,28 @@ class GSSplatRenderer {
     __publicField(this, "modelMatrix", new Float32Array(16));
     // 剔除选项
     __publicField(this, "pixelCullThreshold", 1);
+    __publicField(this, "maxVisibleSplats", 0);
+    // 排序优化：相机变化检测 + 频率控制
+    __publicField(this, "lastSortViewMatrix", new Float32Array(16));
+    __publicField(this, "lastSortProjMatrix", new Float32Array(16));
+    __publicField(this, "lastSortModelMatrix", new Float32Array(16));
+    __publicField(this, "lastSortWidth", 0);
+    __publicField(this, "lastSortHeight", 0);
+    __publicField(this, "lastSortPixelThreshold", -1);
+    __publicField(this, "lastSortMaxVisible", -1);
+    __publicField(this, "sortStateInitialized", false);
+    __publicField(this, "sortFrequency", 1);
+    __publicField(this, "frameCounter", 0);
+    // 深度法线Pass依赖资源
+    __publicField(this, "depthNormalPipeline", null);
+    __publicField(this, "depthRT", null);
+    __publicField(this, "depthRTView", null);
+    __publicField(this, "normalRT", null);
+    __publicField(this, "normalRTView", null);
+    __publicField(this, "dnRTWidth", 0);
+    __publicField(this, "dnRTHeight", 0);
+    // 这一帧的深度法线回读结果，返回指定像素的3*3区域的深度值和法线
+    __publicField(this, "dnResult", null);
     this.renderer = renderer;
     this.camera = camera;
     this.createPipeline();
@@ -5511,9 +6703,21 @@ class GSSplatRenderer {
     });
     this.bindGroupLayout = device.createBindGroupLayout({
       entries: [
-        { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } },
-        { binding: 1, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } },
-        { binding: 2, visibility: GPUShaderStage.VERTEX, buffer: { type: "read-only-storage" } }
+        {
+          binding: 0,
+          visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+          buffer: { type: "uniform" }
+        },
+        {
+          binding: 1,
+          visibility: GPUShaderStage.VERTEX,
+          buffer: { type: "read-only-storage" }
+        },
+        {
+          binding: 2,
+          visibility: GPUShaderStage.VERTEX,
+          buffer: { type: "read-only-storage" }
+        }
       ]
     });
     const pipelineLayout = device.createPipelineLayout({
@@ -5529,28 +6733,30 @@ class GSSplatRenderer {
       fragment: {
         module: shaderModule,
         entryPoint: "fs_main",
-        targets: [{
-          format: this.renderer.format,
-          blend: {
-            color: {
-              srcFactor: "one",
-              dstFactor: "one-minus-src-alpha",
-              operation: "add"
-            },
-            alpha: {
-              srcFactor: "one",
-              dstFactor: "one-minus-src-alpha",
-              operation: "add"
+        targets: [
+          {
+            format: this.renderer.format,
+            blend: {
+              color: {
+                srcFactor: "one",
+                dstFactor: "one-minus-src-alpha",
+                operation: "add"
+              },
+              alpha: {
+                srcFactor: "one",
+                dstFactor: "one-minus-src-alpha",
+                operation: "add"
+              }
             }
           }
-        }]
+        ]
       },
       primitive: {
         topology: "triangle-strip"
       },
       depthStencil: {
         format: this.renderer.depthFormat,
-        depthWriteEnabled: false,
+        depthWriteEnabled: true,
         depthCompare: "always"
       }
     });
@@ -5561,6 +6767,65 @@ class GSSplatRenderer {
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
     });
   }
+  // 创建深度和法线渲染管线，这个管线用于渲染深度和法线信息，用于后续的拾取操作
+  // RGB采用"one add one-minus-src-alpha"的混合模式对深度和法线做AlphaBlending
+  // A采用"zero add one-minus-src-alpha"的混合模式计算Transmittance
+  createDepthNormalPipeline() {
+    const device = this.renderer.device;
+    const shaderModule = device.createShaderModule({ code: gsDepthNormalShader });
+    const pipelineLayout = device.createPipelineLayout({
+      bindGroupLayouts: [this.bindGroupLayout]
+    });
+    this.depthNormalPipeline = device.createRenderPipeline({
+      layout: pipelineLayout,
+      vertex: {
+        module: shaderModule,
+        entryPoint: "vs_main",
+        buffers: []
+      },
+      fragment: {
+        module: shaderModule,
+        entryPoint: "fs_depth_normal",
+        targets: [
+          {
+            format: "rgba16float",
+            blend: {
+              color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+              alpha: { srcFactor: "zero", dstFactor: "one-minus-src-alpha", operation: "add" }
+            }
+          },
+          {
+            format: "rgba16float",
+            blend: {
+              color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+              alpha: { srcFactor: "zero", dstFactor: "one-minus-src-alpha", operation: "add" }
+            }
+          }
+        ]
+      },
+      primitive: { topology: "triangle-strip" }
+    });
+  }
+  ensureDepthNormalTextures(w, h) {
+    if (this.depthRT && this.dnRTWidth === w && this.dnRTHeight === h) return;
+    const device = this.renderer.device;
+    if (this.depthRT) this.depthRT.destroy();
+    if (this.normalRT) this.normalRT.destroy();
+    this.depthRT = device.createTexture({
+      size: { width: w, height: h },
+      format: "rgba16float",
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
+    });
+    this.depthRTView = this.depthRT.createView();
+    this.normalRT = device.createTexture({
+      size: { width: w, height: h },
+      format: "rgba16float",
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
+    });
+    this.normalRTView = this.normalRT.createView();
+    this.dnRTWidth = w;
+    this.dnRTHeight = h;
+  }
   setPosition(x, y, z) {
     this.position = [x, y, z];
     this.updateModelMatrix();
@@ -5644,6 +6909,56 @@ class GSSplatRenderer {
   setPixelCullThreshold(threshold) {
     this.pixelCullThreshold = threshold;
   }
+  /**
+   * 设置最大可见 splat 数量
+   * 排序后只保留距离最近的 N 个 splat，远处被遮挡的 splat 被丢弃
+   * 0 = 不限制
+   */
+  setMaxVisibleSplats(count) {
+    this.maxVisibleSplats = count;
+  }
+  getMaxVisibleSplats() {
+    return this.maxVisibleSplats;
+  }
+  /**
+   * 设置排序频率
+   * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推
+   * 相机静止时自动跳过排序，不受此参数影响
+   */
+  setSortFrequency(frequency) {
+    this.sortFrequency = Math.max(1, Math.round(frequency));
+  }
+  getSortFrequency() {
+    return this.sortFrequency;
+  }
+  needsSort() {
+    const view = this.camera.viewMatrix;
+    const proj = this.camera.projectionMatrix;
+    const model = this.modelMatrix;
+    const w = this.renderer.width;
+    const h = this.renderer.height;
+    if (!this.sortStateInitialized || w !== this.lastSortWidth || h !== this.lastSortHeight || this.pixelCullThreshold !== this.lastSortPixelThreshold || this.maxVisibleSplats !== this.lastSortMaxVisible) {
+      this.saveSortState(view, proj, model, w, h);
+      return true;
+    }
+    for (let i = 0; i < 16; i++) {
+      if (view[i] !== this.lastSortViewMatrix[i] || proj[i] !== this.lastSortProjMatrix[i] || model[i] !== this.lastSortModelMatrix[i]) {
+        this.saveSortState(view, proj, model, w, h);
+        return true;
+      }
+    }
+    return false;
+  }
+  saveSortState(view, proj, model, w, h) {
+    this.lastSortViewMatrix.set(view);
+    this.lastSortProjMatrix.set(proj);
+    this.lastSortModelMatrix.set(model);
+    this.lastSortWidth = w;
+    this.lastSortHeight = h;
+    this.lastSortPixelThreshold = this.pixelCullThreshold;
+    this.lastSortMaxVisible = this.maxVisibleSplats;
+    this.sortStateInitialized = true;
+  }
   setData(splats) {
     const device = this.renderer.device;
     if (this.splatBuffer) {
@@ -5661,10 +6976,14 @@ class GSSplatRenderer {
       return;
     }
     this.boundingBox = this.computeBoundingBox(splats);
+    const positions = new Float32Array(this.splatCount * 3);
     const data = new Float32Array(this.splatCount * SPLAT_FLOAT_COUNT);
     for (let i = 0; i < this.splatCount; i++) {
       const splat = splats[i];
       const offset = i * SPLAT_FLOAT_COUNT;
+      positions[i * 3 + 0] = splat.mean[0];
+      positions[i * 3 + 1] = splat.mean[1];
+      positions[i * 3 + 2] = splat.mean[2];
       data[offset + 0] = splat.mean[0];
       data[offset + 1] = splat.mean[1];
       data[offset + 2] = splat.mean[2];
@@ -5700,6 +7019,7 @@ class GSSplatRenderer {
       usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
     });
     device.queue.writeBuffer(this.splatBuffer, 0, data);
+    this.cpuPositions = positions;
     this.sorter = new GSSplatSorter(
       device,
       this.splatCount,
@@ -5738,6 +7058,7 @@ class GSSplatRenderer {
       return;
     }
     this.boundingBox = this.computeBoundingBoxFromCompact(compactData);
+    this.cpuPositions = new Float32Array(compactData.positions);
     const includeSH = compactData.shCoeffs !== void 0;
     const gpuData = compactDataToGPUBuffer(compactData, includeSH);
     this.splatBuffer = device.createBuffer({
@@ -5795,13 +7116,19 @@ class GSSplatRenderer {
       208,
       new Float32Array([this.renderer.width, this.renderer.height, 0, 0])
     );
-    this.sorter.setScreenSize(this.renderer.width, this.renderer.height);
-    this.sorter.setCullingOptions({
-      nearPlane: this.camera.near,
-      farPlane: this.camera.far,
-      pixelThreshold: this.pixelCullThreshold
-    });
-    this.sorter.sort();
+    const changed = this.needsSort();
+    this.frameCounter++;
+    const shouldSort = changed || this.sortFrequency > 1 && this.frameCounter % this.sortFrequency === 0;
+    if (shouldSort) {
+      this.sorter.setScreenSize(this.renderer.width, this.renderer.height);
+      this.sorter.setCullingOptions({
+        nearPlane: this.camera.near,
+        farPlane: this.camera.far,
+        pixelThreshold: this.pixelCullThreshold,
+        maxVisibleCount: this.maxVisibleSplats
+      });
+      this.sorter.sort();
+    }
     pass.setPipeline(this.pipeline);
     pass.setBindGroup(0, this.bindGroup);
     pass.drawIndirect(this.sorter.getDrawIndirectBuffer(), 0);
@@ -5812,31 +7139,42 @@ class GSSplatRenderer {
   getBoundingBox() {
     return this.boundingBox;
   }
+  getCPUPositions() {
+    return this.cpuPositions;
+  }
   computeBoundingBox(splats) {
     if (splats.length === 0) {
       return { min: [0, 0, 0], max: [0, 0, 0], center: [0, 0, 0], radius: 0 };
     }
-    const min = [splats[0].mean[0], splats[0].mean[1], splats[0].mean[2]];
-    const max = [splats[0].mean[0], splats[0].mean[1], splats[0].mean[2]];
+    const min = [
+      splats[0].mean[0],
+      splats[0].mean[1],
+      splats[0].mean[2]
+    ];
+    const max2 = [
+      splats[0].mean[0],
+      splats[0].mean[1],
+      splats[0].mean[2]
+    ];
     for (let i = 1; i < splats.length; i++) {
       const [x, y, z] = splats[i].mean;
       min[0] = Math.min(min[0], x);
       min[1] = Math.min(min[1], y);
       min[2] = Math.min(min[2], z);
-      max[0] = Math.max(max[0], x);
-      max[1] = Math.max(max[1], y);
-      max[2] = Math.max(max[2], z);
+      max2[0] = Math.max(max2[0], x);
+      max2[1] = Math.max(max2[1], y);
+      max2[2] = Math.max(max2[2], z);
     }
     const center = [
-      (min[0] + max[0]) / 2,
-      (min[1] + max[1]) / 2,
-      (min[2] + max[2]) / 2
+      (min[0] + max2[0]) / 2,
+      (min[1] + max2[1]) / 2,
+      (min[2] + max2[2]) / 2
     ];
-    const dx = max[0] - min[0];
-    const dy = max[1] - min[1];
-    const dz = max[2] - min[2];
+    const dx = max2[0] - min[0];
+    const dy = max2[1] - min[1];
+    const dz = max2[2] - min[2];
     const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
-    return { min, max, center, radius };
+    return { min, max: max2, center, radius };
   }
   computeBoundingBoxFromCompact(data) {
     if (data.count === 0) {
@@ -5844,7 +7182,7 @@ class GSSplatRenderer {
     }
     const positions = data.positions;
     const min = [positions[0], positions[1], positions[2]];
-    const max = [positions[0], positions[1], positions[2]];
+    const max2 = [positions[0], positions[1], positions[2]];
     for (let i = 1; i < data.count; i++) {
       const x = positions[i * 3 + 0];
       const y = positions[i * 3 + 1];
@@ -5852,20 +7190,183 @@ class GSSplatRenderer {
       min[0] = Math.min(min[0], x);
       min[1] = Math.min(min[1], y);
       min[2] = Math.min(min[2], z);
-      max[0] = Math.max(max[0], x);
-      max[1] = Math.max(max[1], y);
-      max[2] = Math.max(max[2], z);
+      max2[0] = Math.max(max2[0], x);
+      max2[1] = Math.max(max2[1], y);
+      max2[2] = Math.max(max2[2], z);
+    }
+    const center = [
+      (min[0] + max2[0]) / 2,
+      (min[1] + max2[1]) / 2,
+      (min[2] + max2[2]) / 2
+    ];
+    const dx = max2[0] - min[0];
+    const dy = max2[1] - min[1];
+    const dz = max2[2] - min[2];
+    const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
+    return { min, max: max2, center, radius };
+  }
+  // 1、提交深度和法线渲染Pass；
+  // 2、如果px和py不为-1，则表示需要回读指定像素周围3*3区域的深度和法线信息，这一帧的回读结果保存在dnResult中，下一帧可以获取
+  prepareDepthNormalPass(px = -1, py = -1) {
+    if (this.splatCount === 0 || !this.bindGroup || !this.sorter) return;
+    if (!this.depthNormalPipeline) this.createDepthNormalPipeline();
+    const w = this.renderer.width;
+    const h = this.renderer.height;
+    this.ensureDepthNormalTextures(w, h);
+    const device = this.renderer.device;
+    const encoder = device.createCommandEncoder({ label: "depth-normal-encoder" });
+    const pass = encoder.beginRenderPass({
+      colorAttachments: [
+        {
+          view: this.depthRTView,
+          clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          loadOp: "clear",
+          storeOp: "store"
+        },
+        {
+          view: this.normalRTView,
+          clearValue: { r: 0, g: 0, b: 0, a: 1 },
+          loadOp: "clear",
+          storeOp: "store"
+        }
+      ]
+    });
+    pass.setPipeline(this.depthNormalPipeline);
+    pass.setBindGroup(0, this.bindGroup);
+    pass.drawIndirect(this.sorter.getDrawIndirectBuffer(), 0);
+    pass.end();
+    const ipx = Math.floor(px);
+    const ipy = Math.floor(py);
+    if (ipx >= 0 && ipx < w && ipy >= 0 && ipy < h) {
+      const x0 = Math.max(0, ipx - 1);
+      const y0 = Math.max(0, ipy - 1);
+      const x1 = Math.min(w, ipx + 2);
+      const y1 = Math.min(h, ipy + 2);
+      const copyW = x1 - x0;
+      const copyH = y1 - y0;
+      const cx = ipx - x0;
+      const cy = ipy - y0;
+      const rawBytesPerRow = copyW * 8;
+      const bytesPerRow = Math.ceil(rawBytesPerRow / 256) * 256;
+      const sliceBytes = bytesPerRow * copyH;
+      const buf = device.createBuffer({
+        size: sliceBytes * 2,
+        // two RT slices (depth + normal)
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+      });
+      encoder.copyTextureToBuffer(
+        { texture: this.depthRT, origin: { x: x0, y: y0 } },
+        { buffer: buf, offset: 0, bytesPerRow },
+        { width: copyW, height: copyH }
+      );
+      encoder.copyTextureToBuffer(
+        { texture: this.normalRT, origin: { x: x0, y: y0 } },
+        { buffer: buf, offset: sliceBytes, bytesPerRow },
+        { width: copyW, height: copyH }
+      );
+      device.queue.submit([encoder.finish()]);
+      const vm = new Float32Array(this.camera.viewMatrix);
+      const proj = new Float32Array(this.camera.projectionMatrix);
+      const cam = new Float32Array(this.camera.position);
+      buf.mapAsync(GPUMapMode.READ).then(() => {
+        const raw = new Uint16Array(buf.getMappedRange().slice(0));
+        buf.unmap();
+        buf.destroy();
+        this.dnResult = { raw, vm, proj, cam, w, h, px: ipx, py: ipy, copyX: x0, copyY: y0, copyW, copyH, cx, cy };
+      }).catch(() => {
+        buf.destroy();
+      });
+    } else {
+      device.queue.submit([encoder.finish()]);
+    }
+  }
+  static half2Float(h) {
+    const sign = (h & 32768) << 16;
+    const exponent = (h & 31744) >> 10;
+    const mantissa = h & 1023;
+    if (exponent === 0) {
+      if (mantissa === 0) {
+        _GSSplatRenderer._f32[0] = 0;
+        return sign ? -0 : 0;
+      }
+      let e = -1;
+      let m = mantissa;
+      do {
+        e++;
+        m <<= 1;
+      } while ((m & 1024) === 0);
+      _GSSplatRenderer._u32[0] = sign | 127 - 15 - e << 23 | (m & 1023) << 13;
+    } else if (exponent === 31) {
+      _GSSplatRenderer._u32[0] = sign | 2139095040 | mantissa << 13;
+    } else {
+      _GSSplatRenderer._u32[0] = sign | exponent + 127 - 15 << 23 | mantissa << 13;
+    }
+    return _GSSplatRenderer._f32[0];
+  }
+  // 通过上一帧的回读结果dnResult，获取深度和法线信息
+  // 世界位置通过当前像素以及对应深度反向投影计算
+  // 世界法线使用3×3邻域直接平均以降低噪声敏感度
+  getDepthNormal() {
+    if (!this.dnResult) return null;
+    const { raw, vm, proj, cam, w, h, px, py, copyW, copyH, cx, cy } = this.dnResult;
+    const rawBytesPerRow = copyW * 8;
+    const bytesPerRow = Math.ceil(rawBytesPerRow / 256) * 256;
+    const u16PerRow = bytesPerRow / 2;
+    const sliceU16 = u16PerRow * copyH;
+    const h2f = _GSSplatRenderer.half2Float;
+    const cOff = cy * u16PerRow + cx * 4;
+    const accumDepth = h2f(raw[cOff + 0]);
+    const transmittance = h2f(raw[cOff + 3]);
+    const alpha = 1 - transmittance;
+    if (alpha < 1e-6) return null;
+    const viewDepth = accumDepth / alpha;
+    let snx = 0, sny = 0, snz = 0;
+    for (let ky = 0; ky < 3; ky++) {
+      const ry = cy + ky - 1;
+      if (ry < 0 || ry >= copyH) continue;
+      for (let kx = 0; kx < 3; kx++) {
+        const rx = cx + kx - 1;
+        if (rx < 0 || rx >= copyW) continue;
+        const off = sliceU16 + ry * u16PerRow + rx * 4;
+        const a = 1 - h2f(raw[off + 3]);
+        if (a < 1e-6) continue;
+        snx += h2f(raw[off + 0]) / a;
+        sny += h2f(raw[off + 1]) / a;
+        snz += h2f(raw[off + 2]) / a;
+      }
+    }
+    let nx = snx, ny = sny, nz = snz;
+    const nLen = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (nLen > 1e-8) {
+      nx /= nLen;
+      ny /= nLen;
+      nz /= nLen;
+    } else {
+      nx = 0;
+      ny = 1;
+      nz = 0;
+    }
+    const ndcX = (px + 0.5) / w * 2 - 1;
+    const ndcY = 1 - (py + 0.5) / h * 2;
+    const viewX = ndcX * viewDepth / proj[0];
+    const viewY = ndcY * viewDepth / proj[5];
+    const viewZ = -viewDepth;
+    const wx = vm[0] * viewX + vm[1] * viewY + vm[2] * viewZ + cam[0];
+    const wy = vm[4] * viewX + vm[5] * viewY + vm[6] * viewZ + cam[1];
+    const wz = vm[8] * viewX + vm[9] * viewY + vm[10] * viewZ + cam[2];
+    const toCamX = cam[0] - wx;
+    const toCamY = cam[1] - wy;
+    const toCamZ = cam[2] - wz;
+    if (nx * toCamX + ny * toCamY + nz * toCamZ < 0) {
+      nx = -nx;
+      ny = -ny;
+      nz = -nz;
     }
-    const center = [
-      (min[0] + max[0]) / 2,
-      (min[1] + max[1]) / 2,
-      (min[2] + max[2]) / 2
-    ];
-    const dx = max[0] - min[0];
-    const dy = max[1] - min[1];
-    const dz = max[2] - min[2];
-    const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
-    return { min, max, center, radius };
+    return {
+      depth: viewDepth,
+      normal: [nx, ny, nz],
+      worldPos: [wx, wy, wz]
+    };
   }
   supportsSHMode(mode) {
     return mode >= SHMode.L0 && mode <= SHMode.L3;
@@ -5887,11 +7388,24 @@ class GSSplatRenderer {
       this.sorter.destroy();
       this.sorter = null;
     }
+    if (this.depthRT) {
+      this.depthRT.destroy();
+      this.depthRT = null;
+    }
+    if (this.normalRT) {
+      this.normalRT.destroy();
+      this.normalRT = null;
+    }
+    this.dnResult = null;
     this.uniformBuffer.destroy();
     this.splatCount = 0;
     this.bindGroup = null;
+    this.depthNormalPipeline = null;
   }
-}
+};
+__publicField(_GSSplatRenderer, "_f32", new Float32Array(1));
+__publicField(_GSSplatRenderer, "_u32", new Uint32Array(_GSSplatRenderer._f32.buffer));
+let GSSplatRenderer = _GSSplatRenderer;
 function calculateTextureDimensions(count) {
   if (count <= 0) {
     return { width: 4, height: 4 };
@@ -5913,7 +7427,7 @@ function computeBoundingBox(positions, count) {
     };
   }
   const min = [positions[0], positions[1], positions[2]];
-  const max = [positions[0], positions[1], positions[2]];
+  const max2 = [positions[0], positions[1], positions[2]];
   for (let i = 1; i < count; i++) {
     const x = positions[i * 3 + 0];
     const y = positions[i * 3 + 1];
@@ -5921,11 +7435,11 @@ function computeBoundingBox(positions, count) {
     min[0] = Math.min(min[0], x);
     min[1] = Math.min(min[1], y);
     min[2] = Math.min(min[2], z);
-    max[0] = Math.max(max[0], x);
-    max[1] = Math.max(max[1], y);
-    max[2] = Math.max(max[2], z);
+    max2[0] = Math.max(max2[0], x);
+    max2[1] = Math.max(max2[1], y);
+    max2[2] = Math.max(max2[2], z);
   }
-  return { min, max };
+  return { min, max: max2 };
 }
 function compressSplatsToTextures(device, data) {
   const count = data.count;
@@ -6721,6 +8235,7 @@ class GSSplatRendererMobile {
     __publicField(this, "positionsBuffer", null);
     // Bounding box
     __publicField(this, "boundingBox", null);
+    __publicField(this, "cpuPositions", null);
     // 帧计数（用于排序频率控制）
     __publicField(this, "frameCount", 0);
     __publicField(this, "sortEveryNFrames", 1);
@@ -6937,7 +8452,7 @@ class GSSplatRendererMobile {
       },
       depthStencil: {
         format: this.renderer.depthFormat,
-        depthWriteEnabled: false,
+        depthWriteEnabled: true,
         depthCompare: "always"
       }
     });
@@ -6967,6 +8482,7 @@ class GSSplatRendererMobile {
       }
       this.compressedTextures = compressSplatsToTextures(device, data);
       this.boundingBox = this.computeBoundingBox(data);
+      this.cpuPositions = new Float32Array(data.positions);
       this.positionsBuffer = device.createBuffer({
         size: data.count * 12,
         // 3 floats per position
@@ -7044,7 +8560,7 @@ class GSSplatRendererMobile {
     }
     const positions = data.positions;
     const min = [positions[0], positions[1], positions[2]];
-    const max = [positions[0], positions[1], positions[2]];
+    const max2 = [positions[0], positions[1], positions[2]];
     for (let i = 1; i < data.count; i++) {
       const x = positions[i * 3 + 0];
       const y = positions[i * 3 + 1];
@@ -7052,20 +8568,20 @@ class GSSplatRendererMobile {
       min[0] = Math.min(min[0], x);
       min[1] = Math.min(min[1], y);
       min[2] = Math.min(min[2], z);
-      max[0] = Math.max(max[0], x);
-      max[1] = Math.max(max[1], y);
-      max[2] = Math.max(max[2], z);
+      max2[0] = Math.max(max2[0], x);
+      max2[1] = Math.max(max2[1], y);
+      max2[2] = Math.max(max2[2], z);
     }
     const center = [
-      (min[0] + max[0]) / 2,
-      (min[1] + max[1]) / 2,
-      (min[2] + max[2]) / 2
+      (min[0] + max2[0]) / 2,
+      (min[1] + max2[1]) / 2,
+      (min[2] + max2[2]) / 2
     ];
-    const dx = max[0] - min[0];
-    const dy = max[1] - min[1];
-    const dz = max[2] - min[2];
+    const dx = max2[0] - min[0];
+    const dy = max2[1] - min[1];
+    const dz = max2[2] - min[2];
     const radius = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2;
-    return { min, max, center, radius };
+    return { min, max: max2, center, radius };
   }
   /**
    * 渲染
@@ -7119,6 +8635,9 @@ class GSSplatRendererMobile {
   getBoundingBox() {
     return this.boundingBox;
   }
+  getCPUPositions() {
+    return this.cpuPositions;
+  }
   /**
    * 设置排序频率
    * @param n 每 n 帧排序一次
@@ -7254,14 +8773,40 @@ class SceneManager {
     return this.meshRenderer.removeMeshByIndex(index);
   }
   // ============================================
+  // 覆盖层 Mesh 管理（热点等）
+  // ============================================
+  getOverlayMeshCount() {
+    return this.meshRenderer.getOverlayMeshCount();
+  }
+  getOverlayMeshByIndex(index) {
+    return this.meshRenderer.getOverlayMeshByIndex(index);
+  }
+  getOverlayMeshRange(startIndex, count) {
+    const meshes = [];
+    for (let i = 0; i < count; i++) {
+      const mesh = this.meshRenderer.getOverlayMeshByIndex(startIndex + i);
+      if (mesh) meshes.push(mesh);
+    }
+    return meshes;
+  }
+  removeOverlayMeshByIndex(index) {
+    return this.meshRenderer.removeOverlayMeshByIndex(index);
+  }
+  getOverlayMeshColor(index) {
+    return this.meshRenderer.getOverlayMeshColor(index);
+  }
+  setOverlayMeshRangeColor(startIndex, count, r, g, b, a = 1) {
+    return this.meshRenderer.setOverlayMeshRangeColor(startIndex, count, r, g, b, a);
+  }
+  // ============================================
   // Splat 管理
   // ============================================
   /**
    * 获取 Splat 数量
    */
   getSplatCount() {
-    var _a;
-    return ((_a = this.gsRenderer) == null ? void 0 : _a.getSplatCount()) ?? 0;
+    var _a2;
+    return ((_a2 = this.gsRenderer) == null ? void 0 : _a2.getSplatCount()) ?? 0;
   }
   /**
    * 清空 Splats
@@ -7279,43 +8824,43 @@ class SceneManager {
    * 设置 Splat 位置
    */
   setSplatPosition(x, y, z) {
-    var _a;
-    (_a = this.gsRenderer) == null ? void 0 : _a.setPosition(x, y, z);
+    var _a2;
+    (_a2 = this.gsRenderer) == null ? void 0 : _a2.setPosition(x, y, z);
   }
   /**
    * 获取 Splat 位置
    */
   getSplatPosition() {
-    var _a;
-    return ((_a = this.gsRenderer) == null ? void 0 : _a.getPosition()) ?? null;
+    var _a2;
+    return ((_a2 = this.gsRenderer) == null ? void 0 : _a2.getPosition()) ?? null;
   }
   /**
    * 设置 Splat 旋转
    */
   setSplatRotation(x, y, z) {
-    var _a;
-    (_a = this.gsRenderer) == null ? void 0 : _a.setRotation(x, y, z);
+    var _a2;
+    (_a2 = this.gsRenderer) == null ? void 0 : _a2.setRotation(x, y, z);
   }
   /**
    * 获取 Splat 旋转
    */
   getSplatRotation() {
-    var _a;
-    return ((_a = this.gsRenderer) == null ? void 0 : _a.getRotation()) ?? null;
+    var _a2;
+    return ((_a2 = this.gsRenderer) == null ? void 0 : _a2.getRotation()) ?? null;
   }
   /**
    * 设置 Splat 缩放
    */
   setSplatScale(x, y, z) {
-    var _a;
-    (_a = this.gsRenderer) == null ? void 0 : _a.setScale(x, y, z);
+    var _a2;
+    (_a2 = this.gsRenderer) == null ? void 0 : _a2.setScale(x, y, z);
   }
   /**
    * 获取 Splat 缩放
    */
   getSplatScale() {
-    var _a;
-    return ((_a = this.gsRenderer) == null ? void 0 : _a.getScale()) ?? null;
+    var _a2;
+    return ((_a2 = this.gsRenderer) == null ? void 0 : _a2.getScale()) ?? null;
   }
   // ============================================
   // SH 模式
@@ -7324,8 +8869,8 @@ class SceneManager {
    * 设置 SH 模式
    */
   setSHMode(mode) {
-    var _a;
-    if ((_a = this.gsRenderer) == null ? void 0 : _a.setSHMode) {
+    var _a2;
+    if ((_a2 = this.gsRenderer) == null ? void 0 : _a2.setSHMode) {
       this.gsRenderer.setSHMode(mode);
     }
   }
@@ -7333,8 +8878,8 @@ class SceneManager {
    * 获取当前 SH 模式
    */
   getSHMode() {
-    var _a, _b;
-    return ((_b = (_a = this.gsRenderer) == null ? void 0 : _a.getSHMode) == null ? void 0 : _b.call(_a)) ?? 0;
+    var _a2, _b2;
+    return ((_b2 = (_a2 = this.gsRenderer) == null ? void 0 : _a2.getSHMode) == null ? void 0 : _b2.call(_a2)) ?? 0;
   }
   // ============================================
   // Bounding Box 查询
@@ -7342,15 +8887,15 @@ class SceneManager {
   /**
    * 获取 Mesh 的组合 bounding box
    */
-  getMeshBoundingBox() {
+  getBoundingBox() {
     return this.meshRenderer.getCombinedBoundingBox();
   }
   /**
    * 获取 Splat 的 bounding box
    */
   getSplatBoundingBox() {
-    var _a;
-    return ((_a = this.gsRenderer) == null ? void 0 : _a.getBoundingBox()) ?? null;
+    var _a2;
+    return ((_a2 = this.gsRenderer) == null ? void 0 : _a2.getBoundingBox()) ?? null;
   }
   /**
    * 获取指定 Mesh 范围的组合 bounding box
@@ -7393,16 +8938,16 @@ class SceneManager {
   getSceneBoundingBox() {
     let combinedMin = null;
     let combinedMax = null;
-    const meshBBox = this.getMeshBoundingBox();
+    const meshBBox = this.getBoundingBox();
     if (meshBBox) {
-      combinedMin = [...meshBBox.min];
-      combinedMax = [...meshBBox.max];
+      combinedMin = [meshBBox.min[0], meshBBox.min[1], meshBBox.min[2]];
+      combinedMax = [meshBBox.max[0], meshBBox.max[1], meshBBox.max[2]];
     }
     const splatBBox = this.getSplatBoundingBox();
     if (splatBBox) {
       if (combinedMin === null || combinedMax === null) {
-        combinedMin = [...splatBBox.min];
-        combinedMax = [...splatBBox.max];
+        combinedMin = [splatBBox.min[0], splatBBox.min[1], splatBBox.min[2]];
+        combinedMax = [splatBBox.max[0], splatBBox.max[1], splatBBox.max[2]];
       } else {
         combinedMin[0] = Math.min(combinedMin[0], splatBBox.min[0]);
         combinedMin[1] = Math.min(combinedMin[1], splatBBox.min[1]);
@@ -9117,7 +10662,7 @@ class ArcShape extends Shape {
     const dynRotY = this._dynamicRotation.y * Math.PI / 180;
     const dynRotZ = this._dynamicRotation.z * Math.PI / 180;
     const dynQuat = Quat.fromEuler(dynRotX, dynRotY, dynRotZ);
-    const finalQuat = baseQuat.multiply(dynQuat);
+    const finalQuat = dynQuat.multiply(baseQuat);
     return Mat4.compose(this._position, finalQuat, this._scale);
   }
   /**
@@ -9612,7 +11157,7 @@ const RING_FACING_EPSILON = 1e-4;
 const PERS_SCALE_RATIO = 0.3;
 const MIN_SCALE = 1e-4;
 const RAD_TO_DEG = 180 / Math.PI;
-class TransformGizmoV2 {
+class TransformGizmo {
   constructor(config) {
     __publicField(this, "renderer");
     __publicField(this, "camera");
@@ -10272,8 +11817,8 @@ class TransformGizmoV2 {
     const forward = gizmoRot.transformVector(new Vec3(0, 0, 1));
     const xArc = this._shapes.get("x");
     if (xArc) {
-      const angle = Math.atan2(localFacingDir.z, localFacingDir.y) * RAD_TO_DEG;
-      xArc.setDynamicRotation(new Vec3(0, angle - 90, 0));
+      const angle = -Math.atan2(localFacingDir.y, localFacingDir.z) * RAD_TO_DEG;
+      xArc.setDynamicRotation(new Vec3(angle, 0, 0));
       const dot = facingDir.dot(right);
       if (!this._dragging) {
         const showSector = 1 - Math.abs(dot) > RING_FACING_EPSILON;
@@ -10488,7 +12033,7 @@ class TransformGizmoV2 {
     }
   }
   _updateHover(axis, isPlane) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a2, _b2, _c, _d, _e, _f, _g;
     if (this._dragging) return;
     if (this._hoverAxis !== axis) {
       for (const shape of this._shapes.values()) {
@@ -10498,8 +12043,8 @@ class TransformGizmoV2 {
       this._hoverIsPlane = isPlane;
       if (axis) {
         if (axis === "xyz") {
-          (_a = this._shapes.get("x")) == null ? void 0 : _a.hover(true);
-          (_b = this._shapes.get("y")) == null ? void 0 : _b.hover(true);
+          (_a2 = this._shapes.get("x")) == null ? void 0 : _a2.hover(true);
+          (_b2 = this._shapes.get("y")) == null ? void 0 : _b2.hover(true);
           (_c = this._shapes.get("z")) == null ? void 0 : _c.hover(true);
           (_d = this._shapes.get("xyz")) == null ? void 0 : _d.hover(true);
         } else if (axis === "f") {
@@ -10833,7 +12378,7 @@ class GizmoManager {
     this.canvas = canvas;
     this.controls = controls;
     this.viewportGizmo = new ViewportGizmo(renderer, camera, canvas);
-    this.transformGizmo = new TransformGizmoV2({ renderer, camera, canvas });
+    this.transformGizmo = new TransformGizmo({ renderer, camera, canvas });
     this.transformGizmo.init();
     this.boundingBoxRenderer = new BoundingBoxRenderer(renderer, camera);
     this.transformGizmo.setOnDragStateChange((isDragging) => {
@@ -10973,6 +12518,946 @@ class GizmoManager {
     this.boundingBoxRenderer.destroy();
   }
 }
+class HotspotManager {
+  constructor(renderer, camera, canvas, controls, meshRenderer) {
+    __publicField(this, "camera");
+    __publicField(this, "renderer");
+    __publicField(this, "controls");
+    __publicField(this, "meshRenderer");
+    __publicField(this, "objLoader");
+    __publicField(this, "canvas");
+    __publicField(this, "active", false);
+    __publicField(this, "gsRenderer", null);
+    // 圆圈指示器
+    __publicField(this, "indicatorMesh", null);
+    __publicField(this, "indicatorAdded", false);
+    // 已放置的热点
+    __publicField(this, "hotspots", []);
+    // 当前命中点缓存
+    __publicField(this, "currentHit", null);
+    // 指示器变换状态缓存（点击时用于热点放置）
+    __publicField(this, "indicatorTransform", null);
+    // OBJ 模型 URL
+    __publicField(this, "hotspotOBJUrl", "");
+    // 事件处理函数引用
+    __publicField(this, "boundOnMouseMove");
+    __publicField(this, "boundOnMouseDown");
+    __publicField(this, "boundOnMouseUp");
+    __publicField(this, "boundOnKeyDown");
+    // 拖拽检测
+    __publicField(this, "mouseDownPos", null);
+    __publicField(this, "isDragging", false);
+    __publicField(this, "DRAG_THRESHOLD", 5);
+    // rAF 驱动的流畅更新
+    __publicField(this, "pendingMouseX", 0);
+    __publicField(this, "pendingMouseY", 0);
+    __publicField(this, "hasPendingMove", false);
+    __publicField(this, "rafId", 0);
+    // 法线缓存：如果命中点没有大变化则复用上次法线
+    __publicField(this, "lastHitIdx", -1);
+    __publicField(this, "lastNormal", [0, 1, 0]);
+    // 指示器半径（世界空间基准）
+    __publicField(this, "indicatorBaseRadius", 0.02);
+    // 搜索邻域的屏幕空间半径（像素）
+    __publicField(this, "pickRadiusPx", 20);
+    // 回调
+    __publicField(this, "onHotspotPlaced", null);
+    __publicField(this, "onModeChanged", null);
+    // ============================================
+    // 事件处理
+    // ============================================
+    // Current mouse pixel position in device pixels (for GPU readback request)
+    __publicField(this, "pickPixelX", -1);
+    __publicField(this, "pickPixelY", -1);
+    // Last client coords for CPU fallback
+    __publicField(this, "lastClientX", 0);
+    __publicField(this, "lastClientY", 0);
+    // True when mouse has moved since last consumeGPUResult that produced a result
+    __publicField(this, "pickDirty", false);
+    this.renderer = renderer;
+    this.camera = camera;
+    this.canvas = canvas;
+    this.controls = controls;
+    this.meshRenderer = meshRenderer;
+    this.objLoader = new OBJLoader(renderer.device);
+    this.boundOnMouseMove = this.onMouseMove.bind(this);
+    this.boundOnMouseDown = this.onMouseDown.bind(this);
+    this.boundOnMouseUp = this.onMouseUp.bind(this);
+    this.boundOnKeyDown = this.onKeyDown.bind(this);
+  }
+  setGSRenderer(gsRenderer) {
+    this.gsRenderer = gsRenderer;
+    if (gsRenderer) {
+      const bbox = gsRenderer.getBoundingBox();
+      if (bbox) {
+        this.indicatorBaseRadius = bbox.radius * 8e-3;
+      }
+    }
+  }
+  setHotspotOBJUrl(url) {
+    this.hotspotOBJUrl = url;
+  }
+  enter() {
+    var _a2;
+    if (this.active) return;
+    if (!this.gsRenderer || !this.gsRenderer.getCPUPositions()) {
+      console.warn("HotspotManager: 没有可用的 GS 数据");
+      return;
+    }
+    this.active = true;
+    this.canvas.style.cursor = "none";
+    this.createIndicatorMesh();
+    this.canvas.addEventListener("mousemove", this.boundOnMouseMove);
+    this.canvas.addEventListener("mousedown", this.boundOnMouseDown);
+    this.canvas.addEventListener("mouseup", this.boundOnMouseUp);
+    window.addEventListener("keydown", this.boundOnKeyDown);
+    (_a2 = this.onModeChanged) == null ? void 0 : _a2.call(this, true);
+  }
+  exit() {
+    var _a2;
+    if (!this.active) return;
+    this.active = false;
+    this.canvas.style.cursor = "";
+    this.canvas.removeEventListener("mousemove", this.boundOnMouseMove);
+    this.canvas.removeEventListener("mousedown", this.boundOnMouseDown);
+    this.canvas.removeEventListener("mouseup", this.boundOnMouseUp);
+    window.removeEventListener("keydown", this.boundOnKeyDown);
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+    this.hasPendingMove = false;
+    this.hideIndicator();
+    this.currentHit = null;
+    this.mouseDownPos = null;
+    this.isDragging = false;
+    this.lastHitIdx = -1;
+    this.pickPixelX = -1;
+    this.pickPixelY = -1;
+    this.pickDirty = false;
+    (_a2 = this.onModeChanged) == null ? void 0 : _a2.call(this, false);
+  }
+  isActive() {
+    return this.active;
+  }
+  getHotspots() {
+    return [...this.hotspots];
+  }
+  setOnHotspotPlaced(cb) {
+    this.onHotspotPlaced = cb;
+  }
+  setOnModeChanged(cb) {
+    this.onModeChanged = cb;
+  }
+  /**
+   * Returns the current pick pixel coordinates in device pixels.
+   * Called by the render loop to pass to prepareDepthNormalPass.
+   * Returns [-1, -1] when no pick is needed.
+   */
+  getPickPixel() {
+    return [this.pickPixelX, this.pickPixelY];
+  }
+  onMouseMove(e) {
+    if (!this.active) return;
+    if (this.mouseDownPos) {
+      const dx = e.clientX - this.mouseDownPos.x;
+      const dy = e.clientY - this.mouseDownPos.y;
+      if (dx * dx + dy * dy > this.DRAG_THRESHOLD * this.DRAG_THRESHOLD) {
+        this.isDragging = true;
+      }
+    }
+    this.pendingMouseX = e.clientX;
+    this.pendingMouseY = e.clientY;
+    if (!this.hasPendingMove) {
+      this.hasPendingMove = true;
+      this.rafId = requestAnimationFrame(() => this.processMouseMove());
+    }
+  }
+  processMouseMove() {
+    this.hasPendingMove = false;
+    if (!this.active) return;
+    const rect = this.canvas.getBoundingClientRect();
+    const dpr = this.canvas.width / rect.width;
+    this.pickPixelX = (this.pendingMouseX - rect.left) * dpr;
+    this.pickPixelY = (this.pendingMouseY - rect.top) * dpr;
+    this.lastClientX = this.pendingMouseX;
+    this.lastClientY = this.pendingMouseY;
+    this.pickDirty = true;
+  }
+  /**
+   * 读取上一帧的深度法线GPU回读结果，更新指示器
+   * 每帧在App.Render()中调用
+   * 如果GPU没有回读结果，则使用CPU拾取
+   */
+  consumeGPUResult() {
+    var _a2;
+    if (!this.active || !this.pickDirty) return;
+    let hit = null;
+    if ((_a2 = this.gsRenderer) == null ? void 0 : _a2.getDepthNormal) {
+      const result = this.gsRenderer.getDepthNormal();
+      if (result) {
+        const dist = Math.sqrt(
+          (result.worldPos[0] - this.camera.position[0]) ** 2 + (result.worldPos[1] - this.camera.position[1]) ** 2 + (result.worldPos[2] - this.camera.position[2]) ** 2
+        );
+        hit = { point: result.worldPos, normal: result.normal, distance: dist };
+      }
+    }
+    if (!hit) {
+      hit = this.raycastSplatsCPU(this.lastClientX, this.lastClientY);
+    }
+    this.pickDirty = false;
+    this.currentHit = hit;
+    if (hit) {
+      this.updateIndicator(hit.point, hit.normal);
+      this.showIndicator();
+    } else {
+      this.hideIndicator();
+    }
+  }
+  onMouseDown(e) {
+    if (!this.active || e.button !== 0) return;
+    this.mouseDownPos = { x: e.clientX, y: e.clientY };
+    this.isDragging = false;
+  }
+  onMouseUp(e) {
+    if (!this.active || e.button !== 0) return;
+    if (!this.isDragging && this.currentHit) {
+      this.placeHotspot(this.currentHit.point, this.currentHit.normal);
+    }
+    this.mouseDownPos = null;
+    this.isDragging = false;
+  }
+  onKeyDown(e) {
+    if (e.key === "Escape") {
+      this.exit();
+    }
+  }
+  // ============================================
+  // 射线拾取
+  // ============================================
+  raycastSplatsCPU(clientX, clientY) {
+    var _a2;
+    const positions = (_a2 = this.gsRenderer) == null ? void 0 : _a2.getCPUPositions();
+    if (!positions) return null;
+    const rect = this.canvas.getBoundingClientRect();
+    const ndcX = (clientX - rect.left) / rect.width * 2 - 1;
+    const ndcY = -((clientY - rect.top) / rect.height * 2 - 1);
+    const rayOrigin = this.camera.position;
+    const modelMatrix = this.gsRenderer.getModelMatrix();
+    const vp = this.camera.viewProjectionMatrix;
+    const count = positions.length / 3;
+    const step = count > 3e5 ? Math.ceil(count / 3e5) : 1;
+    const halfW = rect.width / 2;
+    const halfH = rect.height / 2;
+    const pickRadSq = this.pickRadiusPx * this.pickRadiusPx;
+    let bestCamDistSq = Infinity;
+    let bestIdx = -1;
+    let bestScreenDistSq = Infinity;
+    const m0 = modelMatrix[0], m1 = modelMatrix[1], m2 = modelMatrix[2];
+    const m4 = modelMatrix[4], m5 = modelMatrix[5], m6 = modelMatrix[6];
+    const m8 = modelMatrix[8], m9 = modelMatrix[9], m10 = modelMatrix[10];
+    const m12 = modelMatrix[12], m13 = modelMatrix[13], m14 = modelMatrix[14];
+    const v0 = vp[0], v1 = vp[1], v3 = vp[3];
+    const v4 = vp[4], v5 = vp[5], v7 = vp[7];
+    const v8 = vp[8], v9 = vp[9], v11 = vp[11];
+    const v12 = vp[12], v13 = vp[13], v15 = vp[15];
+    const rox = rayOrigin[0], roy = rayOrigin[1], roz = rayOrigin[2];
+    for (let i = 0; i < count; i += step) {
+      const i3 = i * 3;
+      const lx = positions[i3], ly = positions[i3 + 1], lz = positions[i3 + 2];
+      const tx = m0 * lx + m4 * ly + m8 * lz + m12;
+      const ty = m1 * lx + m5 * ly + m9 * lz + m13;
+      const tz = m2 * lx + m6 * ly + m10 * lz + m14;
+      const cw = v3 * tx + v7 * ty + v11 * tz + v15;
+      if (cw <= 0) continue;
+      const invCw = 1 / cw;
+      const pixX = ((v0 * tx + v4 * ty + v8 * tz + v12) * invCw - ndcX) * halfW;
+      const pixY = ((v1 * tx + v5 * ty + v9 * tz + v13) * invCw - ndcY) * halfH;
+      const screenDistSq = pixX * pixX + pixY * pixY;
+      if (screenDistSq < pickRadSq) {
+        const dx = tx - rox, dy = ty - roy, dz = tz - roz;
+        const camDistSq = dx * dx + dy * dy + dz * dz;
+        if (camDistSq < bestCamDistSq * 0.98 || camDistSq < bestCamDistSq * 1.02 && screenDistSq < bestScreenDistSq) {
+          bestCamDistSq = camDistSq;
+          bestScreenDistSq = screenDistSq;
+          bestIdx = i;
+        }
+      }
+    }
+    if (bestIdx < 0) return null;
+    const hx = positions[bestIdx * 3], hy = positions[bestIdx * 3 + 1], hz = positions[bestIdx * 3 + 2];
+    const hitPoint = [
+      m0 * hx + m4 * hy + m8 * hz + m12,
+      m1 * hx + m5 * hy + m9 * hz + m13,
+      m2 * hx + m6 * hy + m10 * hz + m14
+    ];
+    let normal;
+    if (bestIdx === this.lastHitIdx) {
+      normal = [...this.lastNormal];
+    } else {
+      normal = this.estimateNormal(positions, bestIdx, modelMatrix);
+      this.lastHitIdx = bestIdx;
+      this.lastNormal = [...normal];
+    }
+    const toCamX = rox - hitPoint[0], toCamY = roy - hitPoint[1], toCamZ = roz - hitPoint[2];
+    if (normal[0] * toCamX + normal[1] * toCamY + normal[2] * toCamZ < 0) {
+      normal[0] = -normal[0];
+      normal[1] = -normal[1];
+      normal[2] = -normal[2];
+    }
+    return { point: hitPoint, normal, distance: Math.sqrt(bestCamDistSq) };
+  }
+  // ============================================
+  // 法线估计 (局部 PCA)
+  // ============================================
+  estimateNormal(positions, centerIdx, modelMatrix) {
+    var _a2;
+    const count = positions.length / 3;
+    const m = modelMatrix;
+    const cx = positions[centerIdx * 3 + 0];
+    const cy = positions[centerIdx * 3 + 1];
+    const cz = positions[centerIdx * 3 + 2];
+    const wcx = m[0] * cx + m[4] * cy + m[8] * cz + m[12];
+    const wcy = m[1] * cx + m[5] * cy + m[9] * cz + m[13];
+    const wcz = m[2] * cx + m[6] * cy + m[10] * cz + m[14];
+    const bbox = (_a2 = this.gsRenderer) == null ? void 0 : _a2.getBoundingBox();
+    const searchRadius = bbox ? bbox.radius * 0.015 : 0.3;
+    const searchRadiusSq = searchRadius * searchRadius;
+    const neighbors = [];
+    const maxNeighbors = 80;
+    const step = count > 15e4 ? Math.ceil(count / 15e4) : 1;
+    for (let i = 0; i < count; i += step) {
+      const px = positions[i * 3 + 0];
+      const py = positions[i * 3 + 1];
+      const pz = positions[i * 3 + 2];
+      const wpx = m[0] * px + m[4] * py + m[8] * pz + m[12];
+      const wpy = m[1] * px + m[5] * py + m[9] * pz + m[13];
+      const wpz = m[2] * px + m[6] * py + m[10] * pz + m[14];
+      const dx = wpx - wcx;
+      const dy = wpy - wcy;
+      const dz = wpz - wcz;
+      const distSq = dx * dx + dy * dy + dz * dz;
+      if (distSq < searchRadiusSq && distSq > 1e-12) {
+        neighbors.push({ pos: [wpx, wpy, wpz], distSq });
+      }
+    }
+    if (neighbors.length < 6) {
+      const bigRadiusSq = searchRadiusSq * 4;
+      neighbors.length = 0;
+      for (let i = 0; i < count; i += step) {
+        const px = positions[i * 3 + 0];
+        const py = positions[i * 3 + 1];
+        const pz = positions[i * 3 + 2];
+        const wpx = m[0] * px + m[4] * py + m[8] * pz + m[12];
+        const wpy = m[1] * px + m[5] * py + m[9] * pz + m[13];
+        const wpz = m[2] * px + m[6] * py + m[10] * pz + m[14];
+        const dx = wpx - wcx;
+        const dy = wpy - wcy;
+        const dz = wpz - wcz;
+        const distSq = dx * dx + dy * dy + dz * dz;
+        if (distSq < bigRadiusSq && distSq > 1e-12) {
+          neighbors.push({ pos: [wpx, wpy, wpz], distSq });
+        }
+      }
+    }
+    if (neighbors.length < 3) return [0, 1, 0];
+    if (neighbors.length > maxNeighbors) {
+      neighbors.sort((a, b) => a.distSq - b.distSq);
+      neighbors.length = maxNeighbors;
+    }
+    const roughNormal = this.weightedPCA(neighbors, wcx, wcy, wcz);
+    const [rnx, rny, rnz] = roughNormal;
+    const projections = [];
+    for (const nb of neighbors) {
+      const d = (nb.pos[0] - wcx) * rnx + (nb.pos[1] - wcy) * rny + (nb.pos[2] - wcz) * rnz;
+      projections.push(d);
+    }
+    const absDev = projections.map((d) => Math.abs(d));
+    absDev.sort((a, b) => a - b);
+    const mad = absDev[Math.floor(absDev.length / 2)] || 1e-8;
+    const inlierThreshold = Math.max(mad * 3, searchRadius * 0.05);
+    const inliers = neighbors.filter(
+      (_, i) => Math.abs(projections[i]) < inlierThreshold
+    );
+    if (inliers.length < 3) return roughNormal;
+    return this.weightedPCA(inliers, wcx, wcy, wcz);
+  }
+  /**
+   * 距离加权 PCA：离中心越近的点权重越高
+   */
+  weightedPCA(neighbors, cx, cy, cz) {
+    let totalW = 0;
+    let mx = 0, my = 0, mz = 0;
+    for (const nb of neighbors) {
+      const w = 1 / (nb.distSq + 1e-10);
+      mx += nb.pos[0] * w;
+      my += nb.pos[1] * w;
+      mz += nb.pos[2] * w;
+      totalW += w;
+    }
+    mx /= totalW;
+    my /= totalW;
+    mz /= totalW;
+    let c00 = 0, c01 = 0, c02 = 0;
+    let c11 = 0, c12 = 0, c22 = 0;
+    for (const nb of neighbors) {
+      const w = 1 / (nb.distSq + 1e-10);
+      const dx = nb.pos[0] - mx;
+      const dy = nb.pos[1] - my;
+      const dz = nb.pos[2] - mz;
+      c00 += w * dx * dx;
+      c01 += w * dx * dy;
+      c02 += w * dx * dz;
+      c11 += w * dy * dy;
+      c12 += w * dy * dz;
+      c22 += w * dz * dz;
+    }
+    c00 /= totalW;
+    c01 /= totalW;
+    c02 /= totalW;
+    c11 /= totalW;
+    c12 /= totalW;
+    c22 /= totalW;
+    return this.smallestEigenvector(c00, c01, c02, c11, c12, c22);
+  }
+  /**
+   * 求 3x3 对称矩阵最小特征值对应的特征向量（偏移幂迭代）
+   */
+  smallestEigenvector(a00, a01, a02, a11, a12, a22) {
+    let vx = 0.577, vy = 0.577, vz = 0.577;
+    for (let iter = 0; iter < 30; iter++) {
+      const nx = a00 * vx + a01 * vy + a02 * vz;
+      const ny = a01 * vx + a11 * vy + a12 * vz;
+      const nz = a02 * vx + a12 * vy + a22 * vz;
+      const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+      if (len < 1e-12) return [0, 1, 0];
+      vx = nx / len;
+      vy = ny / len;
+      vz = nz / len;
+    }
+    const lambdaMax = a00 * vx * vx + a11 * vy * vy + a22 * vz * vz + 2 * a01 * vx * vy + 2 * a02 * vx * vz + 2 * a12 * vy * vz;
+    const b00 = lambdaMax - a00;
+    const b01 = -a01;
+    const b02 = -a02;
+    const b11 = lambdaMax - a11;
+    const b12 = -a12;
+    const b22 = lambdaMax - a22;
+    vx = 0.577;
+    vy = 0.577;
+    vz = 0.577;
+    for (let iter = 0; iter < 30; iter++) {
+      const nx = b00 * vx + b01 * vy + b02 * vz;
+      const ny = b01 * vx + b11 * vy + b12 * vz;
+      const nz = b02 * vx + b12 * vy + b22 * vz;
+      const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+      if (len < 1e-12) return [0, 1, 0];
+      vx = nx / len;
+      vy = ny / len;
+      vz = nz / len;
+    }
+    return [vx, vy, vz];
+  }
+  // ============================================
+  // 圆圈指示器
+  // ============================================
+  createIndicatorMesh() {
+    if (this.indicatorMesh) return;
+    const device = this.renderer.device;
+    const segments = 48;
+    const outerRadius = this.indicatorBaseRadius;
+    const innerRadius = outerRadius * 0.92;
+    const vertexCount = segments * 2;
+    const vertexData = new Float32Array(vertexCount * 6);
+    for (let i = 0; i < segments; i++) {
+      const angle = i / segments * Math.PI * 2;
+      const cos = Math.cos(angle);
+      const sin = Math.sin(angle);
+      const oi = i * 2 * 6;
+      vertexData[oi] = cos * outerRadius;
+      vertexData[oi + 1] = sin * outerRadius;
+      vertexData[oi + 2] = 0;
+      vertexData[oi + 3] = 0;
+      vertexData[oi + 4] = 0;
+      vertexData[oi + 5] = 1;
+      const ii = (i * 2 + 1) * 6;
+      vertexData[ii] = cos * innerRadius;
+      vertexData[ii + 1] = sin * innerRadius;
+      vertexData[ii + 2] = 0;
+      vertexData[ii + 3] = 0;
+      vertexData[ii + 4] = 0;
+      vertexData[ii + 5] = 1;
+    }
+    const indices = [];
+    for (let i = 0; i < segments; i++) {
+      const o0 = i * 2, i0 = i * 2 + 1;
+      const o1 = (i + 1) % segments * 2, i1 = (i + 1) % segments * 2 + 1;
+      indices.push(o0, o1, i0);
+      indices.push(i0, o1, i1);
+    }
+    const vertexBuffer = device.createBuffer({
+      size: vertexData.byteLength,
+      usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST
+    });
+    device.queue.writeBuffer(vertexBuffer, 0, vertexData);
+    const indexData = new Uint16Array(indices);
+    const alignedSize = Math.ceil(indexData.byteLength / 4) * 4;
+    const alignedBuf = new Uint8Array(alignedSize);
+    alignedBuf.set(
+      new Uint8Array(
+        indexData.buffer,
+        indexData.byteOffset,
+        indexData.byteLength
+      )
+    );
+    const indexBuffer = device.createBuffer({
+      size: alignedSize,
+      usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST
+    });
+    device.queue.writeBuffer(indexBuffer, 0, alignedBuf);
+    const bbox = {
+      min: [-outerRadius, -outerRadius, 0],
+      max: [outerRadius, outerRadius, 0],
+      center: [0, 0, 0],
+      radius: outerRadius
+    };
+    this.indicatorMesh = new Mesh(
+      vertexBuffer,
+      vertexCount,
+      indexBuffer,
+      indices.length,
+      bbox
+    );
+    this.indicatorMesh.hasUV = false;
+    this.indicatorMesh.indexFormat = "uint16";
+  }
+  showIndicator() {
+    if (!this.indicatorMesh || this.indicatorAdded) return;
+    const material = {
+      baseColorFactor: [1, 1, 1, 0.85],
+      baseColorTexture: null,
+      metallicFactor: 0,
+      roughnessFactor: 1,
+      doubleSided: true
+    };
+    this.meshRenderer.addOverlayMesh(this.indicatorMesh, material);
+    this.indicatorAdded = true;
+  }
+  hideIndicator() {
+    if (!this.indicatorMesh || !this.indicatorAdded) return;
+    this.meshRenderer.detachOverlayMesh(this.indicatorMesh);
+    this.indicatorAdded = false;
+  }
+  updateIndicator(point, normal) {
+    if (!this.indicatorMesh) return;
+    const camPos = this.camera.position;
+    const dist = Math.sqrt(
+      (point[0] - camPos[0]) ** 2 + (point[1] - camPos[1]) ** 2 + (point[2] - camPos[2]) ** 2
+    );
+    const targetScreenPx = 40;
+    const halfVFov = this.camera.fov / 2;
+    const halfHFov = Math.atan(Math.tan(halfVFov) * this.camera.aspect);
+    const visualRadius = dist * Math.tan(halfHFov) * (targetScreenPx / this.canvas.clientWidth);
+    const [nx, ny, nz] = normal;
+    const up = Math.abs(ny) < 0.99 ? [0, 1, 0] : [1, 0, 0];
+    let rx = up[1] * nz - up[2] * ny;
+    let ry = up[2] * nx - up[0] * nz;
+    let rz = up[0] * ny - up[1] * nx;
+    let rLen = Math.sqrt(rx * rx + ry * ry + rz * rz);
+    if (rLen < 1e-8) {
+      rx = 1;
+      ry = 0;
+      rz = 0;
+      rLen = 1;
+    }
+    rx /= rLen;
+    ry /= rLen;
+    rz /= rLen;
+    let fx = ny * rz - nz * ry;
+    let fy = nz * rx - nx * rz;
+    let fz = nx * ry - ny * rx;
+    let fLen = Math.sqrt(fx * fx + fy * fy + fz * fz);
+    if (fLen < 1e-8) {
+      fx = 0;
+      fy = 0;
+      fz = 1;
+      fLen = 1;
+    }
+    fx /= fLen;
+    fy /= fLen;
+    fz /= fLen;
+    const scale = visualRadius / this.indicatorBaseRadius;
+    const m = this.indicatorMesh.modelMatrix;
+    m[0] = rx * scale;
+    m[1] = ry * scale;
+    m[2] = rz * scale;
+    m[3] = 0;
+    m[4] = fx * scale;
+    m[5] = fy * scale;
+    m[6] = fz * scale;
+    m[7] = 0;
+    m[8] = nx * scale;
+    m[9] = ny * scale;
+    m[10] = nz * scale;
+    m[11] = 0;
+    const normalOffset = dist * 0.02;
+    m[12] = point[0] + nx * normalOffset;
+    m[13] = point[1] + ny * normalOffset;
+    m[14] = point[2] + nz * normalOffset;
+    m[15] = 1;
+    this.indicatorTransform = {
+      point: [...point],
+      normal: [nx, ny, nz],
+      right: [rx, ry, rz],
+      forward: [fx, fy, fz],
+      visualDiameter: visualRadius * 2,
+      normalOffset
+    };
+  }
+  // ============================================
+  // OBJ 热点放置
+  // ============================================
+  async placeHotspot(point, normal) {
+    var _a2;
+    if (!this.hotspotOBJUrl) {
+      console.warn("HotspotManager: 未设置热点 OBJ 模型 URL");
+      return;
+    }
+    const snap = this.indicatorTransform;
+    if (!snap) {
+      console.warn("HotspotManager: 无指示器状态，跳过放置");
+      return;
+    }
+    this.hideIndicator();
+    try {
+      const loadedMeshes = await this.objLoader.load(this.hotspotOBJUrl);
+      if (loadedMeshes.length === 0) {
+        console.warn("HotspotManager: OBJ 加载无网格");
+        return;
+      }
+      const meshStartIndex = this.meshRenderer.getMeshCount();
+      let placedScale = 1;
+      let placedLocalCenter = [0, 0, 0];
+      const firstBbox = loadedMeshes[0].mesh.getLocalBoundingBox();
+      if (firstBbox) {
+        const modelW = firstBbox.max[0] - firstBbox.min[0];
+        const modelH = firstBbox.max[1] - firstBbox.min[1];
+        const modelD = firstBbox.max[2] - firstBbox.min[2];
+        const modelMaxDim = Math.max(modelW, modelH, modelD, 1e-6);
+        placedScale = snap.visualDiameter / modelMaxDim;
+        placedLocalCenter = [
+          (firstBbox.min[0] + firstBbox.max[0]) / 2,
+          (firstBbox.min[1] + firstBbox.max[1]) / 2,
+          (firstBbox.min[2] + firstBbox.max[2]) / 2
+        ];
+      }
+      for (const { mesh, material } of loadedMeshes) {
+        this.applyIndicatorTransform(mesh, snap);
+        this.meshRenderer.addOverlayMesh(mesh, material);
+      }
+      const info = {
+        position: [...snap.point],
+        normal: [...snap.normal],
+        meshStartIndex,
+        meshCount: loadedMeshes.length,
+        billboard: false,
+        placedScale,
+        placedNormalOffset: snap.normalOffset,
+        placedLocalCenter
+      };
+      this.hotspots.push(info);
+      (_a2 = this.onHotspotPlaced) == null ? void 0 : _a2.call(this, info);
+      console.log(
+        `热点已放置: pos=(${snap.point[0].toFixed(3)}, ${snap.point[1].toFixed(3)}, ${snap.point[2].toFixed(3)}) normal=(${snap.normal[0].toFixed(3)}, ${snap.normal[1].toFixed(3)}, ${snap.normal[2].toFixed(3)})`
+      );
+    } catch (error) {
+      console.error("HotspotManager: 放置热点失败:", error);
+    }
+  }
+  /**
+   * 将 OBJ mesh 的变换设置为与指示器完全一致的大小、位置、朝向。
+   *
+   * 使用指示器缓存的基向量 (right, forward, normal) 和 visualDiameter，
+   * 将 OBJ 缩放到与指示器圆圈等大，居中放置在相同位置。
+   */
+  applyIndicatorTransform(mesh, snap) {
+    const { point, normal, right, forward, visualDiameter, normalOffset } = snap;
+    const [nx, ny, nz] = normal;
+    const [rx, ry, rz] = right;
+    const [fx, fy, fz] = forward;
+    const bbox = mesh.getLocalBoundingBox();
+    let objScale = 1;
+    if (bbox) {
+      const modelW = bbox.max[0] - bbox.min[0];
+      const modelH = bbox.max[1] - bbox.min[1];
+      const modelD = bbox.max[2] - bbox.min[2];
+      const modelMaxDim = Math.max(modelW, modelH, modelD, 1e-6);
+      objScale = visualDiameter / modelMaxDim;
+    }
+    let lcx = 0, lcy = 0, lcz = 0;
+    if (bbox) {
+      lcx = (bbox.min[0] + bbox.max[0]) / 2;
+      lcy = (bbox.min[1] + bbox.max[1]) / 2;
+      lcz = (bbox.min[2] + bbox.max[2]) / 2;
+    }
+    const owx = (rx * lcx + fx * lcy + nx * lcz) * objScale;
+    const owy = (ry * lcx + fy * lcy + ny * lcz) * objScale;
+    const owz = (rz * lcx + fz * lcy + nz * lcz) * objScale;
+    const m = mesh.modelMatrix;
+    m[0] = rx * objScale;
+    m[1] = ry * objScale;
+    m[2] = rz * objScale;
+    m[3] = 0;
+    m[4] = fx * objScale;
+    m[5] = fy * objScale;
+    m[6] = fz * objScale;
+    m[7] = 0;
+    m[8] = nx * objScale;
+    m[9] = ny * objScale;
+    m[10] = nz * objScale;
+    m[11] = 0;
+    m[12] = point[0] + nx * normalOffset - owx;
+    m[13] = point[1] + ny * normalOffset - owy;
+    m[14] = point[2] + nz * normalOffset - owz;
+    m[15] = 1;
+    this.decomposeModelMatrix(mesh);
+  }
+  /**
+   * 从 modelMatrix 反向提取 position / rotation / scale，
+   * 使 Mesh 的分离属性与矩阵保持同步（Gizmo 需要）。
+   */
+  decomposeModelMatrix(mesh) {
+    const m = mesh.modelMatrix;
+    mesh.position[0] = m[12];
+    mesh.position[1] = m[13];
+    mesh.position[2] = m[14];
+    const sx = Math.sqrt(m[0] * m[0] + m[1] * m[1] + m[2] * m[2]);
+    const sy = Math.sqrt(m[4] * m[4] + m[5] * m[5] + m[6] * m[6]);
+    const sz = Math.sqrt(m[8] * m[8] + m[9] * m[9] + m[10] * m[10]);
+    mesh.scale[0] = sx;
+    mesh.scale[1] = sy;
+    mesh.scale[2] = sz;
+    const isx = sx > 1e-8 ? 1 / sx : 0;
+    const isy = sy > 1e-8 ? 1 / sy : 0;
+    const isz = sz > 1e-8 ? 1 / sz : 0;
+    const r00 = m[0] * isx, r10 = m[1] * isx, r20 = m[2] * isx;
+    const r21 = m[6] * isy;
+    const r22 = m[10] * isz;
+    const sinRy = -r20;
+    const ry = Math.asin(Math.max(-1, Math.min(1, sinRy)));
+    const cosRy = Math.cos(ry);
+    let rotX, rotZ;
+    if (Math.abs(cosRy) > 1e-6) {
+      rotX = Math.atan2(r21, r22);
+      rotZ = Math.atan2(r10, r00);
+    } else {
+      rotX = Math.atan2(-m[9] * isz, m[5] * isy);
+      rotZ = 0;
+    }
+    mesh.rotation[0] = rotX;
+    mesh.rotation[1] = ry;
+    mesh.rotation[2] = rotZ;
+  }
+  // ============================================
+  // Billboard 控制
+  // ============================================
+  /**
+   * 设置指定热点的 billboard 模式
+   * @param hotspotIndex 热点索引（在 hotspots 数组中的位置）
+   * @param enabled 是否启用 billboard
+   */
+  setHotspotBillboard(hotspotIndex, enabled) {
+    if (hotspotIndex < 0 || hotspotIndex >= this.hotspots.length) return false;
+    const info = this.hotspots[hotspotIndex];
+    if (info.billboard === enabled) return true;
+    info.billboard = enabled;
+    if (!enabled) {
+      this.restoreHotspotOrientation(info);
+    }
+    return true;
+  }
+  getHotspotBillboard(hotspotIndex) {
+    if (hotspotIndex < 0 || hotspotIndex >= this.hotspots.length) return false;
+    return this.hotspots[hotspotIndex].billboard;
+  }
+  getHotspotCount() {
+    return this.hotspots.length;
+  }
+  /**
+   * 通过 overlay mesh 起始索引找到对应的热点索引
+   */
+  findHotspotIndexByMeshStart(overlayMeshStartIndex) {
+    return this.hotspots.findIndex(
+      (h) => h.meshStartIndex === overlayMeshStartIndex
+    );
+  }
+  /**
+   * 每帧调用：更新所有 billboard 热点朝向相机
+   */
+  updateBillboards() {
+    const camPos = this.camera.position;
+    for (const info of this.hotspots) {
+      if (!info.billboard) continue;
+      const {
+        position,
+        normal,
+        placedScale,
+        placedNormalOffset,
+        placedLocalCenter
+      } = info;
+      const [nx, ny, nz] = normal;
+      const wx = position[0] + nx * placedNormalOffset;
+      const wy = position[1] + ny * placedNormalOffset;
+      const wz = position[2] + nz * placedNormalOffset;
+      let zx = camPos[0] - wx;
+      let zy = camPos[1] - wy;
+      let zz = camPos[2] - wz;
+      const zLen = Math.sqrt(zx * zx + zy * zy + zz * zz);
+      if (zLen < 1e-8) continue;
+      zx /= zLen;
+      zy /= zLen;
+      zz /= zLen;
+      const up = Math.abs(zy) < 0.99 ? [0, 1, 0] : [1, 0, 0];
+      let rx = up[1] * zz - up[2] * zy;
+      let ry = up[2] * zx - up[0] * zz;
+      let rz = up[0] * zy - up[1] * zx;
+      let rLen = Math.sqrt(rx * rx + ry * ry + rz * rz);
+      if (rLen < 1e-8) {
+        rx = 1;
+        ry = 0;
+        rz = 0;
+        rLen = 1;
+      }
+      rx /= rLen;
+      ry /= rLen;
+      rz /= rLen;
+      let fx = zy * rz - zz * ry;
+      let fy = zz * rx - zx * rz;
+      let fz = zx * ry - zy * rx;
+      let fLen = Math.sqrt(fx * fx + fy * fy + fz * fz);
+      if (fLen < 1e-8) {
+        fx = 0;
+        fy = 1;
+        fz = 0;
+        fLen = 1;
+      }
+      fx /= fLen;
+      fy /= fLen;
+      fz /= fLen;
+      const s = placedScale;
+      const [lcx, lcy, lcz] = placedLocalCenter;
+      const owx = (rx * lcx + fx * lcy + zx * lcz) * s;
+      const owy = (ry * lcx + fy * lcy + zy * lcz) * s;
+      const owz = (rz * lcx + fz * lcy + zz * lcz) * s;
+      for (let i = 0; i < info.meshCount; i++) {
+        const mesh = this.meshRenderer.getOverlayMeshByIndex(
+          info.meshStartIndex + i
+        );
+        if (!mesh) continue;
+        const m = mesh.modelMatrix;
+        m[0] = rx * s;
+        m[1] = ry * s;
+        m[2] = rz * s;
+        m[3] = 0;
+        m[4] = fx * s;
+        m[5] = fy * s;
+        m[6] = fz * s;
+        m[7] = 0;
+        m[8] = zx * s;
+        m[9] = zy * s;
+        m[10] = zz * s;
+        m[11] = 0;
+        m[12] = wx - owx;
+        m[13] = wy - owy;
+        m[14] = wz - owz;
+        m[15] = 1;
+        this.decomposeModelMatrix(mesh);
+      }
+    }
+  }
+  /**
+   * 关闭 billboard 时恢复到放置时的法线朝向
+   */
+  restoreHotspotOrientation(info) {
+    const {
+      position,
+      normal,
+      placedScale,
+      placedNormalOffset,
+      placedLocalCenter
+    } = info;
+    const [nx, ny, nz] = normal;
+    const up = Math.abs(ny) < 0.99 ? [0, 1, 0] : [1, 0, 0];
+    let rx = up[1] * nz - up[2] * ny;
+    let ry = up[2] * nx - up[0] * nz;
+    let rz = up[0] * ny - up[1] * nx;
+    let rLen = Math.sqrt(rx * rx + ry * ry + rz * rz);
+    if (rLen < 1e-8) {
+      rx = 1;
+      ry = 0;
+      rz = 0;
+      rLen = 1;
+    }
+    rx /= rLen;
+    ry /= rLen;
+    rz /= rLen;
+    let fx = ny * rz - nz * ry;
+    let fy = nz * rx - nx * rz;
+    let fz = nx * ry - ny * rx;
+    let fLen = Math.sqrt(fx * fx + fy * fy + fz * fz);
+    if (fLen < 1e-8) {
+      fx = 0;
+      fy = 0;
+      fz = 1;
+      fLen = 1;
+    }
+    fx /= fLen;
+    fy /= fLen;
+    fz /= fLen;
+    const s = placedScale;
+    const [lcx, lcy, lcz] = placedLocalCenter;
+    const owx = (rx * lcx + fx * lcy + nx * lcz) * s;
+    const owy = (ry * lcx + fy * lcy + ny * lcz) * s;
+    const owz = (rz * lcx + fz * lcy + nz * lcz) * s;
+    const wx = position[0] + nx * placedNormalOffset;
+    const wy = position[1] + ny * placedNormalOffset;
+    const wz = position[2] + nz * placedNormalOffset;
+    for (let i = 0; i < info.meshCount; i++) {
+      const mesh = this.meshRenderer.getOverlayMeshByIndex(
+        info.meshStartIndex + i
+      );
+      if (!mesh) continue;
+      const m = mesh.modelMatrix;
+      m[0] = rx * s;
+      m[1] = ry * s;
+      m[2] = rz * s;
+      m[3] = 0;
+      m[4] = fx * s;
+      m[5] = fy * s;
+      m[6] = fz * s;
+      m[7] = 0;
+      m[8] = nx * s;
+      m[9] = ny * s;
+      m[10] = nz * s;
+      m[11] = 0;
+      m[12] = wx - owx;
+      m[13] = wy - owy;
+      m[14] = wz - owz;
+      m[15] = 1;
+      this.decomposeModelMatrix(mesh);
+    }
+  }
+  // ============================================
+  // 生命周期
+  // ============================================
+  destroy() {
+    this.exit();
+    if (this.indicatorMesh && !this.indicatorAdded) {
+      this.indicatorMesh.destroy();
+    }
+    this.indicatorMesh = null;
+    this.hotspots = [];
+  }
+}
 class App {
   constructor(canvas) {
     __publicField(this, "canvas");
@@ -10985,6 +13470,7 @@ class App {
     // 子系统管理器
     __publicField(this, "sceneManager");
     __publicField(this, "gizmoManager");
+    __publicField(this, "hotspotManager");
     __publicField(this, "isRunning", false);
     __publicField(this, "animationId", 0);
     // 是否使用移动端渲染器
@@ -11013,6 +13499,13 @@ class App {
       this.canvas,
       this.controls
     );
+    this.hotspotManager = new HotspotManager(
+      this.renderer,
+      this.camera,
+      this.canvas,
+      this.controls,
+      this.meshRenderer
+    );
     window.addEventListener("resize", this.boundOnResize);
   }
   // ============================================
@@ -11086,6 +13579,7 @@ class App {
         gsRenderer.setCompactData(compactData);
         if (onProgress) onProgress(100, "upload");
         this.sceneManager.setGSRenderer(gsRenderer);
+        this.hotspotManager.setGSRenderer(gsRenderer);
         return compactData.count;
       } else {
         gsRenderer = new GSSplatRenderer(this.renderer, this.camera);
@@ -11099,6 +13593,7 @@ class App {
         gsRenderer.setCompactData(compactData);
         if (onProgress) onProgress(100, "upload");
         this.sceneManager.setGSRenderer(gsRenderer);
+        this.hotspotManager.setGSRenderer(gsRenderer);
         return compactData.count;
       }
     } catch (error) {
@@ -11130,6 +13625,7 @@ class App {
       const gsRenderer = new GSSplatRenderer(this.renderer, this.camera);
       gsRenderer.setData(splats);
       this.sceneManager.setGSRenderer(gsRenderer);
+      this.hotspotManager.setGSRenderer(gsRenderer);
       this.useMobileRenderer = false;
       if (onProgress) onProgress(100, "upload");
       return splats.length;
@@ -11137,6 +13633,49 @@ class App {
       throw error;
     }
   }
+  /**
+   * 加载 SOG 文件 (Spatially Ordered Gaussians)
+   */
+  async addSOG(urlOrBuffer, onProgress, isLocalFile = false) {
+    try {
+      const isMobile = isMobileDevice();
+      let buffer;
+      if (typeof urlOrBuffer === "string") {
+        buffer = await this.fetchWithProgress(urlOrBuffer, (downloadProgress) => {
+          if (onProgress) {
+            onProgress(downloadProgress * 0.5, "download");
+          }
+        });
+      } else {
+        buffer = urlOrBuffer;
+        if (onProgress && isLocalFile) {
+          onProgress(50, "download");
+        }
+      }
+      if (onProgress) onProgress(50, "parse");
+      const compactData = await deserializeSOG(buffer, (p, stage) => {
+        if (onProgress) {
+          onProgress(50 + p / 100 * 40, stage);
+        }
+      });
+      if (onProgress) onProgress(90, "upload");
+      let gsRenderer;
+      if (isMobile) {
+        gsRenderer = new GSSplatRendererMobile(this.renderer, this.camera);
+        this.useMobileRenderer = true;
+      } else {
+        gsRenderer = new GSSplatRenderer(this.renderer, this.camera);
+        this.useMobileRenderer = false;
+      }
+      gsRenderer.setCompactData(compactData);
+      this.sceneManager.setGSRenderer(gsRenderer);
+      this.hotspotManager.setGSRenderer(gsRenderer);
+      if (onProgress) onProgress(100, "upload");
+      return compactData.count;
+    } catch (error) {
+      throw error;
+    }
+  }
   /**
    * 添加测试立方体
    */
@@ -11179,7 +13718,8 @@ class App {
   }
   render() {
     this.camera.setAspect(this.renderer.getAspectRatio());
-    this.camera.updateMatrix();
+    this.controls.update();
+    this.hotspotManager.updateBillboards();
     const pass = this.renderer.beginFrame();
     const gsRenderer = this.sceneManager.getGSRenderer();
     if (gsRenderer) {
@@ -11188,6 +13728,11 @@ class App {
     this.meshRenderer.render(pass);
     this.gizmoManager.render(pass);
     this.renderer.endFrame();
+    this.hotspotManager.consumeGPUResult();
+    if (gsRenderer == null ? void 0 : gsRenderer.prepareDepthNormalPass) {
+      const [px, py] = this.hotspotManager.getPickPixel();
+      gsRenderer.prepareDepthNormalPass(px, py);
+    }
   }
   onResize() {
     this.camera.setAspect(this.renderer.getAspectRatio());
@@ -11217,6 +13762,7 @@ class App {
   }
   clearSplats() {
     this.sceneManager.clearSplats();
+    this.hotspotManager.setGSRenderer(null);
     this.useMobileRenderer = false;
   }
   // ============================================
@@ -11271,6 +13817,25 @@ class App {
     return this.sceneManager.setMeshRangeColor(startIndex, count, r, g, b, a);
   }
   // ============================================
+  // 覆盖层 Mesh（热点等）
+  // ============================================
+  getOverlayMeshCount() {
+    return this.sceneManager.getOverlayMeshCount();
+  }
+  removeOverlayMeshByIndex(index) {
+    return this.sceneManager.removeOverlayMeshByIndex(index);
+  }
+  getOverlayMeshColor(index) {
+    return this.sceneManager.getOverlayMeshColor(index);
+  }
+  setOverlayMeshRangeColor(startIndex, count, r, g, b, a = 1) {
+    return this.sceneManager.setOverlayMeshRangeColor(startIndex, count, r, g, b, a);
+  }
+  createOverlayMeshGroupProxy(startIndex, count) {
+    const meshes = this.sceneManager.getOverlayMeshRange(startIndex, count);
+    return this.gizmoManager.createMeshGroupProxy(meshes);
+  }
+  // ============================================
   // 相机控制
   // ============================================
   frameCurrentModel(animate = true) {
@@ -11364,6 +13929,40 @@ class App {
     return this.useMobileRenderer;
   }
   // ============================================
+  // 热点管理
+  // ============================================
+  getHotspotManager() {
+    return this.hotspotManager;
+  }
+  enterHotspotMode(objUrl) {
+    this.hotspotManager.setHotspotOBJUrl(objUrl);
+    this.hotspotManager.enter();
+  }
+  exitHotspotMode() {
+    this.hotspotManager.exit();
+  }
+  isHotspotModeActive() {
+    return this.hotspotManager.isActive();
+  }
+  getHotspots() {
+    return this.hotspotManager.getHotspots();
+  }
+  setHotspotBillboard(hotspotIndex, enabled) {
+    return this.hotspotManager.setHotspotBillboard(hotspotIndex, enabled);
+  }
+  getHotspotBillboard(hotspotIndex) {
+    return this.hotspotManager.getHotspotBillboard(hotspotIndex);
+  }
+  getHotspotCount() {
+    return this.hotspotManager.getHotspotCount();
+  }
+  findHotspotIndexByMeshStart(overlayMeshStartIndex) {
+    return this.hotspotManager.findHotspotIndexByMeshStart(overlayMeshStartIndex);
+  }
+  getOverlayMeshByIndex(index) {
+    return this.sceneManager.getOverlayMeshByIndex(index);
+  }
+  // ============================================
   // 内部方法
   // ============================================
   async fetchWithProgress(url, onProgress) {
@@ -11411,6 +14010,7 @@ class App {
     window.removeEventListener("resize", this.boundOnResize);
     this.sceneManager.destroy();
     this.gizmoManager.destroy();
+    this.hotspotManager.destroy();
     if (this.meshRenderer) {
       this.meshRenderer.destroy();
     }
@@ -11429,16 +14029,13 @@ export {
   DEFAULT_MATERIAL,
   DEFAULT_OBJ_MATERIAL,
   GLBLoader,
-  SHMode as GSSHMode,
   GSSplatRenderer,
   GSSplatRendererMobile,
   GSSplatSorter,
   GSSplatSorterMobile,
   GizmoManager,
-  MeshGroupProxy as GizmoMeshGroupProxy,
   GizmoMode,
-  SplatBoundingBoxProvider as GizmoSplatBoundingBoxProvider,
-  SplatTransformProxy as GizmoSplatTransformProxy,
+  HotspotManager,
   MTLParser,
   Mesh,
   MeshGroupProxy,
@@ -11452,7 +14049,7 @@ export {
   SplatBoundingBoxProvider,
   SplatTransformProxy,
   TextureCache,
-  TransformGizmoV2,
+  TransformGizmo,
   ViewportGizmo,
   calculateTextureDimensions,
   compactDataToGPUBuffer,
@@ -11460,6 +14057,7 @@ export {
   computeBoundingBox$1 as computeBoundingBox,
   createBoundingBoxFromMinMax,
   createTextureFromImageBitmap,
+  deserializeSOG,
   deserializeSplat,
   destroyCompressedTextures,
   getRecommendedDPR,
@@ -11467,6 +14065,7 @@ export {
   isWebGPUSupported,
   loadPLY,
   loadPLYMobile,
+  loadSOG,
   loadSplat,
   loadTextureFromBlob,
   loadTextureFromBuffer,