【OpenCV入門】waitKey関数の基本的な使い方を徹底解説

By /

はい、承知いたしました。
OpenCVのwaitKey()関数について、基本的な使い方を徹底解説する詳細な記事を作成します。以下、記事本文です。

【OpenCV入門】waitKey関数の基本的な使い方を徹底解説

はじめに：OpenCVの縁の下の力持ち、waitKey()関数

OpenCVを使って画像処理やコンピュータビジョンの世界に足を踏み入れたとき、多くの人が最初に出会う関数の一つが cv2.imshow() です。この関数は画像や動画をウィンドウに表示するためのものですが、cv2.imshow() だけを実行しても、期待通りに画像が表示されないことに気づくでしょう。ウィンドウが一瞬だけ表示されてすぐに消えてしまったり、表示されても「応答なし」と表示されて固まってしまったり…

なぜこのようなことが起こるのでしょうか？その答えを握っているのが、今回徹底解説する cv2.waitKey() 関数です。

cv2.waitKey()は、一見すると「キーボードからの入力を待つ」だけの単純な関数に見えます。しかし、その裏ではOpenCVのウィンドウシステムを正常に機能させるための、非常に重要な役割を担っています。

この関数の主な役割は、大きく分けて3つあります。

  1. キー入力の待機: プログラムの実行を一時停止し、ユーザーがキーボードのキーを押すのを待ちます。
  2. 表示時間の制御: 動画のフレーム表示のように、一定時間だけ画像を表示するために使用されます。
  3. ウィンドウイベントの処理: これが最も重要かつ見過ごされがちな役割です。ウィンドウの描画、リサイズ、移動、×ボタンで閉じるなどの操作を処理する時間をプログラムに与えます。

waitKey()を理解せずにOpenCVを使いこなすことはできません。逆に言えば、この関数をマスターすれば、OpenCVを使ったアプリケーション開発の幅が格段に広がります。

この記事では、waitKey()関数の基本的な構文から、静止画・動画での実践的な使い方、特定のキー入力で処理を分岐させる方法、そして初心者がつまずきやすい注意点やトラブルシューティングまで、約5000字のボリュームで徹底的に解説していきます。

この記事を読み終える頃には、あなたはwaitKey()を自在に操り、インタラクティブで安定したOpenCVアプリケーションを作成するための確かな知識を身につけていることでしょう。それでは、OpenCVの心臓部とも言えるwaitKey()の世界へ一緒に飛び込んでいきましょう。

waitKey()関数の基本的な構文と引数

まずはwaitKey()関数の最も基本的な形を見ていきましょう。PythonのOpenCVライブラリでは、この関数は以下のように記述します。

python
key = cv2.waitKey(delay)

非常にシンプルですね。この関数は一つの引数 delay を取り、戻り値として key を返します。それぞれがどのような意味を持つのか、詳しく見ていきましょう。

引数 delay：待機時間をミリ秒で指定する

delay は、プログラムがキー入力を待機する時間を ミリ秒 (ms) 単位で指定する整数です。1000ミリ秒 = 1秒です。この delay に渡す値によって、waitKey()の動作は大きく3つのパターンに分かれます。

delay の値 動作 主な用途
0 無限に待機 ユーザーが何らかのキーを押すまで、プログラムの実行を完全に停止して待ち続けます。
正の整数 (例: 1, 25, 1000) 指定したミリ秒だけ待機 delayで指定された時間だけプログラムを停止し、キー入力を待ちます。その時間内にキーが押されれば、そのキーの情報を返します。キーが押されなくても、指定時間が経過すれば次の処理に進みます。
負の整数 (例: -1) 無限に待機 delayに0を指定した場合と全く同じ動作をします。

delay = 0 の場合

これは「ユーザーからのアクションがあるまで、ずっと待つ」というモードです。画像を表示して、ユーザーが内容を確認し終えて何かキーを押すまでプログラムを停止させておきたい、という場合に最適です。デバッグ中に画像の内容をじっくり確認したいときにも非常に便利です。

delay > 0 の場合

こちらは「制限時間付きの待機」モードです。例えば cv2.waitKey(1000) とした場合、プログラムは1秒間だけ停止します。その1秒の間にユーザーがキーを押せば、そのキー情報を返してすぐに次の処理に進みます。もし1秒間キーが押されなければ、キー入力がなかったことを示す値を返し、次の処理に進みます。

動画やWebカメラの映像を表示する際には、このモードが必須です。whileループの中で cv2.waitKey(1) のように非常に短い待機時間を設定することで、フレームを次々と更新しつつ、ウィンドウのイベント処理やキー入力の受付を可能にします。なぜ 1 という値がよく使われるのかは、後の実践的な使い方のセクションで詳しく解説します。

