Skip to main content

Human Detection & Intrusion Detection API

Viewtron AI security cameras include built-in human detection and intrusion detection that runs entirely on the camera hardware — no cloud service or external AI software required. When a person, vehicle, or motorcycle enters a defined intrusion zone, 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 target classification (person, car, or motorcycle).

This is the most commonly used AI detection feature in the Viewtron API. You can configure up to 4 intrusion zones per camera, each with independent object filters and sensitivity settings. All Viewtron IP cameras and NVRs are NDAA compliant.

What You Can Build​

  • Automated intruder alerts — send email, SMS, or push notifications with snapshot images when a person enters a restricted area
  • Presence-based automation — turn on lights, activate relays, or trigger recordings when humans are detected
  • Custom alarm logic — filter by target type (person vs car vs motorcycle) to reduce false alarms
  • Security dashboards — aggregate intrusion events across multiple cameras with images and timestamps
  • Integration with access control — connect to VMS, alarm panels, or building management systems
  • Dwell time tracking — combine with real-time traject data for continuous position monitoring

How It Works​

  1. Configure an intrusion zone on the camera — define a polygon region and enable object filters (person, car, motor)
  2. Enable HTTP POST webhooks — point the camera or NVR at your server's IP and port
  3. Your server receives XML when a detection occurs — the POST includes alarm type, target coordinates, zone boundary, and base64 images
  4. Parse the event using the Viewtron Python SDK (pip install viewtron) or Node.js SDK
  5. Take action — save images, log to CSV, send alerts, trigger relays

Event Data Included​

Each intrusion detection webhook POST contains:

FieldDescription
smartTypePEA (IPC) or regionIntrusion (NVR)
targetTypeperson, car, or motor
rectBounding box of the detected target (x1, y1, x2, y2)
boundary / pointGroupPolygon coordinates of the intrusion zone
eventId / targetIdUnique IDs for the event and tracked target
statusSMART_START, SMART_PROCEDURE, or SMART_STOP
sourceBase64DataFull-frame JPEG image (base64 encoded, ~500 KB)
targetBase64DataCropped target JPEG image (base64 encoded, ~50-80 KB)
currentTimeDetection timestamp

Object Filters​

Each intrusion zone can independently filter by target type with per-object sensitivity (1-100):

ObjectDescriptionDefault Sensitivity
personHuman detection50
carVehicle (car/truck) detection50
motorMotorcycle/bicycle detection50

Disable any object type to ignore it entirely, or adjust sensitivity to control the detection threshold.

Parsing Intrusion Events​

The simplest way to receive intrusion 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"Intrusion detected from {client_ip}")
    print(f"  Target: {event.get_alarm_type()} ({event.get_alarm_description()})")
    print(f"  Event ID: {event.raw.get('eventId', 'N/A')}")

    overview = event.get_source_image_bytes()
    if overview:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-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()}-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
GetSmartPerimeterConfigRead intrusion zone configurationIntrusion Detection Config
SetHttpPostConfigConfigure webhook destinationWebhook Config
GetAlarmStatusPoll current alarm stateAlarm Status

Integrations​

Viewtron human detection also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantPerson and vehicle detection as native HA sensors — automate lights, alarms, notifications
Node-REDnode-red-contrib-viewtronIntrusion events direct to Node-RED flows — no middleware needed

For a walkthrough of human detection events in action, including zone configuration and live webhook output, see the AI Security Camera System video guide.

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.