README.md

---
license: mit
base_model:
- Ultralytics/YOLOv8
tags:
- yolov8
- object-detection
- deep-learning
- computer-vision
- pretrained
---

# 📦 YOLOv8s - Modelo de Detección de Objetos

Este modelo está basado en **YOLOv8s**, entrenado específicamente para la detección de objetos en entornos urbanos y de tráfico. Se han combinado múltiples datasets para mejorar la detección de matrículas y objetos en escenarios urbanos complejos.

---

### 📂 Arquitectura del Proyecto
El modelo forma parte de un pipeline más amplio donde los videos son procesados en AWS. La arquitectura general es la siguiente:

![image/png](https://cdn-uploads.huggingface.co/production/uploads/66f1268bcaf696884799cb97/wTk0ygmkAy1CxRdcrU5PJ.png)

1. Los videos son enviados a un **bucket S3** desde una API.  
2. Un **AWS Lambda** enciende una instancia **EC2** que contiene el modelo YOLOv8s.  
3. La EC2 procesa el video y envía los resultados a **DynamoDB**.  
4. Los resultados finales se almacenan en **S3** en formato JSON y logs en formato .log.  
5. DynamoDB indexa la información con claves secundarias globales (GSI).  
6. Cuando el proceso finaliza, una **segunda Lambda** apaga la instancia EC2.  

---

### 📊 Datasets Utilizados
Para entrenar el modelo, se ha utilizado el dataset de **COCO8**, pero también es posible añadir otros datasets como **License Plate Recognition** o **Shahbagh Traffic Dataset**:

- **COCO8** - versión reducida de COCO para pruebas rápidas.  
- **License Plate Recognition** - para mejorar la detección de matrículas.  
- **Shahbagh Traffic Dataset** - dataset específico para escenas de tráfico.  

---

### ⚙ **Configuración del Entorno**
Para garantizar un entrenamiento sin problemas, es importante configurar correctamente el entorno. Se recomienda usar un entorno virtual de Python y asegurarse de que todas las dependencias necesarias estén instaladas.

#### **1️⃣ Crear y activar un entorno virtual (opcional pero recomendado)**  
```bash
# Crear el entorno virtual
python -m venv .venv  

# Activar el entorno virtual  
# En Linux/macOS  
source .venv/bin/activate  

# En Windows (cmd o PowerShell)  
.venv\Scripts\activate  
```

#### **2️⃣ Instalar las dependencias necesarias**  
```bash
pip install -r requirements.txt
```

o también

```bash
pip install ultralytics roboflow
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu  # Cambiar a cu121 si se usa GPU con CUDA 12.1
```

---

#### **3️⃣ Descargar los datasets**
Si utilizas el **dataset de COCO8**, puedes descargarlo con el siguiente código:

```python
from ultralytics.utils.downloads import download

# Descargar el dataset COCO8 en formato YOLO
download('https://ultralytics.com/assets/coco8.zip', dir='datasets')
```

Si utilizas los **datasets de Roboflow**, puedes descargarlos con el siguiente código: 

```python
from roboflow import Roboflow

# Configurar la API Key
rf = Roboflow(api_key="TU_API_KEY")

# Cargar el dataset desde Roboflow Universe
project = rf.workspace("shovonthesis").project("shahbagh-g7vmy")

# Seleccionar la versión 4 del dataset (según la URL)
version = project.version(4)

# Descargar el dataset en formato YOLOv8
dataset_path = version.download("yolov8")

print(f"✅ Dataset descargado en: {dataset_path}")
```

### 🔹 **Observaciones**
Para descargar los datasets de Roboflow mediante código es necesario la Private API Key que se encuentra en **Settings > APi Keys** de tu cuenta de Roboflow.

# `rf.workspace("license-project")`
- `rf` es un objeto de la clase **Roboflow** que hemos inicializado con nuestra **API Key**.
- `.workspace("shovonthesis")` selecciona el espacio de trabajo llamado `"shovonthesis"`, que es donde está almacenado el dataset dentro de **Roboflow**.

# `.project("license-plate-detection-project")`
- Dentro del espacio de trabajo `"shovonthesis"`, buscamos el dataset con el identificador `"shahbagh-g7vmy"`.
- `project` ahora representa este dataset específico y nos permitirá **acceder a sus versiones, descargarlo o gestionarlo**.
- Una vez esto este configurado solo nos quedará seleccionar la versión que queremos del dataset y ejecutarlo.

---

### ⚙ **Configuración del Entrenamiento**
El modelo fue entrenado utilizando **YOLOv8s** con los siguientes parámetros:

```python
from ultralytics import YOLO

# Cargar el modelo YOLOv8s preentrenado
model = YOLO("yolov8s.pt")

# Entrenar el modelo
model.train(
    data="/home/USER/yolo/yolov8-object-detection/datasets/combined/data.yaml",
    epochs=150,
    batch=8,
    imgsz=640,
    device='cpu',  # Cambiar a 'cuda' si hay GPU disponible
    project="/home/USER/yolo/yolov8-object-detection/runs/detect",
    name="train_yolov8s",
    exist_ok=True,
    patience=200,
    lr0=0.01,
    momentum=0.937,
    weight_decay=0.0005
)
```

---

### ✅ **Validación del Modelo**
Después del entrenamiento, validamos el modelo con el siguiente código:

```python
from ultralytics import YOLO

# Cargar el modelo entrenado
model = YOLO("/home/USER/yolo/yolov8-object-detection/runs/detect/train_yolov8s/weights/best.pt")

# Validar el modelo y guardar los resultados
metrics = model.val(
    data="/home/USER/yolo/yolov8-object-detection/datasets/combined/data.yaml",
    project="/home/USER/yolo/yolov8-object-detection/runs/val",
    name="val",
    exist_ok=True
)

print(metrics)
```

### 🔹 **Recomendación**
Primeramente descarga el dataset de **COCO8** para que genere la estructura correcta de los archivos para incluir los demás datasets.

*Para juntar varios datasets habrá que hacerlo manualmente o mediante un codigo de python que añada las imágenes y labels a sus carpetas correspondientes.*

---

### 💻 **Uso del Modelo en Videos**
Para aplicar el modelo a un video y detectar objetos:

```python
from ultralytics import YOLO

# Cargar el modelo entrenado
model = YOLO("runs/detect/train_yolov8s/weights/best.pt")

# Realizar inferencia en un video
results = model.predict("ruta/video.mp4", save=True, conf=0.5)

# Guardar el video con las detecciones
print("✅ Procesamiento completado. Video guardado.")
```

---

### 📂 Estructura del Proyecto YOLOv8

```bash
.
├── .venv/                        # Entorno
├── datasets/                     # Carpeta de datasets
│   ├── coco8/                    # Dataset COCO8
│   ├── yolov8s.pt                # Pesos preentrenados de YOLOv8s
├── datasets-download/            # Descargas de datasets
├── processed-video/              # Vídeos procesados
│   ├── ny-traffic-processed.mp4  # Vídeo de tráfico procesado
├── raw-video/                    # Vídeos sin procesar
│   ├── ny-traffic.mp4            # Vídeo de tráfico original
├── runs/                         # Resultados de entrenamiento y validación
│   ├── detect/                   # Carpeta de detección de objetos
│   │   ├── train_coco8           # Entrenamiento con COCO8
│   │   ├── train_yolov8n         # Entrenamiento con YOLOv8n
│   ├── val/                      # Resultados de validación
│   │   ├── val_coco8/            # Resultados de validación con gráficas relevantes
│   │   ├── best.pt               # Mejor peso del modelo YOLOv8s entrenado con COCO8
│   │   ├── last.pt               # Último peso del modelo YOLOv8s entrenado con COCO8
├── .gitattributes                # Configuración de atributos de Git
├── .gitignore                    # Ignorar archivos innecesarios en Git
├── predict.py                    # Script para realizar predicciones a los vídeos
├── requirements.txt              # Dependencias del proyecto
├── train_yolov8n.py              # Script para entrenar YOLOv8n
├── train_yolov8s.py              # Script para entrenar YOLOv8s
├── validate.py                   # Script para validar el modelo
├── yolov8n.pt                    # Pesos del modelo YOLOv8n
```

---

### 📊 **Resultados y Gráficos**

#### Comparación General de Resultados entre YOLOv8n y YOLOv8s

| **Métrica**        | **YOLOv8n** | **YOLOv8s** | **Diferencia (YOLOv8s - YOLOv8n)** |
|--------------------|------------|------------|----------------------------------|
| **Precisión (B)**  | 0.748      | 0.821      | +0.073                          |
| **Recall (B)**     | 0.561      | 0.920      | +0.359                          |
| **mAP@50 (B)**     | 0.645      | 0.944      | +0.299                          |
| **mAP@50-95 (B)**  | 0.431      | 0.726      | +0.295                          |
| **Fitness**        | 0.453      | 0.747      | +0.294                          |

#### 📌 Análisis:
- **Precisión**: YOLOv8s tiene mejor precisión (**+7.3%**), lo que significa que el modelo comete menos falsos positivos.
- **Recall**: YOLOv8s tiene un recall significativamente mayor (**+35.9%**), indicando que detecta más objetos correctamente.
- **mAP@50**: YOLOv8s supera a YOLOv8n en un **30%**, lo que sugiere que el modelo más grande tiene una mejor capacidad para detectar objetos con alta confianza.
- **mAP@50-95**: También mejora en un **29.5%**, lo que significa que tiene un rendimiento más consistente en diferentes umbrales de IoU.
- **Fitness**: YOLOv8s tiene una mejora notable (**+29.4%**), lo que indica un mejor balance entre precisión y recall.

---

#### Comparación de Velocidad

| **Parámetro**       | **YOLOv8n** | **YOLOv8s** | **Diferencia**  |
|---------------------|------------|------------|----------------|
| **Preprocesamiento** | 1.92 ms    | 1.68 ms    | -0.24 ms       |
| **Inferencia**      | 55.05 ms   | 128.99 ms  | +73.94 ms      |
| **Postprocesamiento** | 1.22 ms    | 0.91 ms    | -0.31 ms       |

#### 📌 Análisis:
- **Preprocesamiento**: Similar en ambos modelos.
- **Inferencia**: **YOLOv8s es mucho más lento** en inferencia (**+74 ms**), lo cual es esperable ya que es un modelo más grande.
- **Postprocesamiento**: Ligeramente más rápido en **YOLOv8s**, pero la diferencia no es significativa.

---
### 🔍 YOLOv8n vs YOLOv8s

#### Comparación de Métricas

![image/png](https://cdn-uploads.huggingface.co/production/uploads/66f1268bcaf696884799cb97/-TvkHPXa8E4AbB9h_sesd.png)

#### 📌 Análisis:
- YOLOv8s supera en todas las métricas a YOLOv8n.
- La mayor diferencia se observa en **Recall (+35.9%)** y **mAP@50-95 (+29.5%)**, indicando una mejor detección a diferentes umbrales de IoU.
- Aunque YOLOv8s tiene mejor rendimiento, su velocidad de inferencia es más lenta.

---

#### Evolución de la Función de Pérdida por Época

![image/png](https://cdn-uploads.huggingface.co/production/uploads/66f1268bcaf696884799cb97/w8fqST_MaK-jjS8xeRzTd.png)

#### 📌 Análisis:
- Ambos modelos muestran una disminución de la pérdida a lo largo del entrenamiento.
- **YOLOv8s** comienza con una pérdida mayor pero converge bien, sugiriendo que aprende mejor con más iteraciones.
- **YOLOv8n** tiene una convergencia más rápida pero con menor precisión general.

---

#### Curva de Precisión-Recall

![image/png](https://cdn-uploads.huggingface.co/production/uploads/66f1268bcaf696884799cb97/kgiCT9F4pKS43h0Ym8OrK.png)

#### 📌 Análisis:
- **YOLOv8s** mantiene una precisión más alta en todos los valores de recall, lo que significa menos falsos positivos en comparación con YOLOv8n.
- **YOLOv8n** muestra más fluctuaciones en la curva, indicando menor estabilidad en la detección de objetos.

---

#### Matriz de Confusión

![image/png](https://cdn-uploads.huggingface.co/production/uploads/66f1268bcaf696884799cb97/6EG6ybWD9ZqdNoabfruPf.png)

#### 📌 Análisis:
- Ambas matrices muestran que algunos objetos están siendo confundidos entre sí.
- **YOLOv8s** presenta menos errores de clasificación en comparación con YOLOv8n.
- La normalización de la matriz confirma que YOLOv8s tiene una mejor distribución de predicciones.

---

#### Ejemplo de Detección

![image/jpeg](https://cdn-uploads.huggingface.co/production/uploads/66f1268bcaf696884799cb97/tenTgxyadyFDm_rwxfKiW.jpeg)

---