How to Handle Disabled Collision Rules in SRDF: A Complete Guide

To handle disabled collision rules in SRDF, parse the <disable_collisions> elements using parseDisabledCollisionPairs in parseSrdf.js, which validates link pairs against the URDF model and returns a structured array for MoveIt 2 planning.

The Semantic Robot Description Format (SRDF) enables developers to configure robot behavior beyond the physical description provided by URDF. In the earthtojake/text-to-cad repository, handling disabled collision rules is essential for safe motion planning, allowing specific link pairs to intersect during manipulation without triggering collision errors. The parser validates these rules against the robot model and integrates them into MoveIt 2 planning contexts.

Understanding SRDF Disabled Collision Pairs

Disabled collision pairs tell the motion planning system to ignore collisions between specific robot links. This is crucial for robots with physically adjacent components that technically occupy the same space during normal operation, such as a gripper passing through a torso cavity during manipulation tasks.

According to the text-to-cad source code, each disabled collision rule requires three attributes: link1, link2, and reason. The parser enforces strict validation to ensure data integrity before the rules reach the MoveIt 2 server.

How the Parser Processes Disabled Collisions

Core Implementation in parseSrdf.js

The primary implementation resides in viewer/packages/cadjs/src/lib/urdf/parseSrdf.js. The function parseDisabledCollisionPairs processes <disable_collisions> elements found within the top-level <robot> tag.

The function accepts the parsed URDF data to validate link existence. It builds a Set of valid link names from the URDF model, then iterates through each <disable_collisions> element in the SRDF document.

The Seven Validation Steps

The parser performs rigorous validation to prevent configuration errors:

1. Link existence verification – Checks both link1 and link2 against the URDF link set. If either link is missing, it throws SRDF disabled collision pair references missing link.

2. Self-collision prevention – Rejects entries where link1 equals link2 with the error SRDF disabled collision pair cannot repeat the same link.

3. Duplicate detection – Uses a normalized key generated by [link1, link2].sort().join('/') stored in a seenPairs set. Any repeat triggers Duplicate SRDF disabled collision pair.

4. Reason requirement – Validates that the reason attribute is non-empty, throwing SRDF disabled collision pair … requires a reason if absent.

5. Normalization – Stores pairs in a consistent order regardless of XML declaration order.

6. Source tracking – Generates a source identifier for traceability.

7. Structured return – Returns objects with the schema { link1, link2, reason, source }.

The resulting array is exposed in the parsed SRDF object under the property disabledCollisionPairs.

SRDF Syntax for Disabling Collisions

Define disabled collision pairs within your SRDF XML using the following structure:

<robot name="my_robot">
  <!-- other SRDF elements … -->

  <!-- Disable collisions between the robot hand and the torso -->
  <disable_collisions link1="hand_link" link2="torso_link"
                     reason="Hand can safely intersect torso during manipulation"/>
</robot>

The reason attribute is mandatory and should describe why the collision is safe to ignore, aiding future maintenance and safety audits.

JavaScript Implementation Example

Import the parser from the @text-to-cad/cadjs package and process your SRDF content:

import { parseSrdf } from '@text-to-cad/cadjs/lib/urdf/parseSrdf.js';

// Assume `srdfXml` contains the XML string and `urdfData` is the parsed URDF.
const srdf = parseSrdf(srdfXml, { sourceUrl: 'my_robot.srdf', urdfData });

console.log(srdf.disabledCollisionPairs);
/*
[
  {
    link1: 'hand_link',
    link2: 'torso_link',
    reason: 'Hand can safely intersect torso during manipulation',
    source: 'hand_link-torso_link'
  }
]
*/

The parser automatically validates against the provided urdfData, ensuring all referenced links exist in the robot model before returning the collision pairs.

Integration with MoveIt 2 Server

After parsing, consume the disabled collision data in your motion planning pipeline using the motionFromSrdf function:

import { motionFromSrdf } from '@text-to-cad/cadjs/lib/urdf/parseSrdf.js';

// `srdfObj` is the result of `parseSrdf`
const motion = motionFromSrdf(srdfObj);

// Pass `motion.disabledCollisionPairs` to the Motion Planning API
moveit2Client.setDisabledCollisions(motion.disabledCollisionPairs);

On the Python server side, viewer/moveit2_server/context.py (lines 340-350) validates the SRDF content and propagates the disabled collision information to the MoveIt 2 planning context. The server loads SRDF files via moveit2_server/srdf_source.py, which indirectly invokes the JavaScript parser to ensure consistency between client and server validation logic.

Unit tests in viewer/src/server/catalog/cadDirectoryScanner.test.mjs verify correct handling of SRDF metadata, including edge cases for disabled collision rules.

Summary

• Validation is mandatory – The parser in parseSrdf.js verifies link existence against the URDF model and rejects self-collisions or duplicate pairs.
• Reason attribute required – Every <disable_collisions> element must include a human-readable explanation for the safety exception.
• Normalization prevents duplicates – The parser sorts link names alphabetically before comparison to catch logically identical pairs regardless of XML ordering.
• MoveIt 2 integration – Parsed rules flow through motionFromSrdf to the Python server context, informing the motion planner which collisions to ignore.
• Test coverage – The repository includes unit tests validating SRDF parsing logic and disabled collision handling.

Frequently Asked Questions

What happens if I reference a non-existent link in a disabled collision pair?

The parser throws SRDF disabled collision pair references missing link and halts processing. This ensures that disabled collision rules always reference valid URDF links, preventing runtime errors during motion planning when the MoveIt 2 server attempts to locate the physical geometry.

Can I disable collisions between a link and itself?

No. The parser explicitly rejects self-collision entries with the error SRDF disabled collision pair cannot repeat the same link. This prevents logical errors where a link would be configured to ignore collisions with its own geometry, which is physically impossible and indicates a configuration mistake.

Why does the parser require a reason attribute?

The reason attribute serves as mandatory documentation for safety exceptions. If the attribute is empty or missing, the parser throws SRDF disabled collision pair … requires a reason. This requirement ensures that every disabled collision decision is documented for future maintainers and safety auditors reviewing the robot configuration.

How does MoveIt 2 consume the disabled collision data?

The JavaScript parser exposes disabled pairs through the disabledCollisionPairs property. The motionFromSrdf function packages this data for transmission to the Python server, where moveit2_server/context.py validates and applies the rules to the MoveIt 2 planning scene. The planning algorithms then ignore collisions between the specified link pairs during trajectory generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}