Model card and verified loader (pin_classifier.py)
Browse files- README.md +92 -0
- pin_classifier.py +70 -0
README.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
library_name: pytorch
|
| 3 |
+
tags:
|
| 4 |
+
- image-classification
|
| 5 |
+
- robotics
|
| 6 |
+
- so101
|
| 7 |
+
- pin-inspection
|
| 8 |
+
pipeline_tag: image-classification
|
| 9 |
+
---
|
| 10 |
+
|
| 11 |
+
# Pin classifier — clasificador de pieza con perno / sin perno (SO-101)
|
| 12 |
+
|
| 13 |
+
**Mira la pieza que sostiene el brazo, con la cámara frontal y la de muñeca, y decide si tiene perno (`pin`) o no
|
| 14 |
+
(`nopin`).** Es la etapa de inspección del sistema. Hoy su veredicto decide a qué caja va la pieza, aunque en el futuro
|
| 15 |
+
podrá elegirlo el operario.
|
| 16 |
+
|
| 17 |
+
```
|
| 18 |
+
Pick (act-pick) → pieza delante de la cámara → ESTE CLASIFICADOR (pin / nopin) → selector de destino → Up-down GOOD | Up-down BAD
|
| 19 |
+
```
|
| 20 |
+
|
| 21 |
+
Relacionados: [`act-pick`](https://huggingface.co/MikelRubi/act-pick),
|
| 22 |
+
[`act-up-down-good`](https://huggingface.co/MikelRubi/act-up-down-good) y
|
| 23 |
+
[`act-up-down-bad`](https://huggingface.co/MikelRubi/act-up-down-bad).
|
| 24 |
+
|
| 25 |
+
## Modelo
|
| 26 |
+
|
| 27 |
+
| | |
|
| 28 |
+
|---|---|
|
| 29 |
+
| **Archivo** | `model.pt` |
|
| 30 |
+
| **Arquitectura** | EfficientNet-B0 preentrenada en ImageNet (4,0 M de parámetros), **compartida por las dos cámaras**. Por cada cámara se calculan el promedio y el máximo del mapa de características; se concatenan (front y luego wrist, 5120 valores) y una capa lineal da las 2 clases |
|
| 31 |
+
| **Entrada** | Dos imágenes RGB, `front` y `wrist`, recortadas al centro a 4:3 (sin deformar) y redimensionadas a 448×336. La normalización ImageNet va dentro del modelo |
|
| 32 |
+
| **Salida** | `nopin` / `pin` y la probabilidad de `pin` |
|
| 33 |
+
| **Precisión** | **≈ 85 %** en sesiones de grabación no vistas (validación cruzada por sesiones). Referencia de la clase mayoritaria: 52 % |
|
| 34 |
+
| **Ojo** | Medido en la misma sala, con el mismo operario y la misma luz que el entrenamiento. No se ha probado otro día, con otra iluminación ni con otro lote de piezas |
|
| 35 |
+
|
| 36 |
+
## Uso
|
| 37 |
+
|
| 38 |
+
```python
|
| 39 |
+
from pin_classifier import load_model, predict # pin_classifier.py está en este repo
|
| 40 |
+
model = load_model("model.pt") # torch, torchvision, numpy y Pillow
|
| 41 |
+
label, p_pin = predict(model, front_rgb, wrist_rgb) # arrays HxWx3 uint8 en RGB, de cualquier tamaño
|
| 42 |
+
```
|
| 43 |
+
|
| 44 |
+
`pin_classifier.py` reconstruye la arquitectura y carga los pesos en modo estricto. Se comprobó con los 110 pares de
|
| 45 |
+
fotos etiquetadas de `so101-pick-cube_20261024_115532/pin_snapshots`: clasifica bien los 110, como debe pasar, porque esas
|
| 46 |
+
fotos forman parte del entrenamiento. Con las cámaras en el orden inverso, el acierto baja al 56–66 %; el orden importa.
|
| 47 |
+
|
| 48 |
+
## Datos
|
| 49 |
+
|
| 50 |
+
1004 pares front+wrist de las grabaciones `MikelRubi/so101-pick-cube_*` (23 y 24 de octubre):
|
| 51 |
+
- **654 pares** de los últimos 3 frames de 218 episodios de pick (112 `pin`, 106 `nopin`), etiquetados a ojo. 16 de los
|
| 52 |
+
`pin` y 72 de los `nopin` son «moderados» (vista borrosa o parcial). Se descartaron 39 episodios ambiguos y 5 sin pieza.
|
| 53 |
+
- **350 pares** de fotos tomadas a propósito (186 `pin`, 164 `nopin`), guardadas en la carpeta `pin_snapshots/` de cada
|
| 54 |
+
dataset.
|
| 55 |
+
|
| 56 |
+
**Entrenamiento:** 25 épocas, entropía cruzada con pesos por clase, AdamW y OneCycle (el backbone a una décima de la tasa
|
| 57 |
+
de la cabeza), y aumentos fuertes: rotación, zoom, desplazamiento, volteo, saturación y balance de blancos, desenfoque y
|
| 58 |
+
ruido.
|
| 59 |
+
|
| 60 |
+
## Resultados (validación cruzada de 5 particiones; cada partición aparta sesiones de grabación completas)
|
| 61 |
+
|
| 62 |
+
| Subconjunto | n | Precisión | Clase mayoritaria |
|
| 63 |
+
|---|---|---|---|
|
| 64 |
+
| Todos los pares | 1004 | **0,85** | 0,52 |
|
| 65 |
+
| Últimos frames de episodios | 654 | 0,87 | 0,51 |
|
| 66 |
+
| Fotos tomadas a propósito | 350 | 0,83 | 0,53 |
|
| 67 |
+
| Por episodio | 568 | 0,84 | 0,52 |
|
| 68 |
+
| Por episodio, solo etiquetas claras | 480 | 0,84 | 0,59 |
|
| 69 |
+
|
| 70 |
+
Por partición: 0,76 · 0,85 · 1,00 · 0,88 · 0,88. El `model.pt` de este repo está entrenado con todos los datos, así que
|
| 71 |
+
estas cifras salen de los cinco modelos de la validación cruzada y no de él mismo (`metrics.json`: precisión en
|
| 72 |
+
entrenamiento 0,998). Las etiquetas son un juicio visual, no una verdad absoluta.
|
| 73 |
+
|
| 74 |
+
**Otras arquitecturas probadas:**
|
| 75 |
+
|
| 76 |
+
| Arquitectura | Precisión |
|
| 77 |
+
|---|---|
|
| 78 |
+
| ResNet18 a 448×336 | 0,85 en todos los pares, 0,82 por episodio |
|
| 79 |
+
| CNN pequeña entrenada desde cero | 0,55 (azar) |
|
| 80 |
+
| ResNet18 con menos datos | 0,66 (627 pares) y 0,81 (905 pares) |
|
| 81 |
+
|
| 82 |
+
Lo que más influyó fue tener más datos, partir de pesos preentrenados y usar más resolución.
|
| 83 |
+
|
| 84 |
+
## Archivos
|
| 85 |
+
|
| 86 |
+
- `model.pt`: diccionario con `state_dict`, `classes`, `height`, `width`, `backbone`, `cameras` y `channels`.
|
| 87 |
+
- `pin_classifier.py`: carga e inferencia.
|
| 88 |
+
- `metrics.json`: informe del entrenamiento final.
|
| 89 |
+
- `model_card_original.md`: la ficha original del autor.
|
| 90 |
+
|
| 91 |
+
Modelo entrenado por Iker Azurmendi (`IkerAzurmendi/pin_classifier_so101`; `IkerAzurmendi/pin-classifier` contiene el
|
| 92 |
+
mismo `model.pt`).
|
pin_classifier.py
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Load and run the pin / no-pin classifier (front + wrist cameras, shared EfficientNet-B0).
|
| 2 |
+
|
| 3 |
+
from pin_classifier import load_model, predict
|
| 4 |
+
model = load_model("model.pt")
|
| 5 |
+
label, p_pin = predict(model, front_rgb, wrist_rgb) # HxWx3 uint8 RGB arrays (any size)
|
| 6 |
+
|
| 7 |
+
Only needs torch, torchvision, numpy and Pillow.
|
| 8 |
+
"""
|
| 9 |
+
from __future__ import annotations
|
| 10 |
+
|
| 11 |
+
import numpy as np
|
| 12 |
+
import torch
|
| 13 |
+
from PIL import Image
|
| 14 |
+
from torch import nn
|
| 15 |
+
from torchvision.models import efficientnet_b0
|
| 16 |
+
|
| 17 |
+
CAMERA_ORDER = ("front", "wrist") # order in which the two cameras' features are concatenated
|
| 18 |
+
POOL_ORDER = ("mean", "max") # order of the two global poolings per camera
|
| 19 |
+
|
| 20 |
+
|
| 21 |
+
class PinClassifier(nn.Module):
|
| 22 |
+
def __init__(self, classes, height, width):
|
| 23 |
+
super().__init__()
|
| 24 |
+
self.classes, self.height, self.width = list(classes), height, width
|
| 25 |
+
self.register_buffer("mean", torch.zeros(1, 3, 1, 1))
|
| 26 |
+
self.register_buffer("std", torch.ones(1, 3, 1, 1))
|
| 27 |
+
self.backbone = efficientnet_b0(weights=None).features
|
| 28 |
+
self.head = nn.Sequential(nn.Dropout(0.0), nn.Linear(2 * 2 * 1280, len(self.classes)))
|
| 29 |
+
|
| 30 |
+
def embed(self, x: torch.Tensor) -> torch.Tensor:
|
| 31 |
+
f = self.backbone((x - self.mean) / self.std)
|
| 32 |
+
pooled = {"mean": f.mean(dim=(2, 3)), "max": f.amax(dim=(2, 3))}
|
| 33 |
+
return torch.cat([pooled[p] for p in POOL_ORDER], dim=1)
|
| 34 |
+
|
| 35 |
+
def forward(self, front: torch.Tensor, wrist: torch.Tensor) -> torch.Tensor:
|
| 36 |
+
views = {"front": front, "wrist": wrist}
|
| 37 |
+
return self.head(torch.cat([self.embed(views[c]) for c in CAMERA_ORDER], dim=1))
|
| 38 |
+
|
| 39 |
+
|
| 40 |
+
def load_model(path: str, device: str = "cpu") -> PinClassifier:
|
| 41 |
+
ckpt = torch.load(path, map_location="cpu", weights_only=False)
|
| 42 |
+
assert ckpt.get("backbone") == "efficientnet_b0" and ckpt.get("cameras") == "both", "unexpected checkpoint"
|
| 43 |
+
model = PinClassifier(ckpt["classes"], ckpt["height"], ckpt["width"])
|
| 44 |
+
state = ckpt["state_dict"]
|
| 45 |
+
model.mean.resize_as_(state["mean"]); model.std.resize_as_(state["std"])
|
| 46 |
+
model.load_state_dict(state, strict=True)
|
| 47 |
+
return model.to(device).eval()
|
| 48 |
+
|
| 49 |
+
|
| 50 |
+
def to_tensor(rgb: np.ndarray, width: int, height: int) -> torch.Tensor:
|
| 51 |
+
"""Centre-crop to the model's aspect ratio (never stretch), resize, scale to [0, 1]."""
|
| 52 |
+
image = Image.fromarray(rgb)
|
| 53 |
+
w, h = image.size
|
| 54 |
+
target = width / height
|
| 55 |
+
if w / h > target:
|
| 56 |
+
cw = round(h * target); image = image.crop(((w - cw) // 2, 0, (w - cw) // 2 + cw, h))
|
| 57 |
+
else:
|
| 58 |
+
ch = round(w / target); image = image.crop((0, (h - ch) // 2, w, (h - ch) // 2 + ch))
|
| 59 |
+
image = image.resize((width, height), Image.BILINEAR)
|
| 60 |
+
return torch.from_numpy(np.asarray(image, dtype=np.float32) / 255.0).permute(2, 0, 1).unsqueeze(0)
|
| 61 |
+
|
| 62 |
+
|
| 63 |
+
@torch.no_grad()
|
| 64 |
+
def predict(model: PinClassifier, front_rgb: np.ndarray, wrist_rgb: np.ndarray) -> tuple[str, float]:
|
| 65 |
+
device = next(model.parameters()).device
|
| 66 |
+
front = to_tensor(front_rgb, model.width, model.height).to(device)
|
| 67 |
+
wrist = to_tensor(wrist_rgb, model.width, model.height).to(device)
|
| 68 |
+
probs = model(front, wrist).softmax(dim=1)[0]
|
| 69 |
+
index = int(probs.argmax())
|
| 70 |
+
return model.classes[index], float(probs[model.classes.index("pin")])
|