URDF Export: Inconsistent Joint Transforms & Keeping Kimatic Behavior

[d-kleine]

I’m currently working on a robot with a parallel gripper and ran into an issue when exporting to URDF:

[Error] [omni.ui.python] ValueError: The 'name_of_joint''s joint transforms are not consistent.

I’m not sure what exactly is causing this or how to fix it.

Right now, I’ve set up one finger as part of the articulation and configured the other finger using a mimic joints. This works good for far. However, the gripper also includes passive joints (e.g., linkage rods that constrain motion). These joints are currently excluded from the articulation, because including them creates an articulation loop.

For reference, I’ve followed the “Rig Closed-Loop Structures” tutorial, but unfortunately it doesn’t cover passive joints like pins that hold parts in place while allowing rotation:
https://docs.isaacsim.omniverse.nvidia.com/5.1.0/robot_setup_tutorials/rig_closed_loop_structures.html

I would like to ask

• How should passive joints (like linkage rods) be represented in USD so that URDF export works correctly?
• Is there a recommended way to avoid articulation loops while still preserving the kinematic behavior of a parallel gripper?
• Since I want to train the robot in Isaac Lab, the USD needs to conform to a URDF tree structure. How can I structure the model so it remains URDF-compatible while still capturing the closed-chain mechanics?

Any guidance or examples for handling parallel grippers / closed-chain mechanisms in this workflow would be really helpful! 🙂

[zwdoescode]

The "joint transforms are not consistent" error comes from Isaac Sim's URDF exporter (nvidia.srl.from_usd.transform_graph). It computes each joint's global position two ways -- via the parent link (physics:localPos0/localRot0) and via the child link (physics:localPos1/localRot1). If these don't agree within tolerance, you get this error.

This typically happens when:

• Joint local frames became stale after body transforms were edited
• A joint was placed manually without the GUI's auto-alignment
• The exporter picks up passive/constraint joints that form a closed loop it can't resolve into a tree

Isaac Sim's URDF exporter (TransformGraph.init_from_stage()) collects every UsdPhysics.Joint prim on the stage, not just those inside your articulation. Your passive linkage joints (outside the articulation) are still being found and validated -- that's what's triggering the error.

The "Rig Closed-Loop Structures" tutorial handles loops within a PhysX articulation at runtime (using D6 joints as constraints). But for URDF export, those constraint joints must be excluded since URDF can't represent loops. The simulation can handle closed chains; the file format cannot.

Here are some fixes for your reference

Fix 1: Exclude passive joints from export (recommended)

The exporter's UsdToUrdf class supports node_names_to_remove and edge_names_to_remove parameters specifically for breaking kinematic loops. This isn't exposed in the GUI, but works programmatically:

from nvidia.srl.from_usd.to_urdf import UsdToUrdf

usd_to_urdf = UsdToUrdf(
    stage,
    node_names_to_remove=["linkage_rod_joint_1", "linkage_rod_joint_2"],
    root="/World/Robot",
)
usd_to_urdf.save_to_file("robot.urdf")

Replace the joint names with the actual prim names of your passive linkage joints. This tells the exporter to skip those joints when building the tree topology.

Fix 2: Fix joint transform consistency

If the error fires on a joint you do want in the URDF (not a loop-forming joint), the local frames need correcting:

1. Select the joint prim in the Stage panel
2. In the Property panel, check physics:localPos0, physics:localRot0 (relative to body0) and physics:localPos1, physics:localRot1 (relative to body1)
3. Both must place the joint at the same world-space location
4. Easiest fix: use Physics -> Joint Edit mode in the GUI to reposition the joint -- this recalculates both frames automatically

Fix 3: Structure the USD for tree-compatible export

Since URDF requires a tree (no loops), structure your gripper as:

base_link
  -> finger1_joint (revolute, actuated)
    -> finger1_link
  -> finger2_joint (revolute)
    -> finger2_link

Then add <mimic> to the exported URDF for the dependent finger:

<joint name="finger2_joint" type="revolute">
  <mimic joint="finger1_joint" multiplier="-1.0" offset="0.0"/>
  ...
</joint>

The linkage rods are removed from the URDF entirely (via node_names_to_remove above). The <mimic> tag enforces the kinematic coupling that the linkages originally provided.

Please let us know if the above fixes resolve your issue. If not, could you please provide a minimal setup files for us to replicate this issue? Thanks!

[d-kleine]

Thanks! With your help, I just noticed that when attempting to export to URDF with inconsistent joints (the console reports [Error] [omni.ui.python] ValueError: The 'name_of_joint' joint transforms are not consistent.), a new layer named anon:...:inertia_temp.usda is automatically created and set as the current authoring layer. Is this behavior intended?

I'm still struggling to understand how to resolve the joint transform inconsistencies. It appears that several joints are affected. When I drag an anchor point, the joint transforms inconsistency remains when exporting to URDF. I may be misunderstanding what the anchor points represent, but when selecting a joint in the Stage view, is the small light-blue circle in the center of the joint in the viewport the anchor point that should be adjusted?

If possible, it would be very helpful to have a short screencast showing a reproducible workflow fixing inconsistent joint transforms.

[zwdoescode]

@d-kleine Could you please share your USD files for me to replicate your issue and try to fix it?

[d-kleine]

Thanks for offering to take a look. I’d prefer not to publicly share my USD files, as they represent quite a bit of work and I’m not comfortable making them publicly available. For context, my setup is based on the SO-101 arm, but with a parallel gripper (instead of the standard end effector). However, I was able to reproduce a very similar issue using the standard SO-101 asset that ships with the Isaac Sim 5.1.0 Asset Browser, triggering the same error.

Reproduction steps

1. Create a new stage.
2. Add a Ground Plane.
3. Open Window → Isaac Sim Asset [Beta].
4. Under ROBOTS, filter for 101.
5. Select so101_new_calib.usd and drag-and-drop it into the origin (do not use "Load as Reference").
6. Attempt to export the robot via File → Export to URDF.

This produces the following error:

[Error] [omni.ui.python] ValueError: The 'root_joint''s joint transforms are not consistent.
[Error] [omni.ui.python] global___joint_via_parent:
[Error] [omni.ui.python] [[1. 0. 0. 0.]
[Error] [omni.ui.python]  [0. 1. 0. 0.]
[Error] [omni.ui.python]  [0. 0. 1. 0.]
[Error] [omni.ui.python]  [0. 0. 0. 1.]]
[Error] [omni.ui.python] global___joint_via_child:
[Error] [omni.ui.python] [[ 1.          0.          0.         -0.01247835]
[Error] [omni.ui.python]  [ 0.          1.          0.         -0.00688887]
[Error] [omni.ui.python]  [ 0.          0.          1.          0.00000095]
[Error] [omni.ui.python]  [ 0.          0.          0.          1.        ]]

In this example, the issue is reported on the root fixed joint due to inconsistent parent/child transforms. In my own model, I am seeing the same type of error, but on revolute joints of the parallel gripper instead of the root fixed joint.

Do you have an idea how to resolve these inconsistent joint transforms in Isaac Sim 5.1.0?

[zwdoescode]

Hi @d-kleine We just released Isaac Sim 6.0 GA version. Do you want to try it out and see if it is still reproducible in the latest version? Thanks?

[d-kleine]

Just tested the URDF export feature with the 6.0 GA release, the inconsistency doesn't show up anymore. Thanks!

I just exported the robot and viewed the exported URDF file, something is still wrong here. I might open a separate issue on that once figured out what went wrong here.