# droid-dataset/droid architecture

> Architecture diagram of the GitHub repository droid-dataset/droid, 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/droid-dataset/droid
- Repository: https://github.com/droid-dataset/droid

## Overview

##### Project Type and Purpose
- The project is a platform for setting up a teleoperated robot system to collect demonstration data – “in-the-wild” dataset collection for robot manipulation.
- Its purpose is twofold: (a) establishing the hardware–software integration for the robot (including camera calibration, sensor input, and robot control such as with the Franka arm), and (b) running workflows for data collection, evaluation, postprocessing, and training of policies.

##### File Structure Analysis
- Notice the presence of multiple Docker-related directories (.docker) with configurations for different environments (“laptop” and “nuc”). This shows an emphasis on containerized deployment.
- The “droid” directory encapsulates the core functionality. It includes many submodules – for calibration, camera utilities (with support for live cameras and recordings), controllers (including an Oculus controller), data loading and processing, evaluation routines, robot and inverse kinematics (robot_ik), training, postprocessing and user interface components.
- There is also a “scripts” directory that provides automation for tasks (e.g. data conversion, evaluation, training, testing), which supports the operational workflows.
- Configuration files (in the “config” directory) ensure hardware-specific parameters are clearly separated (e.g., using “fr3” and “panda” setups).

##### Key Components and Their Roles
a. Hardware & External Devices:
– Robot hardware (e.g., Franka robotic arms tied to “droid/franka” and “droid/robot_ik”).
– Cameras (via modules in “droid/camera_utils”).
– Controllers (including “droid/controllers/oculus_controller.py” for teleoperation).
b. Data Acquisition & User Interface:
– Data collection is managed in “droid/user_interface” (with GUIs and data collector scripts) and supplementary scripts.
– Camera readers (both live: “zed_camera.py”, and recorded: “mp4_reader.py”/“svo_reader.py”) handle input data streams.
c. Data Processing & Postprocessing:
– Modules in “droid/data_loading”, “droid/data_processing”, “droid/postprocessing”, and “droid/trajectory_utils” manage the ingestion, transformation, and postprocessing of collected data.
d. Evaluation & Training:
– “droid/evaluation” and “droid/training” (plus corresponding scripts in “scripts/evaluation” and “scripts/training”) implement policy evaluation, model training, and sanity-checks.
e. Deployment and Environment Management:
– Distinct Dockerfiles and docker-compose files (in “.docker” and GitHub workflows) show that the platform supports multiple environments (laptop vs. nuc configurations), ensuring reproducibility and ease of deployment.
f. Supporting Utilities & Miscellaneous:
– “droid/misc” and “droid/plotting” include helpful functionality like parameters, visualization, and utility functions crucial for logging, version control, and data analysis.

##### Relationships and Interactions
- Data flows start from the hardware layer (sensors and controllers) and pass through the data acquisition layer (user interface and camera_utils) toward data processing pipelines.
- Processed data is then used for evaluation and training, with rich postprocessing functionality.
- Additionally, configuration files and Docker/CI configurations indicate that setting up and deploying the system is an integral part.
- There are significant interactions between the modules – for instance, calibration feeds into data acquisition; processed data feeds into evaluation routines; and training modules depend on properly collected and processed data.

