# ncsu-yoon-lab/project-oval architecture

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

- Interactive diagram: https://gitdiagram.com/ncsu-yoon-lab/project-oval
- Repository: https://github.com/ncsu-yoon-lab/project-oval

## Overview

##### Project Type and Purpose
- Project Oval is an autonomous vehicle system aimed at operating on a university campus. It leverages a ROS2 framework running on an onboard computer (Jetson) to coordinate multiple sensors and control nodes. It not only manages vehicle motion and sensor data (GPS, camera, joystick, etc.) but also integrates external interfaces like a GUI (built with Kivy) and an AWS-hosted web server for remote control or monitoring.
- Besides the main autonomous vehicle control nodes (in the “project-oval” directory), there is an Arduino directory containing motor actuation code and a “sidewalk-segmentation” folder that appears to provide additional computer vision functionality (possibly for detecting or segmenting sidewalks for navigation).

##### File Structure – Architecturally
- At the top level you see folders such as “arduino”, “project-oval”, and “sidewalk-segmentation.” This separation implies a design where:
- The “project-oval” directory contains the core ROS2 Python nodes (e.g., joy, GNSS, Zed, Xbox Controller, Motor Actuation, Pure Pursuit, RTK, Server, and Camera) as well as supporting libraries.
- The “arduino” folder contains low-level controller code which the onboard computer’s Motor Actuation Node may trigger.
- “sidewalk-segmentation” contains scripts, configurations, and model files for image segmentation that might either be used as an independent module or integrated with the primary vehicle navigation system.
- Look for configuration and build files (package.xml, setup.py, requirements.txt, etc.) that underscore dependencies and environment setup typical of a ROS2 ecosystem and Python-based projects.

##### Final Recommendations
- Combine components wherever logical interactions occur (e.g., grouping all sensor nodes together) to avoid clutter.
- Don’t shy away from detailing even what might seem like “minor” nodes—they are critical to understanding the overall flow (especially in an autonomous system where timing and coordination are key).
- Once the draft is complete, review the intended startup sequences (as laid out in the README) to ensure every node and data path is correctly represented.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% On-board ROS2 System
    subgraph "On-board ROS2 System"
        driver["Driver Node"]:::ros
        legacy["Legacy Driver Node"]:::ros
        lane["Lane Follower Node"]:::ros
        xbox["Xbox Controller Node"]:::ros
        motor["Motor Actuation Node"]:::ros
        server["Server Node"]:::ros
        camera["Camera Node"]:::ros
    end

    %% Sensor Inputs
    subgraph "Sensor Inputs"
        joy["Joy Node"]:::sensor
        gnss["Swift GNSS Node"]:::sensor
        rtk["RTK Node"]:::sensor
        zed["Zed Node"]:::sensor
    end

    %% Computer Vision Module
    subgraph "Computer Vision Module"
        seg["Sidewalk Segmentation Module"]:::cv
        segModel["Segmentation Model"]:::cv
    end

    %% Hardware Interfaces
    subgraph "Hardware Interfaces"
        arduino["Arduino Motor Control"]:::hardware
    end

    %% External Interfaces
    subgraph "External Interfaces"
        aws["AWS EC2 Web Server"]:::external
        gui["Kivy GUI"]:::external
    end

    %% Connections between Sensor Inputs and ROS2 nodes
    joy -->|"feeds"| xbox
    gnss -->|"coords"| lane
    rtk -->|"orientation"| lane
    zed -->|"image_data"| seg
    zed -->|"image_feed"| camera

    %% Connections within On-board ROS2 System
    xbox -->|"commands"| motor
    motor -->|"triggers"| arduino

    %% External communication
    server <-->|"sync"| aws
    gui -->|"UI_commands"| server

    %% Styles
    classDef ros fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef sensor fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef cv fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef hardware fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef external fill:#D8BFD8,stroke:#333,stroke-width:2px;

    %% Click Events
    click driver "https://github.com/ncsu-yoon-lab/project-oval/blob/main/project-oval/driver_node.py"
    click legacy "https://github.com/ncsu-yoon-lab/project-oval/blob/main/project-oval/legacy_driver_node.py"
    click lane "https://github.com/ncsu-yoon-lab/project-oval/blob/main/project-oval/lane_follower_node.py"
    click xbox "https://github.com/ncsu-yoon-lab/project-oval/blob/main/project-oval/xbox_controller_node.py"
    click motor "https://github.com/ncsu-yoon-lab/project-oval/blob/main/project-oval/library/arduino_controller.py"
    click arduino "https://github.com/ncsu-yoon-lab/project-oval/blob/main/arduino/motor_arduino.ino"
    click seg "https://github.com/ncsu-yoon-lab/project-oval/blob/main/sidewalk-segmentation/sidewalk_segmentation.py"
    click segModel "https://github.com/ncsu-yoon-lab/project-oval/tree/main/sidewalk-segmentation/sidewalk_segmentation_model/"
```
