@nebula-spatial/viewer 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to this package are documented in this file.
 
+## 0.4.5
+
+### Added
+
+- 新增 USD 视觉材质适配支持矩阵，明确 `UsdPreviewSurface`、MaterialX Standard Surface、OmniPBR 和 OmniGlass 的已转换、有界近似及未适配范围。
+- 支持常量介质透明、`presence`、`opacityThreshold`、受限透明纹理、MaterialX 薄壁透射，以及 OmniGlass 的覆盖率、反射颜色、粗糙度和受限法线适配。
+- 支持 USD 实例材质代理中的可确定常量 `UsdPreviewSurface` 输入恢复；保留循环、歧义、程序节点和体积光学语义的诊断。
+- 本地 Viewer 文件包入口支持 `root.usd`、`root.usda`、`root.usdc` 和 `root.usdz`，不受上传顺序影响。
+- 支持浏览器 Xacro 子集展开，包含宏、属性、参数、条件、块参数、嵌套 include 与 ROS package 映射；不支持的 Python/ROS 语义会显式失败。
+- 支持 URDF mimic 联动、可行控制范围、浏览器 COLLADA 网格、内嵌材质，以及本地文件包目录浏览和入口切换。
+
+### Improved
+
+- 统一 URDF/MJCF 视觉材质的线性颜色、粗糙度、金属度、法线、透明度、发光和纹理通道转换，并补充纹理资源释放与诊断。
+- URDF 审查工作台补充惯性姿态、惯量信息展开、连续关节控制范围、关节扫描和侧栏交互保持。
+- USD 视觉过滤按 `purpose` 隔离辅助几何；修正世界侧关节参考系、单位/up-axis 转换和显式惯性处理。
+- 物理模型取景忽略环境平面，避免地面或辅助几何主导模型缩放；补充跨格式材质审计页面及 Chromium 验证脚本。
+- 恢复分离 USD 视觉树到刚体的引用归属，支持显式引用 Prim 路径与 defaultPrim 引用，并对歧义、缺失和格式错误保留诊断。
+
+### Fixed
+
+- 玻璃透射材质按 USD `doubleSided` 声明应用单面/双面策略，避免共享材质被错误修改；纯金属材质不被误判为玻璃。
+- 修复 USD 透明度、覆盖率阈值、透明纹理、OmniGlass 法线与反射参数的边界转换；无法可靠表达的体积吸收、实体光程和复杂光学效果继续报告诊断，不生成猜测值。
+- 允许具有完整显式质量、质心、惯量和主轴数据的 USD 刚体缺少碰撞几何；仅有不完整惯性时仍明确失败，不虚构碰撞形状。
+- 修复 URDF 固定轴 RPY、惯性坐标旋转、mimic 初始姿态与 MuJoCo equality 约束；修复 USD 聚合视觉网格不随对应刚体更新的问题。
+
+### Behavior notes
+
+- 本版本继续使用有边界的 Three.js 材质映射，不执行 MDL 或完整 MaterialX 节点网络，也不承诺与 Blender、Omniverse 或路径追踪渲染逐像素一致。
+- `USD-VISUAL-MATERIAL-SUPPORT.md` 随 npm 包发布，记录具体支持矩阵；材质适配报告和诊断仍是判断单个资产结果的依据。
+- Xacro 是受限浏览器预处理子集，不执行外部 ROS 命令或环境访问；复杂 Python/YAML 语义应先使用官方工具展开。
+- 本次发布只更新 Viewer；`@nebula-spatial/cad-loader` 和私有 `scene-runtime` 版本不变。
+
 ## 0.4.4
 
 ### Added

package/README.md

@@ -328,11 +328,32 @@ Viewer 自动识别所有资产形态，也不能把本地样本验证等同于
 
 ### USD 视觉材质适配与诊断
 
