Skip to content

QPyCam Python API

The QPyCam Python API provides a way to integrate camera functionalities into Python applications. It supports live streaming, recording, RTSP, and AI-based inference with MQTT integration.

Import QPyCam

To use QPyCam in Python, import the class VideoCapture from the qpycam module:

from qpycam import VideoCapture

The VideoCapture class serves as the main entry point for the QPyCam API. It provides a flexible and configurable interface for all the powerful features of QPyCam. The workflow is as follows:

  1. Create a VideoCapture object. Most of the features are configured here using the constructor parameters.
  2. Optionally, enable the AI inference feature by calling the detect method.
  3. Start the camera and all the configured features with start method.
  4. Stop the camera with stop method.

Configure Camera (Video Source)

QPyCam supports three types of cameras: CSI, USB, and RTSP. The camera should be configured in the VideoCapture constructor. Examples for different camera types are shown below.

The CSI camera is the default camera type (camera_type=0).

camera = VideoCapture(
    camera_type=0,
    source_width=1920,
    source_height=1080,
    fps=30
)

To capture video from a USB camera, specify camera_type=1 and set the device ID:

camera = VideoCapture(
    camera_type=1,
    device_id=2,
    source_width=1280,
    source_height=720,
    fps=30
)

You can also use an RTSP stream instead of a physically connected camera as the input source:

camera = VideoCapture(
    camera_type=2,
    input_rtsp_url="rtsp://10.1.9.22:8554/live"
)

Configure Video Output

Display Video Stream

To display the live video feed on the screen, enable the display parameter:

camera = VideoCapture(
    camera_type=0,
    source_width=1920,
    source_height=1080,
    fps=30,
    display=True
)

Record Video

To record the video and save it to a file, specify the output_file and timeout parameters:

camera = VideoCapture(
    camera_type=0,
    source_width=1920,
    source_height=1080,
    fps=30,
    output_file="output.mp4",
    timeout = 5000 # milliseconds
)

With the above configuration, the video will be recorded for 5 seconds and saved as output.mp4.

Stream Video via RTSP

To start an RTSP server for remote access, specify the output_ip and output_port parameters:

camera = VideoCapture(
    camera_type=0,
    source_width=1920,
    source_height=1080,
    fps=30,
    output_ip="192.168.1.100",
    output_port=8900
)

Configure Advanced Features

Enable and Configure AI Inference

QPyCam supports various AI inference features such as:

  • Object detection
  • Classification
  • Segmentation
  • Pose estimation

Typically, QPyCam would also visualize the inference results on the video stream. The following examples show how to enable and configure the AI inference features.

camera = VideoCapture(camera_type=0)
camera.detect(
    detect_type="detection",
    module="yolov8",
    model="/opt/yolov8_quantized.tflite",
    labels="/opt/coco_labels.labels",
    threshold=70,
    results=10,
    constants="YOLOv8,q-offsets=<21.0, 0.0, 0.0>,q-scales=<3.093529462814331, 0.00390625, 1.0>;"
)

camera = VideoCapture(camera_type=0)
camera.detect(
    detect_type="classification",
    module="mobilenet",
    model="/opt/mobilenet_v2_quantized.tflite",
    labels="/opt/imagenet_labels.txt",
    constants="Mobilenet,q-offsets=<-59.0>,q-scales=<0.2386164367198944>;"
)

camera = VideoCapture(camera_type=0)
camera.detect(
    detect_type="segmentation",
    module="deeplab-argmax",
    model="/opt/deeplabv3_resnet50.tflite",
    labels="/opt/deeplabv3_resnet50.labels"
)

camera = VideoCapture(camera_type=0)
camera.detect(
    detect_type="pose",
    module="hrnet",
    model="/opt/hrnet_pose_quantized.tflite",
    labels="/opt/hrnet_pose.labels",
    constants="hrnet,q-offsets=<8.0>,q-scales=<0.0040499246679246426>;"
)

Note

In the examples above, all the files are assumed to be in the /opt directory. In practice, you will have to download the models by yourself due to the license restrictions. For how to download the models, please refer to How to Download Qualcomm AI Hub Models.

MQTT Integration

QPyCam supports sending inference results via MQTT. This feature has to be configured in the VideoCapture constructor. An example is shown below:

camera = VideoCapture(
    mqtt_ip="10.1.9.164",
    mqtt_port=1883,
    mqtt_topic="ai/detections"
)

Activate the Camera

Once all the configurations are done, you can activate the camera to perform all the configured operations:

camera.start()

Close the Camera

To stop the camera and end the capture, you can simply close it with the stop method. Alternatively, you can press Ctrl+C to terminate the process.

camera.stop()

Full Example

The following example shows how to:

  • Use a USB camera as the video source.
  • Perform object detection with YOLOv8.
  • Display the video on the device screen.
  • Stream the video via RTSP.
  • Send the inference results via MQTT.
from qpycam import VideoCapture

if __name__ == "__main__":
    try:
        # Configure the video input/output and MQTT in the constructor
        camera = VideoCapture(
            camera_type=1, # USB camera
            device_id=2,
            source_width=1920,
            source_height=1080,
            fps=30,
            display=True,
            output_ip="192.168.1.100",
            output_port=8900,
            mqtt_ip="10.1.9.164",
            mqtt_port=1883,
            mqtt_topic="ai/detections"
        )

        # Enable the AI inference feature
        camera.detect(
            detect_type="detection",
            module="yolov8",
            model="/opt/yolov8_quantized.tflite",
            labels="/opt/coco_labels.labels",
            threshold=70,
            results=10,
            constants="YOLOv8,q-offsets=<21.0, 0.0, 0.0>,q-scales=<3.093529462814331, 0.00390625, 1.0>;"
        )

        # Start the video capture and all the configured features
        camera.start()
    finally:
        # No matter if the program is terminated by the user or by the system,
        # stop the camera and all the tasks.
        if 'camera' in locals():
            camera.stop()