# 超解像プラグインを開発する

このセクションでは、新しい超解像（qtimlvsuperresolution）プラグインの開発方法を説明します。

注釈

- これらの説明は、`imsdk.lnx.2.0.0.r1-rel` リリースに基づいています。
- このセクションは、経験豊富な開発者に向けた、既存のプラグインをベースにして超解像などの未サポートのユース・ケースに対応するためのQualcomm IM SDKプラグインの作成に関するガイダンスとなっています。
- カスタムGStreamerプラグインの作成は高度な作業であり、経験豊富なGStreamer開発者のみを対象としています。
- この作業については、オープンソースの世界やGStreamerの公式ポータルで、豊富なチュートリアルが公開されています。
- このガイドをテンプレートとして使用し、オープンソースのリソースを活用してカスタム・プラグインの開発について理解します。

前提条件

- アプリケーション/プラグインのコードをダウンロードしてコンパイルするには、eSDKをセットアップする必要があります。eSDKをセットアップしてプラグイン・コードをダウンロードしコンパイルする方法については、[Qualcomm Intelligent Multimediaソフトウェア開発キット（IM SDK）クイック・スタート・ガイド](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-51/introduction.html) を参照してください。
- 参考として、このプロセスでは既存のプラグインのソース・コードを使用します。

    [CodeLinaro/ le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/tree/imsdk.lnx.2.0.0.r1-rel?ref_type=heads)

## プラグインのディレクトリ構造

gst-plugins-qti-oss/gst-plugins-mlv<plugin-name>/
        CMakeLists.txt
        config.h.in
        mlv<plugin-name>.c
        mlv<plugin-name>.h
        modules/
            CMakeLists.txt
            ml-video-<plugin-name>-module.h
            ml-v<plugin-name>-<module-name>.c
    Copy to clipboard

## 超解像プラグインの作成手順

1. プラグイン・ヘッダー（`gst-plugins-mlvsuperresolution/mlvsuperresolution.h`）を作成します。

    参考として、既存のプラグインを使用します。

    [gst-plugin-mlvsegmentation/mlvsegmentation.h·imsdk.lnx.2.0.0.r2-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r2-rel/gst-plugin-mlvsegmentation/mlvsegmentation.h?ref_type=heads)

    1. 必要なヘッダーをインポートします。
    2. 処理に必要なデータ変数を含む構造体を作成します。

        超解像の継承チェーンの例：GObject &gt; GstObject &gt; GstElement &gt; GstBaseTransform

        GstBaseTransformは、出力のsizeとcapsが入力のsizeとcapsによって完全に決まるエレメントに適しています。

struct _GstMLVideoSuperresolution {GstBaseTransform   parent;
                                               GstMLInfo          *mlinfo;
                                               GstVideoInfo       *vinfo;
                                               GstBufferPool      *outpool;
                                               GstMLModule        *module;
                                               gint               mdlenum;
                                               GstStructure       *mlconstants;
            };
            
            struct _GstMLVideoSuperresolutionClass {GstBaseTransformClass parent;
            };
            Copy to clipboard

注釈

超解像ではラベル変数は必要ありません。

ラベル変数とその使用法をコードから削除してください。
2. プラグイン実装ファイル（`gst-plugins-mlvsuperresolution/mlvsuperresolution.c`）を作成します。

    参考として、既存のプラグインを使用します。

    [gst-plugin-mlvsegmentation/mlvsegmentation.c imsdk.lnx.2.0.0.r2-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r2-rel/gst-plugin-mlvsegmentation/mlvsegmentation.c?ref_type=heads)

    1. `mlvsuperresolution.h` などの必要なヘッダーをインポートします。
    2. capsを定義します

        - ビデオ・フォーマット

#define GST_ML_VIDEO_SUPERRESOLUTION_VIDEO_FORMATS "{ RGBA, BGRA, ARGB, ABGR, RGBx, BGRx, xRGB, xBGR, RGB, BGR }"
                Copy to clipboard
        - src caps

