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仕様書・サンプルコード

