@d5techs/3dgs-lib 1.3.0 → 1.4.0

package/dist/3dgs-lib.cjs

@@ -11622,6 +11622,8 @@ class TransformGizmo {
     __publicField(this, "dragMode", "selected");
     // 平面翻转
     __publicField(this, "flipPlanes", true);
+    /** 强制等比缩放：开启后无论拖哪个轴，缩放都作用于 xyz */
+    __publicField(this, "uniformScaleOnly", false);
     // 目标对象
     __publicField(this, "_target", null);
     // 形状
@@ -12708,7 +12710,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;
@@ -12887,6 +12890,9 @@ class GizmoManager {
   setGizmoMode(mode) {
     this.transformGizmo.mode = mode;
   }
+  setUniformScaleOnly(enabled) {
+    this.transformGizmo.uniformScaleOnly = enabled;
+  }
   /**
    * 设置 Gizmo 目标对象
    */
@@ -13007,9 +13013,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);
     // ============================================
     // 事件处理
     // ============================================
@@ -13031,6 +13045,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;
@@ -13096,6 +13111,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.
@@ -13737,6 +13921,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 热点朝向相机
    */
@@ -13820,6 +14115,7 @@ class HotspotManager {
         this.decomposeModelMatrix(mesh);
       }
     }
+    this.updateLabels();
   }
   /**
    * 关闭 billboard 时恢复到放置时的法线朝向
@@ -13897,7 +14193,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();
     }
@@ -14057,8 +14364,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") {
@@ -14075,6 +14383,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);
@@ -14090,8 +14408,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;
@@ -14113,6 +14432,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) {
@@ -14317,6 +14652,9 @@ class App {
   setGizmoMode(mode) {
     this.gizmoManager.setGizmoMode(mode);
   }
+  setUniformScaleOnly(enabled) {
+    this.gizmoManager.setUniformScaleOnly(enabled);
+  }
   setGizmoTarget(object) {
     this.gizmoManager.setGizmoTarget(object);
   }
@@ -14415,10 +14753,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) {