#define GST_ML_VIDEO_SUPER_RESOLUTION_SRC_CAPS \
                    "video/x-raw, " \
                    "format = (string) " GST_ML_VIDEO_SUPER_RESOLUTION_VIDEO_FORMATS "; " \
                    "video/x-raw(" GST_CAPS_FEATURE_MEMORY_GBM "), " \
                    "format = (string) " GST_ML_VIDEO_SUPER_RESOLUTION_VIDEO_FORMATS
                Copy to clipboard
        - sink caps

#define GST_ML_VIDEO_SUPER_RESOLUTION_SINK_CAPS \
                       "neural-network/tensors"
                Copy to clipboard
    3. 以下の関数を実装します

        - Init

            1. カスタム・プラグインを登録します。登録が完了すると、`gst_element_factory_make("plugin-name","plugin-name");` を使用して、リファレンス・アプリのプラグインにアクセスできます。

static gboolean plugin_init(GstPlugin * plugin);
                    Copy to clipboard
            2. デフォルトのパラメーターでsuperresolutionを初期化します。これにより、出力バッファを制御できるようになります。入力バッファを受信すると、`gst_ml_video_super_resolution_prepare_output_buffer` を呼び出して、出力バッファを割り当てます。

static void gst_ml_video_super_resolution_init(GstMLVideoSuperResolution * super_resolution)
                    Copy to clipboard
            3. コールバック関数を関数ポインタに初期化し、capsとデフォルトのプロパティを設定します。

static void gst_ml_video_super_resolution_class_init(GstMLVideoSuperResolutionClass * klass)
                    Copy to clipboard
        - バッファ管理

            1. ネゴシエーションされたcapsに基づいて、<abbr title="Graphics Buffer Manager">graphics Buffer Manager (GBM)</abbr> またはION Memoryを割り当てます。

static GstBufferPool * gst_ml_video_super_resolution_create_pool (GstMLVideoSuperResolution * super_resolution,
                                                                                      GstCaps * caps)
                    Copy to clipboard
            2. capsに基づいて適切なバッファ・プール構成を確保します。

gst_ml_video_super_resolution_decide_allocation (GstBaseTransform * base,
                                                                     GstQuery * query)
                    Copy to clipboard
            3. 出力バッファが、capsに基づいてプールから確実に割り当てられるようにします。

static GstFlowReturn gst_ml_video_super_resolution_prepare_output_buffer (GstBaseTransform * base,
                                                                                              GstBuffer * inbuffer,
                                                                                              GstBuffer ** outbuffer)
                    Copy to clipboard
        - Caps

            1. モジュールを検証した後、モジュールのcapsから入力capsと出力capsを収集します。

static gboolean gst_ml_video_super_resolution_set_caps (GstBaseTransform * base,
                                                                            GstCaps * incaps,
                                                                            GstCaps * outcaps)
                    Copy to clipboard
            2. ネゴシエーションされたcapsを修正します。

static GstCaps * gst_ml_video_super_resolution_fixate_caps (GstBaseTransform * base,
                                                                                GstPadDirection direction,
                                                                                GstCaps * incaps,
                                                                                GstCaps * outcaps)
                    Copy to clipboard
            3. video/x-raw、video/x-text、format、height、widthのような指定されたcapsが有効かどうかを確認します。

static gboolean caps_has_feature (const GstCaps * caps,
                                                      const gchar * feature)
                    Copy to clipboard
            4. static capsをregular capsに変換します。

static GstCaps * gst_ml_video_super_resolution_src_caps (void)
                    Copy to clipboard
            5. static capsをregular capsに変換します。

static GstCaps * gst_ml_video_super_resolution_sink_caps (void)
                    Copy to clipboard
        - 変換

            1. sink capsとsrc capsを相互に変換します。

