| 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단계: 환경 구성 및 패키지 설치
2단계: 안전 설정 및 초기화
스크립트 오작동 시 시스템 제어권을 완전히 상실하는 무한 루프 사고를 방지하기 위해, 시작부에 전역 안전장치와 지연 시간을 명시적으로 설정하십시오 [1].
import pyautogui
pyautogui.FAILSAFE = True
pyautogui.PAUSE = 0.1
3단계: 고속 화면 캡처 및 점진적 매칭 (LOCATE-INTERACT)
순수 PyAutoGUI 이미지 매칭 대신, Pillow ImageGrab 메모리 캡처와 OpenCV matchTemplate을 조합하여 성능을 극대화하십시오 [2].
from scripts.pyautogui_utils import wait_and_click_opencv
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