戻り値 key：押されたキーの情報

waitKey()関数は、待機中に押されたキーの情報を戻り値として返します。この戻り値も、キーが押されたかどうかで意味が変わります。

  • キーが押されなかった場合:
    待機時間内（delay > 0 の場合）にどのキーも押されなかった場合、waitKey()は -1 を返します。

  • キーが押された場合:
    何らかのキーが押された場合、そのキーに対応する 32ビット整数のキーコード を返します。

    • ほとんどの英数字キー（’a’, ‘b’, ‘1’, ‘2’など）の場合、このキーコードはその文字の ASCIIコード と一致します。例えば、’A’キーを押すと65、’a’キーを押すと97が返されます。
    • 矢印キーやファンクションキーなどの特殊キーは、ASCIIコードの範囲外の特別な値を返します。ただし、これらの値はOSや環境によって異なる場合があるため、注意が必要です。Escキー（27）、Enterキー（13）、スペースキー（32）は比較的共通でよく使われます。

この戻り値を利用することで、「’q’キーが押されたらプログラムを終了する」「’s’キーが押されたら画像を保存する」といった、ユーザーの入力に応じたインタラクティブな処理を実装できます。

実践的な使い方：具体的なコード例

理論を学んだところで、次は実際にコードを書きながらwaitKey()の使い方をマスターしていきましょう。ここでは、3つの典型的なユースケースを紹介します。

ケース1：画像を表示して、何らかのキーが押されるまで待つ

これはwaitKey()の最も基本的でシンプルな使い方です。imread()で読み込んだ画像を表示し、ユーザーが何かキーを押すまでウィンドウを閉じずに待機させます。

“`python
import cv2
import sys

画像ファイルを読み込む

‘image.jpg’の部分はご自身の画像ファイルパスに変更してください

img = cv2.imread(‘image.jpg’)

画像が正しく読み込めたかチェック

if img is None:
print(“エラー: 画像ファイルを読み込めませんでした。”)
sys.exit()

ウィンドウを作成して画像を表示

cv2.imshow(‘Image Display’, img)

キー入力を無限に待機

何かキーが押されると、次の行に進む

print(“画像を表示しました。何かキーを押すとウィンドウが閉じます。”)
key = cv2.waitKey(0)

押されたキーのキーコードを表示（デバッグ用）

print(f”押されたキーのコード: {key}”)

開いているすべてのOpenCVウィンドウを閉じる

cv2.destroyAllWindows()

print(“プログラムを終了します。”)
“`

コードの解説:

  1. cv2.imread('image.jpg'): 画像ファイルを読み込み、NumPy配列として img 変数に格納します。
  2. cv2.imshow('Image Display', img): ‘Image Display’ という名前のウィンドウを作成し、img の内容を表示します。しかし、この時点ではOSに描画命令が送られるだけで、実際にはまだ画面に表示されません。
  3. key = cv2.waitKey(0): ここが核心部分です。
    • 引数が 0 なので、プログラムはここで完全に停止し、ユーザーがキーを押すのを無限に待ちます。
    • この待機時間中に、imshow()による描画要求が処理され、初めてウィンドウと画像が画面に表示されます。
    • 同時に、ウィンドウの移動やリサイズなどのイベントも処理できるようになります。
    • ユーザーが何かキー（例えばEnterキー）を押すと、そのキーのコードが key 変数に格納され、waitKey()は終了して次の行の処理に進みます。
  4. cv2.destroyAllWindows(): プログラムの終了時に、OpenCVが作成した全てのウィンドウを綺麗に閉じるための関数です。これを呼び出さないと、プログラムが終了してもウィンドウが残り続けることがあります。

もし cv2.waitKey(0) の行をコメントアウトして実行すると、プログラムは一瞬で終了してしまい、画像を見ることはできません。waitKey()がウィンドウを表示し続けるために、いかに重要かが分かります。

ケース2：動画やWebカメラのフレームを連続表示する

次に、動画ファイルやWebカメラからの映像をリアルタイムで表示する例を見てみましょう。このケースでは、whileループと waitKey() を組み合わせるのが定石です。