static GstCaps * gst_ml_video_super_resolution_transform_caps (GstBaseTransform * base,
                                                                                   GstPadDirection direction,
                                                                                   GstCaps * caps,
                                                                                   GstCaps * filter)
                    Copy to clipboard
            2. 推論の実行後、モジュールに基づいてポストプロセス関数（`gst_ml_video_superresolution_module_execute`）が呼び出されます。

gst_ml_video_super_resolution_transform (GstBaseTransform * base,
                                                             GstBuffer * inbuffer,
                                                             GstBuffer * outbuffer)
                    Copy to clipboard
        - プロパティ

            1. モジュールや定数などのプラグインのプロパティを設定します。

static void gst_ml_video_super_resolution_set_property (GObject * object,
                                                                           guint prop_id,
                                                                           const GValue * value,
                                                                           GParamSpec * pspec)
                    Copy to clipboard
            2. モジュールや定数などのプラグインのプロパティを読み込みます。

static void gst_ml_video_super_resolution_get_property (GObject * object,
                                                                            guint prop_id,
                                                                            GValue * value,
                                                                            GParamSpec * pspec)
                    Copy to clipboard
        - De-init

            1. 割り当てられたバッファをすべて解放します。

static void gst_ml_video_super_resolution_finalize (GObject * object)
                    Copy to clipboard
        - テキスト/バウンディング・ボックスを表示します（ユース・ケースのみに基づく、超解像には不要）

            1. 出力フレームに結果をオーバーレイします

static gboolean gst_ml_video_<plugin-name>_fill_video_output(GstMLVideoDetection * detection,
                                                                                 GArray * predictions,
                                                                                 GstBuffer * buffer);
                    Copy to clipboard
    4. `gst-plugins-mlvsuperresolution/CMakeLists.txt` ファイル内のプラグイン名を更新します。

        参考として、既存のプラグインを使用します。

        [gst-plugin-mlvsegmentation/CMakeLists.txt imsdk.lnx.2.0.0.r2-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r2-rel/gst-plugin-mlvsegmentation/CMakeLists.txt?ref_type=heads)

        既存のプラグインの `config.h.in` ファイルを再利用します。

        [gst-plugin-mlvsegmentation/config.h.in imsdk.lnx.2.0.0.r2-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r2-rel/gst-plugin-mlvsegmentation/config.h.in?ref_type=heads)

## モジュールの概要

- モデルにはそれぞれ固有のポストプロセス手順があり、推論バッファに対して実行し、それに応じて出力バッファを更新する必要があります。たとえば、超解像やセグメンテーションのためのRGBピクセルの入力や、検出のためのバウンディング・ボックスの計算などがあります。
- これらのポストプロセス手順は、`<module-name>.c` 内で定義されます。モジュール・ディレクトリには、以下のような構成のファイルの一覧が含まれます。

modules/
             "gst-plugins-mlvsuperresolution/modules/ml-vsuperresolution-<module-name1>.c"
             "gst-plugins-mlvsuperresolution/modules/ml-vsuperresolution-<module-name2>.c"
        
        Here <module-name> represents the model's name like srnet for superresolution.
        Copy to clipboard

## srnetモジュールの作成手順

1. モジュールのヘッダー `gst-plugins-qti-oss/gst-plugin-base/gst/ml/ml-module-video-super-resolution.h` を作成します。

    参考として、既存のプラグインを使用します。

    [gst-plugin-base/gst/ml/ml-module-video-super-resolution.h imsdk.lnx.2.0.0.r2-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r2-rel/gst-plugin-base/gst/ml/ml-module-video-super-resolution.h?ref_type=heads)

    1. 必要な `gst` ヘッダーをインポートします。
    2. `execute` 関数を作成します。

GST_API gboolean gst_ml_module_video_super_resolution_execute(GstMLModule   * module,
                                                                          GstMLFrame    * mlframe,
                                                                          GstVideoFrame * vframe);
            Copy to clipboard

        この関数は、`ml-vsuperresolution-<module-name>.c` ファイル内で定義されているポストプロセス関数（`gst_ml_module_process`）を呼び出すために必要です。
