Generators

URDF, XACRO, and SRDF generators for converting Python objects to files.

Base XML Engine

All XML-based generators in LinkForge inherit from a shared base engine that handles common geometry, inertial, and origin logic.

class linkforge.core.RobotXMLGenerator(pretty_print=True, output_path=None)[source]

Bases: RobotGenerator[str]

Abstract base class for XML-based robotics format generators.

Parameters:

pretty_print (bool)
output_path (Path | None)

__init__(pretty_print=True, output_path=None)[source]

Initialize base XML generator.

Parameters:

pretty_print (bool) – If True, format XML with indentation
output_path (Path | None) – Base path to calculate relative mesh paths

Abstract Generators

class linkforge.core.base.RobotGenerator[source]

Bases: ABC, Generic[T]

Abstract base class for all Robot Generators.

abstractmethod generate(robot, **kwargs)[source]

Generate the output representation from the Robot model.

Parameters:

robot (Robot) – The generic Robot model (Intermediate Representation)
**kwargs (Any) – Format-specific generation options

Return type:

TypeVar(T)

Returns:

The generated output (e.g. XML string, JSON dict)

write(robot, filepath, **kwargs)[source]

Write the generated output to a file.

This is a template method that handles directory creation and delegates the actual writing to the _save_to_file hook.

Parameters:

robot (Robot) – Robot model to export
filepath (Path) – Destination file path
**kwargs (Any) – Options passed to generate() and _save_to_file()

Return type:

None

class linkforge.core.base.IResourceResolver(*args, **kwargs)[source]

Bases: Protocol

