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 y 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

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:

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

Abre 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. 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 ("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.