@nebula-spatial/viewer 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -2,30 +2,53 @@
 
 All notable changes to this package are documented in this file.
 
-## 0.4.3
-
-### Added
-
-- 公开 `AssetPhysicsState` 类型，在 `AssetPreviewSnapshot` 和 `AssetSession` 中增加可选 `physics` 状态，并提供可选 `AssetLoaderContext.reportSessionState()` 通知；现有 loader 无需实现这些新增成员。
-- FBX 外置纹理接入本地文件包与异步 `resourceResolver`，增加受限 TGA/DDS 解码、命名 UV 集、二维纹理变换及受限颜色分层合成；具体边界见 `FBX-MATERIAL-CONVERSION.md`。
-
-### Improved
-
-- 按 FBX 材质 ID、连接顺序及模板恢复材质参数，完善标量贴图通道、事务回滚、取消和资源释放；不支持或近似转换通过警告及诊断报告暴露。
-- 改善 USD 的 OmniPBR/PxrSurface 材质适配、索引 UV、GeomSubset 材质绑定与粗糙度贴图通道，区分视觉适配警告和物理故障。
-- 完善 URDF、MJCF、USD 碰撞几何与位姿同步，保留源格式碰撞定义，补充关节与运动学预览支持及回归测试。
-
-### Fixed
-
-- 物理编译或初始化失败时，在能够独立构建视觉预览的前提下保留资产；运行中的 step/reset 失败停止仿真、保留最后显示的视觉位姿并刷新能力状态，不再自动重启物理。
-- 物理不可用时保留置灰播放按钮，悬停显示物理故障原因并拦截播放，不被材质警告覆盖。
-
-### Behavior notes
-
-- `phase === 'ready'` 仅表示资产预览就绪，不保证物理可运行。宿主应检查 `capabilities.canPlay`，并使用 `physics.status === 'unavailable'` 下的 `issue` 展示原因；未提供物理状态不等于 `not-authored`。
-- FBX 加载完成等待纹理解码和转换；缺失、歧义、鉴权或解码失败按加载失败处理，不保证旧资产继续以缺贴图模型成功加载。
-- 本版本不承诺任意 FBX/自定义着色器无损转换或 Blender 像素一致；USD/URDF/MJCF 物理降级不掩盖取消或视觉加载失败。
-
+## 0.4.4
+
+### Added
+
+- 新增 URDF 审查工作台：模型结构树、搜索过滤、关节滑块与范围扫描、属性面板、XML 只读定位及仅报告确定错误的检查。
+- 公开 `AssetPreview.getInspection()`、插件侧 `ctx.asset.$inspection()` 和 `UrdfInspection` 快照/命令契约；支持关闭内置 URDF UI 或完全 Headless 自定义。
+- 增加关节轴与正转方向、质心、完整惯性张量对应的等效惯量盒可视化；选中部件的质心与惯量使用区别色，仿真运行时标记跟随实时位姿。
+- 新增视角 gizmo、可拖拽调宽及折叠的侧栏、深浅主题切换和 URDF playground 入口。
+
+### Improved
+
+- URDF 默认静止运动学预览，仅显式播放时懒初始化动力学；暂停后支持部件选择与关节控制，再次播放从当前姿态继续，重置恢复初始运动学状态。
+- 支持按住 R 配合鼠标左右移动调节关节，根据相机朝向、关节世界轴及鼠标位置判断方向；不提供 Shift 精调。
+- 使用模型局部 BVH 加速拾取，浅蓝材质高亮选中部件；优先定位关联关节，点击空白取消选择，自动展开选中项祖先并保留结构树滚动位置。
+- 统一 SVG 场景工具栏、输入控件与主题样式，放开轨道相机俯仰范围；本地上传组件加载成功后收起为右上角悬浮按钮，支持手动展开和收起。
+
+### Fixed
+
+- 修复关节滑块连续拖动和重建 UI 导致的结构树滚动跳变；仿真运行时禁用关节控制，保留物理拖拽。
+- 加固物理懒初始化期间的取消与资源释放，初始化失败仍保留运动学审查。
+- 初始化及手动调整姿态后检查实际碰撞边界，必要时下移查看器默认地面，避免初始穿透导致弹飞；不移动模型或资产自带地面，运行时地面保持固定。
+- 重置恢复初始安全物理地面，URDF 返回初始预览地面，不保留临时下移高度；暂停保持当前地面。
+
+## 0.4.3
+
+### Added
+
+- 公开 `AssetPhysicsState` 类型，在 `AssetPreviewSnapshot` 和 `AssetSession` 中增加可选 `physics` 状态，并提供可选 `AssetLoaderContext.reportSessionState()` 通知；现有 loader 无需实现这些新增成员。
+- FBX 外置纹理接入本地文件包与异步 `resourceResolver`，增加受限 TGA/DDS 解码、命名 UV 集、二维纹理变换及受限颜色分层合成；具体边界见 `FBX-MATERIAL-CONVERSION.md`。
+
+### Improved
+
+- 按 FBX 材质 ID、连接顺序及模板恢复材质参数，完善标量贴图通道、事务回滚、取消和资源释放；不支持或近似转换通过警告及诊断报告暴露。
+- 改善 USD 的 OmniPBR/PxrSurface 材质适配、索引 UV、GeomSubset 材质绑定与粗糙度贴图通道，区分视觉适配警告和物理故障。
+- 完善 URDF、MJCF、USD 碰撞几何与位姿同步，保留源格式碰撞定义，补充关节与运动学预览支持及回归测试。
+
+### Fixed
+
+- 物理编译或初始化失败时，在能够独立构建视觉预览的前提下保留资产；运行中的 step/reset 失败停止仿真、保留最后显示的视觉位姿并刷新能力状态，不再自动重启物理。
+- 物理不可用时保留置灰播放按钮，悬停显示物理故障原因并拦截播放，不被材质警告覆盖。
+
+### Behavior notes
+
+- `phase === 'ready'` 仅表示资产预览就绪，不保证物理可运行。宿主应检查 `capabilities.canPlay`，并使用 `physics.status === 'unavailable'` 下的 `issue` 展示原因；未提供物理状态不等于 `not-authored`。
+- FBX 加载完成等待纹理解码和转换；缺失、歧义、鉴权或解码失败按加载失败处理，不保证旧资产继续以缺贴图模型成功加载。
+- 本版本不承诺任意 FBX/自定义着色器无损转换或 Blender 像素一致；USD/URDF/MJCF 物理降级不掩盖取消或视觉加载失败。
+
 ## 0.4.2
 
 ### Fixed

