# orcahand/rwr_system architecture

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

- Interactive diagram: https://gitdiagram.com/orcahand/rwr_system
- Repository: https://github.com/orcahand/rwr_system

## Overview

- Experiments & Launchers: This module (under the “experiments” directory) contains various launch files and experiment scripts (e.g., teleop control, rosbag record, accuracy tests). Represent it as the primary “Experiment/Launch Controller”.
- Ingress: Under “src/ingress”, there are modules for handling sensor inputs from different sources:
- OAK-D (camera streams) and its related configuration.
- Rokoko sensors for glove input.
- Additional sensing through webcams or paper experiments.
Under a single “Ingress” or “Sensor Data Acquisition” component.
- Hand Control: In “src/hand_control”, which includes calibration, dynamixel client, kinematics, and node files. This module is the backbone for interfacing with the robot hand – labeling it as “Hand Control & Kinematics”.
- Retargeter: Found in “src/retargeter”, where the retargeting algorithms lie. It subscribes to sensor data (e.g., glove keypoints from ingress) and publishes hand control commands. Label it “Retargeter/Mapping Logic”.
- Logger: The “src/logger” package logs data and sensor streams. Represent this component as “Data Logger/Recorder”.
- Visualization (Viz): Under “src/viz”, this area handles visualization routines (both via Rviz and rosbag-related visualizers). Label it “Visualization & RViz Integration”.
- Processing (if applicable): Although not the central pipeline, the “src/processing” package likely handles post-process analysis of recorded data.

##### Data Flow and Interactions
- Hand Control to the Visualization module, so that commands and joint states are sent for real-time visual feedback in Rviz.
- Additionally, demonstrate how Experiment Launchers are used to initialize these nodes (launching groups of nodes typically together).

##### Architectural Patterns & Technologies
- Use ROS 2 as the backbone architecture. Emphasize that nodes publish/subscribe on topics (for example, RokokoNode publishes on /ingress/mano, RetargeterNode subscribes to it and publishes on /hand/policy_output).
- That the project leverages a modular package design. This encourages separation of concerns – sensor ingestion, control logic, and visualization are in dedicated packages.
- Mention that some packages (like hand_control) are built using both Python and CMake, indicated by the CMakeLists.txt files.
- Use of roslaunch files (both for experiments and dedicated package nodes) and ROS topic-centric design.

##### Final Touches
- Utilize annotations to include critical information such as ROS topics and key launch files (e.g., retargeting_rviz_orca.launch.py, run_teleop_rokoko.launch.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level - Experiment & Launch Manager
    EXP["Experiment & Launch Controller"]:::exp

    %% Middle Layer - Sensor Data Acquisition
    subgraph "Sensor Data Acquisition"
        OAK["OAK-D Sensor Module"]:::ing
        ROK["Rokoko Sensor Module"]:::ing
        WEB["Webcam Sensor Module"]:::ing
        PAP["Paper Experiments Module"]:::ing
    end

    %% Middle Layer - Retargeter/Mapping Logic
    RET["Retargeter/Mapping Logic"]:::ret

    %% Middle Layer - Hand Control & Kinematics
    HC["Hand Control & Kinematics"]:::hc

    %% Bottom Layer - Data Logger/Recorder and Visualization
    LOG["Data Logger/Recorder"]:::log
    VIZ["Visualization & RViz Integration"]:::viz

    %% Optional Processing Component (Post-Processing Analysis)
    PROC["Processing (Post-Process Analysis)"]:::proc

    %% Connections initiated from Experiment & Launch Controller
    EXP -->|"init"| OAK
    EXP -->|"init"| ROK
    EXP -->|"init"| WEB
    EXP -->|"init"| PAP
    EXP -->|"init"| RET
    EXP -->|"init"| HC
    EXP -->|"init"| VIZ
    EXP -->|"init"| LOG

    %% Data Flow from Ingress to Retargeter
    OAK -->|"sensor_data"| RET
    ROK -->|"sensor_data"| RET
    WEB -->|"sensor_data"| RET
    PAP -->|"sensor_data"| RET

    %% Data Flow from Retargeter to Hand Control
    RET -->|"control_cmd"| HC

    %% Hand Control sends state feedback to Visualization
    HC -->|"joint_states"| VIZ

    %% Logging data connections
    OAK -->|"raw_data"| LOG
    ROK -->|"raw_data"| LOG
    WEB -->|"raw_data"| LOG
    PAP -->|"raw_data"| LOG
    RET -->|"mapping_data"| LOG
    HC -->|"control_data"| LOG

    %% Optional post-processing from Logger to Processing module
    LOG -->|"post_process_data"| PROC

    %% Click Events
    click EXP "https://github.com/orcahand/rwr_system/tree/main/experiments/launch"
    click OAK "https://github.com/orcahand/rwr_system/tree/main/src/ingress/oakd"
    click ROK "https://github.com/orcahand/rwr_system/tree/main/src/ingress/rokoko"
    click WEB "https://github.com/orcahand/rwr_system/tree/main/src/ingress/webcam"
    click PAP "https://github.com/orcahand/rwr_system/tree/main/src/ingress/paper_experiments"
    click HC "https://github.com/orcahand/rwr_system/tree/main/src/hand_control"
    click RET "https://github.com/orcahand/rwr_system/tree/main/src/retargeter"
    click LOG "https://github.com/orcahand/rwr_system/tree/main/src/logger"
    click VIZ "https://github.com/orcahand/rwr_system/tree/main/src/viz"
    click PROC "https://github.com/orcahand/rwr_system/tree/main/src/processing"

    %% Styles
    classDef exp fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef ing fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef ret fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef hc fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef log fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef viz fill:#e6e6ff,stroke:#6666ff,stroke-width:2px;
    classDef proc fill:#e6ffe6,stroke:#66cc66,stroke-width:2px;
```
