LinkForge Composer API

The Composer provides a high-level, fluent API for programmatically constructing and assembling robot models. It is designed to be ergonomic, human-readable, and robust.

RobotBuilder

The main entry point for constructing a robot model.

Tip

Context Managers & Cloning RobotBuilder supports deep cloning via .clone(), allowing you to use a base builder as a template and fork it into multiple variations. Additionally, LinkBuilder supports context managers (with builder.link(...)) to automatically set the parent context for nested links, removing the need to manually specify the parent= argument.

class linkforge.core.RobotBuilder(name=None, robot=None)

Bases: object

A high-level API to compose robots programmatically.

This class serves as the entry point for building robots. It can create new robots from scratch or modify existing ones by adding links or attaching sub-components.

Parameters:

• name (str | None)

• robot (Robot | None)

__init__(name=None, robot=None)

Initialize a new robot builder.

Parameters:

• name (str | None) – Name of the new robot (required if robot is None).

• robot (Robot | None) – Existing robot model to build upon.

Raises:

RobotModelError – If neither name nor robot is provided.

link(name, parent=None, joint_name=None)

Start building a new link programmatically.

Parameters:

• name (str) – Unique name for the link.

• parent (str | None) – Optional parent link name to connect to immediately.

• joint_name (str | None) – Optional explicit name for the connecting joint.

Return type:

LinkBuilder

Returns:

A LinkBuilder instance for fluent construction.

attach(component, at_link, joint_name=None, prefix='', joint_type=JointType.FIXED, xyz=(0, 0, 0), rpy=(0, 0, 0), axis=None, limits=None, disable_collision=False, reason='Adjacent')

Merge another robot or assembly into the current one.

Parameters:

• component (Robot | IComposer) – The Robot or IComposer (e.g. RobotBuilder) to attach.

• at_link (str) – The link in the current robot to attach to.

• joint_name (str | None) – Optional name for the connecting joint.

• prefix (str) – Optional prefix for all links/joints in the component.

• joint_type (JointType) – Type of connecting joint.

• xyz (tuple[float, float, float]) – Joint origin translation.

• rpy (tuple[float, float, float]) – Joint origin rotation.

• axis (tuple[float, float, float] | None) – Optional joint axis (automatically normalized).

• limits (tuple[float, float] | None) – Optional (lower, upper) joint limits.

• disable_collision (bool) – Whether to disable collision checking at the interface.

• reason (str) – Semantic reason for disabling collisions (e.g., “Adjacent”).

Return type:

RobotBuilder

Returns:

The RobotBuilder instance.

material(name, color=None)

Define a global material that can be reused by multiple links.

Parameters:

• name (str) – Unique material name.

• color (tuple[float, float, float, float] | None) – RGBA color as (r, g, b, a), each in range [0.0, 1.0].

Return type:

RobotBuilder

Returns:

The RobotBuilder instance.

ros2_control(name, hardware_plugin, control_type='system', parameters=None)

Add a global ros2_control system configuration.

Parameters:

• name (str) – Unique system name.

• hardware_plugin (str) – The hardware interface plugin (e.g. ‘fake_components/GenericSystem’).

• control_type (str) – Type of control (usually ‘system’).

• parameters (dict[str, Any] | None) – Key-value parameters for the hardware interface.

Return type:

RobotBuilder

Returns:

The RobotBuilder instance.

property semantic: SemanticBuilder

Access the semantic (SRDF/MoveIt) construction API.

Example

>>> builder.semantic.group("arm", links=["link1", "link2"])

clone()

Create a deep copy of the builder and its robot state.

Return type:

RobotBuilder

Returns:

A new independent RobotBuilder instance with cloned state.

build(validate=True)

Finalize the assembly and return the completed Robot model.

Parameters:

validate (bool) – If True, performs a kinematic check for disconnected links or cycles.

Return type:

Robot

Returns:

The completed Robot object.

Raises:

RobotValidationError – If validation is requested and the robot is invalid.

export_urdf(validate=True, pretty_print=True)

Generate the URDF XML representation of the robot.

Parameters:

• validate (bool) – Whether to run internal LinkForge validation.

• pretty_print (bool) – Whether to format the XML with indentation.

