Trigger: Analítica de video (YOLO) (yolo_trigger)¶
Este trigger vigila cámaras en vivo con un modelo de detección de objetos que corre en tus propios servidores (sin nube ni servicios de IA externos) e inicia la automatización cuando se cumple una regla sobre una cámara: aparece una persona, un vehículo cruza una línea, alguien se queda demasiado tiempo en una zona, una mochila queda abandonada, la cámara se tapa, etc.
Cada cámara tiene sus propias zonas y reglas, y un mismo trigger puede vigilar varias cámaras a la vez.
¿Cuándo usarlo?¶
- Cuando la cámara no trae analítica propia o la que trae no alcanza (por ejemplo, contar personas o detectar objetos abandonados).
- Cuando querés la misma lógica en cámaras de distintas marcas, porque la detección la hace Netsocs y no la cámara.
- Cuando necesitás reglas más ricas que un simple "movimiento detectado": por clase de objeto, por zona, por dirección, por tiempo de permanencia o por horario.
Si la cámara o el VMS ya generan el evento que necesitás (por ejemplo, una intrusión de una Hanwha o una Hikvision), es más barato usar Trigger: Event con ese evento.
Requisitos¶
- El servicio
automation-vision-workerdesplegado junto al backend de automatizaciones. Viene en elcompose.yamloficial. - Al menos un modelo de detección instalado. Se instala desde el propio nodo (ver Paso 1).
- Recursos de CPU y RAM suficientes para la cantidad de cámaras y el modelo elegido. Consultá Analítica de video (YOLO): consumo de recursos antes de activar muchas cámaras.
Cómo configurarlo¶
Paso 0) Agregar el nodo¶
En el canvas, abrí el selector de nodos, buscá Video analytics (o "yolo", "detección", "cruce de línea"...) y arrastrá el trigger. Hacé doble click para abrir su configuración.
Paso 1) Elegir el modelo¶
Seleccioná un modelo instalado. Si no hay ninguno, abrí Manage models:
- Catalog: modelos listos para descargar con un click. Están verificados por checksum y tienen licencia Apache-2.0. Todos detectan las 80 clases estándar (COCO): persona, bicicleta, auto, moto, autobús, camión, mochila, bolso, maleta, perro, gato, etc. Se ve el progreso de la descarga.
- Upload: subí tu propio modelo en formato
.onnx, solo o dentro de un.zip. Sirve para modelos entrenados con clases propias (casco, chaleco, placas, armas...). Dentro del zip podés incluir:classes.txt, una clase por línea;- el
data.yamldel entrenamiento; - un
manifest.json.
- Installed: renombrar o borrar modelos. Un modelo que está usando un trigger activo no se puede borrar.
¿Cuál elegir? Para la mayoría de los casos en CPU, YOLOX Tiny. Para muchas cámaras en un servidor modesto, YOLOX Nano. Para objetos pequeños o lejanos, YOLOX S o D-FINE S (idealmente con GPU). La comparación completa está en la página de consumo de recursos.
Seguridad: solo se aceptan modelos ONNX. Los archivos de PyTorch (
.pt,.pth,.pkl) se rechazan porque abrirlos puede ejecutar código. Exportá tu modelo a ONNX antes de subirlo.Licencia: los modelos de Ultralytics (YOLOv8, YOLO11) son AGPL-3.0. Al subirlos se pide aceptar la licencia explícitamente. Usarlos en un producto cerrado requiere una licencia comercial de Ultralytics.
Paso 2) Ajustes generales¶
| Campo | Por defecto | Para qué sirve |
|---|---|---|
| FPS | 5 | Imágenes por segundo que se analizan (de 0.2 a 15). Es lo que más impacta en el consumo de CPU |
| Confidence | 0.35 | Confianza mínima de una detección (0 a 1) para las reglas que no definen la suya |
| Cooldown | 10 s | Tiempo mínimo entre dos disparos de la misma regla, para evitar avalanchas de alertas |
| Include snapshot | Sí | Adjunta a cada evento una foto con las cajas y las zonas dibujadas |
| Timezone | — | Zona horaria de los horarios de las reglas |
Paso 3) Seleccionar las cámaras¶
Elegí una o varias cámaras del árbol de objetos. Para cada cámara se ve su estado en vivo: si está recibiendo imagen, los FPS reales, el tiempo de análisis y el último error.
Cada cámara tiene una pestaña con:
- Enabled: desactiva la cámara sin perder su configuración.
- Stream:
sub(recomendado, más liviano) omain(más resolución, para objetos lejanos). - Copy rules and zones to other cameras: copia la configuración a las demás cámaras.
Paso 4) Dibujar zonas y líneas¶
Sobre la imagen de la cámara podés dibujar:
- Zonas (polígonos): hacé click en cada vértice. Hacen falta al menos 3 puntos.
- Líneas (2 puntos): se usan para cruces y conteos. La flecha muestra el sentido del dibujo:
- Lado A es el que queda a la derecha de la flecha, mirando del primer punto al segundo.
- Lado B es el de la izquierda.
- Si dibujaste la línea al revés, el botón de intercambiar invierte los extremos.
- Zonas de exclusión: lo que caiga dentro se ignora (árboles que se mueven con el viento, pantallas, una calle que no interesa).
Los puntos se pueden arrastrar, y con doble click se borra uno. Las zonas se toman sobre los pies del objeto (el borde inferior central de la caja): una persona "está en la zona" cuando pisa la zona dibujada en el piso.
Paso 5) Crear las reglas¶
Agregá una o más reglas por cámara. Al elegir el tipo, el formulario muestra solo los campos que ese tipo usa.
| Regla | Dispara cuando... | Necesita |
|---|---|---|
| Detected | Aparece la clase elegida (opcionalmente en una zona y con un mínimo de objetos) | — |
| Line cross | Un objeto cruza la línea, en el sentido A→B, B→A o en ambos | Línea |
| Zone enter | Un objeto entra a la zona (o aparece dentro) | Zona |
| Zone exit | Un objeto sale de la zona (o se pierde de vista dentro) | Zona |
| Zone dwell (merodeo) | Un objeto permanece en la zona más de X segundos | Zona |
| Zone count (aforo) | Hay N objetos o más (o N o menos) en la zona durante X segundos | Zona |
| Zone empty | No hay nadie en la zona durante X segundos (por ejemplo, un puesto de guardia vacío) | Zona |
| Line counter | Cuenta entradas (A→B) y salidas (B→A). Avisa cada N cruces o con un reporte periódico | Línea |
| Abandoned object | Un objeto (por defecto mochila, bolso o maleta) queda quieto X segundos sin una persona cerca | — |
| Object removed | Desaparece un objeto que estaba fijo en la escena (un TV, una notebook) | — |
| Wrong way | Un objeto se mueve en contra del sentido permitido | — |
| Tailgating | Dos o más personas cruzan la línea en pocos segundos (una se cuela detrás de otra) | Línea |
| Proximity | Un objeto está cerca de otro de otra clase (persona junto a un vehículo) | — |
| Speed | Un objeto supera una velocidad. Calibrando los metros que abarca el ancho de la imagen, se mide en m/s | — |
| Camera offline | La cámara deja de enviar imagen durante X segundos (y opcionalmente avisa al volver) | — |
| Camera tampered | La imagen queda negra, encandilada, congelada o desenfocada (lente tapada, rociada o girada) | — |
Opciones comunes a todas las reglas:
- Classes: qué objetos cuentan (
person,car,truck...). Vacío = cualquiera. - Min confidence, tamaño mínimo y máximo: filtran detecciones dudosas o lejanas.
- Confirm frames: cuántas imágenes seguidas debe cumplirse la condición. Evita falsas alarmas por un parpadeo del detector.
- Cooldown y alcance del cooldown: una alerta por regla cada X segundos, o una por cada objeto. Por ejemplo, en un cruce de línea cada persona que cruza genera su propio evento.
- Schedule: ventanas horarias por día. Por ejemplo,
20:00–06:00solo de noche: si el fin es anterior al inicio, la ventana cruza la medianoche.
Paso 6) Guardar y activar¶
Guardá y activá la automatización. Si algo no es válido, la activación falla y el motivo aparece en el estado del trigger. Por ejemplo:
- el modelo no está instalado;
- una regla de zona no tiene zona asignada;
- una regla usa una clase que el modelo no detecta.
¿Qué devuelve?¶
Cada vez que una regla se cumple se inicia una ejecución. Estos campos se pueden usar en los nodos siguientes
como {{<clave_del_trigger>.<campo>}}:
| Campo | Descripción |
|---|---|
event_type |
Tipo de regla que disparó (line_cross, zone_dwell, camera_offline, camera_online...) |
rule_id, rule_name |
La regla que se cumplió |
camera_id, camera_name |
La cámara |
class, confidence |
Clase y confianza del objeto principal |
track_id |
Identificador del objeto mientras se lo sigue |
bbox |
Caja del objeto [x1, y1, x2, y2] en proporciones de la imagen (0 a 1) |
objects |
Todos los objetos involucrados |
region_id, region_name |
Zona o línea involucrada |
direction |
a_to_b o b_to_a en los cruces |
dwell_seconds |
Segundos en la zona, sin señal o abandonado |
count, count_in, count_out |
Conteos (aforo, contador de línea) |
speed, speed_unit |
Velocidad medida (regla Speed) |
reason |
Detalle adicional: appeared, lost, report, dark, frozen, blurred, overexposed |
message |
Resumen legible, listo para un mensaje |
snapshot_url |
Foto del evento con las cajas y la zona dibujadas. Se puede enviar tal cual por Telegram, WhatsApp o email |
timestamp |
Fecha y hora del evento |
Si un mismo trigger tiene varias reglas, usá un Switch sobre {{<clave_del_trigger>.rule_id}} para que
cada una siga su propio camino.
Ejemplos¶
- Intrusión nocturna: Zone enter en el patio, clase
person, horario20:00–06:00→ Telegram consnapshot_url→ crear una alarma. - Aforo de un local: Line counter en la puerta, reporte cada 15 minutos y reinicio diario → guardar
count_inycount_outen Google Sheets. - Cola en la caja: Zone count con 5 personas o más durante 60 s, repitiendo cada 5 minutos → avisar al supervisor.
- Auto mal estacionado: Zone dwell con clases
carytruck, 300 s, en la zona prohibida. - Mochila abandonada: Abandoned object con 60 s en el hall.
- Sabotaje: Camera tampered + Camera offline (con aviso de vuelta) en todas las cámaras críticas.
- Elementos de protección personal: subí un modelo propio con las clases
helmetyno_helmety usá Detected con la claseno_helmeten la zona de obra.
Buenas prácticas¶
- Empezá con FPS 5 en cruces y entradas, y FPS 1–2 para permanencia, aforo y objetos abandonados. Así el consumo baja a la mitad o menos.
- Dibujá las zonas sobre el piso y las líneas atravesando el recorrido de los pies.
- Usá zonas de exclusión para lo que se mueve y no interesa, en lugar de subir la confianza.
- Si llegan alertas repetidas, subí el cooldown o cambiá el alcance a "por regla".
- Probá primero con una cámara y mirá el estado en vivo (FPS reales y tiempo de análisis) antes de agregar más.
Problemas frecuentes¶
| Síntoma | Qué revisar |
|---|---|
| model ... is not installed al activar | Instalá el modelo desde Manage models |
| El editor dice que el vision worker no responde | El servicio automation-vision-worker no está levantado |
| Cámara sin imagen (offline) | Que la cámara se vea en el dashboard. El worker usa el mismo video WebRTC que el reproductor |
Origen snapshot en lugar de video |
El WebRTC no conectó y el worker está usando fotos de respaldo (~1 por segundo). Revisá la red entre el worker y DriverHub |
| No detecta objetos chicos o lejanos | Usá un modelo de 640 px (YOLOX S / D-FINE S) o el stream main |
| Falsas alarmas | Zonas de exclusión, tamaño mínimo, confirm frames 3–5 |
| Los cruces no disparan | FPS de 5 o más, y que la línea atraviese el camino de los pies |
| El análisis va lento (FPS reales menores a los configurados) | El servidor no da abasto. Ver consumo de recursos |