> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run the Image Classification Sample Application

> Run the gst-ai-classification sample application.

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.

<img src="https://mintcdn.com/qualcomm-prod/L-jqwrTTz49ZAgVX/Key-Documents/AI-Developer-Workflow/_images/gst_ai_classification_pipeline.svg?fit=max&auto=format&n=L-jqwrTTz49ZAgVX&q=85&s=09014ef9b320471e74bee98c493fc64a" alt="gst-ai-classification pipeline diagram" width="1382" height="718" data-path="Key-Documents/AI-Developer-Workflow/_images/gst_ai_classification_pipeline.svg" />

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

1. 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](https://dragonwingdocs.qualcomm.com/Technologies/Ethernet/get-started-with-ethernet#set-up-an-ssh-connection) to enable Wi-Fi and SSH on the device.

2. On the host computer, set the user environment variable:

   ```shell theme={null}
   export USER=root
   ```

3. Sign in to the target device using SSH:

   ```shell theme={null}
   ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
   ```

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

   ```shell theme={null}
   cd /tmp
   curl -fsSL https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/download_artifacts.sh | bash
   ```

5. (Optional) Download the YOLOv8 model, which is not included in the default download.

   Use one of the following methods:

   <Tabs>
     <Tab title="Download with a script">
       1. Create a [Qualcomm AI Hub account](https://app.aihub.qualcomm.com/account/).

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

       3. Run the following commands on the host computer:

          ```shell theme={null}
          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:

          ```shell theme={null}
          ./export_model.sh --api-key=<API_KEY>
          ```

          The models are downloaded to the `export_assets` directory.

       4. Copy the model to the `/etc/models/` directory on the device:

          ```shell theme={null}
          scp <working-directory>/export_assets/yolov8_det-tflite-w8a8/yolov8_det.tflite $USER@<IP_ADDRESS_OF_TARGET_DEVICE>:/etc/models/
          ```
     </Tab>

     <Tab title="Export with AI Hub APIs">
       Use the [YOLOv8-Detection-Quantized](https://github.com/qualcomm/ai-hub-models/tree/v0.52.0/src/qai_hub_models/models/yolov8_det) model from AI Hub.

       Current releases use the following SDK versions:

       * Qualcomm Linux (GA 2.0): Qualcomm AI Runtime SDK v2.47.0.260601

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

       ```shell theme={null}
       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.47" --profile-options "--qairt_version 2.47"
       ```

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

       ```shell theme={null}
       qairt-net-run --version
       ```

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

       ```shell theme={null}
       qai-hub list-frameworks
       ```

       To list supported devices, run:

       ```shell theme={null}
       qai-hub list-devices
       ```

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

       ```shell theme={null}
       python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit"
       ```
     </Tab>

     <Tab title="Generate a batch model">
       To change the batch size, update `<N>` in the following export command:

       ```shell theme={null}
       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:

       ```shell theme={null}
       python -m qai_hub_models.models.yolov8_det.export --quantize w8a8 --target-runtime=tflite --device="Dragonwing RB3 Gen 2 Vision Kit" --batch-size 4
       ```
     </Tab>
   </Tabs>

## Run the sample application

1. On the host computer, set the user environment variable:

   ```shell theme={null}
   export USER=root
   ```

2. Sign in to the device using SSH:

   ```shell theme={null}
   ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
   ```

3. Run the sample application:

   ```shell theme={null}
   gst-ai-classification --config-file=/etc/configs/config_classification.json
   ```

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

   ```shell theme={null}
   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

<Info>
  This section uses the following default file locations:

  * `/etc/models/` — model files
  * `/etc/labels/` — label files
  * `/etc/media/` — video files
  * `/etc/configs/` — configuration files
</Info>

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

**Configuration template:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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`      | <ul><li>`snpe`: Qualcomm Neural Processing SDK</li><li>`tflite`: LiteRT</li><li>`qnn`: Qualcomm AI Engine Direct</li><li>`onnx`: ONNX Runtime</li></ul> |
| `runtime`           | <ul><li>`cpu`</li><li>`gpu`</li><li>`dsp`</li></ul>                                                                                                     |
| `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`       | <ul><li>`waylandsink`: display on Wayland</li><li>`filesink`: save to file</li><li>`rtspsink`: stream to RTSP server</li></ul>                          |
| `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:

  ```shell theme={null}
  export GST_DEBUG=2
  ```

  For more troubleshooting options, see [Troubleshooting](../topic/troubleshooting).