2. モジュール・ファイル `gst-plugins-mlvsuperresolution/modules/ml-vsuperresolution-srnet.c` を作成します。

    参考として、既存のプラグインを使用します。

    [gst-plugin-mlvsegmentation/modules/ml-vsegmentation-deeplab-argmax.c · imsdk.lnx.2.0.0.r1-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r1-rel/gst-plugin-mlvsegmentation/modules/ml-vsegmentation-deeplab-argmax.c?ref_type=heads)

    1. `modules/ml-video-superresolution-module.h` ヘッダーをインポートします。
    2. モデルの出力capsを定義します。

#define GST_ML_MODULE_CAPS \
                "neural-network/tensors, " \
                "type = (string) { INT8, UINT8, INT32, FLOAT32 }, " \
                "dimensions = (int) < <1, [32, 4096], [32, 4096]> >; " \
                "neural-network/tensors, " \
                "type = (string) { INT8, UINT8, INT32, FLOAT32 }, " \
                "dimensions =  (int) < <1, [32, 4096], [32, 4096], [1, 3]> >"
            Copy to clipboard

        **例**

> 
> 
> 1. AI Hubから [QuickSRNetLarge-Quantized- Qualcomm AI Hub](https://aihub.qualcomm.com/iot/models/quicksrnetlarge_quantized) モデルをダウンロードします。
>         2. LiteRTモデルの出力次元を確認します（[AI Hubモデルをアプリケーションに統合](https://docs.qualcomm.com/doc/80-70018-15BJ/topic/integrate-ai-hub-models.html) を参照）。
> 
>             - 形式：`dtype[N x H X W X C]`
>             - 上記のモジュール出力capsでは、`<1, [32, 4096], [32, 4096], [1, 3]>`
> 
>                 - `N = 1`：モデル出力のバッチ・サイズ
>                 - `H = [32,4096]` ：モデル出力の高さはこの範囲に収まる必要があります
>                 - `W= [32,4096]` ：モデル出力の幅はこの範囲に収まる必要があります
>                 - `C = [1,3]` ：モデル出力のチャネルはこの範囲に収まる必要があります
>                 - `dtype` ：量子化モデルは `int8`、非量子化モデルは `float32`
>         3. 量子化モデルの場合は、出力ノードのスケールとオフセットを確認します。
> 
> 
>             形式：`scale*(q-offset)`
    3. 以下の関数を実装します

        - Init

gpointer gst_ml_module_open (void);
                Copy to clipboard
        - De-init

void gst_ml_module_close (gpointer instance);
                Copy to clipboard
        - Caps

GstCaps *gst_ml_module_caps (void);
                Copy to clipboard
        - コンフィグ作成

gboolean gst_ml_module_configure (gpointer instance,
                                                  GstStructure * settings);
                Copy to clipboard

            モジュールのdtype、scale、offsetを確認します。
        - 逆量子化

static inline gdouble gst_ml_module_get_dequant_value (void       *data,
                                                                       GstMLType  mltype,
                                                                       guint      idx,
                                                                       gdouble    offset,
                                                                       gdouble    scale);
                Copy to clipboard

            スケール値とオフセット値を量子化モデルに渡す必要があります。
        - ポストプロセス

gboolean gst_ml_module_process (gpointer    instance,
                                                GstMLFrame  *mlframe,
                                                gpointer     output);
                Copy to clipboard
        - 推論バッファ

indata = GST_ML_FRAME_BLOCK_DATA (mlframe, 0);
                Copy to clipboard
        - 出力バッファにポストプロセス・データを入力

outdata = GST_VIDEO_FRAME_PLANE_DATA (vframe, 0);
                Copy to clipboard
        - モデルのデータ型

mltype = GST_ML_FRAME_TYPE (mlframe);
                Copy to clipboard
        - ポストプロセス（超解像用）

for (row = 0; row < GST_VIDEO_FRAME_HEIGHT (vframe row++) {
                    for (column = 0; column < GST_VIDEO_FRAME_WIDTH (vframe); column++) {
                        // Calculate the destination index.
                        idx = (((row * GST_VIDEO_FRAME_WIDTH (vframe)) + column) * bpp) + (row * padding)
                        outdata[idx] = gst_ml_module_get_dequant_value(indata, mltype, idx, submodule->qoffsets[0], submodule->qscales[0]) * 255;
                        outdata[idx + 1] = gst_ml_module_get_dequant_value(indata, mltype, idx + 1, submodule->qoffsets[0], submodule->qscales[0]) * 255;
                        outdata[idx + 2] = gst_ml_module_get_dequant_value(indata, mltype, idx + 2, submodule->qoffsets[0], submodule->qscales[0]) * 255;
                        if (bpp == 4)
                            outdata[idx + 3] = 0;
                    }
                }
                Copy to clipboard
    4. `gst-plugins-mlvsuperresolution/modules/CMakeLists.txt` ファイル内のモジュール名を更新します。

        参考として、既存のプラグインを使用します。

        [gst-plugin-mlvsegmentation/modules/CMakeLists.txt · imsdk.lnx.2.0.0.r1-rel · CodeLinaro / le / platform / vendor / qcom-opensource / gst-plugins-qti-oss · GitLab](https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/gst-plugins-qti-oss/-/blob/imsdk.lnx.2.0.0.r1-rel/gst-plugin-mlvsegmentation/modules/CMakeLists.txt?ref_type=heads)

## プラグインをコンパイルするためのBitBakeファイルの更新手順

1. 超解像プラグインのコンパイルとインストールに関する手順は、[Qualcomm IM SDKプラグインの作成](https://docs.qualcomm.com/bundle/publicresource/topics/80-70018-51/create-your-imsdk-plugin.html) に従ってください。
2. Waylandディスプレイを設定します。

ssh root@[IP address of the target device]
        Copy to clipboard

注釈

プロンプトが表示されたら、SSHシェルのパスワードとして `oelinux123` を入力します。

export XDG_RUNTIME_DIR=/dev/socket/weston && export WAYLAND_DISPLAY=wayland-1
        Copy to clipboard

qtimlvsuperresolutionプラグインを使用するGStreamerパイプラインを参照します。

gst-launch-1.0 -e --gst-debug=2,qtimltflite:7 filesrc location=/etc/media/video.mp4 ! qtdemux ! queue ! h264parse ! \
    v4l2h264dec capture-io-mode=4 output-io-mode=4 ! video/x-raw,format=NV12 ! queue ! tee name=split \
    split. ! queue ! qtivcomposer name=mixer \
    sink_0::position="<0, 0>" sink_0::dimensions="<960, 1080>" \
    sink_1::position="<960, 0>" sink_1::dimensions="<960, 1080>" \
    ! queue ! waylandsink sync=false fullscreen=true \
    split. ! qtimlvconverter ! queue ! \
    qtimltflite delegate=external external-delegate-path=libQnnTFLiteDelegate.so \
    external-delegate-options="QNNExternalDelegate,backend_type=htp;" model=/etc/models/quicksrnetlarge_quantized.tflite ! queue ! \
    qtimlvsuperresolution module=srnet constants="qsrnetlarge,q-offsets=<0.0>,q-scales=<1.0>;" ! \
    video/x-raw,width=512,height=512,format=RGB ! queue ! mixer.
    Copy to clipboard

注釈

入力ビデオの解像度は128x128x3であることが必要です。`quicksrnetlarge_quantized.tflite` モデルの入力次元が128x128x3だからです。

Last Published: Oct 15, 2025

[Previous Topic
カスタムGStreamerプラグインを開発する](https://docs.qualcomm.com/bundle/publicresource/80-70018-15BJ/topics/general-guidelines-for-developing-gstreamer-plugin.md) [Next Topic
GStreamer APIでAI Hubモデルとラベルを使用する](https://docs.qualcomm.com/bundle/publicresource/80-70018-15BJ/topics/ai-hub-qualcomm-im-sdk.md)