package/README.md

@@ -258,30 +258,30 @@ preview.reset();
 preview.play();
 ```
 
-### 公开物理状态与会话通知
-
-包入口导出 `AssetPhysicsState`，可通过 `preview.getSnapshot().physics` 或原有订阅回调读取：
-
-```ts
-import type { AssetPhysicsState } from '@nebula-spatial/viewer';
-
-const physics: AssetPhysicsState | null | undefined = preview.getSnapshot().physics;
-if (physics?.status === 'unavailable') {
-  console.warn(physics.issue.message);
-}
-```
-
-- `not-authored`：未声明驱动当前仿真的动力学定义，作为静态或运动学资产预览。
-- `ready`：物理已就绪；播放操作仍应检查 `snapshot.capabilities.canPlay`。
-- `unavailable`：物理准备或运行失败，`issue` 提供原因。
-- `null` 或未提供：会话未报告物理状态，不能等同于 `not-authored`。
-
-资产的 `phase === 'ready'` 与物理可用性相互独立。运行中的 step/reset 失败会停止仿真，
-保留视觉对象及最后显示的位姿，更新能力与物理状态，并上报非致命错误；不会自动重启物理。
-自定义 loader 可通过可选的 `AssetSession.physics` 提供状态，并在就绪后调用
-`context.reportSessionState?.()` 通知 Viewer 刷新 capabilities、physics 和 warning。
-现有 loader 不必实现这些可选成员；自定义 UI 应订阅状态变化，而不是仅以加载完成判断能否播放。
-
+### 公开物理状态与会话通知
+
+包入口导出 `AssetPhysicsState`，可通过 `preview.getSnapshot().physics` 或原有订阅回调读取：
+
+```ts
+import type { AssetPhysicsState } from '@nebula-spatial/viewer';
+
+const physics: AssetPhysicsState | null | undefined = preview.getSnapshot().physics;
+if (physics?.status === 'unavailable') {
+  console.warn(physics.issue.message);
+}
+```
+
+- `not-authored`：未声明驱动当前仿真的动力学定义，作为静态或运动学资产预览。
+- `ready`：物理已就绪；播放操作仍应检查 `snapshot.capabilities.canPlay`。
+- `unavailable`：物理准备或运行失败，`issue` 提供原因。
+- `null` 或未提供：会话未报告物理状态，不能等同于 `not-authored`。
+
+资产的 `phase === 'ready'` 与物理可用性相互独立。运行中的 step/reset 失败会停止仿真，
+保留视觉对象及最后显示的位姿，更新能力与物理状态，并上报非致命错误；不会自动重启物理。
+自定义 loader 可通过可选的 `AssetSession.physics` 提供状态，并在就绪后调用
+`context.reportSessionState?.()` 通知 Viewer 刷新 capabilities、physics 和 warning。
+现有 loader 不必实现这些可选成员；自定义 UI 应订阅状态变化，而不是仅以加载完成判断能否播放。
+
 ### 远端仿真资产与格式识别边界
 
 省略 `format` 与 `format: 'auto'` 等价：只按明确扩展名或已注册 loader 的明确 `match()` 结果识别。
@@ -611,6 +611,43 @@ CAD 类型改为 `ViewerCadUiOptions`、`ViewerCadUiParts`、`ViewerCadUiKeyboar
 - [ ] Draco、MuJoCo、OpenUSD runtime URL 由宿主明确配置并已在真实部署路径验证。
 - [ ] 远端资产的 CORS、MIME、鉴权、相对资源路径以及 USD 的跨源隔离已端到端验证。
 
