Skip to main content

Perimeter Security & Line Crossing Detection API

Viewtron AI security cameras support tripwire line crossing detection and region entry/exit detection that runs entirely on the camera hardware — no cloud service or external AI software required. When a person, vehicle, or motorcycle crosses a defined line or enters/exits a defined region, the camera sends an HTTP POST webhook to your server with the detection event data, including a full-frame overview image, a cropped image of the detected target, bounding box coordinates, and the line or region boundary.

Line crossing detection uses a start point and end point to define a tripwire. You can configure direction filtering to detect only objects crossing in a specific direction (left-to-right, right-to-left, or both). Region entry and exit detection uses a polygon zone and triggers when an object enters or leaves that area. All Viewtron IP cameras and NVRs are NDAA compliant.

The key difference from intrusion detection is that line crossing detects movement across a boundary line rather than presence within a polygon zone. Region entry/exit detects the transition into or out of a zone, rather than continuous presence.

What You Can Build​

  • Boundary crossing alerts — detect when people or vehicles cross a property line, fence line, or restricted area boundary
  • Directional traffic monitoring — filter by crossing direction to track one-way traffic flow at gates, driveways, or corridors
  • Doorway and entry counting — combine with people counting for occupancy tracking
  • Loading dock monitoring — alert when vehicles enter or exit loading zones
  • Parking lot entry/exit — detect vehicles crossing gate lines for access logging
  • Zone transition tracking — trigger different actions when objects enter vs leave a defined region

How It Works​

  1. Configure a tripwire line on the camera — define a start point and end point, set the crossing direction filter (both, left/right, or top/bottom)
  2. Or configure a region entry/exit zone — define a polygon region for AOI (Area of Interest) entry or exit detection
  3. Enable HTTP POST webhooks — point the camera or NVR at your server's IP and port
  4. Your server receives XML when a detection occurs — the POST includes alarm type, line coordinates, target bounding box, and base64 images
  5. Parse the event using the Viewtron Python SDK (pip install viewtron) or Node.js SDK
  6. Take action — save images, log to CSV, send alerts, trigger relays

Event Data Included​

Each line crossing or region entry/exit webhook POST contains:

FieldDescription
smartTypePEA (IPC line cross), lineCrossing (NVR), AOIENTRY (IPC entry), AOILEAVE (IPC exit)
boundarytripwire (line crossing) or zone polygon (region entry/exit)
directionLineStart and end point of the tripwire line (NVR format)
startPoint / endPointLine coordinates defining the tripwire (IPC format uses lineInfo)
rectBounding box of the detected target (x1, y1, x2, y2)
eventId / targetIdUnique IDs for the event and tracked target
statusSMART_START, SMART_PROCEDURE, or SMART_STOP
sourceBase64DataFull-frame JPEG image (base64 encoded)
targetBase64DataCropped target JPEG image (base64 encoded)
currentTimeDetection timestamp

Tripwire Direction Options​

The IPC tripwire configuration supports directional filtering:

DirectionDescription
noneDetect crossing in both directions
rightortopDetect crossing from left-to-right or bottom-to-top only
leftorbottonDetect crossing from right-to-left or top-to-bottom only
note

The NVR v2.0 lineCrossing event does not include crossing direction in the webhook POST data. The direction line coordinates are included, but not which direction the object crossed.

Parsing Line Crossing Events​

The simplest way to receive line crossing events. The SDK's ViewtronServer handles HTTP connections, keepalives, XML parsing, and version detection — you just write the callback:

pip install viewtron
from viewtron import ViewtronServer
import os

IMG_DIR = "images"
os.makedirs(IMG_DIR, exist_ok=True)

def on_event(event, client_ip):
    if event.category != "intrusion":
        return
    print(f"Line crossing detected from {client_ip}")
    print(f"  Type: {event.get_alarm_type()} ({event.get_alarm_description()})")

    overview = event.get_source_image_bytes()
    if overview:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-line-crossing-overview.jpg", "wb") as f:
            f.write(overview)

    target = event.get_target_image_bytes()
    if target:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-line-crossing-target.jpg", "wb") as f:
            f.write(target)

server = ViewtronServer(port=5002, on_event=on_event)
server.serve_forever()

See the Python SDK reference for the full list of methods and event classes.

Relevant API Endpoints​

EndpointPurposeReference
GetSmartTripwireConfigRead tripwire line crossing configurationLine Crossing Config
GetSmartAoiEntryConfigRead region entry detection configurationRegion Entry/Exit Config
GetSmartAoiLeaveConfigRead region exit detection configurationRegion Entry/Exit Config
SetHttpPostConfigConfigure webhook destinationWebhook Config
GetAlarmStatusPoll current alarm state (tripwireAlarm, aoiEntryAlarm, aoiLeaveAlarm)Alarm Status

Integrations​

Viewtron line crossing detection also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantLine crossing events as native HA sensors — automate gates, lights, notifications
Node-REDnode-red-contrib-viewtronLine crossing events direct to Node-RED flows — no middleware needed

Questions & Development Inquiries​

Mike Haldas is available for questions, consultation, and custom software development for Viewtron API related projects. Email details about your project to mike@viewtron.com.