模式配置类

模式配置类#

Isaac Lab 的生成器通过分层配置类，将 USD 物理属性写入 prim。分层结构区分 通用物理 参数与 后端特有 参数，使同一资产配置只需编写一次，就能用于所有支持它的后端。

本页介绍类的继承关系、各层的适用场景，以及参数如何对应到底层 USD 属性。

从 2.x 迁移？请参阅 3.0 迁移指南中的 模式配置类重构 。

快速示例#

为关节体资产添加 MuJoCo（MJC）重力补偿：

import isaaclab.sim as sim_utils
from isaaclab_newton.sim.schemas import (
    MujocoRigidBodyPropertiesCfg,
    MujocoJointDrivePropertiesCfg,
)

spawn = sim_utils.UsdFileCfg(
    usd_path=f"{ISAAC_NUCLEUS_DIR}/Robots/Franka/franka_instanceable.usd",
    rigid_props=MujocoRigidBodyPropertiesCfg(gravcomp=1.0),
    joint_drive_props=MujocoJointDrivePropertiesCfg(actuatorgravcomp=True),
)

MuJoCo 特有字段写入 prim 的 mjc:* 命名空间；在同一实例上设置的 RigidBodyBaseCfg / JointDriveBaseCfg 字段则写入 physics:* 。完整规则见 在单个实例上写入多个命名空间 。

类的继承关系#

对于各属性组（刚体、关节驱动、碰撞、关节体根节点、材质和网格碰撞），Isaac Lab 在核心包 isaaclab.sim.schemas 中定义一个基类，并在对应扩展包中为各后端定义子类：

isaaclab.sim.schemas
├── RigidBodyBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxRigidBodyPropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonRigidBodyPropertiesCfg
│       └── isaaclab_newton.sim.schemas.MujocoRigidBodyPropertiesCfg
│
├── JointDriveBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxJointDrivePropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonJointDrivePropertiesCfg
│       └── isaaclab_newton.sim.schemas.MujocoJointDrivePropertiesCfg
│
├── CollisionBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxCollisionPropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonCollisionPropertiesCfg
│       ├── isaaclab_newton.sim.schemas.NewtonMeshCollisionPropertiesCfg
│       └── isaaclab_newton.sim.schemas.NewtonSDFCollisionPropertiesCfg
│
├── ArticulationRootBaseCfg
│   ├── isaaclab_physx.sim.schemas.PhysxArticulationRootPropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonArticulationRootPropertiesCfg
│
├── MeshCollisionBaseCfg
│   ├── isaaclab_physx.sim.schemas.{PhysxConvexHull, PhysxConvexDecomposition,
│   │                                PhysxTriangleMesh, PhysxSDFMesh, ...}PropertiesCfg
│   └── isaaclab_newton.sim.schemas.NewtonMeshCollisionPropertiesCfg
│       (also inherits NewtonCollisionPropertiesCfg — multi-namespace)
│
└── isaaclab.sim.spawners.materials.RigidBodyMaterialBaseCfg
    ├── isaaclab_physx.sim.spawners.materials.PhysxRigidBodyMaterialCfg
    └── isaaclab_newton.sim.schemas.NewtonMaterialPropertiesCfg

NewtonMeshCollisionPropertiesCfg 使用多重继承，同时继承 NewtonCollisionPropertiesCfg （提供 contact_margin / contact_gap ）和 MeshCollisionBaseCfg （提供 mesh_approximation_name ）。这是 在单个实例上写入多个命名空间 所述按声明类及 MRO 进行属性分发的典型案例：每个继承字段都写入声明该字段的类所对应的命名空间。 NewtonSDFCollisionPropertiesCfg 以碰撞配置为根，因此编写 NewtonSDFCollisionAPI 时，不会同时应用 UsdPhysics.MeshCollisionAPI 或设置 physics:approximation 。

该继承体系 在每个生成器配置槽位上只有一个根类 ：各生成器为每个属性组提供一个字段（ rigid_props 、 joint_drive_props 、 collision_props 等）。Python 的多态允许在期望基类的位置传入任意子类。

