update readme

README.md

@@ -0,0 +1,306 @@
+---
+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)
+
+---