Table of Contents

• viewtron.events
  • APIpost
    • get_alarm_description
    • get_target_types
    • get_time_stamp_formatted
    • get_time_stamp
    • get_ip_cam
    • get_alarm_type
    • get_plate_number
    • source_image_exists
    • target_image_exists
    • images_exist
    • get_source_image
    • get_target_image
    • get_source_image_bytes
    • get_target_image_bytes
  • FaceDetectionImages
  • LPR
    • get_plate_group
  • APIpostV2
    • get_source_image_bytes
    • get_target_image_bytes
  • VehicleLPR
    • get_plate_number
    • get_plate_color
    • get_car_type
    • get_car_color
    • get_car_brand
    • get_car_model
    • get_plate_group
    • get_car_owner
  • FaceDetectionV2
    • get_face_age
    • get_face_sex
    • get_face_glasses
    • get_face_mask
  • Traject
  • ViewtronEvent

viewtron.events

Viewtron Event Parser — transforms camera HTTP POST XML into Python objects.

Viewtron IP cameras send HTTP POST requests containing XML data when AI detection events occur (license plate recognition, intrusion detection, face detection, etc.). This module parses that XML into structured Python objects with a consistent interface.

Most developers should use ViewtronEvent (the factory function) or ViewtronServer rather than instantiating event classes directly.

Example:

from viewtron import ViewtronEvent

event = ViewtronEvent(xml_body) if event and event.category == "lpr": print(event.get_plate_number()) print(event.get_plate_group())

You can find Viewtron IP cameras at https://www.cctvcamerapros.com/viewtron-security-cameras-s/1476.htm

APIpost Objects

class APIpost()

Base class for IPC v1.x camera events.

Parses common fields shared by all event types: device name, alarm type, timestamp, and images. Subclasses add event-specific fields (plate number, face attributes, etc.).

Attributes:

• category str - Event category set by ViewtronEvent — "lpr", "face", "intrusion", "counting", "metadata", or "traject".
• alarm_type str - Raw alarm type from the camera XML (e.g., "VEHICE", "VFD", "PEA").
• alarm_description str - Human-readable description (e.g., "License Plate Detection").
• ip_cam str - Camera device name.
• config_version str - version attribute from the post's \<config> element, such as "1.7" or "2.1.0".
• format str - "v1" or "v2", from the major digit of config_version. A direct camera post that uses a 2.x config version is "v2" even when its body matches the IPC layout.

Notes:

Do not instantiate directly. Use ViewtronEvent(xml) instead.

get_alarm_description

def get_alarm_description()

Returns human-readable event description (e.g., "License Plate Detection").

get_target_types

def get_target_types()

Returns supported target types from the camera (person, car, motor).

get_time_stamp_formatted

def get_time_stamp_formatted()

Returns the camera event time as a string.

currentTime is read as seconds, milliseconds, or microseconds by magnitude, so a microsecond post is the camera's event time rather than the moment the post was parsed.

Returns:

• str - Timestamp like "2026-10-07 17:24:47.427999".

get_time_stamp

def get_time_stamp()

Returns current Unix timestamp as a string (used for filenames).

Returns:

• str - Unix timestamp like "1775748316".

get_ip_cam

def get_ip_cam()

Returns the camera's device name.

Returns:

• str - Device name (e.g., "Viewtron IPC").

get_alarm_type

def get_alarm_type()

Returns the raw alarm type code from the camera XML.

Returns:

• str - Alarm type (e.g., "VEHICE", "VFD", "PEA", "vehicle").

get_plate_number

def get_plate_number()

Returns the detected license plate number.

Returns:

• str - Plate number (e.g., "IB36NL") or "<NO PLATE EXISTS>" if this is not an LPR event.

source_image_exists

def source_image_exists()

Returns True if the event contains an overview/scene image.

Returns:

• bool - True if a base64-encoded overview image is available.

target_image_exists

def target_image_exists()

Returns True if the event contains a target crop image.

Returns:

• bool - True if a base64-encoded target image is available (plate crop for LPR, face crop for face detection).

images_exist

def images_exist()

Returns True if the event contains any images.

Returns:

• bool - True if either overview or target image is available.

get_source_image

def get_source_image()

Returns the overview/scene image as a base64-encoded string.

Returns:

str or None: Base64 JPEG data, or None if no image.

get_target_image

def get_target_image()

Returns the target crop image as a base64-encoded string.

Returns:

str or None: Base64 JPEG data (plate crop, face crop, etc.), or None if no image.

