python-opencv

クイックリファレンス

関数	用途	注意点
cv2.imread(path)	画像を読み込む	パスが無効な場合は None を返します（エラーは発生しません！）
cv2.imwrite(path, img)	画像を保存する	RGB ではなく BGR を想定します
cv2.cvtColor(img, code)	色を変換する	デフォルトは RGB ではなく BGR です
cv2.VideoCapture(src)	動画／カメラ入力	必ず isOpened() と release() を確認してください
cv2.VideoWriter(...)	動画を保存する	BGR フレームを想定します。コーデックが重要です
cv2.resize(img, (w, h))	画像のサイズを変更する	サイズは (幅, 高さ) であり、(高さ, 幅) ではありません

座標系	順序	用途
NumPy のインデックス指定	img[row, col] = img[y, x]	ピクセルへのアクセス
画像の shape	(height, width, channels)	shape は (行, 列, チャンネル) です
OpenCV 関数	(x, y)	描画関数
リサイズ／ROI	(width, height)	サイズパラメーター

色変換	コード	備考
BGR から RGB	cv2.COLOR_BGR2RGB	Matplotlib での表示用
BGR からグレースケール	cv2.COLOR_BGR2GRAY	単一チャンネルで出力
BGR から HSV	cv2.COLOR_BGR2HSV	H: 0-179、S/V: 0-255

補間方法	最適な用途	速度
INTER_NEAREST	速度重視、ピクセル化しても問題ない場合	最速
INTER_LINEAR	汎用（デフォルト）	高速
INTER_AREA	縮小	中速
INTER_CUBIC	高品質な拡大	低速
INTER_LANCZOS4	最高品質の拡大	最低速

このスキルを使う場面

コンピュータービジョンと画像処理に使用します。

• 画像の読み込み、表示、保存
• カメラまたはファイルからの動画キャプチャ
• 画像のフィルタリングと変換
• エッジおよび輪郭の検出
• 物体検出とテンプレートマッチング
• 特徴の検出とマッチング
• DNN モジュールを使ったディープラーニングの推論

関連スキル：

• NumPy 配列については、python-fundamentals-313 を参照してください
• 非同期処理については、python-asyncio を参照してください
• 型ヒントについては、python-type-hints を参照してください

---

OpenCV Python 完全ガイド（2025）

概要

OpenCV（Open Source Computer Vision Library）は、最も広く利用されているコンピュータービジョンライブラリです。Python バインディング（opencv-python）により、NumPy 配列を通じてすべての機能を利用できます。OpenCV はデフォルトで BGR の色形式を使用するため、特に注意が必要です。

インストール

# CPU-only (most common)
pip install opencv-python

# With contrib modules (SIFT, SURF, extra features)
pip install opencv-contrib-python

# Headless (no GUI, for servers)
pip install opencv-python-headless

# Verify installation
python -c "import cv2; print(cv2.__version__)"

主な注意点

• OpenCV は RGB ではなく BGR を使用します。Matplotlib／PIL で表示する前に変換し、cv2.imwrite の前に元に戻してください。
• 画像の shape は (height, width, channels)、NumPy のインデックス指定は img[row, col] ですが、OpenCV の描画関数では (x, y) を使用します。
• cv2.imread は、ファイルが存在しない場合やデコードできない場合に None を返します。画像を使用する前に必ず確認してください。
• VideoCapture と GUI ウィンドウは、finally またはコンテキストマネージャーによるクリーンアップ処理で解放／終了する必要があります。
• NumPy の演算では uint8 がオーバーフローすることがあります。必要に応じて OpenCV の演算を使うか、明示的に浮動小数点数へ正規化してください。

完全な例と安全なパターンについては、references/opencv-critical-gotchas.md を参照してください。

リファレンスマップ

詳細な API パターンとコードレシピは、目的別のリファレンスに分割されています。ユーザーのタスクに合ったファイルを読み込んでください。

重要な注意点 -> references/opencv-critical-gotchas.md

OpenCV でよくある問題の完全な例については、こちらを参照してください。

• BGR/RGB 変換：Matplotlib および PIL との連携、正しい cv2.imwrite の使い方
• 座標の順序：shape、NumPy のインデックス指定、描画関数、ROI スライス
• 画像の読み込み失敗：cv2.imread の None チェックと pathlib による検証
• 動画のクリーンアップ：VideoCapture の解放パターンとコンテキストマネージャーのラッパー
• データ型の安全性：uint8 のオーバーフロー、cv2.add、浮動小数点数への正規化、Canny が想定するデータ型

コア操作 -> references/opencv-core-operations.md

日常的な OpenCV の作業については、こちらを参照してください。

• 画像の入出力：cv2.imread のフラグ、URL からの読み込み、cv2.imwrite の品質パラメーター、複数画像の一括読み込み
• 動画のキャプチャと書き込み：カメラ／ファイルからのキャプチャ、VideoWriter のコーデック（mp4v、XVID、H264）、FPS／解像度の確認
• 色空間の変換：BGR／RGB／HSV／Gray／Lab、HSV による色検出（赤／緑／青の範囲と、赤のデュアルレンジ）、ホワイトバランス用ヘルパー
• 画像フィルタリング：GaussianBlur、medianBlur、bilateralFilter、Sobel／Laplacian／Canny によるエッジ検出、モルフォロジー演算（erode、dilate、open、close、gradient、tophat）
• 輪郭の検出：findContours、面積／周長、バウンディングボックス、輪郭の近似、階層構造
• 画像のリサイズと変換：アスペクト比を維持したリサイズ、回転、アフィン変換／射影変換、warpAffine と warpPerspective の違い
• テンプレートマッチング：cv2.matchTemplate、マルチスケールマッチング、TM_CCOEFF_NORMED によるしきい値処理
• 特徴点の検出：ORB、SIFT、AKAZE のキーポイント、BFMatcher と FLANN マッチャー、比率テスト
• DNN モジュール：ONNX／TF／Caffe 用の cv2.dnn.readNet、Blob の前処理、YOLO／MobileNet の推論
• 画像の表示：cv2.imshow と waitKey のループ、Matplotlib を使用した Jupyter の cv2.imshow 回避策
• パフォーマンスのヒント：NumPy のベクトル化、連続配列、OpenCL 用の cv2.UMat、GPU 処理用の cv2.cuda
• 描画関数：rectangle、circle、line、ellipse、polylines、fillPoly、putText、getTextSize

高度なパターン -> references/opencv-advanced-patterns.md

専門的なコンピュータービジョンのパイプラインについては、こちらを参照してください。

• 背景差分：MOG2、KNN
• 物体追跡：CSRT、KCF、MOSSE、マルチオブジェクトトラッカー
• カメラキャリブレーション：チェスボードのコーナー検出、内部パラメーター／歪み行列、undistort
• ステレオビジョン：StereoBM、StereoSGBM、視差マップ
• オプティカルフロー：Lucas-Kanade の疎なオプティカルフロー、Farneback の密なオプティカルフロー
• 画像のスティッチング：cv2.Stitcher によるパノラマの組み立て
• 顔検出：Haar カスケード、DNN 顔検出器
• ArUco マーカー：マーカーの検出と姿勢推定

トリガーフレーズ

次のいずれかをユーザーが話題にした場合、このスキルを有効にしてください：OpenCV、cv2、BGR、画像処理、輪郭、Canny、Hough 変換、テンプレートマッチング、ORB／SIFT／AKAZE、VideoCapture、VideoWriter、cv2.dnn、cv2.cuda、Python でのコンピュータービジョン。