Trigger: Analítica de video

Este trigger vigila cámaras en vivo con Netsocs Vision, la analítica de video de Netsocs. Los modelos de detección corren en tus propios servidores, sin nube ni servicios externos. La automatización se inicia 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, para contar personas, medir tiempos de permanencia o detectar objetos abandonados).
• Cuando querés la misma lógica en cámaras de distintas marcas: la detección la hace Netsocs, no la cámara.
• Cuando necesitás reglas más ricas que un simple "movimiento detectado": por tipo de objeto, zona, dirección, tiempo de permanencia u 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-worker desplegado junto al backend de automatizaciones. Viene en el compose.yaml oficial.
• Al menos un modelo Netsocs Vision instalado. Se instala desde el propio nodo (ver Paso 1).
• CPU y RAM suficientes para la cantidad de cámaras y el modelo elegido. Antes de activar muchas cámaras, consultá Analítica de video: consumo de recursos.

---

Cómo configurarlo

Paso 0) Agregar el nodo

En el canvas, abrí el selector de nodos, buscá Analítica de video (o "detección", "cruce de línea", "permanencia"...) y arrastrá el trigger. Hacé doble click sobre él para abrir su configuración.

Paso 1) Elegir el modelo

Seleccioná un modelo instalado. Si no hay ninguno, abrí Modelos Netsocs Vision:

• Catálogo: modelos listos para descargar con un click, verificados por checksum. Todos reconocen 80 clases comunes: persona, bicicleta, auto, moto, autobús, camión, mochila, bolso, maleta, perro, gato, etc. La descarga muestra su progreso.
• Subir: subí tu propio modelo de detección en formato ONNX, solo o dentro de un .zip. Sirve para modelos entrenados con clases propias (casco, chaleco, placas...). Dentro del zip podés incluir:
  • classes.txt, una clase por línea;
  • el data.yaml del entrenamiento;
  • un manifest.json.
• Instalados: renombrar o borrar modelos. Un modelo que está usando un trigger activo no se puede borrar.

Modelo	Para qué
Netsocs Vision Nano	Muchas cámaras en un servidor modesto; objetos cercanos
Netsocs Vision Lite	Recomendado en CPU, uso general
Netsocs Vision Crowd	Multitudes: menos cajas duplicadas cuando las personas se superponen
Netsocs Vision Standard	Objetos chicos o lejanos
Netsocs Vision Crowd Pro	Multitudes y objetos chicos, mejor con GPU
Netsocs Vision Precision / Pro	Máxima precisión, con GPU

El consumo de cada uno está en consumo de recursos. Las licencias de los componentes de terceros se consultan desde el enlace Licencias de terceros de esa misma ventana.

Seguridad: solo se aceptan modelos ONNX. Los archivos de PyTorch (.pt, .pth, .pkl) se rechazan porque abrirlos puede ejecutar código.

Licencias de modelos propios: si el modelo que subís tiene una licencia con obligaciones (por ejemplo AGPL-3.0), el sistema te pide aceptarla antes de instalarlo. Cumplir esa licencia queda a tu cargo.

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
Confianza	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
Incluir foto	Sí	Adjunta a cada evento una foto del momento
Dibujar cajas	Sí	Marca en la foto los objetos detectados (caja, tipo y confianza)
Dibujar zonas y líneas	Sí	Marca en la foto las zonas y líneas, resaltando la del evento
Zona horaria	—	Zona horaria de los horarios de las reglas

Con las dos opciones de dibujo apagadas, la foto es la imagen limpia más una franja con el nombre de la regla y la hora.

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:

• Habilitada: desactiva la cámara sin perder su configuración.
• Stream: sub (recomendado, más liviano) o main (más resolución, para objetos lejanos).
• Copiar reglas y zonas a otras cámaras: 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 evalúan sobre los pies del objeto (el borde inferior central de su 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
Detección	Aparece el tipo de objeto elegido (opcionalmente en una zona y con un mínimo de objetos)	—
Cruce de línea	Un objeto cruza la línea, en el sentido A→B, B→A o en ambos	Línea
Entrada a zona	Un objeto entra a la zona (o aparece dentro)	Zona
Salida de zona	Un objeto sale de la zona (o se pierde de vista dentro)	Zona
Permanencia en zona (al salir)	Un objeto, o un grupo, termina su visita a la zona. Informa cuánto duró, la foto de entrada, la de salida y recortes del objeto	Zona
Merodeo	Un objeto lleva en la zona más de X segundos (dispara mientras sigue dentro)	Zona
Aforo	Hay N objetos o más (o N o menos) en la zona durante X segundos	Zona
Zona vacía	No hay nadie en la zona durante X segundos (por ejemplo, un puesto de guardia vacío)	Zona
Contador de línea	Cuenta entradas (A→B) y salidas (B→A); avisa cada N cruces o con un reporte periódico	Línea
Objeto abandonado	Un objeto (por defecto mochila, bolso o maleta) queda quieto X segundos sin una persona cerca	—
Objeto retirado	Desaparece un objeto que estaba fijo en la escena (un TV, una notebook)	—
Sentido contrario	Un objeto se mueve en contra del sentido permitido	—
Colarse detrás de otro	Dos o más personas cruzan la línea en pocos segundos	Línea
Proximidad	Un objeto está cerca de otro de otro tipo (persona junto a un vehículo)	—
Velocidad	Un objeto supera una velocidad (en m/s si calibrás cuántos metros abarca el ancho de la imagen)	—
Cámara sin señal	La cámara deja de enviar imagen durante X segundos (y opcionalmente avisa al volver)	—
Sabotaje de cámara	La imagen queda negra, encandilada, congelada o desenfocada (lente tapada, rociada o girada)	—

Permanencia en zona: modos

• Cada objeto: un evento por objeto cuando sale de la zona, con su duración.
• Grupo: un solo evento cuando la zona queda vacía. Cubre a todos los que estuvieron, desde que entró el primero hasta que salió el último. Es más estable cuando las personas se tapan entre sí.

También se configura la duración mínima (las visitas más cortas no se informan) y la cantidad máxima de recortes por evento.

Opciones comunes a todas las reglas

• Clases: qué objetos cuentan (person, car, truck...). Vacío = cualquiera.
• Confianza mínima, tamaño mínimo y máximo: filtran detecciones dudosas o lejanas.
• Frames de confirmación: 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.
• Horario: ventanas horarias por día. Por ejemplo, 20:00–06:00 solo 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 un tipo de objeto que el modelo no reconoce.

---

¿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_visit, camera_offline, camera_online...)
rule_id, rule_name	La regla que se cumplió
camera_id, camera_name	La cámara
class, confidence	Tipo 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 (en Permanencia: cuánto duró la visita), sin señal o abandonado
count, count_in, count_out	Conteos (aforo, contador de línea, objetos de una visita en grupo)
speed, speed_unit	Velocidad medida (regla Velocidad)
reason	Detalle adicional: appeared, lost, group, report, dark, frozen, blurred, overexposed
message	Resumen legible, listo para un mensaje
snapshot_url	Foto del evento. En Permanencia, el frame de salida. Se puede enviar tal cual por Telegram, WhatsApp o email
entry_snapshot_url	Permanencia: foto del frame de entrada
entered_at, exited_at	Permanencia: momento de entrada y de salida
crops	Permanencia: recortes del objeto. Cada uno con url, kind (entry, best o exit), class, confidence y timestamp
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: Entrada a zona en el patio, clase person, horario 20:00–06:00 → Telegram con snapshot_url → crear una alarma.
• Tiempo de atención en mostrador: Permanencia en zona, modo Cada objeto, duración mínima 10 s → guardar dwell_seconds, entered_at y exited_at en Google Sheets, con el primer recorte (crops) como evidencia.
• Ocupación de una sala: Permanencia en zona, modo Grupo → registrar cada período de ocupación y cuántas personas pasaron (count).
• Aforo de un local: Contador de línea en la puerta, reporte cada 15 minutos y reinicio diario → guardar count_in y count_out.
• Cola en la caja: Aforo con 5 personas o más durante 60 s, repitiendo cada 5 minutos → avisar al supervisor.
• Auto mal estacionado: Merodeo con clases car y truck, 300 s, en la zona prohibida.
• Mochila abandonada: Objeto abandonado con 60 s en el hall.
• Sabotaje: Sabotaje de cámara + Cámara sin señal (con aviso de vuelta) en todas las cámaras críticas.
• Elementos de protección personal: subí un modelo propio con las clases helmet y no_helmet y usá Detección con la clase no_helmet en 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á su 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 Modelos Netsocs Vision
El editor dice que el servicio de visión no responde	El servicio automation-vision-worker no está levantado
Cámara sin imagen (offline)	Que la cámara se vea en el dashboard: se usa el mismo video WebRTC que el reproductor
Origen snapshot en lugar de video	El WebRTC no conectó y se están usando fotos de respaldo (~1 por segundo). Revisá la red entre el servicio de visión y DriverHub
No detecta objetos chicos o lejanos	Usá Netsocs Vision Standard o Crowd Pro, o el stream main
Falsas alarmas	Zonas de exclusión, tamaño mínimo, frames de confirmación 3–5
Los cruces no disparan	FPS de 5 o más, y que la línea atraviese el camino de los pies
Una visita se parte en dos (reason: lost)	La persona quedó tapada unos segundos. Usá el modo Grupo
El análisis va lento (FPS reales menores a los configurados)	El servidor no da abasto. Ver consumo de recursos