何时使用哪种类#

选择取决于目标后端和所需字段。

使用基类 （ RigidBodyBaseCfg 、 JointDriveBaseCfg 等）

适用于只需要通用物理字段，并希望资产配置可跨后端使用的情况。导入基类不会连带导入 isaaclab_physx 或 isaaclab_newton 。

使用 PhysX 子类 （ PhysxRigidBodyPropertiesCfg 等）

适用于目标为 PhysX 后端、且资产需要 PhysX 特有参数的情况，例如逐刚体阻尼、TGS 求解器迭代次数、休眠/稳定化阈值、扭转接触面摩擦和柔顺接触材质等。子类继承全部基类字段，因此可在同一实例上同时设置通用和 PhysX 字段。

使用 Newton 子类 （ NewtonRigidBodyPropertiesCfg 等）

适用于目标为 Newton，且需要 newton:contactMargin 、 newton:torsionalFriction 、 newton:selfCollisionEnabled 等 Newton 原生属性的情况。空的 Newton 基类（ NewtonRigidBodyPropertiesCfg 、 NewtonJointDrivePropertiesCfg ）为未来原生字段预留 newton:* 命名空间，并作为求解器特有子类的父类。

使用 MuJoCo 子类 （ MujocoRigidBodyPropertiesCfg 、 MujocoJointDrivePropertiesCfg ）

适用于明确使用 Newton 的 MuJoCo 求解器，且需要 MuJoCo 专属参数的情况，例如通过 mjc:gravcomp / mjc:actuatorgravcomp 实现重力补偿。它继承 Newton 基类，因此 isinstance(cfg, NewtonRigidBodyPropertiesCfg) 为 True。

参数分别属于哪些类#

备注

下表概括各配置类包含的字段。权威来源是自动生成的 API 参考： isaaclab.sim.schemas 、 isaaclab_physx.sim.schemas 和 isaaclab_newton.sim.schemas 直接呈现配置类的文档字符串。这些表格仅供查找；如果与源代码不一致，以 API 文档为准。

通用物理（在基类上声明）#

位于 基类 。大多数字段写入 physics:* （标准 UsdPhysics.*API 命名空间），但少数“例外”字段为了跨后端可用而声明在基类上，实际却写入其他命名空间，因为目前只有这些 USD 路径受到支持。例如， disable_gravity 写入 physxRigidBody:disableGravity ，因为 PhysX 和 Newton 导入器都会读取这个 PhysX 属性。下表的“USD 属性”列给出实际写出的属性，而非命名空间类别。

基类

字段

USD 属性

RigidBodyBaseCfg

rigid_body_enabled, kinematic_enabled

physics:rigidBodyEnabled, physics:kinematicEnabled

RigidBodyBaseCfg

disable_gravity

physxRigidBody:disableGravity （PhysX 按刚体生效；Newton 在场景层面部分支持）

CollisionBaseCfg

collision_enabled

physics:collisionEnabled

CollisionBaseCfg

contact_offset, rest_offset

physxCollision:contactOffset 、 physxCollision:restOffset （Newton 通过 PhysX 桥接读取）

ArticulationRootBaseCfg

articulation_enabled

physxArticulation:articulationEnabled

ArticulationRootBaseCfg

fix_root_link

生成 UsdPhysics.FixedJoint （在写入端处理，不是 USD 属性）

JointDriveBaseCfg

drive_type, max_force, stiffness, damping

drive:<axis>:physics:type/maxForce/stiffness/damping

JointDriveBaseCfg

max_joint_velocity

physxJoint:maxJointVelocity （唯一的 USD 路径；Newton 目前通过 PhysX 桥接读取）

JointDriveBaseCfg

ensure_drives_exist

仅在写入端处理 — 为 True 时，确保所有 stiffness=0 且 damping=0 的驱动具有最小 stiffness=1e-3 ，使 Newton 等后端将关节识别为主动驱动；本身不是独立的 USD 属性

