Data Models

Core data structures for representing robots.

Robot

class linkforge.core.Robot(name, version='1.1', materials=<factory>, metadata=<factory>, resource_resolver=<factory>, links=<factory>, joints=<factory>, sensors=<factory>, transmissions=<factory>, ros2_controls=<factory>, gazebo_elements=<factory>, semantic=<factory>)

Bases: object

Complete robot description containing links, joints, and metadata.

Acts as the central hub of the LinkForge IR, maintaining rigid bodies (Links) connected by kinematic constraints (Joints), along with sensors, transmissions, and simulation-specific metadata. It provides high-level assembly and traversal APIs.

Parameters:

• name (str)

• version (str)

• materials (dict[str, Material])

• metadata (dict[str, Any])

• resource_resolver (IResourceResolver)

• links (Sequence[Link])

• joints (Sequence[Joint])

• sensors (Sequence[Sensor])

• transmissions (Sequence[Transmission])

• ros2_controls (Sequence[Ros2Control])

• gazebo_elements (Sequence[GazeboElement])

• semantic (SemanticRobotDescription)

name: str

version: str = '1.1'

materials: dict[str, Material]

metadata: dict[str, Any]

resource_resolver: IResourceResolver

links: Sequence[Link]

joints: Sequence[Joint]

sensors: Sequence[Sensor]

transmissions: Sequence[Transmission]

ros2_controls: Sequence[Ros2Control]

gazebo_elements: Sequence[GazeboElement]

semantic: SemanticRobotDescription

__post_init__()

Initialize and index the robot structure.

Return type:

None

clone()

Create a deep copy of the robot model.

Return type:

Robot

normalized()

Return a new Robot with all components sorted by name.

This ensures that structural equality checks are order-independent.

Return type:

Robot

prefix_all(prefix)

Add a namespace prefix to all components in the robot.

This is a recursive operation that updates names for links, joints, sensors, transmissions, ros2_control interfaces, and semantic data. It is primarily used during ‘RobotBuilder.attach()’ to prevent name collisions.

Parameters:

prefix (str) – The string prefix to prepend (e.g., arm_).

Return type:

None

merge(component, at_link, joint_name, prefix='', joint_type=JointType.FIXED, origin=None, axis=None, limits=None)

Merge another robot model into this one at a specific link.

This operation combines the kinematic tree, sensors, transmissions, hardware interfaces, and semantic metadata. A new joint is created to connect this robot’s at_link to the sub-robot’s root link.

Parameters:

• component (Robot) – The sub-robot model to attach.

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

• joint_name (str) – Unique name for the new connecting joint.

• prefix (str) – Optional namespace prefix for all elements in the sub-robot.

• joint_type (JointType) – Type of the connecting joint (default: FIXED).

• origin (Transform | None) – Optional relative transform for the connection.

• axis (Vector3 | None) – Optional joint axis (required for non-fixed types).

• limits (JointLimits | None) – Optional joint limits.

Return type:

Robot

Returns:

The current robot instance (self) for method chaining.

Raises:

RobotValidationError – If the attachment link is not found or if merging results in name collisions or kinematic cycles.

add_link(link, overwrite=False)

Add a link to the robot and update indices.

Parameters:

• link (Link) – The Link object to add.

• overwrite (bool) – If True, replaces existing link with same name.

Raises:

RobotValidationError – If a link with the same name already exists and overwrite is False, or if naming conventions are violated.

Return type:

None

add_joint(joint)

Add a joint to the robot and update indices.

Parameters:

joint (Joint) – The Joint object to add.

Raises:

RobotValidationError – If the joint name is a duplicate or if the referenced parent/child links do not exist.

Return type:

None

get_link(name)

Retrieve a link by name using the internal index.

Parameters:

name (str) – The name of the link to find.

Return type:

Link | None

Returns:

The Link object if found, otherwise None.

link(name)

Retrieve a link by name, raising an error if it does not exist.

Parameters:

name (str) – The name of the link to find.

Return type:

Link

Returns:

The Link object.

Raises:

RobotValidationError – If the link is not found.

get_joint(name)

Retrieve a joint by name using the internal index.

Parameters:

name (str) – The name of the joint to find.

Return type:

Joint | None

Returns:

The Joint object if found, otherwise None.

joint(name)

Retrieve a joint by name, raising an error if it does not exist.

Parameters:

name (str) – The name of the joint to find.

Return type:

Joint

Returns:

The Joint object.

Raises:

RobotValidationError – If the joint is not found.

has_link(name)

Check if a link with the given name exists in the robot.

Parameters:

name (str) – The name of the link to check.

Return type:

bool

Returns:

True if the link exists, False otherwise.

has_joint(name)

Check if a joint with the given name exists in the robot.

Parameters:

name (str) – The name of the joint to check.

Return type:

bool

Returns:

True if the joint exists, False otherwise.

get_joints_for_link(link_name, as_parent=True)

Get all joints where the link is parent or child.

Parameters:

• link_name (str) – Name of the link

• as_parent (bool) – If True, get joints where link is parent; if False, where link is child

Return type:

list[Joint]

Returns:

List of matching joints.

get_parent_joint(link_name)

Get the joint that has this link as its child.

In a tree structure, a link has at most one parent joint.

Parameters:

link_name (str) – Name of the link.

Return type:

Joint | None

Returns:

The parent Joint if found, otherwise None.

get_child_joints(link_name)

Get all joints that have this link as their parent.

Parameters:

link_name (str) – Name of the parent link.

Return type:

list[Joint]

Returns:

List of child Joint objects.

get_parent_link(link_name)

Get the parent link of the specified link.

Parameters:

link_name (str) – Name of the child link.

Return type:

Link | None

Returns:

