Editor / Viewer 子域

July 10, 2026 · View on GitHub

最后更新：2026-07-09 | 覆盖源码：src/core/robot/assemblySceneProjection.ts、src/core/robot/assemblyScenePlacement.ts、src/features/editor/、src/features/urdf-viewer/、src/app/components/unified-viewer/、src/shared/components/3d/ 交叉引用：architecture.md、file-io.md、style-guide.md、wasm-build.md

1. 单模式 Editor

Editor 子域划分与快速映射见 CLAUDE.md §Editor 单模式。

新增功能前，先判断属于哪类子能力，避免跨子系统逻辑缠绕。

2. 目录结构

features/editor/
  index.ts                    # 统一 Editor 公开入口

features/urdf-viewer/
  components/                 # React 组件层
    ViewerCanvas.tsx          # viewer 画布层与共享 canvas 适配
    ViewerScene.tsx           # 统一场景编排，格式差异下沉到 RobotModel/backend
    RobotModel.tsx            # 后端驱动的机器人渲染与交互入口
    ViewerToolbar.tsx         # 顶部工具条
    ViewerLoadingHud.tsx      # loading 状态 HUD
  hooks/                      # React hooks
  renderers/                  # viewer backend 生命周期与 Three.js backend 适配
    ThreeJsBackend.ts         # legacy Three.js backend implementation
    createRendererBackend.ts  # source format -> backend factory
    loadedRobotSceneSync.ts   # runtime scene graph 同步
    sourceFormat.ts           # viewer source format 判定
    types.ts                  # renderer backend contract
  utils/                      # 交互、USD adapter、load key、可视化与 patch 工具
  types.ts                    # 共享类型收口
  runtime/                    # vendored usd-viewer runtime
    embed/                    # 嵌入适配
    hydra/                    # Hydra render delegate
    types/                    # runtime 类型
    vendor/                   # 第三方 vendor 代码
    viewer/                   # viewer 核心
    UPSTREAM.md               # 上游来源说明
  workers/                    # Web Workers

3. 核心 hooks / 能力

useViewerController：viewer 控制器
useMouseInteraction：鼠标交互处理
useHoverDetection：悬停检测
useVisualizationEffects：惯性、质心、原点等辅助可视化
useRendererBackend：统一模型加载与格式后端生命周期，backend 实现在 features/urdf-viewer/renderers/
useRobotLoader：Three.js backend 的底层 source loader
useHighlightManager：高亮管理

4. 实现约束

新能力优先放入 hooks 或新增组件，不要恢复双壳并存
保持 RobotNode <-> JointNode 交替递归渲染模式
材质必须通过 materials.ts / urdfMaterials.ts 复用，不在高频路径直接 new
viewer backend / load scene sync 归 features/urdf-viewer/renderers/；shared/components/3d/renderers/ 只保留 STL/OBJ/DAE/GLTF 等纯 mesh renderer 组件
使用 RobotData、WorkspaceSelection 等共享类型，避免 any
TransformControls 引用注册必须完整、可追踪
Props 与共享类型统一收口到 types.ts
可视化扩展通过 visualizationFactories.ts
共享关节面板位于 src/shared/components/Panel/JointsPanel.tsx

5. Canonical Assembly scene projection

viewer 不持有可写机器人状态；useWorkspaceStore.workspace 是唯一模型，渲染数据由 createAssemblySceneProjection 只读派生
projection 输出 RobotData、direct-component | assembled-scene 策略、globalToEntityRef / entityRefKeyToGlobal 双向映射和 component root target
单个可见 component 且无 bridge 时可用 direct-component；其余情况使用 assembled-scene。这只是 renderer/resource 性能策略，不得改变 selection、mutation、history 或 source sync 路由
Assembly transform 与 component transform 由 createAssemblyScenePlacement 的统一 root placement 应用；不得恢复 source-scene 专用 transform fallback
renderer 点击、hover、focus、joint motion 与 transform controls 必须通过 projection map 往返 WorkspaceSelection / EntityRef；禁止解析全局 ID 文本猜 component owner
source file 只提供 loader/resource context。结构编辑始终写入目标 component 的 source-local RobotData，策略切换不得改动 canonical workspace snapshot

