You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+8-10Lines changed: 8 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@
14
14
15
15
LinkForge brings the **"LLVM architecture" to Robotics**. It utilizes a universal, mathematical Intermediate Representation (IR) for physical robots—paving the way for the upcoming **`.lf` standard**.
16
16
17
-
By treating robot descriptions as *Source Code* rather than compiled *Executables*, LinkForge bridges the gap between CAD, Simulation, and AI training with zero data loss. Currently featuring a native **Blender integration**, it acts as a strict safety net to guarantee your robot is rigorous, physics-compliant, and simulation-ready.
17
+
By treating robot descriptions as **"Source Code"** rather than compiled **"Executables"**, LinkForge bridges the gap between CAD, Simulation, and AI training with zero data loss. Currently featuring a native **Blender integration**, it acts as a strict safety net to guarantee your robot is rigorous, physics-compliant, and simulation-ready.
Copy file name to clipboardExpand all lines: VISION.md
+20-18Lines changed: 20 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,25 +15,28 @@ To build the **LLVM for Robotics**. We are eliminating the fundamental gap betwe
15
15
16
16
## 🌉 The Universal Robotics Bridge
17
17
18
-
There is a fundamental "impedance mismatch" in the modern robotics workflow. LinkForge exists to eliminate it.
18
+
There is a fundamental "impedance mismatch" in the modern robotics workflow. LinkForge exists to eliminate it by redefining how we treat robot descriptions.
19
19
20
20
### The Problem: "Executables" vs. "Source Code"
21
21
Currently, the robotics ecosystem treats formats like URDF, SDF, and MJCF as the source of truth. However, these are actually **"Executables"**—lossy, environment-specific snapshots compiled from opaque CAD tools.
22
-
When a design is exported, critical metadata (author intent, precise materials, motor curves) is lost. Furthermore, this is a one-way street: true "Round-Trip Engineering" (editing a simulation model and syncing it back to CAD) is nearly impossible.
22
+
23
+
When you export a robot to URDF, you are "compiling" it. If you manually fix a joint limit in the XML, you cannot easily "decompile" that change back into your CAD model. Your design intent is lost in a one-way, destructive pipeline.
23
24
24
25
### The Solution: The `.lf` Standard
25
-
LinkForge introduces the `.lf` file format—the **"Source Code"** for robotics. It acts as the high-fidelity translator ensuring your design intent is mathematically preserved across the entire development lifecycle:
26
+
LinkForge introduces the `.lf` file format—the **"Source Code"** for robotics.
27
+
***The Git for Robotics**: Just as Git tracks code changes, LinkForge tracks the physical intent of your robot.
28
+
***Unified Truth**: The `.lf` format acts as a high-fidelity translator ensuring your design intent is mathematically preserved across the entire development lifecycle:
26
29
27
-
**Design Systems** (Blender, FreeCAD, OnShape) ➜ **LinkForge Core (`.lf`)** ➜ **Simulation & Production** (ROS 2, MuJoCo, Isaac Sim, Real Hardware)
We believe a simulator should never be "close enough." It should be identical. Our North Star is the perfect **Digital Twin**:
34
-
***True Round-Trip Engineering**: Import legacy models, validate them, edit them visually, and deploy them anywhere without data destruction.
35
-
***Automated Linting**: Catch mechanical conflicts and kinematic errors *during* the design phase—reducing simulation failures and hardware rework.
36
-
***Numerical Integrity**: Every mass calculation and inertia tensor is scientifically grounded, guaranteed by a core that enforces double-precision physics over approximations.
37
+
***True Round-Trip Engineering**: Import legacy models, validate them, edit them visually, and redeploy them anywhere without data destruction.
38
+
***Physics as Truth**: Every mass calculation and inertia tensor is scientifically grounded. If the physics are wrong, the Linter catches it *during* the design phase—long before it hits hardware.
39
+
***Numerical Integrity**: We enforce double-precision physics over approximations, ensuring that your robot behaves the same way in MuJoCo as it does in the real world.
37
40
38
41
---
39
42
@@ -45,36 +48,35 @@ Why LinkForge is the infrastructure for the next generation of robotics:
45
48
| :--- | :--- | :--- |
46
49
|**Architecture**| Monolithic / Tied to one CAD tool |**Hexagonal / Multi-Host & Multi-Target**|
47
50
|**Format**| XML-based, Lossy, Fragmented |**JSON/YAML `.lf` Standard (Metadata-Rich)**|
48
-
|**Validation**| Post-Export (Fail in Sim) |**Automated Linting (Fail in Editor via LSP)**|
51
+
|**Validation**| Post-Export (Fail in Sim) |**Automated Linting (Fail in Editor)**|
49
52
|**Physics**| "Close Enough" Mesh Export |**Scientific Inertia & Mass Sanity**|
50
53
|**Asset Loading**| Fragile Local File Paths |**Cloud-Native `lf://` URI Resolution**|
51
54
52
55
---
53
56
54
57
## 🏗️ Technical Strategy: The Hexagonal Core
55
58
56
-
LinkForge is engineered for the future. By utilizing a **Hexagonal Architecture (Ports & Adapters)**, we remain framework-independent:
57
-
***Decoupled Intelligence**: Our "Robotics Brain" (`linkforge_core`) is completely isolated from specific UI hosts or simulation engines.
58
-
***Model Once, Deploy Anywhere**: Write your robot once in `.lf`, and swappable adapters will generate the exact MJCF, URDF, or SDF needed for your specific runtime.
59
-
***Scalable Adaptation**: As new tools and engines emerge, LinkForge is ready to bridge them without rewriting the fundamental physics core.
59
+
LinkForge is the **"LLVM for Robotics."** By utilizing a **Hexagonal Architecture**, we remain framework-independent:
60
+
***Decoupled Intelligence**: Our "Robotics Brain" (`linkforge_core`) is isolated from specific UI hosts or simulation engines.
61
+
***Model Once, Deploy Anywhere**: Write your robot once in `.lf`, and swappable adapters generate the exact MJCF, URDF, or SDF needed for your specific runtime.
60
62
61
63
---
62
64
63
65
## 🚀 Future Horizons
64
66
65
67
We are building the infrastructure for the next generation of autonomy:
66
-
***🛡️ Kinematic Intelligence**: Built-in solvers to validate workspace reachability and mechanical interference inside the visual editor.
67
-
***🧠 Intelligence-Driven Rigging**: Graph Neural Networks (GNNs) that leverage geometric analysis to automate joint and sensor placement based on mesh topology.
68
-
***📦 The LinkForge Package Manager (LPM)**: A global, decentralized registry for verified robot parts.
69
-
***🌊 High-Fidelity Noise Injection**: Modeling real-world sensor imperfections (drift, jitter, bias) directly in the IR to close the Sim-to-Real gap.
68
+
***🛡️ Kinematic Intelligence**: Built-in solvers to validate workspace reachability inside the visual editor.
69
+
***🧠 Intelligence-Driven Rigging**: Graph Neural Networks (GNNs) that automate joint placement based on mesh topology.
70
+
***📦 The LinkForge Package Manager (LPM)**: A decentralized registry for verified robot components.
71
+
***🌊 High-Fidelity Noise Injection**: Modeling real-world sensor imperfections directly in the IR to close the Sim-to-Real gap.
70
72
71
73
---
72
74
73
75
## 🗺️ Vision 2030: The Universal Connector
74
76
75
-
By 2030, the "monolithic robot" will be a thing of the past. We believe the robotics industry will evolve into a modular ecosystem where specialized companies build world-class components—legs, torsos, manipulators—that just work together.
77
+
By 2030, the "monolithic robot" will be a thing of the past. We believe the robotics industry will evolve into a modular ecosystem where specialized components—legs, torsos, manipulators—just work together.
76
78
77
-
**LinkForge is the "USB Port" for this future.** By providing the universal Intermediate Representation (IR), we enable a global supply chain where any "LinkForge Certified" part can be plugged into any assembly with zero friction. We are building the economic infrastructure for the physical world.
79
+
**LinkForge is the "USB Port" for this future.** By providing a universal Intermediate Representation (IR), we enable a global ecosystem where any **standard-compliant**part can be integrated into any assembly with zero friction. We are building the **foundational infrastructure** for the physical world.
One of the core architectural inspirations for LinkForge is the **LLVM Compiler Infrastructure**. This document explains why we use this analogy and how it maps to the physical world of robotics.
4
+
5
+
---
6
+
7
+
## 1. The Analogy: Software vs. Hardware
8
+
9
+
In software development, compilers like Clang/LLVM solved the "M-by-N" problem (M languages, N hardware architectures). Instead of writing a unique compiler for every pair, they created an **Intermediate Representation (IR)**.
In traditional robotics, a URDF is an **Executable**. It is a lossy, "compiled" snapshot of a design. If you need to change a motor's mass, you edit the XML directly, but that change never "decompiles" back into your original CAD source.
24
+
25
+
By treating the `.lf` IR as **Source Code**, LinkForge enables:
26
+
1.**Bidirectional Sync**: Changes in the "Executable" (Simulator) can be merged back into the "Source" (CAD).
27
+
2.**Linting**: Just as a compiler catches syntax errors, LinkForge catches **Kinematic and Physical Errors** (e.g., disconnected chains, negative inertia) before they reach the simulator.
28
+
3.**Optimization**: The LinkForge "Middle-End" can simplify complex meshes or optimize mass distributions automatically while preserving the IR's integrity.
29
+
30
+
---
31
+
32
+
## 3. Intermediate Optimization
33
+
34
+
Just as LLVM has "Optimization Passes," the LinkForge Middle-End performs intelligent operations on the robot IR to ensure it is simulation-ready.
35
+
36
+
### Current "Passes" [Live]
37
+
***Physical Integrity Pass**: Validates inertia tensors against the triangle inequality to prevent "unphysical" simulation behavior.
38
+
***Namespacing Pass**: Automatically prefixes link and joint names during assembly to prevent kinematic collisions.
39
+
***Semantic Synthesis**: Combines disparate sub-robots into a single, unified kinematic graph with verified root links.
***Decoupled Intelligence**: The core logic (`linkforge_core`) is isolated from specific UI hosts or simulation engines.
47
+
***Swappable Adapters**: To support a new simulator (like a new backend in LLVM), we only need to write a single adapter that translates LinkForge IR to the target format.
48
+
49
+
---
50
+
51
+
## 5. Summary
52
+
53
+
LinkForge isn't just an exporter; it is a **Transformation Engine**. We are building the infrastructure that allows roboticists to stop "hand-crafting binaries" and start "engineering with source code."
54
+
55
+
---
56
+
57
+
> [!IMPORTANT]
58
+
> **LinkForge** is built for the era of Embodied AI, where high-fidelity simulation is the only way to scale.
# The `.lf` Standard: Robotics Intermediate Representation (IR)
2
+
3
+
**Version**: 1.1
4
+
**Status**: Specification Draft
5
+
**Target Runtimes**: ROS 2, MuJoCo, Gazebo, Isaac Sim
6
+
7
+
---
8
+
9
+
## 1. Overview
10
+
The `.lf` (LinkForge) format is the "Source Code" for robotics. It is a high-fidelity, metadata-rich Intermediate Representation (IR) designed to bridge the gap between CAD tools and simulation engines without data loss.
11
+
12
+
### Design Principles
13
+
1.**Physics is Truth**: Every inertial property must be physically plausible (validated via the triangle inequality).
14
+
2.**Lossless Round-Trips**: All data required for simulation must be syncable back to the visual modeling environment.
15
+
3.**Modular Assembly**: Support for referencing external components via `lf://` URIs.
16
+
17
+
---
18
+
19
+
## 2. File Structure
20
+
The `.lf` standard uses **JSON** or **YAML** as its primary exchange format.
21
+
22
+
### 2.1 Top-Level Schema
23
+
```json
24
+
{
25
+
"format_version": "1.1",
26
+
"units": {
27
+
"length": "meters",
28
+
"mass": "kg",
29
+
"angle": "radians",
30
+
"time": "seconds"
31
+
},
32
+
"metadata": {
33
+
"name": "string",
34
+
"author": "string",
35
+
"license": "string",
36
+
"version": "semver"
37
+
},
38
+
"kinematics": "KinematicsObject",
39
+
"perception": "PerceptionObject",
40
+
"control": "ControlObject",
41
+
"sim_specific": "SimulationObject"
42
+
}
43
+
```
44
+
45
+
---
46
+
47
+
## 3. Core Components
48
+
49
+
### 3.1 Kinematics (Links & Joints)
50
+
Links represent rigid bodies, and Joints represent the kinematic constraints between them.
Assets (meshes, materials) should be referenced using cloud-resolvable URIs.
68
+
*`lf://local/parts/wheel.glb`: Resolve from the local project workspace.
69
+
*`lf://registry/sensors/lidar_v3.lf`: Resolve from a global or private registry.
70
+
71
+
### 3.3 Actuator Curves (AI-Ready)
72
+
To support high-fidelity Reinforcement Learning, `.lf` supports torque/effort curves rather than just static limits.
73
+
```json
74
+
"actuator": {
75
+
"type": "dc_motor",
76
+
"torque_curve": [
77
+
{"rpm": 0, "torque": 5.0},
78
+
{"rpm": 1000, "torque": 4.5}
79
+
]
80
+
}
81
+
```
82
+
83
+
---
84
+
85
+
## 4. Namespacing & Modular Assembly
86
+
When merging robots (e.g., attaching an arm to a torso), LinkForge uses **Prefix Namespacing** to avoid collisions.
87
+
* Sub-robot `arm` link `hand` becomes `arm_hand` in the final IR.
88
+
89
+
---
90
+
91
+
## 5. Future: Binary IR
92
+
For high-performance loading in large-scale simulation environments (e.g., thousands of robots in Isaac Sim), LinkForge will introduce a **Binary IR** based on **Protocol Buffers (protobuf)**. This will serve as the "Object File" (`.lfo`) to the `.lf` "Source Code."
93
+
94
+
---
95
+
96
+
> [!TIP]
97
+
> For implementation details, see the `linkforge_core.models` Python module in the source code.
0 commit comments