The parent Link object if found, otherwise None.

get_child_links(link_name)

Get all immediate child links of the specified link.

Parameters:

link_name (str) – Name of the parent link.

Return type:

list[Link]

Returns:

List of child Link objects.

get_root_link()

Get the root link of the kinematic tree.

Return type:

Link

Returns:

The root Link object.

Raises:

RobotValidationError – If no root link is found or multiple root links exist.

add_sensor(sensor)

Attach a sensor to the robot model.

Parameters:

sensor (Sensor) – The Sensor object to add.

Raises:

RobotValidationError – If the sensor name is a duplicate or referenced link does not exist.

Return type:

None

get_sensor(name)

Retrieve a sensor by name.

Parameters:

name (str) – The name of the sensor to find.

Return type:

Sensor | None

Returns:

The Sensor object if found, otherwise None.

sensor(name)

Retrieve a sensor by name, raising an error if it does not exist.

Parameters:

name (str) – The name of the sensor to find.

Return type:

Sensor

Returns:

The Sensor object.

Raises:

RobotValidationError – If the sensor is not found.

has_sensor(name)

Check if a sensor with the given name exists.

Parameters:

name (str) – The name of the sensor to check.

Return type:

bool

Returns:

True if the sensor exists, False otherwise.

add_transmission(transmission)

Define a mechanical transmission for one or more joints.

Parameters:

transmission (Transmission) – The Transmission definition to add.

Raises:

RobotValidationError – If the transmission name is a duplicate or referenced joints do not exist.

Return type:

None

get_transmission(name)

Retrieve a transmission by name.

Parameters:

name (str) – The name of the transmission to find.

Return type:

Transmission | None

Returns:

The Transmission object if found, otherwise None.

transmission(name)

Retrieve a transmission by name, raising an error if it does not exist.

Parameters:

name (str) – The name of the transmission to find.

Return type:

Transmission

Returns:

The Transmission object.

Raises:

RobotValidationError – If the transmission is not found.

has_transmission(name)

Check if a transmission with the given name exists.

Parameters:

name (str) – The name of the transmission to check.

Return type:

bool

Returns:

True if the transmission exists, False otherwise.

add_ros2_control(ros2_control)

Register a ros2_control hardware system.

Parameters:

ros2_control (Ros2Control) – The hardware configuration to add.

Raises:

RobotValidationError – If the configuration name is a duplicate.

Return type:

None

update_ros2_control(ros2_control)

Update an existing ros2_control configuration.

Parameters:

ros2_control (Ros2Control) – The updated Ros2Control configuration.

Return type:

None

get_ros2_control(name)

Retrieve a ROS2 Control configuration by name.

Parameters:

name (str) – The name of the configuration to find.

Return type:

Ros2Control | None

Returns:

The Ros2Control object if found, otherwise None.

ros2_control(name)

Retrieve a ROS2 Control configuration by name, raising an error if it does not exist.

Parameters:

name (str) – The name of the configuration to find.

Return type:

Ros2Control

Returns:

The Ros2Control object.

Raises:

RobotValidationError – If the configuration is not found.

has_ros2_control(name)

Check if a ROS2 Control configuration with the given name exists.

Parameters:

name (str) – The name of the configuration to check.

Return type:

bool

Returns:

True if it exists, False otherwise.

add_gazebo_element(element)

Add simulation-specific metadata (Gazebo tags).

Parameters:

element (GazeboElement) – The GazeboElement definition.

Raises:

RobotValidationError – If the referenced link/joint does not exist.

Return type:

None

get_gazebo_elements(reference=None)

Get Gazebo elements, optionally filtered by reference.

Parameters:

reference (str | None) – Optional name of the link/joint to filter by.

Return type:

list[GazeboElement]

Returns:

List of matching GazeboElement objects.

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

Add a planning group for MoveIt.

Parameters:

• name (str) – Unique group name.

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

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

• chains (list[Chain] | None) – List of kinematic Chain objects.

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

• base_link (str | None) – Shorthand for a single chain base link.

• tip_link (str | None) – Shorthand for a single chain tip link.

Return type:

Robot

Returns:

The robot instance for chaining.

Raises:

RobotValidationError – If any referenced link, joint, or subgroup does not exist.

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

Disable collision checking between two links.

Parameters:

• link1 (str) – First link name.

• link2 (str) – Second link name.

• reason (str) – Reason for disabling (default: SRDF_REASON_ADJACENT).

Return type:

Robot

Returns:

The robot instance for chaining.

Raises:

RobotValidationError – If link1 or link2 is not found.

disable_all_collisions(links, reason='Adjacent')

Disable collision checking between all pairs in the provided list.

Parameters:

• links (list[str]) – List of link names to disable collisions between.

• reason (str) – Reason for disabling (default: ‘Adjacent’).

Return type:

Robot

Returns:

The robot instance for chaining.

enable_collisions(link1, link2, reason=None)

Explicitly re-enable collision checking between two links.

Parameters:

• link1 (str) – First link name.

• link2 (str) – Second link name.

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

Return type:

Robot

Returns:

The robot instance for chaining.

Raises:

RobotValidationError – If link1 or link2 is not found.

disable_default_collisions(link)

Disable all default collisions for a specific link.

Parameters:

link (str) – Link name.

Return type:

Robot

Returns:

The robot instance for chaining.

Raises:

RobotValidationError – If the link is not found.

add_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:

Robot

Returns:

The robot instance for chaining.

Raises:

RobotValidationError – If the joint is not found.

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:

Robot

Returns:

The robot instance for chaining.

Raises:

RobotValidationError – If the link is not found.

property graph: KinematicGraph

Get the formal kinematic graph representing the robot’s structure.

