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.

Geometry Roles and Types

LinkForge uses custom properties to explicitly track the role and primitive type of meshes within a link, allowing for multiple visuals and collisions per link.

Role	Property	Export Behavior
Visual Geometry	geom_role = "VISUAL"	Exported to the <visual> tag. Can be any number of meshes.
Collision Geometry	geom_role = "COLLISION"	Exported to the <collision> tag. Displayed as wireframe, in-front, and hidden from renders.

The specific geometry type (mesh, box, cylinder, sphere) is explicitly declared in the UI and stored in the geometry_type property, ensuring exact mapping to URDF tags.

Sanitization Rules

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

1. Spaces are replaced with underscores _.

2. Special characters (except underscores and hyphens) are removed.

3. 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.*
Geometry	Object.linkforge_geom.*
Joint	Object.linkforge_joint.*
Sensor	Object.linkforge_sensor.*
Robot	Scene.linkforge.*
ROS2 Control	Scene.linkforge.ros2_control_joints