Reference: Robot Structure & Mapping

This document provides a technical specification of how LinkForge maps Blender objects to URDF elements.

Object Mapping

URDF Element	Blender Object Type	Display Type	Notes
Link	`Empty`	Plain Axes	The coordinate frame of the link.
Visual	`Mesh`	Textured/Solid	Must be a child of a Link Empty.
Collision	`Mesh`	Wireframe	Child of Link Empty. Exported as primitive or simplified mesh.
Joint	`Empty`	Arrows	Colored axes (RGB for XYZ).
Sensor	`Empty`	Sphere	Wireframe sphere. Must be a child of a Link Empty.

Supported Joint Types

Type	Axis Required	Limits Allowed	Description
revolute	Yes	Yes	Hinge joint with range limits (rad).
continuous	Yes	No	Continuous rotation (e.g., wheels).
prismatic	Yes	Yes	Sliding joint with range limits (m).
fixed	No	No	Rigid connection, no motion allowed.
floating	No	No	6-DOF unconstrained movement.
planar	Yes	No	2D motion in a plane normal to the axis.

Supported Geometry Primitives

Primitive	Parameters	Notes
Box	`size: (x, y, z)`	Defined as half-extents or full size based on export.
Cylinder	`radius, length`	Axis of rotation is aligned with Z (standard URDF).
Sphere	`radius`	Pure mathematical sphere.
Mesh	`filename, scale`	Supports `.stl`, `.obj`, and `.dae`.

Naming Conventions

LinkForge uses specific suffixes to identify the role of mesh objects within a link.

Suffix	Role	Export Behavior
`_visual`	Visual Geometry	Exported to the `<visual>` tag.
`_collision`	Collision Geometry	Exported to the `<collision>` tag.

Sanitization Rules

During export, all object names are sanitized to remain compliant with the URDF specification:

Spaces are replaced with underscores _.
Special characters (except underscores and hyphens) are removed.
Leading numbers are prefixed with _ or link_.

Duplicate Name Resolution (Import)

When importing URDFs, LinkForge enforces unique names for all links and joints. If duplicates are found in the source file:

Links: Automatically renamed with a numeric suffix (e.g., base_link_duplicate_1).
Joints: Automatically renamed with a numeric suffix (e.g., joint_duplicate_1).
Warnings: All renames are logged to the console, allowing you to identify and fix the source URDF if needed.

Hierarchy Rules

1. Link Container

A Link is not just a mesh; it is a container.

All visual and collision meshes must be direct children of the Link Empty.
A Link Empty must have its is_robot_link property set to True.

[!IMPORTANT] Offsetting Mesh Origins: In Blender, “Setting Origin” for a mesh only changes its offset relative to its parent Link Empty. It does not move the Link Frame or any associated Joints. If you want to move the “Pivot Point” of a link and its joints, you must move the Link Empty or Joint Empty.

2. Joint Connectivity

Joints in LinkForge operate differently than standard Blender parent-child relationships:

A Joint Empty is not parented to its child link in Blender.
Instead, the Joint Empty stores recursive references to the Parent Link and Child Link in its properties.
This allows LinkForge to build a kinematic tree that stays 100% compliant with URDF, regardless of how objects are organized in the Blender Outliner.

3. Coordinate Systems

Both Blender and URDF use Z-up, right-handed coordinate systems. LinkForge uses direct 1:1 coordinate mapping (no rotations applied during import/export).

Data Integrity & Status

When working with imported robots, LinkForge displays status labels on the Link Empty to communicate data safety:

Imported collision: Geometry preserved: Indicates the collision mesh is locked to the original URDF source.
Auto-Calculate Inertia (Locked): Physics properties are preserved from the original <inertial> tags.

Performance & Scalability

LinkForge uses an O(1) hash-based indexing system for robot components. Large-scale robots (100+ links) maintain interactive performance during selection and property editing.

Lazy Kinematic Tree: The parent-child graph (used for IK and gravity compensation) is computed lazily and cached.
Validation: Real-time linting of 90+ physical and kinematic constraints happens in the background without blocking the UI.
- Disconnected Links: The validator now aggressively checks the kinematic graph to ensure no disconnected islands exist. Every link must ultimately trace back to the root_link (or be the root itself), otherwise export is blocked to prevent broken simulations.

Coordinate Conventions:

Blender Default: Z-up, Y-forward, X-right
URDF/ROS (REP-103): Z-up, X-forward, Y-left

Recommendation: Model your robot using ROS conventions (X-forward) in Blender for intuitive joint configuration, even though Blender’s default is Y-forward.

Joint Axes: Selecting “X”, “Y”, or “Z” in the Joint panel assigns the exact vector (e.g., 1 0 0) based on the Joint Empty’s local orientation.
Origins: The location and rotation of Empties in Blender map directly to the <origin> tag in URDF (XYZ position, RPY rotation).

Property Storage

LinkForge stores all metadata as Custom Properties on the Blender objects. These can be inspected in the “Custom Properties” panel of the Object Data tab, though it is recommended to use the LinkForge Sidebar for editing.

Component	Property Location
Link	`Object.linkforge.*`
Joint	`Object.linkforge_joint.*`
Sensor	`Object.linkforge_sensor.*`
Robot	`Scene.linkforge.*`
ROS2 Control	`Scene.linkforge.ros2_control_joints`