This is built on demand (and cached) to ensure it reflects the current state of links and joints with optimal performance.

property root_link: Link

Get the root link of the kinematic tree.

The root link is the one that is never a child in any joint.

property has_cycle: bool

Check for cycles in the kinematic tree.

property total_mass: float

Calculate total mass of the robot.

property degrees_of_freedom: int

Calculate total degrees of freedom (actuated joints only).

export_urdf(validate=True, pretty_print=True)

Export the assembled robot to URDF XML.

Parameters:

• validate (bool) – Whether to run full kinematic validation (default: True).

• pretty_print (bool) – Whether to indent the XML (default: True).

Return type:

str

Returns:

URDF XML string.

export_srdf(validate=True, pretty_print=True)

Export the assembled semantic description to SRDF XML.

Parameters:

• validate (bool) – Whether to validate (default: True).

• pretty_print (bool) – Whether to indent the XML (default: True).

Return type:

str

Returns:

SRDF XML string.

__str__()

Return a lightweight human-readable summary of the robot.

Return type:

str

summary()

Return a detailed architectural summary and validity status.

This method performs a deep kinematic analysis, which may be computationally expensive on first call as it builds the graph.

Return type:

str

resolve_resource(uri, relative_to=None)

Resolve a resource URI using the robot’s configured resolver.

Parameters:

• uri (str) – The resource URI to resolve (e.g. mesh path, package://).

• relative_to (Path | None) – Optional base directory for relative path resolution.

Return type:

Path

Returns:

The resolved absolute Path.

__init__(name, version='1.1', materials=<factory>, metadata=<factory>, resource_resolver=<factory>, links=<factory>, joints=<factory>, sensors=<factory>, transmissions=<factory>, ros2_controls=<factory>, gazebo_elements=<factory>, semantic=<factory>)

Parameters:

• name (str)

• version (str)

• materials (dict[str, Material])

• metadata (dict[str, Any])

• resource_resolver (IResourceResolver)

• links (Sequence[Link])

• joints (Sequence[Joint])

• sensors (Sequence[Sensor])

• transmissions (Sequence[Transmission])

• ros2_controls (Sequence[Ros2Control])

• gazebo_elements (Sequence[GazeboElement])

• semantic (SemanticRobotDescription)

Link

class linkforge.core.Link(name, inertial=None, physics=<factory>, visuals=<factory>, collisions=<factory>)

Bases: object

Robot link representing a rigid body in a kinematic chain.

A link is a rigid body defined by its name, physical properties (inertial), and geometric representations (visual/collision). It serves as a node in the kinematic graph.

Parameters:

• name (str)

• inertial (Inertial | None)

• physics (LinkPhysics)

• visuals (Sequence[Visual])

• collisions (Sequence[Collision])

name: str

inertial: Inertial | None = None

physics: LinkPhysics

visuals: Sequence[Visual]

collisions: Sequence[Collision]

__post_init__()

Validate link.

Return type:

None

add_visual(visual)

Add a visual representation.

Parameters:

visual (Visual)

Return type:

None

add_collision(collision)

Add a collision representation.

Parameters:

collision (Collision)

Return type:

None

property mass: float

Get link mass (0.0 if no inertial properties are defined).

property inertia: InertiaTensor

Get link inertia tensor (zero tensor if not defined).

property inertial_origin: Transform

Get inertial origin (identity if not defined).

with_prefix(prefix)

Create a new link with a prefixed name and sub-elements.

Parameters:

prefix (str)

Return type:

Link

__init__(name, inertial=None, physics=<factory>, visuals=<factory>, collisions=<factory>)

Parameters:

• name (str)

• inertial (Inertial | None)

• physics (LinkPhysics)

• visuals (Sequence[Visual])

• collisions (Sequence[Collision])

class linkforge.core.Visual(geometry, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), material=None, name=None)

Bases: object

Visual representation of a link.

Parameters:

• geometry (Box | Cylinder | Sphere | Mesh)

• origin (Transform)

• material (Material | None)

• name (str | None)

geometry: Box | Cylinder | Sphere | Mesh

origin: Transform = Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0))

material: Material | None = None

name: str | None = None

with_prefix(prefix)

Create a new visual with a prefixed name and material.

Parameters:

prefix (str)

Return type:

Visual

__init__(geometry, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), material=None, name=None)

Parameters:

• geometry (Box | Cylinder | Sphere | Mesh)

• origin (Transform)

• material (Material | None)

• name (str | None)

class linkforge.core.Collision(geometry, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), name=None)

Bases: object

Collision representation of a link.

Parameters:

• geometry (Box | Cylinder | Sphere | Mesh)

• origin (Transform)

• name (str | None)

geometry: Box | Cylinder | Sphere | Mesh

origin: Transform = Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0))

name: str | None = None

with_prefix(prefix)

Create a new collision with a prefixed name.

Parameters:

prefix (str)

Return type:

Collision

__init__(geometry, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), name=None)

Parameters:

• geometry (Box | Cylinder | Sphere | Mesh)

• origin (Transform)

• name (str | None)

class linkforge.core.Inertial(mass, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), inertia=<factory>)

Bases: object

Inertial properties of a robot link.

Parameters:

• mass (float)

• origin (Transform)

• inertia (InertiaTensor)

mass: float

origin: Transform = Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0))

inertia: InertiaTensor

__post_init__()

Validate inertial properties.

Raises:

RobotPhysicsError – If mass is negative.

Return type:

None

__init__(mass, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), inertia=<factory>)

Parameters:

• mass (float)

• origin (Transform)

• inertia (InertiaTensor)

class linkforge.core.InertiaTensor(ixx, iyy, izz, ixy=0.0, ixz=0.0, iyz=0.0)

Bases: object

3x3 inertia tensor representation.