+OmniPBR 是 NVIDIA 的 MDL 材质模板，不等于 OpenUSD 的 UsdPreviewSurface。
+本查看器做有边界的 Three.js 参数/纹理映射，不执行 MDL，也不承诺完整等价。
+支持独立灰度 roughness/metallic 贴图，以及 ORM 的明确粗糙度/金属度通道；
+非灰度独立图不猜测 mono 规则。0–1 influence 按
+`constant * (1 - influence) + texture * influence` 混合原始数据像素，输出 8 位标量纹理，
+因此存在量化误差；未声明的粗糙度/金属度常量采用 OmniPBR 默认值 0.5/0。
+支持 `diffuse_tint` 和已有 `normalmap_texture`，默认法线强度为 1，按默认 DirectX V
+切线翻转处理；明确的 U/V 翻转参数优先。仍限定单位 UV 变换和数据纹理色彩空间。
+Opacity 遵守 enable 开关、常量阈值与贴图 alpha/average/maximum 采样（luminance 暂不支持），
+属于 cutout/覆盖率近似，不是玻璃透射。自发光遵守开关及强度，但仍报告辐射度等价性限制。
+非默认 specular_level、AO-to-diffuse、复杂 UV/投影、细节法线、自发光贴图组合与 OmniGlass
+仍有未支持部分；具体以逐材质报告为准，不能用“无报错”代替原渲染器画面对照。
+
+完整的 USD 材质支持矩阵与限制见 [USD-VISUAL-MATERIAL-SUPPORT.md](./USD-VISUAL-MATERIAL-SUPPORT.md)。
+
 USD 仿真继续以 OpenUSD Stage 和 USD Physics 为语义权威；视觉适配层只在
 `@openusd-wasm/three-loader` 完成标准几何、材质绑定、`UsdPreviewSurface`、受支持纹理和
 PBR 参数转换之后查漏补缺。它不会重建 loader 已正确生成的材质，也不会修改刚体、关节、碰撞体
 或 MuJoCo 绑定。
 
+USD 视觉引用归属：当视觉几何位于独立聚合树、刚体树中的 `Visual` Prim 通过 USD reference 指向该聚合树时，Viewer 会按引用的目标 Prim 路径将网格绑定到对应刚体，使其跟随 MuJoCo 运行时位姿。支持显式引用 Prim 路径及 defaultPrim 引用；多个刚体映射到同一视觉尾路径、引用元数据缺失或格式无法解析时不会猜测归属，而是保留视觉诊断。
+实例化材质：当 Loader 遗漏实例代理中的 Shader 时，适配层沿 `outputs:surface` 读取
+标准 `UsdPreviewSurface`，解析其输入到材质实例常量的连接，再复用 Loader 的材质转换。
+当前只补齐可确定解析的常量网络；缺失、循环、歧义连接或纹理/程序节点网络保留原诊断。
+不会解除 Stage 实例化、修改 USD 文件或改变物理定义。
+
 视觉拓扑补齐遵循原始 USD 数据，不进行猜测：
 
 - 在三角面、四边形或多边形的三角化面角与 Loader 输出可逐项核对时，按 `primvars:st:indices`
@@ -711,6 +732,8 @@ npm run build --workspace @nebula-spatial/viewer
 
 ### USD / Isaac Sim 物理映射边界
 
+USD 转换生成的 MuJoCo 碰撞几何使用 `margin="0"`，不额外膨胀接触表面，以保留资产预留的窄缝。该策略不关闭碰撞，也不修改拖拽力。PhysX `contactOffset/restOffset` 不直接等价于 MuJoCo `margin/gap`，目前不做一比一映射；不声明跨引擎接触行为完全一致。
+
 查看器遵循 OpenUSD `UsdPhysics` 的基础刚体语义：`PhysicsCollisionAPI` 单独应用表示静态碰撞体，和 `PhysicsRigidBodyAPI` 同时应用表示动态刚体；同一刚体下可以包含多个碰撞形状。场景单位、Z/Y-up、Cube/Sphere/Cylinder/Capsule/Mesh 碰撞体、静态碰撞体、质量/密度、自由刚体初始速度和基础关节会在可验证的范围内映射到 MuJoCo。
 
 Isaac Sim/PhysX 专有的碰撞近似、碰撞组、simulation owner、求解器/CCD、接触模型和逐对关节碰撞过滤不保证等价转换。无法可靠映射的属性会写入 `diagnostics.droppedFeatures`，不会伪造一个看似正确的 MJCF 结果；若基础几何或刚体语义无法建立，则按 USD 物理降级策略处理。
@@ -742,3 +765,39 @@ ready 等待纹理解码及转换完成；中断和关闭清理源纹理、转
 
 材质参数对齐不等于截图逐像素对齐：还需相同 HDR、环境旋转、曝光、视角与色彩管理。
 Viewer 不会为了匹配单个 Blender 截图而覆盖全局曝光或灯光。
