USD decoder: PhysicsFilteredPairsAPI fails or is ignored for collider endpoints, and newton:selfCollisionEnabled is not read

オープン
#3,917 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 6 日以内に返信

@TianqiTang1117 がすでに取り組んでいます。

2026年11月18日 から。

  • #3918 @TianqiTang1117 による — オープン

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
49/100
issue の種類
バグ
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
cpp, python
領域
backend

調査の方向性

Start in plugin/usd_decoder with ParseUsdFilteredPairsAPI, ParseUsdPhysicsRigidbody, and ParseNewtonArticulationRootAPI; the issue identifies these entry points but no test file. Trace how filtered-pair targets become MuJoCo excludes and how articulation bodies are collected, then add regression coverage for the five reproduction cases. Done means valid collider pairs no longer fail or get ignored, and disabled Newton self-collisions produce no contacts between non-parent-child articulation bodies.

索引モデルが issue の本文から書いたものです。

説明

Summary

The USD decoder only handles PhysicsFilteredPairsAPI when it is applied to a rigid body and targets another rigid body. Other forms that UsdPhysics allows either fail to compile the whole model or are silently ignored. Separately, newton:selfCollisionEnabled on NewtonArticulationRootAPI is declared in newton_tokens.h but never read.

Verified at runtime with the mujoco-usd 4.0.1 wheel. plugin/usd_decoder is unchanged on main since the 4.0.1 tag.

Details

UsdPhysics says "The FilteringPairsAPI can be applied to objects with a UsdPhysicsRigidBodyAPI, UsdPhysicsCollisionAPI, or UsdPhysicsArticulationRootAPI", and that a relationship from A to B implies the one from B to A (overview.dox, and the PhysicsFilteredPairsAPI schema doc: "can be applied either to a body or collision or even articulation").

ParseUsdFilteredPairsAPI is only called from ParseUsdPhysicsRigidbody, and copies each target path into mjsExclude::bodyname2. So:

Authored Result
Rigid body → rigid body <exclude>, correct
Rigid body → static collider (e.g. a floor) Compile error: body '/World/floor' not found in bodypair 0
Rigid body → collider under another rigid body Compile error: body '/World/A/geom' not found in bodypair 0
API applied on a collider Ignored; the pair still collides

The compile errors are the worst part: a single spec-valid filtered pair makes the whole stage fail to load.

For self collisions, ParseNewtonArticulationRootAPI reads newton:jointsAddMobility but not newton:selfCollisionEnabled. The Newton schema (v0.4.0, the version MuJoCo pins) defines false as "equivalent to applying PhysicsFilteredPairsAPI relationships between all bodies in the articulation", so there is a direct MuJoCo equivalent: an <exclude> for each pair of bodies in the articulation.

Why it matters
  • Collider-level filtered pairs are valid UsdPhysics, and one of them is enough to make the whole stage fail to load in MuJoCo. Filtering a body against a static collider such as a floor is a common case.
  • When the API is applied on a collider, the filtering is silently lost, so the model loads but generates contacts the asset explicitly disabled.
  • newton:selfCollisionEnabled = false is the Newton schema's way to disable self collisions for an articulation, and MuJoCo already parses NewtonArticulationRootAPI. Ignoring it silently re-enables self collisions.
Request
  1. Resolve each filtered-pair endpoint to the colliders it covers: a rigid body to its colliders, a collider to itself, a static collider to that geom on the world body, and an articulation root to all colliders in the articulation. When both sides cover whole MuJoCo bodies, emit <exclude> as today, using world for static colliders when the pair covers all of the world body's colliders.
  2. Parse PhysicsFilteredPairsAPI on colliders and articulation roots as well as rigid bodies.
  3. For collider-level pairs that <exclude> can't express, set contype/conaffinity on the affected geoms, or at minimum warn and skip the pair instead of failing to compile.
  4. For newton:selfCollisionEnabled = false, add an <exclude> for each pair of bodies in the articulation. Parent-child pairs are already filtered by default, so those can be skipped.
Reproduction

pip install mujoco-usd==4.0.1, then:

repro.py
import tempfile

import mujoco
import mujoco._usd  # registers the USD decoder plugin
from pxr import Gf, Sdf, Usd, UsdGeom, UsdPhysics


def collider(stage, path, pos, body=True):
    prim = UsdGeom.Sphere.Define(stage, path)
    prim.CreateRadiusAttr(0.1)
    prim.AddTranslateOp().Set(Gf.Vec3d(*pos))
    if body:
        UsdPhysics.RigidBodyAPI.Apply(prim.GetPrim())
    UsdPhysics.CollisionAPI.Apply(prim.GetPrim())
    return prim.GetPrim()