Symmetric tensor with 6 unique components: [ ixx ixy ixz ] [ ixy iyy iyz ] [ ixz iyz izz ]

The tensor must be physically plausible. Diagonals must be positive values, and the principal moments must satisfy the triangle inequality for rigid body mass distribution.

Parameters:

• ixx (float)

• iyy (float)

• izz (float)

• ixy (float)

• ixz (float)

• iyz (float)

ixx: float

iyy: float

izz: float

ixy: float = 0.0

ixz: float = 0.0

iyz: float = 0.0

__post_init__()

Validate inertia tensor values.

Return type:

None

classmethod stability_floor()

Create a minimal valid inertia tensor for stability (e.g. massless links).

Returns a tensor with MIN_REASONABLE_INERTIA on the diagonals to prevent physics solver instability.

Return type:

InertiaTensor

__init__(ixx, iyy, izz, ixy=0.0, ixz=0.0, iyz=0.0)

Parameters:

• ixx (float)

• iyy (float)

• izz (float)

• ixy (float)

• ixz (float)

• iyz (float)

… autoclass:: linkforge.core.models.link.LinkPhysics

members:

undoc-members:

show-inheritance:

Joint

class linkforge.core.Joint(name, type, parent, child, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), axis=None, limits=None, dynamics=None, mimic=None, safety_controller=None, calibration=None)

Bases: object

Robot joint defining the kinematic connection between two links.

A joint couples a parent link to a child link with a specific degree of freedom (DOF) and mechanical limits. It defines the coordinate transformation from parent to child.

Parameters:

• name (str)

• type (JointType)

• parent (str)

• child (str)

• origin (Transform)

• axis (Vector3 | None)

• limits (JointLimits | None)

• dynamics (JointDynamics | None)

• mimic (JointMimic | None)

• safety_controller (JointSafetyController | None)

• calibration (JointCalibration | None)

name: str

type: JointType

parent: str

child: str

origin: Transform = Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0))

axis: Vector3 | None = None

limits: JointLimits | None = None

dynamics: JointDynamics | None = None

mimic: JointMimic | None = None

safety_controller: JointSafetyController | None = None

calibration: JointCalibration | None = None

__post_init__()

Validate and normalize joint properties.

Return type:

None

property degrees_of_freedom: int

Get number of degrees of freedom.

with_prefix(prefix)

Create a new joint with prefixed name, parent, child, and mimic.

Parameters:

prefix (str)

Return type:

Joint

__init__(name, type, parent, child, origin=Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0)), axis=None, limits=None, dynamics=None, mimic=None, safety_controller=None, calibration=None)

Parameters:

• name (str)

• type (JointType)

• parent (str)

• child (str)

• origin (Transform)

• axis (Vector3 | None)

• limits (JointLimits | None)

• dynamics (JointDynamics | None)

• mimic (JointMimic | None)

• safety_controller (JointSafetyController | None)

• calibration (JointCalibration | None)

class linkforge.core.JointType(*values)

Bases: StrEnum

Standard robot joint types.

REVOLUTE = 'revolute'

CONTINUOUS = 'continuous'

PRISMATIC = 'prismatic'

FIXED = 'fixed'

FLOATING = 'floating'

PLANAR = 'planar'

class linkforge.core.JointLimits(lower=None, upper=None, effort=10.0, velocity=1.0)

Bases: object

Joint limits for revolute/prismatic joints.

For CONTINUOUS joints, lower/upper are optional (only effort/velocity used).

Parameters:

• lower (float | None)

• upper (float | None)

• effort (float)

• velocity (float)

lower: float | None = None

upper: float | None = None

effort: float = 10.0

velocity: float = 1.0

__post_init__()

Validate limits.

Return type:

None

__init__(lower=None, upper=None, effort=10.0, velocity=1.0)

Parameters:

• lower (float | None)

• upper (float | None)

• effort (float)

• velocity (float)

class linkforge.core.JointDynamics(damping=0.0, friction=0.0)

Bases: object

Joint dynamics properties defining physical behavior.

Parameters:

• damping (float)

• friction (float)

damping: float = 0.0

friction: float = 0.0

__post_init__()

Validate dynamics.

Return type:

None

__init__(damping=0.0, friction=0.0)

Parameters:

• damping (float)

• friction (float)

class linkforge.core.JointMimic(joint, multiplier=1.0, offset=0.0)

Bases: object

Joint mimic configuration (this joint mimics another).

Parameters:

• joint (str)

• multiplier (float)

• offset (float)

joint: str

multiplier: float = 1.0

offset: float = 0.0

with_prefix(prefix)

Create a new mimic with a prefixed joint name.

Parameters:

prefix (str)

Return type:

JointMimic

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

Parameters:

• joint (str)

• multiplier (float)

• offset (float)

… autoclass:: linkforge.core.models.joint.JointSafetyController

members:

undoc-members:

show-inheritance:

Geometry

class linkforge.core.Box(size)

Bases: object

Box geometry representing a rectangular cuboid.

Parameters:

size (Vector3)

size: Vector3

__post_init__()

Validate box dimensions.

Return type:

None

property type: GeometryType

Get the geometry primitive type (BOX).

volume()

Calculate volume.

Return type:

float

__init__(size)

Parameters:

size (Vector3)

class linkforge.core.Cylinder(radius, length)

Bases: object

Cylinder geometry aligned along the local Z-axis.

Parameters:

• radius (float)

• length (float)

radius: float

length: float

__post_init__()

Validate cylinder dimensions.

Return type:

None

property type: GeometryType

Get the geometry primitive type (CYLINDER).

volume()

Calculate volume of the cylinder.

Return type:

float

__init__(radius, length)

Parameters:

• radius (float)

