@d5techs/3dgs-lib 1.2.0 → 1.4.0

package/dist/3dgs-lib.js

@@ -4411,7 +4411,8 @@ function readProperty$1(dataView, baseOffset, prop, littleEndian) {
 function sigmoid$1(x) {
   return 1 / (1 + Math.exp(-x));
 }
-async function loadPLY(url) {
+async function loadPLY(url, options = {}) {
+  const { coordinateSystem = "blender" } = options;
   const response = await fetch(url);
   if (!response.ok) {
     throw new Error(`无法加载 PLY 文件: ${url}`);
@@ -4423,6 +4424,7 @@ async function loadPLY(url) {
     throw new Error("不支持 ASCII 格式的 PLY 文件，请使用 binary_little_endian 或 binary_big_endian 格式");
   }
   const littleEndian = format === "binary_little_endian";
+  const swapYZ = coordinateSystem === "blender";
   const propMap = buildPropertyMap(properties);
   const props = {
     x: propMap.get("x"),
@@ -4488,9 +4490,14 @@ async function loadPLY(url) {
       shRest[dstBase + 2] = srcB < shRestProps.length ? readProperty$1(dataView, base, shRestProps[srcB], littleEndian) : 0;
     }
     splats[i] = {
-      mean: [x, y, z],
-      scale: [scale_0, scale_1, scale_2],
-      rotation: [
+      mean: swapYZ ? [x, z, y] : [x, y, z],
+      scale: swapYZ ? [scale_0, scale_2, scale_1] : [scale_0, scale_1, scale_2],
+      rotation: swapYZ ? [
+        -rot_0 * qnorm,
+        rot_1 * qnorm,
+        rot_3 * qnorm,
+        rot_2 * qnorm
+      ] : [
         rot_0 * qnorm,
         rot_1 * qnorm,
         rot_2 * qnorm,
@@ -4706,7 +4713,8 @@ async function parsePLYBuffer(buffer, options = {}) {
   const {
     maxSplats = 2e5,
     loadSH = false,
-    onProgress
+    onProgress,
+    coordinateSystem = "blender"
   } = options;
   const seed = options.seed ?? buffer.byteLength;
   const { headerText, dataOffset } = extractHeader(buffer);
@@ -4796,27 +4804,41 @@ async function parsePLYBuffer(buffer, options = {}) {
   const opacities = new Float32Array(actualCount);
   const shCoeffs = loadSH ? new Float32Array(actualCount * 45) : void 0;
   const dataView = new DataView(buffer, dataOffset);
+  const swapYZ = coordinateSystem === "blender";
   let outputIdx = 0;
   let lastProgress = 0;
   for (let i = 0; i < actualCount; i++) {
     const srcIdx = sampleIndices ? sampleIndices[i] : i;
     const base = srcIdx * stride;
-    positions[outputIdx * 3 + 0] = offsets.x >= 0 ? readProperty(dataView, base + offsets.x, types.x, littleEndian) : 0;
-    positions[outputIdx * 3 + 1] = offsets.y >= 0 ? readProperty(dataView, base + offsets.y, types.y, littleEndian) : 0;
-    positions[outputIdx * 3 + 2] = offsets.z >= 0 ? readProperty(dataView, base + offsets.z, types.z, littleEndian) : 0;
-    scales[outputIdx * 3 + 0] = offsets.scale_0 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_0, types.scale_0, littleEndian)) : 1;
-    scales[outputIdx * 3 + 1] = offsets.scale_1 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_1, types.scale_1, littleEndian)) : 1;
-    scales[outputIdx * 3 + 2] = offsets.scale_2 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_2, types.scale_2, littleEndian)) : 1;
+    const px = offsets.x >= 0 ? readProperty(dataView, base + offsets.x, types.x, littleEndian) : 0;
+    const py = offsets.y >= 0 ? readProperty(dataView, base + offsets.y, types.y, littleEndian) : 0;
+    const pz = offsets.z >= 0 ? readProperty(dataView, base + offsets.z, types.z, littleEndian) : 0;
+    positions[outputIdx * 3 + 0] = px;
+    positions[outputIdx * 3 + 1] = swapYZ ? pz : py;
+    positions[outputIdx * 3 + 2] = swapYZ ? py : pz;
+    const sx = offsets.scale_0 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_0, types.scale_0, littleEndian)) : 1;
+    const sy = offsets.scale_1 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_1, types.scale_1, littleEndian)) : 1;
+    const sz = offsets.scale_2 >= 0 ? Math.exp(readProperty(dataView, base + offsets.scale_2, types.scale_2, littleEndian)) : 1;
+    scales[outputIdx * 3 + 0] = sx;
+    scales[outputIdx * 3 + 1] = swapYZ ? sz : sy;
+    scales[outputIdx * 3 + 2] = swapYZ ? sy : sz;
     const rot_0 = offsets.rot_0 >= 0 ? readProperty(dataView, base + offsets.rot_0, types.rot_0, littleEndian) : 1;
     const rot_1 = offsets.rot_1 >= 0 ? readProperty(dataView, base + offsets.rot_1, types.rot_1, littleEndian) : 0;
     const rot_2 = offsets.rot_2 >= 0 ? readProperty(dataView, base + offsets.rot_2, types.rot_2, littleEndian) : 0;
     const rot_3 = offsets.rot_3 >= 0 ? readProperty(dataView, base + offsets.rot_3, types.rot_3, littleEndian) : 0;
     const qlen = Math.sqrt(rot_0 * rot_0 + rot_1 * rot_1 + rot_2 * rot_2 + rot_3 * rot_3);
     const qnorm = qlen > 0 ? 1 / qlen : 1;
-    rotations[outputIdx * 4 + 0] = rot_0 * qnorm;
-    rotations[outputIdx * 4 + 1] = rot_1 * qnorm;
-    rotations[outputIdx * 4 + 2] = rot_2 * qnorm;
-    rotations[outputIdx * 4 + 3] = rot_3 * qnorm;
+    if (swapYZ) {
+      rotations[outputIdx * 4 + 0] = -rot_0 * qnorm;
+      rotations[outputIdx * 4 + 1] = rot_1 * qnorm;
+      rotations[outputIdx * 4 + 2] = rot_3 * qnorm;
+      rotations[outputIdx * 4 + 3] = rot_2 * qnorm;
+    } else {
+      rotations[outputIdx * 4 + 0] = rot_0 * qnorm;
+      rotations[outputIdx * 4 + 1] = rot_1 * qnorm;
+      rotations[outputIdx * 4 + 2] = rot_2 * qnorm;
+      rotations[outputIdx * 4 + 3] = rot_3 * qnorm;
+    }
     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;
@@ -11598,6 +11620,8 @@ class TransformGizmo {
     __publicField(this, "dragMode", "selected");
     // 平面翻转
     __publicField(this, "flipPlanes", true);
+    /** 强制等比缩放：开启后无论拖哪个轴，缩放都作用于 xyz */
+    __publicField(this, "uniformScaleOnly", false);
     // 目标对象
     __publicField(this, "_target", null);
     // 形状
@@ -12684,7 +12708,8 @@ class TransformGizmo {
   }
   _applyScale(delta) {
     if (!this._target || !this._dragStartTransform) return;
-    const axis = this._selectedAxis;
+    let axis = this._selectedAxis;
+    if (this.uniformScaleOnly) axis = "xyz";
     let scaleFactor = 1;
     if (axis === "x") scaleFactor = 1 + delta.x;
     else if (axis === "y") scaleFactor = 1 + delta.y;
@@ -12863,6 +12888,9 @@ class GizmoManager {
   setGizmoMode(mode) {
     this.transformGizmo.mode = mode;
   }
+  setUniformScaleOnly(enabled) {
+    this.transformGizmo.uniformScaleOnly = enabled;
+  }
   /**
    * 设置 Gizmo 目标对象
    */
@@ -12983,9 +13011,17 @@ class HotspotManager {
     __publicField(this, "indicatorBaseRadius", 0.02);
     // 搜索邻域的屏幕空间半径（像素）
     __publicField(this, "pickRadiusPx", 20);
+    // 标签 overlay 容器
+    __publicField(this, "labelContainer", null);
+    // 热点点击回调
+    __publicField(this, "onHotspotClicked", null);
+    // 热点点击命中半径（屏幕空间 NDC 距离）
+    __publicField(this, "hotspotHitRadius", 0.05);
     // 回调
     __publicField(this, "onHotspotPlaced", null);
     __publicField(this, "onModeChanged", null);
+    __publicField(this, "_clickListenerBound", false);
+    __publicField(this, "_boundOnCanvasClick", null);
     // ============================================
     // 事件处理
     // ============================================
@@ -13007,6 +13043,7 @@ class HotspotManager {
     this.boundOnMouseDown = this.onMouseDown.bind(this);
     this.boundOnMouseUp = this.onMouseUp.bind(this);
     this.boundOnKeyDown = this.onKeyDown.bind(this);
+    this.initLabelContainer();
   }
   setGSRenderer(gsRenderer) {
     this.gsRenderer = gsRenderer;
@@ -13072,6 +13109,175 @@ class HotspotManager {
   setOnModeChanged(cb) {
     this.onModeChanged = cb;
   }
+  // ============================================
+  // 标签管理
+  // ============================================
+  initLabelContainer() {
+    const container = document.createElement("div");
+    container.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;overflow:hidden;z-index:10";
+    const parent = this.canvas.parentElement;
+    if (parent) {
+      const pos = getComputedStyle(parent).position;
+      if (pos === "static") parent.style.position = "relative";
+      parent.appendChild(container);
+    }
+    this.labelContainer = container;
+  }
+  /**
+   * 设置热点标签
+   */
+  setHotspotLabel(hotspotIndex, text, position = "top", fontSize = 14, visible = true) {
+    if (hotspotIndex < 0 || hotspotIndex >= this.hotspots.length) return false;
+    const info = this.hotspots[hotspotIndex];
+    info.label = { text, position, fontSize, visible };
+    this.ensureLabelElement(info);
+    this.applyLabelStyle(info);
+    return true;
+  }
+  /**
+   * 设置热点标签可见性
+   */
+  setHotspotLabelVisible(hotspotIndex, visible) {
+    if (hotspotIndex < 0 || hotspotIndex >= this.hotspots.length) return false;
+    const info = this.hotspots[hotspotIndex];
+    if (!info.label) return false;
+    info.label.visible = visible;
+    if (info._labelElement) {
+      info._labelElement.style.display = visible ? "block" : "none";
+    }
+    return true;
+  }
+  /**
+   * 获取热点标签配置
+   */
+  getHotspotLabel(hotspotIndex) {
+    if (hotspotIndex < 0 || hotspotIndex >= this.hotspots.length) return null;
+    return this.hotspots[hotspotIndex].label ?? null;
+  }
+  ensureLabelElement(info) {
+    if (info._labelElement) return;
+    if (!this.labelContainer) return;
+    const el = document.createElement("div");
+    el.style.cssText = "position:absolute;white-space:nowrap;color:#fff;text-shadow:0 1px 4px rgba(0,0,0,0.8);pointer-events:none;transform-origin:center;transition:opacity 0.15s";
+    this.labelContainer.appendChild(el);
+    info._labelElement = el;
+  }
+  applyLabelStyle(info) {
+    const el = info._labelElement;
+    const label = info.label;
+    if (!el || !label) return;
+    el.textContent = label.text;
+    el.style.fontSize = `${label.fontSize}px`;
+    el.style.display = label.visible ? "block" : "none";
+  }
+  /**
+   * 每帧更新所有标签的屏幕位置
+   */
+  updateLabels() {
+    var _a2;
+    if (!this.labelContainer) return;
+    const rect = this.canvas.getBoundingClientRect();
+    const vp = this.camera.viewProjectionMatrix;
+    for (const info of this.hotspots) {
+      if (!((_a2 = info.label) == null ? void 0 : _a2.visible) || !info._labelElement) continue;
+      const [px, py, pz] = info.position;
+      const clipW = vp[3] * px + vp[7] * py + vp[11] * pz + vp[15];
+      if (clipW <= 0) {
+        info._labelElement.style.opacity = "0";
+        continue;
+      }
+      const ndcX = (vp[0] * px + vp[4] * py + vp[8] * pz + vp[12]) / clipW;
+      const ndcY = (vp[1] * px + vp[5] * py + vp[9] * pz + vp[13]) / clipW;
+      const screenX = (ndcX + 1) * 0.5 * rect.width;
+      const screenY = (1 - ndcY) * 0.5 * rect.height;
+      const el = info._labelElement;
+      el.style.opacity = "1";
+      const iconOffset = 20;
+      switch (info.label.position) {
+        case "top":
+          el.style.left = `${screenX}px`;
+          el.style.top = `${screenY - iconOffset}px`;
+          el.style.transform = "translate(-50%, -100%)";
+          break;
+        case "left":
+          el.style.left = `${screenX - iconOffset}px`;
+          el.style.top = `${screenY}px`;
+          el.style.transform = "translate(-100%, -50%)";
+          break;
+        case "right":
+          el.style.left = `${screenX + iconOffset}px`;
+          el.style.top = `${screenY}px`;
+          el.style.transform = "translate(0, -50%)";
+          break;
+      }
+    }
+  }
+  // ============================================
+  // 热点点击检测
+  // ============================================
+  /**
+   * 设置热点点击回调
+   */
+  setOnHotspotClicked(cb) {
+    this.onHotspotClicked = cb;
+    if (cb && !this._clickListenerBound) {
+      this._boundOnCanvasClick = this._onCanvasClick.bind(this);
+      this.canvas.addEventListener("click", this._boundOnCanvasClick);
+      this._clickListenerBound = true;
+    } else if (!cb && this._clickListenerBound && this._boundOnCanvasClick) {
+      this.canvas.removeEventListener("click", this._boundOnCanvasClick);
+      this._clickListenerBound = false;
+    }
+  }
+  _onCanvasClick(e) {
+    if (this.active) return;
+    const idx = this.hitTestHotspot(e.clientX, e.clientY);
+    if (idx >= 0 && this.onHotspotClicked) {
+      this.onHotspotClicked(idx, this.hotspots[idx]);
+    }
+  }
+  /**
+   * 检测给定屏幕坐标命中了哪个热点
+   * @returns 热点索引，-1 表示未命中
+   */
+  hitTestHotspot(clientX, clientY) {
+    if (this.hotspots.length === 0) return -1;
+    const rect = this.canvas.getBoundingClientRect();
+    const ndcX = (clientX - rect.left) / rect.width * 2 - 1;
+    const ndcY = -((clientY - rect.top) / rect.height * 2 - 1);
+    const vp = this.camera.viewProjectionMatrix;
+    const camPos = this.camera.position;
+    let closestDist = Infinity;
+    let closestIdx = -1;
+    for (let i = 0; i < this.hotspots.length; i++) {
+      const h = this.hotspots[i];
+      const [px, py, pz] = h.position;
+      const clipW = vp[3] * px + vp[7] * py + vp[11] * pz + vp[15];
+      if (clipW <= 0) continue;
+      const clipX = (vp[0] * px + vp[4] * py + vp[8] * pz + vp[12]) / clipW;
+      const clipY = (vp[1] * px + vp[5] * py + vp[9] * pz + vp[13]) / clipW;
+      const dx = clipX - ndcX;
+      const dy = clipY - ndcY;
+      const screenDist = Math.sqrt(dx * dx + dy * dy);
+      if (screenDist < this.hotspotHitRadius) {
+        const cx = px - camPos[0];
+        const cy = py - camPos[1];
+        const cz = pz - camPos[2];
+        const dist3D = cx * cx + cy * cy + cz * cz;
+        if (dist3D < closestDist) {
+          closestDist = dist3D;
+          closestIdx = i;
+        }
+      }
+    }
+    return closestIdx;
+  }
+  /**
+   * 设置热点点击命中半径（NDC 空间，默认 0.05）
+   */
+  setHotspotHitRadius(radius) {
+    this.hotspotHitRadius = radius;
+  }
   /**
    * Returns the current pick pixel coordinates in device pixels.
    * Called by the render loop to pass to prepareDepthNormalPass.
@@ -13713,6 +13919,117 @@ class HotspotManager {
       (h) => h.meshStartIndex === overlayMeshStartIndex
     );
   }
+  /**
+   * 在指定位置和法线方向程序化放置一个热点（用于从保存数据恢复）。
+   * 逻辑与交互放置一致：加载 OBJ → 计算朝向矩阵 → addOverlayMesh → 注册到内部列表。
+   * @returns 放置后的 HotspotInfo，失败返回 null
+   */
+  async placeHotspotAt(objUrl, position, normal, visualDiameter, normalOffset, overrideScale) {
+    var _a2;
+    try {
+      const loadedMeshes = await this.objLoader.load(objUrl);
+      if (loadedMeshes.length === 0) return null;
+      if (visualDiameter == null) {
+        const bbox = (_a2 = this.gsRenderer) == null ? void 0 : _a2.getBoundingBox();
+        visualDiameter = bbox ? bbox.radius * 0.03 : 0.3;
+      }
+      if (normalOffset == null) {
+        normalOffset = 0.02;
+      }
+      const meshStartIndex = this.meshRenderer.getOverlayMeshCount();
+      const [nx, ny, nz] = normal;
+      let upX = 0, upY = 1, upZ = 0;
+      if (Math.abs(ny) > 0.99) {
+        upX = 1;
+        upY = 0;
+        upZ = 0;
+      }
+      let rx = upY * nz - upZ * ny;
+      let ry = upZ * nx - upX * nz;
+      let rz = upX * ny - upY * nx;
+      const rLen = Math.sqrt(rx * rx + ry * ry + rz * rz) || 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;
+      const fLen = Math.sqrt(fx * fx + fy * fy + fz * fz) || 1;
+      fx /= fLen;
+      fy /= fLen;
+      fz /= fLen;
+      let placedScale = 1;
+      let placedLocalCenter = [0, 0, 0];
+      const firstBbox = loadedMeshes[0].mesh.getLocalBoundingBox();
+      if (firstBbox) {
+        const modelMaxDim = Math.max(
+          firstBbox.max[0] - firstBbox.min[0],
+          firstBbox.max[1] - firstBbox.min[1],
+          firstBbox.max[2] - firstBbox.min[2],
+          1e-6
+        );
+        placedScale = overrideScale != null ? overrideScale : 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) {
+        const bbox = mesh.getLocalBoundingBox();
+        let s = placedScale;
+        let lcx = 0, lcy = 0, lcz = 0;
+        if (bbox) {
+          if (overrideScale != null) {
+            s = overrideScale;
+          } else {
+            const mDim = Math.max(bbox.max[0] - bbox.min[0], bbox.max[1] - bbox.min[1], bbox.max[2] - bbox.min[2], 1e-6);
+            s = visualDiameter / mDim;
+          }
+          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) * s;
+        const owy = (ry * lcx + fy * lcy + ny * lcz) * s;
+        const owz = (rz * lcx + fz * lcy + nz * lcz) * s;
+        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] = position[0] + nx * normalOffset - owx;
+        m[13] = position[1] + ny * normalOffset - owy;
+        m[14] = position[2] + nz * normalOffset - owz;
+        m[15] = 1;
+        this.decomposeModelMatrix(mesh);
+        this.meshRenderer.addOverlayMesh(mesh, material);
+      }
+      const info = {
+        position: [...position],
+        normal: [...normal],
+        meshStartIndex,
+        meshCount: loadedMeshes.length,
+        billboard: false,
+        placedScale,
+        placedNormalOffset: normalOffset,
+        placedLocalCenter
+      };
+      this.hotspots.push(info);
+      return info;
+    } catch (error) {
+      console.error("HotspotManager: placeHotspotAt 失败:", error);
+      return null;
+    }
+  }
   /**
    * 每帧调用：更新所有 billboard 热点朝向相机
    */
@@ -13796,6 +14113,7 @@ class HotspotManager {
         this.decomposeModelMatrix(mesh);
       }
     }
+    this.updateLabels();
   }
   /**
    * 关闭 billboard 时恢复到放置时的法线朝向
@@ -13873,7 +14191,18 @@ class HotspotManager {
   // 生命周期
   // ============================================
   destroy() {
+    var _a2, _b2;
     this.exit();
+    if (this._clickListenerBound && this._boundOnCanvasClick) {
+      this.canvas.removeEventListener("click", this._boundOnCanvasClick);
+      this._clickListenerBound = false;
+    }
+    for (const info of this.hotspots) {
+      (_a2 = info._labelElement) == null ? void 0 : _a2.remove();
+      info._labelElement = void 0;
+    }
+    (_b2 = this.labelContainer) == null ? void 0 : _b2.remove();
+    this.labelContainer = null;
     if (this.indicatorMesh && !this.indicatorAdded) {
       this.indicatorMesh.destroy();
     }
@@ -13968,8 +14297,12 @@ class App {
   }
   /**
    * 加载 PLY 文件 (3D Gaussian Splatting)
+   * @param urlOrBuffer PLY 文件 URL 或 ArrayBuffer
+   * @param onProgress 进度回调
+   * @param isLocalFile 是否为本地文件
+   * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
    */
-  async addPLY(urlOrBuffer, onProgress, isLocalFile = false) {
+  async addPLY(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
       const isMobile = isMobileDevice();
       let buffer;
@@ -13998,7 +14331,8 @@ class App {
         const compactData = await this.parsePLYBuffer(buffer, {
           maxSplats: Infinity,
           loadSH: false,
-          onProgress: parseProgressCallback
+          onProgress: parseProgressCallback,
+          coordinateSystem
         });
         if (onProgress) onProgress(90, "upload");
         gsRenderer.setCompactData(compactData);
@@ -14012,7 +14346,8 @@ class App {
         const compactData = await this.parsePLYBuffer(buffer, {
           maxSplats: Infinity,
           loadSH: true,
-          onProgress: parseProgressCallback
+          onProgress: parseProgressCallback,
+          coordinateSystem
         });
         if (onProgress) onProgress(90, "upload");
         gsRenderer.setCompactData(compactData);
@@ -14027,8 +14362,9 @@ class App {
   }
   /**
    * 加载 Splat 文件
+   * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
    */
-  async addSplat(urlOrBuffer, onProgress, isLocalFile = false) {
+  async addSplat(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
       let buffer;
       if (typeof urlOrBuffer === "string") {
@@ -14045,6 +14381,16 @@ class App {
       }
       if (onProgress) onProgress(50, "parse");
       const splats = deserializeSplat(buffer);
+      if (coordinateSystem === "blender") {
+        for (const s of splats) {
+          const [mx, my, mz] = s.mean;
+          s.mean = [mx, mz, my];
+          const [sx, sy, sz] = s.scale;
+          s.scale = [sx, sz, sy];
+          const [rw, rx, ry, rz] = s.rotation;
+          s.rotation = [-rw, rx, rz, ry];
+        }
+      }
       if (onProgress) onProgress(90, "parse");
       if (onProgress) onProgress(90, "upload");
       const gsRenderer = new GSSplatRenderer(this.renderer, this.camera);
@@ -14060,8 +14406,9 @@ class App {
   }
   /**
    * 加载 SOG 文件 (Spatially Ordered Gaussians)
+   * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
    */
-  async addSOG(urlOrBuffer, onProgress, isLocalFile = false) {
+  async addSOG(urlOrBuffer, onProgress, isLocalFile = false, coordinateSystem = "blender") {
     try {
       const isMobile = isMobileDevice();
       let buffer;
@@ -14083,6 +14430,22 @@ class App {
           onProgress(50 + p / 100 * 40, stage);
         }
       });
+      if (coordinateSystem === "blender") {
+        const { positions, scales, rotations, count } = compactData;
+        for (let i = 0; i < count; i++) {
+          const i3 = i * 3, i4 = i * 4;
+          const py = positions[i3 + 1], pz = positions[i3 + 2];
+          positions[i3 + 1] = pz;
+          positions[i3 + 2] = py;
+          const sy = scales[i3 + 1], sz = scales[i3 + 2];
+          scales[i3 + 1] = sz;
+          scales[i3 + 2] = sy;
+          const rw = rotations[i4], ry = rotations[i4 + 2], rz = rotations[i4 + 3];
+          rotations[i4] = -rw;
+          rotations[i4 + 2] = rz;
+          rotations[i4 + 3] = ry;
+        }
+      }
       if (onProgress) onProgress(90, "upload");
       let gsRenderer;
       if (isMobile) {
@@ -14287,6 +14650,9 @@ class App {
   setGizmoMode(mode) {
     this.gizmoManager.setGizmoMode(mode);
   }
+  setUniformScaleOnly(enabled) {
+    this.gizmoManager.setUniformScaleOnly(enabled);
+  }
   setGizmoTarget(object) {
     this.gizmoManager.setGizmoTarget(object);
   }
@@ -14385,10 +14751,53 @@ class App {
   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);
+  }
   getOverlayMeshByIndex(index) {
     return this.sceneManager.getOverlayMeshByIndex(index);
   }
   // ============================================
+  // 热点点击 & 标签
+  // ============================================
+  /**
+   * 检测给定屏幕坐标命中了哪个热点
+   * @returns 热点索引，-1 表示未命中
+   */
+  hitTestHotspot(clientX, clientY) {
+    return this.hotspotManager.hitTestHotspot(clientX, clientY);
+  }
+  /**
+   * 设置热点点击回调（非放置模式下生效）
+   */
+  setOnHotspotClicked(cb) {
+    this.hotspotManager.setOnHotspotClicked(cb);
+  }
+  /**
+   * 设置热点点击命中半径（NDC 空间，默认 0.05）
+   */
+  setHotspotHitRadius(radius) {
+    this.hotspotManager.setHotspotHitRadius(radius);
+  }
+  /**
+   * 设置热点文字标签
+   */
+  setHotspotLabel(hotspotIndex, text, position, fontSize, visible) {
+    return this.hotspotManager.setHotspotLabel(hotspotIndex, text, position, fontSize, visible);
+  }
+  /**
+   * 设置热点标签可见性
+   */
+  setHotspotLabelVisible(hotspotIndex, visible) {
+    return this.hotspotManager.setHotspotLabelVisible(hotspotIndex, visible);
+  }
+  /**
+   * 获取热点标签配置
+   */
+  getHotspotLabel(hotspotIndex) {
+    return this.hotspotManager.getHotspotLabel(hotspotIndex);
+  }
+  // ============================================
   // 内部方法
   // ============================================
   async fetchWithProgress(url, onProgress) {