Hace un tiempo os hablé de Makespace Madrid, la asociación maker de Tetuán donde paso buena parte de mi tiempo libre. Uno de los encantos (y a la vez de los quebraderos de cabeza) de un espacio compartido es precisamente eso: que es compartido. Las herramientas pasan por muchas manos, y por más carteles y buena voluntad que pongamos, al final del día siempre hay un destornillador que no ha vuelto a su sitio, unos alicates que aparecen en otro banco o directamente una herramienta que se ha \"evaporado\".
\nEste problema, que parece menor, tiene un coste real: tiempo perdido buscando, herramientas que se estropean o se pierden, y esa sensación de desorden que desmotiva. Así que decidí atacarlo con lo que mejor se me da: escribir código y trastear con electrónica.
\nEl resultado es Workbench Organizer CV, un sistema que, al cerrar el makespace, hace una foto de cada banco de trabajo con una cámara y comprueba mediante visión artificial si cada herramienta está en su hueco. Si algo falta o está mal colocado, genera una imagen anotada, guarda un historial y lanza una notificación.
\nPlaca ESP32-CAM: un microcontrolador con WiFi y una cámara OV2640 por poco más de lo que cuesta un café con leche. Fuente: Wikimedia Commons, CC BY-SA 4.0
La ESP32-CAM es una plaquita con WiFi, una cámara OV2640 y un precio ridículo. La programo con ESPHome, que me permite configurarla de forma declarativa y, lo más importante para este proyecto, exponer un endpoint de snapshot:
\n![ESP32-CAM](\"https://commons.wikimedia.org/wiki/File:ESP32-CAM.jpg\"){kind=link}
esp32_camera:\n name: cam-banco-electronica\n # ... pines de la ESP32-CAM AI-Thinker ...\n\nesp32_camera_web_server:\n - port: 8081\n mode: snapshotCon esto, un simple GET http://<ip-camara>:8081/ devuelve un JPEG del banco. En el sistema doy de alta esa cámara como tipo esphome con autenticación none.
Para montarla en el banco imprimí en 3D esta carcasa con rótula tipo snap-fit para ESP32-CAM, que viene fenomenal porque la rótula permite orientar la cámara hacia el banco con precisión (algo clave, como veremos, para que la alineación funcione bien).
\nSeguridad: ESPHome no autentica el endpoint de snapshot. Cualquiera en la misma red puede ver la imagen. Por eso estas cámaras deben vivir en una VLAN / red IoT aislada, accesible únicamente desde el servidor. En mi caso ya tengo la red segmentada con pfSense, como conté en el artículo del makespace.
Para explicar la estructura voy a usar el modelo C4 de Simon Brown, que describe un sistema en niveles de zoom progresivo: Contexto → Contenedores → Componentes → Código. Me parece la mejor forma de no perderse: empezamos con vista de pájaro y vamos bajando.
\nEn el nivel más alto solo interesa quién usa el sistema y con qué se relaciona:
\nDiagrama de contexto C4: el sistema, sus dos tipos de usuario y los sistemas externos con los que habla
Hay dos \"actores\" que disparan cosas:
\nY dos sistemas externos: las cámaras (de las que el sistema tira imágenes) y un webhook de notificaciones (al que el sistema empuja las incidencias).
\nBajamos un nivel y abrimos la caja \"sistema\". Aparecen los tres microservicios y los almacenes de datos:
\nDiagrama de componentes C4 del api-service
HttpOnly, y el trigger token de la palanca.cv-serviceY aquí está el protagonista de este artículo, el pipeline de visión desglosado en módulos independientes:
\nDiagrama de secuencia de una inspección completa
El orquestador (en api-service/src/inspections/orchestrator.ts) tiene tres propiedades que me importaban mucho:
Concurrencia acotada. Los bancos se inspeccionan en paralelo pero con un límite (cameraConcurrency), para no saturar la red ni el CV. Uso un pequeño pool:
const outcomes = await runWithConcurrency(workbenches, config.settings.cameraConcurrency, (wb) =>\n worker(wb, inspectionId),\n);Aislamiento de fallos parciales. Si una cámara no responde o el CV peta con un banco, ese banco se marca como not_evaluable pero el resto de la inspección continúa. Un fallo nunca cancela el lote. Cada inspectWorkbench está diseñado para no lanzar excepciones nunca: cualquier problema se convierte en un resultado.
Bloqueo por banco. Un banco no puede tener dos inspecciones simultáneas (imaginad la palanca y una automatización disparando a la vez). Un Mutex protege un Set de bancos bloqueados:
const locked = new Set<string>();\nconst lockMutex = new Mutex();\n\nasync function tryLock(id: string): Promise<boolean> {\n return lockMutex.runExclusive(() => {\n if (locked.has(id)) return false;\n locked.add(id);\n return true;\n });\n}Un principio que atraviesa todo el diseño y que quiero subrayar: el sistema nunca se inventa resultados positivos. Si la imagen no tiene calidad o no se puede alinear, el banco es not_evaluable. Prefiero mil veces un \"no lo sé\" honesto a un \"todo correcto\" falso que te haga cerrar el taller con una herramienta perdida.
Vamos al lío. El cv-service es un FastAPI minúsculo en la superficie: expone POST /v1/compare, que recibe dos imágenes (referencia y captura actual) más un payload JSON con la definición de las herramientas, y devuelve el veredicto.
@app.post(\"/v1/compare\", response_model=CompareResponse)\nasync def compare(\n reference: UploadFile = File(...),\n current: UploadFile = File(...),\n payload: str = Form(...),\n) -> CompareResponse:\n payload_obj = ComparePayload.model_validate(json.loads(payload))\n ...\n result = run_compare(ref_bytes, cur_bytes, payload_obj)Antes de tocar un solo píxel, Pydantic valida el payload (app/models.py). Y aquí ya hay teoría interesante. Cada herramienta se describe con un polígono de vértices normalizados, y valido su no-degeneración con la fórmula del área de Gauss (el shoelace o \"lazo de zapato\"):
def _shoelace_area(points: List[Vertex]) -> float:\n total = 0.0\n for i in range(len(points)):\n a = points[i]\n b = points[(i + 1) % len(points)]\n total += a.x * b.y - b.x * a.y\n return abs(total) / 2.0Esta fórmula calcula el área de un polígono simple sumando los \"productos cruzados\" de vértices consecutivos; si el resultado es prácticamente cero, el polígono es degenerado (todos los puntos casi en línea) y lo rechazo. También exijo que los pesos de las métricas sumen 1 y que haya entre 3 y 24 vértices. Validar en la frontera, con tipos, evita que basura llegue al algoritmo.
\nEl orquestador del pipeline es app/pipeline/compare.py. Su flujo es este:
Extracción de bordes con Canny (umbrales 60/160, los mismos que usa el código). Imagen base de ejemplo de Wikimedia Commons
Métrica 3 — Correlación de plantilla. Uso cv2.matchTemplate con el método TM_CCOEFF_NORMED, que desliza la región de referencia (la \"plantilla\") sobre la región de búsqueda de la captura y calcula la correlación cruzada normalizada en cada posición, quedándose con el máximo. La normalización la hace robusta frente a cambios globales de brillo. El truco de usar una región de búsqueda ligeramente mayor (el searchMargin) es que tolera que la herramienta esté un pelín desplazada dentro de su hueco:
result = cv2.matchTemplate(search_region, ref_region, cv2.TM_CCOEFF_NORMED)\n_, max_val, _, max_loc = cv2.minMaxLoc(result)El detalle que lo cambia todo: la máscara. Las tres métricas se calculan restringidas a los píxeles dentro del polígono. Para SSIM y bordes, relleno el exterior de la máscara con el valor medio interior (un relleno \"neutro\"), en lugar de con ceros, para no inyectar un borde artificial durísimo en el límite del polígono que falsearía las métricas. La correlación se calcula solo sobre los píxeles de dentro (correlación de Pearson enmascarada). Esto es lo que permite usar polígonos ajustados sin que el fondo contamine el resultado.
\napp/pipeline/scoring.py es deliberadamente trivial: una combinación lineal ponderada de las tres métricas, con pesos configurables que suman 1:
score = (weights[\"ssim\"] * metrics.ssim\n + weights[\"edgeSimilarity\"] * metrics.edge_similarity\n + weights[\"templateCorrelation\"] * metrics.template_correlation)Por defecto SSIM pesa 0.4, bordes 0.35 y plantilla 0.25. Que sea simple y transparente es una feature, no una carencia: puedo explicar exactamente de dónde sale cada score.
\nY app/pipeline/classification.py traduce ese score en un estado, con una banda de incertidumbre:
def classify(score, threshold, uncertainty_margin):\n if score >= threshold:\n return \"ok\"\n if score >= threshold - uncertainty_margin:\n return \"uncertain\"\n return \"misplaced\"Esa banda uncertain entre \"bien\" y \"mal\" es importante: en la frontera, en vez de arriesgarme a un falso positivo o negativo, marco la herramienta como \"dudosa\" para que un humano le eche un ojo. Y recordad el matiz de antes: aunque el score supere el umbral, si la calidad de la imagen no era aceptable, degrado el ok a uncertain.
Por último, app/pipeline/annotation.py dibuja cada polígono sobre la imagen con su color según estado (verde ok, rojo misplaced, naranja uncertain, gris not_evaluable) y una etiqueta con el nombre y el score. Esa imagen anotada se codifica en Base64 y viaja en la respuesta; el API la decodifica y la guarda como fichero (nunca se persiste Base64 dentro del JSON). Es justo el estilo de la imagen de portada de este artículo.
Una de las cosas de las que más orgulloso estoy es de que todo es configurable sin tocar código. Hay tres niveles: variables de entorno (.env), la configuración del sistema (data/config.json) y los secretos (config/auth.json). Vamos con calma.
Así se relacionan las entidades de config.json: