OpenCV + opencv_contrib を Windows でビルドする完全ガイド【C++/VS2022】

この記事では、Windows 上で OpenCV のソースコードを opencv_contrib（外部モジュール）込みで CMake を使ってビルドし、Visual Studio 2022 で使える状態にするまでの手順を解説します。

公式の Windows 向けインストーラーには contrib モジュールが含まれていません。SURF・FREAK（xfeatures2d）・顔ランドマーク検出（face モジュール）・ximgproc などを使いたい場合は、自前でソースビルドが必須です。

⚠️ SIFT は OpenCV 4.4 以降、ArUco は 4.7 以降でそれぞれ本体に統合されました。これらは contrib ビルドなしで使えます。contrib が必要な代表例は SURF・FREAK（xfeatures2d） です。

前提環境

⚠️ OpenCV 本体と opencv_contrib のバージョンは 完全に一致 させてください。マイナーバージョンのズレでも CMake Configure がエラーになります。

手順

1. Visual Studio 2022 のインストール

https://visualstudio.microsoft.com/ja/downloads/ から Community 版をダウンロードします。

インストーラーを起動したら 「C++ によるデスクトップ開発」 ワークロードにチェックを入れてインストールしてください。MSVC v143 ツールセットと Windows SDK が同時に入ります。

2. CMake のインストール

https://cmake.org/download/ から Windows x64 の .msi インストーラーをダウンロードします。

インストール中に 「Add CMake to the system PATH for all users」 を選択し、PATH を通してください。インストール後、動作確認します。

cmake --version
# cmake version 3.28.x

3. ソースコードのダウンロード

以下の 2 つをダウンロードし、展開先を揃えておくと管理が楽です。

• OpenCV 本体: https://opencv.org/releases/ → Sources をダウンロード
• opencv_contrib: https://github.com/opencv/opencv_contrib/releases → 同一バージョンの zip

展開後のディレクトリ構成（例）:

C:\opencv_src\
  opencv-4.10.0\        ← OpenCV 本体ソース
  opencv_contrib-4.10.0\  ← contrib ソース
C:\opencv_build\        ← CMake のビルド出力先（空フォルダを事前に作成）
C:\opencv\              ← インストール先（cmake --install の出力先）

opencv_build と opencv（インストール先）フォルダは手動で作成しておきます。

mkdir C:\opencv_build
mkdir C:\opencv

4. CMake GUI による Configure & Generate

CMake GUI（cmake-gui）を起動し、以下を入力します。

「Configure」をクリックします。初回はジェネレーター選択ダイアログが出ます。

Generator: Visual Studio 17 2022
Platform:  x64

Configure が完了（赤いハイライト行が並んだ状態）したら、以下のエントリを設定します。

OPENCV_EXTRA_MODULES_PATH の入力後に再度「Configure」を実行してください。赤いハイライトが消えたら「Generate」をクリックします。

-- Configuring done
-- Generating done
-- Build files have been written to: C:/opencv_build

上記が表示されれば Generate 完了です。

5. Visual Studio でビルド & インストール

Generate が終わると C:\opencv_build\OpenCV.sln が生成されます。

方法 A: cmake コマンドでビルド（推奨）

Developer Command Prompt for VS 2022 または PowerShell で実行します。

cmake --build C:\opencv_build --config Release --parallel
cmake --install C:\opencv_build --config Release

--parallel オプションで論理コア数を使い切ってビルドします。コア数によりますが 15〜30 分程度かかります。

方法 B: Visual Studio IDE でビルド

OpenCV.sln を Visual Studio 2022 で開き、構成を Release / x64 に変更後、ソリューションエクスプローラーから INSTALL プロジェクトをビルドします。

6. 環境変数の設定

ビルド完了後、インストール先の DLL を Windows が見つけられるよう PATH を追加します。

C:\opencv\x64\vc17\bin

システム環境変数 Path に追加後、PC を再起動またはシェルを再起動してください。

動作確認

