@fengyizhi/scene-lib 1.0.2 → 1.0.4

package/index.d.ts

@@ -379,6 +379,14 @@ interface EnvironmentConfig {
         ceilingUseBaseColor?: boolean;
     };
 }
+/** 实例化组（InstancedMesh 优化） */
+interface InstanceGroup {
+    id: string;
+    /** 资产 ID（同组的节点必须共享同一 assetId） */
+    assetId: string;
+    /** 参与实例化的节点 ID 列表 */
+    nodeIds: string[];
+}
 interface SceneDoc {
     schemaVersion: 3;
     /** 场景 ID（服务器分配） */
@@ -396,6 +404,8 @@ interface SceneDoc {
     dashboard?: DashboardConfig;
     /** 告警配置 */
     alarm?: AlarmConfig;
+    /** 实例化组（性能优化） */
+    instanceGroups?: InstanceGroup[];
 }
 /** 场景元数据（列表用，不包含完整 SceneDoc） */
 interface SceneMeta {
@@ -403,6 +413,10 @@ interface SceneMeta {
     name: string;
     createdAt: number;
     updatedAt: number;
+    /** 创建者用户 ID */
+    ownerId: string;
+    /** 是否为模板场景 */
+    isTemplate?: boolean;
 }
 declare function nextId(prefix?: string): string;
 declare function createNode(primitive: PrimitiveKind, name: string): NodeDoc;
@@ -477,6 +491,18 @@ declare class AddNodeCommand implements Command {
     do(store: SceneStore): void;
     undo(store: SceneStore): void;
 }
+/** 批量添加节点（用于复制操作，一次撤销全部） */
+declare class BatchAddCommand implements Command {
+    readonly label: string;
+    private nodes;
+    private parentIds;
+    constructor(items: {
+        node: NodeDoc;
+        parentId: string | null;
+    }[]);
+    do(store: SceneStore): void;
+    undo(store: SceneStore): void;
+}
 declare class RemoveNodeCommand implements Command {
     private readonly id;
     readonly label = "\u5220\u9664\u8282\u70B9";
@@ -503,6 +529,7 @@ declare class GroupCommand implements Command {
     private originalParents;
     private originalPositions;
     private removedEmptyGroups;
+    private commonParentId;
     constructor(selectedIds: string[]);
     do(store: SceneStore): void;
     undo(store: SceneStore): void;
@@ -514,6 +541,10 @@ declare class UngroupCommand implements Command {
     private children;
     private groupParentId;
     private groupName;
+    /** 记录 group 的变换（用于 undo 恢复） */
+    private groupTransform;
+    /** 记录子节点在 group 内的原始位置（用于 undo 恢复） */
+    private originalChildPositions;
     constructor(groupId: string);
     do(store: SceneStore): void;
     undo(store: SceneStore): void;
@@ -558,13 +589,17 @@ declare class SetAlarmCommand implements Command {
     do(store: SceneStore): void;
     undo(store: SceneStore): void;
 }
-/** 拖动节点改变父节点 */
+/** 拖动节点改变父节点（保持世界坐标不变） */
 declare class ReparentCommand implements Command {
     private readonly nodeId;
     private readonly newParentId;
     readonly label = "\u79FB\u52A8\u8282\u70B9";
     private oldParentId;
     private oldIndex;
+    /** 记录旧位置（用于 undo 恢复） */
+    private oldPosition;
+    private oldRotation;
+    private oldScale;
     constructor(nodeId: string, newParentId: string | null);
     do(store: SceneStore): void;
     undo(store: SceneStore): void;
@@ -764,6 +799,36 @@ declare class MovePathPointToEndCommand implements Command {
     do(store: SceneStore): void;
     undo(store: SceneStore): void;
 }
+/** 对齐命令：将多个节点对齐到指定轴向的指定位置 */
+declare class AlignCommand implements Command {
+    private readonly nodeIds;
+    private readonly axis;
+    private readonly position;
+    private readonly targetPositions;
+    readonly label: string;
+    private beforePositions;
+    constructor(nodeIds: string[], axis: 'x' | 'y' | 'z', position: 'min' | 'center' | 'max', targetPositions: Map<string, [number, number, number]>);
+    do(store: SceneStore): void;
+    undo(store: SceneStore): void;
+}
+/** 启用实例化渲染 */
+declare class EnableInstancingCommand implements Command {
+    private readonly nodeIds;
+    readonly label = "\u542F\u7528\u5B9E\u4F8B\u5316\u6E32\u67D3";
+    private groupId;
+    constructor(nodeIds: string[]);
+    do(store: SceneStore): void;
+    undo(store: SceneStore): void;
+}
+/** 禁用实例化渲染 */
+declare class DisableInstancingCommand implements Command {
+    private readonly nodeIds;
+    readonly label = "\u7981\u7528\u5B9E\u4F8B\u5316\u6E32\u67D3";
+    private removedGroup;
+    constructor(nodeIds: string[]);
+    do(store: SceneStore): void;
+    undo(store: SceneStore): void;
+}
 
 type TransformMode = 'translate' | 'rotate' | 'scale';
 interface PickEvent {
@@ -776,6 +841,8 @@ interface ViewerCallbacks {
     onTransformEnd(id: string, before: TransformState, after: TransformState): void;
     /** 资产加载完成后生成缩略图 */
     onThumbnailGenerated?(assetId: string, dataUrl: string): void;
+    /** 相机视角变化 */
+    onCameraChange?(): void;
     /** 路径点移动 */
     onPathPointMoved?(nodeId: string, effectIndex: number, pointIndex: number, newPosition: Vec3): void;
     /** 添加路径点 */
@@ -817,6 +884,12 @@ declare class SceneViewer {
     private pendingAssetNodes;
     /** 动画基础变换（nodeId → 数据模型原始变换） */
     private animBases;
+    /** FPS 统计 */
+    private fpsFrames;
+    private fpsTime;
+    private fpsCurrent;
+    /** 场景统计缓存 */
+    private statsCache;
     /** 缩略图渲染器（离屏） */
     private thumbRenderer?;
     private thumbScene;
@@ -827,6 +900,10 @@ declare class SceneViewer {
     private lastFrameTime;
     /** 拖拽中冻结动画 */
     private animationFrozen;
+    /** 性能模式：true 时使用 renderer（无后处理），false 时使用 composer（有后处理） */
+    private performanceMode;
+    /** 顶层节点集合（没有父节点的节点，用于视锥剔除优化） */
+    private topLevelNodes;
     /** 相机是否已从文档恢复（只在首次 sync 时恢复一次） */
     private cameraRestored;
     /** 保存原始材质参数（覆盖前），用于撤销覆盖时恢复 */
@@ -837,6 +914,8 @@ declare class SceneViewer {
     private textureCache;
     /** 标签对象缓存（nodeId → label mesh） */
     private labelObjects;
+    /** 实例化网格缓存（groupId → InstancedMesh 数组） */
+    private instanceMeshes;
     private textureLoader;
     /** HDRI 环境贴图缓存 */
     private hdriTexture;
@@ -908,6 +987,8 @@ declare class SceneViewer {
     private pathEditor;
     /** 是否为编辑器模式（编辑器模式下动画默认播放，不依赖数据） */
     private isEditorMode;
+    /** 相机视角变化回调 */
+    onCameraChange?: () => void;
     constructor(host: HTMLElement, store: SceneStore, cb: ViewerCallbacks, dashboardOverlayEl?: HTMLDivElement, isEditorMode?: boolean);
     setMode(mode: TransformMode): void;
     /** 设置路径编辑的活动效果 */
@@ -916,7 +997,7 @@ declare class SceneViewer {
     isPathEditing(): boolean;
     /** 设置路径编辑控制点大小 */
     setPathHandleSize(size: number): void;
-    /** 将当前相机状态写入 SceneDoc（保存前调用） */
+    /** 将当前相机状态写入 SceneDoc（保存前调用，不触发 notifyChanged） */
     saveCamera(): void;
     /** 从 SceneDoc 恢复相机位置 */
     private restoreCamera;
@@ -926,6 +1007,14 @@ declare class SceneViewer {
     sync(): void;
     /** 强制恢复相机（草稿恢复后调用） */
     forceRestoreCamera(): void;
+    /** 同步实例化组：创建/更新 InstancedMesh */
+    private syncInstanceGroups;
+    /** 设置性能模式 */
+    setPerformanceMode(enabled: boolean): void;
+    /** 更新顶层节点集合（没有父节点的节点） */
+    private updateTopLevelNodes;
+    /** 视锥剔除：隐藏不在相机视锥内的顶层节点，大幅减少 CPU 遍历开销 */
+    private updateFrustumCulling;
     /** 创建标签 mesh */
     private createLabel;
     /** 应用场景环境配置（背景色、半球光、平行光、HDRI） */
@@ -1045,6 +1134,14 @@ declare class SceneViewer {
     private updateEffects;
     dispose(): void;
     private createMesh;
+    /**
+     * 参考 JCISceneParser 的 GdeepCloneMaterials
+     * 几何体共享（不 clone），材质独立克隆
+     * - Object3D/Group：clone(false) 不递归，手动处理 children
+     * - Mesh：共享 geometry，克隆 material
+     * - Light：完整克隆
+     */
+    private gdeepCloneMaterials;
     /** 判断对象是否为灯光 */
     private isLight;
     /** 根据节点数据创建灯光对象 */
@@ -1101,6 +1198,8 @@ declare class SceneViewer {
     private refreshSelection;
     /** 根据 Box3 创建包围盒的几何体 */
     private createBoxGeometry;
+    /** 用局部坐标 min/max 创建包围盒几何体 */
+    private createBoxGeometryFromMinMax;
     /** 计算 group 的所有后代的包围盒（本地空间，相对于组的 Object3D） */
     private computeGroupLocalBounds;
     /** 计算 group 的所有后代的包围盒（世界空间） */
@@ -1117,6 +1216,27 @@ declare class SceneViewer {
     private resize;
     /** 屏幕坐标 → 地面（y=0）世界坐标 */
     screenToGround(viewportX: number, viewportY: number): Vec3 | null;
+    /** 获取当前 FPS */
+    getFps(): number;
+    /** 标记场景统计过期（模型加载/删除后调用） */
+    markStatsDirty(): void;
+    /** 获取场景顶点数和三角面数（带缓存，只统计根节点避免重复） */
+    getSceneStats(): {
+        vertices: number;
+        faces: number;
+        drawCalls: number;
+    };
+    /** 获取指定节点的顶点数、面数、DrawCalls */
+    getNodeStats(nodeIds: string[]): {
+        vertices: number;
+        faces: number;
+        drawCalls: number;
+    };
+    /** 获取节点的世界空间包围盒 */
+    getObjectBoundingBox(nodeId: string): {
+        min: [number, number, number];
+        max: [number, number, number];
+    } | null;
 }
 
 /**
@@ -1148,6 +1268,7 @@ declare class SceneViewComponent implements AfterViewInit, OnChanges, OnDestroy
         assetId: string;
         dataUrl: string;
     }>;
+    cameraChange: EventEmitter<void>;
     pathPointMoved: EventEmitter<{
         nodeId: string;
         effectIndex: number;
@@ -1271,14 +1392,31 @@ declare class SceneViewComponent implements AfterViewInit, OnChanges, OnDestroy
     showAlarm(nodeId: string, data: any): void;
     /** 隐藏告警弹框 */
     hideAlarm(nodeId: string): void;
+    /** 设置性能模式 */
+    setPerformanceMode(enabled: boolean): void;
     /** 拖拽悬停：允许放置 */
     onDragOver(e: DragEvent): void;
     /** 拖拽放置：解析资产信息并发射事件 */
     onDrop(e: DragEvent): void;
     /** 获取 viewer 实例（供外部调用高级功能如告警弹窗） */
     getViewer(): SceneViewer | null;
+    getFps(): number;
+    getSceneStats(): {
+        vertices: number;
+        faces: number;
+        drawCalls: number;
+    };
+    getNodeStats(nodeIds: string[]): {
+        vertices: number;
+        faces: number;
+        drawCalls: number;
+    };
+    getObjectBoundingBox(nodeId: string): {
+        min: [number, number, number];
+        max: [number, number, number];
+    } | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<SceneViewComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<SceneViewComponent, "twin-scene-view", never, { "store": { "alias": "store"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "isEditorMode": { "alias": "isEditorMode"; "required": false; }; }, { "select": "select"; "transformEnd": "transformEnd"; "dropAsset": "dropAsset"; "thumbnailGenerated": "thumbnailGenerated"; "pathPointMoved": "pathPointMoved"; "addPathPoint": "addPathPoint"; "deletePathPoint": "deletePathPoint"; "pathEditingChanged": "pathEditingChanged"; "pathPointRightClick": "pathPointRightClick"; "segmentRightClick": "segmentRightClick"; "modelSurfaceClick": "modelSurfaceClick"; "movePathPointToEnd": "movePathPointToEnd"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SceneViewComponent, "twin-scene-view", never, { "store": { "alias": "store"; "required": false; }; "mode": { "alias": "mode"; "required": false; }; "isEditorMode": { "alias": "isEditorMode"; "required": false; }; }, { "select": "select"; "transformEnd": "transformEnd"; "dropAsset": "dropAsset"; "thumbnailGenerated": "thumbnailGenerated"; "cameraChange": "cameraChange"; "pathPointMoved": "pathPointMoved"; "addPathPoint": "addPathPoint"; "deletePathPoint": "deletePathPoint"; "pathEditingChanged": "pathEditingChanged"; "pathPointRightClick": "pathPointRightClick"; "segmentRightClick": "segmentRightClick"; "modelSurfaceClick": "modelSurfaceClick"; "movePathPointToEnd": "movePathPointToEnd"; }, never, never, true, never>;
 }
 
 /**
@@ -1531,5 +1669,5 @@ declare const DRACO_DECODER_PATH = "assets/draco/gltf/";
 /** Draco 编码器路径（打包进 npm 包） */
 declare const DRACO_ENCODER_PATH = "assets/draco/encoder/";
 
-export { AddAnimationCommand, AddEffectCommand, AddNodeCommand, BatchRemoveCommand, DRACO_DECODER_PATH, DRACO_ENCODER_PATH, FlyPathCommand, GroupCommand, History, InsertPathPointCommand, KeyframeCommand, MaterialOverrideCommand, MovePathPointToEndCommand, ParticleRuntime, PathEditor, PathParticleRuntime, RemoveAnimationCommand, RemoveEffectCommand, RemoveNodeCommand, RemovePathPointCommand, ReparentCommand, SceneStore, SceneViewComponent, SceneViewer, SegmentedPath, SetAlarmCommand, SetDashboardCommand, SetEnvironmentCommand, SetLightPropertyCommand, SetNodeNameCommand, SetNodeTextCommand, SyncMaterialCommand, ToggleSegmentTypeCommand, TransformCommand, UngroupCommand, UpdateAnimationCommand, UpdateEffectCommand, UpdatePathPointsCommand, clone, createNode, createSceneDoc, nextId };
-export type { AlarmConfig, AlarmPopupData, AnimationRule, CameraDoc, CameraKeyframe, Command, DashboardConfig, DashboardDataPoint, DashboardWidget, EnvironmentConfig, FlyPath, MaterialOverride, NodeDoc, ParticleEffect, PathEditorCallbacks, PathParticleEffect, PickEvent, PrimitiveKind, SceneDoc, SceneMeta, ScreenContentEffect, TransformMode, TransformState, UvAnimationEffect, Vec3, ViewerCallbacks, VisualEffect, VisualEffectBase, VisualEffectKind };
+export { AddAnimationCommand, AddEffectCommand, AddNodeCommand, AlignCommand, BatchAddCommand, BatchRemoveCommand, DRACO_DECODER_PATH, DRACO_ENCODER_PATH, DisableInstancingCommand, EnableInstancingCommand, FlyPathCommand, GroupCommand, History, InsertPathPointCommand, KeyframeCommand, MaterialOverrideCommand, MovePathPointToEndCommand, ParticleRuntime, PathEditor, PathParticleRuntime, RemoveAnimationCommand, RemoveEffectCommand, RemoveNodeCommand, RemovePathPointCommand, ReparentCommand, SceneStore, SceneViewComponent, SceneViewer, SegmentedPath, SetAlarmCommand, SetDashboardCommand, SetEnvironmentCommand, SetLightPropertyCommand, SetNodeNameCommand, SetNodeTextCommand, SyncMaterialCommand, ToggleSegmentTypeCommand, TransformCommand, UngroupCommand, UpdateAnimationCommand, UpdateEffectCommand, UpdatePathPointsCommand, clone, createNode, createSceneDoc, nextId };
+export type { AlarmConfig, AlarmPopupData, AnimationRule, CameraDoc, CameraKeyframe, Command, DashboardConfig, DashboardDataPoint, DashboardWidget, EnvironmentConfig, FlyPath, InstanceGroup, MaterialOverride, NodeDoc, ParticleEffect, PathEditorCallbacks, PathParticleEffect, PickEvent, PrimitiveKind, SceneDoc, SceneMeta, ScreenContentEffect, TransformMode, TransformState, UvAnimationEffect, Vec3, ViewerCallbacks, VisualEffect, VisualEffectBase, VisualEffectKind };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fengyizhi/scene-lib",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "peerDependencies": {
     "@angular/common": ">=16.0.0",
     "@angular/core": ">=16.0.0",