“`python
import cv2

Webカメラからの入力を開始 (0はデフォルトのカメラ)

動画ファイルの場合は ‘video.mp4’ のようにパスを指定

cap = cv2.VideoCapture(0)

if not cap.isOpened():
print(“エラー: カメラを開けませんでした。”)
exit()

while True:
# カメラから1フレーム読み込む
ret, frame = cap.read()

# フレームの読み込みに失敗したらループを抜ける
if not ret:
    print("エラー: フレームを読み込めませんでした。")
    break

# 読み込んだフレームをウィンドウに表示
cv2.imshow('Webcam Live', frame)

# 1ミリ秒だけキー入力を待つ
# 'q'キーが押されたらループを抜ける
key = cv2.waitKey(1)
if key == ord('q'):
    print("'q'キーが押されたため、ループを終了します。")
    break

キャプチャを解放し、ウィンドウを閉じる

cap.release()
cv2.destroyAllWindows()
“`

コードの解説:

  1. cv2.VideoCapture(0): PCに接続されたデフォルトのカメラデバイスを開きます。
  2. while True:: 無限ループを開始し、カメラからフレームを連続で取得します。
  3. ret, frame = cap.read(): カメラから1フレーム分の画像を読み込みます。retは読み込みが成功したかどうかのbool値、frameが画像データです。
  4. cv2.imshow('Webcam Live', frame): 現在のフレームをウィンドウに表示します。
  5. key = cv2.waitKey(1): ここが動画表示のキモです。
    • 引数に 1 を指定しているため、プログラムは 1ミリ秒 だけ停止します。
    • この非常に短い待機時間中に、imshow()で要求されたフレームの描画が行われ、ウィンドウイベント（閉じるボタンなど）が処理され、そしてキー入力がないかチェックされます。
    • 1ミリ秒後、キー入力がなくてもプログラムは次のループ処理（次のフレームの読み込み）に進みます。
    • このループが高速に繰り返されることで、私たちの目には映像が滑らかに動いているように見えます。

なぜ waitKey(0) ではダメなのか？
もしここで cv2.waitKey(0) を使うと、プログラムは最初の1フレームを表示した時点で無限待機に入ってしまい、ユーザーがキーを押すまで次のフレームが読み込まれません。結果として、動画は再生されず、静止画が表示されるだけになってしまいます。

delay の値を変えるとどうなる？
waitKey()の引数の値は、動画の最大フレームレート（fps: frames per second）に影響を与えます。
* cv2.waitKey(1): 理論上は最大1000fpsを目指しますが、実際にはフレームの読み込みや処理にかかる時間があるため、そこまで速くはなりません。一般的なWebカメラ（30fpsや60fps）の映像を表示するには十分な速度です。
* cv2.waitKey(33): 1フレームあたり約33ミリ秒待機します。1秒は1000ミリ秒なので、1000 / 33 ≒ 30fps となり、約30fpsの動画を再生するのに近い待機時間となります。
* cv2.waitKey(100): 100ミリ秒ごとにフレームを更新するため、1秒あたり10フレームしか表示されず、映像はカクカクしたスローモーションのように見えます。

このように、delayの値を調整することで、意図的に再生速度をコントロールすることも可能です。

ケース3：特定のキーで処理を分岐させる

waitKey()の戻り値を利用すれば、ユーザーのキー入力に応じて様々なアクションを実行できます。先ほどの動画表示の例では’q’キーで終了しましたが、さらに機能を追加してみましょう。

  • ‘q’キー: プログラムを終了する
  • ‘s’キー: 現在のフレームを画像ファイルとして保存する
  • ‘c’キー: 画面をグレースケールに切り替える（フラグで管理）

“`python
import cv2

cap = cv2.VideoCapture(0)
if not cap.isOpened():
exit()

グレースケール表示用のフラグ

grayscale_mode = False

保存する画像のカウンター

save_counter = 0

while True:
ret, frame = cap.read()
if not ret:
break

# 表示するフレームを決定
if grayscale_mode:
    # グレースケールに変換
    display_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
else:
    # カラーのまま
    display_frame = frame

# ウィンドウにフレームを表示
cv2.imshow('Interactive Webcam', display_frame)

# キー入力を1ミリ秒待つ
key = cv2.waitKey(1) & 0xFF

# 'q'キーが押されたらループを抜ける (終了)
if key == ord('q'):
    print("終了します。")
    break

# 's'キーが押されたらフレームを保存
elif key == ord('s'):
    save_counter += 1
    filename = f'capture_{save_counter}.jpg'
    # カラーの元フレームを保存
    cv2.imwrite(filename, frame)
    print(f"フレームを '{filename}' として保存しました。")

# 'c'キーが押されたらグレースケールモードを切り替え
elif key == ord('c'):
    grayscale_mode = not grayscale_mode
    if grayscale_mode:
        print("グレースケールモードに切り替えました。")
    else:
        print("カラーモードに切り替えました。")

cap.release()
cv2.destroyAllWindows()
“`