Return type:

str

Returns:

A URDF XML string.

export_srdf(validate=True, pretty_print=True)

Generate the SRDF XML representation of the robot.

Parameters:

• validate (bool) – Whether to validate the semantic description.

• pretty_print (bool) – Whether to format the XML with indentation.

Return type:

str

Returns:

An SRDF XML string.

LinkBuilder

A staged builder for configuring individual links and their parent joints.

class linkforge.core.LinkBuilder(builder, name, parent=None, joint_name=None)

Bases: object

Staged fluent builder for programmatic link and joint construction.

This builder accumulates link and joint properties in stages. It is usually returned by builder.link() or link_builder.child().

Parameters:

• builder (IComposer)

• name (str)

• parent (str | None)

• joint_name (str | None)

__init__(builder, name, parent=None, joint_name=None)

Initialize a new LinkBuilder. Internal use only.

Parameters:

• builder (IComposer)

• name (str)

• parent (str | None)

• joint_name (str | None)

__enter__()

Enter the context of this link.

Pushes this link’s name onto the parent stack, making it the default parent for any links created within this block.

Return type:

LinkBuilder

__exit__(exc_type, exc_val, exc_tb)

Exit the context of this link.

Pops this link’s name from the parent stack and automatically commits the link to flush its configured properties if no exception occurred.

Parameters:

• exc_type (type[BaseException] | None)

• exc_val (BaseException | None)

• exc_tb (Any)

Return type:

None

visual(geometry, xyz=(0, 0, 0), rpy=(0, 0, 0), material=None, name=None)

Add a visual representation to the link.

Parameters:

• geometry (Box | Cylinder | Sphere | Mesh) – Shape of the visual (e.g., box(), cylinder()).

• xyz (tuple[float, float, float]) – Translation relative to the link frame.

• rpy (tuple[float, float, float]) – Rotation (roll-pitch-yaw) in radians.

• material (str | Material | None) – Material name or Material object.

• name (str | None) – Optional name for this visual element.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance for chaining.

collision(geometry=None, xyz=None, rpy=None, name=None)

Add a collision geometry to the link.

If no arguments are provided, it automatically clones the last added visual element’s geometry and origin.

Parameters:

• geometry (Box | Cylinder | Sphere | Mesh | None) – Shape of the collision element.

• xyz (tuple[float, float, float] | None) – Translation relative to the link frame.

• rpy (tuple[float, float, float] | None) – Rotation relative to the link frame.

• name (str | None) – Optional name for this collision element.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

mass(value, origin_xyz=None, origin_rpy=None, inertia=None)

Define the mass and center of gravity for the link.

If no inertia is provided, LinkForge will automatically calculate the inertia tensor based on the link’s geometry and mass during commit().

Parameters:

• value (float) – Mass in kilograms.

• origin_xyz (tuple[float, float, float] | None) – Position of the center of mass.

• origin_rpy (tuple[float, float, float] | None) – Orientation of the principal axes of inertia.

• inertia (InertiaTensor | None) – Optional manual InertiaTensor.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

inertia(ixx, iyy, izz, ixy=0, ixz=0, iyz=0)

Manually specify the inertia tensor components.

Parameters:

• ixx (float) – Moments of inertia.

• iyy (float) – Moments of inertia.

• izz (float) – Moments of inertia.

• ixy (float) – Products of inertia.

• ixz (float) – Products of inertia.

• iyz (float) – Products of inertia.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

at_origin(xyz=(0, 0, 0), rpy=(0, 0, 0))

Set the transform from the parent link to this link’s frame.

Parameters:

• xyz (tuple[float, float, float]) – Translation as (x, y, z).

• rpy (tuple[float, float, float]) – Rotation as (roll, pitch, yaw).

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

fixed(name=None, xyz=None, rpy=None)

Configure the connection as a FIXED joint.

Parameters:

• name (str | None) – Unique joint name.

• xyz (tuple[float, float, float] | None) – Joint origin translation.

• rpy (tuple[float, float, float] | None) – Joint origin rotation.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

revolute(axis, limits, name=None, xyz=None, rpy=None, effort=10.0, velocity=1.0)

