OpenCV/C++ imread・imshow の使い方 〜画像を読み込んで表示する〜

C++ で OpenCV を使った画像処理の第一歩は「画像を読み込んで表示する」ことです。cv::imread でファイルを cv::Mat に読み込み、cv::imshow でウィンドウに表示するだけで完結します。最小構成は次のとおりです。

cv::Mat img = cv::imread("sample.jpg");
cv::imshow("window", img);
cv::waitKey(0);

動作環境

ビルド・実行コマンド（Linux / macOS）:

g++ -std=c++17 main.cpp `pkg-config --cflags --libs opencv4` -o main
./main

基本の使い方

完全プログラム

#include <opencv2/opencv.hpp>
#include <iostream>

int main()
{
    // 画像ファイルを読み込む（実行ディレクトリに sample.jpg を置く）
    cv::Mat img = cv::imread("sample.jpg");

    // 読み込み失敗チェック（パス誤りや対応外フォーマットで空になる）
    if (img.empty()) {
        std::cerr << "画像の読み込みに失敗しました。パスを確認してください。" << std::endl;
        return 1;
    }

    // ウィンドウタイトルを "OpenCV Sample" として画像を表示
    cv::imshow("OpenCV Sample", img);

    // キー入力があるまでウィンドウを維持する（0 = 無限待機）
    cv::waitKey(0);

    return 0;
}

実行結果

sample.jpg が正常に読み込まれると、「OpenCV Sample」というタイトルバーを持つウィンドウが開き、画像が表示されます。ウィンドウにフォーカスを当てた状態で任意のキーを押すとウィンドウが閉じてプログラムが終了します。

読み込みに失敗した場合（ファイルが存在しない等）は以下がターミナルに出力されます。

画像の読み込みに失敗しました。パスを確認してください。

行ごとの解説

cv::imread("sample.jpg")
指定したパスの画像ファイルを読み込み、cv::Mat として返します。デフォルトでカラー（BGR 3チャンネル）として読み込まれます。ファイルが存在しない・非対応フォーマットの場合は空の cv::Mat を返し、例外はスローされません。そのため直後の empty() チェックが必須です。

cv::imshow("OpenCV Sample", img)
第1引数のタイトルで GUI ウィンドウを生成し、cv::Mat の内容をそのまま表示します。同じタイトルで複数回呼ぶと同一ウィンドウが更新されます（動画ループ等に利用）。

cv::waitKey(0)
引数 0 はキー入力を無限に待ちます。正の整数を渡すとミリ秒単位のタイムアウトになります（例: cv::waitKey(1000) で1秒後に自動で抜ける）。cv::imshow を呼んだだけではウィンドウのイベントループが動かないため、必ずセットで呼び出す必要があります。

引数と戻り値

cv::imread

flags の主な値:

cv::imshow

cv::waitKey

実践例

グレースケールで読み込んで表示する

カラー不要な処理（エッジ検出・二値化など）では、読み込み時からグレースケールにしておくと後続処理が軽くなります。

#include <opencv2/opencv.hpp>
#include <iostream>

int main()
{
    // IMREAD_GRAYSCALE を指定してグレースケールで読み込む
    cv::Mat gray = cv::imread("sample.jpg", cv::IMREAD_GRAYSCALE);

    if (gray.empty()) {
        std::cerr << "画像の読み込みに失敗しました。" << std::endl;
        return 1;
    }

    cv::imshow("Grayscale", gray);
    cv::waitKey(0);

    return 0;
}

実行すると、モノクロのウィンドウが表示されます。gray.type() は CV_8UC1（1チャンネル8ビット）になります。

押したキーを判定してウィンドウを閉じる

cv::waitKey の戻り値でキーを判定できます。s キーで別名保存、q キーで終了するパターンは実務でよく使います。

#include <opencv2/opencv.hpp>
#include <iostream>

int main()
{
    cv::Mat img = cv::imread("sample.jpg");

    if (img.empty()) {
        std::cerr << "画像の読み込みに失敗しました。" << std::endl;
        return 1;
    }

    cv::imshow("Press S to save / Q to quit", img);

    while (true) {
        int key = cv::waitKey(0);

        if (key == 's' || key == 'S') {
            // 'S' キーで画像を保存
            cv::imwrite("output.jpg", img);
            std::cout << "output.jpg に保存しました。" << std::endl;
        } else if (key == 'q' || key == 'Q' || key == 27) {
            // 'Q' キーまたは ESC で終了
            break;
        }
    }

    return 0;
}

つまずきポイント

⚠️ imread が空の Mat を返す

最も多いハマりどころです。cv::imread はファイルが見つからなくても例外を投げず、空の cv::Mat を返します。その後 cv::imshow に渡すと assertion エラーでクラッシュします。

主な原因と確認方法:

• 作業ディレクトリのズレ: IDE（Visual Studio / CLion 等）でビルドすると、実行時のカレントディレクトリがソースの場所とは異なることがあります。絶対パスで確認するか、std::filesystem::current_path() で実行時ディレクトリを出力して確認してください。
• 日本語・スペースを含むパス: ファイルパスに日本語が含まれると cv::imread が失敗するケースがあります（特に Windows）。ASCII のみのパスに移動して試してください。
• 拡張子とフォーマットの不一致: 拡張子を .jpg にしていても中身が PNG のファイルは読み込めます（逆も同様）が、完全に壊れたファイルは失敗します。

⚠️ cv::imshow 後に waitKey を呼ばないとウィンドウが表示されない（またはすぐ消える）

cv::imshow は表示命令をキューに積むだけで、cv::waitKey を呼ぶまでイベントループが動きません。waitKey なしで main が終了すると、ウィンドウが一瞬も表示されずにプログラムが終わります。

⚠️ Windows での リンクエラー（unresolved external symbol）

Visual Studio でビルドする際、Debug ビルド用のライブラリ（opencv_world4XXd.lib）と Release ビルド用（opencv_world4XX.lib）を取り違えるとリンクエラーになります。プロジェクト設定のビルド構成（Debug / Release）と追加の依存ファイルに指定したライブラリ名が一致しているか確認してください。また、x64 / x86 の取り違えも同様にリンクエラーの原因になります。

関連する関数

• cv::imwrite: cv::Mat をファイルに書き出す。imread の逆操作。
• cv::namedWindow: ウィンドウのサイズ変更可否などのオプションを事前に設定する。cv::imshow だけでウィンドウは自動生成されるが、リサイズ可能にしたい場合などは namedWindow を先に呼ぶ。
• cv::destroyAllWindows: 開いているすべてのウィンドウを閉じる。複数ウィンドウを開くプログラムの終了時に使う。
• cv::Mat: OpenCV における画像データの基本型。チャンネル数・ビット深度・サイズをまとめて管理する。

まとめ

• cv::imread でファイルを cv::Mat に読み込み、cv::imshow でウィンドウに表示するのが C++ 画像処理の基本形です。
• imread 直後の empty() チェックと imshow 後の waitKey 呼び出しはセットで忘れずに入れてください。
• グレースケール読み込みやキー入力判定など、実務で使う応用もフラグや戻り値を変えるだけで対応できます。