lego-bricks-ml-vision 0.1.32
A package for LEGO brick detection and visualization using YOLO.
License: Apache License 2.0
Requires Python: >=3.8

# LEGO Bricks ML Vision

**LEGO Bricks ML Vision** es un paquete de Python diseÃ±ado para detectar y visualizar piezas de LEGO en imÃ¡genes usando YOLOv8 y pipelines personalizados. Este proyecto aborda el problema de identificar piezas individuales en entornos desordenados y proporciona herramientas de visualizaciÃ³n para anÃ¡lisis y presentaciones profesionales.

---

## **CaracterÃ­sticas Principales**

- **DetecciÃ³n de Objetos**: IdentificaciÃ³n de piezas de LEGO utilizando YOLOv8.
- **Preprocesamiento de Datos**: Herramientas para redimensionar imÃ¡genes y asegurar consistencia en los nombres de archivos.
- **ConversiÃ³n de Anotaciones**: TransformaciÃ³n de formatos de LabelMe a YOLO.
- **VisualizaciÃ³n**: GeneraciÃ³n de grids anotados, comparaciones y organizaciÃ³n de carpetas para presentaciones.
- **Pipeline Modular**: DiseÃ±o adaptable para escalabilidad y personalizaciÃ³n.

---

## **Requisitos del Sistema**

- **VersiÃ³n de Python**: >= 3.8
- **Sistemas Operativos Compatibles**: Windows, macOS, Linux
- **Hardware Recomendado**:
  - CPU (mÃ­nimo)
  - GPU (opcional, recomendado para entrenamiento)

---

## **InstalaciÃ³n**

1. Instala el paquete directamente desde PyPI:

   ```bash
   pip install lego-bricks-ml-vision
   ```

2. Alternativamente, clona el repositorio:

   ```bash
   git clone https://github.com/MiguelDiLalla/LEGO_Bricks_ML_Vision.git
   cd LEGO_Bricks_ML_Vision
   pip install -e .
   ```

---

## **Uso**

### ConfiguraciÃ³n del Entorno

Ejecuta el siguiente script para preparar el entorno:

```python
from scripts.pipeline import setup_environment
setup_environment()
```

### EjecuciÃ³n del Pipeline Principal

El pipeline principal realiza detecciÃ³n, preprocesamiento, entrenamiento y pruebas:

```bash
run-pipeline
```

### GeneraciÃ³n de Visualizaciones

Crea visualizaciones profesionales para anÃ¡lisis:

```bash
run-visualize
```

---

## **Detalles de Scripts y Funciones**

### **Pipeline Principal (`pipeline.py`)**

- `setup_environment()`: Configura el entorno necesario.
- `download_dataset_from_kaggle()`: Descarga y extrae datasets desde Kaggle.
- `preprocess_images()`: Redimensiona imÃ¡genes.
- `labelme_to_yolo()`: Convierte anotaciones LabelMe a formato YOLO.
- `train_yolo_pipeline()`: Entrena un modelo YOLO con datos procesados.
- `test_model_on_real_images()`: EvalÃºa el modelo entrenado en imÃ¡genes reales.
- `visualize_results()`: Genera un grid de imÃ¡genes anotadas.

### **VisualizaciÃ³n y Presentaciones (`visualize_presentation.py`)**

- `create_dataset_grid()`: Genera grids de imÃ¡genes del dataset.
- `annotate_model_results()`: Anota imÃ¡genes con resultados del modelo.
- `generate_comparison_grid()`: Crea comparaciones antes/despuÃ©s de la detecciÃ³n.
- `organize_presentation_folders()`: Organiza subcarpetas para presentaciones.

---

## **Ejemplos PrÃ¡cticos**

### Preprocesamiento de ImÃ¡genes

```python
from scripts.pipeline import preprocess_images
preprocess_images("datasets/raw", "datasets/processed")
```

### Entrenamiento de Modelo YOLO

```python
from scripts.pipeline import train_yolo_pipeline
train_yolo_pipeline("datasets", annotations_format="YOLO", epochs=50, img_size=256)
```

### GeneraciÃ³n de Grids

```python
from scripts.visualize_presentation import create_dataset_grid
create_dataset_grid("datasets/processed_images", "presentation/dataset_samples")
```

---

## **Estructura del Proyecto**

```
LEGO_Bricks_ML_Vision/
â”œâ”€â”€ data/              # Datos crudos y procesados
â”œâ”€â”€ scripts/           # Scripts principales
â”‚   â”œâ”€â”€ pipeline.py    # Pipeline de entrenamiento
â”‚   â”œâ”€â”€ visualize_presentation.py  # VisualizaciÃ³n y presentaciÃ³n
â”œâ”€â”€ presentation/      # Visualizaciones generadas
â”œâ”€â”€ requirements.txt   # Dependencias del proyecto
â”œâ”€â”€ setup.py           # ConfiguraciÃ³n del paquete
â”œâ”€â”€ README.md          # DocumentaciÃ³n del proyecto
```

---

## **Contribuciones**

Las contribuciones son bienvenidas. Sigue estos pasos:

1. Haz un fork del repositorio.
2. Crea una rama para tu contribuciÃ³n:

   ```bash
   git checkout -b feature/nueva-funcionalidad
   ```

3. EnvÃ­a un pull request explicando tus cambios.

---

## **Licencia**

Este proyecto estÃ¡ bajo la Licencia Apache 2.0.