Configure the connection as a REVOLUTE (limited rotation) joint.

Parameters:

• axis (tuple[float, float, float]) – Rotation axis unit vector.

• limits (tuple[float, float]) – (lower, upper) joint limits in radians.

• name (str | None) – Unique joint name.

• xyz (tuple[float, float, float] | None) – Joint origin translation.

• rpy (tuple[float, float, float] | None) – Joint origin rotation.

• effort (float) – Maximum joint effort.

• velocity (float) – Maximum joint velocity.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

continuous(axis, name=None, xyz=None, rpy=None, effort=10.0, velocity=1.0)

Configure the connection as a CONTINUOUS (unlimited rotation) joint.

Parameters:

• axis (tuple[float, float, float]) – Rotation axis unit vector.

• name (str | None) – Unique joint name.

• xyz (tuple[float, float, float] | None) – Joint origin translation.

• rpy (tuple[float, float, float] | None) – Joint origin rotation.

• effort (float) – Maximum joint effort (optional).

• velocity (float) – Maximum joint velocity (optional).

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

prismatic(axis, limits, name=None, xyz=None, rpy=None, effort=10.0, velocity=1.0)

Configure the connection as a PRISMATIC (linear sliding) joint.

Parameters:

• axis (tuple[float, float, float]) – Translation axis unit vector.

• limits (tuple[float, float]) – (lower, upper) joint limits in meters.

• name (str | None) – Unique joint name.

• xyz (tuple[float, float, float] | None) – Joint origin translation.

• rpy (tuple[float, float, float] | None) – Joint origin rotation.

• effort (float) – Maximum joint effort.

• velocity (float) – Maximum joint velocity.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

floating(name=None, xyz=None, rpy=None)

Configure the connection as a FLOATING (6 DOF) joint.

Parameters:

• name (str | None) – Unique joint name.

• xyz (tuple[float, float, float] | None) – Joint origin translation.

• rpy (tuple[float, float, float] | None) – Joint origin rotation.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

planar(axis, name=None, xyz=None, rpy=None)

Configure the connection as a PLANAR joint.

Parameters:

• axis (tuple[float, float, float]) – Plane normal unit vector.

• name (str | None) – Unique joint name.

• xyz (tuple[float, float, float] | None) – Joint origin translation.

• rpy (tuple[float, float, float] | None) – Joint origin rotation.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

dynamics(damping=0.0, friction=0.0)

Set the physical dynamics for the joint.

Parameters:

• damping (float) – Damping coefficient.

• friction (float) – Friction coefficient.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

mimic(joint, multiplier=1.0, offset=0.0)

Set this joint to mimic another joint’s movement.

Parameters:

• joint (str) – Name of the joint to mimic.

• multiplier (float) – Scaling factor for the movement.

• offset (float) – Offset in radians/meters.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

safety(soft_lower=None, soft_upper=None, k_position=None, k_velocity=0.0)

Define a safety controller for the joint.

Parameters:

• soft_lower (float | None) – Software limits.

• soft_upper (float | None) – Software limits.

• k_position (float | None) – Controller gains.

• k_velocity (float) – Controller gains.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

calibration(rising=None, falling=None)

Set calibration offsets for the joint.

Parameters:

• rising (float | None) – Rising edge offset.

• falling (float | None) – Falling edge offset.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

physics(**kwargs)

Set surface and contact physics properties for this link.

Supports both typed LinkPhysics fields and raw engine-specific parameters.

Common arguments:

self_collide (bool): Enable self-collision. gravity (bool): Enable gravity. mu, mu2 (float): Friction coefficients. kp, kd (float): Contact stiffness and damping.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

Parameters:

kwargs (Any)

transmission(reduction=1.0, interface='effort', actuator=None, name=None)

Define a transmission (mechanical reduction) for the current joint.

Parameters:

• reduction (float) – Mechanical reduction ratio.

• interface (str) – Hardware interface (effort, position, velocity).

• actuator (str | None) – Optional name for the actuator.

• name (str | None) – Optional transmission name.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

ros2_control(command_interfaces, state_interfaces, parameters=None, system_name=None)

Configure ros2_control interfaces for the current joint.

Parameters:

