Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt

Use this file to discover all available pages before exploring further.

spatial_filter is a stateless workflow node that drops detections that lie outside an author-defined polygon zone. It pairs with timed_condition downstream to build zone-based intrusion alerts without per-camera pixel coordinates. Execution context is inferred from the upstream graph:
  • Wired downstream of a camera_frame trigger + call_model chain it is compiled into the edge worker as an inline polygon-membership comprehension.
  • Wired anywhere else it runs in the cloud workflow runner against the detection array of the upstream node.
Typical chain for a zone-scoped intrusion alert: 
trigger (camera_frame) → call_model (YOLO) → anonymize → spatial_filter → timed_condition → send_alert

​
Coordinate system

Polygons are stored as [[x, y], ...] of floats in normalized [0..1] image coordinates — the same space YOLO bounding boxes already use. A zone authored against a 1080p stream keeps working when you swap the camera for a 4K one without any manual remap. Polygons must have at least 3 vertices.

​
Inputs

FieldTypeDescription
detectionsarrayDetection results from an upstream call_model (or anonymize / annotate — the implicit-wiring contract carries the detection array through unchanged). Required.
polygonarray[[x, y], ...] in normalized [0..1] coordinates. ≥ 3 vertices.
point_modestringWhich part of each detection’s bounding box must fall inside the polygon to count as “in”. bbox_bottom_center (default) for floor-anchored subjects, centroid for mid-air things, any_overlap if any pixel of the bbox touching the polygon should count.
framestringimage (only mode supported in v1; floor-plan zones are deferred).
classesarrayOptional class allow-list applied before the polygon test. null / empty means every detection class is tested.

​
Outputs

FieldTypeDescription
detectionsarraySubset of input detections that passed the polygon test.
countnumberLength of the filtered detection array — handy for downstream conditional gates.
polygonarrayEcho of the configured polygon (normalized coordinates) so downstream snapshot rendering and the live frontend overlay can draw the ROI without re-fetching the node config.

​
Authoring zones

Zones are authored in the workflow editor inspector for the spatial_filter node:
  1. Add a Spatial Filter node from the Decision & Control group.
  2. Wire a camera_frame trigger upstream (typically through a call_model that runs detection).
  3. In the inspector, click on the polygon canvas to add vertices, drag to move them, double-click to remove (≥ 3 vertices required).
  4. Optional: click Capture frame to fetch the latest still from the upstream camera trigger and trace the polygon over the actual scene.
  5. Pick the Reference Point that matches your subjects: bbox_bottom_center for people standing on the floor, centroid for mid-air objects, any_overlap when even a finger crossing the line should count.
Once the workflow is active, the polygon also renders as a read-only overlay on the twin’s WebRTC stream so operators can see which zones are armed.

​
Edge implementation

The node compiles into a Python comprehension inlined into the generated edge worker (wf_<uuid8>.py) — no extra runtime dependencies, no MQTT round-trip per frame. The polygon-membership helper is generated only once even if multiple zones share a worker. See Edge Workers for the full lifecycle.

​
Companion nodes

  • timed_condition — fire only when something has been inside the zone for at least N seconds.
  • anonymize — pair upstream of spatial_filter to publish privacy-safe video while still alerting on zone violations.