cv::dnn::readNet (ONNX) の使い方【OpenCV/C++】〜ONNXモデルを読み込んで推論する〜

OpenCV for C++
📌 準備: OpenCV の環境構築がまだの方はこちら → C++ 環境構築ガイド / C#(OpenCvSharp)セットアップ

cv::dnn::readNet (ONNX) の使い方【OpenCV/C++】〜ONNXモデルを読み込んで推論する〜

OpenCV の cv::dnn::readNet を使うと、PyTorch や ONNX Runtime を使わずに C++ だけで ONNX モデルの推論が完結します。外部ライブラリへの依存を最小限に抑えながら、画像分類・物体検出・顔認識など幅広いタスクに応用できます。

最小の呼び出しは以下の2行です。

cv::dnn::Net net = cv::dnn::readNet("model.onnx");
cv::Mat blob = cv::dnn::blobFromImage(img, 1.0/255.0, cv::Size(224,224), cv::Scalar(), true);

動作環境

  • OpenCV 4.x(dnn モジュールが有効なビルド)
  • コンパイル例:
g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o main

環境構築がまだの方は環境構築ガイドを先にどうぞ。

基本の使い方

ここでは ImageNet 用の 1000 クラス分類モデル(model.onnx・入力 224×224 RGB)を例にします。

#include <opencv2/opencv.hpp>
#include <opencv2/dnn.hpp>
#include <iostream>
#include <vector>
#include <string>

int main()
{
    // --- 1. モデルの読み込み ---
    cv::dnn::Net net = cv::dnn::readNet("model.onnx");
    if (net.empty()) {
        std::cerr << "モデルの読み込みに失敗しました" << std::endl;
        return -1;
    }

    // CPU 推論(CUDA を使う場合は DNN_BACKEND_CUDA / DNN_TARGET_CUDA を指定)
    net.setPreferableBackend(cv::dnn::DNN_BACKEND_OPENCV);
    net.setPreferableTarget(cv::dnn::DNN_TARGET_CPU);

    // --- 2. 入力画像の前処理 ---
    cv::Mat img = cv::imread("input.jpg");
    if (img.empty()) {
        std::cerr << "画像の読み込みに失敗しました" << std::endl;
        return -1;
    }

    // blobFromImage: リサイズ・正規化・BGR→RGB変換・NCHW 変換をまとめて実行
    cv::Mat blob = cv::dnn::blobFromImage(
        img,
        1.0 / 255.0,          // スケール: ピクセル値を [0,1] に正規化
        cv::Size(224, 224),   // モデルの入力サイズ
        cv::Scalar(0, 0, 0),  // 減算する平均値(ImageNet mean を使う場合は調整)
        true,                 // BGR → RGB に変換
        false                 // クロップしない
    );

    // --- 3. 推論実行 ---
    net.setInput(blob);
    cv::Mat output = net.forward(); // shape: [1, 1000]

    // --- 4. 結果の取得(最大スコアのクラスインデックス)---
    cv::Point classIdPoint;
    double confidence;
    cv::minMaxLoc(output.reshape(1, 1), nullptr, &confidence, nullptr, &classIdPoint);
    int classId = classIdPoint.x;

    std::cout << "ClassID: " << classId
              << "  Confidence: " << confidence << std::endl;

    return 0;
}

実行結果

ClassID: 144  Confidence: 17.2668

値はモデルと入力画像によって変わります(上は ONNX Model Zoo の SqueezeNet 1.1 での例)。多くの分類モデルの出力は softmax をかける前のスコアなので、Confidence は確率ではありません。

行ごとの解説

処理 ポイント
readNet("model.onnx") 拡張子から ONNX 形式を自動判別。empty() で失敗チェックを必ず行う
setPreferableBackend/Target CPU 推論なら DNN_BACKEND_OPENCV + DNN_TARGET_CPU。CUDA 環境なら DNN_BACKEND_CUDA + DNN_TARGET_CUDA
blobFromImage 前処理(リサイズ・正規化・チャンネル順変換・NCHW 整形)を 1 関数で実施
net.setInput(blob) ネットワークの入力層にテンソルをセット
net.forward() 引数なしで最終出力層の結果を取得
minMaxLoc 1D に reshape してから最大値インデックスを取得

引数と戻り値

cv::dnn::readNet

引数 型 説明
model const String& モデルファイルのパス(.onnx / .pb / .weights 等)
config const String& 設定ファイルのパス(ONNX の場合は省略可、デフォルト "")
framework const String& フレームワーク名(省略時は拡張子から自動判別、デフォルト "")
戻り値 cv::dnn::Net 読み込んだネットワークオブジェクト

cv::dnn::blobFromImage(主要引数)

引数 型 説明
image InputArray 入力画像
scalefactor double ピクセル値へのスケール係数
size Size 出力サイズ(モデルの入力解像度に合わせる)
mean Scalar 各チャンネルから減算する平均値
swapRB bool BGR→RGB 変換フラグ
crop bool リサイズ後にセンタークロップするか
戻り値 cv::Mat 4D テンソル(NCHW 形式)

実践例

複数出力層を持つ物体検出モデル(例: YuNet / YOLO 系)

物体検出モデルは出力が複数あることが多いため、getUnconnectedOutLayersNames() で出力層名を取得し、forward のオーバーロードを使います。

