OpenCVとカスケード分類器で作るリアルタイム顔検出プロジェクト

python -m venv myenv

myenv\Scripts\activate

python3 -m venv myenv

source myenv/bin/activate

opencv-python==4.11.0.86

pip install -r requirements.txt

# 必要なライブラリをインポート
import cv2 as cv  # OpenCVライブラリ（画像・動画処理用）
import os  # ファイルパス操作用
import time  # 時間計測用


class WebcamDetector:
    """
    Webカメラを使用したリアルタイム検出システムのメインクラス
    """
    
    def __init__(self):
        """
        WebcamDetectorクラスの初期化メソッド
        オブジェクト作成時に自動で呼ばれる
        """
        # カメラ関連の初期値設定
        self.camera = None  # Webカメラオブジェクト格納用
        self.is_running = False  # システム動作状態の管理フラグ
        self.window_name = "Real-time Detection System"  # 表示ウィンドウ名
        self.camera_index = 0  # 使用カメラの番号（0が標準）

    def check_camera_permission(self):
        """
        利用可能なカメラを検索して接続テストを行うメソッド
        複数のカメラがある場合も自動で最適なものを選択
        
        Returns:
            int: 使用可能なカメラ番号、見つからない場合は-1
        """
        print("利用可能なカメラを検索しています...")
        
        # カメラ番号0〜3まで順番にテスト
        for index in range(4):
            print(f"カメラ番号 {index} をテスト中...")
            
            # テスト用カメラオブジェクトを作成
            test_camera = cv.VideoCapture(index)
            
            # カメラが開けるかチェック
            if test_camera.isOpened():
                # 実際に画像が取得できるかテスト
                ret, frame = test_camera.read()
                # テスト完了後はリソースを解放
                test_camera.release()
                
                # 画像取得成功なら使用可能
                if ret and frame is not None:
                    print(f"カメラ番号 {index} が利用可能です")
                    return index
                else:
                    print(f"カメラ番号 {index} は画像取得に失敗")
            else:
                print(f"カメラ番号 {index} にアクセスできません")
        
        # 利用可能なカメラが見つからない場合
        print("利用可能なカメラが見つかりませんでした")
        return -1

    def setup_camera(self):
        """
        Webカメラの初期化と各種設定を行うメソッド
        カメラアクセス確認と詳細設定を一括処理
        
        Returns:
            bool: 初期化成功でTrue、失敗でFalse
        """
        # まずカメラアクセス許可状況を確認
        available_camera = self.check_camera_permission()
        
        # 利用可能カメラが見つからない場合の対処
        if available_camera == -1:
            print("\n=== カメラアクセスのトラブルシューティング ===")
            print("1. カメラが他のアプリで使用中でないか確認")
            print("2. macOSの場合 システム環境設定 > セキュリティとプライバシー > カメラ")
            print("3. Windowsの場合 設定 > プライバシー > カメラ")
            print("4. ターミナルやVSCodeにカメラ許可を与える")
            return False
        
        # 使用するカメラ番号を記録
        self.camera_index = available_camera
        
        try:
            # VideoCapture オブジェクトでカメラに接続
            self.camera = cv.VideoCapture(self.camera_index)
            
            # カメラが正常に開かれているか最終確認
            if not self.camera.isOpened():
                print("エラー Webカメラの初期化に失敗しました")
                return False
            
            # カメラの安定化待機（重要）
            time.sleep(1)
            
            # 解像度設定（640x480ピクセル）
            self.camera.set(cv.CAP_PROP_FRAME_WIDTH, 640)
            self.camera.set(cv.CAP_PROP_FRAME_HEIGHT, 480)
            
            # フレームレート設定（1秒30枚）
            self.camera.set(cv.CAP_PROP_FPS, 30)
            
            # バッファサイズ調整でリアルタイム性向上
            self.camera.set(cv.CAP_PROP_BUFFERSIZE, 1)
            
            print(f"カメラ番号 {self.camera_index} で初期化完了")
            return True
            
        except Exception as e:
            print(f"カメラ初期化中にエラー発生 {e}")
            return False

    def capture_frame(self):
        """
        Webカメラから1枚の画像（フレーム）を取得するメソッド
        エラー対策として複数回の取得試行を実装
        
        Returns:
            tuple: (成功フラグ, 画像データ) の組み合わせ
        """
        # カメラが初期化されているかチェック
        if self.camera is None:
            print("エラー カメラが初期化されていません")
            return False, None
        
        # 最大3回まで取得を試行
        for attempt in range(3):
            # カメラから1フレーム読み取り
            success, frame = self.camera.read()
            
            # 取得成功かつ画像データが存在するかチェック
            if success and frame is not None:
                # 画像データが空でないか最終確認
                if frame.size > 0:
                    return True, frame
                else:
                    print(f"警告 空の画像を取得 (試行 {attempt + 1}/3)")
            else:
                print(f"警告 画像取得に失敗 (試行 {attempt + 1}/3)")
            
            # 次の試行前に少し待機
            time.sleep(0.1)
        
        # 全試行失敗の場合
        return False, None

    def display_frame(self, frame):
        """
        取得した画像をウィンドウに表示するメソッド
        ウィンドウサイズ調整も自動で実行
        
        Args:
            frame: 表示したい画像データ（numpy配列形式）
        """
        # 画像データが存在するかチェック
        if frame is None:
            return
        
        # ウィンドウサイズを画像に合わせて自動調整
        cv.namedWindow(self.window_name, cv.WINDOW_AUTOSIZE)
        
        # 指定したウィンドウに画像を表示
        cv.imshow(self.window_name, frame)

    def check_exit_key(self):
        """
        キーボード入力を監視して終了指示を検出するメソッド
        
        Returns:
            bool: 終了キー押下でTrue、それ以外でFalse
        """
        # 30ミリ秒間キー入力を待機（フレームレート調整も兼ねる）
        key = cv.waitKey(30) & 0xFF
        
        # 'q'キー、'Q'キー、ESCキー（番号27）のいずれかが押されたかチェック
        if key == ord('q') or key == ord('Q') or key == 27:
            return True
        
        # 上記以外のキーまたはキー入力なしの場合
        return False

    def ensure_window_focus(self):
        """
        OpenCVウィンドウを最前面に表示してキー入力を受けやすくするメソッド
        特にmacOSでキー入力が効かない問題の対策
        """
        # ウィンドウを一時的に最前面に移動
        cv.setWindowProperty(self.window_name, cv.WND_PROP_TOPMOST, 1)
        # すぐに最前面設定を解除（通常状態に戻す）
        cv.setWindowProperty(self.window_name, cv.WND_PROP_TOPMOST, 0)

    def run_detection(self):
        """
        リアルタイム映像表示のメインループ実行メソッド
        カメラ初期化から終了まで全体制御を行う
        """
        # Step1 カメラの初期化処理
        if not self.setup_camera():
            print("カメラ初期化失敗のため終了します")
            return
        
        # Step2 システム動作開始の準備
        self.is_running = True
        print("検出システムを開始します")
        print("終了するには 'q' キーまたはESCキーを押してください")
        print("※ウィンドウをクリックしてからキーを押してください")
        
        # カウンタ変数の初期化
        frame_count = 0  # 処理したフレーム数
        error_count = 0  # 連続エラー数
        max_errors = 10  # 許可する最大連続エラー数
        
        try:
            # Step3 メインループ開始
            while self.is_running:
                # フレーム取得処理
                success, frame = self.capture_frame()
                
                # フレーム取得失敗の場合
                if not success:
                    error_count += 1
                    print(f"フレーム取得エラー ({error_count}/{max_errors})")
                    
                    # 連続エラーが上限に達した場合は終了
                    if error_count >= max_errors:
                        print("連続エラー上限に達したため終了します")
                        break
                    
                    # 次のループに進む
                    continue
                
                # フレーム取得成功時の処理
                error_count = 0  # エラーカウントをリセット
                frame_count += 1  # 成功フレーム数をカウント
                
                # 取得したフレームを画面に表示
                self.display_frame(frame)
                
                # 初回表示時のみウィンドウフォーカス設定
                if frame_count == 1:
                    self.ensure_window_focus()
                
                # 終了キー入力チェック
                if self.check_exit_key():
                    print("終了キーが検出されました")
                    self.is_running = False
                    break
        
        # Ctrl+Cでの強制終了をキャッチ
        except KeyboardInterrupt:
            print("\nプログラムが中断されました")
        
        # 正常・異常終了に関わらず実行される処理
        finally:
            print(f"総フレーム数 {frame_count}")
            # リソース解放処理を実行
            self.cleanup()

    def cleanup(self):
        """
        プログラム終了時のリソース解放処理
        メモリリークやカメラ占有を防ぐ重要な処理
        """
        print("リソースを解放しています...")
        
        # カメラリソースの解放処理
        if self.camera is not None:
            # カメラ接続を終了
            self.camera.release()
            print("カメラリソースを解放しました")
        
        # すべてのOpenCVウィンドウを閉じる
        cv.destroyAllWindows()
        
        # ウィンドウが完全に閉じるまで待機
        for i in range(5):
            cv.waitKey(1)
        
        print("ウィンドウを閉じました")
        print("クリーンアップが完了しました")

