Skip to main content

Real-Time Object Tracking API (traject)

Viewtron AI cameras support a unique real-time tracking mode called traject that continuously streams target position data to your server via HTTP POST. Unlike alarm-based detection events that fire once per event, traject sends continuous updates at approximately 7 posts per second for the entire duration a target is being tracked. Each post is only ~1.7 KB of XML data containing the target ID, target type (person, car, or motorcycle), and bounding box coordinates — no images are included.

This makes traject fundamentally different from every other detection type in the Viewtron API. Alarm-based methods like human detection or line crossing send a single event with images when something happens. Traject gives you a continuous stream of position data that lets you know exactly where a target is, how long it has been there, and when it leaves. The stream starts within ~140ms of a target being detected and stops within ~1 second of the target leaving the camera's view.

Important: Traject is only available from IPC cameras directly — NVRs do not forward traject data. The camera must be subscribed to the traject data type via httpPostV2 configuration.

What You Can Build​

  • Real-time position dashboards — display target locations on a map or floor plan that updates in real time
  • Presence-based relay control — turn on lights, activate alarms, or control relays while a person is present (see the ESP8266 relay controller project)
  • Dwell time analysis — calculate exactly how long each target stays in view, down to sub-second precision
  • Speed and direction estimation — track bounding box movement between frames to estimate velocity
  • Occupancy counting — monitor how many targets are simultaneously active in the camera's field of view
  • Custom alarm logic — build your own detection rules based on target position, duration, or movement patterns

How It Works​

  1. Enable traject on the camera — subscribe to the traject data type in the httpPostV2 configuration and enable "Smart track data" in the camera's HTTP Post V2 web interface
  2. Your server receives continuous XML posts while any target is being tracked — approximately 7 posts per second per target
  3. Parse the position data using the Viewtron Python SDK (pip install viewtron) or Node.js SDK — each post contains one or more targets with targetId, targetType, and bounding rect coordinates
  4. Track targets over time — use the targetId to correlate posts for the same target, calculate dwell time and movement
  5. Detect departure — when posts stop arriving for a targetId, the target has left the camera's view

Comparison with Other Methods​

MethodSignal TypePosts While PresentGaps While PresentData per Post
GetAlarmStatus pollingperimeterAlarm=truePeriodic (your poll rate)Yes (5-20 seconds)~660 bytes
Alarm server pushOne POST per event1-2 per entryYes (20-60 seconds)~510-530 KB (with images)
httpPostV2 trajectContinuous POSTs6-12 per secondNone~1.7 KB (no images)

The key advantage of traject is zero gaps. Alarm-based methods have significant blind periods where a target is present but no data is being sent. Traject provides continuous confirmation that a target is still there.

Traject Data Fields​

Each traject POST contains one or more tracked targets:

FieldTypeDescription
targetIduint32Unique ID for the tracked target — new ID assigned per entry
targetTypestringperson, car, or motor
rectx1, y1, x2, y2Bounding box in normalized coordinates (0-10000)
pointx, yTarget center point (may be 0,0)
velocityuint32Target velocity (may be 0)
directionuint32Target direction (may be 0)
trajectlengthlistTrajectory path points (may be empty)
currentTimetint64Timestamp in microseconds
macstringCamera MAC address
deviceNamestringCamera name
note

The velocity, direction, and trajectlength fields are included in the XML but are typically reported as zero in current firmware. You can calculate speed and direction yourself by tracking bounding box position changes between consecutive posts.

Parsing Traject Events​

The SDK includes a Traject class for parsing traject posts. The ViewtronServer handles the HTTP connection and keepalives:

pip install viewtron
from viewtron import ViewtronServer
import time

# Active targets: {targetId: {type, first_seen, last_seen, post_count}}
active_targets = {}
TARGET_TIMEOUT = 2.0

def on_traject(event, client_ip):
    """Called for each traject post (~7/sec per target)."""
    now = time.time()

    for target in event.targets:
        tid = target["targetId"]
        if tid in active_targets:
            active_targets[tid]["last_seen"] = now
            active_targets[tid]["post_count"] += 1
        else:
            active_targets[tid] = {
                "type": target["targetType"],
                "first_seen": now,
                "last_seen": now,
                "post_count": 1,
            }
            print(f"  [ARRIVED] Target {tid} ({target['targetType']})")

    # Expire departed targets
    expired = [tid for tid, t in active_targets.items()
               if now - t["last_seen"] > TARGET_TIMEOUT]
    for tid in expired:
        t = active_targets.pop(tid)
        dwell = t["last_seen"] - t["first_seen"]
        print(f"  [DEPARTED] Target {tid} ({t['type']}) — "
              f"dwell: {dwell:.1f}s, posts: {t['post_count']}")

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

See the Python SDK reference for the full Traject class API.

Configuration​

Enable traject on an IPC camera by sending this XML to SetHttpPostConfig:

<?xml version="1.0" encoding="UTF-8"?>
<config version="1.0" xmlns="http://www.ipc.com/ver10">
<httpPostV2><postUrlConf>
  <urlList type="list" count="1"><item>
    <urlId>1</urlId>
    <switch>true</switch>
    <url>
      <protocol>http</protocol>
      <domain><![CDATA[192.168.0.53]]></domain>
      <port>80</port>
      <path><![CDATA[/API]]></path>
      <authentication>none</authentication>
    </url>
    <heatBeatSwitch>true</heatBeatSwitch>
    <keepaliveTimeval>90</keepaliveTimeval>
    <subscribeDateType type="list" count="1">
      <item>traject</item>
    </subscribeDateType>
    <subscriptionEvents type="list" count="1">
      <item>PERIMETER</item>
    </subscriptionEvents>
  </item></urlList>
</postUrlConf></httpPostV2>
</config>
warning

The "Smart track data" checkbox must also be enabled in the camera's HTTP Post V2 web interface (Edit HTTP POST dialog). The camera will not send traject data even if configured via API unless this checkbox is checked.

Important Notes​

  • Traject is IPC-only. NVRs do not forward traject data and do not expose the smart track data subscription.
  • Works through NVR PoE. When an IPC is connected to an NVR via PoE, the camera still sends traject directly to your server. The XML format is identical — the source IP will be the NVR's PoE interface.
  • No images included. Traject posts contain only position data (~1.7 KB). For images, use a parallel alarm-based subscription.
  • Recommended dual setup: Configure the NVR's HTTP POST for alarm events with images, and configure the IPC's httpPostV2 for traject tracking. This gives you both event snapshots and continuous position data.
  • New targetId per entry. Each time a target enters the camera's view, it receives a new unique targetId. The same physical person will get different IDs if they leave and return.

For a working automation example, see the ESP8266 Relay Controller project, which uses traject data to control a relay for continuous human presence detection — keeping a relay energized for the entire duration a person is in view with zero gaps.

Relevant API Endpoints​

EndpointPurposeReference
SetHttpPostConfigConfigure httpPostV2 with traject subscriptionWebhook Config
GetHttpPostConfigRead current httpPostV2 configurationWebhook Config
GetSmartPerimeterConfigConfigure the perimeter detection zone that triggers trackingIntrusion Detection Config

Integrations​

Viewtron traject tracking also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantReal-time presence detection as native HA sensors — automate lights, relays, alarms
Node-REDnode-red-contrib-viewtronTraject data direct to Node-RED flows — build presence logic visually

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.