MassPropertiesCfg

mass, density

physics:mass, physics:density

RigidBodyMaterialBaseCfg

static_friction, dynamic_friction, restitution

physics:staticFriction, physics:dynamicFriction, physics:restitution

MeshCollisionBaseCfg

mesh_approximation_name

physics:approximation

PhysX 特有（ physx*:* 命名空间， Physx*API 模式）#

位于 PhysX 子类。只有用户在 PhysX 配置中显式设置字段时才写入。

PhysX 子类

字段（部分）

USD 命名空间 / 模式

PhysxRigidBodyPropertiesCfg

linear_damping 、 angular_damping 、 max_linear_velocity 、 max_angular_velocity 、 solver_position_iteration_count 、 sleep_threshold 、 enable_gyroscopic_forces 等

physxRigidBody:* / PhysxRigidBodyAPI

PhysxJointDrivePropertiesCfg

（目前为空，为未来的 PhysX 专属驱动参数预留）

physxJoint:* / PhysxJointAPI

PhysxCollisionPropertiesCfg

torsional_patch_radius, min_torsional_patch_radius

physxCollision:* / PhysxCollisionAPI

PhysxArticulationRootPropertiesCfg

enabled_self_collisions, solver_position_iteration_count, sleep_threshold, stabilization_threshold

physxArticulation:* / PhysxArticulationAPI

PhysxRigidBodyMaterialCfg

compliant_contact_stiffness, compliant_contact_damping, friction_combine_mode, restitution_combine_mode

physxMaterial:* / PhysxMaterialAPI

PhysxConvexHullPropertiesCfg （以及其他网格预处理子类）

hull_vertex_limit 、 min_thickness 等

physxConvexHullCollision:* / PhysxConvexHullCollisionAPI

面向 Newton（ newton:* 命名空间， Newton*API 模式）#

位于 Newton 子类。仅在用户显式设置时写入。

Newton 子类

字段

USD 命名空间 / 模式

NewtonRigidBodyPropertiesCfg

（为空，为未来的 Newton 原生刚体字段预留）

newton:*

NewtonJointDrivePropertiesCfg

（为空，为未来的 Newton 原生关节驱动字段预留）

newton:*

NewtonCollisionPropertiesCfg

contact_margin, contact_gap

newton:* / NewtonCollisionAPI

NewtonMeshCollisionPropertiesCfg

max_hull_vertices

newton:* / NewtonMeshCollisionAPI

NewtonSDFCollisionPropertiesCfg

sdf_max_resolution 、 sdf_target_voxel_size 、 sdf_texture_format 、 hydroelastic_enabled 等

newton:* / NewtonSDFCollisionAPI

NewtonMaterialPropertiesCfg

torsional_friction, rolling_friction

newton:* / NewtonMaterialAPI

NewtonArticulationRootPropertiesCfg

self_collision_enabled

newton:* / NewtonArticulationRootAPI

MuJoCo 求解器特有（ mjc:* 命名空间）#

位于继承 Newton 子类的 MuJoCo 子类。仅在运行 Newton 的 MuJoCo 求解器时读取。

MuJoCo 子类

字段

USD 属性 / 模式

MujocoRigidBodyPropertiesCfg

gravcomp

mjc:gravcomp （原始属性，不应用模式）

MujocoJointDrivePropertiesCfg

actuatorgravcomp

通过 MjcJointAPI 写入 mjc:actuatorgravcomp

备注

这两个 MuJoCo 条目对 USD 应用模式的要求不同： mjc:actuatorgravcomp 属于已注册的 MjcJointAPI 应用模式，因此字段不是 None 时，写入器会调用 prim.AddAppliedSchema("MjcJointAPI") 。刚体级重力补偿的 mjc:gravcomp 没有已注册的 Mjc 应用模式，因此写入器将其写为原始 USD 属性。Newton 的 MuJoCo 求解器通过同一解析路径读取两者；应用模式的区别仅是 USD 端的细节。

