🚗 Vehicle_MEX_Model — Clasificación de vehículos

📌 Descripción general

Este repositorio documenta el entrenamiento de un modelo baseline para clasificación de vehículos (grano fino) usando Ultralytics YOLO (modo classify) sobre el dataset Vehicle_MEX_Dataset.
Incluye scripts reproducibles, notebooks de aumento de datos, métricas y visualizaciones (sin subir el dataset completo de imágenes).

📦 Dataset

• Dataset original (descarga): https://data.mendeley.com/datasets/gbk6gnv245/1
• Estructura esperada para YOLO-CLS:

Vehicle_classification.v1/
├── train/
│   ├── B2/
│   ├── B3/
│   └── ...
├── valid/
│   ├── B2/
│   ├── B3/
│   └── ...
└── test/
    ├── B2/
    ├── B3/
    └── ...

🎯 Objetivos

• ✅ Entrenar un baseline reproducible para clasificación de vehículos.
• ✅ Identificar errores por clase usando matriz de confusión.
• ✅ Proponer y ejecutar mejoras con regularización y aumento de datos.
• ✅ Preparar un flujo opcional de búsqueda de hiperparámetros (HPO) para acelerar la convergencia y mejorar precisión.

🧠 Método (Pipeline de entrenamiento)

Etapas del flujo:

1. Preprocesamiento y balanceo con notebooks/Data_augmenter.ipynb
2. Entrenamiento con YOLO-CLS (Ultralytics)
3. Validación y análisis (matrices de confusión + curvas de entrenamiento)
4. Ajustes manuales e iteración
5. (Opcional) HPO con Ray Tune + Optuna para encontrar mejores hiperparámetros

🧾 Pesos del modelo (descarga e inferencia)

Este repositorio incluye el archivo de pesos entrenados listo para su descarga:

• weights/best.pt

📥 Obtener los pesos

• Opción A (recomendado): clonar el repo

git clone <TU_URL_DE_GITHUB>/Vehicle_MEX_Model.git
cd Vehicle_MEX_Model

• Opción B: descarga directa desde GitHub

1. Abre weights/best.pt en GitHub
2. Descarga con el botón de descarga o usa el enlace raw (ejemplo):

https://raw.githubusercontent.com/<TU_USUARIO>/Vehicle_MEX_Model/main/weights/best.pt

🧪 Cargar pesos y ejecutar inferencia (Python)

from ultralytics import YOLO

model = YOLO("weights/best.pt")
pred = model.predict(source="ruta/a/imagen.jpg", imgsz=640)

🧪 Inferencia (CLI)

yolo classify predict model=weights/best.pt source="ruta/a/imagen.jpg" imgsz=640

📈 Resultados (Improvement_1 — Mejor modelo)

Métricas reportadas para el modelo entrenado (weights/best.pt):

Metric	Value
Fitness	0.9668674468994141
Top-1 Accuracy	0.9373493790626526
Top-5 Accuracy	0.9963855147361755

🔎 Confusion Matrix

🎞️ Demo (lotes de entrenamiento)

🧩 Estructura del proyecto

Vehicle_MEX_Model/
├── assets/                      # Imágenes/GIF ligeros para README (no dataset completo)
├── configs/                     # Configuraciones usadas en entrenamientos
├── notebooks/                   # Notebooks de análisis/augmentación
├── results/                     # Curvas, matrices, logs, CSV de resultados
├── weights/                     # Pesos del modelo entrenado (best.pt)
├── scripts/                     # Scripts de entrenamiento y HPO
├── requirements.txt
├── .gitignore
└── README.md

🛠️ Instalación

1) Clonar

git clone <TU_URL_DE_GITHUB>/Vehicle_MEX_Model.git
cd Vehicle_MEX_Model

2) Crear entorno (recomendado)

python -m venv .venv

Windows

.venv\Scripts\activate

Linux/Mac

source .venv/bin/activate

3) Instalar dependencias

pip install -r requirements.txt

🚀 Entrenamiento

Script principal:

• scripts/1_Classification.py

Ejemplo:

python scripts/1_Classification.py

🧪 Aumento y balanceo del dataset

Notebook:

• notebooks/Data_augmenter.ipynb

Incluye:

• selector de carpetas (local)
• análisis automático de desbalance por clase
• previsualización de augmentations
• exportación a estructura YOLO-CLS con imágenes 640x640 (padding + Lanczos)

✨ Características principales

• 🧱 Reproducibilidad: logs + configs (configs/, results/)
• 🧰 Aumentos realistas orientados a vehículos (rotación leve, perspectiva, brillo/contraste, ruido)
• 🧯 Regularización agresiva (dropout, weight decay, warmup)
• 🧪 HPO opcional con Ray Tune + Optuna

🧾 Especificaciones técnicas

• Framework: Ultralytics YOLO (classification)
• Input: 640×640 (con padding para conservar proporciones)
• Optimizer: AdamW
• Scheduler: Cosine LR (si se habilita en los scripts)

🏙️ Aplicaciones

• 🚦 Clasificación automática de tipos de vehículos en escenarios urbanos y carreteros
• 🛣️ Analítica de tráfico por categoría
• 🧾 Inventario vehicular y monitoreo en infraestructura
• 🔍 Soporte a sistemas ITS (Intelligent Transportation Systems)

🧑‍🔬 Research Team

Photo	Investigador(a)	Afiliación	Contacto
	Dr. José Alberto Guzmán Torres 🇲🇽 Aplicaciones de ingeniería e inteligencia artificial
	Dr. Francisco Javier Domínguez Mota 🇲🇽 Matemática aplicada y métodos de diferencias finitas
	Dra. Elia M. Alonso Guzmán 🇲🇽 Ingeniería civil y ciencia de materiales
	Dr. Gerardo Tinoco Guerrero 🇲🇽 Métodos numéricos y matemática computacional
	Dr. Wilfrido Martínez Molina 🇲🇽 Ingeniería civil y ciencia de materiales
	Dr. Heriberto Árias Rojas 🇲🇽 Aplicaciones de ingeniería

⚖️ Licencia

Licencia MIT. Ver LICENSE.