• length (float)

class linkforge.core.Sphere(radius)

Bases: object

Sphere geometry.

Parameters:

radius (float)

radius: float

__post_init__()

Validate sphere dimensions.

Return type:

None

property type: GeometryType

Get the geometry primitive type (SPHERE).

volume()

Calculate volume of the sphere.

Return type:

float

__init__(radius)

Parameters:

radius (float)

class linkforge.core.Mesh(resource, scale=<factory>)

Bases: object

Mesh geometry from file or URI.

Parameters:

• resource (str)

• scale (Vector3)

resource: str

scale: Vector3

__post_init__()

Validate mesh scale.

Return type:

None

property type: GeometryType

Get the geometry primitive type (MESH).

__init__(resource, scale=<factory>)

Parameters:

• resource (str)

• scale (Vector3)

class linkforge.core.Vector3(x, y, z)

Bases: object

3D vector representation for spatial coordinates, axes, and scaling.

Parameters:

• x (float)

• y (float)

• z (float)

x: float

y: float

z: float

__iter__()

Allow unpacking: x, y, z = vector.

Return type:

Iterator[float]

to_tuple()

Convert to tuple.

Return type:

tuple[float, float, float]

__str__()

String representation.

Return type:

str

__init__(x, y, z)

Parameters:

• x (float)

• y (float)

• z (float)

class linkforge.core.Transform(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0))

Bases: object

Spatial transformation representing a 6-DOF pose.

Combines XYZ position (Vector3) and RPY (Roll-Pitch-Yaw) orientation in radians, following the standard robotics convention.

Parameters:

• xyz (Vector3)

• rpy (Vector3)

xyz: Vector3 = Vector3(x=0.0, y=0.0, z=0.0)

rpy: Vector3 = Vector3(x=0.0, y=0.0, z=0.0)

classmethod identity()

Create identity transform.

Return type:

Transform

__str__()

String representation.

Return type:

str

__init__(xyz=Vector3(x=0.0, y=0.0, z=0.0), rpy=Vector3(x=0.0, y=0.0, z=0.0))

Parameters:

• xyz (Vector3)

• rpy (Vector3)

… autoclass:: linkforge.core.models.geometry.GeometryType

members:

undoc-members:

show-inheritance:

Sensor

class linkforge.core.Sensor(name, type, link_name, update_rate=30.0, always_on=True, visualize=False, camera_info=None, lidar_info=None, imu_info=None, gps_info=None, contact_info=None, force_torque_info=None, origin=<factory>, topic=None, plugin=None)

Bases: object

Unified sensor model for simulation and hardware abstraction.

Sensors are logical entities attached to robot links. They define data acquisition parameters (update rate, FOV, range) and are exported to simulation-specific formats (e.g., Gazebo <sensor> tags).

Parameters:

• name (str)

• type (SensorType)

• link_name (str)

• update_rate (float)

• always_on (bool)

• visualize (bool)

• camera_info (CameraInfo | None)

• lidar_info (LidarInfo | None)

• imu_info (IMUInfo | None)

• gps_info (GPSInfo | None)

• contact_info (ContactInfo | None)

• force_torque_info (ForceTorqueInfo | None)

• origin (Transform)

• topic (str | None)

• plugin (GazeboPlugin | None)

name: str

type: SensorType

link_name: str

update_rate: float = 30.0

always_on: bool = True

visualize: bool = False

camera_info: CameraInfo | None = None

lidar_info: LidarInfo | None = None

imu_info: IMUInfo | None = None

gps_info: GPSInfo | None = None

contact_info: ContactInfo | None = None

force_torque_info: ForceTorqueInfo | None = None

origin: Transform

topic: str | None = None

plugin: GazeboPlugin | None = None

__post_init__()

Validate sensor configuration.

Return type:

None

with_prefix(prefix)

Create a new sensor with prefixed name, link, topic, contact_info, and plugin.

Parameters:

prefix (str)

Return type:

Sensor

__init__(name, type, link_name, update_rate=30.0, always_on=True, visualize=False, camera_info=None, lidar_info=None, imu_info=None, gps_info=None, contact_info=None, force_torque_info=None, origin=<factory>, topic=None, plugin=None)

Parameters:

• name (str)

• type (SensorType)

• link_name (str)

• update_rate (float)

• always_on (bool)

• visualize (bool)

• camera_info (CameraInfo | None)

• lidar_info (LidarInfo | None)

• imu_info (IMUInfo | None)

• gps_info (GPSInfo | None)

• contact_info (ContactInfo | None)

• force_torque_info (ForceTorqueInfo | None)

• origin (Transform)

• topic (str | None)

• plugin (GazeboPlugin | None)

class linkforge.core.SensorType(*values)

Bases: StrEnum

Enumeration of supported sensor types in the LinkForge IR.

Note on LIDAR vs RAY: - LIDAR is the modern Gazebo Harmonic/GZ standard (“lidar”) - RAY is provided for Gazebo Classic / ROS1 compatibility (“ray”)

CAMERA = 'camera'

DEPTH_CAMERA = 'depth_camera'

LIDAR = 'lidar'

RAY = 'ray'

GPU_LIDAR = 'gpu_lidar'

IMU = 'imu'

GPS = 'gps'

FORCE_TORQUE = 'force_torque'

CONTACT = 'contact'

class linkforge.core.CameraInfo(horizontal_fov=1.047, width=640, height=480, format='R8G8B8', near_clip=0.1, far_clip=100.0, noise=None)

Bases: object

Camera-specific sensor information.

Parameters:

• horizontal_fov (float)

• width (int)

• height (int)

• format (str)

• near_clip (float)

• far_clip (float)

• noise (SensorNoise | None)

horizontal_fov: float = 1.047