• command_interfaces (list[str]) – List of allowed commands (e.g. [‘position’]).

• state_interfaces (list[str]) – List of exposed states (e.g. [‘position’, ‘velocity’]).

• parameters (dict[str, Any] | None) – Key-value parameters for the joint control.

• system_name (str | None) – Optional name of the specific ros2_control system to attach to.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

camera(name, fov=1.047, width=640, height=480, xyz=(0, 0, 0), rpy=(0, 0, 0))

Attach a camera sensor to this link.

Parameters:

• name (str) – Unique sensor name.

• fov (float) – Horizontal field of view in radians.

• width (int) – Resolution in pixels.

• height (int) – Resolution in pixels.

• xyz (tuple[float, float, float]) – Position/Orientation relative to link frame.

• rpy (tuple[float, float, float]) – Position/Orientation relative to link frame.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

lidar(name, range_min=0.1, range_max=10.0, samples=640, xyz=(0, 0, 0), rpy=(0, 0, 0))

Attach a 1D/2D lidar sensor to this link.

Parameters:

• name (str) – Unique sensor name.

• range_min (float) – Distance limits in meters.

• range_max (float) – Distance limits in meters.

• samples (int) – Number of rays per scan.

• xyz (tuple[float, float, float]) – Position/Orientation relative to link frame.

• rpy (tuple[float, float, float]) – Position/Orientation relative to link frame.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

gpu_lidar(name, range_min=0.1, range_max=10.0, samples=640, xyz=(0, 0, 0), rpy=(0, 0, 0))

Attach a high-performance GPU-accelerated lidar sensor to this link.

Parameters:

• name (str) – Unique sensor name.

• range_min (float) – Distance limits in meters.

• range_max (float) – Distance limits in meters.

• samples (int) – Number of rays per scan.

• xyz (tuple[float, float, float]) – Position/Orientation relative to link frame.

• rpy (tuple[float, float, float]) – Position/Orientation relative to link frame.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

imu(name, update_rate=100.0, xyz=(0, 0, 0), rpy=(0, 0, 0))

Attach an IMU (Inertial Measurement Unit) to this link.

Parameters:

• name (str) – Unique sensor name.

• update_rate (float) – Sampling rate in Hz.

• xyz (tuple[float, float, float]) – Position/Orientation relative to link frame.

• rpy (tuple[float, float, float]) – Position/Orientation relative to link frame.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

gps(name, update_rate=5.0, xyz=(0, 0, 0), rpy=(0, 0, 0))

Attach a GPS sensor to this link.

Parameters:

• name (str) – Unique sensor name.

• update_rate (float) – Sampling rate in Hz.

• xyz (tuple[float, float, float]) – Position/Orientation relative to link frame.

• rpy (tuple[float, float, float]) – Position/Orientation relative to link frame.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

force_torque(name, update_rate=100.0, xyz=(0, 0, 0), rpy=(0, 0, 0))

Attach a force-torque sensor to this link.

Parameters:

• name (str) – Unique sensor name.

• update_rate (float) – Sampling rate in Hz.

• xyz (tuple[float, float, float]) – Position/Orientation relative to link frame.

• rpy (tuple[float, float, float]) – Position/Orientation relative to link frame.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

contact(name, collision, update_rate=50.0)

Attach a contact sensor to this link.

Parameters:

• name (str) – Unique sensor name.

• collision (str) – The name of the collision element to monitor.

• update_rate (float) – Sampling rate in Hz.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

sensor(sensor)

Attach a pre-configured Sensor object to this link.

Parameters:

sensor (Sensor) – Pre-configured Sensor model.

Return type:

LinkBuilder

Returns:

The LinkBuilder instance.

child(name, joint_name=None)

Finalize this link and start building a new child link attached to it.

Parameters:

• name (str) – Name of the new child link.

• joint_name (str | None) – Optional explicit name for the connecting joint.

Return type:

LinkBuilder

Returns:

A new LinkBuilder instance for the child link.

commit()

Finalize this link and return to the main RobotBuilder.

Return type:

IComposer

Returns:

The parent RobotBuilder instance.

root()

Finalize this link as the robot’s root link (no joint).

Raises:

RobotValidationError – If the link already has a parent assigned.

