@d5techs/3dgs-lib 1.4.14 → 1.4.15

package/dist/App.d.ts

@@ -30,7 +30,31 @@ import type { CoordinateSystem } from "./gs/PLYLoaderMobile";
  * @param progress 进度值 0-100
  * @param stage 当前阶段: 'download' | 'parse' | 'upload'
  */
-export type ProgressCallback = (progress: number, stage: 'download' | 'parse' | 'upload') => void;
+export type ProgressCallback = (progress: number, stage: "download" | "parse" | "upload") => void;
+/**
+ * 自适应性能配置
+ * 当相机靠近模型时自动降低渲染负载，远离时恢复全质量
+ */
+export interface AdaptivePerformanceConfig {
+    /** 远距离阈值（倍率 × boundingBox.radius），超过此距离使用全质量 */
+    farThreshold: number;
+    /** 近距离阈值（倍率 × boundingBox.radius），低于此距离使用最大优化 */
+    nearThreshold: number;
+    /** 最近距离时的渲染分辨率缩放 (0.25~1.0) */
+    minRenderScale: number;
+    /** 最近距离时的亚像素剔除阈值 (越高剔除越多) */
+    maxPixelThreshold: number;
+    /** 远距离时的亚像素剔除阈值 */
+    minPixelThreshold: number;
+    /** 最近距离时的可见 splat 比例上限 (0~1, 0=不限制) */
+    nearVisibleRatio: number;
+    /** 远距离时是否完全取消可见数量限制 */
+    farUnlimited: boolean;
+    /** 是否启用深度范围限制（近似 transmittance cutoff） */
+    enableDepthRangeLimit: boolean;
+    /** 近距离时深度范围限制倍率（× boundingBox.radius），越小剔除后方越多 */
+    nearDepthRangeRatio: number;
+}
 /**
  * App - 统一调度入口
  */
