@d5techs/3dgs-lib 1.1.3 → 1.3.0

package/dist/App.d.ts

@@ -23,6 +23,8 @@ import type { HotspotInfo } 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
@@ -43,6 +45,7 @@ export declare class App {
     private sceneManager;
     private gizmoManager;
     private hotspotManager;
+    private sceneAids;
     private isRunning;
     private animationId;
     private useMobileRenderer;
@@ -62,8 +65,12 @@ 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 文件
      */
@@ -156,6 +163,11 @@ export declare class App {
     getOverlayMeshByIndex(index: number): import("./mesh/Mesh").Mesh | null;
     private fetchWithProgress;
     private parsePLYBuffer;
+    setGridVisible(visible: boolean): void;
+    getGridVisible(): boolean;
+    setAxesVisible(visible: boolean): void;
+    getAxesVisible(): boolean;
+    getSceneAidsRenderer(): SceneAidsRenderer;
     /**
      * 销毁应用及所有资源
      */

package/dist/core/SceneAidsRenderer.d.ts

@@ -0,0 +1,32 @@
+import { Renderer } from "./Renderer";
+import { Camera } from "./Camera";
+/**
+ * SceneAidsRenderer - 场景辅助渲染器
+ * 渲染无限网格（XZ 平面）和世界坐标轴（RGB = XYZ）
+ */
+export declare class SceneAidsRenderer {
+    private renderer;
+    private camera;
+    private _gridVisible;
+    private _axesVisible;
+    private gridPipeline;
+    private gridUniformBuffer;
+    private gridBindGroup;
+    private axesPipeline;
+    private axesUniformBuffer;
+    private axesBindGroup;
+    private axesVertexBuffer;
+    constructor(renderer: Renderer, camera: Camera);
+    private createGridPipeline;
+    private createAxesPipeline;
+    private createAxesVertexBuffer;
+    get gridVisible(): boolean;
+    set gridVisible(v: boolean);
+    get axesVisible(): boolean;
+    set axesVisible(v: boolean);
+    render(pass: GPURenderPassEncoder): void;
+    private renderGrid;
+    private renderAxes;
+    private invertMatrix4;
+    destroy(): void;
+}

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

@@ -10,6 +10,7 @@ export { Camera } from './core/Camera';
 export { OrbitControls } from './core/OrbitControls';
 export { ViewportGizmo } from './core/gizmo/ViewportGizmo';
 export { BoundingBoxRenderer } from './core/BoundingBoxRenderer';
+export { SceneAidsRenderer } from './core/SceneAidsRenderer';
 export { Mesh } from './mesh/Mesh';
 export { MeshRenderer } from './mesh/MeshRenderer';
 export { GLBLoader } from './loaders/GLBLoader';
@@ -21,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';

package/package.json

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