USD Physics Visualizer

在 VS Code 内检查 USD 机器人：三维模型、物理关节、碰撞几何、质心、惯量主轴与等效惯量椭球。无需启动 Isaac Sim。

当前版本 0.1.4 使用英文插件名称和简体中文界面，包含命令、设置、提示和诊断说明。USD 原始节点名、路径和属性键保持原值，方便对照文件。已采用“机械连杆”Logo 作为插件图标与预览页标识，发布图标为 512×512 像素。更新内容见 CHANGELOG.md。

Marketplace 发布

当前安装包使用 Marketplace 上传页面确认的发布者标识 HaibeiNan，扩展标识为 HaibeiNan.usd-physics-visualizer。清单中的 publisher 必须匹配上传页面选择的发布者标识，不能用其他账号或资料中的 UUID 替代。

在 Marketplace 发布者管理页 登录拥有该发布者权限的账号，选择对应发布者，再选择 New extension → Visual Studio Code，上传 release/usd-physics-visualizer-0.1.4.vsix。本地打包不会自动将插件发布到市场；上传页面会校验发布者身份。后续更新需提高 package.json 的版本号再打包上传。

如果此前安装了 local-robotics 或 UUID 发布者的开发包，安装本版本前请先卸载对应开发版，避免两个扩展同时注册相同命令。

安装和第一次使用

1. 在 VS Code 扩展面板选择 … → Install from VSIX…，安装发布目录中的 usd-physics-visualizer-0.1.4.vsix。
2. 运行命令 USD Physics Visualizer：安装或检查运行环境。需要本机有 Python 3.9+；插件会在自己的存储目录建立独立环境，安装 usd-core==25.11，不修改系统 Python。首次安装需要网络和可用的 Python venv。
3. 右键 .usd、.usda、.usdc 或 .usdz → USD Physics Visualizer：打开预览。也可以通过 Reopen Editor With… → USD Physics Visualizer 打开。
4. 运行 USD Physics Visualizer：打开机器人示例 可以检查随插件附带的机械臂和各项功能。

也可以通过终端安装：

code --install-extension /绝对路径/usd-physics-visualizer-0.1.4.vsix

如果已有 OpenUSD 环境，直接配置 Python 可执行文件，跳过自动安装：

{
  "usdPhysics.pythonPath": "/path/to/environment/bin/python"
}

该解释器需要能执行 from pxr import Usd, UsdGeom, UsdPhysics。这里填写 Python 可执行文件路径，不能填写带参数的 shell 命令。Isaac Sim 自带的 Python 如果需要专门的启动脚本，优先另建普通 Python 环境并安装 usd-core。

远程 SSH

在连接目标服务器后，把 VSIX 安装到 SSH 主机 的扩展区域。插件的解析进程运行在远端，模型文件和相对引用也在远端解析；WebGL 视口在本地 VS Code 中显示。Python 路径设置在远端设置中，例如服务器上的 venv / Conda 解释器。启动命令与本地相同，远端无需桌面环境或 GPU。

如果希望双击直接预览，可自行添加：

{
  "workbench.editorAssociations": {
    "*.usd": "usdPhysics.preview",
    "*.usda": "usdPhysics.preview",
    "*.usdc": "usdPhysics.preview",
    "*.usdz": "usdPhysics.preview"
  }
}

插件默认保留文件的原有打开方式。

设置自动预览后，关闭已经打开的文本标签页，再重新打开文件；已有标签页不会自动切换。

使用

刷新会保留相机、选中项、图层开关和预览姿态。切换时间采样时以该采样的原始姿态为准。“源文件”对 USDA 打开并排文本；二进制 USD 的属性在属性面板中查看。

数据含义与支持范围

