@d5techs/3dgs-lib 1.4.14 → 1.4.16

package/dist/3dgs-lib.js

@@ -261,6 +261,10 @@ class Renderer {
     __publicField(this, "_lastCSSHeight", 0);
     // 背景颜色
     __publicField(this, "_clearColor", { r: 0.15, g: 0.15, b: 0.15, a: 1 });
+    // GPU 平台信息
+    __publicField(this, "_isAppleGPU", false);
+    __publicField(this, "_gpuVendor", "");
+    __publicField(this, "_gpuArchitecture", "");
     this.canvas = canvas;
   }
   /**
@@ -304,6 +308,15 @@ class Renderer {
   get depthFormat() {
     return "depth24plus";
   }
+  get isAppleGPU() {
+    return this._isAppleGPU;
+  }
+  get gpuVendor() {
+    return this._gpuVendor;
+  }
+  get gpuArchitecture() {
+    return this._gpuArchitecture;
+  }
   /**
    * 获取渲染宽度（像素）
    */
@@ -329,6 +342,17 @@ class Renderer {
     if (!adapter) {
       throw new Error("无法获取 GPU 适配器");
     }
+    try {
+      const adapterAny = adapter;
+      const adapterInfo = adapterAny.requestAdapterInfo ? await adapterAny.requestAdapterInfo() : adapterAny.info;
+      if (adapterInfo) {
+        this._gpuVendor = (adapterInfo.vendor ?? "").toLowerCase();
+        this._gpuArchitecture = (adapterInfo.architecture ?? "").toLowerCase();
+      }
+      this._isAppleGPU = this._gpuVendor.includes("apple") || typeof navigator !== "undefined" && /mac/i.test(navigator.platform ?? "");
+    } catch {
+      this._isAppleGPU = typeof navigator !== "undefined" && /mac/i.test(navigator.platform ?? "");
+    }
     const adapterLimits = adapter.limits;
     this._device = await adapter.requestDevice({
       requiredLimits: {
@@ -535,7 +559,7 @@ class Camera {
     this.viewMatrix[15] = 1;
   }
   /**
-   * 计算投影矩阵 (透视投影)
+   * 计算投影矩阵 (透视投影, OpenGL [-1,1] 深度)
    */
   updateProjectionMatrix() {
     const f = 1 / Math.tan(this.fov / 2);
@@ -584,7 +608,7 @@ class Camera {
     }
   }
 }
-class OrbitControls {
+const _OrbitControls = class _OrbitControls {
   constructor(camera, canvas) {
     __publicField(this, "camera");
     __publicField(this, "canvas");
@@ -618,6 +642,9 @@ class OrbitControls {
     __publicField(this, "velocityPanX", 0);
     __publicField(this, "velocityPanY", 0);
     __publicField(this, "velocityPanZ", 0);
+    // 键盘移动
+    __publicField(this, "moveSpeed", 0.015);
+    __publicField(this, "pressedKeys", /* @__PURE__ */ new Set());
     // 触摸手势状态
     __publicField(this, "touchMode", "none");
     __publicField(this, "lastTouchDistance", 0);
@@ -629,6 +656,9 @@ class OrbitControls {
     __publicField(this, "boundOnMouseMove");
     __publicField(this, "boundOnMouseUp");
     __publicField(this, "boundOnWheel");
+    __publicField(this, "boundOnDblClick");
+    __publicField(this, "boundOnKeyDown");
+    __publicField(this, "boundOnKeyUp");
     __publicField(this, "boundOnTouchStart");
     __publicField(this, "boundOnTouchMove");
     __publicField(this, "boundOnTouchEnd");
@@ -639,6 +669,9 @@ class OrbitControls {
     this.boundOnMouseMove = this.onMouseMove.bind(this);
     this.boundOnMouseUp = this.onMouseUp.bind(this);
     this.boundOnWheel = this.onWheel.bind(this);
+    this.boundOnDblClick = this.onDblClick.bind(this);
+    this.boundOnKeyDown = this.onKeyDown.bind(this);
+    this.boundOnKeyUp = this.onKeyUp.bind(this);
     this.boundOnTouchStart = this.onTouchStart.bind(this);
     this.boundOnTouchMove = this.onTouchMove.bind(this);
     this.boundOnTouchEnd = this.onTouchEnd.bind(this);
@@ -662,6 +695,9 @@ class OrbitControls {
     });
     this.canvas.addEventListener("touchend", this.boundOnTouchEnd);
     this.canvas.addEventListener("contextmenu", this.boundOnContextMenu);
+    this.canvas.addEventListener("dblclick", this.boundOnDblClick);
+    window.addEventListener("keydown", this.boundOnKeyDown);
+    window.addEventListener("keyup", this.boundOnKeyUp);
   }
   removeEventListeners() {
     this.canvas.removeEventListener("mousedown", this.boundOnMouseDown);
@@ -673,6 +709,9 @@ class OrbitControls {
     this.canvas.removeEventListener("touchmove", this.boundOnTouchMove);
     this.canvas.removeEventListener("touchend", this.boundOnTouchEnd);
     this.canvas.removeEventListener("contextmenu", this.boundOnContextMenu);
+    this.canvas.removeEventListener("dblclick", this.boundOnDblClick);
+    window.removeEventListener("keydown", this.boundOnKeyDown);
+    window.removeEventListener("keyup", this.boundOnKeyUp);
   }
   destroy() {
     this.removeEventListeners();
@@ -751,6 +790,100 @@ class OrbitControls {
       this.applySpherical();
     }
   }
+  onKeyDown(e) {
+    var _a2;
+    if (!this.enabled) return;
+    const tag = (_a2 = e.target) == null ? void 0 : _a2.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return;
+    const key = e.key.toLowerCase();
+    if (_OrbitControls.MOVE_KEYS.has(key)) {
+      this.pressedKeys.add(key);
+      e.preventDefault();
+    }
+  }
+  onKeyUp(e) {
+    this.pressedKeys.delete(e.key.toLowerCase());
+  }
+  applyKeyboardMovement() {
+    if (this.pressedKeys.size === 0) return;
+    const m = this.camera.viewMatrix;
+    const right = [m[0], m[4], m[8]];
+    const forward = [-m[2], -m[6], -m[10]];
+    const speed = this.moveSpeed * this.distance;
+    let dx = 0, dy = 0, dz = 0;
+    if (this.pressedKeys.has("w") || this.pressedKeys.has("arrowup")) {
+      dx += forward[0] * speed;
+      dy += forward[1] * speed;
+      dz += forward[2] * speed;
+    }
+    if (this.pressedKeys.has("s") || this.pressedKeys.has("arrowdown")) {
+      dx -= forward[0] * speed;
+      dy -= forward[1] * speed;
+      dz -= forward[2] * speed;
+    }
+    if (this.pressedKeys.has("a") || this.pressedKeys.has("arrowleft")) {
+      dx -= right[0] * speed;
+      dy -= right[1] * speed;
+      dz -= right[2] * speed;
+    }
+    if (this.pressedKeys.has("d") || this.pressedKeys.has("arrowright")) {
+      dx += right[0] * speed;
+      dy += right[1] * speed;
+      dz += right[2] * speed;
+    }
+    this.camera.target[0] += dx;
+    this.camera.target[1] += dy;
+    this.camera.target[2] += dz;
+  }
+  onDblClick(e) {
+    if (!this.enabled) return;
+    const rect = this.canvas.getBoundingClientRect();
+    const ndcX = (e.clientX - rect.left) / rect.width * 2 - 1;
+    const ndcY = -((e.clientY - rect.top) / rect.height * 2 - 1);
+    const m = this.camera.viewMatrix;
+    const right = [m[0], m[4], m[8]];
+    const up = [m[1], m[5], m[9]];
+    const forward = [-m[2], -m[6], -m[10]];
+    const halfFovTan = Math.tan(this.camera.fov / 2);
+    const aspect = this.camera.aspect;
+    const dirX = forward[0] + right[0] * ndcX * halfFovTan * aspect + up[0] * ndcY * halfFovTan;
+    const dirY = forward[1] + right[1] * ndcX * halfFovTan * aspect + up[1] * ndcY * halfFovTan;
+    const dirZ = forward[2] + right[2] * ndcX * halfFovTan * aspect + up[2] * ndcY * halfFovTan;
+    const len = Math.sqrt(dirX * dirX + dirY * dirY + dirZ * dirZ);
+    const newTarget = [
+      this.camera.position[0] + dirX / len * this.distance,
+      this.camera.position[1] + dirY / len * this.distance,
+      this.camera.position[2] + dirZ / len * this.distance
+    ];
+    this.animateToTarget(newTarget);
+  }
+  animateToTarget(target) {
+    this.clearVelocity();
+    const startTarget = [
+      this.camera.target[0],
+      this.camera.target[1],
+      this.camera.target[2]
+    ];
+    const startTheta = this.theta;
+    const startPhi = this.phi;
+    const duration = 300;
+    const startTime = performance.now();
+    const animate = (currentTime) => {
+      const elapsed = currentTime - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const eased = 1 - Math.pow(1 - progress, 3);
+      this.camera.target[0] = startTarget[0] + (target[0] - startTarget[0]) * eased;
+      this.camera.target[1] = startTarget[1] + (target[1] - startTarget[1]) * eased;
+      this.camera.target[2] = startTarget[2] + (target[2] - startTarget[2]) * eased;
+      this.theta = startTheta;
+      this.phi = startPhi;
+      this.applySpherical();
+      if (progress < 1) {
+        requestAnimationFrame(animate);
+      }
+    };
+    requestAnimationFrame(animate);
+  }
   onTouchStart(e) {
     e.preventDefault();
     if (!this.enabled) return;
@@ -861,6 +994,7 @@ class OrbitControls {
    * 在渲染循环中调用此方法以获得平滑惯性效果
    */
   update() {
+    this.applyKeyboardMovement();
     if (this.enableDamping) {
       const EPS = 1e-6;
       const f = this.dampingFactor;
@@ -1000,7 +1134,19 @@ class OrbitControls {
     this.velocityPanY = 0;
     this.velocityPanZ = 0;
   }
-}
+};
+/** 移动键 */
+__publicField(_OrbitControls, "MOVE_KEYS", /* @__PURE__ */ new Set([
+  "w",
+  "a",
+  "s",
+  "d",
+  "arrowup",
+  "arrowdown",
+  "arrowleft",
+  "arrowright"
+]));
+let OrbitControls = _OrbitControls;
 class ViewportGizmo {
   constructor(_renderer, camera, canvas) {
     __publicField(this, "camera");
@@ -5547,6 +5693,8 @@ struct CullingParams {
   frustumDilation: f32,
   pixelThreshold: f32,
   maxVisibleCount: u32,
+  depthRangeLimit: f32,
+  _pad_cull: f32,
 }
 
 @group(0) @binding(0) var<storage, read> splats: array<Splat>;
@@ -5618,6 +5766,11 @@ fn projectAndCull(@builtin(global_invocation_id) gid: vec3<u32>) {
     if projectedExtent < params.pixelThreshold { return; }
   }
   
+  // 深度范围限制：只渲染距相机一定深度范围内的 splat
+  if params.depthRangeLimit > 0.0 {
+    if abs(viewPos.z) > params.depthRangeLimit { return; }
+  }
+
   // 深度编码 (viewPos.z 是负数)
   let depth = viewPos.z;
   let sortableDepth = encodeDepthKey(depth);
@@ -5640,8 +5793,7 @@ fn initIndirectBuffer() {
   atomicStore(&indirectBuffer[3], 0u);
 }
 
-// 排序后截断：只保留最近的 maxVisibleCount 个 splat
-// 因为 radix sort 是按深度从近到远排序，截断尾部等于丢弃被遮挡的远处 splat
+// 排序后截断：限制最大绘制数量
 @compute @workgroup_size(1)
 fn clampDrawCount() {
   let maxCount = params.maxVisibleCount;
@@ -5881,8 +6033,8 @@ 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>;
+var<workgroup> binCounter: array<u32, RADIX_SIZE>;
 
 @compute @workgroup_size(256, 1, 1)
 fn downsweep(
@@ -5901,50 +6053,40 @@ fn downsweep(
   let partitionEnd = min(partitionStart + BLOCK_SIZE, numKeys);
   let elemsInPartition = partitionEnd - partitionStart;
   
-  // Phase 1: 所有线程并行加载元素到共享内存
+  // Phase 1: 所有 256 个线程并行加载元素到共享内存（合并全局内存访问）
   for (var j = 0u; j < ELEMENTS_PER_THREAD; j++) {
     let keyIdx = partitionStart + tid * ELEMENTS_PER_THREAD + j;
     let localIdx = tid * ELEMENTS_PER_THREAD + j;
     
     if keyIdx < numKeys {
-      let key = downsweepKeysIn[keyIdx];
-      localKeys[localIdx] = key;
+      localKeys[localIdx] = downsweepKeysIn[keyIdx];
       localValues[localIdx] = downsweepValuesIn[keyIdx];
-      localBins[localIdx] = (key >> shift) & RADIX_MASK;
-    } else {
-      localBins[localIdx] = 0xFFFFFFFFu;
     }
   }
   
-  // Phase 2: 初始化 bin 基础写入位置（利用 256 线程并行）
+  // Phase 2: 初始化 bin 基础写入位置 + 计数器归零
   if tid < RADIX_SIZE {
     let passIdx = downsweepParams.passIndex;
     binBasePos[tid] = globalHistogramDownsweep[RADIX_SIZE * passIdx + tid] + 
                       partitionHistogramDownsweep[RADIX_SIZE * partitionId + tid];
+    binCounter[tid] = 0u;
   }
   
   workgroupBarrier();
   
-  // 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 b = localBins[localIdx];
-    if b == 0xFFFFFFFFu { continue; }
-    
-    // 计算 rank：扫描本分区中在当前元素之前、且属于同一 bin 的元素数
-    var rank = 0u;
-    for (var p = 0u; p < localIdx; p++) {
-      if localBins[p] == b { rank++; }
-    }
-    
-    let writePos = binBasePos[b] + rank;
-    if writePos < numKeys {
-      downsweepKeysOut[writePos] = localKeys[localIdx];
-      downsweepValuesOut[writePos] = localValues[localIdx];
+  // Phase 3: 单线程顺序计数散射 — O(n) 稳定
+  // 按元素顺序遍历，用 counter 数组跟踪每个 bin 的写入偏移
+  // 稳定性由遍历顺序保证，无需任何比较或原子操作
+  if tid == 0u {
+    for (var j = 0u; j < elemsInPartition; j++) {
+      let key = localKeys[j];
+      let b = (key >> shift) & RADIX_MASK;
+      let writePos = binBasePos[b] + binCounter[b];
+      binCounter[b] = binCounter[b] + 1u;
+      if writePos < numKeys {
+        downsweepKeysOut[writePos] = key;
+        downsweepValuesOut[writePos] = localValues[j];
+      }
     }
   }
 }
@@ -6008,7 +6150,7 @@ class GSSplatSorter {
       label: "radix-sort-shader"
     });
     this.cullingParamsBuffer = device.createBuffer({
-      size: 32,
+      size: 48,
       usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
       label: "culling-params"
     });
@@ -6237,7 +6379,7 @@ class GSSplatSorter {
    * 每帧调用
    */
   sort() {
-    const cullingParamsData = new ArrayBuffer(32);
+    const cullingParamsData = new ArrayBuffer(48);
     const view = new DataView(cullingParamsData);
     view.setUint32(0, this.splatCount, true);
     view.setFloat32(4, this.cullingOptions.nearPlane, true);
@@ -6247,6 +6389,7 @@ class GSSplatSorter {
     view.setFloat32(20, this.cullingOptions.frustumDilation ?? 0.2, true);
     view.setFloat32(24, this.cullingOptions.pixelThreshold, true);
     view.setUint32(28, this.cullingOptions.maxVisibleCount ?? 0, true);
+    view.setFloat32(32, this.cullingOptions.depthRangeLimit ?? 0, true);
     this.device.queue.writeBuffer(this.cullingParamsBuffer, 0, cullingParamsData);
     const encoder = this.device.createCommandEncoder({ label: "splat-sort-encoder" });
     encoder.clearBuffer(this.globalHistogramBuffer);
@@ -6377,7 +6520,8 @@ struct Uniforms {
   cameraPos: vec3<f32>,
   _pad: f32,
   screenSize: vec2<f32>,
-  _pad2: vec2<f32>,
+  shMode: u32,
+  _pad2: f32,
 }
 
 struct Splat {
@@ -6392,10 +6536,13 @@ struct Splat {
   _pad2: array<f32, 3>,
 }
 
-// 完整 L3 球谐函数求值 (匹配原始 3DGS Python 实现)
-// SH 系数以 interleaved 格式存储: [R0,G0,B0, R1,G1,B1, ...]
-// dir: 从相机指向 splat 的归一化方向向量（模型空间）
+// SH_LEVEL 在 createPipeline 时注入为编译期常量，GPU 编译器会折叠死代码
+// L3 模式下生成的 GPU 指令与无分支版本完全一致
+const SH_LEVEL: u32 = 3u; // @SH_LEVEL_INJECT@
+
 fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
+  if SH_LEVEL == 0u { return vec3<f32>(0.0); }
+
   let x = dir.x;
   let y = dir.y;
   let z = dir.z;
@@ -6407,6 +6554,8 @@ fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
   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]);
 
+  if SH_LEVEL == 1u { return result; }
+
   // 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;
@@ -6417,6 +6566,8 @@ fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
   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]);
 
+  if SH_LEVEL == 2u { return result; }
+
   // 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]);
@@ -6726,7 +6877,8 @@ struct Uniforms {
   cameraPos: vec3<f32>,
   _pad: f32,
   screenSize: vec2<f32>,
-  _pad2: vec2<f32>,
+  shMode: u32,
+  _pad2: f32,
 }
 
 struct Splat {
@@ -6974,6 +7126,8 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     __publicField(this, "sorter", null);
     __publicField(this, "shMode", SHMode.L3);
     __publicField(this, "boundingBox", null);
+    // 预分配 uniform 上传缓冲区，避免每帧 GC（56 floats = 224 bytes）
+    __publicField(this, "uniformData", new Float32Array(56));
     __publicField(this, "cpuPositions", null);
     // Transform
     __publicField(this, "position", [0, 0, 0]);
@@ -6984,6 +7138,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     // 剔除选项
     __publicField(this, "pixelCullThreshold", 1);
     __publicField(this, "maxVisibleSplats", 0);
+    __publicField(this, "depthRangeLimit", 0);
     // 排序优化：相机变化检测 + 频率控制
     __publicField(this, "lastSortViewMatrix", new Float32Array(16));
     __publicField(this, "lastSortProjMatrix", new Float32Array(16));
@@ -6992,6 +7147,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     __publicField(this, "lastSortHeight", 0);
     __publicField(this, "lastSortPixelThreshold", -1);
     __publicField(this, "lastSortMaxVisible", -1);
+    __publicField(this, "lastSortDepthRange", -1);
     __publicField(this, "sortStateInitialized", false);
     __publicField(this, "sortFrequency", 1);
     __publicField(this, "frameCounter", 0);
@@ -7001,6 +7157,8 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     __publicField(this, "editorBindGroupLayout", null);
     __publicField(this, "editorBindGroup", null);
     __publicField(this, "editorEnabled", false);
+    // Apple GPU 优化：禁用深度写入让 TBDR HSR 生效
+    __publicField(this, "depthWriteEnabled", true);
     // 深度法线Pass依赖资源
     __publicField(this, "depthNormalPipeline", null);
     __publicField(this, "depthRT", null);
@@ -7019,8 +7177,12 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   }
   createPipeline() {
     const device = this.renderer.device;
+    const shaderCode = gsOptimizedShader.replace(
+      "const SH_LEVEL: u32 = 3u; // @SH_LEVEL_INJECT@",
+      `const SH_LEVEL: u32 = ${this.shMode}u;`
+    );
     const shaderModule = device.createShaderModule({
-      code: gsOptimizedShader
+      code: shaderCode
     });
     this.bindGroupLayout = device.createBindGroupLayout({
       entries: [
@@ -7077,11 +7239,16 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       },
       depthStencil: {
         format: this.renderer.depthFormat,
-        depthWriteEnabled: true,
+        depthWriteEnabled: this.depthWriteEnabled,
         depthCompare: "always"
       }
     });
   }
+  setDepthWriteEnabled(enabled) {
+    if (this.depthWriteEnabled === enabled) return;
+    this.depthWriteEnabled = enabled;
+    this.createPipeline();
+  }
   createUniformBuffer() {
     this.uniformBuffer = this.renderer.device.createBuffer({
       size: 224,
@@ -7093,7 +7260,9 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   // A采用"zero add one-minus-src-alpha"的混合模式计算Transmittance
   createDepthNormalPipeline() {
     const device = this.renderer.device;
-    const shaderModule = device.createShaderModule({ code: gsDepthNormalShader });
+    const shaderModule = device.createShaderModule({
+      code: gsDepthNormalShader
+    });
     const pipelineLayout = device.createPipelineLayout({
       bindGroupLayouts: [this.bindGroupLayout]
     });
@@ -7111,15 +7280,31 @@ const _GSSplatRenderer = class _GSSplatRenderer {
           {
             format: "rgba16float",
             blend: {
-              color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
-              alpha: { srcFactor: "zero", dstFactor: "one-minus-src-alpha", operation: "add" }
+              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" }
+              color: {
+                srcFactor: "one",
+                dstFactor: "one-minus-src-alpha",
+                operation: "add"
+              },
+              alpha: {
+                srcFactor: "zero",
+                dstFactor: "one-minus-src-alpha",
+                operation: "add"
+              }
             }
           }
         ]
@@ -7222,7 +7407,9 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     return this.modelMatrix;
   }
   setSHMode(mode) {
+    if (this.shMode === mode) return;
     this.shMode = mode;
+    this.createPipeline();
   }
   getSHMode() {
     return this.shMode;
@@ -7241,6 +7428,18 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   getMaxVisibleSplats() {
     return this.maxVisibleSplats;
   }
+  /**
+   * 设置深度范围限制（view-space 距离）
+   * 只渲染距相机此距离范围内的 splat，超出部分被剔除
+   * 近似 transmittance cutoff：近距离时大量 splat 堆叠在后方但被前方遮挡
+   * 0 = 不限制
+   */
+  setDepthRangeLimit(limit) {
+    this.depthRangeLimit = limit;
+  }
+  getDepthRangeLimit() {
+    return this.depthRangeLimit;
+  }
   /**
    * 设置排序频率
    * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推
@@ -7258,7 +7457,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     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) {
+    if (!this.sortStateInitialized || w !== this.lastSortWidth || h !== this.lastSortHeight || this.pixelCullThreshold !== this.lastSortPixelThreshold || this.maxVisibleSplats !== this.lastSortMaxVisible || this.depthRangeLimit !== this.lastSortDepthRange) {
       this.saveSortState(view, proj, model, w, h);
       return true;
     }
@@ -7278,6 +7477,7 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     this.lastSortHeight = h;
     this.lastSortPixelThreshold = this.pixelCullThreshold;
     this.lastSortMaxVisible = this.maxVisibleSplats;
+    this.lastSortDepthRange = this.depthRangeLimit;
     this.sortStateInitialized = true;
   }
   setData(splats) {
@@ -7409,36 +7609,26 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       ]
     });
     if (this.editorEnabled) this.rebuildEditorBindGroup();
+    this.sortStateInitialized = false;
   }
   render(pass) {
     if (this.splatCount === 0 || !this.bindGroup || !this.sorter) {
       return;
     }
-    this.renderer.device.queue.writeBuffer(
-      this.uniformBuffer,
-      0,
-      new Float32Array(this.camera.viewMatrix)
-    );
-    this.renderer.device.queue.writeBuffer(
-      this.uniformBuffer,
-      64,
-      new Float32Array(this.camera.projectionMatrix)
-    );
-    this.renderer.device.queue.writeBuffer(
-      this.uniformBuffer,
-      128,
-      new Float32Array(this.modelMatrix)
-    );
-    this.renderer.device.queue.writeBuffer(
-      this.uniformBuffer,
-      192,
-      new Float32Array(this.camera.position)
-    );
-    this.renderer.device.queue.writeBuffer(
-      this.uniformBuffer,
-      208,
-      new Float32Array([this.renderer.width, this.renderer.height, 0, 0])
-    );
+    const ud = this.uniformData;
+    ud.set(this.camera.viewMatrix, 0);
+    ud.set(this.camera.projectionMatrix, 16);
+    ud.set(this.modelMatrix, 32);
+    const pos = this.camera.position;
+    ud[48] = pos[0];
+    ud[49] = pos[1];
+    ud[50] = pos[2];
+    ud[51] = 0;
+    ud[52] = this.renderer.width;
+    ud[53] = this.renderer.height;
+    ud[54] = 0;
+    ud[55] = 0;
+    this.renderer.device.queue.writeBuffer(this.uniformBuffer, 0, ud);
     const changed = this.needsSort();
     this.frameCounter++;
     const shouldSort = changed || this.sortFrequency > 1 && this.frameCounter % this.sortFrequency === 0;
@@ -7448,7 +7638,8 @@ const _GSSplatRenderer = class _GSSplatRenderer {
         nearPlane: this.camera.near,
         farPlane: this.camera.far,
         pixelThreshold: this.pixelCullThreshold,
-        maxVisibleCount: this.maxVisibleSplats
+        maxVisibleCount: this.maxVisibleSplats,
+        depthRangeLimit: this.depthRangeLimit
       });
       this.sorter.sort();
     }
@@ -7542,7 +7733,9 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     const h = this.renderer.height;
     this.ensureDepthNormalTextures(w, h);
     const device = this.renderer.device;
-    const encoder = device.createCommandEncoder({ label: "depth-normal-encoder" });
+    const encoder = device.createCommandEncoder({
+      label: "depth-normal-encoder"
+    });
     const pass = encoder.beginRenderPass({
       colorAttachments: [
         {
@@ -7600,7 +7793,22 @@ const _GSSplatRenderer = class _GSSplatRenderer {
         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 };
+        this.dnResult = {
+          raw,
+          vm,
+          proj,
+          cam,
+          w,
+          h,
+          px: ipx,
+          py: ipy,
+          copyX: x0,
+          copyY: y0,
+          copyW,
+          copyH,
+          cx,
+          cy
+        };
       }).catch(() => {
         buf.destroy();
       });
@@ -7760,14 +7968,33 @@ const _GSSplatRenderer = class _GSSplatRenderer {
   }
   createEditorPipeline() {
     const device = this.renderer.device;
-    const editorShaderCode = this.buildEditorShader();
+    const editorShaderCode = this.buildEditorShader().replace(
+      "const SH_LEVEL: u32 = 3u; // @SH_LEVEL_INJECT@",
+      `const SH_LEVEL: u32 = ${this.shMode}u;`
+    );
     const shaderModule = device.createShaderModule({ code: editorShaderCode });
     this.editorBindGroupLayout = 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: 3, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, 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" }
+        },
+        {
+          binding: 3,
+          visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+          buffer: { type: "read-only-storage" }
+        }
       ]
     });
     const pipelineLayout = device.createPipelineLayout({
@@ -7779,13 +8006,23 @@ const _GSSplatRenderer = class _GSSplatRenderer {
       fragment: {
         module: shaderModule,
         entryPoint: "fs_editor",
-        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: {
@@ -7796,7 +8033,8 @@ const _GSSplatRenderer = class _GSSplatRenderer {
     });
   }
   rebuildEditorBindGroup() {
-    if (!this.editorBindGroupLayout || !this.splatBuffer || !this.sorter || !this.editorStateBuffer) return;
+    if (!this.editorBindGroupLayout || !this.splatBuffer || !this.sorter || !this.editorStateBuffer)
+      return;
     this.editorBindGroup = this.renderer.device.createBindGroup({
       layout: this.editorBindGroupLayout,
       entries: [
@@ -7843,7 +8081,8 @@ struct Uniforms {
   cameraPos: vec3<f32>,
   _pad: f32,
   screenSize: vec2<f32>,
-  _pad2: vec2<f32>,
+  shMode: u32,
+  _pad2: f32,
 }
 
 struct Splat {
@@ -7858,12 +8097,19 @@ struct Splat {
   _pad2: array<f32, 3>,
 }
 
+const SH_LEVEL: u32 = 3u; // @SH_LEVEL_INJECT@
+
 fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
+  if SH_LEVEL == 0u { return vec3<f32>(0.0); }
+
   let x = dir.x; let y = dir.y; let z = dir.z;
   var result = vec3<f32>(0.0);
   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]);
+
+  if SH_LEVEL == 1u { return result; }
+
   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]);
@@ -7871,6 +8117,9 @@ fn evalSH(splat: Splat, dir: vec3<f32>) -> vec3<f32> {
   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]);
+
+  if SH_LEVEL == 2u { return result; }
+
   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]);
@@ -15655,6 +15904,216 @@ class EyedropperSelection {
     this.pointerId = null;
   }
 }
+class SphereSelection {
+  constructor(parent, onSelect) {
+    __publicField(this, "parent");
+    __publicField(this, "svg");
+    __publicField(this, "circle");
+    __publicField(this, "onSelect");
+    __publicField(this, "center", { x: 0, y: 0 });
+    __publicField(this, "radiusPx", 0);
+    __publicField(this, "dragId");
+    this.parent = parent;
+    this.onSelect = onSelect;
+    this.svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    this.svg.classList.add("tool-svg");
+    this.svg.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;display:none;z-index:10;";
+    parent.appendChild(this.svg);
+    this.circle = document.createElementNS(
+      this.svg.namespaceURI,
+      "circle"
+    );
+    this.circle.setAttribute("fill", "rgba(0,150,255,0.12)");
+    this.circle.setAttribute("stroke", "#09f");
+    this.circle.setAttribute("stroke-width", "1.5");
+    this.circle.setAttribute("stroke-dasharray", "6 3");
+    this.circle.style.display = "none";
+    this.svg.appendChild(this.circle);
+    this.pointerdown = this.pointerdown.bind(this);
+    this.pointermove = this.pointermove.bind(this);
+    this.pointerup = this.pointerup.bind(this);
+  }
+  activate() {
+    this.svg.style.display = "block";
+    this.parent.style.cursor = "crosshair";
+    this.parent.addEventListener("pointerdown", this.pointerdown);
+    this.parent.addEventListener("pointermove", this.pointermove);
+    this.parent.addEventListener("pointerup", this.pointerup);
+  }
+  deactivate() {
+    if (this.dragId !== void 0) this.dragEnd();
+    this.svg.style.display = "none";
+    this.parent.style.cursor = "";
+    this.parent.removeEventListener("pointerdown", this.pointerdown);
+    this.parent.removeEventListener("pointermove", this.pointermove);
+    this.parent.removeEventListener("pointerup", this.pointerup);
+  }
+  updateCircle() {
+    this.circle.setAttribute("cx", this.center.x.toString());
+    this.circle.setAttribute("cy", this.center.y.toString());
+    this.circle.setAttribute("r", Math.max(1, this.radiusPx).toString());
+  }
+  pointerdown(e) {
+    if (this.dragId !== void 0) return;
+    if (e.pointerType === "mouse" ? e.button !== 0 : !e.isPrimary) return;
+    e.preventDefault();
+    e.stopPropagation();
+    this.dragId = e.pointerId;
+    this.parent.setPointerCapture(this.dragId);
+    this.center.x = e.offsetX;
+    this.center.y = e.offsetY;
+    this.radiusPx = 0;
+    this.updateCircle();
+    this.circle.style.display = "block";
+  }
+  pointermove(e) {
+    if (e.pointerId !== this.dragId) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const dx = e.offsetX - this.center.x;
+    const dy = e.offsetY - this.center.y;
+    this.radiusPx = Math.sqrt(dx * dx + dy * dy);
+    this.updateCircle();
+  }
+  dragEnd() {
+    if (this.dragId !== void 0) {
+      this.parent.releasePointerCapture(this.dragId);
+      this.dragId = void 0;
+    }
+    this.circle.style.display = "none";
+  }
+  pointerup(e) {
+    if (e.pointerId !== this.dragId) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const selectOp = e.shiftKey ? "add" : e.ctrlKey ? "remove" : "set";
+    if (this.radiusPx < 3) this.radiusPx = 20;
+    this.onSelect(selectOp, { x: this.center.x, y: this.center.y }, this.radiusPx);
+    this.dragEnd();
+  }
+}
+class BoxSelection {
+  constructor(parent, onSelect) {
+    __publicField(this, "parent");
+    __publicField(this, "svg");
+    __publicField(this, "rect");
+    __publicField(this, "crossV");
+    __publicField(this, "crossH");
+    __publicField(this, "onSelect");
+    __publicField(this, "center", { x: 0, y: 0 });
+    __publicField(this, "halfW", 0);
+    __publicField(this, "halfH", 0);
+    __publicField(this, "dragId");
+    this.parent = parent;
+    this.onSelect = onSelect;
+    this.svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+    this.svg.classList.add("tool-svg");
+    this.svg.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;display:none;z-index:10;";
+    parent.appendChild(this.svg);
+    this.rect = document.createElementNS(
+      this.svg.namespaceURI,
+      "rect"
+    );
+    this.rect.setAttribute("fill", "rgba(0,200,100,0.12)");
+    this.rect.setAttribute("stroke", "#0c6");
+    this.rect.setAttribute("stroke-width", "1.5");
+    this.rect.setAttribute("stroke-dasharray", "6 3");
+    this.rect.style.display = "none";
+    this.svg.appendChild(this.rect);
+    const mkLine = () => {
+      const l = document.createElementNS(this.svg.namespaceURI, "line");
+      l.setAttribute("stroke", "#0c6");
+      l.setAttribute("stroke-width", "1");
+      l.setAttribute("stroke-dasharray", "3 3");
+      l.style.display = "none";
+      this.svg.appendChild(l);
+      return l;
+    };
+    this.crossV = mkLine();
+    this.crossH = mkLine();
+    this.pointerdown = this.pointerdown.bind(this);
+    this.pointermove = this.pointermove.bind(this);
+    this.pointerup = this.pointerup.bind(this);
+  }
+  activate() {
+    this.svg.style.display = "block";
+    this.parent.style.cursor = "crosshair";
+    this.parent.addEventListener("pointerdown", this.pointerdown);
+    this.parent.addEventListener("pointermove", this.pointermove);
+    this.parent.addEventListener("pointerup", this.pointerup);
+  }
+  deactivate() {
+    if (this.dragId !== void 0) this.dragEnd();
+    this.svg.style.display = "none";
+    this.parent.style.cursor = "";
+    this.parent.removeEventListener("pointerdown", this.pointerdown);
+    this.parent.removeEventListener("pointermove", this.pointermove);
+    this.parent.removeEventListener("pointerup", this.pointerup);
+  }
+  updateVisuals() {
+    const x = this.center.x - this.halfW;
+    const y = this.center.y - this.halfH;
+    const w = this.halfW * 2;
+    const h = this.halfH * 2;
+    this.rect.setAttribute("x", x.toString());
+    this.rect.setAttribute("y", y.toString());
+    this.rect.setAttribute("width", Math.max(1, w).toString());
+    this.rect.setAttribute("height", Math.max(1, h).toString());
+    this.crossV.setAttribute("x1", this.center.x.toString());
+    this.crossV.setAttribute("y1", y.toString());
+    this.crossV.setAttribute("x2", this.center.x.toString());
+    this.crossV.setAttribute("y2", (y + h).toString());
+    this.crossH.setAttribute("x1", x.toString());
+    this.crossH.setAttribute("y1", this.center.y.toString());
+    this.crossH.setAttribute("x2", (x + w).toString());
+    this.crossH.setAttribute("y2", this.center.y.toString());
+  }
+  pointerdown(e) {
+    if (this.dragId !== void 0) return;
+    if (e.pointerType === "mouse" ? e.button !== 0 : !e.isPrimary) return;
+    e.preventDefault();
+    e.stopPropagation();
+    this.dragId = e.pointerId;
+    this.parent.setPointerCapture(this.dragId);
+    this.center.x = e.offsetX;
+    this.center.y = e.offsetY;
+    this.halfW = 0;
+    this.halfH = 0;
+    this.updateVisuals();
+    this.rect.style.display = "block";
+    this.crossV.style.display = "block";
+    this.crossH.style.display = "block";
+  }
+  pointermove(e) {
+    if (e.pointerId !== this.dragId) return;
+    e.preventDefault();
+    e.stopPropagation();
+    this.halfW = Math.abs(e.offsetX - this.center.x);
+    this.halfH = Math.abs(e.offsetY - this.center.y);
+    this.updateVisuals();
+  }
+  dragEnd() {
+    if (this.dragId !== void 0) {
+      this.parent.releasePointerCapture(this.dragId);
+      this.dragId = void 0;
+    }
+    this.rect.style.display = "none";
+    this.crossV.style.display = "none";
+    this.crossH.style.display = "none";
+  }
+  pointerup(e) {
+    if (e.pointerId !== this.dragId) return;
+    e.preventDefault();
+    e.stopPropagation();
+    const selectOp = e.shiftKey ? "add" : e.ctrlKey ? "remove" : "set";
+    if (this.halfW < 3 && this.halfH < 3) {
+      this.halfW = 20;
+      this.halfH = 20;
+    }
+    this.onSelect(selectOp, { x: this.center.x, y: this.center.y }, this.halfW, this.halfH);
+    this.dragEnd();
+  }
+}
 function exportEditedPLY(positions, scales, rotations, colors, opacities, shCoeffs, state) {
   const totalCount = state.count;
   let keepCount = 0;
@@ -15865,6 +16324,14 @@ class SplatEditor {
       this.toolOverlay,
       (op, pt, threshold) => this.selectByColor(op, pt, threshold)
     ));
+    this.toolManager.register("sphere", new SphereSelection(
+      this.toolOverlay,
+      (op, centerPx, radiusPx) => this.selectBySphere(op, centerPx, radiusPx)
+    ));
+    this.toolManager.register("box", new BoxSelection(
+      this.toolOverlay,
+      (op, centerPx, halfW, halfH) => this.selectByBox(op, centerPx, halfW, halfH)
+    ));
     this.gsRenderer.setEditorState(this.splatState.data);
     this._keyHandler = this._onKeyDown.bind(this);
     window.addEventListener("keydown", this._keyHandler);
@@ -16067,6 +16534,106 @@ class SplatEditor {
     });
     this.editHistory.add(editOp);
   }
+  /**
+   * 球选择：以点击处最近 splat 为中心，拖拽半径定义世界空间球体
+   */
+  selectBySphere(op, centerPx, radiusPx) {
+    const pick = this.pickWorldPosition(centerPx.x, centerPx.y);
+    if (!pick) return;
+    const worldRadius = radiusPx * pick.pixelToWorld;
+    const cpuPos = this.gsRenderer.getCPUPositions();
+    if (!cpuPos) return;
+    const modelMat = this.gsRenderer.getModelMatrix();
+    const cx = pick.worldX, cy = pick.worldY, cz = pick.worldZ;
+    const r2 = worldRadius * worldRadius;
+    const editOp = new SelectOp(this.splatState, op, (i) => {
+      if (this.splatState.data[i] & (State.hidden | State.deleted)) return false;
+      const i3 = i * 3;
+      const lx = cpuPos[i3], ly = cpuPos[i3 + 1], lz = cpuPos[i3 + 2];
+      const wx = modelMat[0] * lx + modelMat[4] * ly + modelMat[8] * lz + modelMat[12];
+      const wy = modelMat[1] * lx + modelMat[5] * ly + modelMat[9] * lz + modelMat[13];
+      const wz = modelMat[2] * lx + modelMat[6] * ly + modelMat[10] * lz + modelMat[14];
+      const dx = wx - cx, dy = wy - cy, dz = wz - cz;
+      return dx * dx + dy * dy + dz * dz < r2;
+    });
+    this.editHistory.add(editOp);
+  }
+  /**
+   * 盒选择：以点击处最近 splat 为中心，拖拽定义世界空间 AABB
+   * X/Y 半宽由屏幕拖拽距离转换，Z 半深度取 max(halfW, halfH)
+   */
+  selectByBox(op, centerPx, halfWPx, halfHPx) {
+    const pick = this.pickWorldPosition(centerPx.x, centerPx.y);
+    if (!pick) return;
+    const s = pick.pixelToWorld;
+    const hx = halfWPx * s;
+    const hy = halfHPx * s;
+    const hz = Math.max(hx, hy);
+    const cpuPos = this.gsRenderer.getCPUPositions();
+    if (!cpuPos) return;
+    const modelMat = this.gsRenderer.getModelMatrix();
+    const cx = pick.worldX, cy = pick.worldY, cz = pick.worldZ;
+    const editOp = new SelectOp(this.splatState, op, (i) => {
+      if (this.splatState.data[i] & (State.hidden | State.deleted)) return false;
+      const i3 = i * 3;
+      const lx = cpuPos[i3], ly = cpuPos[i3 + 1], lz = cpuPos[i3 + 2];
+      const wx = modelMat[0] * lx + modelMat[4] * ly + modelMat[8] * lz + modelMat[12];
+      const wy = modelMat[1] * lx + modelMat[5] * ly + modelMat[9] * lz + modelMat[13];
+      const wz = modelMat[2] * lx + modelMat[6] * ly + modelMat[10] * lz + modelMat[14];
+      return Math.abs(wx - cx) < hx && Math.abs(wy - cy) < hy && Math.abs(wz - cz) < hz;
+    });
+    this.editHistory.add(editOp);
+  }
+  /**
+   * 根据屏幕像素坐标，找到最近的可见 splat 并返回其世界坐标及深度换算系数
+   */
+  pickWorldPosition(px, py) {
+    this.ensureProjection();
+    const proj = this.projectedPositions;
+    if (!proj) return null;
+    const cpuPos = this.gsRenderer.getCPUPositions();
+    if (!cpuPos) return null;
+    const w = this.container.clientWidth;
+    const h = this.container.clientHeight;
+    const nx = px / w;
+    const ny = py / h;
+    let bestIdx = -1;
+    let bestDist = Infinity;
+    for (let i = 0; i < this.splatState.count; i++) {
+      const b = i * 3;
+      const sz = proj[b + 2];
+      if (sz <= 0 || sz >= 1) continue;
+      if (this.splatState.data[i] & (State.hidden | State.deleted)) continue;
+      const dx = proj[b] - nx;
+      const dy = proj[b + 1] - ny;
+      const d = dx * dx + dy * dy;
+      if (d < bestDist) {
+        bestDist = d;
+        bestIdx = i;
+      }
+    }
+    if (bestIdx < 0) return null;
+    const modelMat = this.gsRenderer.getModelMatrix();
+    const viewMat = this.camera.viewMatrix;
+    const projMat = this.camera.projectionMatrix;
+    const i3 = bestIdx * 3;
+    const lx = cpuPos[i3], ly = cpuPos[i3 + 1], lz = cpuPos[i3 + 2];
+    const wx = modelMat[0] * lx + modelMat[4] * ly + modelMat[8] * lz + modelMat[12];
+    const wy = modelMat[1] * lx + modelMat[5] * ly + modelMat[9] * lz + modelMat[13];
+    const wz = modelMat[2] * lx + modelMat[6] * ly + modelMat[10] * lz + modelMat[14];
+    const vz = viewMat[2] * wx + viewMat[6] * wy + viewMat[10] * wz + viewMat[14];
+    const depth = Math.abs(vz);
+    const focalX = Math.abs(projMat[0]) * 0.5 * w;
+    const focalY = Math.abs(projMat[5]) * 0.5 * h;
+    const focal = (focalX + focalY) * 0.5;
+    return {
+      worldX: wx,
+      worldY: wy,
+      worldZ: wz,
+      viewDepth: depth,
+      pixelToWorld: depth / focal
+    };
+  }
   // ============================================
   // 投影
   // ============================================
@@ -16176,6 +16743,21 @@ class SplatEditor {
     }
   }
 }
+const DEFAULT_ADAPTIVE_CONFIG = {
+  farThreshold: 2.5,
+  nearThreshold: 0.3,
+  minRenderScale: 1,
+  maxPixelThreshold: 1.2,
+  minPixelThreshold: 0.7,
+  nearVisibleRatio: 1,
+  farUnlimited: true,
+  enableDepthRangeLimit: true,
+  nearDepthRangeRatio: 2.5
+};
+function smoothstep(edge0, edge1, x) {
+  const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
+  return t * t * (3 - 2 * t);
+}
 class App {
   constructor(canvas) {
     __publicField(this, "canvas");
@@ -16196,6 +16778,13 @@ class App {
     __publicField(this, "useMobileRenderer", false);
     // 最近加载的 CompactSplatData（用于编辑器导出）
     __publicField(this, "lastCompactData", null);
+    // 自适应性能控制
+    __publicField(this, "adaptivePerformanceEnabled", false);
+    __publicField(this, "adaptiveConfig", {
+      ...DEFAULT_ADAPTIVE_CONFIG
+    });
+    __publicField(this, "lastAppliedRenderScale", 1);
+    __publicField(this, "baseRenderScale", 1);
     // 绑定的事件处理函数
     __publicField(this, "boundOnResize");
     this.canvas = canvas;
@@ -16229,6 +16818,36 @@ class App {
     );
     this.sceneAids = new SceneAidsRenderer(this.renderer, this.camera);
     window.addEventListener("resize", this.boundOnResize);
+    if (this.renderer.isAppleGPU) {
+      this.applyAppleGPUDefaults();
+    }
+  }
+  /**
+   * Apple GPU (M1/M2/M3 等) 自动优化配置
+   * TBDR 架构特点：片段着色器开销高、带宽敏感、compute pass 较慢
+   * 策略：降低 SH 等级、更积极的自适应参数、禁用无效深度写入
+   */
+  applyAppleGPUDefaults() {
+    this.adaptiveConfig = {
+      ...this.adaptiveConfig,
+      maxPixelThreshold: 2,
+      enableDepthRangeLimit: true,
+      nearDepthRangeRatio: 2
+    };
+    console.log(
+      `[3DGS] Apple GPU detected (${this.renderer.gpuVendor}/${this.renderer.gpuArchitecture}), applying TBDR optimizations: SH→L1, depthWrite off, aggressive culling`
+    );
+  }
+  /**
+   * 创建桌面端 GSSplatRenderer 并自动应用平台优化
+   */
+  createDesktopGSRenderer() {
+    const renderer = new GSSplatRenderer(this.renderer, this.camera);
+    if (this.renderer.isAppleGPU) {
+      renderer.setSHMode(SHMode.L1);
+      renderer.setDepthWriteEnabled(false);
+    }
+    return renderer;
   }
   // ============================================
   // 模型加载
@@ -16275,11 +16894,14 @@ class App {
       const isMobile = isMobileDevice();
       let buffer;
       if (typeof urlOrBuffer === "string") {
-        buffer = await this.fetchWithProgress(urlOrBuffer, (downloadProgress) => {
-          if (onProgress) {
-            onProgress(downloadProgress * 0.5, "download");
+        buffer = await this.fetchWithProgress(
+          urlOrBuffer,
+          (downloadProgress) => {
+            if (onProgress) {
+              onProgress(downloadProgress * 0.5, "download");
+            }
           }
-        });
+        );
       } else {
         buffer = urlOrBuffer;
         if (onProgress && isLocalFile) {
@@ -16310,7 +16932,7 @@ class App {
         this.hotspotManager.setGSRenderer(gsRenderer);
         return compactData.count;
       } else {
-        gsRenderer = new GSSplatRenderer(this.renderer, this.camera);
+        gsRenderer = this.createDesktopGSRenderer();
         this.useMobileRenderer = false;
         const compactData = await this.parsePLYBuffer(buffer, {
           maxSplats: Infinity,
@@ -16339,11 +16961,14 @@ class App {
       const isMobile = isMobileDevice();
       let buffer;
       if (typeof urlOrBuffer === "string") {
-        buffer = await this.fetchWithProgress(urlOrBuffer, (downloadProgress) => {
-          if (onProgress) {
-            onProgress(downloadProgress * 0.5, "download");
+        buffer = await this.fetchWithProgress(
+          urlOrBuffer,
+          (downloadProgress) => {
+            if (onProgress) {
+              onProgress(downloadProgress * 0.5, "download");
+            }
           }
-        });
+        );
       } else {
         buffer = urlOrBuffer;
         if (onProgress && isLocalFile) {
@@ -16366,14 +16991,17 @@ class App {
       if (onProgress) onProgress(90, "upload");
       let gsRenderer;
       if (isMobile) {
-        const mobileRenderer = new GSSplatRendererMobile(this.renderer, this.camera);
+        const mobileRenderer = new GSSplatRendererMobile(
+          this.renderer,
+          this.camera
+        );
         this.useMobileRenderer = true;
         const compactData = App.splatCpuToCompactData(splats);
         mobileRenderer.setCompactData(compactData);
         this.lastCompactData = compactData;
         gsRenderer = mobileRenderer;
       } else {
-        const desktopRenderer = new GSSplatRenderer(this.renderer, this.camera);
+        const desktopRenderer = this.createDesktopGSRenderer();
         this.useMobileRenderer = false;
         desktopRenderer.setData(splats);
         gsRenderer = desktopRenderer;
@@ -16425,11 +17053,14 @@ class App {
       const isMobile = isMobileDevice();
       let buffer;
       if (typeof urlOrBuffer === "string") {
-        buffer = await this.fetchWithProgress(urlOrBuffer, (downloadProgress) => {
-          if (onProgress) {
-            onProgress(downloadProgress * 0.5, "download");
+        buffer = await this.fetchWithProgress(
+          urlOrBuffer,
+          (downloadProgress) => {
+            if (onProgress) {
+              onProgress(downloadProgress * 0.5, "download");
+            }
           }
-        });
+        );
       } else {
         buffer = urlOrBuffer;
         if (onProgress && isLocalFile) {
@@ -16466,7 +17097,7 @@ class App {
         gsRenderer = new GSSplatRendererMobile(this.renderer, this.camera);
         this.useMobileRenderer = true;
       } else {
-        gsRenderer = new GSSplatRenderer(this.renderer, this.camera);
+        gsRenderer = this.createDesktopGSRenderer();
         this.useMobileRenderer = false;
       }
       gsRenderer.setCompactData(compactData);
@@ -16519,9 +17150,69 @@ class App {
     this.render();
     this.animationId = requestAnimationFrame(this.animate.bind(this));
   }
+  updateAdaptivePerformance() {
+    if (!this.adaptivePerformanceEnabled) return;
+    const gsRenderer = this.getGSRenderer();
+    if (!gsRenderer) return;
+    const bbox = gsRenderer.getBoundingBox();
+    if (!bbox || bbox.radius < 1e-6) return;
+    const cam = this.camera.position;
+    const model = gsRenderer.getModelMatrix();
+    const cx = bbox.center[0] * model[0] + bbox.center[1] * model[4] + bbox.center[2] * model[8] + model[12];
+    const cy = bbox.center[0] * model[1] + bbox.center[1] * model[5] + bbox.center[2] * model[9] + model[13];
+    const cz = bbox.center[0] * model[2] + bbox.center[1] * model[6] + bbox.center[2] * model[10] + model[14];
+    const modelScale = Math.max(
+      Math.sqrt(
+        model[0] * model[0] + model[1] * model[1] + model[2] * model[2]
+      ),
+      Math.sqrt(
+        model[4] * model[4] + model[5] * model[5] + model[6] * model[6]
+      ),
+      Math.sqrt(
+        model[8] * model[8] + model[9] * model[9] + model[10] * model[10]
+      )
+    );
+    const scaledRadius = bbox.radius * modelScale;
+    const dx = cam[0] - cx;
+    const dy = cam[1] - cy;
+    const dz = cam[2] - cz;
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    const distanceRatio = distance / scaledRadius;
+    const cfg = this.adaptiveConfig;
+    const t = smoothstep(cfg.nearThreshold, cfg.farThreshold, distanceRatio);
+    const renderScale = cfg.minRenderScale + (this.baseRenderScale - cfg.minRenderScale) * t;
+    const quantizedScale = Math.round(renderScale * 20) / 20;
+    if (quantizedScale !== this.lastAppliedRenderScale) {
+      this.renderer.setRenderScale(quantizedScale);
+      this.lastAppliedRenderScale = quantizedScale;
+    }
+    const pixelThreshold = cfg.maxPixelThreshold + (cfg.minPixelThreshold - cfg.maxPixelThreshold) * t;
+    gsRenderer.setPixelCullThreshold(pixelThreshold);
+    const splatCount = gsRenderer.getSplatCount();
+    if (cfg.farUnlimited && t >= 0.99) {
+      gsRenderer.setMaxVisibleSplats(0);
+    } else {
+      const ratio = cfg.nearVisibleRatio + (1 - cfg.nearVisibleRatio) * t;
+      gsRenderer.setMaxVisibleSplats(Math.round(splatCount * ratio));
+    }
+    if (cfg.enableDepthRangeLimit) {
+      if (t >= 0.99) {
+        gsRenderer.setDepthRangeLimit(0);
+      } else {
+        const depthRange = scaledRadius * (cfg.nearDepthRangeRatio + (4 - cfg.nearDepthRangeRatio) * t);
+        gsRenderer.setDepthRangeLimit(depthRange);
+      }
+    }
+    if (t < 0.3) {
+      gsRenderer.setSortFrequency(2);
+    } else {
+      gsRenderer.setSortFrequency(1);
+    }
+  }
   render() {
     this.camera.setAspect(this.renderer.getAspectRatio());
     this.controls.update();
+    this.updateAdaptivePerformance();
     this.hotspotManager.updateBillboards();
     const pass = this.renderer.beginFrame();
     const gsRenderer = this.sceneManager.getGSRenderer();
@@ -16532,10 +17223,12 @@ class App {
     this.sceneAids.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);
+    if (this.hotspotManager.isActive()) {
+      this.hotspotManager.consumeGPUResult();
+      if (gsRenderer == null ? void 0 : gsRenderer.prepareDepthNormalPass) {
+        const [px, py] = this.hotspotManager.getPickPixel();
+        gsRenderer.prepareDepthNormalPass(px, py);
+      }
     }
   }
   onResize() {
@@ -16640,7 +17333,14 @@ class App {
     return this.sceneManager.getOverlayMeshColor(index);
   }
   setOverlayMeshRangeColor(startIndex, count, r, g, b, a = 1) {
-    return this.sceneManager.setOverlayMeshRangeColor(startIndex, count, r, g, b, a);
+    return this.sceneManager.setOverlayMeshRangeColor(
+      startIndex,
+      count,
+      r,
+      g,
+      b,
+      a
+    );
   }
   createOverlayMeshGroupProxy(startIndex, count) {
     const meshes = this.sceneManager.getOverlayMeshRange(startIndex, count);
@@ -16777,16 +17477,28 @@ class App {
     return this.hotspotManager.getHotspotBillboard(hotspotIndex);
   }
   setHotspotPlacedScale(hotspotIndex, newPlacedScale) {
-    return this.hotspotManager.setHotspotPlacedScale(hotspotIndex, newPlacedScale);
+    return this.hotspotManager.setHotspotPlacedScale(
+      hotspotIndex,
+      newPlacedScale
+    );
   }
   getHotspotCount() {
     return this.hotspotManager.getHotspotCount();
   }
   findHotspotIndexByMeshStart(overlayMeshStartIndex) {
-    return this.hotspotManager.findHotspotIndexByMeshStart(overlayMeshStartIndex);
+    return this.hotspotManager.findHotspotIndexByMeshStart(
+      overlayMeshStartIndex
+    );
   }
   async placeHotspotAt(objUrl, position, normal, visualDiameter, normalOffset, overrideScale) {
-    return this.hotspotManager.placeHotspotAt(objUrl, position, normal, visualDiameter, normalOffset, overrideScale);
+    return this.hotspotManager.placeHotspotAt(
+      objUrl,
+      position,
+      normal,
+      visualDiameter,
+      normalOffset,
+      overrideScale
+    );
   }
   getOverlayMeshByIndex(index) {
     return this.sceneManager.getOverlayMeshByIndex(index);
@@ -16817,7 +17529,13 @@ class App {
    * 设置热点文字标签
    */
   setHotspotLabel(hotspotIndex, text, position, fontSize, visible) {
-    return this.hotspotManager.setHotspotLabel(hotspotIndex, text, position, fontSize, visible);
+    return this.hotspotManager.setHotspotLabel(
+      hotspotIndex,
+      text,
+      position,
+      fontSize,
+      visible
+    );
   }
   /**
    * 设置热点标签可见性
@@ -16898,7 +17616,10 @@ class App {
    * 适用于移动端提质或桌面端降负载
    */
   setRenderScale(scale) {
-    this.renderer.setRenderScale(scale);
+    this.baseRenderScale = scale;
+    if (!this.adaptivePerformanceEnabled) {
+      this.renderer.setRenderScale(scale);
+    }
   }
   getRenderScale() {
     return this.renderer.getRenderScale();
@@ -16946,6 +17667,49 @@ class App {
       mobileRenderer.setSortFrequency(frequency);
     }
   }
+  /**
+   * 是否检测到 Apple GPU（M1/M2/M3 等）
+   */
+  get isAppleGPU() {
+    var _a2;
+    return ((_a2 = this.renderer) == null ? void 0 : _a2.isAppleGPU) ?? false;
+  }
+  // ============================================
+  // 自适应性能控制
+  // ============================================
+  /**
+   * 启用/禁用自适应性能优化
+   * 开启后系统会根据相机与模型的距离自动调节：
+   * - 渲染分辨率（renderScale）
+   * - 亚像素剔除阈值（pixelThreshold）
+   * - 最大可见 splat 数量（maxVisibleSplats）
+   */
+  setAdaptivePerformance(enabled) {
+    this.adaptivePerformanceEnabled = enabled;
+    if (!enabled) {
+      this.renderer.setRenderScale(this.baseRenderScale);
+      this.lastAppliedRenderScale = this.baseRenderScale;
+      const gsRenderer = this.getGSRenderer();
+      if (gsRenderer) {
+        gsRenderer.setPixelCullThreshold(1);
+        gsRenderer.setMaxVisibleSplats(0);
+        gsRenderer.setDepthRangeLimit(0);
+        gsRenderer.setSortFrequency(1);
+      }
+    }
+  }
+  getAdaptivePerformance() {
+    return this.adaptivePerformanceEnabled;
+  }
+  /**
+   * 设置自适应性能配置参数
+   */
+  setAdaptivePerformanceConfig(config) {
+    this.adaptiveConfig = { ...this.adaptiveConfig, ...config };
+  }
+  getAdaptivePerformanceConfig() {
+    return { ...this.adaptiveConfig };
+  }
   /**
    * 销毁应用及所有资源
    */