##### Architectural Patterns & Technologies
- The system adopts containerization via Docker and is built to support multiple deployment environments, which speaks to patterns like “Infrastructure as Code”.
- The modular decomposition (with directories clearly split according to functionality such as “camera_utils”, “controllers”, “data_processing”, “robot_ik”, etc.) may suggest a loosely coupled, layered architecture.
- Scripts and CI/CD workflows indicate continuous integration practices.
- The separation of configuration from code (e.g., config/fr3 vs. config/panda) showcases a design favoring parameterization for hardware variability.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        FR["Franka Robot Control"]:::hardware
        IK["Robot Inverse Kinematics"]:::hardware
        CF["Config FR3"]:::hardware
        CP["Config Panda"]:::hardware
    end

    %% Data Acquisition Layer
    subgraph "Data Acquisition Layer"
        direction TB
        CA["Camera Utilities"]:::dataAcquisition
        ZED["ZED Camera Reader"]:::dataAcquisition
        CR["Recorded Camera Readers"]:::dataAcquisition
        OC["Oculus Controller"]:::dataAcquisition
        UI["User Interface & Data Collection"]:::dataAcquisition
    end

    %% Data Processing Pipeline
    subgraph "Data Processing Pipeline"
        direction TB
        DL["Data Loading"]:::processing
        DP["Data Processing"]:::processing
        TU["Trajectory Utilities"]:::processing
        PP["Postprocessing"]:::processing
    end

    %% Evaluation & Training
    subgraph "Evaluation & Training"
        direction TB
        EV["Evaluation Routines"]:::evaluation
        SEV["Scripts Evaluation"]:::evaluation
        TR["Training Modules"]:::evaluation
        STR["Scripts Training"]:::evaluation
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        direction TB
        DC["Docker Configurations"]:::deployment
        CI["CI/CD Workflows"]:::deployment
    end

    %% Utilities & Miscellaneous
    subgraph "Utilities & Miscellaneous"
        direction TB
        MU["Misc Utilities"]:::utilities
        PV["Plotting & Visualization"]:::utilities
    end

    %% Relationships and Data Flows
    %% Hardware to Data Acquisition
    FR -->|"controls"| UI
    IK -->|"kinematics"| UI
    CF -->|"configures"| UI
    CP -->|"configures"| UI
    CA -->|"feeds"| UI
    OC -->|"operates"| UI
    ZED -->|"captures"| CA
    CR -->|"captures"| CA

    %% Data Acquisition to Data Processing Pipeline
    UI -->|"data flows"| DL

    %% Processing Pipeline Internal Flow
    DL -->|"transforms"| DP
    DP -->|"calculates"| TU
    TU -->|"prepares"| PP

    %% Data Processing Pipeline to Evaluation & Training
    PP -->|"evaluates"| EV
    PP -->|"trains"| TR

    %% Evaluation & Training internal flow
    EV -->|"scripted"| SEV
    TR -->|"scripted"| STR

    %% Deployment influences (dashed arrows)
    DC ..-> FR
    DC ..-> UI
    DC ..-> DL
    DC ..-> EV
    DC ..-> TR

    CI ..-> FR
    CI ..-> UI
    CI ..-> DL
    CI ..-> EV
    CI ..-> TR

    %% Postprocessing connects to Utilities & Miscellaneous
    PP -->|"logs/visualizes"| MU
    PP -->|"displays"| PV

    %% Styles
    classDef hardware fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef dataAcquisition fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef processing fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef evaluation fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef deployment fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef utilities fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

%% Click Events
click FR "https://github.com/droid-dataset/droid/tree/main/droid/franka"
click IK "https://github.com/droid-dataset/droid/tree/main/droid/robot_ik"
click CF "https://github.com/droid-dataset/droid/tree/main/config/fr3"
click CP "https://github.com/droid-dataset/droid/tree/main/config/panda"
click CA "https://github.com/droid-dataset/droid/tree/main/droid/camera_utils"
click ZED "https://github.com/droid-dataset/droid/blob/main/droid/camera_utils/camera_readers/zed_camera.py"
click CR "https://github.com/droid-dataset/droid/tree/main/droid/camera_utils/recording_readers"
click OC "https://github.com/droid-dataset/droid/blob/main/droid/controllers/oculus_controller.py"
click UI "https://github.com/droid-dataset/droid/tree/main/droid/user_interface"
click DL "https://github.com/droid-dataset/droid/tree/main/droid/data_loading"
click DP "https://github.com/droid-dataset/droid/tree/main/droid/data_processing"
click TU "https://github.com/droid-dataset/droid/tree/main/droid/trajectory_utils"
click PP "https://github.com/droid-dataset/droid/tree/main/droid/postprocessing"
click EV "https://github.com/droid-dataset/droid/tree/main/droid/evaluation"
click SEV "https://github.com/droid-dataset/droid/tree/main/scripts/evaluation"
click TR "https://github.com/droid-dataset/droid/tree/main/droid/training"
click STR "https://github.com/droid-dataset/droid/tree/main/scripts/training"
click DC "https://github.com/droid-dataset/droid/blob/main/.docker"
click CI "https://github.com/droid-dataset/droid/tree/main/.github/workflows"
click MU "https://github.com/droid-dataset/droid/tree/main/droid/misc"
click PV "https://github.com/droid-dataset/droid/tree/main/droid/plotting"
```
