> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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-staging/blZpKs_b9On5nj-y/archives/2.1/Key-Documents/AI-Developer-Workflow/_images/gst_ai_classification_pipeline.svg?fit=max&auto=format&n=blZpKs_b9On5nj-y&q=85&s=b200f9d6b3900fd8952e5d3efd69fdd7" alt="gst-ai-classification pipeline diagram" width="1382" height="718" data-path="archives/2.1/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

<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/Technologies/Wi-Fi/setup-wi-fi#set-up-uart/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=root
    ```
  </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_2.x.sh script">
    ```shell theme={null}
    cd /tmp
    curl -L -O https://raw.githubusercontent.com/qualcomm/sample-apps-for-qualcomm-linux/refs/heads/main/qualcomm-linux/scripts/download_artifacts_2.x.sh
    chmod +x download_artifacts_2.x.sh 
    ./download_artifacts_2.x.sh
    ```
  </Step>

  <Step title="Enable qticamsrc">
    In the terminal of the target device, run the following command to enable camera:

    ```shell theme={null}
    echo -n "camx" > /var/data
    efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -w -f /var/data
    efivar -n 882f8c2b-9646-435f-8de5-f208ff80c1bd-VendorDtbOverlays -p
    sync
    reboot
    ```

    <Note>
      `camera` use-case is not supported on `IQ-2390`.
    </Note>
  </Step>

  <Step title="(Optional) Download the YOLOv8 model">
    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 `${HOME}/Downloads/qimsdk_samples/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>:~/Downloads/qimsdk_samples/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:

        * Qualcomm Linux (GA 2.1): Qualcomm AI Runtime SDK v2.50.0.260828

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

        ```shell theme={null}
        qai-hub-models export yolov8_det --quantize w8a8 --target-runtime=qnn_context_binary --device="Dragonwing RB3 Gen 2 Vision Kit" --compile-options="--qairt_version 2.50" --profile-options "--qairt_version 2.50"
        ```

        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}
        qai-hub-models export yolov8_det --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}
        qai-hub-models export <Model_Name> --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}
        qai-hub-models export yolov8_det --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="On the host computer, set the user environment variable">
    ```shell theme={null}
    export USER=root
    ```
  </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 application with the sample configuration file">
    To run the application with the sample configuration file, use:

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

    This command runs the application using the sample configuration in `/etc/configs/config_classification.json`.

    To view the available command-line options, run:

    ```bash theme={null}
    gst-ai-classification -h
    ```

    Press **CTRL + C** to stop the execution.
  </Step>

  <Step title="Run the application with a custom configuration file (optional)">
    You can use a custom configuration file by specifying its path with `--config-file`:

    ```bash theme={null}
    gst-ai-classification --config-file=/path/to/config_classification.json
    ```

    If `--config-file` is specified, the application uses that file. Otherwise, it searches for `config_classification.json` in the following order:

    | Priority | Location | Description |
    | :-: | :- | :- |
    | 1 | The path provided with `--config-file`. | Uses the configuration file specified on the command line. |
    | 2 | `$XDG_CONFIG_HOME/qimsdk_samples/config_classification.json` | Uses the user-defined configuration directory when the environment variable is set. |
    | 3 | `$HOME/.config/qimsdk_samples/config_classification.json` | Uses the default user configuration directory when no file is found in `XDG_CONFIG_HOME`. |
    | 4 | `/etc/configs/config_classification.json` | Uses the system-wide configuration file as the final fallback. |

    To create a user-specific configuration, copy the sample file to the user configuration directory:

    ```bash theme={null}
    export XDG_CONFIG_HOME="$HOME/.config"
    mkdir -p "$XDG_CONFIG_HOME/qimsdk_samples"
    cp /etc/configs/config_classification.json "$XDG_CONFIG_HOME/qimsdk_samples/config_classification.json"
    ```

    <Note>
      Modify the copied configuration file to specify the required parameters. The custom configuration file must follow the schema defined in [`configurations`](#configure-the-application).
    </Note>

    Run the application:

    ```bash theme={null}
    gst-ai-classification
    ```
  </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

Edit the `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": "video.mp4",
  "ml-framework": "tflite",
  "model":" inception_v3_quantized.tflite",
  "labels": "classification.json",
  "threshold": 40,
  "runtime": "dsp",
  "output-type": "waylandsink"
}
```

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

  * `${HOME}/Downloads/qimsdk_samples/models/` — model files
  * `${HOME}/Downloads/qimsdk_samples/labels/` — label files
  * `${HOME}/Downloads/qimsdk_samples/media/` — video files
</Info>

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