#include <opencv2/opencv.hpp>
#include <opencv2/dnn.hpp>
#include <iostream>
#include <vector>
#include <string>

int main()
{
    cv::dnn::Net net = cv::dnn::readNet("detector.onnx");
    if (net.empty()) {
        std::cerr << "モデルの読み込みに失敗しました" << std::endl;
        return -1;
    }
    net.setPreferableBackend(cv::dnn::DNN_BACKEND_OPENCV);
    net.setPreferableTarget(cv::dnn::DNN_TARGET_CPU);

    cv::Mat img = cv::imread("input.jpg");
    if (img.empty()) {
        std::cerr << "画像の読み込みに失敗しました" << std::endl;
        return -1;
    }

    // 入力を 640×640 にリサイズ(モデルに合わせて変更)
    cv::Mat blob = cv::dnn::blobFromImage(
        img, 1.0 / 255.0, cv::Size(640, 640), cv::Scalar(), true, false);

    net.setInput(blob);

    // 出力層名を自動取得
    std::vector<std::string> outNames = net.getUnconnectedOutLayersNames();

    // 複数出力を受け取る
    std::vector<cv::Mat> outputs;
    net.forward(outputs, outNames);

    // outputs[0] の shape をデバッグ出力
    for (size_t i = 0; i < outputs.size(); ++i) {
        std::cout << "output[" << i << "] size: "
                  << outputs[i].size << std::endl;
    }

    return 0;
}

CUDA バックエンドへの切り替え

CUDA 対応 OpenCV がある環境では、バックエンドを変えるだけで GPU 推論に切り替えられます。

net.setPreferableBackend(cv::dnn::DNN_BACKEND_CUDA);
net.setPreferableTarget(cv::dnn::DNN_TARGET_CUDA);

推論ループの外で 1 回だけ呼び出してください。setInput / forward のコードはそのままで機能します。

つまずきポイント

⚠️ blobFromImage のスケール・平均値がモデルと合っていない

最もよくある推論精度の問題です。PyTorch で学習したモデルであれば scalefactor=1/255.0 かつ mean=Scalar(0.485*255, 0.456*255, 0.406*255)(ImageNet mean)が一般的ですが、モデルによって異なります。標準偏差(0.229, 0.224, 0.225)での割り算も必要なモデルでは、blobFromImage の scalefactor は1つの値しか取れないため、OpenCV 4.8 以降の cv::dnn::blobFromImageWithParams(Image2BlobParams の scalefactor にチャンネルごとの値を指定)を使います。モデルの前処理仕様を必ず確認してください。スケールや平均値のズレは推論が通っても出力が全く意味をなさない原因になります。

⚠️ net.empty() だけでは読み込み失敗を捕まえられない

readNet はファイルが存在しない・破損しているとき、空の Net を返すのではなく cv::Exception を投げます(例: Can't read ONNX file: model.onnx / Failed to parse ONNX model: model.onnx)。try-catch を組み合わせて使うのが安全です。

try {
    cv::dnn::Net net = cv::dnn::readNet("model.onnx");
    if (net.empty()) { /* ... */ }
} catch (const cv::Exception& e) {
    std::cerr << e.what() << std::endl;
}

⚠️ ONNX の opset バージョンが OpenCV dnn でサポートされていない

OpenCV 4.x の dnn モジュールは ONNX の全 op をサポートしているわけではありません。PyTorch でエクスポートする際は opset_version=11 や 12 など、比較的枯れたバージョンを指定すると互換性が上がります。未対応の op を含むモデルを読み込むと、Can't create layer "..." of type "Unique" のように op 名を含むエラーが出ます。

関連する関数

  • cv::dnn::readNetFromONNX — ONNX 専用の読み込み関数。readNet と実質同じですが明示的に ONNX を指定できます
  • cv::dnn::blobFromImages — バッチ処理用(複数画像を一括で blob 化)
  • cv::dnn::NMSBoxes — 物体検出後の Non-Maximum Suppression に使用
  • cv::dnn::Net::getPerfProfile — 各レイヤーの推論時間をプロファイリング

物体検出の後段で検出結果を追跡したい場合は、cv::KalmanFilter の使い方【OpenCV/C++】〜カルマンフィルタで物体追跡〜やcv::calcOpticalFlowPyrLK の使い方【OpenCV/C++】〜LK法でオプティカルフローを追跡する〜と組み合わせると実用的なパイプラインが組めます。

まとめ

  • cv::dnn::readNet("model.onnx") で ONNX モデルを C++ だけで読み込める
  • blobFromImage で前処理を一括化し、setInput → forward で推論まで完結する
  • blobFromImage のスケール・平均値・swapRB はモデルの学習時設定に合わせることが精度の要

🛠 画像処理のプロが開発するSDK/API

本ブログを運営するスワローインキュベートは、OpenCV ベースのなりすまし判定SDK/API(C++製・OpenCV 4.10)を開発しています。顔認証システムへの組み込み実績多数。

→ 顔認証のなりすまし対策 設計チェックリスト(当ブログ)
→ なりすまし判定SDK/APIの詳細を見る
→ API仕様書・サンプルコード

タイトルとURLをコピーしました