skills-store: Skill for Claude Code

PyAutoGUI & OpenCV Helper

PyAutoGUI는 운영체제의 마우스와 키보드를 제어하고 화면 이미지를 분석하여 다양한 GUI 환경을 자동화할 수 있는 직관적인 라이브러리입니다 [1]. 하지만 단순한 API 호출만으로는 화면 로딩 지연, 이미지 해상도 미세 오차, 다국어 입력 오류, 그리고 실시간 화면 인식 시의 연산 병목 현상에 직면하게 됩니다 [3] [8].

이 스킬은 PyAutoGUI의 강력한 제어 기능과 OpenCV의 초고속·고정밀 이미지 분석 기술을 융합하여, 오작동 없이 안정적으로 구동되는 고품질 자동화 파이프라인을 구축하기 위한 최적의 개발 지침과 검증된 유틸리티를 제공합니다 [1] [2].

1. 핵심 사용 시나리오

이 스킬은 다음과 같은 고급 GUI 자동화가 필요한 프로젝트에서 필수적으로 사용됩니다:

• 고속 화면 분석 및 실시간 반응: 프레임 변화가 빠른 게임이나 실시간 대시보드 화면을 캡처하고 대상을 지연 없이 검출해야 할 때 [8].
• 고정밀 이미지 검색 (Template Matching): 미세한 픽셀 오차나 압축 손실이 있는 이미지 환경에서 정확도 임계값(threshold)을 점진적으로 완화하며 대상을 검출할 때 [2].
• 다중 객체 동시 검출: 화면 내 동일한 아이콘이나 체크박스가 여러 개 존재할 때 이를 모두 식별하고 중복 매칭 좌표를 정교하게 필터링할 때 [1].
• 멀티스레딩 기반 제어: 화면 인식 연산과 마우스/키보드 제어 동작이 서로를 방해하지 않도록 병렬 처리 아키텍처를 설계할 때 [8].
• 안전장치 및 한글 입력 우회: 제어권 상실을 방지하는 Fail-Safe 안전장치 설계 및 클립보드를 활용한 한글 타이핑이 필요할 때 [1] [3].

---

2. 권장 개발 워크플로우

PyAutoGUI와 OpenCV를 결합한 고성능 자동화 스크립트를 작성할 때는 다음 4단계 표준 프로세스를 준수하십시오.

+------------------------+      +------------------------+
| 1. 환경 구성 및 패키지  | ---> | 2. 안전 설정 및 초기화  |
+------------------------+      +------------------------+
                                             |
                                             v
+------------------------+      +------------------------+
| 4. 멀티스레딩 및 복구  | <--- | 3. 고속 캡처 및 매칭   |
+------------------------+      +------------------------+

1단계: 환경 구성 및 패키지 설치

• 필수 종속성: 고성능 템플릿 매칭과 클립보드 제어를 위해 다음 패키지들을 사전에 설치하십시오.

  sudo pip3 install pyautogui opencv-python pyperclip pillow numpy
  

• OS별 권한: macOS 환경에서는 반드시 시스템 설정 > 화면 기록 권한을 부여하고 실행 앱을 재시작해야 캡처가 정상 작동합니다 [3].

2단계: 안전 설정 및 초기화

스크립트 오작동 시 시스템 제어권을 완전히 상실하는 무한 루프 사고를 방지하기 위해, 시작부에 전역 안전장치와 지연 시간을 명시적으로 설정하십시오 [1].

import pyautogui
pyautogui.FAILSAFE = True  # 마우스를 모서리로 가져가면 강제 종료
pyautogui.PAUSE = 0.1       # 모든 제어 명령 사이에 0.1초 미세 지연 부여

3단계: 고속 화면 캡처 및 점진적 매칭 (LOCATE-INTERACT)

순수 PyAutoGUI 이미지 매칭 대신, Pillow ImageGrab 메모리 캡처와 OpenCV matchTemplate을 조합하여 성능을 극대화하십시오 [2].

from scripts.pyautogui_utils import wait_and_click_opencv

# 'button.png' 이미지가 화면에 로드될 때까지 최대 10초 대기 후 정밀 클릭
# 매칭 감도(threshold)를 자동으로 완화하며 유연하게 검색합니다.
success = wait_and_click_opencv('button.png', timeout=10, initial_threshold=0.95)