LinkForge

LinkForge

The Programmable Robot Description Engine

(opens in a new tab) (opens in a new tab) Image: Documentation (opens in a new tab) (opens in a new tab) (opens in a new tab) (opens in a new tab) (opens in a new tab)

Writing and maintaining robot descriptions in URDF or SRDF is fragile by design. Inertia values are guessed by hand, collision geometries drift from visual meshes, and physics bugs are discovered only after export (or worse, on physical hardware).

LinkForge treats your robot as source code, not a static document.

Define it programmatically, validate rigid-body physics before export, and compile safely to any standard target. Whether you are building a single prototype in Blender or generating thousands of variants in a headless RL training loop, LinkForge is the validation layer between your design intent and your simulation.

Why LinkForge?

[!TIP] For a deep dive into our long-term technical strategy and the IR philosophy, see VISION.md (opens in a new tab).

Quick Start

Headless Core (CI / ML Pipelines / Scripting)

pip install linkforge-core

from linkforge.core import RobotBuilder, box, cylinder

# 1. Build a robot programmatically
builder = RobotBuilder("my_arm")

builder.link("base_link") \
    .visual(box(0.5, 0.5, 0.1)) \
    .collision() \
    .mass(5.0) \
    .root()

builder.link("arm_link", parent="base_link") \
    .visual(cylinder(radius=0.05, length=0.4), xyz=(0, 0, 0.2)) \
    .collision() \
    .mass(1.0) \
    .revolute(axis=(0, 0, 1), xyz=(0, 0, 0.05), limits=(-3.14, 3.14)) \
    .commit()

# 2. Validate: catches disconnected links, kinematic loops, non-physical inertias
robot = builder.build(validate=True)

# 3. Compile to standard targets
urdf_xml = builder.export_urdf()
srdf_xml = builder.export_srdf()

Modular Assembly

Compose validated sub-assemblies from reusable robot components:

from linkforge.core import RobotBuilder, read_urdf

base_builder  = RobotBuilder(robot=read_urdf("mobile_base.urdf"))
arm_builder   = RobotBuilder(robot=read_urdf("manipulator.urdf"))

# Attach arm onto the base, auto-resolving naming conflicts
base_builder.attach(
    arm_builder,
    at_link="top_plate",
    prefix="left_arm_",
    xyz=(0, 0, 0.1),
)

# Add a MoveIt 2 planning group for the combined assembly
base_builder.semantic.group(
    "arm_chain",
    base_link="top_plate",
    tip_link="left_arm_end_effector",
)

robot = base_builder.build(validate=True)
urdf_xml = base_builder.export_urdf()
srdf_xml = base_builder.export_srdf()

Blender Visual Designer (Full Platform)

Design robots visually in Blender - all physics validation and export pipelines are backed by the same linkforge-core engine. See the Installation section below to set it up.

Technical Specifications

Installation

Headless Python Core

Requirements: Python 3.11+

pip install linkforge-core

No Blender, no GUI dependencies. Full Composer API, parsers, generators, validators, and physics engine.

Blender Visual Designer

Requirements: Blender 4.2 or later

Method 1: Blender Extensions (Recommended)

1. Open Blender → Edit › Preferences › Get Extensions
2. Search for "LinkForge"
3. Click Install

Method 2: Split-Platform ZIP (Current Stable)

1. Download the .zip for your specific platform (e.g., linkforge-blender-x.x.x-macos_arm64.zip) from Latest Releases (opens in a new tab).
2. Open Blender → Edit › Preferences › Extensions.
3. Click the arrow icon (⌄) in the top right → Install from Disk.
4. Select the downloaded .zip file and click Install.
5. Enable the extension in the list.

Method 3: Development Mode (For Contributors)

git clone https://github.com/arounamounchili/linkforge.git
cd linkforge
just install
just develop  # Links workspace into Blender for live development

Using the Blender Visual Designer

Creating a Robot from Scratch

