Parking Detector v2.0

Overview

A computer vision app for real-time parking space monitoring. It uses YOLOv8 (Ultralytics) for object detection, polygon–object overlap for occupancy, optional uncertainty and “frequent hit” logic, and interactive tools to create, edit, and delete spaces.

Features

• Universal or class-filtered detection — all COCO classes or a restricted list (e.g. vehicles only)
• Interactive polygons — click four corners per space; visual feedback while drawing
• Edit and delete modes — adjust or remove spaces without editing JSON by hand
• Uncertainty and timing — borderline overlap states and dwell time before “probably occupied”
• Frequent detections — treat noisy partial overlaps as occupied when hits spike in a window
• Free / occupied time stats — rolling totals shown on the overlay
• JSON configuration — thresholds and device selection in config/settings.json
• CPU / CUDA / auto — configurable inference device

Project layout

Park_space_detector_Yolov8/
├── src/
│   └── parking_detector.py      # Main application
├── config/
│   └── settings.json            # Runtime settings
├── data/
│   └── parking_spaces.json      # Saved parking polygons
├── models/
│   └── yolov8n.pt               # YOLO weights (downloaded on first run)
├── docs/
│   └── README_Detailed.md       # Detailed documentation
├── examples/
│   └── *.png                    # Sample images
├── scripts/
│   ├── install.sh               # Setup helper
│   └── switch_device.sh         # Toggle CPU/CUDA/auto in config
├── tests/
│   ├── conftest.py              # Shared pytest fixtures
│   └── test_parking_detector.py # Unit tests
├── .github/workflows/ci.yml     # CI (pytest on Ubuntu)
├── requirements.txt
├── requirements-dev.txt         # pytest (local + CI)
├── pytest.ini
└── README.md

Quick start

1. Install dependencies

pip install -r requirements.txt

2. Run

cd src
python parking_detector.py

From the repository root you can also run: python src/parking_detector.py.

Tests

pip install -r requirements.txt -r requirements-dev.txt
pytest -v

Tests run on every push and pull request to main via GitHub Actions (see .github/workflows/ci.yml).

3. Video source

Edit video_path in src/parking_detector.py:

# Local file
video_path = '/path/to/your/video.mp4'

# Webcam
video_path = 0

# IP camera / MJPEG
video_path = 'http://your-camera-ip/stream'

4. Device settings (config/settings.json)

Auto (default):

{
  "device": "auto",
  "force_cpu": false
}

Force CPU:

{
  "device": "cpu",
  "force_cpu": true
}

Force CUDA:

{
  "device": "cuda",
  "force_cpu": false
}

Controls

Key	Action
D	Debug — click boxes to append their class IDs to tracked_objects
E	Edit — pick a space, then click four new corners
R	Delete — click a space to remove it
U	Toggle universal vs. cars-only (uses tracked_objects when off)
S	Save polygons to data/parking_spaces.json
C	Clear interaction modes and tracking caches
Q	Quit

Modes

1. Normal — click four corners per space; the polygon closes automatically after the fourth point.
2. Edit (E) — click inside a space to select it, then place four corners again.
3. Delete (R) — click inside a space to delete it.
4. Debug (D) — all detections drawn; click a box to track that class in debug-driven workflows.

Configuration (config/settings.json)

{
  "universal_detection": true,
  "occupancy_threshold": 0.6,
  "uncertainty_threshold": 0.3,
  "uncertainty_time_threshold": 3.0,
  "frequent_detection_threshold": 10,
  "frequent_detection_window": 10.0,
  "tracked_objects": [2, 67]
}

Field	Meaning
universal_detection	If true, use all detected classes; if false, only IDs in tracked_objects
occupancy_threshold	Min overlap ratio (0–1) for occupied
uncertainty_threshold	Lower bound for uncertain partial overlap
uncertainty_time_threshold	Seconds in uncertainty before probably occupied
frequent_detection_threshold	Hits needed inside the window for frequent state
frequent_detection_window	Sliding window (seconds) for frequent hits
tracked_objects	COCO class IDs when not in universal mode
force_cpu	Force CPU even if CUDA exists
device	"auto", "cuda", or "cpu"

Space states (overlay)

State	Color (BGR-style intent)	Meaning
Free	Green	Below uncertainty threshold
Occupied	Red	Above occupancy threshold
Uncertain	Yellow	Partial overlap, still stabilizing
Probably occupied	Orange-red	Uncertain long enough
Frequent	Magenta	Many partial hits in a short window

Requirements

Minimum: Python 3.8+, 4 GB RAM, OpenCV-capable environment.

Recommended: Python 3.9+, 8 GB+ RAM, NVIDIA GPU with CUDA for real-time HD streams.

Setup script

chmod +x scripts/install.sh
./scripts/install.sh

License

Apache License 2.0 — see the LICENSE file.

Version

v2.0 — Interactive editing, uncertainty / timing, and frequent-detection handling.

---

Tip: Stable lighting and a fixed camera angle improve overlap-based occupancy. Calibrate thresholds (occupancy_threshold, uncertainty_threshold) for your scene.

GitHub “About” metadata (copy-paste)

Repository description (short line for the GitHub About field):

Real-time parking occupancy monitor with YOLOv8, OpenCV, interactive polygons, uncertainty timing, and JSON configuration.

Suggested topics (add under repository Settings → General → Topics):

yolov8 ultralytics opencv pytorch computer-vision object-detection parking-detection real-time deep-learning python