+
+## Xacro preview
+
+`.xacro` and `.urdf.xacro` use `xacro-parser@0.3.11` as an optional, lazily loaded
+preprocessing stage before the existing URDF kinematic review. They do not autoplay.
+Upload the entire description directory, not only its entry XML, or provide a
+`baseUrl` / `resourceResolver` for includes and meshes.
+
+```ts
+const preview = viewer.openAsset({ kind: 'files', entry: 'robot/urdf/main.urdf.xacro', files }, {
+  xacro: {
+    arguments: { prefix: 'arm_', size: 0.2 },
+    packages: { robot_description: 'robot' },
+  },
+});
+await preview.ready;
+```
+
+`xacro.packages` maps ROS package names to directories relative to the uploaded
+file package or `baseUrl`. Local `package.xml` files supply mappings automatically;
+explicit mappings override discovery. Ambiguous package names fail. External ROS
+commands and environment access are not executed. Mesh/texture `package://` paths
+use the same mapping. Resource requests retain the existing resolver and abort signal.
+
+Supported subset: macros, properties, arguments/defaults, numeric expressions,
+if/unless, block parameters and nested includes. Python expressions are **not**
+fully compatible: `xacro.load_yaml`, include namespaces, dynamic `xacro:call`, and
+`param:=^|default` are unsupported. Expansion errors are fatal `E_XACRO_EXPAND`
+errors; there is no fallback that renders incomplete raw Xacro as URDF. Inputs are
+limited to 4 MiB each and 128 include reads, but this is not a sandbox or a complete
+CPU/memory limit for untrusted macro expansion.
+
+Review source ranges are labeled `(expanded URDF)`; they do not map back to the
+original macro definition. The current Universal Robots ROS2 description uses
+Python/YAML expressions and is not covered by this browser subset. For full ROS
+compatibility, expand with the official Xacro tool first and open the resulting URDF.

package/USD-VISUAL-MATERIAL-SUPPORT.md

