vehicle-counter/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Flask-based web application for real-time object detection and tracking using YOLOv11. The application supports both webcam streaming and uploaded video file processing with object detection overlays.

Key Dependencies

• Flask: Web framework for routing and serving HTML templates
• OpenCV (cv2): Video processing and frame manipulation
• Ultralytics YOLO: YOLOv11 model for object detection and tracking
• NumPy: Array operations for image data

The YOLO model file (yolo11s.pt) must be present in the root directory.

Running the Application

Start the Flask development server:

python3 app.py

The application runs on 0.0.0.0:8080 and is accessible at http://localhost:8080

Application Architecture

Single-File Structure

The entire application is contained in app.py with no separate modules. All routes, video processing logic, and model initialization are in this single file.

Core Components

YOLO Model (lines 10-11)

• Model loaded once at application startup: model = YOLO("yolo11s.pt")
• Class names extracted from model for labeling: names = model.model.names

Video Processing Pattern Both webcam and uploaded video processing share identical detection logic:

1. Frame skipping: Only processes every 2nd frame (count % 2 != 0) for performance
2. Frame resizing: All frames resized to (1020, 600) for consistent output
3. YOLO tracking: Uses model.track(frame, persist=True) to maintain object IDs across frames
4. Annotation: Draws bounding boxes and labels with format {track_id} - {class_name}
5. Streaming: Yields JPEG frames as multipart HTTP response

Duplicate Code The functions detect_objects_from_webcam() (lines 21-52) and detect_objects_from_video() (lines 86-118) contain nearly identical logic - only the video source differs (webcam vs. file path).

Routes and Flow

Main Routes:

• / - Landing page (index.html) with video upload form and webcam button
• /start_webcam - Webcam detection page (webcam.html)
• /upload [POST] - Handles video file uploads, saves to uploads/ directory
• /uploads/<filename> - Video playback page (play_video.html)

Streaming Routes:

• /webcam_feed - Streams processed webcam frames with detections
• /video_feed/<filename> - Streams processed video file frames with detections
• /video/<filename> - Serves raw video files from uploads directory

Templates

All templates follow the same pattern:

• Centered layout with flex containers
• Fixed dimensions (1020x600) for video display
• "Back to Home" link for navigation

Important Notes

File Uploads

• Uploaded videos are saved to uploads/ directory (created automatically if missing)
• No file size limits or validation beyond checking file existence
• No cleanup mechanism for uploaded files

Performance Optimization

• Frame skipping (every 2nd frame) reduces CPU load but may miss fast-moving objects
• Frame resizing to 1020x600 is hardcoded throughout

Object Tracking

• Uses persistent tracking (persist=True) to maintain object IDs across frames
• Track IDs are displayed alongside class names in the format: {track_id} - {class_name}
• Tracking state persists within a single video stream session

Webcam Access

• Uses cv2.VideoCapture(0) for default webcam
• No error handling if webcam is unavailable or already in use