def main():
    """
    プログラムのメイン実行関数
    WebcamDetectorオブジェクトを作成してシステム開始
    """
    # システム開始のお知らせ
    print("=== リアルタイム検出システム ===")
    print("Webカメラを使用した検出システムを開始します")
    print()
    
    # WebcamDetectorのインスタンス（実体）を作成
    detector = WebcamDetector()
    
    # 検出システムのメイン処理を開始
    detector.run_detection()
    
    # システム終了のお知らせ
    print("プログラムを終了します")


# スクリプトが直接実行された場合のみmain関数を呼び出し
if __name__ == "__main__":
    main()

python src/webcam_detector.py

python3 src/webcam_detector.py

    def __init__(self):
        """
        WebcamDetectorクラスの初期化メソッド
        オブジェクト作成時に自動で呼ばれる
        """
        # カメラ関連の初期値設定
        self.camera = None  # Webカメラオブジェクト格納用
        self.is_running = False  # システム動作状態の管理フラグ
        self.window_name = "Real-time Detection System"  # 表示ウィンドウ名
        self.camera_index = 0  # 使用カメラの番号（0が標準）
        
        # 以下を追加 カスケード分類器関連の初期値設定
        self.face_cascade = None  # 顔検出用分類器オブジェクト
        self.eye_cascade = None  # 目検出用分類器オブジェクト
        self.eye_glasses_cascade = None  # メガネ対応目検出用分類器オブジェクト
        self.classifiers_loaded = False  # 分類器読み込み完了フラグ

    def check_classifier_files(self):
        """
        カスケード分類器XMLファイルの存在確認メソッド
        プロジェクトフォルダ内の分類器ファイルを自動検索
        
        Returns:
            dict: 各分類器ファイルのパス情報を格納した辞書
        """
        print("カスケード分類器ファイルの存在確認を開始します...")
        
        # 現在のファイルから2階層上がプロジェクトルート
        base_dir = os.path.dirname(os.path.dirname(__file__))
        # classifiersフォルダのパスを作成
        classifiers_dir = os.path.join(base_dir, 'classifiers')
        
        # 必要な分類器ファイル名とパスの定義
        classifier_files = {
            'face': os.path.join(classifiers_dir, 'haarcascade_frontalface_default.xml'),
            'eye': os.path.join(classifiers_dir, 'haarcascade_eye.xml'),
            'eye_glasses': os.path.join(classifiers_dir, 'haarcascade_eye_tree_eyeglasses.xml')
        }
        
        # ファイル存在状況を記録する辞書
        file_status = {}
        
        # 各ファイルの存在確認ループ
        for classifier_type, file_path in classifier_files.items():
            # ファイルが存在するかチェック
            if os.path.exists(file_path):
                print(f"✓ {classifier_type} 分類器ファイルを発見 {os.path.basename(file_path)}")
                file_status[classifier_type] = file_path  # パスを記録
            else:
                print(f"✗ {classifier_type} 分類器ファイルが見つかりません {file_path}")
                file_status[classifier_type] = None  # 見つからない場合はNone
        
        return file_status

    def load_cascades(self):
        """
        カスケード分類器をメモリに読み込んで使用準備するメソッド
        3つの分類器（顔、目、メガネ対応目）を順次読み込み
        
        Returns:
            bool: 必須分類器の読み込み成功でTrue、失敗でFalse
        """
        print("カスケード分類器の読み込みを開始します...")
        
        # まずファイル存在確認を実行
        file_status = self.check_classifier_files()
        
        try:
            # 顔検出用分類器の読み込み（必須）
            if file_status['face']:
                # XMLファイルから分類器オブジェクトを作成
                self.face_cascade = cv.CascadeClassifier(file_status['face'])
                # 読み込み成功確認（空のオブジェクトでないかチェック）
                if self.face_cascade.empty():
                    print("エラー 顔検出分類器の読み込みに失敗しました")
                    return False
                print("顔検出分類器の読み込み完了")
            else:
                print("エラー 顔検出分類器ファイルが見つかりません")
                return False
            
            # 目検出用分類器の読み込み（必須）
            if file_status['eye']:
                # XMLファイルから分類器オブジェクトを作成
                self.eye_cascade = cv.CascadeClassifier(file_status['eye'])
                # 読み込み成功確認
                if self.eye_cascade.empty():
                    print("エラー 目検出分類器の読み込みに失敗しました")
                    return False
                print("目検出分類器の読み込み完了")
            else:
                print("エラー 目検出分類器ファイルが見つかりません")
                return False
            
            # メガネ対応目検出用分類器の読み込み（オプション）
            if file_status['eye_glasses']:
                # XMLファイルから分類器オブジェクトを作成
                self.eye_glasses_cascade = cv.CascadeClassifier(file_status['eye_glasses'])
                # 読み込み失敗でもシステム継続（オプション機能のため）
                if self.eye_glasses_cascade.empty():
                    print("警告 メガネ対応目検出分類器の読み込みに失敗（オプション機能）")
                    self.eye_glasses_cascade = None
                else:
                    print("メガネ対応目検出分類器の読み込み完了")
            else:
                print("警告 メガネ対応目検出分類器ファイルが見つかりません（オプション機能）")
                self.eye_glasses_cascade = None
            
            # 読み込み完了フラグを設定
            self.classifiers_loaded = True
            print("カスケード分類器の読み込みが完了しました")
            return True
            
        except Exception as e:
            print(f"分類器読み込み中にエラーが発生しました {e}")
            return False

    def convert_to_grayscale(self, frame):
        """
        カラー画像をグレースケール（白黒）に変換するメソッド
        検出処理の高速化と精度向上のため
        
        Args:
            frame: 変換元のカラー画像（BGR形式）
        
        Returns:
            numpy.ndarray: グレースケール変換後の画像データ
        """
        # 入力画像の存在確認
        if frame is None:
            return None
        
        # BGRカラーからグレースケールに変換
        gray_frame = cv.cvtColor(frame, cv.COLOR_BGR2GRAY)
        
        return gray_frame

    def prepare_detection(self, frame):
        """
        検出処理実行前の準備作業メソッド
        画像品質チェックとグレースケール変換を実行
        
        Args:
            frame: 処理対象の元画像
        
        Returns:
            tuple: (元画像, グレースケール画像) の組み合わせ
                  エラー時は (None, None)
        """
        # 入力画像の存在確認
        if frame is None:
            return None, None
        
        # 画像サイズの取得と最小サイズチェック
        height, width = frame.shape[:2]
        if width < 100 or height < 100:
            print("警告 画像サイズが小さすぎます")
            return None, None
        
        # カラー画像をグレースケールに変換
        gray_frame = self.convert_to_grayscale(frame)
        
        # グレースケール変換の成功確認
        if gray_frame is None:
            print("エラー グレースケール変換に失敗しました")
            return None, None
        
        # 元画像とグレースケール画像の両方を返す
        return frame, gray_frame

    def run_detection(self):
        """
        リアルタイム検出のメインループ実行メソッド
        カメラ初期化から分類器読み込み、検出処理まで全体制御
        """
        # Step1 カメラの初期化処理
        if not self.setup_camera():
            print("カメラ初期化失敗のため終了します")
            return
        
        # 以下を追加 Step2 カスケード分類器の読み込み処理
        if not self.load_cascades():
            print("カスケード分類器読み込み失敗のため終了します")
            # カメラリソース解放してから終了
            self.cleanup()
            return
        
        # Step3 システム動作開始の準備
        self.is_running = True
        print("検出システムを開始します")
        print("終了するには 'q' キーまたはESCキーを押してください")
        print("※ウィンドウをクリックしてからキーを押してください")
        
        # カウンタ変数の初期化
        frame_count = 0  # 処理したフレーム数
        error_count = 0  # 連続エラー数
        max_errors = 10  # 許可する最大連続エラー数
        
        try:
            # Step4 メインループ開始
            while self.is_running:
                # フレーム取得処理
                success, frame = self.capture_frame()
                
                # フレーム取得失敗の場合
                if not success:
                    error_count += 1
                    print(f"フレーム取得エラー ({error_count}/{max_errors})")
                    
                    # 連続エラーが上限に達した場合は終了
                    if error_count >= max_errors:
                        print("連続エラー上限に達したため終了します")
                        break
                    
                    # 次のループに進む
                    continue
                
                # フレーム取得成功時の処理
                error_count = 0  # エラーカウントをリセット
                frame_count += 1  # 成功フレーム数をカウント
                
                # 以下を追加 Step5 検出前準備処理
                processed_frame, gray_frame = self.prepare_detection(frame)
                
                # 準備処理失敗時はスキップ
                if processed_frame is None:
                    continue
                
                # 準備完了した画像を表示（まだ検出結果は描画していない）
                self.display_frame(processed_frame)
                
                # 初回表示時のみウィンドウフォーカス設定
                if frame_count == 1:
                    self.ensure_window_focus()
                
                # 終了キー入力チェック
                if self.check_exit_key():
                    print("終了キーが検出されました")
                    self.is_running = False
                    break
        
        # Ctrl+Cでの強制終了をキャッチ
        except KeyboardInterrupt:
            print("\nプログラムが中断されました")
        
        # 正常・異常終了に関わらず実行される処理
        finally:
            print(f"総フレーム数 {frame_count}")
            # リソース解放処理を実行
            self.cleanup()