コードの解説:

  • ord('q'): Pythonの組み込み関数 ord() は、文字をそのASCII（Unicode）コードポイントに変換します。waitKey()が返すキーコードは数値なので、文字 'q' と直接比較することはできません。ord('q') を使って 'q' のASCIIコード（113）を取得し、戻り値と比較することで、’q’キーが押されたかどうかを正しく判定できます。
  • key = cv2.waitKey(1) & 0xFF: ここで & 0xFF という謎の記述が出てきました。これは非常に重要なので、次のセクションで詳しく解説します。
  • if/elif構文: waitKey()の戻り値 key を使って、条件分岐を行っています。
    • key == ord('s') が真になれば、cv2.imwrite() を使って現在のカラーフレームをJPEGファイルとして保存します。
    • key == ord('c') が真になれば、grayscale_mode というbool値のフラグを True と False で切り替えています。次のループでは、このフラグの状態に応じて表示する画像を変えています。

このように、waitKey()は単なる「待ち」関数ではなく、ユーザーと対話するアプリケーションを作成するための重要な入り口となるのです。

waitKey()とキーコードの詳解

waitKey()をさらに深く理解するために、戻り値であるキーコードと、多くのサンプルコードで見かける & 0xFF の謎について掘り下げていきましょう。

戻り値はなぜ数値なのか？（ASCIIコード）

前述の通り、waitKey()は押されたキーに対応する数値を返します。この数値は、多くの場合 ASCIIコード に基づいています。ASCII（アスキー）は、アルファベット、数字、記号などをコンピュータ上で表現するための最も基本的な文字コード体系です。

例えば、
* ‘a’キー -> ord('a') -> 97
* ‘A’キー -> ord('A') -> 65
* ‘1’キー -> ord('1') -> 49
* スペースキー -> ord(' ') -> 32
* Enterキー -> 13
* Escキー -> 27

waitKey()の戻り値と ord() を使って比較するのは、このASCIIコードに基づいた仕組みを利用しているためです。

なぜ & 0xFF が必要なのか？

多くのOpenCVのサンプルコードを見ると、key = cv2.waitKey(1) & 0xFF のように、& 0xFF というビット演算が付け加えられています。これは一体何のためでしょうか？

結論から言うと、OSや環境間の互換性を保つためのおまじない のようなものです。

waitKey()は32ビットの整数を返しますが、標準的なASCIIコードは下位8ビット（0〜255）の範囲に収まります。しかし、特定の状況下では、この下位8ビット以外の部分に余分な情報が付加されてしまうことがあります。

  • 64ビットマシンでの問題: 64ビット環境では、キーコードが32ビットの範囲を超えた値として返されることがあり、下位8ビットだけを見ないと正しく判定できないケースがありました。
  • NumLockキーなどの状態: NumLockや他の修飾キーがオンになっていると、キーコードの上位ビットにその状態を示すフラグが立つことがあります。

& はビット単位のAND演算子です。0xFF は16進数表記で、2進数にすると 11111111 となります。つまり、下位8ビットがすべて1で、それより上位のビットはすべて0です。

waitKey()の戻り値に対して & 0xFF を行うと、どのような値が返ってきても、下位8ビットの値だけが取り出され、それより上位のビットはすべて0にマスク（無視）されます。

例：
NumLockがオンの状態で’a’キーを押したとき、waitKey()が仮に 0x100061 という値を返したとします。（0x61は’a’のASCIIコード）
0x100061 & 0xFF を計算すると、結果は 0x61 となり、正しく’a’のキーコードだけを抽出できます。

最近のOpenCVやPythonのバージョンではこの問題が解消されていることも多く、& 0xFFがなくても正常に動作することがほとんどです。しかし、どのような環境でも意図通りに動作する頑健なコードを書くためには、この & 0xFF を付けておくことが推奨されます。特に、不特定多数の環境で使われる可能性のあるプログラムを書く際には、付けておくと安心です。

特殊キー（矢印キーなど）の扱い

矢印キー、Home、End、F1〜F12などの特殊キーを扱いたい場合、少し注意が必要です。これらのキーはASCIIコードを持たず、waitKey()はプラットフォーム依存の特別な値を返します。そのため、ord()で判定することはできません。

残念ながら、これらの特殊キーのコードはOSによって異なるため、クロスプラットフォームで確実に動作するコードを書くのは困難です。もしどうしても特殊キーを扱いたい場合は、cv2.waitKeyEx() という拡張関数を使用する方法がありますが、これは入門の範囲を超えるため、ここでは紹介に留めます。

まずは、英数字キー、Esc、Enter、スペースキーなど、ord()や直接の数値比較で安定して判定できるキーを使うことから始めるのが良いでしょう。

