fix: handle URDF world-anchor joints and link/joint name collisions

Two failures that fell out of testing against a wider URDF corpus
(Bullet's minitaur, the so101 from onshape-to-robot, drake's acrobot):

- Many URDFs anchor the base link to the world frame with a fixed
  joint whose parent is a synthetic `world` link that's never defined.
  BB has no concept of a world frame — the topology root is the robot.
  Drop such joints in a pre-pass, leaving the child unparented so the
  root-finder picks it up. A warning records what was dropped.
- URDF has separate namespaces for link and joint names, but BB
  requires global uniqueness across both. Several real URDFs use the
  same string for a link and a joint (so101's `gripper`, minitaur's
  `motor_back_rightL_link`). Rename colliding joints with a `_joint`
  suffix (incrementing if that's also taken) and rewrite `<mimic>`
  source references to match.

With these fixes, eleven public URDFs now compile cleanly: Allegro
Hand, ANYmal B, Bullet cartpole, Drake acrobot/pendulum, KUKA iiwa,
Bullet minitaur, Franka Panda, SO-101, UR5, and WidowX (xacro-free
portions).

Author: jimsynz

lib/bb/urdf/importer.ex

@@ -50,7 +50,12 @@ if Code.ensure_loaded?(Sourceror) do
     @spec to_quoted(Parser.robot(), module) ::
             {:ok, Macro.t(), [String.t()]} | {:error, term}
     def to_quoted(robot, module_name) when is_atom(module_name) do
-      robot = dedupe_material_names(robot)
+      robot =
+        robot
+        |> drop_world_anchor_joints()
+        |> dedupe_joint_names()
+        |> dedupe_material_names()
+
       links_by_name = Map.new(robot.links, &{&1.name, &1})
       joints_by_parent = Enum.group_by(robot.joints, & &1.parent)
       child_links = MapSet.new(robot.joints, & &1.child)
@@ -76,6 +81,76 @@ if Code.ensure_loaded?(Sourceror) do
       end
     end
 
+    # URDF commonly anchors a robot to the world with a fixed joint whose
+    # parent is a synthetic link (`world`, `map`, etc.) that's never defined
+    # in the file. BB has no concept of a world frame — the topology root is
+    # the robot. Drop joints whose parent link isn't defined; their child
+    # then becomes an unparented link, which the root-finder picks up
+    # naturally.
+    defp drop_world_anchor_joints(robot) do
+      link_names = MapSet.new(robot.links, & &1.name)
+
+      {joints, dropped} =
+        Enum.split_with(robot.joints, &MapSet.member?(link_names, &1.parent))
+
+      warnings =
+        Enum.map(dropped, fn joint ->
+          "dropped joint #{inspect(joint.name)}: parent link #{inspect(joint.parent)} is not defined (URDF world anchor?)"
+        end)
+
+      %{robot | joints: joints, warnings: robot.warnings ++ warnings}
+    end
+
+    # URDF has separate namespaces for link and joint names; BB requires
+    # global uniqueness across both. Rename any joint whose name collides
+    # with a link (or with another joint) and rewrite `<mimic>` source
+    # references to match.
+    defp dedupe_joint_names(robot) do
+      link_names = MapSet.new(robot.links, & &1.name)
+      {joints, _used, renames} = rename_colliding_joints(robot.joints, link_names)
+      joints = rewrite_mimic_sources(joints, renames)
+      %{robot | joints: joints}
+    end
+
+    defp rename_colliding_joints(joints, link_names) do
+      Enum.reduce(joints, {[], link_names, %{}}, fn joint, {acc, used, renames} ->
+        if MapSet.member?(used, joint.name) do
+          new_name = unique_name(joint.name <> "_joint", used)
+
+          {[%{joint | name: new_name} | acc], MapSet.put(used, new_name),
+           Map.put(renames, joint.name, new_name)}
+        else
+          {[joint | acc], MapSet.put(used, joint.name), renames}
+        end
+      end)
+      |> then(fn {joints, used, renames} -> {Enum.reverse(joints), used, renames} end)
+    end
+
+    defp unique_name(base, used) do
+      if MapSet.member?(used, base) do
+        Enum.find_value(Stream.iterate(2, &(&1 + 1)), &numbered_candidate(base, &1, used))
+      else
+        base
+      end
+    end
+
+    defp numbered_candidate(base, n, used) do
+      candidate = "#{base}_#{n}"
+      if MapSet.member?(used, candidate), do: nil, else: candidate
+    end
+
+    defp rewrite_mimic_sources(joints, renames) when map_size(renames) == 0, do: joints
+
+    defp rewrite_mimic_sources(joints, renames) do
+      Enum.map(joints, fn
+        %{mimic: %{joint: source} = mimic} = joint ->
+          %{joint | mimic: %{mimic | joint: Map.get(renames, source, source)}}
+
+        joint ->
+          joint
+      end)
+    end
+
     # URDF lets many visuals reference a single named material; BB's DSL
     # requires globally-unique entity names. Keep the URDF name on the first
     # visual that uses each material and strip it on later occurrences (BB

test/bb/urdf/importer_test.exs

@@ -155,6 +155,26 @@ defmodule BB.Urdf.ImporterTest do
       assert source =~ ~r/mesh do\s*filename "package:\/\/meshes\/arm\.stl"\s*scale 1\.0/
     end
 
+    test "drops joints whose parent link is undefined (URDF world anchor)" do
+      {source, warnings} = import_fixture("world_anchor.urdf", MyApp.WorldGen)
+
+      refute source =~ "joint :world_anchor"
+      assert source =~ "joint :shoulder"
+      assert Enum.any?(warnings, &(&1 =~ "dropped joint \"world_anchor\""))
+      assert [{MyApp.WorldGen, _}] = Code.compile_string(source)
+    end
+
+    test "renames joints that collide with link names and rewrites mimic refs" do
+      {source, _warnings} = import_fixture("name_collision.urdf", MyApp.CollideGen)
+
+      # `gripper` is a link; the homonymous joint gets renamed.
+      assert source =~ "link :gripper"
+      assert source =~ "joint :gripper_joint"
+      # The mimic source on `finger_joint` points to the renamed joint.
+      assert source =~ "source: :gripper_joint"
+      assert [{MyApp.CollideGen, _}] = Code.compile_string(source)
+    end
+
     test "errors out on multiple root links" do
       xml = """
       <?xml version="1.0"?>

test/fixtures/urdf/name_collision.urdf

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<robot name="collision_bot">
+  <link name="base"/>
+  <link name="gripper"/>
+  <link name="finger"/>
+
+  <joint name="gripper" type="revolute">
+    <parent link="base"/>
+    <child link="gripper"/>
+    <axis xyz="0 0 1"/>
+    <limit lower="-1" upper="1" effort="1" velocity="1"/>
+  </joint>
+
+  <joint name="finger_joint" type="prismatic">
+    <parent link="gripper"/>
+    <child link="finger"/>
+    <axis xyz="1 0 0"/>
+    <limit lower="0" upper="0.05" effort="1" velocity="0.1"/>
+    <mimic joint="gripper" multiplier="0.5"/>
+  </joint>
+</robot>

test/fixtures/urdf/name_collision.urdf.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 James Harton
+
+SPDX-License-Identifier: Apache-2.0

test/fixtures/urdf/world_anchor.urdf

@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<robot name="anchored_bot">
+  <link name="base_link"/>
+  <link name="arm"/>
+
+  <joint name="world_anchor" type="fixed">
+    <parent link="world"/>
+    <child link="base_link"/>
+  </joint>
+
+  <joint name="shoulder" type="revolute">
+    <parent link="base_link"/>
+    <child link="arm"/>
+    <axis xyz="0 0 1"/>
+    <limit lower="-1" upper="1" effort="1" velocity="1"/>
+  </joint>
+</robot>

test/fixtures/urdf/world_anchor.urdf.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2026 James Harton
+
+SPDX-License-Identifier: Apache-2.0