USD 支持参考#

本文档列出 MotrixSim 当前 USD 加载流程支持的主要元素、层级关系和支持状态。

备注

这里的“支持”表示转换器会读取对应 USD schema 或属性，并映射到 MSD / MotrixSim 中已有的语义。本文档是当前转换器的支持契约，不是 USD / Omni schema 的全量属性索引；对于标记为“部分支持”的 schema，只承诺表中列出的子集和主要已知缺口。没有列出的 USD / PhysX / Omni schema 或属性不应假定已支持；转换器通常会对无法表达的属性输出 warning，或跳过没有可用数据的 prim。

状态标记#

标记

含义

支持

核心语义已转换，可作为当前推荐用法

部分支持

只承诺表中列出的子集，或部分属性会被忽略 / warning

未支持

当前不会转换为 MotrixSim 语义

目录#

USD Stage / Assets 部分支持
Scene Prim Hierarchy 部分支持
  • UsdGeom.Xform / instance / instance proxy 支持
  • UsdPhysics.Scene / 刚体属性 部分支持
  • UsdPhysics.RigidBodyAPI 部分支持
  • UsdPhysics.MassAPI 支持
  • ArticulationRootAPI 部分支持
  • UsdPhysics.Joint family 部分支持
  • UsdGeom.Gprim geometry 部分支持
  • UsdLux.LightAPI lights 部分支持
Joints / Drives 部分支持
  • FixedJoint, RevoluteJoint, PrismaticJoint, SphericalJoint 支持
  • PhysicsDriveAPI:angular, PhysicsDriveAPI:linear 部分支持
  • DistanceJoint, PhysicsDriveAPI:transX/rotX... 未支持
Geometry / Meshes / Collision 部分支持
  • Mesh, Cube, Cylinder, Capsule, Sphere, Plane 支持
  • GeomSubset, normals, st texcoords 部分支持
  • CollisionAPI, MeshCollisionAPI, FilteredPairsAPI 部分支持
  • boundingSphere, boundingCube, convexDecomposition 支持
Materials / Textures 部分支持
  • OmniPBR, OmniGlass, UsdPreviewSurface 部分支持
  • PhysicsMaterialAPI, PhysX compliant contact material 部分支持
  • 未知 shader id 未支持
Lights / Environment 部分支持
  • DistantLight, SphereLight, RectLight 支持
  • DomeLight ambient / HDR skybox 部分支持
Unsupported Domains 未支持
  • camera、sensor、tendon、deformable、particle、time-sampled animation 等 schema

入口#

USD / API 元素

状态

MotrixSim 映射

motrixsim.load_model(path)

支持

转换 USD 并直接返回 SceneModel

motrixsim.msd.from_file(path)

支持

转换 USD 并返回可继续编辑、组合的 msd.World

Stage、文件和资产#

USD 元素 / 功能

状态

MotrixSim 映射

.usd / .usda / .usdc / .usdz

支持

使用 OpenUSD Stage.Open 打开

sublayer / reference / payload

部分支持

由 OpenUSD 负责展开；转换器处理展开后的 prim

resolved texture path

支持

转换为 MSD texture file source

相对纹理路径

支持

按 USD 文件所在目录解析

远程纹理 URL

部分支持

下载到本地 cache 后转换

time-sampled stage animation

未支持

当前按默认 time 读取静态场景

场景层级和变换#

USD 元素 / 属性

状态

MotrixSim 映射

UsdGeom.Xform 层级

支持

遍历场景层级并累计世界变换

instance / instance proxy

支持

遍历 instance proxy children

visibility = invisible

支持

不生成视觉几何

purpose = guide

支持

不生成视觉几何；如果同时是 collider，仍可生成碰撞几何

scale / 非均匀 scale

支持

应用到几何尺寸或 mesh_scale

负 scale

支持

翻转 mesh winding，避免背面剔除方向错误

UsdPhysics.RigidBodyAPI

部分支持

创建 Link / Body；非 kinematic 顶层刚体创建 FreeJoint

kinematic rigid body

支持

作为无 free joint 的静态 link 处理

ArticulationRootAPI

部分支持

用于继承 self-collision 设置

物理场景和刚体属性#

USD 元素 / 属性

状态

MotrixSim 映射

UsdPhysics.Scene.gravityDirection + gravityMagnitude

支持

simulate_option.gravity

physxScene:timeStepsPerSecond

支持

simulate_option.timestep

UsdPhysics.MassAPI

支持

读取下列 MassAPI 属性

MassAPI.mass

支持

link.inertial.mass

MassAPI.centerOfMass

支持

link.inertial.pos

MassAPI.diagonalInertia

支持

link.inertial.diag_inertia

MassAPI.principalAxes

支持

link.inertial.orientation

MassAPI.density

支持

collider physics_material.density

physxRigidBody:disableGravity

支持

link.gravcomp = 1.0

physxRigidBody:linearDamping / angularDamping

未支持

输出 warning

physxRigidBody:maxLinearVelocity / maxAngularVelocity

未支持

输出 warning

physxRigidBody:enableCCD / retainAccelerations

未支持

输出 warning

非有限值或非正质量会被忽略并输出 warning。该分组在目录中仍标为“部分支持”，是因为 PhysX 刚体扩展属性仍有未支持项；MassAPI 自身当前列出的属性均已转换。

关节和驱动#

USD joint / 属性

状态

MotrixSim 映射

FixedJoint

支持

转换为无自由度的固定子 link

RevoluteJoint

支持

JointType.Revolute，支持 X/Y/Z axis、limit、reference pose

PrismaticJoint