+## URDF Viewer 审查工作台（0.4.4）
+
+URDF 默认打开为静止的**运动学预览**：关节控制由确定性 FK 驱动，不会自动加载或启动 MuJoCo。只有用户调用 `preview.play()`、`ctx.commands.play()` 或点击内置“动力学仿真”播放按钮后，Viewer 才按需初始化现有物理运行时。
+
+内置工作台包括可折叠结构树、搜索/过滤、关节滑块与范围扫描、Collision/关节轴与正方向/质心/惯量覆盖层、属性面板、XML 只读定位，以及只报告确定错误的严格检查。可通过 `ui.urdf: false` 关闭内置界面，或通过 `ui.preset: 'none'` 完全 Headless 使用。
+
+### 交互与仿真状态
+
+- 默认不打开全部关节轴；选中部件时显示关联关节轴，启用关节轴开关后显示全部关节轴。
+- 可用滑块或按住 **R + 鼠标左右移动**调节选中可动关节；方向结合相机朝向、关节世界轴及鼠标位置计算，未启用 Shift 精调。
+- 仿真运行时关节控制与部件选择只读，但保留物理拖拽；关节轴、质心、惯量可以开关并跟随实时姿态。
+- 暂停后恢复点选与关节调整，再次播放使用当前姿态；重置恢复初始运动学状态。选中关节时，其 child link 的质心和惯量使用区别色。
+- 场景工具栏提供播放/暂停、重置、地面显隐、适应视图及主题切换；侧栏支持调宽和折叠，结构树选择保留滚动位置。
+
+### 默认地面的防穿透与重置
+
+默认物理地面在初始化及手动调整姿态后按编译后的碰撞边界检查；必要时只下移查看器自动添加的地面，不移动模型或修改资产自带地面。运行过程中地面保持固定，可视地面跟随物理地面高度。
+
+暂停保留当前地面；重置恢复初始化时的安全物理高度，URDF 返回初始预览地面。再次启动仍检查穿透。此机制不修复资产内部碰撞体互相穿透等其他物理问题。
+
+### 自定义审查界面
+
+```ts
+const preview = await viewer.openAsset(source, { format: 'urdf' });
+const inspection = preview.getInspection();
+
+if (inspection?.kind === 'urdf') {
+  const stop = inspection.subscribe(snapshot => renderRobotReview(snapshot));
+  inspection.select('joint:elbow');
+  inspection.setJointValue('elbow', 0.5);
+  inspection.setOverlay('jointAxis', true);
+  // preview.play(); // 明确调用后才初始化并启动动力学仿真
+  stop();
+}
+```
+
+插件使用 `ctx.asset.$inspection()` 读取同一审查会话，通过 `ctx.commands.play/pause()` 控制动力学。完整交互、架构、状态所有权、严格规则和扩展方式见 [`docs/urdf-reviewer-interaction-design.md`](../../docs/urdf-reviewer-interaction-design.md)。
 ## 通用 Three.js 对象
 
 Viewer 同样可管理非 CAD 的 `Object3D`：