get_source_image_bytes

def get_source_image_bytes()

Returns the overview/scene image as decoded JPEG bytes.

Ready to save to disk, publish to MQTT, or include in notifications.

Returns:

bytes or None: JPEG image data, or None if no image.

get_target_image_bytes

def get_target_image_bytes()

Returns the target crop image as decoded JPEG bytes.

Ready to save to disk, publish to MQTT, or include in notifications. For LPR events this is the plate crop, for face detection it's the face crop.

Returns:

bytes or None: JPEG image data, or None if no image.

FaceDetectionImages Objects

class FaceDetectionImages(APIpost)

Dedicated image extractor for Face Detection (VFD + FEATURE_RESULT) events. Replaces CommonImagesLocation for FaceDetection – images are delivered differently: • Full scene image → in <sourceDataInfo><sourceBase64Data> • Face crop(s) → in each <item><targetImageData><targetBase64Data>

LPR Objects

class LPR(APIpost)

IPC v1.x License Plate Recognition event (smartType: VEHICE/VEHICLE).

Parses plate number, authorization status, and images from the camera's HTTP POST XML.

Attributes:

• plate_number str - Detected plate text (e.g., "IB36NL").
• vehicleListType str or None - Raw vehicleListType text, or None when the element is absent.
• direction str or None - "approach", "away", or None. leave in the post is normalized to "away".
• confidence float or None - Detection confidence from 0 to 100. PlateConfidence count="9900" is 99.0.
• vehicle_color str or None - carAttr/color when present.
• vehicle_brand str or None - carAttr/brand when present.
• vehicle_type str or None - carAttr/type when present.
• vehicle_model str or None - carAttr/model when present.
• plate_list str or None - whiteList, blackList, temporaryList, strangerList, or None.

Example:

event = ViewtronEvent(xml_body) if event.category == "lpr": print(event.get_plate_number()) # "IB36NL" print(event.get_plate_group()) # "whiteList" print(event.direction, event.confidence, event.plate_list)

get_plate_group

def get_plate_group()

Returns the plate's database group from the IPC camera.

The IPC camera uses fixed group names in the XML vehicleListType field. The application decides what each group means.

Returns:

• str - Plate group — "whiteList", "blackList", "temporaryList", or empty string if the plate is not in the camera's database.

  IPC camera group values (raw XML values, not UI labels):

  • "whiteList" — camera UI shows this as "Allow list"
  • "blackList" — camera UI shows this as "Block list"
  • "temporaryList" — camera UI shows this as "Temporary vehicle"
  • "" (empty) — plate is not in the database, or temporary plate with an expired date range

APIpostV2 Objects

class APIpostV2()

Base class for NVR v2.0 HTTP Posts.

Attributes:

• config_version str - version attribute from the post, such as "2.0.0" or "2.1.0".
• format str - "v2" when config_version starts with 2, otherwise "v1".

get_source_image_bytes

def get_source_image_bytes()

Returns the overview/scene image as decoded JPEG bytes.

Returns:

bytes or None: JPEG image data, or None if no image.

get_target_image_bytes

def get_target_image_bytes()

Returns the target crop image as decoded JPEG bytes.

Returns:

bytes or None: JPEG image data, or None if no image.

VehicleLPR Objects

class VehicleLPR(APIpostV2)

NVR v2.0 License Plate Recognition (smartType: vehicle).

Uses a completely different XML structure from other v2.0 alarm types:

• licensePlateListInfo instead of eventInfo + targetListInfo
• Plate number in licensePlateAttribute/licensePlateNumber
• Vehicle attributes: carType, color, brand, model
• Plate database match in licensePlateMatchInfo (groupName, carOwner, etc.)
• Target image is a plate crop inside licensePlateListInfo/item/targetImageData

Attributes:

• group_name str - NVR plate group name (e.g., "Whitelist", "Residents"). Empty string if the plate is not in the NVR database. NVR groups are user-defined — unlike IPC cameras which use fixed whiteList/blackList/temporaryList values.
• car_owner str - Owner name from the NVR plate database.
• direction str or None - "approach", "away", or None.
• confidence float or None - 0–100 detection confidence, or None. vehicle_color, vehicle_brand, vehicle_type, vehicle_model: Vehicle attributes from carAttribute. Empty values are None. get_car_color() and the other car getters still return strings.
• plate_list str or None - whiteList, blackList, temporaryList, or strangerList when the NVR group name is one of those lists. A custom group name stays on get_plate_group() and plate_list is None.