waitKey()の注意点とよくあるエラー

最後に、初心者がwaitKey()を使う際につまずきがちなポイントと、その解決策をQ&A形式でまとめます。

Q1. imshow()で画像を表示したのに、ウィンドウが一瞬で消えてしまいます。

A1. imshow()の直後に waitKey() を呼び出していないのが原因です。OpenCVのスクリプトは、処理が最後まで終わると自動的に終了します。imshow()でウィンドウを表示する命令を出しても、その後にプログラムを一時停止させる waitKey() がないと、プログラムが一瞬で終了し、それに伴ってウィンドウも閉じられてしまいます。

対策:
静止画を表示する場合は、cv2.imshow() の後に必ず cv2.waitKey(0) を置いてください。

Q2. ウィンドウは表示されるのですが、画像が真っ白（または真っ黒）で、「応答なし」になって固まってしまいます。

A2. whileループの中でwaitKey()を呼び出していない、またはwaitKey()が呼び出される前に非常に時間のかかる重い処理があることが原因です。waitKey()はキー入力を待つだけでなく、ウィンドウの再描画やイベント（マウス操作や閉じるボタン）を処理する役割も担っています。この関数が定期的に呼び出されないと、OSは「このアプリケーションは応答していない」と判断してしまいます。

対策:
動画処理などの while ループの中では、フレームを表示する cv2.imshow() の後、ループの最後に近い部分で必ず cv2.waitKey(1) のように短い待機時間で呼び出してください。これにより、フレームごとにウィンドウイベントを処理する時間が確保され、フリーズを防ぐことができます。

Q3. ‘q’キーを押してもプログラムが終了しません。キー判定がうまく動きません。

A3. いくつかの原因が考えられます。

  • & 0xFF を忘れている: 最もよくある原因です。特に64ビット環境では、この記述がないとキーコードの比較がうまくいかないことがあります。
  • CapsLockがオンになっている: ord('q') は小文字の’q’（ASCIIコード 113）を判定しますが、CapsLockがオンの状態でQキーを押すと、大文字の’Q’（ASCIIコード 81）が入力されます。
  • ウィンドウがアクティブでない: キー入力は、フォーカスが当たっている（アクティブな）ウィンドウに対して送られます。OpenCVの表示ウィンドウ以外（例えばターミナルやコードエディタ）が選択されていると、キー入力はOpenCVのウィンドウに届きません。

対策:
1. まず、key = cv2.waitKey(1) & 0xFF のように & 0xFF を付けることを徹底してください。
2. 大文字と小文字の両方に対応させたい場合は、以下のように書くのが確実です。
python
if key == ord('q') or key == ord('Q'):
break
3. プログラムを実行したら、必ずOpenCVの表示ウィンドウをクリックしてアクティブな状態にしてからキーを押してみてください。

まとめ

この記事では、OpenCVのwaitKey()関数について、その基本的な役割から実践的な応用までを徹底的に解説しました。最後に、この関数の重要なポイントをもう一度振り返りましょう。

waitKey()は、見た目のシンプルさとは裏腹に、3つの非常に重要な役割を担っています。

  1. キー入力の待機: key = cv2.waitKey() の形で戻り値を取得し、if key == ord('q'): のように使うことで、ユーザーからのキー入力を受け付け、インタラクティブなアプリケーションを作成できます。
  2. 処理の一時停止と時間制御: 引数 delay にミリ秒単位で時間を指定します。delay=0 なら無限待機（静止画向け）、delay>0 なら指定時間待機（動画向け）となり、表示時間をコントロールできます。
  3. ウィンドウイベントの処理: これが最も重要な隠れた役割です。waitKey()が呼び出される短い時間で、ウィンドウの描画、更新、リサイズ、閉じるボタンの処理などが行われます。waitKey()がないと、ウィンドウは正しく機能しません。

そして、環境間の互換性を保つために & 0xFF を付けて key = cv2.waitKey(1) & 0xFF と書くのが、より堅牢なコードを書くための作法であることも学びました。

waitKey()は、OpenCVアプリケーションの「呼吸」を制御するような関数です。この呼吸がなければ、アプリケーションは生きていけません。静止画を表示するとき、動画を再生するとき、ユーザーからの入力を受け付けたいとき、あらゆる場面でこの関数が登場します。

今日学んだ知識を土台として、ぜひあなた自身の手で様々なOpenCVアプリケーションを作成してみてください。waitKey()を自在に操れるようになったあなたは、もはやOpenCVの初心者ではありません。次のステップへ進む準備は万端です。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール