LinkForge

The Linter & Bridge for Robotics

LinkForge is The Linter & Bridge for Robotics.

In robotics, creativity starts in your head — but getting that idea into a simulator usually means hours of writing XML, fixing joint limits, and fighting coordinate systems.

LinkForge removes that friction. It acts as both a Linter and a Bridge, allowing you to model your robot in Blender as naturally as sculpting a 3D scene, while guaranteeing the output is rigorous, simulation-ready code.

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

From idea → hardened robot model → ready for simulation. All inside Blender.

🛠️ Technical Specifications

Feature	Support	Details
Links	✅ Full	Visual/Collision Geometry, Materials, Automatic Physics
Joints	✅ Full	All 6 types (Fixed, Revolute, etc.) + Mimic Joints
Sensors	✅ Full	Camera, LiDAR, IMU, GPS, Contact, Force/Torque
Control	✅ Full	ros2_control Dashboard & Gazebo Plugin Integration
Validation	✅ Pro	Linter for Robotics catches structural errors before export
Fidelity	✅ Pro	Round-Trip Precision for lossless Import/Export
Formats	✅ Full	URDF 1.0, XACRO (Macros, Properties, Multi-file)

🚀 Key Features

• Bidirectional Workflow: Seamlessly import existing URDF/XACRO files for editing or build complex robot models from scratch using Blender's 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 (The Safety Net): Built-in integrity checker inspects robot topology, physics data, and joint limits. It catches "exploding robot" 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)

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

Method 2: Manual Installation

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

🎯 Quick Start

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.
   • Repeat for all robot parts.

2. 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.

3. Add Sensors (Optional)

   • Select a link → Perceive panel → Add Sensor
   • Configure sensor properties in the Sensor section.

4. 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).

5. 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

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

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

• v1.0.0: Core URDF/XACRO Export, Sensors, & ros2_control basics.
• v1.1.0: Enhanced Documentation, Workflow Polish, & Bug Fixes.
• v1.2.0: Architectural Stability (Hexagonal Core, Numerical Precision).
• v1.3.0: High-Fidelity Expansion (MJCF/MuJoCo & SDF/Gazebo support).
• v1.4.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.

---

🔮 Our Transparency Commitment

We believe in being upfront about what LinkForge does—and what it doesn't do.

1. Standard Compliance: We guarantee 100% compliance with the official URDF/XACRO specifications. Your robot will work in any standard parser.
2. The "Wild URDF" Limit: We aim for lossless Round-Trip (Import → Edit → Export). However, if you import a "Wild" URDF containing non-standard tags, custom XML comments, or parser-specific hacks, we do not guarantee their preservation. We clean the code to ensure validity.
3. Beta Features: Advanced features like ros2_control are evolving. We commit to vigilance in updating them, but syntax changes in ROS 2 may require extension updates.

🤝 Contributing

We welcome contributions! LinkForge is an 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):

arounamounchili 💻 🎨 🤔 🚧

MagnusHanses 🐛

GeKo-8 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

Made with ❤️ for roboticists worldwide
Precision engineering meets creative modeling.