# men3m-4/openarm_sorting architecture

> Architecture diagram of the GitHub repository men3m-4/openarm_sorting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/men3m-4/openarm_sorting
- Repository: https://github.com/men3m-4/openarm_sorting

## Overview

OpenArm Cup Sorting is a ROS 2 simulation where an operator confirms a task, the RGB-D perception system localizes red and blue cubes, and a coordinator uses MoveIt and the left gripper to place them in one configured cup, verifying motion and placement. The graph also shows robot-description and launch support layers. Relationships for sampled modules are grounded in their excerpts or the source index; launch orchestration and several runtime links rely on the README’s documented architecture, since launch sources were not excerpted here.

Main entry points: [`src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py`](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py) (Sorting coordinator), [`src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py`](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py) (Cube detector), [`src/openarm_sorting_bringup/launch/cup_sorting.launch.py`](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/launch/cup_sorting.launch.py) (Cup sorting launch), [`src/openarm_sorting_description/openarm_sorting_description/robot_description.py`](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/openarm_sorting_description/robot_description.py) (Robot description)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bringup["Simulation and bringup"]
  node_launch["Cup sorting launch"]
  node_world["Gazebo world"]
  node_launch_helpers["Launch support<br/>[launch_support.py]"]
  node_rgbd_camera["Simulated RGB-D camera"]
  node_controller_config["Gazebo controllers"]
end

subgraph group_robot["Robot description"]
  node_robot_description["Robot description"]
  node_collision_patch["Finger collision patch"]
end

subgraph group_perception["Cube perception"]
  node_detector["Cube detector<br/>[cube_detector.py]"]
  node_segmentation["Color segmentation"]
  node_camera_geometry["Camera geometry<br/>[camera_geometry.py]"]
end

subgraph group_task["Task execution"]
  node_coordinator["Sorting coordinator<br/>[coordinator.py]"]
  node_prompt["Task confirmation<br/>[task_prompt.py]"]
end

subgraph group_planning["Motion and gripper"]
  node_planning_scene["Planning scene<br/>[planning_scene.py]"]
  node_moveit_interface["MoveIt client"]
  node_gripper["Left gripper client<br/>[gripper.py]"]
  node_ros_utils["ROS async helpers<br/>[ros_utils.py]"]
end

node_operator(("Operator"))
node_move_group["MoveIt move_group"]
node_gazebo_control["Gazebo control"]

node_operator -->|"starts"| node_launch
node_launch -->|"starts simulation"| node_world
node_launch -->|"starts perception"| node_detector
node_launch -->|"starts task"| node_coordinator
node_launch -->|"uses configuration"| node_launch_helpers
node_launch_helpers -->|"loads description"| node_robot_description
node_robot_description -->|"patches collisions"| node_collision_patch
node_world -->|"hosts robot"| node_rgbd_camera
node_robot_description -->|"configures control"| node_controller_config
node_rgbd_camera -->|"sends RGB-D"| node_detector
node_detector -->|"uses masks"| node_segmentation
node_detector -->|"uses projection"| node_camera_geometry
node_detector -->|"publishes cube poses"| node_coordinator
node_prompt -->|"sends confirmation"| node_coordinator
node_coordinator -->|"builds collision scene"| node_planning_scene
node_coordinator -->|"requests motion"| node_moveit_interface
node_coordinator -->|"commands grasp"| node_gripper
node_moveit_interface -->|"plans and executes"| node_move_group
node_moveit_interface -->|"awaits actions"| node_ros_utils
node_gripper -->|"awaits actions"| node_ros_utils
node_move_group -->|"sends trajectories"| node_gazebo_control
node_gripper -->|"sends gripper commands"| node_gazebo_control
node_coordinator -->|"checks placement by camera"| node_detector

