# shubhankarmondal/four-ur5e-cooperative-transport architecture

> Architecture diagram of the GitHub repository shubhankarmondal/four-ur5e-cooperative-transport, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubhankarmondal/four-ur5e-cooperative-transport
- Repository: https://github.com/shubhankarmondal/four-ur5e-cooperative-transport

## Overview

This repository is a MuJoCo simulation and demonstration of four UR5e arms cooperatively transporting a plate through contact grasps. The user-facing workflow builds or loads the scene, initializes grasp configurations, follows a payload trajectory under closed-loop control, and optionally records and renders the run. The graph includes documented validation and scene-building capabilities. Runtime call evidence is limited to the shown excerpts and SOURCE INDEX references; unsampled internal links are omitted where not established.

Main entry points: [`scripts/demo.py`](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/demo.py) (Interactive Demo), [`scripts/run_demo.py`](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/run_demo.py) (Run and Record), [`scripts/render.py`](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/render.py) (Video Demo), [`src/homtrans/controller.py`](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/controller.py) (Cooperative Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_modeling["Scene and Models"]
  node_scene["MuJoCo Scene<br/>[scene.py]"]
  node_robot_assets["Robot Assets"]
  node_scene_model["Transport Model"]
  node_scene_builder["Scene Builder<br/>[build_scene.py]"]
end

subgraph group_planning["Motion and Grasp"]
  node_trajectory["Payload Trajectory<br/>[trajectory.py]"]
  node_kinematics["Grasp IK<br/>[kinematics.py]"]
end

subgraph group_runtime["Control and Simulation"]
  node_controller["Cooperative Controller<br/>[controller.py]"]
  node_allocation["Wrench Allocation<br/>[allocation.py]"]
  node_simulation["Simulation Loop<br/>[simulation.py]"]
end

subgraph group_presentation["Demo and Rendering"]
  node_demo["Interactive Demo<br/>[demo.py]"]
  node_run_demo["Run and Record<br/>[run_demo.py]"]
  node_render_cli["Video Demo<br/>[render.py]"]
  node_renderer["Recording and Renderer<br/>[render.py]"]
end

subgraph group_quality["Validation"]
  node_validate["Validation Suite<br/>[validate.py]"]
end

node_user(("User"))
node_viewer["MuJoCo Viewer"]
node_video["Rendered Video"]

node_user -->|"starts demo"| node_demo
node_user -->|"runs transport"| node_run_demo
node_user -->|"renders demo"| node_render_cli
node_user -->|"validates run"| node_validate
node_scene_builder -->|"builds from"| node_scene
node_scene -->|"uses models"| node_robot_assets
node_scene -->|"defines model"| node_scene_model
node_demo -->|"loads model"| node_scene_model
node_demo -->|"creates reference"| node_trajectory
node_demo -->|"creates controller"| node_controller
node_demo -->|"initializes arms"| node_kinematics
node_demo -.->|"runs headless"| node_simulation
node_demo -->|"steps interactively"| node_viewer
node_run_demo -->|"loads model"| node_scene_model
node_run_demo -->|"creates reference"| node_trajectory
node_run_demo -->|"creates controller"| node_controller
node_run_demo -->|"initializes arms"| node_kinematics
node_run_demo -->|"runs simulation"| node_simulation
node_run_demo -->|"records frames"| node_renderer
node_render_cli -->|"loads model"| node_scene_model
node_render_cli -->|"creates reference"| node_trajectory
node_render_cli -->|"creates controller"| node_controller
node_render_cli -->|"initializes arms"| node_kinematics
node_render_cli -->|"runs simulation"| node_simulation
node_render_cli -->|"renders recording"| node_renderer
node_simulation -->|"computes commands"| node_controller
node_simulation -->|"tracks reference"| node_trajectory
node_controller -->|"allocates wrench"| node_allocation
node_controller -->|"samples reference"| node_trajectory
node_renderer -->|"writes video"| node_video
node_validate -->|"checks behavior"| node_controller
node_validate -->|"checks workspace"| node_kinematics
node_validate -->|"checks motion"| node_trajectory
node_validate -->|"checks correspondence"| node_video

click node_scene "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/scene.py"
click node_robot_assets "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/tree/main/assets"
click node_scene_model "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/models/four_ur5e_transport.xml"
click node_scene_builder "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/build_scene.py"
click node_trajectory "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/trajectory.py"
click node_kinematics "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/kinematics.py"
click node_controller "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/controller.py"
click node_allocation "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/allocation.py"
click node_simulation "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/simulation.py"
click node_demo "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/demo.py"
click node_run_demo "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/run_demo.py"
click node_render_cli "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/render.py"
click node_renderer "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/render.py"
click node_validate "https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/validate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scene,node_robot_assets,node_scene_model,node_scene_builder,node_user,node_viewer toneBlue
class node_trajectory,node_kinematics toneAmber
class node_controller,node_allocation,node_simulation toneMint
class node_demo,node_run_demo,node_render_cli,node_renderer toneRose
class node_validate,node_video toneIndigo
```

## Components

### Scene and Models

- [MuJoCo Scene](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/scene.py): `src/homtrans/scene.py`
- [Robot Assets](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/tree/main/assets): `assets`
- [Transport Model](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/models/four_ur5e_transport.xml): `models/four_ur5e_transport.xml`
- [Scene Builder](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/build_scene.py): `scripts/build_scene.py`

### Motion and Grasp

- [Payload Trajectory](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/trajectory.py): `src/homtrans/trajectory.py`
- [Grasp IK](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/kinematics.py): `src/homtrans/kinematics.py`

### Control and Simulation

- [Cooperative Controller](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/controller.py): `src/homtrans/controller.py`
- [Wrench Allocation](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/allocation.py): `src/homtrans/allocation.py`
- [Simulation Loop](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/simulation.py): `src/homtrans/simulation.py`

### Demo and Rendering

- [Interactive Demo](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/demo.py): `scripts/demo.py`
- [Run and Record](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/run_demo.py): `scripts/run_demo.py`
- [Video Demo](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/render.py): `scripts/render.py`
- [Recording and Renderer](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/src/homtrans/render.py): `src/homtrans/render.py`

### Validation

- [Validation Suite](https://github.com/shubhankarmondal/four-ur5e-cooperative-transport/blob/main/scripts/validate.py): `scripts/validate.py`

### Other components

- **User**
- **MuJoCo Viewer**
- **Rendered Video**

## Connections

- User → Interactive Demo: starts demo (evidence: `README.md`)
- User → Run and Record: runs transport (evidence: `README.md`)
- User → Video Demo: renders demo (evidence: `README.md`)
- User → Validation Suite: validates run (evidence: `README.md`)
- Scene Builder → MuJoCo Scene: builds from (evidence: `scripts/build_scene.py`)
- MuJoCo Scene → Robot Assets: uses models (evidence: `README.md`)
- MuJoCo Scene → Transport Model: defines model (evidence: `README.md`)
- Interactive Demo → Transport Model: loads model (evidence: `scripts/demo.py`)
- Interactive Demo → Payload Trajectory: creates reference (evidence: `scripts/demo.py`)
- Interactive Demo → Cooperative Controller: creates controller (evidence: `scripts/demo.py`)
- Interactive Demo → Grasp IK: initializes arms (evidence: `scripts/demo.py`)
- Interactive Demo → Simulation Loop: runs headless (evidence: `scripts/demo.py`)
- Interactive Demo → MuJoCo Viewer: steps interactively (evidence: `scripts/demo.py`)
- Run and Record → Transport Model: loads model (evidence: `scripts/run_demo.py`)
- Run and Record → Payload Trajectory: creates reference (evidence: `scripts/run_demo.py`)
- Run and Record → Cooperative Controller: creates controller (evidence: `scripts/run_demo.py`)
- Run and Record → Grasp IK: initializes arms (evidence: `scripts/run_demo.py`)
- Run and Record → Simulation Loop: runs simulation (evidence: `scripts/run_demo.py`)
- Run and Record → Recording and Renderer: records frames (evidence: `scripts/run_demo.py`)
- Video Demo → Transport Model: loads model (evidence: `scripts/render.py`)
- Video Demo → Payload Trajectory: creates reference (evidence: `scripts/render.py`)
- Video Demo → Cooperative Controller: creates controller (evidence: `scripts/render.py`)
- Video Demo → Grasp IK: initializes arms (evidence: `scripts/render.py`)
- Video Demo → Simulation Loop: runs simulation (evidence: `scripts/render.py`)
- Video Demo → Recording and Renderer: renders recording (evidence: `scripts/render.py`)
- Simulation Loop → Cooperative Controller: computes commands (evidence: `README.md`)
- Simulation Loop → Payload Trajectory: tracks reference (evidence: `README.md`)
- Cooperative Controller → Wrench Allocation: allocates wrench (evidence: `src/homtrans/controller.py`)
- Cooperative Controller → Payload Trajectory: samples reference (evidence: `src/homtrans/controller.py`)
- Recording and Renderer → Rendered Video: writes video (evidence: `README.md`)
- Validation Suite → Cooperative Controller: checks behavior (evidence: `scripts/validate.py`)
- Validation Suite → Grasp IK: checks workspace (evidence: `scripts/validate.py`)
- Validation Suite → Payload Trajectory: checks motion (evidence: `scripts/validate.py`)
- Validation Suite → Rendered Video: checks correspondence (evidence: `scripts/validate.py`)
