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]

Hi @zwdoescode,

First of all, thank you very much! I have a few follow-up questions regarding your points:

4. Easiest fix: use Physics -> Joint Edit mode in the GUI to reposition the joint -- this recalculates both frames automatically

Nice! 👍🏻 Unfortunately, I have never seen an option "Joint Edit mode" before, where can I find it / how can I do that?

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:

I see, great! 👍🏻 For the UI, it would be great if there would be an option to exclude passive joints from export in the URDF Exporter Extension (in the future) 🙂

[zwdoescode]

Apologies for the unclear wording — there isn't a single "Joint Edit mode" menu item. Here's the actual workflow to visually reposition joint frames and fix the consistency error:

1. Enable joint visualization: In the viewport, click the Eye icon (👁) in the toolbar → Show By Type → Physics → enable Joints
2. Select the joint prim in the Stage panel
3. You'll see joint editing manipulators appear in the viewport on the joint frames. These let you drag the joint anchor point.
4. You can also use the Physics Inspector (Tools > Physics > Physics Inspector) to interactively inspect and manipulate joints.

I will create a feature request (IREQ-460) about exposing the node_names_to_remove and edge_names_to_remove parameters in the URDF Exporter GUI.

[d-kleine]

@zwdoescode I am still struggling to understand what I need to do to make the joint transforms consistent again. Currently, when trying to move the affected joint, it says [Warning] [omni.usd.commands.usd_commands] Overridden in a stronger layer. How can I resolve this issue without re-doing all joints again?

[zwdoescode]

That warning indicates that it's a USD layer issue, not a joint-geometry one. The joint's transform attributes (physics:localPos0/1, physics:localRot0/1) already have an opinion authored in a layer that is stronger than the layer you're currently authoring into, so your Joint-Edit move gets written to a weaker layer and is overridden → nothing changes, and the inconsistency stays.

You don't need to redo any joints. You just need to edit in the right layer (or remove the overriding opinion).

Option A — Edit in the strongest layer (quickest)

1. Open Window > Layers.
2. The strongest layer with an opinion is the one whose value wins. Find the layer that holds the joint's transform (the bold/colored one for that attribute).
3. Right-click that layer → Set Authoring Layer (it becomes the active edit target).
4. Now use Joint-Edit / move the joint frame again — it will write into that layer and take effect.

Option B — Remove the overriding override
If the stronger opinion is an accidental override (e.g. in the session/root layer over a referenced robot), select the joint, and in the Property panel right-click the affected physics:localPos*/localRot* attribute → Remove Override (or delete that spec from the stronger layer in the Layers window). The intended value in the weaker layer then wins.

A quick way to see which layer is fighting you: select the joint, open the Layers window, and watch which layer highlights when you inspect physics:localPos1. That's the one to author into (Option A) or strip the override from (Option B).

Let me know which layer turns out to hold the opinion — happy to help narrow it down if it's coming from a reference/payload.