pyautogui-helper

name	pyautogui-helper
description	PyAutoGUI와 OpenCV를 결합하여 화면 고속 캡처, 고정밀 템플릿 매칭, 멀티스레딩 병렬 제어 및 다국어 텍스트 입력 우회를 지원하는 강력한 GUI 자동화 스킬입니다.

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)

4단계: 멀티스레딩 기반 병렬 제어 구현

실시간 검출 성능을 유지하기 위해 화면을 지속해서 캡처·분석하는 스레드와 마우스/키보드를 제어하는 스레드를 분리하고, 스레드 간 데이터 전송 시 락(threading.Lock)을 걸어 동기화하십시오 [8].

---

3. 리소스 및 레퍼런스 안내

효과적인 개발을 위해 이 스킬에 내장된 상세 레퍼런스와 유틸리티 코드를 적극적으로 활용하십시오.

• PyAutoGUI 핵심 API 레퍼런스: api_reference.md
  • 마우스 좌표계, 클릭 제어, 키보드 단축키 맵, 메시지 박스 등 기본 제어 명세.
• OpenCV 화면 인식 API 레퍼런스: opencv_reference.md
  • 그레이스케일 변환, 템플릿 매칭 방식(TM_CCOEFF_NORMED), 이미지 블러링 및 이진화, ORB 특징점 검출 등 핵심 비전 API 상세 정리.
• 실전 문제 해결 및 고급 설계 패턴: best_practices.md
  • 고속 캡처 기법, 점진적 매칭 감도 제어 코드, 다중 객체 중복 제거 알고리즘 및 멀티스레딩 병렬 검출기 설계 가이드.
• 검증된 유틸리티 코드: pyautogui_utils.py
  • 화면 정보 획득, OpenCV 고속 캡처, 다중 객체 좌표 검출 및 안전한 한글 입력 기능이 즉시 구현된 완성형 유틸리티 스크립트.

---

References

• [1] PyAutoGUI Documentation - PyAutoGUI 공식 사용자 가이드 및 API 개요
• [2] PyAutoGUI Design Pattern - LOCATE-INTERACT 디자인 패턴 및 안정적인 이미지 매칭 설계
• [3] PyAutoGUI Common Problems and Fixes - OS별 권한 설정 및 다국어 입력 오류 해결을 위한 실전 트러블슈팅 가이드
• [8] How To Build a Bot with OpenCV - OpenCV 객체 검출과 PyAutoGUI 제어, 멀티스레딩(Threading) 연동 실전 가이드