Return type:

IComposer

Returns:

The parent RobotBuilder instance.

build()

Finalize this link and return the completed Robot model.

Return type:

Robot

Returns:

The completed Robot model.

SemanticBuilder

A namespace for SRDF and MoveIt planning groups, named states, and self-collision settings.

class linkforge.core.composer.semantic_builder.SemanticBuilder(builder)

Bases: object

Namespace for SRDF and MoveIt-specific semantic properties.

Accessed via RobotBuilder.semantic.

Parameters:

builder (IComposer)

__init__(builder)

Initialize semantic builder.

Parameters:

builder (IComposer)

done()

Return to the parent RobotBuilder.

Return type:

IComposer

group(name, links=None, joints=None, chains=None, subgroups=None, base_link=None, tip_link=None)

Define a planning group for MoveIt.

Parameters:

• name (str) – Unique name for the group.

• links (list[str] | None) – List of link names to include.

• joints (list[str] | None) – List of joint names to include.

• chains (list[Chain] | None) – List of (base, tip) tuples for kinematic chains.

• subgroups (list[str] | None) – List of other planning group names to include.

• base_link (str | None) – Optional shorthand for chain base.

• tip_link (str | None) – Optional shorthand for chain tip.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

group_state(name, group, values)

Define a named state (e.g. ‘home’) for a planning group.

Parameters:

• name (str) – Unique name for the state.

• group (str) – The group this state belongs to.

• values (dict[str, float | tuple[float, ...]]) – Dictionary of joint names and their positions.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

end_effector(name, group, parent_link, parent_group=None)

Define an end effector for MoveIt.

Parameters:

• name (str) – Unique name for the end effector.

• group (str) – The planning group representing the end effector.

• parent_link (str) – The link it is attached to.

• parent_group (str | None) – Optional parent group (e.g. ‘arm’).

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

passive_joint(name)

Mark a joint as passive (not actuated) for MoveIt.

Parameters:

name (str) – Name of the joint to mark as passive.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

virtual_joint(name, child_link, parent_frame='world', joint_type='fixed')

Define a virtual joint connecting the robot to the world frame.

Parameters:

• name (str) – Unique joint name.

• child_link (str) – The root link of the robot.

• parent_frame (str) – The external frame (e.g., ‘world’, ‘map’).

• joint_type (str) – Joint type (fixed, floating, planar).

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

disable_collisions(link1, link2, reason='Adjacent')

Instruct MoveIt to ignore collisions between two specific links.

Parameters:

• link1 (str) – Names of the links.

• link2 (str) – Names of the links.

• reason (str) – Explanation for disabling (e.g. ‘Adjacent’, ‘Never’).

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

enable_collisions(link1, link2, reason=None)

Explicitly re-enable collision checking between two specific links.

Parameters:

• link1 (str) – Names of the links.

• link2 (str) – Names of the links.

• reason (str | None) – Optional explanation for enabling.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

disable_default_collisions(link)

Disable all default collisions for a specific link.

Parameters:

link (str) – Name of the link.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

joint_property(joint_name, property_name, value)

Add a custom property/metadata to a joint.

Parameters:

• joint_name (str) – Name of the joint.

• property_name (str) – Name of the property.

• value (str) – Property value as string.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

approximate_link_collision(link, spheres)

Add sphere-based collision approximation for a link.

Parameters:

• link (str) – Name of the link.

• spheres (list[SrdfSphere]) – List of SrdfSphere objects.

Return type:

SemanticBuilder

Returns:

The parent RobotBuilder instance.

Interfaces

class linkforge.core.composer.interfaces.IComposer(*args, **kwargs)

Bases: Protocol

Interface for a builder that can contain and manage links.

robot: Robot

link(name, parent=None, joint_name=None)

Start building a new link.

Parameters:

• name (str)

• parent (str | None)

• joint_name (str | None)

Return type:

LinkBuilder

material(name, color=None)

Define a global material.

Parameters:

• name (str)

• color (tuple[float, float, float, float] | None)

Return type:

IComposer

build(validate=True)

Finalize the assembly and return the completed Robot model.

Parameters:

validate (bool)

Return type:

Robot

__init__(*args, **kwargs)