def main():
    """
    プログラムのメイン実行関数
    WebcamDetectorオブジェクトを作成してシステム開始
    """
    # システム開始のお知らせ
    print("=== リアルタイム検出システム ===")
    print("Webカメラを使用した検出システムを開始します")
    print("顔・目検出用のカスケード分類器を読み込みます")
    print()
    
    # WebcamDetectorのインスタンス（実体）を作成
    detector = WebcamDetector()
    
    # 検出システムのメイン処理を開始
    detector.run_detection()
    
    # システム終了のお知らせ
    print("プログラムを終了します")


# スクリプトが直接実行された場合のみmain関数を呼び出し
if __name__ == "__main__":
    main()

python src/webcam_detector.py

python3 src/webcam_detector.py

    def detect_faces(self, gray_frame):
        """
        グレースケール画像から顔を検出するメソッド
        カスケード分類器を使用した顔領域の特定
        
        Args:
            gray_frame: グレースケール変換済みの画像データ
        
        Returns:
            numpy.ndarray: 検出された顔の座標情報配列 (x, y, width, height)
        """
        # 入力画像と分類器の存在確認
        if gray_frame is None or self.face_cascade is None:
            return []
        
        try:
            # detectMultiScale関数で顔検出を実行
            faces = self.face_cascade.detectMultiScale(
                gray_frame,                # 検索対象の画像データ
                scaleFactor=1.1,          # 画像縮小比率（1.1は10%ずつ縮小）
                minNeighbors=5,           # 検出に必要な近隣矩形数（誤検出防止）
                minSize=(30, 30),         # 検出する顔の最小サイズ（ピクセル）
                maxSize=(300, 300)        # 検出する顔の最大サイズ（ピクセル）
            )
            
            # 検出結果を配列で返す
            return faces
            
        except Exception as e:
            print(f"顔検出中にエラーが発生しました {e}")
            return []

    def detect_eyes(self, gray_frame, face_roi=None):
        """
        グレースケール画像から目を検出するメソッド
        顔領域指定時はその範囲内で効率的に検出
        
        Args:
            gray_frame: グレースケール変換済みの画像データ
            face_roi: 顔領域の座標 (x, y, width, height)、Noneで画像全体検索
        
        Returns:
            numpy.ndarray: 検出された目の座標情報配列 (x, y, width, height)
        """
        # 入力画像と分類器の存在確認
        if gray_frame is None or self.eye_cascade is None:
            return []
        
        try:
            # 検索範囲の設定処理
            if face_roi is not None:
                # 顔領域の座標とサイズを取得
                x, y, w, h = face_roi
                # 顔の上半分のみを目検索対象にする（目は顔の上部にあるため）
                roi_gray = gray_frame[y:y + h//2, x:x + w]
                # 元画像座標系への変換用のオフセット値
                detection_area = (x, y)
            else:
                # 顔領域未指定時は画像全体を検索
                roi_gray = gray_frame
                detection_area = (0, 0)
            
            # 目検出の実行
            eyes = self.eye_cascade.detectMultiScale(
                roi_gray,
                scaleFactor=1.05,         # 目は小さいのでより細かい縮小率
                minNeighbors=3,           # 顔より緩い条件で検出
                minSize=(10, 10),         # 目の最小サイズ
                maxSize=(50, 50)          # 目の最大サイズ
            )
            
            # 座標を元の画像座標系に変換
            if face_roi is not None and len(eyes) > 0:
                # x座標を元画像座標系に補正
                eyes[:, 0] += detection_area[0]
                # y座標を元画像座標系に補正
                eyes[:, 1] += detection_area[1]
            
            # 検出結果を返す
            return eyes
            
        except Exception as e:
            print(f"目検出中にエラーが発生しました {e}")
            return []

    def detect_eyes_with_glasses(self, gray_frame, face_roi=None):
        """
        メガネ着用者に対応した目検出メソッド
        通常の目検出で失敗した場合の補完機能
        
        Args:
            gray_frame: グレースケール変換済みの画像データ
            face_roi: 顔領域の座標 (x, y, width, height)
        
        Returns:
            numpy.ndarray: 検出された目の座標情報配列 (x, y, width, height)
        """
        # 入力画像とメガネ対応分類器の存在確認
        if gray_frame is None or self.eye_glasses_cascade is None:
            return []
        
        try:
            # 検索範囲の設定処理
            if face_roi is not None:
                # 顔領域の座標とサイズを取得
                x, y, w, h = face_roi
                # 顔の上半分でメガネ対応検出を実行
                roi_gray = gray_frame[y:y + h//2, x:x + w]
                # 元画像座標系への変換用のオフセット値
                detection_area = (x, y)
            else:
                # 顔領域未指定時は画像全体を検索
                roi_gray = gray_frame
                detection_area = (0, 0)
            
            # メガネ対応目検出の実行
            eyes_glasses = self.eye_glasses_cascade.detectMultiScale(
                roi_gray,
                scaleFactor=1.1,          # メガネありの場合のスケール設定
                minNeighbors=4,           # 中間的な条件設定
                minSize=(15, 15),         # メガネ込みの最小サイズ
                maxSize=(80, 80)          # メガネ込みの最大サイズ
            )
            
            # 座標補正処理
            if face_roi is not None and len(eyes_glasses) > 0:
                # x座標を元画像座標系に補正
                eyes_glasses[:, 0] += detection_area[0]
                # y座標を元画像座標系に補正
                eyes_glasses[:, 1] += detection_area[1]
            
            # 検出結果を返す
            return eyes_glasses
            
        except Exception as e:
            print(f"メガネ対応目検出中にエラーが発生しました {e}")
            return []

    def draw_detection_results(self, frame, faces, eyes):
        """
        検出結果を画像に矩形とラベルで描画するメソッド
        顔と目を異なる色で視覚的に区別
        
        Args:
            frame: 描画対象のカラー画像
            faces: 検出された顔の座標配列
            eyes: 検出された目の座標配列
        
        Returns:
            numpy.ndarray: 描画処理完了後の画像データ
        """
        # 入力画像の存在確認
        if frame is None:
            return frame
        
        # 元画像を保護するためコピーを作成
        result_frame = frame.copy()
        
        # 検出された顔に矩形とラベルを描画
        for (x, y, w, h) in faces:
            # 緑色の矩形で顔を囲む
            cv.rectangle(
                result_frame,              # 描画対象の画像
                (x, y),                    # 矩形の左上角座標
                (x + w, y + h),           # 矩形の右下角座標
                (0, 255, 0),              # 色指定（BGR形式で緑色）
                2                         # 矩形線の太さ
            )
            
            # 顔矩形の上部に「Face」ラベルを表示
            cv.putText(
                result_frame,
                'Face',                    # 表示する文字列
                (x, y - 10),              # 文字の表示位置
                cv.FONT_HERSHEY_SIMPLEX,  # フォントの種類
                0.6,                      # 文字サイズ
                (0, 255, 0),              # 文字色（緑色）
                2                         # 文字の太さ
            )
        
        # 検出された目に矩形とラベルを描画
        for (x, y, w, h) in eyes:
            # 青色の矩形で目を囲む
            cv.rectangle(
                result_frame,
                (x, y),                    # 矩形の左上角座標
                (x + w, y + h),           # 矩形の右下角座標
                (255, 0, 0),              # 色指定（BGR形式で青色）
                1                         # 矩形線の太さ（目は細く）
            )
            
            # 目矩形の上部に「Eye」ラベルを表示
            cv.putText(
                result_frame,
                'Eye',                     # 表示する文字列
                (x, y - 5),               # 文字の表示位置
                cv.FONT_HERSHEY_SIMPLEX,  # フォントの種類
                0.4,                      # 小さめの文字サイズ
                (255, 0, 0),              # 文字色（青色）
                1                         # 文字の太さ
            )
        
        # 描画完了した画像を返す
        return result_frame

    def perform_detection(self, frame, gray_frame):
        """
        顔と目の検出を統合実行して結果描画するメソッド
        検出ロジックと描画処理を一元管理
        
        Args:
            frame: 元のカラー画像
            gray_frame: グレースケール変換済み画像
        
        Returns:
            numpy.ndarray: 検出結果が描画された画像
        """
        # 入力画像の存在確認
        if frame is None or gray_frame is None:
            return frame
        
        # Step1 顔検出の実行
        faces = self.detect_faces(gray_frame)
        
        # Step2 目検出の実行準備
        all_eyes = []  # 全ての目検出結果を格納
        
        # 顔が検出された場合の処理
        if len(faces) > 0:
            # 各検出顔に対して目検出を実行
            for face in faces:
                # 通常の目検出を試行
                eyes = self.detect_eyes(gray_frame, face)
                
                # 通常検出で目が見つからず、メガネ対応分類器が利用可能な場合
                if len(eyes) == 0 and self.eye_glasses_cascade is not None:
                    # メガネ対応目検出を試行
                    eyes = self.detect_eyes_with_glasses(gray_frame, face)
                
                # 検出された目があれば全体リストに追加
                if len(eyes) > 0:
                    all_eyes.extend(eyes)
        else:
            # 顔が検出されなかった場合は画像全体で目検出
            eyes = self.detect_eyes(gray_frame)
            if len(eyes) > 0:
                all_eyes.extend(eyes)
        
        # Step3 検出結果の描画
        result_frame = self.draw_detection_results(frame, faces, all_eyes)
        
        # 検出状況をコンソールに出力（デバッグ用）
        if len(faces) > 0 or len(all_eyes) > 0:
            print(f"検出結果 顔{len(faces)}個, 目{len(all_eyes)}個")
        
        # 描画完了した画像を返す
        return result_frame

    def run_detection(self):
        """
        リアルタイム検出のメインループ実行メソッド
        カメラ初期化から検出処理、結果表示まで全体制御
        """
        # Step1 カメラの初期化処理
        if not self.setup_camera():
            print("カメラ初期化失敗のため終了します")
            return
        
        # Step2 カスケード分類器の読み込み処理
        if not self.load_cascades():
            print("カスケード分類器読み込み失敗のため終了します")
            # カメラリソース解放してから終了
            self.cleanup()
            return
        
        # Step3 システム動作開始の準備
        self.is_running = True
        print("検出システムを開始します")
        print("顔と目の検出を開始します...")
        print("終了するには 'q' キーまたはESCキーを押してください")
        print("※ウィンドウをクリックしてからキーを押してください")
        
        # カウンタ変数の初期化
        frame_count = 0  # 処理したフレーム数
        error_count = 0  # 連続エラー数
        max_errors = 10  # 許可する最大連続エラー数
        detection_count = 0  # 検出成功回数
        
        try:
            # Step4 メインループ開始
            while self.is_running:
                # フレーム取得処理
                success, frame = self.capture_frame()
                
                # フレーム取得失敗の場合
                if not success:
                    error_count += 1
                    print(f"フレーム取得エラー ({error_count}/{max_errors})")
                    
                    # 連続エラーが上限に達した場合は終了
                    if error_count >= max_errors:
                        print("連続エラー上限に達したため終了します")
                        break
                    
                    # 次のループに進む
                    continue
                
                # フレーム取得成功時の処理
                error_count = 0  # エラーカウントをリセット
                frame_count += 1  # 成功フレーム数をカウント
                
                # Step5 検出前準備処理
                processed_frame, gray_frame = self.prepare_detection(frame)
                
                # 準備処理失敗時はスキップ
                if processed_frame is None:
                    continue
                
                # 以下を変更 Step6 検出処理と結果描画を実行
                detection_frame = self.perform_detection(processed_frame, gray_frame)
                
                # 検出結果が描画された画像を表示
                self.display_frame(detection_frame)
                
                # 初回表示時のみウィンドウフォーカス設定
                if frame_count == 1:
                    self.ensure_window_focus()
                
                # 終了キー入力チェック
                if self.check_exit_key():
                    print("終了キーが検出されました")
                    self.is_running = False
                    break
        
        # Ctrl+Cでの強制終了をキャッチ
        except KeyboardInterrupt:
            print("\nプログラムが中断されました")
        
        # 正常・異常終了に関わらず実行される処理
        finally:
            print(f"総フレーム数 {frame_count}")
            # リソース解放処理を実行
            self.cleanup()

def main():
    """
    プログラムのメイン実行関数
    WebcamDetectorオブジェクトを作成してシステム開始
    """
    # システム開始のお知らせ
    print("=== リアルタイム顔・目検出システム ===")
    print("Webカメラを使用したリアルタイム検出を開始します")
    print("顔は緑色の矩形、目は青色の矩形で表示されます")
    print()
    
    # WebcamDetectorのインスタンス（実体）を作成
    detector = WebcamDetector()
    
    # 検出システムのメイン処理を開始
    detector.run_detection()
    
    # システム終了のお知らせ
    print("プログラムを終了します")


# スクリプトが直接実行された場合のみmain関数を呼び出し
if __name__ == "__main__":
    main()

python src/webcam_detector.py

python3 src/webcam_detector.py

    def __init__(self):
        """
        WebcamDetectorクラスの初期化メソッド
        オブジェクト作成時に自動で呼ばれる
        """
        # カメラ関連の初期値設定
        self.camera = None  # Webカメラオブジェクト格納用
        self.is_running = False  # システム動作状態の管理フラグ
        self.window_name = "Real-time Detection System"  # 表示ウィンドウ名
        self.camera_index = 0  # 使用カメラの番号（0が標準）
        
        # カスケード分類器関連の初期値設定
        self.face_cascade = None  # 顔検出用分類器オブジェクト
        self.eye_cascade = None  # 目検出用分類器オブジェクト
        self.eye_glasses_cascade = None  # メガネ対応目検出用分類器オブジェクト
        self.classifiers_loaded = False  # 分類器読み込み完了フラグ
        
        # 以下を追加 統計情報管理用の初期値設定
        self.total_faces_detected = 0  # 累計検出顔数
        self.total_eyes_detected = 0  # 累計検出目数
        self.frames_with_faces = 0  # 顔が写ったフレーム数
        self.frames_with_eyes = 0  # 目が写ったフレーム数
        self.start_time = None  # システム開始時刻記録用
        self.last_fps_time = None  # FPS計算用の前回時刻
        self.fps_counter = 0  # FPS計算用のフレームカウンタ
        self.current_fps = 0  # 現在のFPS値保存用

    def calculate_fps(self):
        """
        現在のフレームレート（FPS）を計算するメソッド
        1秒間に処理できたフレーム数を測定
        
        Returns:
            float: 現在のFPS値
        """
        # 現在時刻を取得
        current_time = time.time()
        
        # 初回実行時の初期化処理
        if self.last_fps_time is None:
            self.last_fps_time = current_time
            self.fps_counter = 0
            return 0.0
        
        # フレームカウンタを増加
        self.fps_counter += 1
        
        # 前回計算から1秒経過したかチェック
        time_elapsed = current_time - self.last_fps_time
        if time_elapsed >= 1.0:
            # FPS値を計算（フレーム数 ÷ 経過時間）
            self.current_fps = self.fps_counter / time_elapsed
            # 次回計算に向けてリセット
            self.fps_counter = 0
            self.last_fps_time = current_time
        
        # 現在のFPS値を返す
        return self.current_fps

    def update_detection_stats(self, faces_count, eyes_count):
        """
        検出統計情報を更新するメソッド
        毎フレームの検出結果を累積して記録
        
        Args:
            faces_count (int): 今回フレームで検出された顔の数
            eyes_count (int): 今回フレームで検出された目の数
        """
        # 累計検出数に加算
        self.total_faces_detected += faces_count
        self.total_eyes_detected += eyes_count
        
        # 検出があったフレーム数をカウント
        if faces_count > 0:
            self.frames_with_faces += 1
        
        if eyes_count > 0:
            self.frames_with_eyes += 1

    def draw_system_info(self, frame, faces_count, eyes_count, frame_count):
        """
        画像にシステム情報（FPS、統計データ）を描画するメソッド
        リアルタイムでシステム状況を画面表示
        
        Args:
            frame: 描画対象の画像
            faces_count (int): 現在フレームの顔検出数
            eyes_count (int): 現在フレームの目検出数
            frame_count (int): 総処理フレーム数
        
        Returns:
            numpy.ndarray: システム情報が描画された画像
        """
        # 入力画像の存在確認
        if frame is None:
            return frame
        
        # 画像サイズを取得
        height, width = frame.shape[:2]
        
        # 現在のFPS値を計算
        fps = self.calculate_fps()
        
        # 情報表示用の半透明背景を作成
        overlay = frame.copy()
        # 黒い矩形を描画（左上角に配置）
        cv.rectangle(overlay, (10, 10), (300, 120), (0, 0, 0), -1)
        # 元画像と重み付き合成で半透明効果を作成
        frame = cv.addWeighted(overlay, 0.7, frame, 0.3, 0)
        
        # 表示する情報文字列を作成
        info_text = [
            f"FPS: {fps:.1f}",  # フレームレート
            f"Frame: {frame_count}",  # 総フレーム数
            f"Faces: {faces_count} (Total: {self.total_faces_detected})",  # 顔検出情報
            f"Eyes: {eyes_count} (Total: {self.total_eyes_detected})"  # 目検出情報
        ]
        
        # 各情報を順番に画面に描画
        for i, text in enumerate(info_text):
            # 表示位置を計算（20ピクセル間隔で縦に配置）
            y_position = 30 + i * 20
            # 白色文字で情報を描画
            cv.putText(
                frame,
                text,                      # 表示文字列
                (15, y_position),         # 表示位置
                cv.FONT_HERSHEY_SIMPLEX,  # フォント種類
                0.5,                      # 文字サイズ
                (255, 255, 255),          # 文字色（白色）
                1                         # 文字の太さ
            )
        
        # 情報描画完了した画像を返す
        return frame

    def detect_faces(self, gray_frame):
        """
        グレースケール画像から顔を検出するメソッド
        パラメータ最適化で精度と性能のバランス改善
        
        Args:
            gray_frame: グレースケール変換済みの画像データ
        
        Returns:
            numpy.ndarray: 検出された顔の座標情報配列 (x, y, width, height)
        """
        # 入力画像と分類器の存在確認
        if gray_frame is None or self.face_cascade is None:
            return []
        
        try:
            # detectMultiScale関数で顔検出を実行
            faces = self.face_cascade.detectMultiScale(
                gray_frame,
                scaleFactor=1.05,         # より細かいスケール調整（1.1→1.05に変更）
                minNeighbors=6,           # 誤検出防止を強化（5→6に変更）
                minSize=(40, 40),         # 最小サイズを拡大（30→40に変更）
                maxSize=(250, 250),       # 最大サイズを調整（300→250に変更）
                flags=cv.CASCADE_SCALE_IMAGE  # 検出フラグを追加（性能最適化）
            )
            
            # 検出結果を配列で返す
            return faces
            
        except Exception as e:
            print(f"顔検出中にエラーが発生しました {e}")
            return []

    def safe_detection_execute(self, frame, gray_frame):
        """
        安全な検出処理実行メソッド
        例外処理を強化してシステム安定性を向上
        
        Args:
            frame: 元のカラー画像
            gray_frame: グレースケール変換済み画像
        
        Returns:
            tuple: (処理済み画像, 顔検出数, 目検出数) の組み合わせ
        """
        try:
            # Step1 顔検出の実行
            faces = self.detect_faces(gray_frame)
            
            # Step2 目検出の実行準備
            all_eyes = []  # 全ての目検出結果を格納
            
            # 顔が検出された場合の処理
            if len(faces) > 0:
                # 各検出顔に対して目検出を実行
                for face in faces:
                    # 通常の目検出を試行
                    eyes = self.detect_eyes(gray_frame, face)
                    
                    # 通常検出で目が見つからず、メガネ対応分類器が利用可能な場合
                    if len(eyes) == 0 and self.eye_glasses_cascade is not None:
                        # メガネ対応目検出を試行
                        eyes = self.detect_eyes_with_glasses(gray_frame, face)
                    
                    # 検出された目があれば全体リストに追加
                    if len(eyes) > 0:
                        all_eyes.extend(eyes)
            else:
                # 顔が検出されなかった場合は画像全体で目検出
                eyes = self.detect_eyes(gray_frame)
                if len(eyes) > 0:
                    all_eyes.extend(eyes)
            
            # Step3 検出結果の描画
            result_frame = self.draw_detection_results(frame, faces, all_eyes)
            
            # 処理結果を返す（画像、顔数、目数）
            return result_frame, len(faces), len(all_eyes)
            
        # OpenCV固有のエラーをキャッチ
        except cv.error as e:
            print(f"OpenCV処理エラー {e}")
            return frame, 0, 0
        # その他の予期しないエラーをキャッチ
        except Exception as e:
            print(f"予期しないエラーが発生しました {e}")
            return frame, 0, 0

    def run_detection(self):
        """
        リアルタイム検出のメインループ実行メソッド
        全機能を統合した完全版の処理制御
        """
        # Step1 カメラの初期化処理
        if not self.setup_camera():
            print("カメラ初期化失敗のため終了します")
            return
        
        # Step2 カスケード分類器の読み込み処理
        if not self.load_cascades():
            print("カスケード分類器読み込み失敗のため終了します")
            # カメラリソース解放してから終了
            self.cleanup()
            return
        
        # 以下を追加 Step3 開始時刻を記録（統計計算用）
        self.start_time = time.time()
        
        # Step4 システム動作開始の準備
        self.is_running = True
        print("検出システムを開始します")
        print("顔（緑）と目（青）の検出を開始します...")
        print("画面左上にFPSと統計情報が表示されます")
        print("終了するには 'q' キーまたはESCキーを押してください")
        print("※ウィンドウをクリックしてからキーを押してください")
        
        # カウンタ変数の初期化
        frame_count = 0  # 処理したフレーム数
        error_count = 0  # 連続エラー数
        max_errors = 10  # 許可する最大連続エラー数
        
        try:
            # Step5 メインループ開始
            while self.is_running:
                # フレーム取得処理
                success, frame = self.capture_frame()
                
                # フレーム取得失敗の場合
                if not success:
                    error_count += 1
                    print(f"フレーム取得エラー ({error_count}/{max_errors})")
                    
                    # 連続エラーが上限に達した場合は終了
                    if error_count >= max_errors:
                        print("連続エラー上限に達したため終了します")
                        break
                    
                    # 次のループに進む
                    continue
                
                # フレーム取得成功時の処理
                error_count = 0  # エラーカウントをリセット
                frame_count += 1  # 成功フレーム数をカウント
                
                # Step6 検出前準備処理
                processed_frame, gray_frame = self.prepare_detection(frame)
                
                # 準備処理失敗時はスキップ
                if processed_frame is None:
                    continue
                
                # 以下を変更 Step7 安全な検出処理を実行
                detection_frame, faces_count, eyes_count = self.safe_detection_execute(processed_frame, gray_frame)
                
                # Step8 統計情報を更新
                self.update_detection_stats(faces_count, eyes_count)
                
                # Step9 システム情報を画面に描画
                final_frame = self.draw_system_info(detection_frame, faces_count, eyes_count, frame_count)
                
                # Step10 最終画像を表示
                self.display_frame(final_frame)
                
                # 初回表示時のみウィンドウフォーカス設定
                if frame_count == 1:
                    self.ensure_window_focus()
                
                # 終了キー入力チェック
                if self.check_exit_key():
                    print("終了キーが検出されました")
                    self.is_running = False
                    break
        
        # Ctrl+Cでの強制終了をキャッチ
        except KeyboardInterrupt:
            print("\nプログラムが中断されました")
        
        # 正常・異常終了に関わらず実行される処理
        finally:
            # 以下を追加 最終統計情報を表示
            self.print_final_statistics(frame_count)
            # リソース解放処理を実行
            self.cleanup()

    def print_final_statistics(self, total_frames):
        """
        プログラム終了時に最終統計情報を表示するメソッド
        システム全体の実行結果をまとめて出力
        
        Args:
            total_frames (int): 処理した総フレーム数
        """
        print("\n=== 検出システム統計情報 ===")
        
        # 実行時間と平均FPSの計算・表示
        if self.start_time is not None:
            total_time = time.time() - self.start_time
            print(f"総実行時間 {total_time:.1f}秒")
            
            if total_time > 0:
                avg_fps = total_frames / total_time
                print(f"平均FPS {avg_fps:.1f}")
        
        # 基本統計情報の表示
        print(f"総処理フレーム数 {total_frames}")
        print(f"総検出顔数 {self.total_faces_detected}")
        print(f"総検出目数 {self.total_eyes_detected}")
        
        # 検出率の計算・表示
        if total_frames > 0:
            face_detection_rate = (self.frames_with_faces / total_frames) * 100
            eye_detection_rate = (self.frames_with_eyes / total_frames) * 100
            print(f"顔検出率 {face_detection_rate:.1f}%")
            print(f"目検出率 {eye_detection_rate:.1f}%")
        
        print("=========================")

def main():
    """
    プログラムのメイン実行関数
    WebcamDetectorオブジェクトを作成してシステム開始
    """
    # システム開始のお知らせ
    print("=== リアルタイム顔・目検出システム ===")
    print("OpenCVカスケード分類器による高精度検出")
    print("顔は緑色の矩形、目は青色の矩形で表示されます")
    print("画面左上にリアルタイム統計情報が表示されます")
    print()
    
    # WebcamDetectorのインスタンス（実体）を作成
    detector = WebcamDetector()
    
    # 検出システムのメイン処理を開始
    detector.run_detection()
    
    # システム終了のお知らせ
    print("プログラムを終了します")


# スクリプトが直接実行された場合のみmain関数を呼び出し
if __name__ == "__main__":
    main()

python src/webcam_detector.py

python3 src/webcam_detector.py

# Virtual environment
myenv/

# OpenCV temporary files
*.tmp

# System files
.DS_Store
Thumbs.db

# IDE files
.vscode/settings.json
.idea/

# Cache files
__pycache__/
*.pyc
*.pyo
*.pyd