@d5techs/3dgs-lib 1.2.0 → 1.4.0

package/dist/App.d.ts

@@ -19,11 +19,12 @@ import { GSSplatRenderer } from "./gs/GSSplatRenderer";
 import { GSSplatRendererMobile } from "./gs/GSSplatRendererMobile";
 import type { BoundingBox, SimpleBoundingBox } from "./types";
 import { HotspotManager } from "./interaction/HotspotManager";
-import type { HotspotInfo } from "./interaction/HotspotManager";
+import type { HotspotInfo, HotspotLabelPosition, HotspotLabelConfig } from "./interaction/HotspotManager";
 import { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider } from "./scene/proxies";
 import { TransformableObject, GizmoMode } from "./core/gizmo/TransformGizmo";
 import type { BoundingBoxProvider } from "./types";
 import { SceneAidsRenderer } from "./core/SceneAidsRenderer";
+import type { CoordinateSystem } from "./gs/PLYLoaderMobile";
 /**
  * 统一进度回调类型
  * @param progress 进度值 0-100
@@ -64,16 +65,22 @@ export declare class App {
     addOBJ(url: string): Promise<Mesh[]>;
     /**
      * 加载 PLY 文件 (3D Gaussian Splatting)
+     * @param urlOrBuffer PLY 文件 URL 或 ArrayBuffer
+     * @param onProgress 进度回调
+     * @param isLocalFile 是否为本地文件
+     * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
      */