@@ -0,0 +1,51 @@
+# USD 视觉材质适配矩阵
+
+> 更新日期：2026-09-22
+>
+> 本文描述浏览器 Viewer 当前对 USD 材质的**语义转换与视觉近似边界**，不是渲染器等价性声明。没有资产资源、没有材质连接或缺少可靠光学数据时，适配层不会生成替代内容。
+
+## 判定等级
+
+| 等级 | 含义 |
+|---|---|
+| 原生保留 | Loader 已能正确表达，适配层不重建或只做诊断清理。 |
+| 已转换 | 源参数和资源可以确定映射到 Three.js 材质。 |
+| 有界近似 | 可以表达主要视觉意图，但与源渲染器、MDL、MaterialX 或路径追踪不保证等价。 |
+| 未适配 | 当前没有可靠的映射；保留 Loader 输出并报告限制。 |
+| 不处理 | 需要缺失资源、未知节点语义或无法从资产确定的数据；禁止猜测。 |
+
+## 当前支持矩阵
+
+| 材质体系 / 功能 | 当前视觉结果 | 已覆盖内容 | 尚未适配或有边界的内容 | 处理原则 |
+|---|---|---|---|---|
+| `UsdPreviewSurface` 不透明 | 原生保留 | 常量颜色、粗糙度、金属度等由 Loader 提供 | 复杂节点网络依赖 Loader 能力 | 不重复转换已正确支持的材质 |
+| `UsdPreviewSurface` 常量介质透明 | 有界近似 | `opacityMode=transparent`、常量 IOR、`MeshPhysicalMaterial.transmission`、反射保留 | Three.js 与 PreviewSurface 的透射瓣、粗糙度和多层透射不完全等价 | 不把所有 opacity 机械转换为玻璃 |
+| `UsdPreviewSurface` `presence` | 已转换（常量） | 整体覆盖率、零值消失、中间值透明 | 纹理驱动和复杂连接 | 不与玻璃 transmission 混淆 |
+| `UsdPreviewSurface` `opacityThreshold` | 已转换（受限） | 常量小于阈值裁切，大于等于阈值保留 | 复杂纹理过滤、跨渲染器阈值边缘差异 | 不将裁切误作连续半透明 |
+| `UsdPreviewSurface` 透明纹理 | 已转换（受限） | raw、UV0、明确通道、scale/bias、支持的 wrap 模式 | 非 raw 色彩空间、复杂 UV、多节点合成 | 只重排已有像素，不生成纹理 |
+| `UsdPreviewSurface` 纯金属透明 | 有界近似 | 保留纯金属镜面响应，不转成玻璃 | 半金属、复杂 specular workflow | 金属和玻璃分支严格区分 |
+| MaterialX Standard Surface 薄壁透射 | 有界近似 | 常量 opacity 与 transmission 分离；Loader 透射结果保留 | 完整 MaterialX 节点执行、复杂组合和多层透射 | 不把 transmission_depth 当几何壁厚 |
+| MaterialX 实体透射 | 未适配关键效果 | 保留可表达的表面透射 | 体积颜色、吸收、内部光程 | 缺少可靠光程时不猜测 thickness |
+| OmniPBR 基础颜色 | 已转换 / 有界近似 | 常量颜色、已有 diffuse texture | 复杂 UV、程序化节点 | 只使用资产已有资源 |
+| OmniPBR ORM | 已转换（受限） | raw ORM 的粗糙度 G、金属度 B、影响权重 | 非 raw、复杂 UV、无效资源 | 通道重排和线性混合需可确定 |
+| OmniPBR AO | 有界近似 | 有效 AO 纹理、raw、支持 UV、`aoMapIntensity` | OmniPBR AO 对漫反射的精确调制；`aoMap` 是 Three.js 间接光近似 | `ao_to_diffuse=0` 不报有效缺失 |
+| OmniPBR 法线 / bump | 有界近似 | 已有法线纹理、强度和切线方向的受限映射 | 复杂节点、未知切线约定 | 缺失法线不生成替代 |
+| OmniGlass 常量薄壁 | 有界近似 | IOR、粗糙度、表面透射、覆盖率、反射颜色、受限法线纹理 | MDL 完整执行、复杂纹理和多层光学 | 保留 DoubleSide 策略边界，不改普通材质 |
+| OmniGlass `cutout_opacity` | 已转换（常量） | `enable_opacity`、常量覆盖率、阈值边界 | opacity 纹理和复杂连接 | 覆盖率不当作 transmission |
+| OmniGlass 实体玻璃 | 未适配关键效果 | 表面透射和可表达的 IOR/粗糙度 | 体积吸收、`depth` 对应的光程、实体颜色 | 不把 `depth` 当 thickness 或 attenuationDistance |
+| 玻璃 DoubleSide 策略 | 已转换（有条件） | 透射材质：显式 `doubleSided=false` 用 FrontSide；true 或未声明用 DoubleSide | 未能读取源属性时不猜测 | 其他材质保持原有 side |
+
+## 当前明确不伪造的内容
+
+- 缺失或无法解码的纹理、法线、粗糙度、AO 和 ORM 资源；
+- 未知 MDL / MaterialX 节点的输出；
+- OmniGlass / MaterialX 的实体内部光程、体积吸收和真实壁厚；
+- 不能从几何确定的 `thickness`、`attenuationDistance` 或吸收距离；
+- 通过修改背景、排序、颜色或强制双面制造“看起来更像”的资产特例；
+- 把 Storm、Three.js 实时结果或 Loader 成功解析当作 Cycles、RTX 或 Karma 的最终真值。
+
+## 验证范围
+
+当前回归覆盖常量透明、`presence`、阈值裁切、纯金属透明、MaterialX 薄壁/实体边界、OmniPBR ORM/AO 受限路径、OmniGlass 常量参数、法线纹理和玻璃单双面策略。
+
+测试通过只表示代码路径和诊断契约符合预期，不表示所有 USD 材质与源渲染器逐像素一致。对于复杂资产，仍需结合源材质终端、资源清单和目标渲染器单独判断。

package/dist/assets/types.d.ts

@@ -3,7 +3,7 @@ import type { Object3D, WebGLRenderer, Scene, Camera, Box3, ColorRepresentation
 import type { CadLoadSource, CadOpenOptions } from '../cad/types';
 import type { ViewerViewMode } from '../types';
 export type AssetPreviewKind = 'cad' | 'model' | 'simulation';
-export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'fbx' | 'urdf' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
+export type BuiltinAssetFormat = 'cad' | 'glb' | 'gltf' | 'fbx' | 'urdf' | 'xacro' | 'mjcf' | 'usd' | 'usda' | 'usdc' | 'usdz';
 export type AssetFormat = BuiltinAssetFormat | (string & {});
 export interface AssetFileEntry {
     readonly path: string;
@@ -26,6 +26,12 @@ export interface ViewerAssetOptions {
     readonly mujocoBaseUrl?: string;
 }
 export interface OpenAssetOptions {
+    /** Browser Xacro subset; unsupported Python/ROS features fail explicitly. */
+    readonly xacro?: {
+        readonly arguments?: Readonly<Record<string, string | number | boolean>>;
+        /** ROS package name -> directory relative to the asset package/baseUrl. */
+        readonly packages?: Readonly<Record<string, string>>;
+    };
     readonly simulationTheme?: 'dark' | 'light';
     readonly format?: AssetFormat | 'auto';
     readonly filename?: string;