@soonspacejs/plugin-cps-soonmanager 2.15.13 → 2.15.15

package/README.md

@@ -2,4 +2,60 @@
 
 > Sync cps soonmanager data plugin for SoonSpace.js
 
+## Web Worker 场景加载
 
+`loadSceneAndSemanticInWorker` 会与场景资源加载并行获取并解析语义数据。墙、柱和窗对象在主线程离场创建，全部完成后统一挂载、注册缓存并刷新场景。
+
+该方法会将场景树中的空间、楼层、房间、门、窗、楼梯、电梯等语义辅助面，以及 `semantic_model` 中除虚拟墙外的墙、柱、窗语义面设置为完全透明并关闭深度写入；`VirtualWall` 为真的墙仍按墙体样式显示。透明模式只通过插件内部参数启用，`loadScene` 和 `loadSceneAndSemantic` 继续使用原有语义颜色及透明度。
+
+```ts
+const scenePromise = cpsSoonmanagerPlugin.loadSceneAndSemanticInWorker(
+  { path, key, applyPresetEffects: false },
+  undefined,
+  {
+    onStage: event => console.info('[SceneLoad]', event),
+    freezeSceneWorldMatrix: true,
+  }
+)
+
+// 业务接口不阻塞场景加载；接口先返回、加载中返回或加载后返回均可应用。
+fetchFullInstanceTree()
+  .then( createWorkIdMap )
+  .then( workIdMap => cpsSoonmanagerPlugin.applyWorkIdMap( workIdMap ) )
+
+const result = await scenePromise
+```
+
+`onStage` 仍会通知各加载阶段和状态，但不再采集或返回阶段耗时；`loadSceneAndSemanticInWorker` 的结果也不再包含 `timings` 字段。
+
+第二个参数与 `loadScene`、`loadSceneAndSemantic` 相同，仍支持加载前传入 `Record` 或 `Map` 类型的 `workIdMap`。业务 ID 也可以通过 `applyWorkIdMap` 在加载过程中或加载完成后传入。未创建对象的映射会保留为 pending，并在对象创建或语义对象统一提交后自动应用；已创建对象会立即更新 `userData.work_id`、`extraIds` 和 SoonSpace 对象缓存。
+
+加载后传入的映射不会追溯执行 `hiddenObjects` 判断；如果需要使用业务 ID 控制初始隐藏状态，应继续通过 `loadSceneAndSemanticInWorker` 第二个参数提前传入。
+
+示例文件：`example/semantic-worker-scene.html`。示例默认使用场景 ID `465391669186895872`，鉴权 token 通过运行时 URL 参数 `token` 传入，不写入源码或构建产物。
+
+示例会调用 UStudio 的 `/boss/twins/scene/v1/instance-tree` 接口获取全量实例树，不传 `include_twins_identifiers`。遍历实例树后使用 `out_instance_id` 作为场景对象 ID，使用 `twins_instance_id` 作为业务 ID，生成以下结构并传给插件：
+
+```ts
+workIdMap[out_instance_id] = { work_id: twins_instance_id }
+```
+
+实例树请求不会计入场景加载等待时间。实例树加载耗时、映射数量和 `applyWorkIdMap` 结果会独立输出到控制台；最终映射保存在 `window.sceneWorkerWorkIdMap`，异步任务保存在 `window.sceneWorkerWorkIdPromise` 供示例调试。
+
+示例支持在场景资源加载过程中传入单个组件 ID：`componentId` 对应 `out_instance_id`，`componentWorkId` 对应 `twins_instance_id`。如果不传 `componentWorkId`，示例会从全量实例树中查找：
+
+```text
+?componentId=<out_instance_id>&componentWorkId=<twins_instance_id>
+```
+
+场景加载 Promise 启动后会立即尝试调用 `applyWorkIdMap`，并由模型进度事件再次兜底；调用结果会输出到控制台。若对象尚未创建，映射会先进入 pending，插件会在对象创建后自动补齐。
+
+Worker 相关源码按职责拆分：
+
+- `semantic-worker.config.ts`：墙、柱、窗的解析配置。
+- `semantic-worker.parser.ts`：纯数据解析和批次分组，不依赖 SoonSpace 实例。
+- `semantic.worker.ts`：Worker 入口，负责资源获取和调用解析器。
+- `semantic-worker.client.ts`：主线程 Worker 生命周期、取消和消息协议。
+- `semantic-worker.shared.ts`：取消、错误和计时结果的共享辅助函数。
+- `semantic-batch.utils.ts`：主线程离场创建、统一挂载和失败清理。
+- `semantic.utils.ts`：旧版逐对象语义加载逻辑，供兼容 API 使用。

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { TerrainTilesRenderer } from '@soonspacejs/plugin-tiles';
 import { default as SoonFlow } from '@soonflow/core';
 import { AnimationPlayer } from 'umanager-animation-parser';
 import { EventDispatcher } from 'three';