支持

JointType.Slide，支持 X/Y/Z axis、limit、reference pose

SphericalJoint

部分支持

JointType.Ball，用 cone angle 近似 ball joint limit

DistanceJoint

未支持

输出 warning

PhysicsDriveAPI:angular

部分支持

应用于 revolute joint spring-damper 和 actuator force limit

PhysicsDriveAPI:linear

部分支持

应用于 prismatic joint spring-damper 和 actuator force limit

drive:maxForce

支持

joint.actuator_force_limit，并为一自由度 joint 生成 MotorActuator.forcerange

drive:targetPosition

支持

spring target

drive:stiffness / drive:damping

支持

joint spring-damper

physxJoint:jointFriction

支持

joint.friction_loss

physxJoint:armature

支持

joint.armature

joint:collisionEnabled = false

支持

生成父子 link collision ignore

PhysicsDriveAPI:transX/transY/transZ/rotX/rotY/rotZ

未支持

输出 warning

physxJoint:maxJointVelocity

未支持

输出 warning

几何、网格和碰撞#

USD geometry / 属性

状态

MotrixSim 映射

UsdGeom.Mesh

部分支持

ShapeType.Mesh，mesh 数据内联到 MeshAsset.source = MeshSource::Buffer

Cube

支持

ShapeType.Box

Cylinder

支持

ShapeType.Cylinder

Capsule

支持

ShapeType.Capsule

Sphere

支持

ShapeType.Sphere

Plane

支持

ShapeType.Plane

GeomSubset with elementType = "face"

支持

拆分为按 face subset 的子 mesh，可保留 subset 材质

normals / st texcoords: vertex / varying / faceVarying

支持

读取并展开到 MSD mesh

其他 normal / texcoord interpolation

未支持

输出 warning

CollisionAPI

支持

生成 collider

MeshCollisionAPI

部分支持

可生成 mesh collider；只支持下列 approximation

MeshCollisionAPI.approximation = none

支持

默认 mesh collider

convexHull

支持

默认 mesh collider，不启用运行时 ACD

boundingSphere

支持

从 mesh 包围盒生成 sphere collider

boundingCube

支持

从 mesh 包围盒生成 box collider；可同时保留 visual mesh

convexDecomposition

支持

标记 mesh asset collision_cooking = ConvexDecomposition，并启用 CoACDConfig

未知 MeshCollisionAPI.approximation

未支持

输出 warning，并回退为默认 mesh collider

FilteredPairsAPI

支持

生成 collision ignore pair

physxCollider:contactOffset

支持

geometry.margin

physxCollider:restOffset

未支持

输出 warning

MotrixPhysicsGeomAPI

支持

支持 Motrix 自定义 impedance contact model 和 priority

物理材质、视觉材质和纹理#

USD material / shader

状态

MotrixSim 映射

PhysicsMaterialAPI.staticFriction

支持

sliding friction，torsional / rolling friction 使用固定比例

PhysicsMaterialAPI.dynamicFriction

支持

static friction 未写入时作为 fallback

PhysicsMaterialAPI.density

支持

collider density，优先级低于 MassAPI.density

PhysicsMaterialAPI.restitution

支持

hard contact restitution

physxMaterial:compliantContactStiffness / Damping

支持

force spring 或 acceleration spring contact model

physxMaterial:compliantContactAccelerationSpring

支持

选择 acceleration spring

physxMaterial:dampingCombineMode / frictionCombineMode / restitutionCombineMode

未支持

输出 warning

OmniPBR

部分支持

只转换 diffuse / opacity texture 合并、diffuse tint、emissive、metallic、roughness、specular level、normal、detail normal、opacity threshold、texture scale / translate

OmniGlass

部分支持

只转换 glass color、IOR、reflection color、roughness，转换为透明非金属材质

UsdPreviewSurface

部分支持

只转换 diffuse color / texture、normal、emissive、metallic、roughness、IOR、UsdTransform2d texture transform

可解析的本地 MDL 材质

部分支持

可从本地 MDL fallback 到 OmniPBR / OmniGlass 参数

MaterialBindingAPI

支持

绑定 visual material 或 physics material

doubleSided

部分支持

影响 both_side；alpha blend 材质有深度排序保护

未知 shader id

未支持

输出 warning

灯光和环境#

USD light

状态

MotrixSim 映射

DistantLight

支持

directional light

SphereLight

支持

point light

RectLight

支持

rect light，保留 width、height、axis、normalize、color、exposure 后 intensity

大面积 RectLight

支持

额外提高 ambient brightness，并设置上限

DomeLight without texture

支持

ambient light

DomeLight with .hdr texture

部分支持

烘焙 IBL map，注册 skybox texture

其他 light 类型

未支持

当前不生成 MotrixSim light

当场景中存在 USD light 时，默认 head light 会被关闭，以避免重复照明。转换后的世界默认启用 SSGI。

当前未支持或未覆盖的领域#

USD / PhysX 领域

状态

说明

UsdGeom.Camera

未支持

当前不转换为 MotrixSim camera

sensor schemas

未支持

当前不转换为 MotrixSim sensor

tendon / cable / actuator-like USD schema

未支持

当前只支持 joint drive 到 motor actuator 的子集

deformable / particle / cloth

未支持

MotrixSim 当前 USD 转换链路不处理

time-sampled animation

未支持

当前读取静态场景

未知材质 shader、无法解析的纹理或异常 mesh 数据

部分支持

可能被 warning、跳过或降级处理

对复杂 USD 资产，应在加载时开启 logging，检查 warning 后再进入物理验证。