Defining Semantic Data (SRDF)

SRDF (Semantic Robot Description Format) extends URDF by adding high-level information needed for motion planning, such as planning groups, named poses, and collision filtering.

While URDF describes what the robot is, SRDF describes how to use it.

1. Planning Groups

A Planning Group is a collection of links and joints that are planned together (e.g., an β€œarm” or a β€œgripper”). In LinkForge, you define these using the group() method on the semantic builder namespace.

from linkforge.core import RobotBuilder

builder = RobotBuilder("my_robot")
# ... (build your robot links and joints)

# Define an arm group using a chain shorthand
builder.semantic.group("arm", base_link="base_link", tip_link="flange")

# Define a gripper group using a list of links
builder.semantic.group("gripper", links=["left_finger", "right_finger", "palm"])

Tip

The base_link and tip_link arguments are convenience shorthands for defining a single kinematic chain. You can also provide multiple chains using the chains=[(base, tip), ...] argument.

2. Group States (Named Poses)

Group states allow you to save specific joint configurations with meaningful names (e.g., β€œhome”, β€œstow”, β€œpick”).

# Add a 'home' pose for the arm
builder.semantic.group_state(
    name="home",
    group="arm",
    values={
        "joint_1": 0.0,
        "joint_2": -1.57,
        "joint_3": 1.57,
    }
)

3. Disabling Self-Collisions

By default, motion planners check for collisions between all pairs of links. You can optimize performance and prevent false positives (e.g., adjacent links that are allowed to touch) by disabling specific pairs.

# Disable collision between specific adjacent links
builder.semantic.disable_collisions("link_1", "link_2", reason="Adjacent")

# Disable all collisions for a set of links (e.g., wheels vs chassis)
builder.robot.disable_all_collisions(["left_wheel", "right_wheel", "chassis"], reason="Never")

4. Exporting SRDF

When you are ready to use your robot in MoveIt or other planners, export the semantic description along with your URDF.

srdf_xml = builder.export_srdf()

with open("robot.srdf", "w") as f:
    f.write(srdf_xml)

Tip

The export_srdf() method automatically validates your groups and states. For example, it will warn you if a group state references a joint that doesn’t belong to the specified group.

5. Semantic Validation Linting

LinkForge includes deep semantic linting. The built-in validator (validate_robot()) will now aggressively verify your semantic configuration against the physical kinematic tree. It catches:

  • Group states containing invalid joints or limits out of bounds.

  • Planning groups containing non-existent links.

  • Semantic collision disabling referencing missing or duplicate links.

  • Kinematic chains (base_link -> tip_link) that are physically disconnected or broken.