-import { IMetadata, ITreeData, IInnerTreeData, IPoiData, ITopologyPath, ILoadSceneOptions, TPropertiesMap, TAnimationsMap, IPlayAnimationByIdOptions, TModelVisionsMap, IPresetEffectsOptions, TSpacesMap, ConstructorOptions, ISpaces, IFlatData, IProgress, IProgressEventMap, IGisData, IFdsData, IGisPlot, IWorkIdMap } from './types';
+import { IMetadata, ITreeData, IInnerTreeData, IPoiData, ITopologyPath, ILoadSceneOptions, TPropertiesMap, TAnimationsMap, IPlayAnimationByIdOptions, TModelVisionsMap, IPresetEffectsOptions, TSpacesMap, ConstructorOptions, ISpaces, IFlatData, IProgress, IProgressEventMap, IGisData, IFdsData, IGisPlot, IWorkIdMap, IApplyWorkIdMapResult, ILoadSceneAndSemanticInWorkerOptions, ILoadSceneAndSemanticInWorkerResult } from './types';
 import { SemanticObject } from './semantic.types';
 type WorkIdContext = {
     byKey: Map<string, string>;
@@ -17,6 +17,7 @@ type WorkIdContext = {
 };
 type LoadSceneOptionsInner = ILoadSceneOptions & {
     __workIdContext?: WorkIdContext | null;
+    transparentSemanticPolygons?: boolean;
 };
 declare class CpsSoonmanagerPlugin extends EventDispatcher<IProgressEventMap> {
     #private;
@@ -174,6 +175,11 @@ declare class CpsSoonmanagerPlugin extends EventDispatcher<IProgressEventMap> {
     refreshPoiByDataSource(): Promise<void>;
     refreshByUserData(): Promise<void>;
     runWithCode<T>(fn: (args: any) => T): Promise<T>;
+    /**
+     * 在场景加载中或加载完成后补充业务 ID 映射。
+     * 未创建对象的映射会保留，并在对象创建或语义对象统一提交后自动应用。
+     */
+    applyWorkIdMap(workIdMap?: IWorkIdMap | null): IApplyWorkIdMapResult;
     /**
      * 根据 id 获取树节点
      */
@@ -192,7 +198,8 @@ declare class CpsSoonmanagerPlugin extends EventDispatcher<IProgressEventMap> {
         wait?: boolean;
     }): Promise<import('@soonspacejs/plugin-fds').VolumePoints | null>;
     /**
-     * 加载整个场景
+     * 加载整个场景。
+     * workIdMap 会在对象创建阶段注册为 userData.work_id 和 extraIds。
      */
     loadScene(options?: ILoadSceneOptions, workIdMap?: IWorkIdMap | null): Promise<undefined>;
     /**
@@ -200,6 +207,14 @@ declare class CpsSoonmanagerPlugin extends EventDispatcher<IProgressEventMap> {
      * @param options
      */
     loadSceneAndSemantic(options?: ILoadSceneOptions, workIdMap?: IWorkIdMap | null): Promise<void>;
+    /**
+     * 加载场景并在 Web Worker 中获取、解析语义数据。
+     *
+     * 墙、柱和窗对象会先离场创建，全部完成后一次性挂载并刷新缓存，
+     * 这样可以避免大场景语义对象逐个挂载时阻塞交互或产生中间画面。
+     * workIdMap 与 loadScene/loadSceneAndSemantic 使用完全相同的映射逻辑。
+     */
+    loadSceneAndSemanticInWorker(options?: ILoadSceneOptions, workIdMap?: IWorkIdMap | null, workerOptions?: ILoadSceneAndSemanticInWorkerOptions): Promise<ILoadSceneAndSemanticInWorkerResult>;
     /**
      * 预设 GIS 效果
      */