cv::imshow の使い方【OpenCV/C++】〜画像をウィンドウに表示する〜

cv::imshow は、cv::Mat に格納した画像をウィンドウに表示する関数です。デバッグから結果確認まで、OpenCV 開発で最も頻繁に呼ぶ関数のひとつです。最小の呼び出しは以下の1行で済みます。

cv::imshow("window_name", img);
cv::waitKey(0);

ただし cv::waitKey を呼ばないとウィンドウが即閉じする、あるいはフリーズするという落とし穴があります。本記事で正しい使い方を確認してください。

動作環境

• OpenCV 4.x（4.5 以降推奨）
• ビルド・実行コマンド例（Linux/macOS）:

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

基本の使い方

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

int main()
{
    // 画像を読み込む（グレースケールにしたい場合は IMREAD_GRAYSCALE を指定）
    cv::Mat img = cv::imread("sample.jpg", cv::IMREAD_COLOR);
    if (img.empty()) {
        std::cerr << "画像の読み込みに失敗しました。パスを確認してください。" << std::endl;
        return -1;
    }

    // ウィンドウに画像を表示する
    cv::imshow("sample", img);

    // キー入力を待つ（0 = 無限待機）
    // この行がないとウィンドウが表示されない or 即閉じする
    cv::waitKey(0);

    // 全ウィンドウを閉じる
    cv::destroyAllWindows();

    return 0;
}

実行結果

（"sample" というタイトルのウィンドウが開き、sample.jpg が表示されます。
  何かキーを押すとウィンドウが閉じてプログラムが終了します。）

各行の解説

引数と戻り値

void cv::imshow(const String& winname, InputArray mat);

戻り値: なし（void）

mat に渡せる型

cv::imshow は内部で型に応じて表示スケールを自動調整します。

実践例

動画フレームをリアルタイムで表示する

カメラや動画ファイルのフレームを逐次表示する典型パターンです。

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

int main()
{
    cv::VideoCapture cap(0); // 0 = デフォルトカメラ
    if (!cap.isOpened()) {
        std::cerr << "カメラのオープンに失敗しました。" << std::endl;
        return -1;
    }

    cv::Mat frame;
    while (true) {
        cap >> frame;
        if (frame.empty()) break;

        cv::imshow("camera", frame);

        // 30ms 待機。'q' キーで終了
        int key = cv::waitKey(30);
        if (key == 'q') break;
    }

    cv::destroyAllWindows();
    return 0;
}

ポイントは cv::waitKey の引数を 30（ミリ秒）にしている点です。動画再生時は 0（無限待機）にするとフレームが進まないため、フレームレートに合わせた待機時間を指定します。

ウィンドウサイズを事前に制御する（cv::namedWindow）

デフォルトでは cv::imshow が自動サイズのウィンドウを生成します。サイズをリサイズ可能にしたい場合は cv::namedWindow を先に呼びます。

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

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

    // WINDOW_NORMAL でリサイズ可能なウィンドウを作成
    cv::namedWindow("resizable", cv::WINDOW_NORMAL);
    cv::resizeWindow("resizable", 640, 480);

    cv::imshow("resizable", img);
    cv::waitKey(0);
    cv::destroyAllWindows();
    return 0;
}

cv::WINDOW_AUTOSIZE（デフォルト）では画像サイズに固定されてリサイズできません。大きな画像を扱う場合は cv::WINDOW_NORMAL を使うと便利です。

つまずきポイント

⚠️ cv::waitKey を呼ばないとウィンドウが表示されない

cv::imshow を呼んだだけでは、GUI のイベントループが回らないためウィンドウが描画されません。必ず直後に cv::waitKey を呼んでください。引数の単位は ミリ秒で、0 を渡すと無限待機になります。

cv::imshow("test", img);
// ここで waitKey を忘れると真っ黒なウィンドウ or 即終了する
cv::waitKey(0);

⚠️ ヘッドレス環境（SSH・Docker 等）でクラッシュする

cv::imshow は GUI ディスプレイが必要です。ディスプレイのないサーバ環境で呼ぶと次のようなエラーが出ます。

error: (-215:Assertion failed) !_src.empty() in function 'imshow'
// または
cannot connect to X server

サーバ環境でのデバッグには cv::imwrite でファイルに書き出して確認するか、DISPLAY 環境変数を設定して X11 フォワーディングを使うのが現実的な対処です。

⚠️ BGR と RGB の取り違えで色が狂う

OpenCV は画像を BGR 順で扱います。cv::imshow はそのまま BGR として表示するため、BGR 画像を渡せば正しく表示されます。ただし他のライブラリ（stb_image など）で読み込んだ RGB 画像をそのまま渡すと赤と青が反転して表示されます。その場合は cv::cvtColor(img, img, cv::COLOR_RGB2BGR) で変換してから渡してください。

関連する関数

• cv::waitKey — cv::imshow とセットで必ず使う。キー入力の取得も兼ねる
• cv::namedWindow — ウィンドウの事前作成とフラグ設定
• cv::destroyAllWindows / cv::destroyWindow — ウィンドウの破棄
• cv::imread — ファイルから cv::Mat に画像を読み込む
• cv::imwrite — ヘッドレス環境でのデバッグ時の代替手段

まとめ

cv::imshow は winname と cv::Mat を渡すだけで画像を表示できるシンプルな関数です。必ず cv::waitKey とセットで使うこと、ヘッドレス環境では使えないことの2点を押さえておけば実務で困ることはほぼありません。動画ループや複数ウィンドウの同時表示など、組み合わせパターンを覚えると開発効率が大きく上がります。