How omar-alzubaidi/walkersafetyai works
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