# autonobot-lab/bestman architecture

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

- Interactive diagram: https://gitdiagram.com/autonobot-lab/bestman
- Repository: https://github.com/autonobot-lab/bestman

## Overview

##### Project Type & Purpose
- BestMan is a robotics platform for mobile manipulation with a focus on sim-to-real integration and modular algorithm deployment.
- Its purpose is to simulate and control a mobile manipulator (wheel-base with an arm) using a rich set of components such as digital twins, motion planning algorithms, perception modules, and a unified Robotics API.
- The platform provides both simulation (through PyBullet) and real-world hardware integration with demo examples and Blender-based rendering.

##### Key Components
a. Simulation & Environment:
- PyBullet Simulation Engine (core of simulation) – the “Env” directory and related Config YAML files.
- DigitalTwin modules manage digital replicas of hardware components.
b. Perception:
- Multiple perception pipelines for object detection (OWL_ViT), grasp pose estimation (AnyGrasp, Contact_GraspNet), affordance recognition, and segmentation (Detic, Grounded SAM, Lang SAM, Segment Anything).
- These are organized under the “Perception” folder.
c. Motion Planning:
- Manipulation and Navigation planning – include submodules like OMPL_Planner, A_star, PRM, and RRT.
- Incorporate Collision Detection modules (both “Basic_CD” and “FCL” versions).
d. Control & Sensor:
- PIDController under “Controller”.
- Sensor modules (such as Camera in “Sensor”).
e. Robotics API:
- Unified interfaces to interact with simulation and hardware (in “Robotics_API”).
f. Task Planning:
- Contains task-level and high-level planning (e.g., LLM_P and potentially PDDL streaming components).
g. User Interface & Visualization:
- User_Interface as integration layer for user interactions.
- Visualization modules handling simulation rendering, including the pyBullet-Blender integration (both under Visualization and docs for rendering integration).
h. Supporting Infrastructure:
- Config (various YAML files for different simulation and hardware scenarios).
- Examples that show individual demo setups.
- Install scripts and documentation to support setup and usage.

##### Relationships & Interactions
- The Simulation Engine and DigitalTwin (bidirectional data update: simulation state ↔ digital hardware models).
- Sensors feeding data into Perception modules; perception outputs then guide Motion Planning.
- Motion Planning sending commands to the Controller (PID) and then to the Robotics API to effect actions.
- Task Planning and High-Level Decision-making modules interfacing with both the motion and perception modules.
- Visualization and Blender rendering modules receiving simulation state and simulation logs to produce rendered outputs.
- Integration paths between the different modules (e.g., how Config parameters are universally used by Simulation, Motion Planning, and Perception modules).

##### Architectural Patterns & Design Principles
- Modularity: each major component (simulation, planning, perception, control) is a self-contained module sitting behind a unified API.
- Layer separation: Input (sensors, UI) → Processing (perception, planning, control) → Actuation (Robotics API, simulation actuation).
- Inter-module communication is predominantly via defined configuration interfaces (YAML files in Config) and standardized Python APIs.