1. Create Links: Select a mesh → Forge panel → Create Link. Configure mass, inertia, and collision geometry in the Physics section.
2. Connect with Joints: Select child link → Forge panel → Create Joint. Set type, limits, axis, and dynamics.
3. Add Sensors (Optional): Select a link → Perceive panel → Add Sensor.
4. Configure Control (Optional): Go to Control panel → Enable Use ROS2 Control → configure command/state interfaces.
5. Validate & Export: Validate & Export panel → click Validate Robot → choose URDF or XACRO → click Export.

Importing Existing URDF

1. Open the LinkForge sidebar tab (N-panel in 3D Viewport).
2. In the Forge panel, click Import URDF/XACRO.
3. Select your file and edit the robot structure normally.
4. Export back via the Validate & Export panel.

Examples & Documentation

Example Files

Complete examples in the examples/ directory:

Programmatic tutorials in the documentation:

• Parametric Robotic Arm - Build a fully-jointed manipulator from mathematical definitions using RobotBuilder.
• Modular Differential Drive - Compose a chassis with automated wheel spacing, track calculations, and SRDF collision matrices.

Documentation Links

• User Guide (opens in a new tab) - Comprehensive tutorials and getting started.
• API Reference (opens in a new tab) - Technical reference for the linkforge-core library.
• Architecture Guide (opens in a new tab) - System design, Hexagonal Core, and data flow.
• CHANGELOG (opens in a new tab) - Version history.

Roadmap

Phase 1: Professional Foundation (Current)

• v1.0 - v1.2: Core URDF/XACRO export, Sensors, ros2_control, and Hexagonal Architecture.
• v1.3.0: Performance & Control (Depsgraph evaluation, ROS 2 Control enhancements).
• v1.4.0: Headless core decoupling, Composer API, Namespaced Merging, and MoveIt 2 SRDF generation.
• v1.5.x: Multi-Geometry Management (Multiple Visuals/Collisions per link, UILists, Primitive Controls & Realtime Viewport Sync).
• v1.6.0: SRDF Configuration Panel (Expose MoveIt 2 planning logic directly in Blender UI).
• v1.7.0: LinkForge CLI & GitHub Actions (Headless verification and export in CI pipelines).

Phase 2: Multi-Physics Interoperability (Upcoming v2.x)

• v2.0.0: The .lf Intermediate Representation (IR) (Typed JSON/YAML schema, lossless URDF bidirectional migration, Blender support).
• v2.x Target: Native MuJoCo / MJCF compilation (Kinematics, actuators, sites, and contact dynamics).
• v2.x Target: Native NVIDIA Isaac Sim / OpenUSD target (Zero-dependency ASCII USDA with UsdPhysics and PhysxSchema).

Development

# 1. Install 'just' command runner (see Contributing Guide for OS-specific instructions)
# 2. Clone repository
git clone https://github.com/arounamounchili/linkforge.git
cd linkforge

# 3. Install dependencies and setup venv
just install

# 4. Link to Blender for live development
just develop

For complete instructions on testing, linting, and building, see our Contributing Guide (opens in a new tab).

Contributing

We welcome contributions! LinkForge is a community-driven project.

• Review our Contributing Guide (opens in a new tab).
• Check our Architecture (opens in a new tab) to understand the internals.
• Join the conversation on GitHub Discussions (opens in a new tab).

Citing LinkForge

If you use LinkForge in academic research, please cite it using the provided CITATION.cff file. You can find the citation format in the "Cite this repository" button on GitHub's sidebar.

License

LinkForge is an open-source project using:

• linkforge-core: Apache License 2.0 (opens in a new tab) - Permissive license for maximum flexibility in research, personal, and commercial projects.
• platforms/blender: GNU General Public License v3.0 (opens in a new tab) - Standard for the Blender ecosystem, ensuring the add-on remains free and open-source.

For third-party component licenses, see THIRD-PARTY-NOTICES.md (opens in a new tab).

Our Contributors

Thanks goes to these wonderful people (emoji key (opens in a new tab)):

This project follows the all-contributors (opens in a new tab) specification. Contributions of any kind welcome!

Precision engineering meets creative modeling.