OpenCvSharp4 を NuGet でインストールして使う完全ガイド【C# / .NET 8】

この記事を読めば、.NET 8 の C# プロジェクトに OpenCvSharp4 を NuGet で追加し、画像の読み込み・変換・保存までを動かせる状態になります。Visual Studio を使う場合と dotnet CLI を使う場合の両方を説明します。

前提環境

OpenCV 4.x 時点の情報です。OpenCvSharp4 は OpenCV 4 系に対応したバインディングです。

手順

1. .NET 8 コンソールプロジェクトを作成する

dotnet new console -n OpenCvSample --framework net8.0
cd OpenCvSample

Visual Studio を使う場合は「コンソール アプリ」テンプレートで .NET 8 を選択して作成してください。

2. NuGet パッケージを追加する

OpenCvSharp4 と OpenCvSharp4.runtime.win の 2 つが必要です。前者がマネージドバインディング本体、後者が Windows 向けのネイティブ DLL（OpenCvSharpExtern.dll）です。

dotnet add package OpenCvSharp4
dotnet add package OpenCvSharp4.runtime.win

Visual Studio を使う場合は「NuGet パッケージの管理」から同様に 2 パッケージを検索・インストールしてください。

インストール後、OpenCvSample.csproj に以下が追加されていることを確認します。

<PackageReference Include="OpenCvSharp4" Version="4.*" />
<PackageReference Include="OpenCvSharp4.runtime.win" Version="4.*" />

3. 動作確認用の画像を用意する

プロジェクトフォルダ直下に任意の JPEG/PNG ファイルを input.jpg という名前で配置してください。手元に画像がない場合は以下のコマンドで Windows 標準のサンプル画像を使えます。

copy C:\Windows\Web\Wallpaper\Windows\img0.jpg input.jpg

4. ビルド・実行する

dotnet build
dotnet run

動作確認

以下の完全プログラムで「画像をグレースケール変換して保存する」動作確認を行います。

using OpenCvSharp;

// --- 画像の読み込み ---
using var src = Cv2.ImRead("input.jpg", ImreadModes.Color);
if (src.Empty())
{
    Console.Error.WriteLine("画像を読み込めませんでした。input.jpg をプロジェクトフォルダに置いてください。");
    return;
}

Console.WriteLine($"読み込み成功: {src.Width} x {src.Height}, チャンネル数={src.Channels()}");

// --- グレースケール変換 ---
using var gray = new Mat();
Cv2.CvtColor(src, gray, ColorConversionCodes.BGR2GRAY);

// --- 保存 ---
Cv2.ImWrite("output_gray.jpg", gray);
Console.WriteLine("output_gray.jpg を保存しました。");

// --- ウィンドウ表示（GUIが使える環境のみ） ---
// Cv2.ImShow("gray", gray);
// Cv2.WaitKey(0);

実行すると以下のように表示され、プロジェクトフォルダに output_gray.jpg が生成されます。

読み込み成功: 1920 x 1200, チャンネル数=3
output_gray.jpg を保存しました。

⚠️ Cv2.ImShow / Cv2.WaitKey はウィンドウシステムが必要です。CI/CD 環境やサーバーサイドでは ImWrite のみで確認してください。

つまずきポイント

① DllNotFoundException: OpenCvSharpExtern

エラーメッセージ例:

System.DllNotFoundException: Unable to load DLL 'OpenCvSharpExtern'

原因: OpenCvSharp4.runtime.win パッケージが入っていないか、x86/x64 のターゲットアーキテクチャが合っていない。

対処:
– OpenCvSharp4.runtime.win を追加できているか確認する。
– プロジェクトのターゲットを x64 に固定する（Any CPU では問題が出ることがある）。

dotnet build -r win-x64

または .csproj に以下を追加します。

<RuntimeIdentifier>win-x64</RuntimeIdentifier>

② Mat の Dispose 漏れによるネイティブメモリリーク

Mat はネイティブヒープ上にピクセルデータを持つため、GC だけでは回収されません。必ず using で解放してください。

✅ 正しい書き方:

using var mat = Cv2.ImRead("input.jpg");

⚠️ やってはいけない書き方（リーク）:

var mat = Cv2.ImRead("input.jpg"); // Dispose されない

ループ内で大量の Mat を生成する処理では、Dispose 漏れがすぐにメモリ枯渇につながります。Mat だけでなく Mat[] や MatExpr なども同様です。

③ Bitmap ↔ Mat の相互変換には Extensions パッケージが必要

WinForms / WPF の Bitmap と Mat を相互変換したい場合、追加で OpenCvSharp4.Extensions パッケージが必要です。

dotnet add package OpenCvSharp4.Extensions

このパッケージなしに BitmapConverter.ToBitmap(mat) を呼び出すと型が見つからずビルドエラーになります。WinForms を使わない純粋なバックエンド処理では不要です。

まとめ

NuGet からの導入は 2 パッケージを追加するだけで、C++ でのビルドが不要なのが OpenCvSharp の大きなメリットです。まずはここで動作確認し、次のステップとしてフィルタリングや特徴点検出など各処理の実装に進んでください。