# gkjohnson/urdf-loaders architecture

> Architecture diagram of the GitHub repository gkjohnson/urdf-loaders, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gkjohnson/urdf-loaders
- Repository: https://github.com/gkjohnson/urdf-loaders

## Overview

##### Project type and purpose
- This is an open-source URDF (Universal Robot Description Format) loader library that provides two parallel implementations:
- A C# plugin for Unity (under the unity/Assets/URDFLoader folder)
- A JavaScript/TypeScript module for THREE.js (under the javascript folder)
- It ships with example URDF robot models and demo scenes for both environments.

##### File structure
- Top-level directories:
- javascript/ – Source code, build scripts, tests, and demo pages for the web loader
- unity/ – Unity package containing C# loader code, editor extensions, example scenes and materials
- urdf/ – Repository of URDF files and associated STL meshes (ATHLETE models)
- Configuration and CI:
- .github/workflows – CI for code scanning, builds, tests
- Various linting, Babel, Rollup, Jest config under javascript

##### README insights
- Purpose: “URDF loading code in both C# for Unity and JavaScript for THREE.js”
- Provides live demo link and license details

##### Main components & interactions
A. URDF Model Assets
- .URDF files (robot descriptions)
- .STL meshes (geometry for each link)
B. Parsing Layer
- C# URDFLoader.cs + ColladaLite.cs / DAELoader.cs / StlLoader.cs (Unity)
- JavaScript URDFLoader.js + URDFClasses.js (parsing, in JS or TS)
C. Data Model
- In-memory representation of joints, links, visuals, collisions
D. Rendering Layer
- Unity: GameObjects with MeshFilters/MeshRenderers + Editor tool (URDFRobotEditor)
- Web: Three.js scene graph + custom Web Components (urdf-viewer-element, urdf-manipulator-element)
E. Build & Test (JavaScript only)
- Babel → Rollup → UMD / ES module outputs
- Jest unit tests (URDFLoader.test.js, URDFRobot.test.js)
F. Example Apps
- Unity example scenes (LoadRobot.cs, plane material, etc.)
- Web example pages (simple.html, vr.html, bundled index.bundle.html)

##### Relationships & data flows
1. Developer drops URDF + mesh assets → Parser loads and validates URDF structure
2. Parser hands off to data model classes → constructs joint/link hierarchy
3. Renderer layer consumes data model → constructs visual scene
4. In Unity: Editor script provides Inspector GUI + runtime loader
5. In JS: Web Components wrap Three.js viewer and interactivity (drag-and-drop, VR support)
6. CI pipeline lints code, runs unit tests, and builds bundles for publishing

##### Architectural patterns & design principles
- Separation of concerns: parsing, data modeling, rendering
- Plugin architecture: editor extension vs runtime loader in Unity
- Modular JS design: ES modules, Web Components for extensibility
- Shared asset library (URDF + meshes) reused across both implementations

