LinkForge

The Linter & Bridge for Robotics

LinkForge is The Linter & Bridge for Robotics, integrating directly into Blender.

It allows you to model your robot as naturally as sculpting a 3D scene, while acting as a strict safety net to guarantee the output is rigorous, simulation-ready code.

Forge Structure: Define links, joints, masses, and inertias visually.
Lint & Validate: Catch structural and physics errors before simulation export.
Perceive & Control: Attach sensors and configure ros2_control interfaces.
Export Production Code: Generate hardened URDF/XACRO files.

💎 Why LinkForge?

🛠️ Technical Specifications

🚀 Key Features

Bidirectional Workflow: Import existing URDF/XACRO files for editing or build complex robot models from scratch using Blender native tools.
Production-Ready Export: Generates strictly compliant URDF/XACRO files optimized for ROS, ROS 2, and Gazebo. Includes ROS-Agnostic Asset Resolution, allowing complex robots to be imported and edited on any platform without requiring a ROS installation.
Linter for Robotics: Built-in integrity checker inspects robot topology, physics data, and joint limits. It catches simulation-breaking errors (negative inertias, detached links, circular chains) before you export.
ROS2 Control Support: Automatically generates hardware interface configurations for ros2_control via a centralized dashboard, compatible with Gazebo and physical hardware.
Complete Sensor Suite: Integrated support for Camera, Depth Camera, LiDAR, IMU, GPS, Force/Torque, and Contact sensors with configurable noise models.
Automatic Physics: Scientifically accurate calculation of mass properties and inertia tensors for both primitive shapes and complex arbitrary meshes.
Advanced XACRO Support: Intelligent extraction of repeated geometry into macros and shared materials, producing maintainable and modular code.
Round-Trip Fidelity: The Import → Edit → Export cycle preserves all data with absolute precision, including sensor origins, transmission interfaces, and custom user properties.

📦 Installation

Requirements: Blender 4.2 or later

Method 1: Blender Extensions (Recommended)

Open Blender → Edit > Preferences > Get Extensions
Search for "LinkForge"
Click Install

Method 2: Manual Installation

Download the .zip package for your platform (e.g., linkforge-x.x.x-windows-x64.zip) from Latest Releases
Open Blender → Edit > Preferences > Get Extensions
Click dropdown (⌄) → Install from Disk
Select the downloaded .zip file

🎯 Quick Start

Creating a Robot from Scratch

Create Links
- Select a mesh → Forge panel → Create Link
- Configure mass, inertia, and collision geometry in the Physics section.
- Repeat for all robot parts.
Connect with Joints
- Select child link → Forge panel → Create Joint
- Choose joint type (Revolute, Prismatic, Continuous, Fixed, etc.)
- Set limits, axis, and dynamics in the Joint section.
Add Sensors (Optional)
- Select a link → Perceive panel → Add Sensor
- Configure sensor properties in the Sensor section.
Configure Control (Optional)
- Go to the Control panel → Enable Use ROS2 Control
- Click + to add joints to the Joint Interfaces list.
- Configure Command/State interfaces (Position, Velocity, Effort).
Validate & Export
- Go to the Validate & Export panel.
- Click Validate Robot to check for integrity errors.
- Choose format (URDF/XACRO) and click Export.

Importing Existing URDF

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

🤖 Examples

Complete examples in examples/ directory:

roundtrip_test_robot.urdf: A comprehensive robot containing ALL 6 URDF joint types (fixed, revolute, continuous, prismatic, planar, floating), plus sensors. Perfect for testing full roundtrip capabilities.
mobile_robot.urdf: A simple mobile robot base.
diff_drive_robot.urdf: A differential drive robot with wheels.
quadruped_robot.urdf: A 4-legged robot demonstrating complex kinematic chains and multi-link assemblies.

📚 Documentation

User Guide - Comprehensive tutorials and getting started.
API Reference - Technical reference for developers.
Architecture Guide - System design and internals.
CHANGELOG - Version history.
Examples: examples/

💻 Development

Setup

# 1. Install 'just' (Command Runner)
brew install just

# 2. Clone repository
git clone https://github.com/arounamounchili/linkforge.git
cd linkforge

# 3. Install dependencies
just install

Testing

# Run all tests (Core + Blender)
just test

# Run only core tests
just test-core

# Run with coverage
just coverage

Code Quality

# Run all checks (Lint + Types)
just check

# Fix linting issues
just fix

Building & Distribution

To package LinkForge as a Blender extension:

# Build the production-ready .zip
just build

The package will be created in the dist/ directory.

🎓 Learning Resources

Example Files - Sample URDF files
Community Forum - Ask questions

🗺️ Roadmap

[x] v1.0.0: Core URDF/XACRO Export, Sensors, & ros2_control basics.
[x] v1.1.0: Enhanced Documentation, Workflow Polish, & Bug Fixes.
[x] v1.2.0: Architectural Stability (Hexagonal Core, Numerical Precision).
[x] v1.3.0: Performance & Control (NumPy Acceleration, Depsgraph, & ROS2 Control).
[ ] v1.4.0: Modular Assembly (SRDF, Composer API, linkforge_ros).
[ ] v1.5.0: High-Fidelity Expansion pt.1 (MJCF/MuJoCo support).
[ ] v1.6.0: High-Fidelity Expansion pt.2 (SDF/Gazebo support).
[ ] v1.7.0: Mechanical Debugging (Real-time IK & Collision Interference Validation).
[ ] v2.0.0: Intelligence-Driven Rigging (AI-assisted geometry analysis & Auto-Rigging).

🔭 Vision & Future

For a deep dive into our long-term strategy, the Digital Twin philosophy, and our technical roadmap for AI and Kinematics, please read our Project Vision.

🤝 Contributing

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

🙋 Review our Contributing Guide.
🏗️ Check our Architecture to understand the internals.
💬 Join the conversation on GitHub Discussions.

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details. For third-party component licenses, see THIRD-PARTY-NOTICES.md.

✨ Our Contributors

Thanks goes to these wonderful people (emoji key):

<table> <tbody> <tr> <td align="center" valign="top" width="14.28%"><a href="https://github.com/arounamounchili"><img src="https://avatars.githubusercontent.com/u/55673269?v=4?s=64" width="64px;" alt="arounamounchili"/><br /><sub

Linkforge

Install / Use

README