🎯 HeadMouse Control

고개 회전을 인식하여 듀얼 모니터 환경에서 마우스를 제어하는 Python 애플리케이션입니다.

✨ 주요 기능

• 고개 회전 인식: MediaPipe를 사용한 실시간 얼굴 인식
• 듀얼 모니터 지원: 좌우 화면 간 자연스러운 마우스 제어
• 스마트 위치 기억: 각 화면의 이전 작업 위치 자동 저장
• 직관적인 제어: 고개를 좌우로 돌려서 화면 전환
• 실시간 GUI: 현재 상태와 설정을 실시간으로 확인

🎮 동작 방식

기본 원리

• 고개를 왼쪽으로 돌림 → 왼쪽 모니터로 마우스 이동
• 고개를 오른쪽으로 돌림 → 오른쪽 모니터로 마우스 이동
• 같은 방향 유지 → 마우스 이동 없음 (안정성)

스마트 위치 관리

• 각 모니터의 마지막 작업 위치를 자동 저장
• 화면 전환 시 이전 위치로 복원
• 다른 화면에 있을 때는 기본 위치로 이동

🛠️ 설치 방법

1. 저장소 클론

git clone https://github.com/welldoingk/headmouse-control.git
cd headmouse-control

2. 가상환경 생성 및 활성화

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

3. 필요한 패키지 설치

pip install -r requirements.txt

4. 실행

python headmouse.py

📋 시스템 요구사항

• Python: 3.8 이상
• 운영체제: Windows 10/11
• 카메라: 웹캠 또는 내장 카메라
• 모니터: 듀얼 모니터 환경 권장

🎯 사용 방법

1. 프로그램 실행

python headmouse.py

2. 초기 설정

• cx 기준값 조정: 슬라이더로 좌우 구분 민감도 설정
• 왼쪽 화면 좌표: 왼쪽 모니터의 기본 위치 설정
• 오른쪽 화면 좌표: 오른쪽 모니터의 기본 위치 설정
• 설정 저장: 변경사항을 파일로 저장

3. 사용법

• 고개를 왼쪽으로 돌림 → 왼쪽 모니터로 이동
• 고개를 오른쪽으로 돌림 → 오른쪽 모니터로 이동
• 같은 방향 유지 → 마우스 이동 없음

4. 단축키

• ESC 3회: 일시정지/재개
• ESC 4회: 프로그램 종료

⚙️ 설정 파일

headmouse_config.json

{
  "cx_threshold": 0.515,
  "left_screen_coords": [-1055, 607],
  "right_screen_coords": [889, 640]
}

• cx_threshold: 좌우 구분 기준값 (0.4~0.8)
• left_screen_coords: 왼쪽 모니터 기본 위치 [x, y]
• right_screen_coords: 오른쪽 모니터 기본 위치 [x, y]

🔧 기술 스택

• Python 3.10: 메인 프로그래밍 언어
• MediaPipe: 얼굴 인식 및 랜드마크 추출
• OpenCV: 카메라 입력 처리
• PyAutoGUI: 마우스 제어
• Tkinter: GUI 인터페이스
• NumPy: 수치 계산

📁 프로젝트 구조

headmouse-control/
├── headmouse.py          # 메인 애플리케이션
├── requirements.txt      # Python 패키지 목록
├── README.md            # 프로젝트 설명서
├── headmouse_config.json     # 설정 파일
└── venv/                # 가상환경

🎯 주요 특징

🧠 스마트한 위치 관리

• 각 모니터의 작업 위치 자동 기억
• 화면 전환 시 자연스러운 위치 복원
• 불필요한 마우스 이동 최소화

🎮 직관적인 제어

• 고개 회전만으로 화면 전환
• 복잡한 보정 과정 불필요
• 즉시 사용 가능

🛡️ 안정성

• 화면 경계 확인
• 카메라 연결 실패 시 자동 재시도
• 예외 상황 처리

⚡ 성능

• 실시간 처리 (100ms 간격)
• CPU 최적화
• 메모리 효율적 사용

🐛 문제 해결

카메라가 인식되지 않는 경우

1. 관리자 권한으로 실행
2. 다른 카메라 포트 시도 (0, 1, 2...)
3. 카메라 드라이버 업데이트

마우스가 정확하지 않은 경우

1. cx 기준값 조정
2. 모니터 좌표 재설정
3. 카메라 위치 조정

---