6. USD runtime 边界

runtime/* 是 vendored usd-viewer runtime，不要在 core/parsers/usd/* 重复实现 viewer runtime 职责
URDF Studio 应把 runtime 输出适配到 ViewerRobotDataResolution / RobotData
public/usd/bindings/* 必须保留在静态资源目录，供浏览器运行时 fetch
WASM 构建系统位于 third_party/OpenUSD 和 scripts/build/；重编命令与故障排查见 wasm-build.md

7. USD worker / metadata 链路约束

适用范围：runtime/hydra/render-delegate/*、workers/*、utils/usd*、app/hooks/useFile*.ts 中消费 worker 结果的 USD 工作流

必须遵循：

USD stage preparation、runtime metadata、robot hydration、prepared export cache、roundtrip archive 的修复，默认优先放在 worker/runtime 链路完成，不要搬到主线程 adapter 或 debug bridge
runtime/hydra/render-delegate/* 产出的 metadata snapshot 是该链路的 source of truth；缺字段应修 worker/runtime 生成逻辑
禁止新增"worker 结果缺失 -> 主线程重建 metadata -> 静默继续"的 fallback
对 folded fixed link、collision-only semantic child link 的推断只能基于 stage/truth 中的明确证据，不做纯命名猜测
visual_* / collision_* / group_* / xform_* / scene / root 这类 roundtrip 容器 prim 不是 link identity；runtime metadata 不得把它们提升为 synthetic link 或 fixed joint

验证要求：

改动上述链路时，必须跑 test/unitree_model 整套 USD 浏览器验证
至少覆盖 Go2 + B2 + H1-2
浏览器验证产物写入 tmp/regression/

8. USD offscreen / runtime 生命周期约束

适用范围：usdOffscreenViewer.worker.ts、runtime/hydra/render-delegate/*、shared/utils/three/dispose.ts

必须遵循：

主线程宿主只负责 handoff、尺寸同步与错误透传；不要重建 runtime truth
teardown 必须完整释放 observer、DOM/worker 事件监听、RAF/timer、OffscreenCanvas 关联 runtime、scene graph 与 driver 引用
runtime 全局 handler/registry/active owner 必须提供对称的 unregister/reset
worker 侧创建的 ImageBitmap、object URL、临时 geometry/material/texture 必须显式释放
禁止通过全局单例把旧实例挂死

9. 关键 utils 职责速查

文件	职责
`viewerRobotData.ts`	统一 viewer 层消费的数据形态
`workspaceSceneProjection.ts`	canonical selection/motion 与 renderer global ID 映射
`viewerResourceScope.ts`	source file / assets / robot links 资源域
`usdExportBundle.ts`	USD 场景快照与导出缓存协调
`usdRuntimeRobotHydration.ts`	runtime -> RobotData hydration
`usdSceneRobotResolution.ts`	场景级 robot resolution
`usdViewerRobotAdapter.ts`	viewer runtime / snapshot 到应用数据适配
`usdOffscreenViewerWorkerClient.ts`	主线程对 offscreen worker 请求封装
`usdStageOpenPreparationWorkerBridge.ts`	prepared-open 链路 worker bridge
`usdPreparedExportCacheWorkerBridge.ts`	prepared-export 链路 worker bridge
`runtimeSceneMetadata.ts`	runtime scene metadata 标准化读模型
`visualizationFactories.ts`	辅助可视化对象创建
`dispose.ts`	THREE 资源清理

10. Renderer Backend 职责速查

文件	职责
`renderers/createRendererBackend.ts`	根据 source format 创建 viewer backend
`renderers/ThreeJsBackend.ts`	legacy Three.js 机器人加载、patch、scene 同步
`renderers/loadedRobotSceneSync.ts`	loaded scene 与 runtime robot data 的结构同步
`renderers/robotLoaderSourceMetadata.ts`	loader source metadata 标准化
`renderers/sourceFormat.ts`	viewer source format 分类
`renderers/urdfXmlFallbackPolicy.ts`	URDF XML fallback 策略