width: int = 640

height: int = 480

format: str = 'R8G8B8'

near_clip: float = 0.1

far_clip: float = 100.0

noise: SensorNoise | None = None

__post_init__()

Validate camera parameters.

Return type:

None

__init__(horizontal_fov=1.047, width=640, height=480, format='R8G8B8', near_clip=0.1, far_clip=100.0, noise=None)

Parameters:

• horizontal_fov (float)

• width (int)

• height (int)

• format (str)

• near_clip (float)

• far_clip (float)

• noise (SensorNoise | None)

class linkforge.core.LidarInfo(horizontal_samples=640, horizontal_resolution=1.0, horizontal_min_angle=-1.5707963267948966, horizontal_max_angle=1.5707963267948966, vertical_samples=1, vertical_resolution=1.0, vertical_min_angle=0.0, vertical_max_angle=0.0, range_min=0.1, range_max=10.0, range_resolution=0.01, noise=None)

Bases: object

LIDAR/laser scanner sensor information.

Parameters:

• horizontal_samples (int)

• horizontal_resolution (float)

• horizontal_min_angle (float)

• horizontal_max_angle (float)

• vertical_samples (int)

• vertical_resolution (float)

• vertical_min_angle (float)

• vertical_max_angle (float)

• range_min (float)

• range_max (float)

• range_resolution (float)

• noise (SensorNoise | None)

horizontal_samples: int = 640

horizontal_resolution: float = 1.0

horizontal_min_angle: float = -1.5707963267948966

horizontal_max_angle: float = 1.5707963267948966

vertical_samples: int = 1

vertical_resolution: float = 1.0

vertical_min_angle: float = 0.0

vertical_max_angle: float = 0.0

range_min: float = 0.1

range_max: float = 10.0

range_resolution: float = 0.01

noise: SensorNoise | None = None

__post_init__()

Validate LIDAR parameters.

Return type:

None

__init__(horizontal_samples=640, horizontal_resolution=1.0, horizontal_min_angle=-1.5707963267948966, horizontal_max_angle=1.5707963267948966, vertical_samples=1, vertical_resolution=1.0, vertical_min_angle=0.0, vertical_max_angle=0.0, range_min=0.1, range_max=10.0, range_resolution=0.01, noise=None)

Parameters:

• horizontal_samples (int)

• horizontal_resolution (float)

• horizontal_min_angle (float)

• horizontal_max_angle (float)

• vertical_samples (int)

• vertical_resolution (float)

• vertical_min_angle (float)

• vertical_max_angle (float)

• range_min (float)

• range_max (float)

• range_resolution (float)

• noise (SensorNoise | None)

class linkforge.core.IMUInfo(angular_velocity_noise=None, linear_acceleration_noise=None)

Bases: object

IMU sensor information.

Parameters:

• angular_velocity_noise (SensorNoise | None)

• linear_acceleration_noise (SensorNoise | None)

angular_velocity_noise: SensorNoise | None = None

linear_acceleration_noise: SensorNoise | None = None

__init__(angular_velocity_noise=None, linear_acceleration_noise=None)

Parameters:

• angular_velocity_noise (SensorNoise | None)

• linear_acceleration_noise (SensorNoise | None)

class linkforge.core.GPSInfo(position_sensing_horizontal_noise=None, position_sensing_vertical_noise=None, velocity_sensing_horizontal_noise=None, velocity_sensing_vertical_noise=None)

Bases: object

GPS sensor information.

Parameters:

• position_sensing_horizontal_noise (SensorNoise | None)

• position_sensing_vertical_noise (SensorNoise | None)

• velocity_sensing_horizontal_noise (SensorNoise | None)

• velocity_sensing_vertical_noise (SensorNoise | None)

position_sensing_horizontal_noise: SensorNoise | None = None

position_sensing_vertical_noise: SensorNoise | None = None

velocity_sensing_horizontal_noise: SensorNoise | None = None

velocity_sensing_vertical_noise: SensorNoise | None = None

__init__(position_sensing_horizontal_noise=None, position_sensing_vertical_noise=None, velocity_sensing_horizontal_noise=None, velocity_sensing_vertical_noise=None)

Parameters:

• position_sensing_horizontal_noise (SensorNoise | None)

• position_sensing_vertical_noise (SensorNoise | None)

• velocity_sensing_horizontal_noise (SensorNoise | None)

• velocity_sensing_vertical_noise (SensorNoise | None)

… autoclass:: linkforge.core.models.sensor.ContactInfo

members:

undoc-members:

show-inheritance:

… autoclass:: linkforge.core.models.sensor.ForceTorqueInfo

members:

undoc-members:

show-inheritance:

… autoclass:: linkforge.core.models.sensor.SensorNoise

members:

undoc-members:

show-inheritance:

Transmission

Standard URDF transmission model for ros_control/ros2_control integration.

While Ros2Control provides a modern dashboard-based workflow, Transmission remains fully supported for compatibility and standard URDF workflows.

class linkforge.core.Transmission(name, type, joints=<factory>, actuators=<factory>, parameters=<factory>)

Bases: object

Mechanical transmission mapping between joints and actuators.

Transmissions describe how mathematical joint states relate to physical actuator commands, including hardware interface specifications for ros2_control.

Parameters:

• name (str)

• type (str)

• joints (Sequence[TransmissionJoint])

• actuators (Sequence[TransmissionActuator])

• parameters (dict[str, str])

name: str

type: str

joints: Sequence[TransmissionJoint]

actuators: Sequence[TransmissionActuator]

parameters: dict[str, str]

__post_init__()

Validate transmission configuration.

Return type:

None

with_prefix(prefix)

Create a new transmission with prefixed name, joints, and actuators.