get_plate_number

def get_plate_number()

Returns the detected license plate number.

Returns:

• str - Plate number (e.g., "IB36NL") or "<NO PLATE>".

get_plate_color

def get_plate_color()

Returns the detected plate color (e.g., "blue", "yellow").

Returns:

• str - Plate color, or empty string if not detected.

get_car_type

def get_car_type()

Returns the detected vehicle type (e.g., "sedan", "SUV", "truck").

Returns:

• str - Vehicle type, or empty string if not detected.

get_car_color

def get_car_color()

Returns the detected vehicle color.

Returns:

• str - Vehicle color, or empty string if not detected.

get_car_brand

def get_car_brand()

Returns the detected vehicle brand (e.g., "Toyota", "Ford").

Returns:

• str - Vehicle brand, or empty string if not detected.

get_car_model

def get_car_model()

Returns the detected vehicle model.

Returns:

• str - Vehicle model, or empty string if not detected.

get_plate_group

def get_plate_group()

Returns the plate's database group from the NVR.

NVR plate groups are user-defined — you create groups and name them whatever you want (e.g., "Whitelist", "Residents", "Banned"). The application decides what each group means.

Returns:

• str - Group name, or empty string if the plate is not in the NVR database.

get_car_owner

def get_car_owner()

Returns the owner name from the NVR plate database.

Returns:

• str - Owner name, or empty string if not set.

FaceDetectionV2 Objects

class FaceDetectionV2(APIpostV2)

NVR v2.0 Face Detection (smartType: videoFaceDetect).

Uses faceListInfo instead of eventInfo + targetListInfo. Each face item includes attributes: age, sex, glasses, mask. Target image is a square face crop inside faceListInfo/item/targetImageData.

get_face_age

def get_face_age()

Returns estimated age of the detected face.

Returns:

• str - Age estimate (e.g., "25"), or empty string.

get_face_sex

def get_face_sex()

Returns estimated sex of the detected face.

Returns:

• str - "male" or "female", or empty string.

get_face_glasses

def get_face_glasses()

Returns whether the detected face is wearing glasses.

Returns:

• str - "yes" or "no", or empty string.

get_face_mask

def get_face_mask()

Returns whether the detected face is wearing a mask.

Returns:

• str - "yes" or "no", or empty string.

Traject Objects

class Traject()

Parsed traject (smart tracking) event from a Viewtron camera.

Traject posts are high-volume — cameras send them multiple times per second for each tracked target. Each post contains target ID, type (person/car/motor), bounding box, velocity, and direction.

Attributes:

• category - Always "traject"
• targets - List of dicts with keys: target_id, target_type, rect, velocity, direction
• device_name - Camera name from the post
• mac - Camera MAC address
• timestamp - Event timestamp
• config_version - version attribute from the post
• format - "v1" or "v2"

ViewtronEvent

def ViewtronEvent(post_body)

Parse any HTTP POST body from a Viewtron camera or NVR.

Single entry point for the SDK. Takes the raw XML string from a camera's HTTP POST, detects the API version and event type, and returns the correct parsed event object.

Arguments:

• post_body str - Raw XML string from the camera's HTTP POST body.

Returns:

Event object with a .category attribute, or None.

Possible categories and their event classes:

• "lpr" — LPR (v1.x) or VehicleLPR (v2.0). Plate number, authorization status, vehicle attributes, images.
• "face" — FaceDetection (v1.x) or FaceDetectionV2 (v2.0). Age, sex, glasses, mask attributes.
• "intrusion" — IntrusionDetection, IntrusionEntry, IntrusionExit, RegionIntrusion, LineCrossing.
• "counting" — TargetCountingByLine, TargetCountingByArea.
• "metadata" — VideoMetadata (v1.x) or VideoMetadataV2 (v2.0).
• "traject" — Traject. High-volume tracking data with target IDs, types, and bounding boxes.
• None — Keepalives, alarm status messages, unrecognized events.

Every returned event has config_version (the post's config version attribute, for example "2.1.0") and format ("v1" or "v2"). ViewtronServer reports posts that stay None through its on_unparsed callback.

Example:

from viewtron import ViewtronEvent

event = ViewtronEvent(xml_body) if event is None: return # keepalive or unrecognized

print(event.category) # "lpr" print(event.get_alarm_type()) # "VEHICE" print(event.get_alarm_description()) # "License Plate Detection"

if event.category == "lpr": print(event.get_plate_number()) # "IB36NL" print(event.get_plate_group()) # "whiteList"