@@ -50,12 +74,26 @@ export declare class App {
     private animationId;
     private useMobileRenderer;
     private lastCompactData;
+    private adaptivePerformanceEnabled;
+    private adaptiveConfig;
+    private lastAppliedRenderScale;
+    private baseRenderScale;
     private boundOnResize;
     constructor(canvas: HTMLCanvasElement);
     /**
      * 初始化应用
      */
     init(): Promise<void>;
+    /**
+     * Apple GPU (M1/M2/M3 等) 自动优化配置
+     * TBDR 架构特点：片段着色器开销高、带宽敏感、compute pass 较慢
+     * 策略：降低 SH 等级、更积极的自适应参数、禁用无效深度写入
+     */
+    private applyAppleGPUDefaults;
+    /**
+     * 创建桌面端 GSSplatRenderer 并自动应用平台优化
+     */
+    private createDesktopGSRenderer;
     /**
      * 加载 GLB 文件
      */
@@ -103,6 +141,7 @@ export declare class App {
      */
     stop(): void;
     private animate;
+    private updateAdaptivePerformance;
     private render;
     private onResize;
     getMeshCount(): number;
@@ -161,8 +200,8 @@ export declare class App {
     getGSRenderer(): GSSplatRenderer | undefined;
     getGSRendererMobile(): GSSplatRendererMobile | undefined;
     isUsingMobileRenderer(): boolean;
-    getLastCompactData(): import('./gs/PLYLoaderMobile').CompactSplatData | null;
-    setLastCompactData(data: import('./gs/PLYLoaderMobile').CompactSplatData): void;
+    getLastCompactData(): import("./gs/PLYLoaderMobile").CompactSplatData | null;
+    setLastCompactData(data: import("./gs/PLYLoaderMobile").CompactSplatData): void;
     getHotspotManager(): HotspotManager;
     enterHotspotMode(objUrl: string): void;
     exitHotspotMode(): void;
@@ -234,6 +273,24 @@ export declare class App {
      * 降低排序频率可提升帧率，代价是移动时短暂排序瑕疵
      */
     setSortFrequency(frequency: number): void;
+    /**
+     * 是否检测到 Apple GPU（M1/M2/M3 等）
+     */
+    get isAppleGPU(): boolean;
+    /**
+     * 启用/禁用自适应性能优化
+     * 开启后系统会根据相机与模型的距离自动调节：
+     * - 渲染分辨率（renderScale）
+     * - 亚像素剔除阈值（pixelThreshold）
+     * - 最大可见 splat 数量（maxVisibleSplats）
+     */
+    setAdaptivePerformance(enabled: boolean): void;
+    getAdaptivePerformance(): boolean;
+    /**
+     * 设置自适应性能配置参数
+     */
+    setAdaptivePerformanceConfig(config: Partial<AdaptivePerformanceConfig>): void;
+    getAdaptivePerformanceConfig(): AdaptivePerformanceConfig;
     /**
      * 销毁应用及所有资源
      */

package/dist/core/Camera.d.ts

@@ -27,7 +27,7 @@ export declare class Camera {
      */
     private updateViewMatrix;
     /**
-     * 计算投影矩阵 (透视投影)
+     * 计算投影矩阵 (透视投影, OpenGL [-1,1] 深度)
      */
     private updateProjectionMatrix;
     private subtract;

package/dist/core/OrbitControls.d.ts

@@ -29,6 +29,8 @@ export declare class OrbitControls {
     private velocityPanX;
     private velocityPanY;
     private velocityPanZ;
+    moveSpeed: number;
+    private pressedKeys;
     private touchMode;
     private lastTouchDistance;
     private lastTouchCenter;
@@ -37,6 +39,9 @@ export declare class OrbitControls {
     private boundOnMouseMove;
     private boundOnMouseUp;
     private boundOnWheel;
+    private boundOnDblClick;
+    private boundOnKeyDown;
+    private boundOnKeyUp;
     private boundOnTouchStart;
     private boundOnTouchMove;
     private boundOnTouchEnd;
@@ -57,6 +62,13 @@ export declare class OrbitControls {
     private onMouseMove;
     private onMouseUp;
     private onWheel;
+    /** 移动键 */
+    private static MOVE_KEYS;
+    private onKeyDown;
+    private onKeyUp;
+    private applyKeyboardMovement;
+    private onDblClick;
+    private animateToTarget;
     private onTouchStart;
     private onTouchMove;
     private onTouchEnd;

package/dist/core/Renderer.d.ts

@@ -17,6 +17,9 @@ export declare class Renderer {
     private _lastCSSWidth;
     private _lastCSSHeight;
     private _clearColor;
+    private _isAppleGPU;
+    private _gpuVendor;
+    private _gpuArchitecture;
     constructor(canvas: HTMLCanvasElement);
     /**
      * 设置背景颜色
@@ -34,6 +37,9 @@ export declare class Renderer {
     get context(): GPUCanvasContext;
     get format(): GPUTextureFormat;
     get depthFormat(): GPUTextureFormat;
+    get isAppleGPU(): boolean;
+    get gpuVendor(): string;
+    get gpuArchitecture(): string;
     /**
      * 获取渲染宽度（像素）
      */

package/dist/editor/SplatEditor.d.ts

@@ -68,6 +68,19 @@ export declare class SplatEditor {
     private selectByRect;
     private selectByMask;
     private selectByColor;
+    /**
+     * 球选择：以点击处最近 splat 为中心，拖拽半径定义世界空间球体
+     */
+    private selectBySphere;
+    /**
+     * 盒选择：以点击处最近 splat 为中心，拖拽定义世界空间 AABB
+     * X/Y 半宽由屏幕拖拽距离转换，Z 半深度取 max(halfW, halfH)
+     */
+    private selectByBox;
+    /**
+     * 根据屏幕像素坐标，找到最近的可见 splat 并返回其世界坐标及深度换算系数
+     */
+    private pickWorldPosition;
     /**
      * 每帧调用，标记投影需要更新
      */

package/dist/editor/tools/BoxSelection.d.ts

@@ -0,0 +1,24 @@
+import type { Tool } from './ToolManager';
+export declare class BoxSelection implements Tool {
+    private parent;
+    private svg;
+    private rect;
+    private crossV;
+    private crossH;
+    private onSelect;
+    private center;
+    private halfW;
+    private halfH;
+    private dragId;
+    constructor(parent: HTMLElement, onSelect: (op: 'add' | 'remove' | 'set', centerPx: {
+        x: number;
+        y: number;
+    }, halfW: number, halfH: number) => void);
+    activate(): void;
+    deactivate(): void;
+    private updateVisuals;
+    private pointerdown;
+    private pointermove;
+    private dragEnd;
+    private pointerup;
+}

package/dist/editor/tools/SphereSelection.d.ts

@@ -0,0 +1,21 @@
+import type { Tool } from './ToolManager';
+export declare class SphereSelection implements Tool {
+    private parent;
+    private svg;
+    private circle;
+    private onSelect;
+    private center;
+    private radiusPx;
+    private dragId;
+    constructor(parent: HTMLElement, onSelect: (op: 'add' | 'remove' | 'set', centerPx: {
+        x: number;
+        y: number;
+    }, radiusPx: number) => void);
+    activate(): void;
+    deactivate(): void;
+    private updateCircle;
+    private pointerdown;
+    private pointermove;
+    private dragEnd;
+    private pointerup;
+}

package/dist/gs/GSSplatRenderer.d.ts

@@ -30,6 +30,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private sorter;
     private shMode;
     private boundingBox;
+    private uniformData;
     private cpuPositions;
     private position;
     private rotation;
@@ -38,6 +39,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private modelMatrix;
     private pixelCullThreshold;
     private maxVisibleSplats;
+    private depthRangeLimit;
     private lastSortViewMatrix;
     private lastSortProjMatrix;
     private lastSortModelMatrix;
@@ -45,6 +47,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private lastSortHeight;
     private lastSortPixelThreshold;
     private lastSortMaxVisible;
+    private lastSortDepthRange;
     private sortStateInitialized;
     private sortFrequency;
     private frameCounter;
@@ -53,6 +56,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private editorBindGroupLayout;
     private editorBindGroup;
     private editorEnabled;
+    private depthWriteEnabled;
     private depthNormalPipeline;
     private depthRT;
     private depthRTView;
@@ -63,6 +67,7 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
     private dnResult;
     constructor(renderer: Renderer, camera: Camera);
     private createPipeline;
+    setDepthWriteEnabled(enabled: boolean): void;
     private createUniformBuffer;
     private createDepthNormalPipeline;
     private ensureDepthNormalTextures;
@@ -86,6 +91,14 @@ export declare class GSSplatRenderer implements IGSSplatRendererWithCapabilities
      */
     setMaxVisibleSplats(count: number): void;
     getMaxVisibleSplats(): number;
+    /**
+     * 设置深度范围限制（view-space 距离）
+     * 只渲染距相机此距离范围内的 splat，超出部分被剔除
+     * 近似 transmittance cutoff：近距离时大量 splat 堆叠在后方但被前方遮挡
+     * 0 = 不限制
+     */
+    setDepthRangeLimit(limit: number): void;
+    getDepthRangeLimit(): number;
     /**
      * 设置排序频率
      * 1 = 每帧排序（默认），2 = 每 2 帧排序一次，以此类推

package/dist/gs/GSSplatSorter.d.ts

@@ -25,6 +25,8 @@ export interface CullingOptions {
     frustumDilation?: number;
     /** 最大可见 splat 数量（排序后截断），0 = 不限制 */
     maxVisibleCount?: number;
+    /** 深度范围限制（view-space 距离），超过此深度的 splat 被剔除，0 = 不限制 */
+    depthRangeLimit?: number;
 }
 /**
  * 排序器配置选项

package/dist/index.d.ts

@@ -53,4 +53,4 @@ export { ToolManager } from './editor/tools/ToolManager';
 export type { Tool } from './editor/tools/ToolManager';
 export { exportEditedPLY } from './editor/SplatExporter';
 export { App } from './App';
-export type { ProgressCallback } from './App';
+export type { ProgressCallback, AdaptivePerformanceConfig } from './App';

package/package.json

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