Skip to content

Fix: Migrate suction margin/gap for MuJoCo 3.9 contact semantics - #811

Draft
danwahl wants to merge 1 commit into
mainfrom
bump-mujoco-3.10
Draft

danwahl wants to merge 1 commit into
mainfrom
bump-mujoco-3.10

Conversation

@danwahl

@danwahl danwahl commented Jul 26, 2026

Copy link
Copy Markdown

Motivation

MuJoCo 3.9 redesigned the contact margin and gap geom attributes, and every suction site here still uses the pre-3.9 idiom. PickNikRobotics/moveit_pro#22404 takes the bundled runtime to 3.13.0, past that change.

Brief description

Detection moved from dist < margin to dist < margin + gap, and force from dist < margin - gap to dist < margin. All five sites use margin == gap, the idiom for sensing a part without pushing it away, which under the new semantics generates force from a full margin out.

Applies the upstream migration margin_new = margin_old - gap_old, zero at every site, with gap unchanged. factory_sim's override="enable" forces every margin to o_margin, so its edits are inert there; kept for consistency.

Merge order

  • PickNikRobotics/moveit_pro#22404 merged first

Correct only against the 3.13.0 runtime that PR brings in. Under the 3.6 shipping today this reads as detection at 0, so cups stop sensing parts until they interpenetrate.

How it was tested

Separation sweep against a multi-geom target, stepping 10 µm, reading the outermost separation that registers a contact and the outermost that registers a force-generating one. Single-geom pairs skip MuJoCo's midphase, so the target carries five geoms.

runtime margin gap detection force
3.6.0, shipping today 10 mm 10 mm 9.99 mm penetration only
3.13.0, this PR 0 10 mm 9.99 mm penetration only
3.13.0, unmigrated 10 mm 10 mm 19.99 mm 9.99 mm
3.6.0, shipping today 20 mm 20 mm 19.99 mm penetration only
3.13.0, this PR 0 20 mm 19.99 mm penetration only
3.13.0, unmigrated 20 mm 20 mm 39.99 mm 19.99 mm

3.13.0 with these edits reproduces 3.6.0 exactly at both site sizes. Without them the cup generates force from a full margin out, which is the suction cup pushing the part away before it touches.

Every scene in the affected packages that loads standalone compiles on 3.13.0: factory_sim/description/scene.xml (179 geoms), hangar_sim/description/hangar_scene.xml (306), and hangar_sim/description/ur5e_ridgeback.xml (76). hangar_sim/description/hangar.xml is an include fragment and does not load standalone on 3.6.0 either. All five migrated geoms compile to margin = 0 with gap intact, detection at gap and force at contact.

The 3.10 pairing also needed a body_margin workaround alongside these edits: MuJoCo 3.9 and 3.10 compute body_margin without gap, culling multi-geom bodies at the midphase before the leaves that would detect them, which is the shape every site here migrates to. Measured on 3.10 these geoms give body_margin = 0 and detection collapses to contact. Upstream folded gap into body_margin in 3.11.0, so on 3.13 every migrated body reports body_margin = margin + gap and no workaround is needed.

Release notes

None. The user-facing migration guidance ships with PickNikRobotics/moveit_pro#22404.

MuJoCo 3.9 redesigned contact margin/gap. Detection moved from `dist < margin`
to `dist < margin + gap`, and force generation from `dist < margin - gap` to
`dist < margin`.

All five suction sites here use margin == gap, the idiom for "detect early but
only apply force on true contact". Under the new semantics that same markup
generates force from a full margin away, so the cups push parts off before
touching them. Measured with margin = gap = 0.02: on 3.6 a 15 mm separation is
detected with no force, on 3.10 it is force-generating.

Applies the upstream migration, margin_new = margin_old - gap_old, which is 0 at
every site since margin equals gap. This is the same markup upstream migrated its
own adhesion demo to.

Ordering: this markup only behaves correctly on MuJoCo 3.10 or newer. Under 3.6
it reads as detection at 0 and force at -gap, so the cups stop sensing parts
until they interpenetrate. Merge this only once moveit_pro ships the 3.10 bump,
which also carries the widen_body_margin_for_gap change that restores detection
on multi-geom bodies.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012DpJinnRQknbm62X7GCveK
@coderabbitai

coderabbitai Bot commented Jul 26, 2026

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d9eea250-fc18-44a9-9d2a-c88e9f50b565

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown

MoveIt Pro Example WS - Objectives Integration Test Report

@danwahl danwahl added this to the 10.0.0 milestone Jul 26, 2026
@JWhitleyWork

Copy link
Copy Markdown
Member

Please re-target to v10.0 branch.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants