# Entrenamiento

Crea `modelos_entrenados/material_estado/` (material + estado) y calibra el conteo de SAM 3.

## Credenciales (una vez)

| Para | Qué hacer |
|---|---|
| Backbone DINOv3 y SAM 3 | Aceptar la licencia en [dinov3-convnext-tiny](https://huggingface.co/facebook/dinov3-convnext-tiny-pretrain-lvd1689m) y [sam3](https://huggingface.co/facebook/sam3); después `uv run hf auth login` |
| Datasets de Kaggle | Kaggle → Settings → API → *Create New Token*; guardar `kaggle.json` en `C:\Users\<usuario>\.kaggle\` |
| Datasets de Roboflow | Roboflow → Settings → API Keys; `setx ROBOFLOW_API_KEY "clave"` y abrir una terminal nueva |

Sin Kaggle o Roboflow el pipeline funciona igual con menos datos: esas fuentes se omiten
con aviso. Sin Roboflow no hay madera ni defectos, así que la nota de estado no se valida.

## Pasos

```bash
uv run python -m entrenamiento.descargar          # 1. datasets → datos/crudos/      (minutos)
uv run python -m entrenamiento.preparar           # 2. une, limpia y reparte         (minutos)
uv run python -m entrenamiento.caracteristicas    # 3. pasa cada foto por DINOv3     (horas en CPU, reanudable)
uv run python -m entrenamiento.entrenar           # 4. entrena las 2 cabezas y exporta (minutos)
uv run python -m entrenamiento.evaluar_conteo     # 5. mide y calibra el conteo de SAM 3 (~1 h)
```

El paso 4 escribe `modelos_entrenados/material_estado/informe.md` con las métricas sobre el
conjunto de prueba (fotos que el modelo nunca vio). El paso 5 escribe
`modelos_entrenados/conteo/informe.md` y el umbral elegido.

### Mejor precisión: ajuste fino completo en Colab (GPU gratis)

Los pasos 3-4 dejan el backbone congelado para que se pueda entrenar sin GPU. Ajustar
también el backbone suele mejorar varios puntos, sobre todo en defectos finos:

```bash
uv run python -m entrenamiento.empaquetar_colab   # → datos/revalora_colab.zip
```

Abre [colab_entrenamiento.ipynb](colab_entrenamiento.ipynb) en Google Colab, sube el zip y
ejecuta las celdas. Descarga `material_estado.zip` y sustituye `modelos_entrenados/material_estado/`.

## Datos

Las fuentes están en [fuentes.py](fuentes.py). **Solo se usan datasets con licencia que permite
uso comercial** (MIT, CC0, CC BY 4.0, ODbL); la licencia se comprueba al descargar y las fuentes
no comerciales se descartan. El resultado de cada fuente queda en `datos/procesados/fuentes.json`
y en la tabla final del informe.

| Tipo | Ejemplos | Qué enseña |
|---|---|---|
| Material | TrashNet, RealWaste, Garbage Classification | qué material es |
| Defectos | Roboflow: madera (Kodytek), óxido, telas, cajas dañadas, vidrio roto, abolladuras | qué defectos tiene |

Las etiquetas de cada dataset se traducen a nuestros defectos en [mapeo.py](mapeo.py)
("Dead_Knot" → nudo, "rust" → óxido, "non-damaged" → sin defectos...). Cada imagen solo enseña
los defectos que su dataset etiqueta; el resto no cuenta.

Para **añadir fotos propias** (lo que más mejora el modelo con fotos reales de la plataforma):
crea una carpeta por material con las fotos dentro, añádela a `fuentes.py` como fuente de
material con `origen="url"` o cópiala a `datos/crudos/<nombre>/` con un archivo `.completo`, y
repite los pasos 2-4.

## Decisiones

- **ConvNeXt-Tiny DINOv3** (Meta, 2025): misma red y velocidad que el ConvNeXt-Tiny original,
  con mejores pesos de partida. Licencia DINOv3 (uso comercial permitido, sin usos militares).
- **384 px**: deja ver defectos pequeños; ~0.4 s por imagen en CPU.
- **Características globales + máximo local**: el máximo conserva un defecto pequeño que el
  promedio diluiría.
- **Reparto por grupo**: las variantes aumentadas de una misma foto (Roboflow) nunca quedan a la
  vez en entrenamiento y en prueba.
- **Defectos sin datos suficientes** (< 30 ejemplos con y sin él) no se usan en la nota.