• 使用官方 OpenUSD 场景组合读取层、引用、载荷、变体和实例代理。原始 USD 层级不等于机器人关节拓扑；运动预览按 physics:body0/body1 和关节局部坐标系计算。
• 支持网格（包含凹多边形、左右手拓扑、法线和空洞面）、立方体、球体、圆柱体、胶囊体、圆锥体和平面。保留变换、resetXformStack、可见性和显示色，读取预览表面材质的基础漫反射颜色与不透明度。
• 视口统一以米为单位、Y 轴向上显示，属性保留 USD 局部坐标；质量与惯量面板转换为 kg 和 kg·m²。转动关节以度输入，移动关节使用场景距离单位。
• 支持树形拓扑中的固定、转动和移动关节运动，也能沿相反关系遍历分支。使用原始装配姿态作为参考，再应用关节坐标增量。
• 质心和惯量只绘制文件中已有的有效值。质量默认零、质心负无穷、零惯量、零主轴四元数都按“自动 / 未指定”处理。椭球要求质量、正定对角惯量、质心和主轴完整，表示具有相同质量和惯量的均匀实心椭球。
• 碰撞叠加显示作者提供的几何。convexHull、convexDecomposition、SDF 等近似会显示诊断；不会宣称已经复现 PhysX 最终烹饪结果。
• 闭环、联动关节、球关节 / 距离关节 / D6、缩放刚体坐标系的组件提供结构与属性检查，禁用需要求解器的运动控制。停用的关节不会阻断其他组件的预览。
• 不提供动力学仿真、引擎自动质量计算、蒙皮、PointInstancer、曲线 / NURBS、细分曲面求值、贴图和 MDL 渲染、按面划分的材质子集渲染。相应资产使用基础色或控制网格，并显示诊断。
• 普通相对文件引用和 USDZ 由 OpenUSD 解析。omniverse:// 等专用资源协议需要对应 OpenUSD 资源解析器插件；单独的 usd-core 不包含这些连接器。
• 大网格使用压缩 Float32 / UInt32 缓冲传输；默认上限为 200 万个作者网格三角形，超过后给出错误，可用设置调整。复杂模型仍受本地 WebGL 与可用内存限制。

设置与排错

• 环境失败：查看 输出 → USD Physics Visualizer；确认填写的是当前 SSH 主机上的解释器。手动执行 python -m pip install usd-core==25.11 后配置该 Python。
• 创建环境失败：Linux 发行版可能需要安装 python3-venv。若当前 Python 版本没有对应 usd-core wheel，换用 Python 3.12。实测开发环境为 Python 3.12.4。
• 缺失引用：在诊断页签中查看资源路径，确认引用文件与根文件保持原有目录关系。修复已监视的缺失 / 损坏引用会触发刷新。
• WebGL 初始化失败：检查 VS Code 硬件加速和驱动；远端无需显卡，渲染发生在本地窗口。
• 只看到几何而没有关节：确认资产使用的是 UsdPhysicsJoint，不是仅有动画骨骼的 UsdSkel。
• 插件需要可信工作区和可访问的文件系统。不会在不可信工作区启动解析进程，不支持浏览器版 vscode.dev 的纯 Web 扩展运行方式。

开发与复现验证

需要 Node.js 22、Python 3.12；浏览器和扩展宿主测试使用 Linux、Chromium / Edge、VS Code 与 Xvfb。

npm ci
python3 -m venv .venv
.venv/bin/python -m pip install usd-core==25.11
npm run check
npm test
npm run test:python
npm run build
CHROMIUM_PATH=/path/to/chromium npm run test:browser
npm run test:extension
npm run package
npm run test:packaged
python3 scripts/source-release.py

浏览器验证可加 REAL_ASSET_JSON=/path/to/extracted-stage.json。用 .venv/bin/python python/extract.py /path/to/robot.usd > stage.json 生成。安装包验证可加 USD_TEST_REAL_ASSET=/path/to/S3_22dof.usd，检查真实 S3 模型。扩展宿主和安装包测试在 artifacts/ 下创建独立用户配置、扩展目录和运行环境，避免修改日常 VS Code 配置。源码包包含构建产物，可直接按 F5 启动扩展开发窗口。

验证环境、测试结果和真实资产统计见 VALIDATION.md。

参考

• OpenUSD USD Physics schema
• VS Code Custom Editor API
• URDF Visualizer：交互目标参考；本项目独立实现 USD 解析与物理检查。

代码采用 MIT 许可；第三方组件说明见 THIRD_PARTY_NOTICES.md。