##### Element recommendations
- Blue for core libraries (Parser, Data Model)
- Green for rendering layers (Three.js, Unity)
- Yellow for examples/demos
- Grey for assets/data

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Shared Assets
    subgraph "Shared Assets"
        direction TB
        URDFAssets["URDF Model Assets"]:::assets
    end

    %% JavaScript Lane
    subgraph "JavaScript Implementation" 
        direction TB
        ParserJS["URDFLoader.js (Parser)"]:::core
        DataModelJS["URDFClasses.js (Data Model)"]:::core
        WebComponents["Web Components"]:::render
        SimpleViewer["urdf-viewer-element.js"]:::render
        Manipulator["urdf-manipulator-element.js"]:::render
    end

    %% JavaScript Build & Test
    subgraph "JS Build & Test Pipeline" 
        direction TB
        Babel["babel.config.json"]:::tool
        Rollup["rollup.config.js"]:::tool
        JestCfg["jest.config.js"]:::tool
        Tests["Unit Tests"]:::test
        DemoPages["JS Demo Pages"]:::example
    end

    %% Unity Lane
    subgraph "Unity Implementation"
        direction TB
        ParserCS["URDFLoader.cs + ColladaLite.cs + DAELoader.cs + StlLoader.cs"]:::core
        DataModelCS["URDFRobot.cs (Data Model)"]:::core
        EditorExt["URDFRobotEditor.cs (Editor)"]:::render
    end

    %% Unity Examples
    subgraph "Unity Example Apps"
        direction TB
        LoadRobot["LoadRobot.cs"]:::example
        LoadWeb["LoadWebRobot.cs"]:::example
        Scenes["Unity Scenes & Materials"]:::example
    end

    %% CI Workflows
    subgraph "CI Workflows"
        direction TB
        NodeCI["node.js.yml"]:::ci
        ExamplesCI["examples-build.yml"]:::ci
        CodeQL["codeql.yml"]:::ci
    end

    %% Relationships
    URDFAssets -->|provide URDF & STL| ParserJS
    URDFAssets -->|provide URDF & STL| ParserCS

    ParserJS -->|parse| DataModelJS
    DataModelJS -->|instantiate| WebComponents

    WebComponents -->|use| SimpleViewer
    WebComponents -->|use| Manipulator

    ParserCS -->|parse| DataModelCS
    DataModelCS -->|instantiate| EditorExt

    EditorExt -->|attach to| DataModelCS

    DemoPages -->|demo apps load| ParserJS
    SimpleViewer -->|render scene| DemoPages

    LoadRobot -->|loads via| ParserCS
    LoadWeb -->|loads via| ParserCS
    Scenes -->|render assets| LoadRobot

    %% Build & Test Pipeline Connections
    ParserJS --> Babel --> Rollup --> DemoPages
    Rollup -->|bundle| DemoPages
    ParserJS --> JestCfg --> Tests

    %% CI Connections
    ParserJS --> NodeCI
    LoadRobot --> ExamplesCI
    ParserCS --> CodeQL

    %% Click Events
    click URDFAssets "https://github.com/gkjohnson/urdf-loaders/tree/master/urdf/"
    click ParserJS "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/src/URDFLoader.js"
    click DataModelJS "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/src/URDFClasses.js"
    click SimpleViewer "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/src/urdf-viewer-element.js"
    click Manipulator "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/src/urdf-manipulator-element.js"
    click Babel "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/babel.config.json"
    click Rollup "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/rollup.config.js"
    click JestCfg "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/jest.config.js"
    click Tests "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/test/URDFLoader.test.js"
    click Tests "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/test/URDFRobot.test.js"
    click Tests "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/test/URDFJoint.test.js"
    click DemoPages "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/example/simple.html"
    click DemoPages "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/example/vr.html"
    click DemoPages "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/example/index.html"
    click DemoPages "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/example/index.bundle.html"
    click DemoPages "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/example/src/simple.js"
    click DemoPages "https://github.com/gkjohnson/urdf-loaders/blob/master/javascript/example/src/vr.js"
    click ParserCS "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/URDFLoader/URDFLoader.cs"
    click ParserCS "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/URDFLoader/ColladaLite.cs"
    click ParserCS "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/URDFLoader/DAELoader.cs"
    click ParserCS "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/URDFLoader/StlLoader.cs"
    click DataModelCS "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/URDFLoader/URDFRobot.cs"
    click EditorExt "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/URDFLoader/Editor/URDFRobotEditor.cs"
    click LoadRobot "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/example/LoadRobot.cs"
    click LoadWeb "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/example/LoadWebRobot.cs"
    click Scenes "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/example/scene.unity"
    click Scenes "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/example/web scene.unity"
    click Scenes "https://github.com/gkjohnson/urdf-loaders/blob/master/unity/Assets/example/PlaneMaterial.mat"
    click NodeCI "https://github.com/gkjohnson/urdf-loaders/blob/master/.github/workflows/node.js.yml"
    click ExamplesCI "https://github.com/gkjohnson/urdf-loaders/blob/master/.github/workflows/examples-build.yml"
    click CodeQL "https://github.com/gkjohnson/urdf-loaders/blob/master/.github/workflows/codeql.yml"

    %% Styles
    classDef assets fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#9ec5fe,stroke:#333,stroke-width:1px
    classDef render fill:#b6e2d3,stroke:#333,stroke-width:1px
    classDef example fill:#ffe599,stroke:#333,stroke-width:1px
    classDef tool fill:#f4cccc,stroke:#333,stroke-width:1px
    classDef test fill:#d9d2e9,stroke:#333,stroke-width:1px
    classDef ci fill:#fce5cd,stroke:#333,stroke-width:1px
```
