Python SDK Overview

The Viewtron Python SDK provides two main components:

• ViewtronServer -- an HTTP server that receives AI detection events from Viewtron cameras and NVRs
• ViewtronCamera -- an HTTP client that sends commands to cameras (device info, plate database CRUD)

Both IPC (IP camera, v1.x API) and NVR (network video recorder, v2.0 API) formats are handled transparently. Your code receives the same event.category values regardless of which device sent the event.

Installation

pip install viewtron

Requires Python 3.8 or later. Installs two dependencies: xmltodict (XML parsing) and requests (outbound HTTP for ViewtronCamera).

Quick Start -- Receiving Events

Set up a server that listens for camera HTTP POST events:

from viewtron import ViewtronServer, ViewtronEvent

def handle_event(event, client_ip):
    print(f"{event.category} from {client_ip}")
    if event.category == "lpr":
        print(f"Plate: {event.get_plate_number()}")

server = ViewtronServer(port=5050, on_event=handle_event)
server.serve_forever()

Configure your camera or NVR to send HTTP POST events to http://\<your-ip>:5050. The server handles persistent connections, keepalive responses, and XML parsing automatically.

Quick Start -- Controlling a Camera

Send commands to a camera using its local HTTP API:

from viewtron import ViewtronCamera

camera = ViewtronCamera("192.168.1.108", "admin", "password123")
info = camera.get_device_info()
print(info["deviceName"])

# Add a plate to the allow list
camera.add_plate("ABC1234", group_id="1")

ViewtronCamera uses Basic HTTP authentication. The camera must be reachable on your local network.

Architecture

The SDK has two independent data flows -- inbound events and outbound commands.

Inbound Events (ViewtronServer)

Viewtron cameras and NVRs push AI detection events to your server via HTTP POST. The XML payload is parsed into typed Python objects.

Camera/NVR  -->  HTTP POST (XML)  -->  ViewtronServer  -->  ViewtronEvent()  -->  your callback

1. You start a ViewtronServer on a port of your choice.
2. You configure the camera/NVR to POST events to your server's IP and port.
3. The camera maintains a persistent HTTP/1.1 connection and sends keepalives every 30 seconds.
4. When an AI detection fires, the camera sends an XML payload containing the event type, metadata, and optionally base64-encoded images.
5. ViewtronEvent() parses the XML, detects IPC v1.x vs NVR v2.0 format, and returns the correct event object.
6. Your on_event callback receives the parsed event and the camera's IP address.

Keepalives, alarm status messages, and unrecognized XML are filtered out -- your callback only receives real detection events.

Outbound Commands (ViewtronCamera)

Your application sends HTTP requests to the camera's built-in web API.

Your code  -->  ViewtronCamera  -->  HTTP GET/POST (XML)  -->  Camera

ViewtronCamera wraps the raw XML API with Python methods for device info queries and license plate database management (add, get, modify, delete).

Event Categories

Every event object has a .category string that tells you what type of detection triggered it:

Category	Description	Example Alarm Types
lpr	License plate recognition	VEHICE (IPC), vehicle (NVR)
face	Face detection	VFD (IPC), videoFaceDetect (NVR)
intrusion	Perimeter/zone detection -- line crossing, region intrusion, zone entry/exit, loitering	PEA, AOIENTRY, AOILEAVE, LOITER (IPC), regionIntrusion, lineCrossing (NVR)
counting	People/vehicle counting by line or area	PASSLINECOUNT, TRAFFIC (IPC), targetCountingByLine, targetCountingByArea (NVR)
metadata	Video metadata events	VSD (IPC), videoMetadata (NVR)
traject	Smart tracking -- continuous target position data sent multiple times per second	Traject list data (IPC and NVR)

Route events using event.category:

def handle_event(event, client_ip):
    if event.category == "lpr":
        plate = event.get_plate_number()
        group = event.get_plate_group()
        print(f"Plate {plate} (group: {group})")

    elif event.category == "intrusion":
        alarm = event.get_alarm_type()
        print(f"Intrusion: {alarm}")

    elif event.category == "face":
        # NVR v2.0 provides demographics
        if hasattr(event, 'face_age'):
            print(f"Face: age={event.get_face_age()}, sex={event.get_face_sex()}")

    elif event.category == "traject":
        for target in event.targets:
            print(f"Target {target['target_id']}: {target['target_type']} at {target['rect']}")

IPC vs NVR

Viewtron devices use two different XML API versions:

• IPC (IP Camera) -- v1.x format. Events come directly from the camera. Alarm types are uppercase codes like VEHICE, VFD, PEA.
• NVR (Network Video Recorder) -- v2.0 format. Events are forwarded from cameras connected to the NVR. Alarm types are camelCase strings like vehicle, videoFaceDetect, regionIntrusion.

You do not need to handle this difference. ViewtronEvent() detects the API version automatically and returns the correct event class. The .category value is the same for both -- "lpr" whether it came from an IPC or NVR.

Where the formats do differ in available data:

Feature	IPC (v1.x)	NVR (v2.0)
Plate group	Fixed: whiteList, blackList, temporaryList	User-defined group names (e.g., "Residents")
Vehicle attributes	Not available	Brand, color, type, model
Plate owner	Not available	car_owner from NVR database
Face demographics	Not available	Age, sex, glasses, mask
Channel ID	N/A (direct connection)	NVR channel number

Python Requirements

• Python 3.8+
• Dependencies (installed automatically): xmltodict, requests

What's Next

Detailed reference pages for each component:

• ViewtronServer -- server setup, callbacks (on_event, on_connect, on_raw), threading model
• ViewtronEvent -- event parsing, category routing, what returns None
• LPR Events -- plate number, plate group, vehicle attributes, IPC vs NVR differences
• Intrusion Events -- perimeter, line crossing, zone entry/exit, loitering
• Face Detection Events -- facial analysis, NVR v2.0 demographics
• Counting Events -- people and vehicle counting by line or area
• Images -- extracting overview and target crop images from events
• ViewtronCamera -- camera control, device info, plate database management