Protocol for resolving resource URIs (e.g. package://, file://, https://).

resolve(uri, relative_to=None)[source]

Resolve a URI to a local filesystem Path.

Parameters:

uri (str) – The resource URI to resolve.
relative_to (Path | None) – Optional base directory for relative path resolution.

Return type:

Path

Returns:

The resolved absolute Path.

Raises:

FileNotFoundError – If the resource cannot be located.

__init__(*args, **kwargs)

URDF Generator

class linkforge.core.URDFGenerator(pretty_print=True, output_path=None, use_ros2_control=True)[source]

Bases: RobotXMLGenerator

Unified Robot Description Format (URDF) generator.

Parameters:

pretty_print (bool)
output_path (Path | None)
use_ros2_control (bool)

__init__(pretty_print=True, output_path=None, use_ros2_control=True)[source]

Initialize URDF generator.

Parameters:

pretty_print (bool) – If True, format XML with indentation for readability (default: True)
output_path (Path | None) – Path where URDF will be saved. Used to calculate relative mesh paths. If None, mesh paths will be absolute or package:// URIs.
use_ros2_control (bool) – Whether to generate ros2_control blocks from transmissions. Set to False if you don’t use ROS2 Control or prefer manual configuration. (default: True)

Example

>>> from pathlib import Path
>>> # Basic generator with defaults
>>> generator = URDFGenerator()
>>>
>>> # Generator with relative mesh paths
>>> generator = URDFGenerator(output_path=Path("/workspace/robot.urdf"))

generate(robot, validate=True, **kwargs)[source]

Generate URDF XML string from robot.

Parameters:

robot (Robot) – Robot model with links, joints, sensors, etc.
validate (bool) – Whether to validate robot structure before generation (default: True)
**kwargs (Any) – Additional generation options (e.g. ‘compact’ to avoid comments)

Return type:

str

Returns:

URDF XML as formatted string with proper indentation

Raises:

RobotGeneratorError – If robot validation fails (checks for cycles, missing links, etc.)

generate_robot_element(robot, validate=True)[source]

Generate URDF XML Element tree from robot.

Parameters:

robot (Robot) – Robot model with links, joints, sensors, etc.
validate (bool) – Whether to validate robot structure before generation (default: True)

Return type:

Element

Returns:

URDF XML Element tree

add_links_section(parent, robot)[source]

Add Links section to parent element.

This follows the Template Method pattern. It handles the section header (comment) and iteration, delegating the specific element creation to _add_link_to_xml.

Parameters:

parent (Element)
robot (Robot)

Return type:

None

add_joints_section(parent, robot)[source]

Add Joints section to parent element.

Parameters:

parent (Element)
robot (Robot)

Return type:

None

add_ros2_control(parent, robot)[source]

Add ros2_control to parent element.

This method centralizes the logic for choosing between parsed (centralized) ROS 2 Control configuration and standard transmission-based generation. It ensures consistent XML structure and comments across URDF and XACRO export.

Parameters:

parent (Element) – Parent XML element (robot)
robot (Robot) – Robot model

Return type:

None

add_transmissions(parent, robot)[source]

Add transmissions section to parent element.

Parameters:

parent (Element) – Parent XML element (robot)
robot (Robot) – Robot model

Return type:

None

add_gazebo(parent, robot)[source]

Add Gazebo section to parent element.

Parameters:

parent (Element) – Parent XML element (robot)
robot (Robot) – Robot model

Return type:

None

add_sensors(parent, robot)[source]

Add Sensors section to parent element.

Parameters:

parent (Element) – Parent XML element (robot)
robot (Robot) – Robot model

Return type:

None

XACRO Generator

class linkforge.core.XACROGenerator(pretty_print=True, advanced_mode=True, extract_materials=True, extract_dimensions=True, generate_macros=False, split_files=False, output_path=None, use_ros2_control=True)[source]

Bases: URDFGenerator

Generate XACRO from Robot model.

Supports material and dimension extraction, auto-macro generation, and modular file splitting.

Parameters:

pretty_print (bool)
advanced_mode (bool)
extract_materials (bool)
extract_dimensions (bool)
generate_macros (bool)
split_files (bool)
output_path (Path | None)
use_ros2_control (bool)

__init__(pretty_print=True, advanced_mode=True, extract_materials=True, extract_dimensions=True, generate_macros=False, split_files=False, output_path=None, use_ros2_control=True)[source]

Initialize XACRO generator.

Parameters:

pretty_print (bool) – If True, format XML with indentation
advanced_mode (bool) – Enable advanced XACRO features
extract_materials (bool) – Extract material colors as properties
extract_dimensions (bool) – Extract common dimensions as properties
generate_macros (bool) – Auto-generate macros for repeated patterns
split_files (bool) – Split into multiple files (materials, macros, robot)
output_path (Path | None) – Path where XACRO will be saved (for relative mesh paths)
use_ros2_control (bool) – Whether to generate ROS2 Control from transmissions

generate(robot, validate=True, **kwargs)[source]

Generate XACRO XML string from robot.

Parameters:

robot (Robot)
validate (bool)
kwargs (Any)

Return type:

str

generate_robot_element(robot, validate=True, **_kwargs)[source]

Generate XACRO XML Element tree from robot.

This is used internally by generate() and for multi-file exports to preserve structural comments and metadata.

Parameters:

robot (Robot) – Robot model to convert
validate (bool) – Whether to validate robot structure before generation
_kwargs (Any)

Return type:

Element

Returns:

XACRO XML Element tree

write(robot, filepath, validate=True, **kwargs)[source]

Write XACRO to file.

Parameters:

robot (Robot)
filepath (Path)
validate (bool)
kwargs (Any)

Return type:

None

SRDF Generator

The SRDF generator is documented with the rest of the SRDF layer (models, parser, generator) on the dedicated SRDF reference page.

Usage Examples

Generate URDF

from linkforge.core import Robot, Link, Inertial, InertiaTensor, URDFGenerator

# Create robot
robot = Robot(
    name="my_robot",
    links=[
        Link(
            name="base_link",
            inertial=Inertial(
                mass=10.0,
                inertia=InertiaTensor(ixx=1.0, iyy=1.0, izz=1.0)
            )
        )
    ]
)

# Generate URDF
generator = URDFGenerator(pretty_print=True)
urdf_string = generator.generate(robot)

# Save to file
with open("robot.urdf", "w") as f:
    f.write(urdf_string)

Generate XACRO

from linkforge.core import XACROGenerator
from pathlib import Path

# Generate XACRO with split files
generator = XACROGenerator(
    split_files=True,
    output_dir=Path("robot_description")
)

files = generator.generate(robot)
# Creates:
# - robot.xacro (main assembly)
# - robot_properties.xacro (materials & dimensions)
# - robot_macros.xacro (reusable geometries)
# - robot_ros2_control.xacro (hardware plugins & interfaces)

Export Options

# Compact output (no pretty printing)
generator = URDFGenerator(pretty_print=False)
compact_urdf = generator.generate(robot)

# With custom URDF path (for relative mesh paths)
generator = URDFGenerator(urdf_path=Path("robots/my_robot.urdf"))
urdf = generator.generate(robot)
# Mesh paths will be relative to robots/ directory

Round-Trip Verification

from linkforge.core import URDFParser

# Original robot
robot1 = create_robot()

# Export to URDF
generator = URDFGenerator()
urdf = generator.generate(robot1)

# Re-import
robot2 = URDFParser().parse_string(urdf)

# Verify fidelity
assert robot2.name == robot1.name
assert len(robot2.links) == len(robot1.links)
assert len(robot2.joints) == len(robot1.joints)