click node_launch "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/launch/cup_sorting.launch.py"
click node_world "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/worlds/openarm_cup_sorting_world.sdf"
click node_launch_helpers "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/openarm_sorting_bringup/launch_support.py"
click node_robot_description "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/openarm_sorting_description/robot_description.py"
click node_collision_patch "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/openarm_sorting_description/gripper_collision_patch.py"
click node_rgbd_camera "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/urdf/openarm_v20_gazebo.urdf.xacro"
click node_controller_config "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/config/gazebo_controllers.yaml"
click node_detector "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py"
click node_segmentation "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/color_segmentation.py"
click node_camera_geometry "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/camera_geometry.py"
click node_coordinator "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py"
click node_prompt "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/task_prompt.py"
click node_planning_scene "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/planning_scene.py"
click node_moveit_interface "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/moveit_interface.py"
click node_gripper "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/gripper.py"
click node_ros_utils "https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/ros_utils.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_launch,node_world,node_launch_helpers,node_rgbd_camera,node_controller_config toneBlue
class node_robot_description,node_collision_patch toneAmber
class node_detector,node_segmentation,node_camera_geometry toneMint
class node_coordinator,node_prompt toneRose
class node_planning_scene,node_moveit_interface,node_gripper,node_ros_utils,node_operator,node_move_group,node_gazebo_control toneIndigo
```

## Components

### Simulation and bringup

- [Cup sorting launch](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/launch/cup_sorting.launch.py): `src/openarm_sorting_bringup/launch/cup_sorting.launch.py`
- [Gazebo world](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/worlds/openarm_cup_sorting_world.sdf): `src/openarm_sorting_bringup/worlds/openarm_cup_sorting_world.sdf`
- [Launch support](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_bringup/openarm_sorting_bringup/launch_support.py): `src/openarm_sorting_bringup/openarm_sorting_bringup/launch_support.py`
- [Simulated RGB-D camera](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/urdf/openarm_v20_gazebo.urdf.xacro): `src/openarm_sorting_description/urdf/openarm_v20_gazebo.urdf.xacro`
- [Gazebo controllers](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/config/gazebo_controllers.yaml): `src/openarm_sorting_description/config/gazebo_controllers.yaml`

### Robot description

- [Robot description](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/openarm_sorting_description/robot_description.py): `src/openarm_sorting_description/openarm_sorting_description/robot_description.py`
- [Finger collision patch](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_description/openarm_sorting_description/gripper_collision_patch.py): `src/openarm_sorting_description/openarm_sorting_description/gripper_collision_patch.py`

### Cube perception

- [Cube detector](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py): `src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py`
- [Color segmentation](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/color_segmentation.py): `src/openarm_sorting_vision/openarm_sorting_vision/color_segmentation.py`
- [Camera geometry](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_vision/openarm_sorting_vision/camera_geometry.py): `src/openarm_sorting_vision/openarm_sorting_vision/camera_geometry.py`

### Task execution

- [Sorting coordinator](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py): `src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py`
- [Task confirmation](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/task_prompt.py): `src/openarm_sorting_manipulation/openarm_sorting_manipulation/task_prompt.py`

### Motion and gripper

- [Planning scene](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/planning_scene.py): `src/openarm_sorting_manipulation/openarm_sorting_manipulation/planning_scene.py`
- [MoveIt client](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/moveit_interface.py): `src/openarm_sorting_manipulation/openarm_sorting_manipulation/moveit_interface.py`
- [Left gripper client](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/gripper.py): `src/openarm_sorting_manipulation/openarm_sorting_manipulation/gripper.py`
- [ROS async helpers](https://github.com/men3m-4/openarm_sorting/blob/main/src/openarm_sorting_manipulation/openarm_sorting_manipulation/ros_utils.py): `src/openarm_sorting_manipulation/openarm_sorting_manipulation/ros_utils.py`

### Other components

- **Operator**
- **MoveIt move_group**
- **Gazebo control**

## Connections

- Operator → Cup sorting launch: starts (evidence: `README.md`)
- Cup sorting launch → Gazebo world: starts simulation (evidence: `README.md`)
- Cup sorting launch → Cube detector: starts perception (evidence: `README.md`)
- Cup sorting launch → Sorting coordinator: starts task (evidence: `README.md`)
- Cup sorting launch → Launch support: uses configuration (evidence: `src/openarm_sorting_bringup/launch/cup_sorting.launch.py`)
- Launch support → Robot description: loads description (evidence: `src/openarm_sorting_bringup/openarm_sorting_bringup/launch_support.py`)
- Robot description → Finger collision patch: patches collisions (evidence: `src/openarm_sorting_description/openarm_sorting_description/robot_description.py`)
- Gazebo world → Simulated RGB-D camera: hosts robot (evidence: `README.md`)
- Robot description → Gazebo controllers: configures control (evidence: `README.md`)
- Simulated RGB-D camera → Cube detector: sends RGB-D (evidence: `README.md`)
- Cube detector → Color segmentation: uses masks (evidence: `src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py`)
- Cube detector → Camera geometry: uses projection (evidence: `src/openarm_sorting_vision/openarm_sorting_vision/cube_detector.py`)
- Cube detector → Sorting coordinator: publishes cube poses (evidence: `README.md`)
- Task confirmation → Sorting coordinator: sends confirmation (evidence: `README.md`)
- Sorting coordinator → Planning scene: builds collision scene (evidence: `src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py`)
- Sorting coordinator → MoveIt client: requests motion (evidence: `src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py`)
- Sorting coordinator → Left gripper client: commands grasp (evidence: `src/openarm_sorting_manipulation/openarm_sorting_manipulation/coordinator.py`)
- MoveIt client → MoveIt move_group: plans and executes (evidence: `README.md`)
- MoveIt client → ROS async helpers: awaits actions (evidence: `src/openarm_sorting_manipulation/openarm_sorting_manipulation/moveit_interface.py`)
- Left gripper client → ROS async helpers: awaits actions (evidence: `src/openarm_sorting_manipulation/openarm_sorting_manipulation/gripper.py`)
- MoveIt move_group → Gazebo control: sends trajectories (evidence: `README.md`)
- Left gripper client → Gazebo control: sends gripper commands (evidence: `README.md`)
- Sorting coordinator → Cube detector: checks placement by camera (evidence: `README.md`)