Parameters:

prefix (str)

Return type:

Transmission

normalized()

Return a new transmission with sorted joints and actuators.

Return type:

Transmission

classmethod create_simple(name, joint_name, actuator_name=None, mechanical_reduction=1.0, hardware_interfaces=None)

Create a simple 1-to-1 transmission.

Parameters:

• name (str) – Transmission name

• joint_name (str) – Name of the joint

• actuator_name (str | None) – Name of the actuator (defaults to joint_name + “_motor”)

• mechanical_reduction (float) – Gear ratio (default 1.0)

• hardware_interfaces (list[str] | None) – Interface types (default [HW_IF_POSITION])

Return type:

Transmission

Returns:

Configured simple transmission

classmethod create_differential(name, joint1_name, joint2_name, actuator1_name=None, actuator2_name=None, mechanical_reduction=1.0, hardware_interfaces=None)

Create a differential transmission (2 actuators, 2 joints).

Parameters:

• name (str) – Transmission name

• joint1_name (str) – First joint name

• joint2_name (str) – Second joint name

• actuator1_name (str | None) – First actuator name (defaults to joint1_name + “_motor”)

• actuator2_name (str | None) – Second actuator name (defaults to joint2_name + “_motor”)

• mechanical_reduction (float) – Gear ratio (default 1.0)

• hardware_interfaces (list[str] | None) – Interface types (default [HW_IF_POSITION])

Return type:

Transmission

Returns:

Configured differential transmission

__init__(name, type, joints=<factory>, actuators=<factory>, parameters=<factory>)

Parameters:

• name (str)

• type (str)

• joints (Sequence[TransmissionJoint])

• actuators (Sequence[TransmissionActuator])

• parameters (dict[str, str])

class linkforge.core.TransmissionJoint(name, hardware_interfaces=<factory>, mechanical_reduction=1.0, offset=0.0)

Bases: object

Joint specification in a transmission.

Parameters:

• name (str)

• hardware_interfaces (Sequence[str])

• mechanical_reduction (float | None)

• offset (float)

name: str

hardware_interfaces: Sequence[str]

mechanical_reduction: float | None = 1.0

offset: float = 0.0

__post_init__()

Validate transmission joint.

Return type:

None

with_prefix(prefix)

Create a new transmission joint with a prefixed name.

Parameters:

prefix (str)

Return type:

TransmissionJoint

normalized()

Return a new transmission joint with sorted interfaces.

Return type:

TransmissionJoint

__init__(name, hardware_interfaces=<factory>, mechanical_reduction=1.0, offset=0.0)

Parameters:

• name (str)

• hardware_interfaces (Sequence[str])

• mechanical_reduction (float | None)

• offset (float)

class linkforge.core.TransmissionActuator(name, hardware_interfaces=<factory>, mechanical_reduction=1.0, offset=0.0)

Bases: object

Actuator specification in a transmission.

Parameters:

• name (str)

• hardware_interfaces (Sequence[str])

• mechanical_reduction (float | None)

• offset (float)

name: str

hardware_interfaces: Sequence[str]

mechanical_reduction: float | None = 1.0

offset: float = 0.0

__post_init__()

Validate transmission actuator.

Return type:

None

with_prefix(prefix)

Create a new transmission actuator with a prefixed name.

Parameters:

prefix (str)

Return type:

TransmissionActuator

normalized()

Return a new transmission actuator with sorted interfaces.

Return type:

TransmissionActuator

__init__(name, hardware_interfaces=<factory>, mechanical_reduction=1.0, offset=0.0)

Parameters:

• name (str)

• hardware_interfaces (Sequence[str])

• mechanical_reduction (float | None)

• offset (float)

Material

class linkforge.core.Material(name, color=None, texture=None)

Bases: object

Material properties defining the visual surface of a robot link.

Parameters:

• name (str)

• color (Color | None)

• texture (str | None)

name: str

color: Color | None = None

texture: str | None = None

__post_init__()

Validate material has at least color or texture.

Return type:

None

with_prefix(prefix)

Create a new material with a prefixed name.

Parameters:

prefix (str)

Return type:

Material

__init__(name, color=None, texture=None)

Parameters:

• name (str)

• color (Color | None)

• texture (str | None)

class linkforge.core.Color(r, g, b, a=1.0)

Bases: object

RGBA color representation with components in range [0.0, 1.0].

Parameters:

• r (float)

• g (float)

• b (float)

• a (float)

r: float

g: float

b: float

a: float = 1.0

__post_init__()

Validate color values.

Return type:

None

classmethod white()

Standard white color (1.0, 1.0, 1.0, 1.0).

Return type:

Color

classmethod black()

Standard black color (0.0, 0.0, 0.0, 1.0).

Return type:

Color

classmethod grey()

Standard grey color from constants.

Return type:

Color

to_tuple()

Convert to RGBA tuple.

Return type:

tuple[float, float, float, float]

__str__()

String representation formatted as ‘R G B A’.

Return type:

str

__init__(r, g, b, a=1.0)

Parameters:

• r (float)

• g (float)

• b (float)

• a (float)

Gazebo

class linkforge.core.GazeboElement(reference=None, properties=<factory>, plugins=<factory>, material=None, static=None, stop_cfm=None, stop_erp=None, provide_feedback=None, implicit_spring_damper=None)

Bases: object

Simulation-specific metadata container for Gazebo.

Encapsulates parameters that are not part of the standard URDF spec but are required for high-fidelity physics (e.g., DART/ODE parameters) or visual appearance in Gazebo.

All mutable inputs (properties dict, plugins sequence) are converted to immutable structures in __post_init__ to guarantee true deep immutability even though the class is frozen=True.

Parameters:

• reference (str | None)

