Computer Vision Object Detection Lab

Un proyecto de computer vision que detecta objetos cotidianos en imágenes, videos y streams de webcam en tiempo real usando YOLOv8, OpenCV y Streamlit.

---

Demo Preview

Real-Time Object Detection

Analytics Dashboard

Detection Metrics

---

Descripción General

Este proyecto implementa un pipeline completo de object detection basado en el modelo pretrained YOLOv8 de Ultralytics, entrenado sobre el dataset COCO (80 clases). Incluye scripts para image detection, webcam detection y video detection, un dashboard interactivo con Streamlit, un sistema de metrics, seguimiento de objetos por centroide y utilidades para dataset management y fine-tuning opcional.

---

Características Principales

• Image detection — anota una foto y exporta los resultados en CSV + JSON
• Video detection — procesamiento frame a frame con video de salida anotado
• Webcam detection — inference en tiempo real con contador de FPS (Q = salir, S = guardar frame, P = pausa)
• Object tracking — IDs persistentes por centroide a través de frames consecutivos
• Metrics engine — total de detections, distribución por clase, estadísticas de confidence score, series temporales
• Streamlit dashboard — gráficos interactivos, filtros y UI de subida de imágenes con detección en el navegador
• Dataset utilities — descargador de subconjunto COCO, divisor train/val/test, generador de data.yaml
• Training opcional — fine-tune YOLOv8 sobre un dataset personalizado con un solo comando
• Test suite — cobertura con pytest para detection, metrics y utilidades

---

Objetos Objetivo

Objeto	Clase COCO	Detectado con modelo pretrained
Teléfono celular	cell phone	Sí
Botella	bottle	Sí
Taza	cup	Sí
Laptop	laptop	Sí
Teclado	keyboard	Sí
Mouse	mouse	Sí
Mochila	backpack	Sí
Libro	book	Sí
Auriculares	—	Requiere training personalizado

---

Tech Stack

Componente	Librería
Object detection	Ultralytics YOLOv8
Imagen / video / webcam	OpenCV
Dashboard	Streamlit
Manejo de datos	Pandas
Configuración	PyYAML + python-dotenv
Gráficos	Plotly + Matplotlib
Testing	pytest
Barras de progreso	tqdm + Rich

---

Arquitectura

El proyecto sigue una estructura modular con separación clara de responsabilidades:

computer-vision-object-detection-lab/
│
├── configs/                   Archivos de configuración YAML
│   ├── app_config.yaml        Rutas, umbrales, configuración de webcam
│   └── model_config.yaml      Nombres de modelos, parámetros de inference y training
│
├── data/
│   ├── raw/                   Imágenes y etiquetas descargadas sin procesar
│   ├── processed/             Splits train/val/test en formato YOLO
│   ├── samples/               Imágenes de demostración pequeñas
│  
│
├── models/
│   ├── pretrained/            Caché de pesos YOLO descargados automáticamente
│   └── trained/               Outputs de modelos fine-tuned personalizados
│
├── outputs/
│   ├── images/                Imágenes de salida anotadas
│   ├── videos/                Videos de salida anotados
│   ├── detections/            Logs de detección en CSV + JSON
│   └── reports/               Reportes de evaluation metrics
│
├── notebooks/
│   └── exploration.ipynb      Notebook interactivo de exploración
│
├── src/
│   ├── config/settings.py     Cargador de configuración tipado (dataclasses)
│   ├── data/dataset_utils.py  Helpers para datasets en formato YOLO
│   ├── detection/
│   │   ├── detector.py        Clase YOLODetector + DetectionResult
│   │   └── postprocessing.py  Filtrado, append a CSV, conversión a DataFrame
│   ├── tracking/tracker.py    Object tracker basado en centroide
│   ├── metrics/metrics.py     Clase DetectionMetrics de agregación
│   ├── visualization/         Constructores de gráficos Matplotlib + Plotly
│   ├── dashboard/app.py       Dashboard multipágina con Streamlit
│   └── utils/                 Logger, utilidades de archivos
│
├── scripts/
│   ├── run_image_detection.py
│   ├── run_webcam_detection.py
│   ├── run_video_detection.py
│   ├── download_dataset.py
│   ├── prepare_dataset.py
│   ├── train_model.py
│   └── evaluate_model.py
│
└── tests/
    ├── test_detector.py
    ├── test_metrics.py
    └── test_utils.py

Flujo de datos:

Imagen / Video / Webcam
        │
        ▼
  YOLODetector.detect()
        │
        ▼
  Lista de DetectionResult
        │
   ┌────┴────┐
   ▼         ▼
CSV/JSON   Imagen anotada
   │
   ▼
DetectionMetrics → Streamlit Dashboard

---

Páginas del dashboard:

• Dashboard — gráficos y tablas a partir de todos los CSV en outputs/detections/
• Live Detection (Upload) — sube una imagen y ejecuta detección directamente en el navegador
• About — descripción del proyecto y comandos de inicio rápido

---

Exploración con Jupyter Notebook

jupyter notebook notebooks/exploration.ipynb

El notebook incluye:

• Carga de configuración e inicialización del detector
• Detección sobre una imagen de muestra
• Visualización de la imagen anotada con bounding boxes
• Análisis de CSVs de detecciones guardadas
• Cálculo de metrics por clase
• Gráficos de distribución y confidence

---

Licencia

Este proyecto se publica bajo la Licencia MIT. Los pesos del modelo YOLOv8 están sujetos a la Ultralytics YOLO License. Las anotaciones del dataset COCO están bajo CC BY 4.0.

---

Construido con Ultralytics YOLOv8, OpenCV, Streamlit y Pandas.