> ## 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/9xxk39ukdMdHcCv-/AI-Developer-Workflow-Ubuntu/_images/gst_ai_classification_pipeline.svg?fit=max&auto=format&n=9xxk39ukdMdHcCv-&q=85&s=c1edd820a852afe4fb784430b66415a6" alt="gst-ai-classification pipeline diagram" width="1382" height="718" data-path="AI-Developer-Workflow-Ubuntu/_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

<Steps>
  <Step title="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/Ubuntu/devices/iq9075-evk/set-up-the-device#connect-over-ssh) to enable Wi-Fi and SSH on the device.
  </Step>

  <Step title="Set the user environment variable on the host computer">
    ```shell theme={null}
    export USER=ubuntu
    ```
  </Step>

  <Step title="Sign in to the target device using SSH">
    ```shell theme={null}
    ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
    ```
  </Step>

  <Step title="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:

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

  <Step title="(Optional) Download the YOLOv8 model">
    <Note>
      YoloV8 is for detection use case, not needed for classification use case.
    </Note>

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

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

          <Step title="Copy your API key">
            Go to **Settings** in the upper right corner and copy your API key.
          </Step>

          <Step title="Run the export script 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.
          </Step>

          <Step title="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>:/home/ubuntu/
            ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
            sudo cp /home/ubuntu/yolov8_det.tflite /etc/models/
            ```
          </Step>
        </Steps>
      </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:

        * Ubuntu: Qualcomm AI Runtime SDK v2.46.0.260424

        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.45" --profile-options "--qairt_version 2.45"
        ```

        Update `--qairt_version` to match the version installed on your **target 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 this command on the **host device**:

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

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

        ```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>
  </Step>
</Steps>

## Run the sample application

<Steps>
  <Step title="Set the user environment variable on the host computer">
    ```shell theme={null}
    export USER=ubuntu
    ```
  </Step>

  <Step title="Sign in to the device using SSH">
    ```shell theme={null}
    ssh $USER@<IP_ADDRESS_OF_TARGET_DEVICE>
    ```
  </Step>

  <Step title="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
    ```
  </Step>
</Steps>

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).