• properties (Mapping[str, str])

• plugins (Sequence[GazeboPlugin])

• material (str | None)

• static (bool | None)

• stop_cfm (float | None)

• stop_erp (float | None)

• provide_feedback (bool | None)

• implicit_spring_damper (bool | None)

reference: str | None

properties: Mapping[str, str]

plugins: Sequence[GazeboPlugin]

material: str | None

static: bool | None

stop_cfm: float | None

stop_erp: float | None

provide_feedback: bool | None

implicit_spring_damper: bool | None

__post_init__()

Validate and deeply immutabilise the Gazebo element.

Return type:

None

with_prefix(prefix)

Create a new gazebo element with prefixed reference and plugins.

Parameters:

prefix (str)

Return type:

GazeboElement

__deepcopy__(memo)

Deep copy: Since this object is deeply immutable, return self.

Parameters:

memo (dict[int, Any])

Return type:

GazeboElement

__init__(reference=None, properties=<factory>, plugins=<factory>, material=None, static=None, stop_cfm=None, stop_erp=None, provide_feedback=None, implicit_spring_damper=None)

Parameters:

• reference (str | None)

• properties (Mapping[str, str])

• plugins (Sequence[GazeboPlugin])

• material (str | None)

• static (bool | None)

• stop_cfm (float | None)

• stop_erp (float | None)

• provide_feedback (bool | None)

• implicit_spring_damper (bool | None)

class linkforge.core.GazeboPlugin(name, filename, parameters=<factory>, raw_xml=None)

Bases: object

Gazebo plugin specification for functional extensions.

parameters is stored as an immutable MappingProxyType regardless of what is passed at construction time, ensuring that the frozen=True contract is not silently violated by callers mutating the dict.

Parameters:

• name (str)

• filename (str)

• parameters (Mapping[str, str])

• raw_xml (str | None)

name: str

filename: str

parameters: Mapping[str, str]

raw_xml: str | None

__post_init__()

Validate and deeply immutabilise plugin configuration.

Return type:

None

with_prefix(prefix)

Create a new plugin with a prefixed name.

Parameters:

prefix (str)

Return type:

GazeboPlugin

__deepcopy__(memo)

Deep copy: Since this object is deeply immutable, return self.

Parameters:

memo (dict[int, Any])

Return type:

GazeboPlugin

__init__(name, filename, parameters=<factory>, raw_xml=None)

Parameters:

• name (str)

• filename (str)

• parameters (Mapping[str, str])

• raw_xml (str | None)

ROS2 Control

class linkforge.core.Ros2Control(name, type='system', hardware_plugin='', joints=<factory>, sensors=<factory>, parameters=<factory>)

Bases: object

Hardware interface abstraction for ROS 2 Control.

This model describes a hardware system (system, actuator, or sensor), its associated joints/sensors, and the hardware plugin used to communicate with the physical or simulated hardware.

Parameters:

• name (str)

• type (str)

• hardware_plugin (str)

• joints (Sequence[Ros2ControlJoint])

• sensors (Sequence[Ros2ControlSensor])

• parameters (dict[str, str])

name: str

type: str = 'system'

hardware_plugin: str = ''

joints: Sequence[Ros2ControlJoint]

sensors: Sequence[Ros2ControlSensor]

parameters: dict[str, str]

__post_init__()

Validate ros2_control configuration.

Return type:

None

with_prefix(prefix)

Create a new control block with prefixed name and joints.

Parameters:

prefix (str)

Return type:

Ros2Control

normalized()

Return a new control block with sorted joints and sensors for comparison.

Return type:

Ros2Control

__init__(name, type='system', hardware_plugin='', joints=<factory>, sensors=<factory>, parameters=<factory>)

Parameters:

• name (str)

• type (str)

• hardware_plugin (str)

• joints (Sequence[Ros2ControlJoint])

• sensors (Sequence[Ros2ControlSensor])

• parameters (dict[str, str])

class linkforge.core.Ros2ControlJoint(name, command_interfaces=<factory>, state_interfaces=<factory>, parameters=<factory>)

Joint configuration in a ros2_control block.

Parameters:

• name (str)

• command_interfaces (Sequence[str])

• state_interfaces (Sequence[str])

• parameters (dict[str, str])

name: str

command_interfaces: Sequence[str]

state_interfaces: Sequence[str]

parameters: dict[str, str]

__post_init__()

Validate joint configuration.

Return type:

None

with_prefix(prefix)

Create a new control joint with a prefixed name.

Parameters:

prefix (str)

Return type:

Ros2ControlJoint

normalized()

Return a new control joint with sorted interfaces.

Return type:

Ros2ControlJoint

__init__(name, command_interfaces=<factory>, state_interfaces=<factory>, parameters=<factory>)

Parameters:

• name (str)

• command_interfaces (Sequence[str])

• state_interfaces (Sequence[str])

• parameters (dict[str, str])

class linkforge.core.models.ros2_control.Ros2ControlSensor(name, state_interfaces=<factory>, parameters=<factory>)

Bases: object

Sensor configuration in a ros2_control block.

Parameters:

• name (str)

• state_interfaces (Sequence[str])

• parameters (dict[str, str])

name: str

state_interfaces: Sequence[str]

parameters: dict[str, str]

__post_init__()

Validate sensor configuration.

Return type:

None

with_prefix(prefix)

Create a new control sensor with a prefixed name.

Parameters:

prefix (str)

Return type:

Ros2ControlSensor

normalized()

Return a new control sensor with sorted interfaces.

Return type:

Ros2ControlSensor

__init__(name, state_interfaces=<factory>, parameters=<factory>)

Parameters:

• name (str)

• state_interfaces (Sequence[str])

• parameters (dict[str, str])