Run the Image Classification Sample Application - Qualcomm Dragonwing Documentation

The gst-ai-classification sample application demonstrates hardware-accelerated image classification on a video stream. The pipeline receives input from a camera, file source, Real-Time Streaming Protocol (RTSP) stream or USB camera, performs preprocessing, runs inference on the AI hardware, and displays the results on screen.

The gst-ai-classification application is part of the Qualcomm Intelligent Multimedia (QIM) SDK and is available on the device after flashing. You must push the model and label files to the device before running the application.

Download model and label files

Enable Wi-Fi and SSH on the device

The device requires an internet connection to download the artifacts needed to run sample applications. If SSH and Wi-Fi are already configured, skip this step.Follow Setup an SSH connection to enable Wi-Fi and SSH on the device.

Set the user environment variable on the host computer

export USER=ubuntu

ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>

Download and run the download_artifacts.sh script

On the target device, download and run the download_artifacts.sh script to download the model and label files:

cd /home/ubuntu 
curl -L -O https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/download_artifacts.sh
sudo chmod +x download_artifacts.sh 
sudo ./download_artifacts.sh

(Optional) Download the YOLOv8 model

YoloV8 is for detection use case, not needed for classification use case.

The YOLOv8 model is not included in the default download. Use one of the following methods:

Download with a script
Export with AI Hub APIs
Generate a batch model

Create a Qualcomm AI Hub account

Create a Qualcomm AI Hub account.

Copy your API key

Go to Settings in the upper right corner and copy your API key.

Run the export script on the host computer

curl -L -O https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/export_model.sh
chmod +x export_model.sh

Replace <API_KEY> with your API key:

./export_model.sh --api-key=<API_KEY>

The models are downloaded to the export_assets directory.

Copy the model to the /etc/models/ directory on the device

scp <working-directory>/export_assets/yolov8_det-tflite-w8a8/yolov8_det.tflite $USER@<IP_ADDRESS_OF_TARGET_DEVICE>:/home/ubuntu/
ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
sudo cp /home/ubuntu/yolov8_det.tflite /etc/models/

Use the YOLOv8-Detection-Quantized model from AI Hub.Current releases use the following SDK versions:

Ubuntu: Qualcomm AI Runtime SDK v2.46.0.260424

For example, to export the YOLOv8 QNN model, run:

python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=qnn_context_binary --device="Dragonwing RB3 Gen 2 Vision Kit" --compile-options="--qairt_version 2.45" --profile-options "--qairt_version 2.45"

Update --qairt_version to match the version installed on your target device. To check the installed version:

qairt-net-run --version

To list the QAIRT SDK versions supported by AI Hub for the export command, run this command on the host device:

qai-hub list-frameworks

To list supported devices, run this command on the host device:

qai-hub list-devices

For example, to export the YOLOv8 LiteRT model, run:

python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit"

To change the batch size, update <N> in the following export command:

python -m qai_hub_models.models.<Model_Name>.export --batch-size <N> --device="Dragonwing RB3 Gen 2 Vision Kit"

For example, to export the YOLOv8 LiteRT model with batch size 4:

python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit" --batch-size 4

Run the sample application

Set the user environment variable on the host computer

export USER=ubuntu

ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>

Run the sample application

gst-ai-classification --config-file=/etc/configs/config_classification.json

For more information about the configuration fields or available options, use the help command:

gst-ai-classification -h

The application overlays classified object labels and confidence scores on the video stream and displays the results on the configured output. To stop the application, press Ctrl+C.

Configure the application

This section uses the following default file locations:

/etc/models/ — model files
/etc/labels/ — label files
/etc/media/ — video files
/etc/configs/ — configuration files

Edit the /etc/configs/config_classification.json file to specify your model, input source, and output preferences. Configuration template:

{
  "file-path": "<path-to-input-video>",
  "ml-framework": "<snpe or tflite or qnn or onnx>",
  "model": "<path-to-model-file>",
  "labels": "<path-to-label-file>",
  "threshold": "<postprocessing threshold, integer value from 1 to 100>",
  "runtime": "<dsp, gpu, or cpu>",
  "output-type": "<waylandsink, filesink, or rtspsink>"
}

Example configuration — LiteRT model on a video file using the DSP runtime:

{
  "file-path": "/etc/media/video.mp4",
  "ml-framework": "tflite",
  "model": "/etc/models/inception_v3_quantized.tflite",
  "labels": "/etc/labels/classification.json",
  "threshold": 40,
  "runtime": "dsp"
}

JSON configuration field descriptions

Field	Description
`ml-framework`	`snpe`: Qualcomm Neural Processing SDK `tflite`: LiteRT `qnn`: Qualcomm AI Engine Direct `onnx`: ONNX Runtime
`runtime`	`cpu` `gpu` `dsp`
`output-ip-address`	Output server IP address
`port`	Output server port
`video-format`	USB camera format: `nv12`, `yuy2`, or `mjpeg`, with `width`, `height`, and `framerate` parameters
`output-file`	Name of the output file. Default: `output_classification.mp4`
`output-type`	`waylandsink`: display on Wayland `filesink`: save to file `rtspsink`: stream to RTSP server
`file-path`	Path to the input video file
`rtsp-ip-port`	RTSP input stream in the format `rtsp://<ip>:<port>/<stream>`
`camera`	Camera index: primary (`0`) or secondary (`1`)

Notes

To stop the application, press Ctrl+C.
To enable GStreamer debug logging, set the GST_DEBUG environment variable. For example, to log all warnings:
export GST_DEBUG=2
For more troubleshooting options, see Troubleshooting.

​Download model and label files

​Run the sample application

​Configure the application

​Notes

Download model and label files

Run the sample application

Configure the application

Notes