@@ -697,10 +734,10 @@ ShininessExponent 按 Blender 导入约定直接映射粗糙度，透明通道
 FBX 外置纹理支持入口相对路径、本地文件包和异步 resourceResolver。仅在文件名唯一时
 容许扁平文件选择；重名歧义、缺失、鉴权/解码错误按加载失败处理，不静默忽略。
 ready 等待纹理解码及转换完成；中断和关闭清理源纹理、转换纹理与临时 object URL。
-支持命名 UV 集到 uv/uv1/uv2/uv3 的绑定及二维平移、缩放；W 轴旋转采用显式兼容规则并报告近似。
-颜色分层仅支持同尺寸、同 UV/采样配置及不透明底层下的受限合成，不支持任意分层或自定义 shader。
-近似与不支持项通过 AssetPreviewSnapshot.warning 和 material.userData.fbxConversionReport 报告。
-除浏览器可解码图像外，已接入受限 TGA/DDS 专用解码；不支持任意 DDS 编码或内嵌 DDS。
+支持命名 UV 集到 uv/uv1/uv2/uv3 的绑定及二维平移、缩放；W 轴旋转采用显式兼容规则并报告近似。
+颜色分层仅支持同尺寸、同 UV/采样配置及不透明底层下的受限合成，不支持任意分层或自定义 shader。
+近似与不支持项通过 AssetPreviewSnapshot.warning 和 material.userData.fbxConversionReport 报告。
+除浏览器可解码图像外，已接入受限 TGA/DDS 专用解码；不支持任意 DDS 编码或内嵌 DDS。
 详细支持范围、资源所有权及验证边界见 [FBX-MATERIAL-CONVERSION.md](./FBX-MATERIAL-CONVERSION.md)。
 
 材质参数对齐不等于截图逐像素对齐：还需相同 HDR、环境旋转、曝光、视角与色彩管理。

package/dist/assets/types.d.ts

@@ -1,3 +1,4 @@
+import type { AssetInspection } from '../inspection/types';
 import type { Object3D, WebGLRenderer, Scene, Camera, Box3, ColorRepresentation } from 'three';
 import type { CadLoadSource, CadOpenOptions } from '../cad/types';
 import type { ViewerViewMode } from '../types';
@@ -88,7 +89,7 @@ export interface AssetWarningSnapshot {
 }
 /** Physics availability is independent of the visual asset's ready phase. */
 export type AssetPhysicsState = {
-    readonly status: 'not-authored' | 'ready';
+    readonly status: 'not-authored' | 'available' | 'initializing' | 'ready';
 } | {
     readonly status: 'unavailable';
     readonly issue: AssetWarningSnapshot;
@@ -125,6 +126,7 @@ export interface AssetControlState {
     readonly upAxis: AssetUpAxis | null;
 }
 export interface AssetPreview {
+    getInspection(): AssetInspection | null;
     getPhysicsProperties(): Readonly<Record<string, unknown>> | null;
     /** USD visual report and diagnostics, including static assets. */
     getVisualDiagnostics?(): Readonly<Record<string, unknown>> | null;
@@ -196,6 +198,9 @@ export interface AssetLoaderContext {
     reportSessionState?(): void;
 }
 export interface AssetSession {
+    readonly autoPlay?: boolean;
+    readonly inspection?: AssetInspection | null;
+    isPlaying?(): boolean;
     setTheme?(theme: 'dark' | 'light'): void;
     beforeRender?(renderer: WebGLRenderer, scene: Scene, camera: Camera): (() => void) | void;
     getPhysicsProperties?(): Readonly<Record<string, unknown>> | null;