next-flow-interface 0.26.16 → 0.26.18

package/index.d.ts

@@ -4979,11 +4979,38 @@ export declare class RsNodeService {
   /**
    * 生成节点指纹
    *
-   * 根据节点的多种属性生成唯一指纹，用于区分同名节点。
-   * 包含：位置、旋转、缩放、子节点数量、Mesh 顶点等信息。
+   * 根据节点的多种几何属性生成唯一指纹字符串，用于区分同名节点。
+   * 指纹包含节点的空间变换信息和网格几何特征。
+   *
+   * ## 指纹组成
+   *
+   * | 前缀 | 含义 | 适用类型 |
+   * |------|------|----------|
+   * | C | 子节点数量 | 所有 Node |
+   * | P | 位置 (position) | TransformNode 及子类 |
+   * | R | 旋转 (rotation) | TransformNode 及子类 |
+   * | S | 缩放 (scaling) | TransformNode 及子类 |
+   * | V | 顶点数量 | Mesh |
+   * | I | 索引数量（面数×3） | Mesh |
+   * | B | 包围盒 min/max | Mesh |
+   * | D | 采样顶点坐标 | Mesh |
+   *
+   * ## 采样策略
+   *
+   * 对于 Mesh 节点，会采样 3.33%、50%、96.67% 位置的顶点坐标，
+   * 以较小的数据量捕获网格的几何特征。
    *
    * @param node - Babylon.js 节点对象
-   * @returns 指纹字符串
+   * @returns 指纹字符串，格式如 `C2P10000200003000R00000000000000S10000100001000V1234I5678B...D...`
+   *
+   * @example
+   * ```typescript
+   * const fingerprint = RsNodeService.instance.generateFingerprint(meshNode)
+   * // fingerprint = "C0P10000200003000R00000000000000S10000100001000V1024I3072B..."
+   * ```
+   *
+   * @see {@link matchOriginalNodes} 使用指纹进行节点匹配
+   * @see {@link rescueGenerateSceneNode} 生成场景时调用此方法
    */
   generateFingerprint(node: Node_2): string;
   /**
@@ -5065,31 +5092,35 @@ export declare class RsNodeService {
    */
   getMidByNid(nid: string): string | null;
   /**
-   * 分析指定mid的模型加载内部所有节点
+   * 分析并加载指定模型的所有节点映射
    *
-   * 从 RvSceneService 中获取所有来自该 mid 的 RvSceneNode，
-   * 并将 root 及其内部的所有节点与 RvSceneNode 对应上，调用 addNodePair 完成加载。
-   * 支持复制节点：带有 source.copy 的节点会从源节点 clone。
+   * 当模型文件加载完成后调用此方法，将 RhineVar 协同数据中的 RvSceneNode
+   * 与 Babylon.js 场景中的实际节点建立映射关系。
    *
-   * @param mid - 模型的 mid
-   * @param root - 该模型的根节点
-   */
-  analyzeSceneNode(mid: string, root: Node_2): void;
-  /**
-   * 匹配原始节点（非复制节点）
+   * 执行流程：
+   * 1. 从 RvSceneService 获取所有 source.mid 为该 mid 的原始节点（非复制节点）
+   * 2. 调用 matchOriginalNodes 将协同数据节点与 Babylon 节点进行匹配
+   * 3. 匹配成功后通过 addNodePair 建立 nid 到 Node 的映射
    *
-   * @param rvSceneNodes - 原始 RvSceneNode 列表
-   * @param root - Babylon.js 根节点
-   */
-  private matchOriginalNodes;
-  /**
-   * 处理复制节点
+   * @param mid - 模型ID，用于筛选属于该模型的 RvSceneNode
+   * @param root - 模型的 Babylon.js 根节点对象
    *
-   * 按依赖顺序处理复制节点，确保源节点已存在后再 clone。
+   * @throws {Error} 当找不到任何属于该 mid 的 RvSceneNode 时抛出异常
    *
-   * @param copyNodes - 带有 source.copy 的 RvSceneNode 列表
+   * @example
+   * ```typescript
+   * // 模型加载完成后建立节点映射
+   * const root = loadedModel.rootNode
+   * RsNodeService.instance.analyzeSceneNode('model-123', root)
+   *
+   * // 之后可以通过 nid 获取节点
+   * const node = RsNodeService.instance.getNodeByNid('model-123--L0-N0')
+   * ```
+   *
+   * @see {@link matchOriginalNodes} 内部匹配逻辑
+   * @see {@link generateSceneNode} 首次生成场景节点（与此方法互补）
    */
-  private processCopyNodes;
+  analyzeSceneNode(mid: string, root: Node_2): void;
   /**
    * 根据模型ID获取文件ID (fid)
    *
@@ -5163,7 +5194,35 @@ export declare class RsNodeService {
 export declare class RsSceneService {
   static get instance(): RsSceneService;
   private constructor();
+  /**
+   * 同步所有 Babylon 节点与 RvSceneNode 协同数据
+   *
+   * 将 Babylon.js 场景中的节点树结构与 RhineVar 协同数据中的 RvSceneNode 完全对齐。
+   *
+   * ## 同步流程
+   *
+   * 1. **创建缺失的 copy 节点**：检查所有带 `source.copy` 的 RvSceneNode，
+   *    若对应 Babylon 节点不存在则 clone 创建。按层级顺序处理，确保父节点先于子节点创建。
+   * 2. **同步 parent 关系**：检查所有节点的父子关系，修正不一致的 parent 指向。
+   * 3. **同步 deleted 状态**：将 RvSceneNode 的 `deleted` 字段同步到 Babylon 节点的 `enabled` 状态。
+   *
+   * @throws {Error} 当 copy 源节点不存在时抛出异常
+   * @throws {Error} 当 Babylon clone 操作失败时抛出异常
+   */
   syncAll(): void;
+  /**
+   * 同步单个节点的 Babylon 状态与 RvSceneNode 协同数据
+   *
+   * @param nid - 节点唯一标识符
+   * @param sceneNode - RvSceneNode 协同数据，默认从 RvSceneService 获取
+   * @param targetNode - 目标 Babylon 节点，默认从 RsNodeService 获取
+   * @param parentNode - 父 Babylon 节点，默认从 RsNodeService 获取
+   * @returns 是否发生了变更
+   *
+   * @throws {Error} 当非 copy 节点的 Babylon 节点不存在时抛出异常
+   * @throws {Error} 当 copy 源节点不存在时抛出异常
+   * @throws {Error} 当 Babylon clone 操作失败时抛出异常
+   */
   sync(
     nid: string,
     sceneNode?: RvSceneNode | null,
@@ -5506,6 +5565,7 @@ export declare enum RvBasicType {
   ICO_SPHERE = "ICO_SPHERE",
   CAPSULE = "CAPSULE",
   PLANE = "PLANE",
+  TRANSFORM_NODE = "TRANSFORM_NODE",
 }
 
 /**
@@ -6042,6 +6102,7 @@ export declare class RvModelService {
   has(mid: string): boolean;
   hasFid(fid: string): boolean;
   add(rvModel: RvModel): string;
+  addTransformNode(): string;
   remove(mid: string): boolean;
   generateId(): string;
 }
@@ -6343,10 +6404,11 @@ export declare class RvSceneService {
   isAncestor(nid: string, of: string): boolean;
   isParent(nid: string, of: string): boolean;
   isChild(nid: string, of: string): boolean;
+  newNode(fromNid?: string): void;
   move(nid: string, newParent?: string): void;
   delete(nid: string): void;
   getDescendantsWithSelf(nid: string): string[];
-  generateId(mid: string, layer: number, index: number): string;
+  generateId(mid: string, layer?: number, index?: number): string;
   generateIdAndNameForCopy(fromNid: string): {
     nid: string;
     name: string;
@@ -6465,6 +6527,7 @@ export declare class SceneService {
     offsetX: number;
     offsetY: number;
   };
+  newNode(fromNid?: string): void;
   /**
    * 批量复制
    *
@@ -6753,6 +6816,7 @@ export declare interface Status {
   PluginPreLoaded: boolean;
   FileLoaded: boolean;
   ModelLoaded: boolean;
+  SceneLoaded: boolean;
   PluginPreRendered: boolean;
   Rendered: boolean;
   Shown: boolean;
@@ -6806,6 +6870,10 @@ export declare class StatusService {
   unsubscribeModelLoaded(subscriber: StatusChangeSubscriber): void;
   afterModelLoaded(subscriber: StatusChangeSubscriber): void;
   waitModelLoaded(): Promise<boolean>;
+  subscribeSceneLoaded(subscriber: StatusChangeSubscriber): () => void;
+  unsubscribeSceneLoaded(subscriber: StatusChangeSubscriber): void;
+  afterSceneLoaded(subscriber: StatusChangeSubscriber): void;
+  waitSceneLoaded(): Promise<boolean>;
   subscribePluginPreRendered(subscriber: StatusChangeSubscriber): () => void;
   unsubscribePluginPreRendered(subscriber: StatusChangeSubscriber): void;
   afterPluginPreRendered(subscriber: StatusChangeSubscriber): void;

package/package.json

@@ -36,7 +36,7 @@
     "valtio": "2.1.7",
     "rhine-var": "0.11.2"
   },
-  "version": "0.26.16",
+  "version": "0.26.18",
   "author": "NextFlow",
   "license": "Apache-2.0",
   "keywords": [