在单个实例上写入多个命名空间#

由于各配置字段分发到 声明该字段的类 对应的命名空间，而非实例所属类的命名空间，子类实例可以在同一 prim 上写入多个命名空间的属性。例如：

from isaaclab_newton.sim.schemas import MujocoRigidBodyPropertiesCfg

cfg = MujocoRigidBodyPropertiesCfg(
    rigid_body_enabled=True,        # declared on RigidBodyBaseCfg → physics:rigidBodyEnabled
    disable_gravity=True,            # declared on RigidBodyBaseCfg (exception) → physxRigidBody:disableGravity
    gravcomp=1.0,                    # declared on MujocoRigidBodyPropertiesCfg → mjc:gravcomp
)

写入器将各字段应用到声明该字段的类对应的命名空间。只有相应字段不是 None 时，才添加应用模式（ disable_gravity 使用 PhysxRigidBodyAPI ；Mjc 原始属性没有应用模式）。

生成器用法#

生成器（ UsdFileCfg 、 MeshCuboidCfg 、 MeshSphereCfg 等）的各槽位接受基类类型，并在写入时通过多态分发到正确的子类：

import isaaclab.sim as sim_utils
from isaaclab_physx.sim.schemas import PhysxRigidBodyPropertiesCfg
from isaaclab_newton.sim.schemas import MujocoJointDrivePropertiesCfg

spawn = sim_utils.UsdFileCfg(
    usd_path="...",
    rigid_props=PhysxRigidBodyPropertiesCfg(disable_gravity=True, linear_damping=0.1),
    joint_drive_props=MujocoJointDrivePropertiesCfg(
        drive_type="acceleration",
        stiffness=10.0,
        damping=0.1,
        actuatorgravcomp=True,
    ),
)

重力补偿（MuJoCo 求解器）#

重力补偿包含两部分，通常两者都需要：

  • 刚体级 ：各刚体上的 gravcomp （写入 mjc:gravcomp ），负责 计算 补偿力。

  • 关节级 ：各关节上的 actuatorgravcomp （写入 mjc:actuatorgravcomp ）。它将补偿力分配到执行器通道（ qfrc_actuator ），使其计入 actuatorfrcrange ；否则补偿力进入 qfrc_passive 。

仅设置 actuatorgravcomp=True 不会起作用 — 没有刚体级 gravcomp ，就没有可分配的力。为避免这一问题，当 joint_drive_props 是设有 actuatorgravcomp=True 的 Mujoco 配置，且 rigid_props 尚非 Mujoco 配置时，生成器会 自动启用 MujocoRigidBodyPropertiesCfg(gravcomp=1.0) 。如需其他 gravcomp 值，或希望禁用自动启用行为，请在 rigid_props 中显式传入 MujocoRigidBodyPropertiesCfg 。

命名约定#

配置字段名使用 snake_case ；写入器将其转换为 camelCase 的 USD 属性名（ contact_margin → newton:contactMargin ）。单词字段（ gravcomp 、 actuatorgravcomp ）转换后保持不变，符合 MuJoCo 的小写约定。

字段重命名通过弃用别名保持向后兼容。目前 JointDriveBaseCfg 中有两个这样的别名：

  • max_velocity → max_joint_velocity （USD 属性为 physxJoint:maxJointVelocity ）

  • max_effort → max_force （USD 属性为 drive:<axis>:physics:maxForce ）

旧名称仍作为真正的数据类字段保留（因此 dataclasses.fields() 能看到它们），默认值为 None 。 __post_init__ 运行 deprecate_field_alias ：如果设置了旧字段，会发出 DeprecationWarning ；规范字段为 None 时，将旧值复制到规范字段，然后清空旧字段。如果在同一构造函数中 同时设置两者 ，则不发出警告，以规范字段为准，丢弃旧名称的值。这两个别名计划在 4.0 中移除。

另请参阅#

目录