Skip to content

Fix sibling URDF mimic multiplier relation#297

Open
moonbow721 wants to merge 1 commit into
haosulab:masterfrom
moonbow721:fix-urdf-mimic-sibling-ratio
Open

Fix sibling URDF mimic multiplier relation#297
moonbow721 wants to merge 1 commit into
haosulab:masterfrom
moonbow721:fix-urdf-mimic-sibling-ratio

Conversation

@moonbow721

Copy link
Copy Markdown

Summary

Fix URDF <mimic> constraints for sibling joints with a non-unit multiplier or non-zero offset.

SAPIEN loads URDF <mimic> joints as fixed tendons (python/py_package/wrapper/articulation_builder.py). The two topology branches order their tendon links differently:

  • chain (joint mimics parent): [grandparent, source_child, follower_child]
  • sibling (2 children mimic each other): [root, follower_child, source_child]

but both reuse the same coefficient vector [0, -multiplier, 1]. Because the source-child and follower-child links sit in opposite positions, the -multiplier coefficient lands on the source in the chain case (correct) but on the follower in the sibling case (wrong). The sibling constraint therefore becomes

q_source = multiplier * q_follower + offset
# i.e.  q_follower = (q_source - offset) / multiplier    <- inverted

instead of the intended URDF relation

q_follower = multiplier * q_source + offset

For the common multiplier=1, offset=0 case this is invisible, which is why it went unnoticed; but any non-unit ratio is inverted, and any non-zero offset is applied to the wrong joint. This PR changes the sibling coefficients to [0, 1, -multiplier] and the reciprocals to [0, 1, -1 / multiplier], matching the URDF convention. The chain branch is already correct and is left unchanged.

Test

Adds test_urdf_mimic_sibling_multiplier_offset: a minimal sibling-joint URDF with

<mimic joint="source" multiplier="2.0" offset="0.1"/>

drives source and asserts q_follower ~= 2.0 * q_source + 0.1. This fails on the current code (the follower instead satisfies the inverted (q_source - 0.1) / 2) and passes with the fix.

Validation

Loaded the sibling URDF on a SAPIEN 3.0.3 wheel (drive source to 0.4, follower left free):

build source follower satisfies
before (current) 0.3998 0.1499 (source - 0.1) / 2 (inverted)
after (this PR) 0.3999 0.8998 2 * source + 0.1 (URDF-correct)

The chain topology satisfies 2 * source + 0.1 both before and after, confirming the fix is scoped to the sibling branch only.

Note: the repo's GitHub workflow builds wheels but does not run unittest/, so the added regression test was run locally.

Copilot AI review requested due to automatic review settings June 25, 2026 11:41

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

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