contrib が正しくビルドされているかを確認するプログラムです。ORB（本体）でキーポイント検出、FREAK（xfeatures2d） で記述子計算を行います。FREAK が動けば contrib リンクが通っている証明になります。

#include <iostream>
#include <vector>
#include <opencv2/opencv.hpp>
#include <opencv2/xfeatures2d.hpp>  // contrib: FREAK

int main()
{
    // グレースケール画像を生成（テスト用）
    cv::Mat img = cv::Mat::zeros(400, 400, CV_8UC1);
    cv::rectangle(img, {50, 50}, {350, 350}, cv::Scalar(200), 3);
    cv::circle(img,    {200, 200}, 80,        cv::Scalar(150), 2);

    // ORB でキーポイント検出（本体モジュール）
    auto orb = cv::ORB::create(500);
    std::vector<cv::KeyPoint> keypoints;
    orb->detect(img, keypoints);
    std::cout << "ORB keypoints: " << keypoints.size() << std::endl;

    if (keypoints.empty()) {
        std::cerr << "キーポイントが検出されませんでした。" << std::endl;
        return 1;
    }

    // FREAK で記述子計算（contrib: xfeatures2d）
    cv::Mat descriptors;
    auto freak = cv::xfeatures2d::FREAK::create();
    freak->compute(img, keypoints, descriptors);
    std::cout << "FREAK descriptors: "
              << descriptors.rows << " x " << descriptors.cols << std::endl;

    // キーポイントを描画して保存
    cv::Mat output;
    cv::drawKeypoints(img, keypoints, output,
                      cv::Scalar::all(-1),
                      cv::DrawMatchesFlags::DRAW_RICH_KEYPOINTS);
    cv::imwrite("result.png", output);
    std::cout << "result.png を出力しました。" << std::endl;

    return 0;
}

Visual Studio でのプロジェクト設定（Release / x64 前提）:

BUILD_opencv_world を ON にしてビルドしたため、opencv_world4100.lib 1 ファイルのリンクで全モジュール（contrib 含む）が使えます。バージョン番号部分（4100）は実際のバージョンに合わせてください。

実行結果:

ORB keypoints: 248
FREAK descriptors: 248 x 64
result.png を出力しました。

FREAK descriptors の行が出力されれば contrib のビルドとリンクが成功しています。

つまずきポイント

① opencv_world vs 個別 lib のリンクエラー（LNK2019）

BUILD_opencv_world を ON にした場合は opencv_world4100.lib をリンクします。OFF の場合は opencv_core4100.lib・opencv_xfeatures2d4100.lib のように個別に列挙が必要です。両方を混在させると重複シンボルエラーになるので注意してください。

Debug ビルドでは末尾に d が付く opencv_world4100d.lib を使います。Release ビルドで d 付き lib をリンクすると実行時クラッシュします。プロジェクトの構成ごとに正しく使い分けてください。

② opencv2/xfeatures2d.hpp が見つからない

contrib のヘッダーは C:\opencv\include\opencv2\xfeatures2d.hpp に配置されます。インクルードディレクトリに C:\opencv\include を指定していれば解決します。
もし cmake –install を実行していない場合はヘッダーがコピーされません。INSTALL プロジェクトのビルドを忘れずに行ってください。

③ OPENCV_EXTRA_MODULES_PATH のパス末尾に注意

OPENCV_EXTRA_MODULES_PATH に指定するのは opencv_contrib-4.10.0/modules ディレクトリです。opencv_contrib-4.10.0 のルートを指定すると「No modules directory」エラーになります。Configure 後に CMake の出力ログで contrib モジュールが列挙されていることを確認してください。

--   Extra modules:
--     Location (extra): C:/opencv_src/opencv_contrib-4.10.0/modules
--     Version control: unknown

まとめ

contrib のビルドが必要になる典型的なケースは SURF・FREAK などの xfeatures2d モジュールや、face・ximgproc などの研究向けモジュールです。一度ビルド環境を整えてしまえば、バージョンアップ時も同じ手順で対応できます。