# omar-alzubaidi/walkersafetyai architecture

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

- Interactive diagram: https://gitdiagram.com/omar-alzubaidi/walkersafetyai
- Repository: https://github.com/omar-alzubaidi/walkersafetyai

## Overview

##### Project type and purpose
- This is an AI-powered assistive tool (open-source Python application) that runs locally on a device (laptop/Raspberry Pi) to help older adults avoid obstacles.
- Its core features: real-time video capture, YOLOv8-nano object detection, monocular distance estimation, automatic focal-length calibration, and text-to-speech voice alerts at defined thresholds.

##### File structure
- Top-level Python scripts each implement a single responsibility:
- camera_handler.py – captures frames from the camera and handles video I/O
- object_detector.py – loads YOLOv8n model and runs inference
- focal_length_calibrator.py – computes focal length automatically at startup
- distance_estimator.py – converts pixel measurements to real-world distances
- voice_alert.py – triggers voice warnings at 2 m, 1 m, 0.5 m
- config.py – holds constants (thresholds, model paths, camera parameters)
- utils.py – shared helper functions (e.g., logging, measurement conversions)
- main.py – orchestration script, ties all modules together in runtime flow
- Supporting files: requirements.txt (dependencies), focal_length.txt (generated), README.md.

##### Extract additional architectural insights from README
- On startup, the system auto-calibrates focal length (no user key press).
- Model download and setup occur automatically when main.py is first run.
- The codebase is modular and professional, favoring single-responsibility per module.

a. Main components
- Video Capture Module
- Calibration Module
- Object Detection Module
- Distance Estimation Module
- Voice Alert Module
- Configuration & Utilities
- External Dependencies (YOLOv8n model file, Text-to-Speech engine)
b. Relationships and data flow
1. Camera → Video Capture → Frame buffer
2. Frame buffer → Calibration Module → focal_length.txt (on first run)
4. Detection output + focal_length → Distance Estimator → real-world distances
5. Distance output + thresholds (config) → Voice Alert → audio output
6. Utilities & Config used by every module for logging, parameter access
c. Architectural patterns & principles
- Pipeline architecture: data flows sequentially through capture→detect→estimate→alert
- Lazy initialization & caching: model and focal-length calibration run once, results reused
d. Key technologies & frameworks
- Python 3.x
- ultralytics YOLOv8-nano (pip install ultralytics)
- OpenCV for video capture & image processing
- pyttsx3 or similar TTS for voice alerts
- NumPy for numeric operations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Orchestration
    main["main.py\nOrchestration Pipeline"]:::module

    %% Startup Modules
    main -->|"startup: calibrate focal length"| focal_length_calibrator
    main -->|"startup: load model"| object_detector
    main -->|"start video capture"| camera_handler

    %% Video Capture Pipeline
    CameraHardware["Camera Hardware"]:::external-camera
    CameraHardware -->|"video stream"| camera_handler
    camera_handler -->|"frame BGR image"| frame_buffer

    %% Calibration Module
    focal_length_calibrator["focal_length_calibrator.py\nCalibration Module"]:::module
    focal_length_calibrator -->|"writes focal_length.txt"| focal_file

    focal_file["focal_length.txt"]:::data

    %% Object Detection Module
    object_detector["object_detector.py\nObject Detection Module"]:::module
    object_detector -->|"detection list\n(bboxes,class IDs)"| detection_list
    YOLOModel["YOLOv8n Model File"]:::external-model
    YOLOModel --> object_detector

    frame_buffer -->|"frame BGR image\n+ focal_length.txt"| object_detector
    frame_buffer --> object_detector

    %% Distance Estimation Module
    distance_estimator["distance_estimator.py\nDistance Estimation Module"]:::module
    detection_list -->|"detections\n+ focal_length"| distance_estimator
    distance_estimator -->|"real-world distances (m)"| distance_value

    distance_value["Real-World Distances"]:::data

    %% Voice Alert Module
    voice_alert["voice_alert.py\nVoice Alert Module"]:::module
    distance_value -->|"distance + thresholds"| voice_alert
    TTS["TTS Engine"]:::external-tts
    voice_alert -->|"audio stream"| AudioOutput
    TTS --> voice_alert

    AudioOutput["Audio Output"]:::data

    %% Shared Config & Utilities
    config["config.py\nConfiguration & Constants"]:::configutil
    utils["utils.py\nShared Utilities"]:::configutil

    %% Dependencies Document
    requirements["requirements.txt"]:::doc
    readme["README.md"]:::doc

    %% Dependencies Edges
    config -.-> main
    config -.-> camera_handler
    config -.-> focal_length_calibrator
    config -.-> object_detector
    config -.-> distance_estimator
    config -.-> voice_alert

    utils -.-> main
    utils -.-> camera_handler
    utils -.-> focal_length_calibrator
    utils -.-> object_detector
    utils -.-> distance_estimator
    utils -.-> voice_alert

    readme --> main
    requirements --> main

    %% Classes
    classDef module fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef data fill:#f2f2f2,stroke:#666,stroke-width:1px;
    classDef external-camera fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef external-model fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external-tts fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef configutil fill:#FFE4B5,stroke:#000,stroke-width:1px;
    classDef doc fill:#E6E6FA,stroke:#000,stroke-width:1px;

    %% Click Events
    click camera_handler "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/camera_handler.py"
    click focal_length_calibrator "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/focal_length_calibrator.py"
    click object_detector "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/object_detector.py"
    click distance_estimator "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/distance_estimator.py"
    click voice_alert "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/voice_alert.py"
    click config "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/config.py"
    click utils "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/utils.py"
    click main "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/main.py"
    click requirements "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/requirements.txt"
    click readme "https://github.com/omar-alzubaidi/walkersafetyai/blob/main/README.md"
```
