# sea-bass/pyrobosim architecture

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

## Overview

##### Project Type & Purpose
- pyrobosim is a ROS 2–enabled 2D mobile robot simulator aimed at enabling behavior prototyping. Its purpose is to simulate robot dynamics, navigation, manipulation, and planning in a 2D environment.
- The README and file tree indicate that the project focuses on simulation core functionality, planning (including PDDLStream integration), navigation, manipulation, and a GUI, along with full ROS and messaging integration.

##### Key Components
- Simulator Core:
▪ Core Modules (in pyrobosim/pyrobosim/core): Handles primary simulation aspects like dynamics, world representation (world, room, hallway), robot handling, objects, and YAML utilities.
▪ Navigation Modules (pyrobosim/pyrobosim/navigation): Implements planning algorithms (A*, RRT, PRM) and occupancy grid management. Mark it as responsible for path planning and world graph construction.
▪ Manipulation Modules (pyrobosim/pyrobosim/manipulation): Contains grasping and interaction logic for robot manipulation.
▪ Planning Modules (pyrobosim/pyrobosim/planning): Focus on actions, high-level task planning, and integrates PDDLStream-based planners.
▪ Utility Modules (pyrobosim/pyrobosim/utils): Shared helpers, logging, trajectory, pose and polygon utilities.

- Data & Configuration:
- Data component that provides sample models, YAML templates, configurations, and PDDL definitions (see pyrobosim/pyrobosim/data and the pddlstream domains).
- This is essential for describing simulation world, object, and location data.

- Graphical User Interface:
- The GUI component (pyrobosim/pyrobosim/gui) offers visual simulation feedback, an interface to interact with the simulation (including action runners and world canvas).

- ROS Integration:
- It includes adapters (ros_interface, ros_conversions) that switch between the simulation engine and ROS messaging.
- Link this to the “pyrobosim_msgs” package, where ROS messages, services, and actions (like those for executing tasks, path planning, and world state) are defined.

- Docker & Deployment:

- Testing & Documentation:

##### Relationships and Interactions
- The Simulator Core interacts with the Data & Configuration modules — it reads simulation configurations, world data, and object models.
- The Navigation, Manipulation, and Planning modules all feed into the simulation core’s behavior engine. For example, the Planning module might invoke methods in the Navigation module.
- The GUI interacts bi-directionally with the simulation core for visualization and command execution.
- The “pyrobosim_ros” module provides a bridge between the ROS ecosystem and the Core engine, using messages/action interfaces defined in “pyrobosim_msgs”.
- Docker and deployment components encapsulate all of these modules, ensuring that the development and execution environments are consistent.

##### Architectural Patterns & Design Principles
- The project exhibits a layered architecture where the core simulation functionalities are separated into distinct domain modules (core, navigation, manipulation, planning, and utilities).
- The separation between the simulation engine and the ROS-adapter (pyrobosim_ros) follows a modular integration pattern, which enables reusability in non-ROS contexts.
- The emphasis on configuration through YAML and templated data indicates that the project is designed for flexibility and extensibility.
- Testing and documentation are integrated into the system, suggesting adherence to continuous integration and maintainability best practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulator Core Engine"
        Core["Core Modules"]:::core
        Nav["Navigation Modules"]:::nav
        Manip["Manipulation Modules"]:::manip
        Plan["Planning Modules"]:::plan
        Utils["Utility Modules"]:::utils
    end

    Data_Conf["Data & Configuration"]:::data
    GUI["Graphical User Interface (GUI)"]:::gui
    ROS_Adapter["ROS Adapter"]:::ros
    ROS_Messaging["ROS Messaging"]:::ros
    Docker["Docker & Deployment"]:::docker

    %% Data flows
    Data_Conf -->|"config_input"| Core

    %% Internal module interactions
    Nav -->|"feeds_into"| Core
    Manip -->|"feeds_into"| Core
    Plan -->|"feeds_into"| Core

    %% GUI bidirectional communication with Core
    Core -->|"state_updates"| GUI
    GUI -->|"commands"| Core

    %% ROS Integration
    Core -->|"ROS_msgs"| ROS_Adapter
    ROS_Adapter -->|"interface_to"| ROS_Messaging

    %% Docker & Deployment connections
    Docker -->|"deploys"| Data_Conf
    Docker -->|"deploys"| Core
    Docker -->|"deploys"| GUI
    Docker -->|"deploys"| ROS_Adapter

    %% Click Events
    click Core "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/core"
    click Nav "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/navigation"
    click Manip "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/manipulation"
    click Plan "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/planning"
    click Utils "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/utils"
    click Data_Conf "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/data"
    click GUI "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim/pyrobosim/gui"
    click ROS_Adapter "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim_ros/pyrobosim_ros"
    click ROS_Messaging "https://github.com/sea-bass/pyrobosim/tree/main/pyrobosim_msgs"
    click Docker "https://github.com/sea-bass/pyrobosim/tree/main/docker/Dockerfile"

    %% Styles
    classDef core fill:#a2d5f2,stroke:#1a1a1a,stroke-width:2px;
    classDef nav fill:#b0e0a8,stroke:#1a1a1a,stroke-width:2px;
    classDef manip fill:#e0aaff,stroke:#1a1a1a,stroke-width:2px;
    classDef plan fill:#ffc3a0,stroke:#1a1a1a,stroke-width:2px;
    classDef utils fill:#f3e5ab,stroke:#1a1a1a,stroke-width:2px;
    classDef data fill:#c8e6c9,stroke:#1a1a1a,stroke-width:2px;
    classDef gui fill:#ffe082,stroke:#1a1a1a,stroke-width:2px;
    classDef ros fill:#ce93d8,stroke:#1a1a1a,stroke-width:2px;
    classDef docker fill:#ffcc80,stroke:#1a1a1a,stroke-width:2px;
```
