Skip to main content

Face Detection Events

Face detection events are generated when a camera detects a human face. All face events have category == "face".

Two classes handle face events:

  • FaceDetection -- IPC v1.x format (smartType: VFD or VFD_MATCH)
  • FaceDetectionV2 -- NVR v2.0 format (smartType: videoFaceDetect)

Your code does not need to distinguish between them for basic face detection. Both classes set category to "face" and provide source/target images. The difference is that NVR v2.0 adds demographic attributes (age, sex, glasses, mask) that IPC v1.x cameras cannot provide.

IPC vs NVR Comparison​

FeatureIPC (FaceDetection)NVR (FaceDetectionV2)
Face detectedYesYes
Age estimateNoYes
SexNoYes
GlassesNoYes
MaskNoYes
Face crop imageYes (target image)Yes (target image)
Overview imageYes (source image)Yes (source image)
Channel IDNoYes

NVR Face Attributes​

These methods are only available on FaceDetectionV2 (NVR v2.0) events:

MethodReturnsExample
get_face_age()str"25", "35"
get_face_sex()str"male", "female"
get_face_glasses()str"yes", "no"
get_face_mask()str"yes", "no"

All four methods return an empty string if the attribute is not present in the XML payload.

Code Examples​

Basic Face Detection​

Works with both IPC and NVR events:

def handle_event(event, client_ip):
    if event.category == "face":
        camera = event.get_ip_cam()
        timestamp = event.get_time_stamp_formatted()
        print(f"[{timestamp}] Face detected on {camera}")

NVR Face Attributes​

Use isinstance to check whether the event carries demographic data:

from viewtron.events import FaceDetectionV2

def handle_event(event, client_ip):
    if event.category == "face":
        print(f"Face detected on {event.get_ip_cam()}")

        # NVR v2.0 provides demographic attributes
        if isinstance(event, FaceDetectionV2):
            print(f"  Age: {event.get_face_age()}")
            print(f"  Sex: {event.get_face_sex()}")
            print(f"  Glasses: {event.get_face_glasses()}")
            print(f"  Mask: {event.get_face_mask()}")

Saving Face Crop Images​

Every face event includes two images -- an overview (source) showing the full scene, and a crop (target) showing just the detected face:

def handle_event(event, client_ip):
    if event.category == "face":
        timestamp = event.get_time_stamp()

        # Save the overview image
        if event.source_image_exists():
            with open(f"face_{timestamp}_scene.jpg", "wb") as f:
                f.write(event.get_source_image_bytes())

        # Save the cropped face image
        if event.target_image_exists():
            with open(f"face_{timestamp}_crop.jpg", "wb") as f:
                f.write(event.get_target_image_bytes())

IPC Limitations​

IPC v1.x face detection (FaceDetection class) provides:

  • Face detected notification
  • Source image (overview) and target image (face crop)
  • Camera name and timestamp

It does not provide age, sex, glasses, or mask attributes. These require an NVR running firmware v2.0+.