##### Technologies & Frameworks
- PyBullet for simulation.
- Python for scripting with a variety of libraries (e.g., OMPL for planning, pre-commit setup using Black and isort for code quality).
- Blender, via the customized pyBulletSimImporter, for high fidelity rendering.
- ROS-like system abstractions (though not explicitly ROS, the layered architecture is similar to common robotics frameworks).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware & Simulation Layer
    subgraph "Hardware & Simulation"
        sim("Simulation Engine"):::simulation
        dt("Digital Twin"):::hardware
        api("Robotics API"):::api
    end

    %% Processing Layer
    subgraph "Processing"
        per("Perception"):::processing
        mp("Motion Planning"):::processing
            subgraph "Motion Planning Components"
                ompl("OMPL Planner"):::processing
                cd("Collision Detection (Basic/FCL)"):::processing
                a_star("A* Planner"):::processing
                prm("PRM"):::processing
                rrt("RRT"):::processing
            end
        cs("Control & Sensor"):::control
            subgraph "Control & Sensor Components"
                ctrl("Controller"):::control
                sens("Sensor"):::control
            end
        tp("Task Planning"):::processing
        vis("Visualization/Rendering"):::vis
    end

    %% User Interface Layer
    subgraph "User Interface Layer"
        ui("User Interface"):::ui
    end

    %% Integration & Support
    subgraph "Integration & Support"
        cfg("Config"):::support
        ex("Examples"):::support
        inst("Install"):::support
    end

    %% Relationships & Data Flow
    %% Config flows to major modules
    cfg -- "applies to" --> sim
    cfg -- "applies to" --> per
    cfg -- "applies to" --> mp
    cfg -- "applies to" --> ctrl
    cfg -- "applies to" --> tp
    cfg -- "applies to" --> vis
    cfg -- "applies to" --> api

    %% Simulation & Digital Twin bidirectional update
    sim -- "state update" --> dt
    dt -- "hardware model update" --> sim

    %% Simulation to Visualization
    sim -- "sim_state" --> vis

    %% Sensor to Perception and Control flow
    sens -- "SensorData" --> per
    sens -- "SensorData" --> ctrl

    %% Perception guides Motion Planning
    per -- "SensorInfo" --> mp

    %% Motion Planning details
    mp -- "uses" --> ompl
    mp -- "uses" --> cd
    mp -- "guides" --> a_star
    mp -- "guides" --> prm
    mp -- "guides" --> rrt

    %% Motion Planning to Control
    mp -- "ControlCommands" --> ctrl

    %% Control to Robotics API for actuation
    ctrl -- "Actuation" --> api

    %% Task Planning interactions
    tp -- "plan guidance" --> mp
    tp -- "task prompts" --> per

    %% User Interface interactions
    ui -- "UserCommands" --> api
    ui -- "TaskSelection" --> tp

    %% Click Events
    click sim "https://github.com/autonobot-lab/bestman/blob/0.3.0/Env/Client.py"
    click dt "https://github.com/autonobot-lab/bestman/blob/0.3.0/DigitalTwin/__init__.py"
    click per "https://github.com/autonobot-lab/bestman/tree/0.3.0/Perception/"
    click mp "https://github.com/autonobot-lab/bestman/tree/0.3.0/Motion_Planning/"
    click ompl "https://github.com/autonobot-lab/bestman/tree/0.3.0/Motion_Planning/Manipulation/OMPL_Planner"
    click cd "https://github.com/autonobot-lab/bestman/tree/0.3.0/Motion_Planning/Manipulation/Collision_Detection"
    click a_star "https://github.com/autonobot-lab/bestman/tree/0.3.0/Motion_Planning/Navigation/A_star"
    click prm "https://github.com/autonobot-lab/bestman/tree/0.3.0/Motion_Planning/Navigation/PRM"
    click rrt "https://github.com/autonobot-lab/bestman/tree/0.3.0/Motion_Planning/Navigation/RRT"
    click ctrl "https://github.com/autonobot-lab/bestman/blob/0.3.0/Controller/PIDController.py"
    click sens "https://github.com/autonobot-lab/bestman/blob/0.3.0/Sensor/Camera.py"
    click api "https://github.com/autonobot-lab/bestman/tree/0.3.0/Robotics_API/"
    click tp "https://github.com/autonobot-lab/bestman/tree/0.3.0/Task_Planning/"
    click ui "https://github.com/autonobot-lab/bestman/tree/0.3.0/User_Interface/"
    click vis "https://github.com/autonobot-lab/bestman/blob/0.3.0/Visualization/Visualizer.py"
    click cfg "https://github.com/autonobot-lab/bestman/tree/0.3.0/Config/"
    click ex "https://github.com/autonobot-lab/bestman/tree/0.3.0/Examples/"
    click inst "https://github.com/autonobot-lab/bestman/tree/0.3.0/Install/"

    %% Styles
    classDef simulation fill:#f9f,stroke:#333,stroke-width:2px;
    classDef hardware fill:#ccf,stroke:#f66,stroke-width:2px;
    classDef api fill:#fc9,stroke:#333,stroke-width:2px;
    classDef processing fill:#cff,stroke:#333,stroke-width:2px;
    classDef control fill:#cfc,stroke:#333,stroke-width:2px;
    classDef ui fill:#ffc,stroke:#333,stroke-width:2px;
    classDef support fill:#eee,stroke:#333,stroke-width:2px;
    classDef vis fill:#efe,stroke:#333,stroke-width:2px;

    %% Node Class Assignments
    class sim simulation;
    class dt hardware;
    class api api;
    class per processing;
    class mp processing;
    class ompl processing;
    class cd processing;
    class a_star processing;
    class prm processing;
    class rrt processing;
    class cs control;
    class ctrl control;
    class sens control;
    class tp processing;
    class vis vis;
    class ui ui;
    class cfg support;
    class ex support;
    class inst support;
```
