MikelRubi commited on
Commit
6ff46b0
·
verified ·
1 Parent(s): 6c4f5e4

Model card and verified loader (pin_classifier.py)

Browse files
Files changed (2) hide show
  1. README.md +92 -0
  2. 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")])