-    addPLY(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
+    addPLY(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean, coordinateSystem?: CoordinateSystem): Promise<number>;
     /**
      * 加载 Splat 文件
+     * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
      */
-    addSplat(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
+    addSplat(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean, coordinateSystem?: CoordinateSystem): Promise<number>;
     /**
      * 加载 SOG 文件 (Spatially Ordered Gaussians)
+     * @param coordinateSystem 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换）
      */
-    addSOG(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean): Promise<number>;
+    addSOG(urlOrBuffer: string | ArrayBuffer, onProgress?: ProgressCallback, isLocalFile?: boolean, coordinateSystem?: CoordinateSystem): Promise<number>;
     /**
      * 添加测试立方体
      */
@@ -123,6 +130,7 @@ export declare class App {
     getViewportGizmo(): import(".").ViewportGizmo;
     getBoundingBoxRenderer(): import(".").BoundingBoxRenderer;
     setGizmoMode(mode: GizmoMode): void;
+    setUniformScaleOnly(enabled: boolean): void;
     setGizmoTarget(object: TransformableObject | null): void;
     setSelectionBoundingBox(box: SimpleBoundingBox | null): void;
     setSelectionBoundingBoxProvider(provider: BoundingBoxProvider | null): void;
@@ -155,7 +163,33 @@ export declare class App {
     getHotspotBillboard(hotspotIndex: number): boolean;
     getHotspotCount(): number;
     findHotspotIndexByMeshStart(overlayMeshStartIndex: number): number;
+    placeHotspotAt(objUrl: string, position: [number, number, number], normal: [number, number, number], visualDiameter?: number, normalOffset?: number, overrideScale?: number): Promise<HotspotInfo | null>;
     getOverlayMeshByIndex(index: number): import("./mesh/Mesh").Mesh | null;
+    /**
+     * 检测给定屏幕坐标命中了哪个热点
+     * @returns 热点索引，-1 表示未命中
+     */
+    hitTestHotspot(clientX: number, clientY: number): number;
+    /**
+     * 设置热点点击回调（非放置模式下生效）
+     */
+    setOnHotspotClicked(cb: ((hotspotIndex: number, info: HotspotInfo) => void) | null): void;
+    /**
+     * 设置热点点击命中半径（NDC 空间，默认 0.05）
+     */
+    setHotspotHitRadius(radius: number): void;
+    /**
+     * 设置热点文字标签
+     */
+    setHotspotLabel(hotspotIndex: number, text: string, position?: HotspotLabelPosition, fontSize?: number, visible?: boolean): boolean;
+    /**
+     * 设置热点标签可见性
+     */
+    setHotspotLabelVisible(hotspotIndex: number, visible: boolean): boolean;
+    /**
+     * 获取热点标签配置
+     */
+    getHotspotLabel(hotspotIndex: number): HotspotLabelConfig | null;
     private fetchWithProgress;
     private parsePLYBuffer;
     setGridVisible(visible: boolean): void;

package/dist/core/gizmo/TransformGizmo.d.ts

@@ -81,6 +81,8 @@ export declare class TransformGizmo {
     snapIncrement: number;
     dragMode: GizmoDragMode;
     flipPlanes: boolean;
+    /** 强制等比缩放：开启后无论拖哪个轴，缩放都作用于 xyz */
+    uniformScaleOnly: boolean;
     private _target;
     private _shapes;
     private _hoverAxis;

package/dist/gs/PLYLoader.d.ts

@@ -14,9 +14,15 @@ export type SplatCPU = {
     opacity: number;
     shRest?: Float32Array;
 };
+import type { CoordinateSystem } from './PLYLoaderMobile';
+export interface PLYLoadOptions {
+    /** 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换） */
+    coordinateSystem?: CoordinateSystem;
+}
 /**
  * 加载并解析 PLY 文件
  * @param url PLY 文件的 URL
+ * @param options 加载选项
  * @returns SplatCPU 数组
  */
-export declare function loadPLY(url: string): Promise<SplatCPU[]>;
+export declare function loadPLY(url: string, options?: PLYLoadOptions): Promise<SplatCPU[]>;

package/dist/gs/PLYLoaderMobile.d.ts

@@ -9,6 +9,12 @@
  * 5. 支持多种 PLY 数据类型
  * 6. 确定性采样（基于文件内容的种子）
  */
+/**
+ * 坐标系类型
+ * - 'blender': Blender 坐标系 (Z-up, 右手系)，加载时自动将 Y/Z 对调转换为 WebGPU 的 Y-up 坐标系
+ * - 'webgpu': WebGPU 坐标系 (Y-up)，数据已经是 Y-up 格式，不做转换
+ */
+export type CoordinateSystem = 'blender' | 'webgpu';
 /**
  * 移动端加载配置
  */
@@ -21,6 +27,8 @@ export interface MobileLoadOptions {
     onProgress?: (loaded: number, total: number) => void;
     /** 随机种子（用于确定性采样，默认使用文件大小作为种子） */
     seed?: number;
+    /** 源数据坐标系，默认 'blender'（Z-up → Y-up 自动转换） */
+    coordinateSystem?: CoordinateSystem;
 }
 /**
  * 紧凑 Splat 数据（用于移动端）

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export { MTLParser } from './loaders/MTLParser';
 export type { ParsedMaterial } from './loaders/MTLParser';
 export type { IGSSplatRenderer, IGSSplatRendererWithCapabilities, } from './gs/IGSSplatRenderer';
 export { loadPLY } from './gs/PLYLoader';
-export type { SplatCPU } from './gs/PLYLoader';
+export type { SplatCPU, PLYLoadOptions } from './gs/PLYLoader';
 export { loadPLYMobile, parsePLYBuffer, compactDataToGPUBuffer } from './gs/PLYLoaderMobile';
-export type { MobileLoadOptions, CompactSplatData } from './gs/PLYLoaderMobile';
+export type { MobileLoadOptions, CompactSplatData, CoordinateSystem } from './gs/PLYLoaderMobile';
 export { loadSplat, deserializeSplat } from './gs/SplatLoader';
 export { loadSOG, deserializeSOG } from './gs/SOGLoader';
 export type { SOGProgressCallback } from './gs/SOGLoader';
@@ -41,7 +41,7 @@ export type { SceneObjectType, SceneObjectInfo } from './scene/SceneManager';
 export { SplatTransformProxy, MeshGroupProxy, SplatBoundingBoxProvider, } from './scene/proxies';
 export { GizmoManager } from './interaction/GizmoManager';
 export { HotspotManager } from './interaction/HotspotManager';
-export type { HotspotInfo } from './interaction/HotspotManager';
+export type { HotspotInfo, HotspotLabelConfig, HotspotLabelPosition } from './interaction/HotspotManager';
 export type { TransformableObject } from './core/gizmo/TransformGizmo';
 export { TransformGizmo, GizmoMode } from './core/gizmo/TransformGizmo';
 export type { GizmoTheme, TransformGizmoConfig, GizmoSpace } from './core/gizmo/TransformGizmo';

package/dist/interaction/GizmoManager.d.ts

@@ -52,6 +52,7 @@ export declare class GizmoManager {
      * 设置 Gizmo 模式
      */
     setGizmoMode(mode: GizmoMode): void;
+    setUniformScaleOnly(enabled: boolean): void;
     /**
      * 设置 Gizmo 目标对象
      */

package/dist/interaction/HotspotManager.d.ts

@@ -10,6 +10,15 @@ import { OrbitControls } from "../core/OrbitControls";
 import { MeshRenderer } from "../mesh/MeshRenderer";
 import type { IGSSplatRenderer } from "../gs/IGSSplatRenderer";
 import type { Vec3Tuple } from "../types";
+/** 热点标签位置 */
+export type HotspotLabelPosition = 'top' | 'left' | 'right';
+/** 热点标签配置 */
+export interface HotspotLabelConfig {
+    text: string;
+    position: HotspotLabelPosition;
+    fontSize: number;
+    visible: boolean;
+}
 /** 热点信息 */
 export interface HotspotInfo {
     position: Vec3Tuple;
@@ -24,6 +33,10 @@ export interface HotspotInfo {
     placedNormalOffset: number;
     /** 放置时的本地中心偏移 (本地空间) */
     placedLocalCenter: Vec3Tuple;
+    /** 文字标签配置 */
+    label?: HotspotLabelConfig;
+    /** 标签 DOM 元素（内部使用） */
+    _labelElement?: HTMLDivElement;
 }
 /**
  * HotspotManager
@@ -58,6 +71,9 @@ export declare class HotspotManager {
     private lastNormal;
     private indicatorBaseRadius;
     private pickRadiusPx;
+    private labelContainer;
+    private onHotspotClicked;
+    private hotspotHitRadius;
     private onHotspotPlaced;
     private onModeChanged;
     constructor(renderer: Renderer, camera: Camera, canvas: HTMLCanvasElement, controls: OrbitControls, meshRenderer: MeshRenderer);
@@ -69,6 +85,41 @@ export declare class HotspotManager {
     getHotspots(): HotspotInfo[];
     setOnHotspotPlaced(cb: ((info: HotspotInfo) => void) | null): void;
     setOnModeChanged(cb: ((active: boolean) => void) | null): void;
+    private initLabelContainer;
+    /**
+     * 设置热点标签
+     */
+    setHotspotLabel(hotspotIndex: number, text: string, position?: HotspotLabelPosition, fontSize?: number, visible?: boolean): boolean;
+    /**
+     * 设置热点标签可见性
+     */
+    setHotspotLabelVisible(hotspotIndex: number, visible: boolean): boolean;
+    /**
+     * 获取热点标签配置
+     */
+    getHotspotLabel(hotspotIndex: number): HotspotLabelConfig | null;
+    private ensureLabelElement;
+    private applyLabelStyle;
+    /**
+     * 每帧更新所有标签的屏幕位置
+     */
+    updateLabels(): void;
+    /**
+     * 设置热点点击回调
+     */
+    setOnHotspotClicked(cb: ((hotspotIndex: number, info: HotspotInfo) => void) | null): void;
+    private _clickListenerBound;
+    private _boundOnCanvasClick;
+    private _onCanvasClick;
+    /**
+     * 检测给定屏幕坐标命中了哪个热点
+     * @returns 热点索引，-1 表示未命中
+     */
+    hitTestHotspot(clientX: number, clientY: number): number;
+    /**
+     * 设置热点点击命中半径（NDC 空间，默认 0.05）
+     */
+    setHotspotHitRadius(radius: number): void;
     private pickPixelX;
     private pickPixelY;
     private lastClientX;
@@ -130,6 +181,12 @@ export declare class HotspotManager {
      * 通过 overlay mesh 起始索引找到对应的热点索引
      */
     findHotspotIndexByMeshStart(overlayMeshStartIndex: number): number;
+    /**
+     * 在指定位置和法线方向程序化放置一个热点（用于从保存数据恢复）。
+     * 逻辑与交互放置一致：加载 OBJ → 计算朝向矩阵 → addOverlayMesh → 注册到内部列表。
+     * @returns 放置后的 HotspotInfo，失败返回 null
+     */
+    placeHotspotAt(objUrl: string, position: Vec3Tuple, normal: Vec3Tuple, visualDiameter?: number, normalOffset?: number, overrideScale?: number): Promise<HotspotInfo | null>;
     /**
      * 每帧调用：更新所有 billboard 热点朝向相机
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d5techs/3dgs-lib",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "可扩展的 WebGPU 3D 渲染引擎",
   "type": "module",
   "main": "./dist/3dgs-lib.cjs",