def stage_for(case):
    stage = Usd.Stage.CreateInMemory()
    UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)
    stage.SetDefaultPrim(UsdGeom.Xform.Define(stage, "/World").GetPrim())
    UsdPhysics.Scene.Define(stage, "/World/scene")
    floor = UsdGeom.Cube.Define(stage, "/World/floor")
    floor.AddTranslateOp().Set(Gf.Vec3d(0, 0, -1))
    UsdPhysics.CollisionAPI.Apply(floor.GetPrim())  # static collider
    if case == "selfCollisionEnabled":
        links = [collider(stage, f"/World/L{i}", (x, 0, 1)) for i, x in enumerate((0.0, 0.15, 0.05))]
        UsdPhysics.ArticulationRootAPI.Apply(links[0])
        links[0].ApplyAPI("NewtonArticulationRootAPI")
        links[0].CreateAttribute("newton:selfCollisionEnabled", Sdf.ValueTypeNames.Bool).Set(False)
        for name, b0, b1, p0, p1 in (("j01", 0, 1, 0.075, -0.075), ("j12", 1, 2, -0.05, 0.05)):
            joint = UsdPhysics.RevoluteJoint.Define(stage, f"/World/{name}")
            joint.CreateBody0Rel().AddTarget(links[b0].GetPath())
            joint.CreateBody1Rel().AddTarget(links[b1].GetPath())
            joint.CreateLocalPos0Attr(Gf.Vec3f(p0, 0, 0))
            joint.CreateLocalPos1Attr(Gf.Vec3f(p1, 0, 0))
            joint.CreateAxisAttr("Z")
        return stage
    a = UsdGeom.Xform.Define(stage, "/World/A")
    a.AddTranslateOp().Set(Gf.Vec3d(0, 0, 0.05))
    UsdPhysics.RigidBodyAPI.Apply(a.GetPrim())
    geom_a = collider(stage, "/World/A/geom", (0, 0, 0), body=False)
    b = collider(stage, "/World/B", (0.1, 0, 0.05))
    source, target = {
        "body -> body": (a.GetPrim(), "/World/B"),
        "body -> static collider": (a.GetPrim(), "/World/floor"),
        "body -> collider of a body": (b, "/World/A/geom"),
        "collider -> body": (geom_a, "/World/B"),
    }[case]
    UsdPhysics.FilteredPairsAPI.Apply(source).CreateFilteredPairsRel().AddTarget(target)
    return stage


for case in ("body -> body", "body -> static collider", "body -> collider of a body", "collider -> body", "selfCollisionEnabled"):
    path = tempfile.mkdtemp() + "/scene.usda"
    stage = stage_for(case)
    stage.GetRootLayer().Export(path)
    try:
        model = mujoco.MjSpec.from_file(path).compile()
    except Exception as e:
        print(f"{case:28} compile error: {str(e).splitlines()[0]}")
        continue
    data = mujoco.MjData(model)
    mujoco.mj_forward(model, data)
    name = lambda g: mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_BODY, int(model.geom_bodyid[g])) or "world"
    pairs = sorted({tuple(sorted((name(c.geom1), name(c.geom2)))) for c in data.contact[: data.ncon]})
    print(f"{case:28} nexclude={model.nexclude} contacts={pairs}")
body -> body                 nexclude=1 contacts=[('/World/A', 'world'), ('/World/B', 'world')]
body -> static collider      compile error: Error: body '/World/floor' not found in bodypair 0
body -> collider of a body   compile error: Error: body '/World/A/geom' not found in bodypair 0
collider -> body             nexclude=0 contacts=[('/World/A', '/World/B'), ('/World/A', 'world'), ('/World/B', 'world')]
selfCollisionEnabled         nexclude=0 contacts=[('/World/L0', '/World/L2')]

The last two rows should have no contact between /World/A and /World/B, and none between /World/L0 and /World/L2.

Environment

mujoco 4.0.1, mujoco-usd 4.0.1, usd-core 25.11, newton-usd-schemas 0.7.0, Python 3.12, Linux x86_64 (Ubuntu, kernel 6.8).

主要言語
C++
スター
18.3k
フォーク
2.2k
平均マージ
9日 11時間
マージ済み PR(30日)
5

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

google-deepmind/mujoco のほかの issue

google-deepmind/mujoco の issue をすべて見る

似ている issue

C++ の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。