# How to Handle Disabled Collision Rules in SRDF: A Complete Guide > Learn how to handle disabled collision rules in SRDF using parseDisabledCollisionPairs in text-to-cad. This guide validates link pairs and structures data for MoveIt 2 planning. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: how-to-guide - Published: 2026-07-23 --- **To handle disabled collision rules in SRDF, parse the `` elements using `parseDisabledCollisionPairs` in [`parseSrdf.js`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/viewer/packages/cadjs/src/lib/urdf/parseSrdf.js). The function **`parseDisabledCollisionPairs`** processes `` elements found within the top-level `` 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 `` 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: ```xml ``` 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: ```javascript 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: ```javascript 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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/parseSrdf.js) verifies link existence against the URDF model and rejects self-collisions or duplicate pairs. - **Reason attribute required** – Every `` 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`](https://github.com/earthtojake/text-to-cad/blob/main/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.