[따라하기] 파이썬 OpenCV & Tesseract: 화면 이미지 인식 자동화 매크로 만들기 실무 튜토리얼 완벽 마스터 튜토리얼

본 튜토리얼은 파이썬을 활용하여 화면 이미지 인식 기반의 자동화 매크로를 구축하는 실무 과정을 다룹니다. OpenCV 라이브러리를 통해 화면을 캡처하고 이미지를 전처리하며, Tesseract-OCR 엔진을 사용하여 이미지 내 텍스트를 인식합니다. 최종적으로 인식된 텍스트를 기반으로 마우스 클릭, 키보드 입력 등 자동화 동작을 수행하는 매크로를 구현합니다. 본 과정을 통해 컴퓨터 비전과 광학 문자 인식을 결합한 강력한 자동화 시스템 개발 능력을 습득할 수 있습니다.

학습 목표

파이썬 개발 환경에 OpenCV, Tesseract-OCR 및 관련 라이브러리를 성공적으로 설치하고 설정합니다.
pyautogui를 사용하여 화면의 특정 영역을 캡처하고 이미지 파일로 저장하는 방법을 이해합니다.
OpenCV를 활용하여 캡처된 이미지를 그레이스케일 변환, 이진화, 노이즈 제거 등 텍스트 인식에 최적화된 형태로 전처리하는 방법을 학습합니다.
Tesseract-OCR 엔진을 사용하여 전처리된 이미지에서 텍스트를 정확하게 추출하는 방법을 익힙니다.
인식된 텍스트의 존재 여부 또는 내용에 따라 마우스 클릭, 키보드 입력 등 자동화 동작을 수행하는 매크로 로직을 구현합니다.
실제 업무 환경에서 반복적인 수동 작업을 자동화하는 데 필요한 기초적인 화면 이미지 인식 매크로를 완성합니다.

준비물 및 사전 지식

준비물

운영체제: Windows 10/11, macOS, 또는 Linux
파이썬 3.8 이상 설치
인터넷 연결 (라이브러리 설치용)
텍스트 편집기 또는 IDE (Visual Studio Code, PyCharm 등)

사전 지식

파이썬 기본 문법 (변수, 조건문, 반복문, 함수) 이해
명령 프롬프트 또는 터미널 사용법

1단계: 개발 환경 설정

본격적인 실습에 앞서 필요한 파이썬 라이브러리와 Tesseract-OCR 엔진을 설치하고 설정합니다. 모든 라이브러리는 pip를 사용하여 설치하며, Tesseract-OCR은 별도의 실행 파일 설치가 필요합니다.

1.1 파이썬 및 pip 확인

명령 프롬프트(Windows) 또는 터미널(macOS/Linux)을 열고 다음 명령어를 입력하여 파이썬과 pip가 올바르게 설치되어 있는지 확인합니다.

python --version
pip --version

만약 파이썬 3이 기본이 아닌 경우, python3 또는 pip3를 사용해야 할 수 있습니다.

1.2 필수 파이썬 라이브러리 설치

다음 명령어를 사용하여 필요한 라이브러리들을 설치합니다.

opencv-python: OpenCV 라이브러리
pytesseract: Tesseract-OCR 파이썬 래퍼
Pillow: 이미지 처리 라이브러리 (pytesseract의 의존성)
numpy: 수치 계산 라이브러리 (OpenCV의 의존성)
pyautogui: GUI 자동화 라이브러리 (화면 캡처, 마우스/키보드 제어)

pip install opencv-python pytesseract Pillow numpy pyautogui

설치 중 오류가 발생하면 인터넷 연결 상태를 확인하고, pip 버전을 최신으로 업데이트해 보십시오.

python -m pip install --upgrade pip

1.3 Tesseract-OCR 엔진 설치

pytesseract는 Tesseract-OCR 엔진의 파이썬 인터페이스일 뿐입니다. 실제 OCR 기능을 수행하는 Tesseract 엔진을 별도로 설치해야 합니다.

Windows

Tesseract 다운로드 페이지에 접속합니다.
‘Windows Installer’ 섹션에서 최신 버전의 설치 파일을 다운로드하여 실행합니다.
설치 시 ‘Add to PATH’ 옵션을 반드시 선택하여 시스템 환경 변수에 Tesseract 경로를 추가합니다. 이 옵션을 선택하지 않으면 수동으로 환경 변수를 설정해야 합니다.
기본 설치 경로는 C:\Program Files\Tesseract-OCR입니다. 이 경로를 기억해 두십시오.
설치 완료 후, 명령 프롬프트에서 tesseract --version을 입력하여 설치를 확인합니다.

macOS

Homebrew를 사용하여 설치하는 것을 권장합니다.

brew install tesseract

설치 완료 후, 터미널에서 tesseract --version을 입력하여 설치를 확인합니다.

Linux (Ubuntu/Debian 기준)

sudo apt update
sudo apt install tesseract-ocr
sudo apt install tesseract-ocr-kor # 한국어 언어 팩 설치

설치 완료 후, 터미널에서 tesseract --version을 입력하여 설치를 확인합니다.

1.4 Tesseract 실행 파일 경로 설정 (Windows만 해당, macOS/Linux는 PATH에 자동 추가)

Windows의 경우, pytesseract가 Tesseract 실행 파일을 찾을 수 있도록 파이썬 코드 내에서 경로를 명시해야 할 수 있습니다. C:\Program Files\Tesseract-OCR\tesseract.exe가 기본 경로입니다.

import pytesseract
# Tesseract 설치 경로를 여기에 지정하십시오.
# 예: r'C:\Program Files\Tesseract-OCR\tesseract.exe'
pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'

# 경로가 올바르게 설정되었는지 확인
try:
    print(pytesseract.get_tesseract_version())
except pytesseract.TesseractNotFoundError:
    print("Tesseract 실행 파일을 찾을 수 없습니다. 경로를 확인하십시오.")

이후 단계의 모든 파이썬 코드 상단에 이 경로 설정 코드를 포함하는 것을 권장합니다.

2단계: 화면 캡처 및 이미지 처리

이 단계에서는 pyautogui를 사용하여 화면의 특정 영역을 캡처하고, OpenCV를 사용하여 캡처된 이미지를 텍스트 인식에 적합하도록 전처리합니다.

2.1 특정 영역 화면 캡처

pyautogui.screenshot() 함수를 사용하여 전체 화면 또는 특정 영역을 캡처할 수 있습니다. region=(left, top, width, height) 인자를 사용하여 캡처 영역을 지정합니다.

예를 들어, 화면 좌상단 (0,0)에서 시작하여 너비 800, 높이 600 픽셀 영역을 캡처하는 코드입니다.

import pyautogui
import cv2
import numpy as np

# Tesseract 경로 설정 (Windows 사용자만 해당, 필요시 주석 해제 및 경로 수정)
# import pytesseract
# pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'

def capture_screen_region(left, top, width, height, filename="screenshot.png"):
    """
    화면의 특정 영역을 캡처하여 이미지 파일로 저장하고, OpenCV 이미지 객체로 반환합니다.
    """
    print(f"화면 영역 캡처: ({left}, {top}, {width}, {height})")
    screenshot = pyautogui.screenshot(region=(left, top, width, height))
    
    # Pillow Image 객체를 OpenCV(numpy 배열) 형식으로 변환
    img_cv = cv2.cvtColor(np.array(screenshot), cv2.COLOR_RGB2BGR)
    
    cv2.imwrite(filename, img_cv) # 파일로 저장 (선택 사항)
    print(f"캡처된 이미지를 '{filename}'으로 저장했습니다.")
    return img_cv

# 예시: 화면 좌상단 (0,0)에서 800x600 영역 캡처
# 실제 환경에 맞게 left, top, width, height 값을 조정하십시오.
captured_image = capture_screen_region(0, 0, 800, 600, "captured_region.png")

# 캡처된 이미지 확인 (디버깅용)
# cv2.imshow("Captured Image", captured_image)
# cv2.waitKey(0)
# cv2.destroyAllWindows()

팁: 캡처할 영역의 좌표를 정확히 알아내려면 pyautogui.displayMousePosition() 함수를 사용하면 편리합니다. 이 함수를 실행하고 마우스를 움직이면 현재 마우스 커서의 X, Y 좌표가 터미널에 실시간으로 표시됩니다.

import pyautogui
# 마우스 커서의 현재 위치를 지속적으로 출력
pyautogui.displayMousePosition()
# 필요한 좌표를 확인 후 Ctrl+C로 종료하십시오.

2.2 이미지 전처리

Tesseract의 텍스트 인식률을 높이기 위해서는 이미지를 적절히 전처리하는 과정이 중요합니다. 일반적으로 다음 단계를 거칩니다.

그레이스케일 변환 (Grayscale Conversion): 컬러 이미지를 흑백 이미지로 변환하여 처리할 데이터 양을 줄이고 텍스트와 배경의 대비를 명확하게 합니다.
이진화 (Binarization): 이미지를 완전히 흑백으로 만들어 텍스트 영역과 배경 영역을 명확히 구분합니다. cv2.THRESH_BINARY 또는 cv2.THRESH_OTSU와 같은 방법을 사용합니다.
노이즈 제거 (Noise Removal): 작은 점이나 불필요한 선과 같은 노이즈를 제거하여 OCR 오류를 줄입니다. 모폴로지 연산(erosion, dilation, opening, closing)을 활용할 수 있습니다.

def preprocess_image_for_ocr(image):
    """
    OCR 인식을 위해 이미지를 전처리합니다.
    - 그레이스케일 변환
    - 이진화 (OTSU 알고리즘)
    - 노이즈 제거 (Opening 모폴로지 연산)
    """
    # 1. 그레이스케일 변환
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    print("이미지를 그레이스케일로 변환했습니다.")

    # 2. 이진화 (OTSU 알고리즘 사용)
    # Tesseract는 이진화된 이미지에서 더 나은 성능을 보이는 경우가 많습니다.
    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    print("이미지를 이진화했습니다.")

    # 3. 노이즈 제거 (Opening 연산)
    # Opening은 Erosion(침식) 후 Dilation(팽창)을 수행하여 작은 노이즈를 제거합니다.
    kernel = np.ones((1, 1), np.uint8) # 커널 크기는 이미지 특성에 따라 조절
    processed_image = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel, iterations=1)
    print("이미지 노이즈를 제거했습니다.")
    
    return processed_image

# 위에서 캡처한 이미지를 전처리합니다.
if 'captured_image' in locals():
    preprocessed_img = preprocess_image_for_ocr(captured_image)
    cv2.imwrite("preprocessed_image.png", preprocessed_img)
    print("전처리된 이미지를 'preprocessed_image.png'으로 저장했습니다.")

    # 전처리된 이미지 확인 (디버깅용)
    # cv2.imshow("Preprocessed Image", preprocessed_img)
    # cv2.waitKey(0)
    # cv2.destroyAllWindows()
else:
    print("캡처된 이미지가 없습니다. 2.1 단계를 먼저 실행하십시오.")

3단계: Tesseract를 이용한 텍스트 인식

이제 전처리된 이미지에서 pytesseract를 사용하여 텍스트를 추출하는 방법을 다룹니다. 한국어 텍스트 인식을 위해 언어 팩 설정도 함께 진행합니다.

3.1 이미지에서 텍스트 추출

pytesseract.image_to_string() 함수를 사용하여 이미지에서 텍스트를 추출합니다. lang 인자를 사용하여 인식할 언어를 지정할 수 있습니다. 한국어는 kor, 영어는 eng입니다. 여러 언어를 동시에 인식하려면 kor+eng와 같이 사용합니다.

import pytesseract
import cv2
import numpy as np
from PIL import Image # Pillow 라이브러리 임포트

# Tesseract 경로 설정 (Windows 사용자만 해당, 필요시 주석 해제 및 경로 수정)
pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe' # 실제 Tesseract 경로로 변경

def recognize_text_from_image(image, lang='kor+eng'):
    """
    OpenCV 이미지 객체에서 Tesseract를 사용하여 텍스트를 인식합니다.
    """
    print(f"Tesseract로 텍스트 인식 시작 (언어: {lang})...")
    
    # Tesseract는 Pillow Image 객체를 선호하므로, OpenCV 이미지를 Pillow 이미지로 변환
    # 이 과정에서 이미지가 흑백이 아닌 경우, Pillow가 자동으로 변환을 시도합니다.
    # 하지만 OpenCV에서 이미 전처리(그레이스케일, 이진화)를 수행했으므로 큰 문제는 없습니다.
    # Pillow.Image.fromarray()는 RGB 또는 RGBA 배열을 기대하므로, 흑백 이미지는 'L' 모드로 변환
    if len(image.shape) == 2: # 흑백 이미지인 경우
        pil_image = Image.fromarray(image)
    else: # 컬러 이미지인 경우
        pil_image = Image.fromarray(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))

    text = pytesseract.image_to_string(pil_image, lang=lang)
    print("텍스트 인식 완료.")
    return text.strip() # 공백 제거 후 반환

# 2단계에서 전처리된 이미지를 사용합니다.
# 만약 'preprocessed_img' 변수가 정의되지 않았다면, 예시 이미지를 로드합니다.
if 'preprocessed_img' not in locals():
    print("전처리된 이미지가 없습니다. 'preprocessed_image.png'를 로드합니다.")
    try:
        preprocessed_img = cv2.imread("preprocessed_image.png", cv2.IMREAD_GRAYSCALE)
        if preprocessed_img is None:
            raise FileNotFoundError("preprocessed_image.png 파일을 찾을 수 없습니다.")
    except FileNotFoundError as e:
        print(f"오류: {e}. 2단계의 이미지 캡처 및 전처리 코드를 먼저 실행하십시오.")
        preprocessed_img = None

if preprocessed_img is not None:
    recognized_text = recognize_text_from_image(preprocessed_img, lang='kor+eng')
    print("\n--- 인식된 텍스트 ---")
    print(recognized_text)
    print("-------------------\n")
else:
    print("텍스트 인식을 수행할 이미지가 준비되지 않았습니다.")

참고: Tesseract가 한국어 텍스트를 인식하려면 한국어 언어 팩(kor.traineddata)이 설치되어 있어야 합니다. Linux의 sudo apt install tesseract-ocr-kor 명령이 이를 설치합니다. Windows 설치 시에는 기본적으로 여러 언어 팩이 포함되거나, 설치 옵션에서 선택할 수 있습니다. 만약 인식률이 낮다면 Tesseract 설치 폴더의 tessdata 하위에 kor.traineddata 파일이 존재하는지 확인하십시오.

4단계: 인식된 텍스트 기반 자동화 로직 구현

이제 Tesseract로 인식된 텍스트를 기반으로 특정 조건을 만족할 때 pyautogui를 사용하여 자동화 동작을 수행하는 로직을 구현합니다. 여기서는 특정 텍스트가 화면에 나타나면 마우스 클릭을 수행하는 예시를 보여줍니다.

4.1 텍스트 존재 여부에 따른 동작 수행

화면에서 특정 텍스트를 찾고, 해당 텍스트가 존재하면 마우스 클릭 등의 동작을 실행합니다. pyautogui.locateOnScreen() 함수는 이미지 매칭을 통해 화면에서 특정 이미지를 찾지만, 여기서는 Tesseract로 인식된 텍스트를 기반으로 합니다.

import pyautogui
import cv2
import numpy as np
import pytesseract
from PIL import Image
import time

# Tesseract 경로 설정 (Windows 사용자만 해당, 필요시 주석 해제 및 경로 수정)
pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe' # 실제 Tesseract 경로로 변경

def capture_screen_region(left, top, width, height):
    """화면의 특정 영역을 캡처하여 OpenCV 이미지 객체로 반환합니다."""
    screenshot = pyautogui.screenshot(region=(left, top, width, height))
    return cv2.cvtColor(np.array(screenshot), cv2.COLOR_RGB2BGR)

def preprocess_image_for_ocr(image):
    """OCR 인식을 위해 이미지를 전처리합니다."""
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    kernel = np.ones((1, 1), np.uint8)
    processed_image = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel, iterations=1)
    return processed_image

def recognize_text_from_image(image, lang='kor+eng'):
    """OpenCV 이미지 객체에서 Tesseract를 사용하여 텍스트를 인식합니다."""
    if len(image.shape) == 2:
        pil_image = Image.fromarray(image)
    else:
        pil_image = Image.fromarray(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
    text = pytesseract.image_to_string(pil_image, lang=lang)
    return text.strip()

def automate_based_on_text(target_text, region_coords, action_func):
    """
    지정된 화면 영역에서 특정 텍스트를 찾아 자동화 동작을 수행합니다.
    :param target_text: 찾을 텍스트 문자열.
    :param region_coords: (left, top, width, height) 형태의 캡처 영역 좌표.
    :param action_func: 텍스트 발견 시 실행할 함수 (예: pyautogui.click, pyautogui.write).
    """
    left, top, width, height = region_coords
    print(f"화면 영역 ({left},{top},{width},{height})에서 '{target_text}' 텍스트를 찾습니다...")

    # 화면 캡처 및 전처리
    captured_img = capture_screen_region(left, top, width, height)
    preprocessed_img = preprocess_image_for_ocr(captured_img)

    # 텍스트 인식
    recognized_text = recognize_text_from_image(preprocessed_img, lang='kor+eng')
    print(f"인식된 텍스트:\n{recognized_text}\n")

    # 텍스트 확인 및 동작 수행
    if target_text in recognized_text:
        print(f"'{target_text}' 텍스트를 화면에서 발견했습니다. 지정된 동작을 수행합니다.")
        action_func()
        return True
    else:
        print(f"'{target_text}' 텍스트를 화면에서 찾지 못했습니다.")
        return False

# ----- 자동화 동작 함수 정의 예시 -----
def perform_click_action():
    """예시: 마우스 클릭 동작 (현재 마우스 위치에서 클릭)"""
    print("마우스 클릭 동작을 실행합니다.")
    pyautogui.click() # 현재 마우스 위치에서 클릭
    # 특정 좌표를 클릭하려면 pyautogui.click(x=100, y=200)

def perform_type_action(text_to_type):
    """예시: 키보드 입력 동작"""
    print(f"'{text_to_type}'를 입력합니다.")
    pyautogui.write(text_to_type)

# ----- 메인 자동화 로직 예시 -----
if __name__ == "__main__":
    # 예시: 특정 창에서 '확인' 버튼을 찾아서 클릭하는 상황 가정
    # 이 좌표는 사용자 환경에 따라 달라지므로, pyautogui.displayMousePosition()으로 확인 후 수정하세요.
    target_region = (500, 300, 300, 100) # 예시: X:500, Y:300에서 300x100 픽셀 영역
    
    # 1. '확인' 텍스트를 찾아 클릭하는 매크로
    print("--- '확인' 텍스트 찾기 및 클릭 시도 ---")
    found_and_acted = automate_based_on_text(
        target_text='확인', 
        region_coords=target_region, 
        action_func=perform_click_action
    )
    if found_and_acted:
        print("성공적으로 '확인' 버튼을 클릭했습니다.")
    else:
        print("'확인' 버튼을 찾지 못해 클릭하지 않았습니다.")

    time.sleep(2) # 2초 대기

    # 2. '로그인' 텍스트를 찾아 특정 텍스트를 입력하는 매크로 (가상 시나리오)
    # 이 예시에서는 '로그인' 텍스트를 찾으면 'my_username'을 입력합니다.
    # 실제로는 입력 필드가 활성화된 상태여야 합니다.
    print("\n--- '로그인' 텍스트 찾기 및 텍스트 입력 시도 ---")
    found_and_acted_login = automate_based_on_text(
        target_text='로그인',
        region_coords=target_region, # 동일 영역 사용 (예시)
        action_func=lambda: perform_type_action('my_username') # 람다 함수로 인자 전달
    )
    if found_and_acted_login:
        print("성공적으로 'my_username'을 입력했습니다.")
    else:
        print("'로그인' 텍스트를 찾지 못해 입력하지 않았습니다.")

주의: pyautogui는 실제 마우스와 키보드를 제어하므로, 스크립트 실행 중에는 컴퓨터를 사용하지 않는 것이 좋습니다. 문제가 발생하면 마우스를 화면의 좌상단 (0,0)으로 빠르게 이동하여 pyautogui.FAILSAFE 기능을 활성화하여 스크립트를 강제 종료할 수 있습니다.

5단계: 전체 자동화 매크로 통합 및 실행

이제 앞서 구현한 모든 기능을 통합하여 하나의 완전한 자동화 매크로 스크립트를 완성합니다. 이 스크립트는 지정된 횟수만큼 반복적으로 화면을 확인하고, 특정 텍스트를 발견하면 정의된 동작을 수행합니다.

import pyautogui
import cv2
import numpy as np
import pytesseract
from PIL import Image
import time
import sys # 강제 종료를 위한 라이브러리

# --- 1. Tesseract 경로 설정 (Windows 사용자만 해당, 필요시 주석 해제 및 경로 수정) ---
try:
    pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe' # 실제 Tesseract 경로로 변경
    pytesseract.get_tesseract_version() # 경로 유효성 검사
except pytesseract.TesseractNotFoundError:
    print("오류: Tesseract 실행 파일을 찾을 수 없습니다. 경로를 확인하거나 설치하십시오.", file=sys.stderr)
    sys.exit(1) # 스크립트 종료

# --- 2. 헬퍼 함수 정의 ---
def capture_screen_region(left, top, width, height):
    """화면의 특정 영역을 캡처하여 OpenCV 이미지 객체로 반환합니다."""
    screenshot = pyautogui.screenshot(region=(left, top, width, height))
    return cv2.cvtColor(np.array(screenshot), cv2.COLOR_RGB2BGR)

def preprocess_image_for_ocr(image):
    """OCR 인식을 위해 이미지를 전처리합니다."""
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    kernel = np.ones((1, 1), np.uint8)
    processed_image = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel, iterations=1)
    return processed_image

def recognize_text_from_image(image, lang='kor+eng'):
    """OpenCV 이미지 객체에서 Tesseract를 사용하여 텍스트를 인식합니다."""
    if len(image.shape) == 2:
        pil_image = Image.fromarray(image)
    else:
        pil_image = Image.fromarray(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
    text = pytesseract.image_to_string(pil_image, lang=lang)
    return text.strip()

# --- 3. 자동화 매크로 핵심 로직 ---
def run_automation_macro(target_text, search_region, action_func, interval_seconds=5, max_attempts=10):
    """
    지정된 화면 영역에서 특정 텍스트를 주기적으로 찾아 자동화 동작을 수행하는 매크로.
    :param target_text: 찾을 텍스트 문자열.
    :param search_region: (left, top, width, height) 형태의 캡처 영역 좌표.
    :param action_func: 텍스트 발견 시 실행할 함수 (예: pyautogui.click, pyautogui.write).
    :param interval_seconds: 화면 확인 간격 (초).
    :param max_attempts: 최대 시도 횟수.
    """
    print(f"매크로 시작: '{target_text}' 텍스트를 찾고 있습니다. (최대 {max_attempts}회 시도, {interval_seconds}초 간격)")
    attempts = 0
    while attempts < max_attempts:
        attempts += 1
        print(f"\n--- 시도 {attempts}/{max_attempts} ---")
        
        try:
            captured_img = capture_screen_region(*search_region)
            preprocessed_img = preprocess_image_for_ocr(captured_img)
            recognized_text = recognize_text_from_image(preprocessed_img, lang='kor+eng')
            
            print(f"인식된 텍스트:\n{recognized_text}\n")
            
            if target_text in recognized_text:
                print(f"'{target_text}' 텍스트를 화면에서 발견했습니다. 지정된 동작을 수행합니다.")
                action_func()
                print("매크로 종료: 동작 완료.")
                return True # 동작 완료 후 매크로 종료
            else:
                print(f"'{target_text}' 텍스트를 화면에서 찾지 못했습니다. {interval_seconds}초 후 다시 시도합니다.")
        except Exception as e:
            print(f"매크로 실행 중 오류 발생: {e}", file=sys.stderr)
            print(f"{interval_seconds}초 후 다시 시도합니다.")
            
        time.sleep(interval_seconds)
    
    print(f"매크로 종료: '{target_text}' 텍스트를 {max_attempts}회 시도했으나 찾지 못했습니다.")
    return False

# --- 4. 자동화 동작 함수 정의 예시 ---
def click_at_center_of_region(region):
    """지정된 영역의 중앙을 클릭합니다."""
    left, top, width, height = region
    center_x = left + width // 2
    center_y = top + height // 2
    print(f"좌표 ({center_x}, {center_y}) 클릭.")
    pyautogui.click(x=center_x, y=center_y)

def type_text_then_enter(text_to_type):
    """텍스트를 입력하고 엔터를 누릅니다."""
    print(f"'{text_to_type}' 입력 후 Enter.")
    pyautogui.write(text_to_type)
    pyautogui.press('enter')

# --- 5. 메인 실행 블록 ---
if __name__ == "__main__":
    # pyautogui의 Fail-safe 기능 활성화 (마우스를 화면 좌상단으로 옮기면 스크립트 중단)
    pyautogui.FAILSAFE = True
    
    # --- 사용자 정의 매크로 설정 ---
    # 1. 찾을 텍스트
    target_text_to_find = '로그인' # 예시: 웹 페이지의 '로그인' 버튼 또는 텍스트
    
    # 2. 텍스트를 찾을 화면 영역 (left, top, width, height)
    # 실제 환경에 맞게 pyautogui.displayMousePosition()으로 확인 후 수정하세요.
    # 예시: (X: 700, Y: 400에서 너비 200, 높이 50 픽셀 영역)
    search_area = (700, 400, 200, 50) 
    
    # 3. 텍스트 발견 시 수행할 동작 함수
    # 예시 1: 발견된 영역의 중앙을 클릭 (로그인 버튼 클릭)
    action_to_perform = lambda: click_at_center_of_region(search_area)
    # 예시 2: 특정 텍스트를 입력하고 엔터 (로그인 필드에 아이디 입력)
    # action_to_perform = lambda: type_text_then_enter('my_user_id') 
    
    # 4. 매크로 실행 간격 및 최대 시도 횟수
    check_interval = 3 # 3초마다 화면 확인
    max_check_attempts = 20 # 최대 20회 시도 (총 60초 동안 확인)

    # 매크로 실행
    print("--- 파이썬 화면 이미지 인식 자동화 매크로 시작 ---")
    macro_succeeded = run_automation_macro(
        target_text=target_text_to_find,
        search_region=search_area,
        action_func=action_to_perform,
        interval_seconds=check_interval,
        max_attempts=max_check_attempts
    )

    if macro_succeeded:
        print("매크로가 성공적으로 완료되었습니다.")
    else:
        print("매크로가 지정된 조건 내에서 작업을 완료하지 못했습니다.")
    print("--- 파이썬 화면 이미지 인식 자동화 매크로 종료 ---")

결과 확인

작성된 매크로 스크립트를 실행하기 전에, 테스트할 환경을 준비합니다. 예를 들어, ‘로그인’ 버튼이 있는 웹 페이지나 애플리케이션 화면을 열어둡니다. 스크립트를 실행한 후에는 다음과 같은 사항을 확인합니다.

스크립트가 지정된 영역을 올바르게 캡처하는지 (디버깅 목적으로 캡처 이미지를 저장하여 확인).
Tesseract가 이미지에서 텍스트를 정확하게 인식하는지 (인식된 텍스트 출력을 통해 확인).
타겟 텍스트가 인식되었을 때, pyautogui를 통해 정의된 마우스 클릭 또는 키보드 입력 동작이 올바르게 수행되는지.
매크로가 성공적으로 완료되거나, 지정된 시도 횟수를 초과하여 종료되는지.

매크로가 예상대로 작동하지 않는다면, 다음 섹션의 문제 해결 가이드를 참조하거나, 캡처 영역 좌표, 텍스트 인식 언어, 이미지 전처리 방식 등을 조정해 보십시오.

Troubleshooting (문제 해결)

다음은 본 튜토리얼을 따라 하면서 흔히 겪을 수 있는 문제점과 그 해결책을 정리한 표입니다.

문제점	가능한 원인	해결책
`pytesseract.TesseractNotFoundError: tesseract is not installed or it's not in your PATH`	Tesseract-OCR 엔진이 설치되지 않았거나, 시스템 PATH에 추가되지 않음. Windows의 경우 파이썬 코드 내 경로 설정 누락.	Tesseract-OCR 엔진을 설치하십시오 (1.3단계 참조). Windows 사용자는 설치 시 ‘Add to PATH’를 선택하거나, 파이썬 코드 내 `pytesseract.pytesseract.tesseract_cmd`에 Tesseract 실행 파일의 정확한 경로를 지정하십시오 (1.4단계 참조). macOS/Linux 사용자는 `brew install tesseract` 또는 `sudo apt install tesseract-ocr`로 설치 후 PATH가 올바르게 설정되었는지 확인하십시오.
`ModuleNotFoundError: No module named 'opencv-python'` 또는 유사한 라이브러리 오류	필요한 파이썬 라이브러리가 설치되지 않았습니다.	`pip install opencv-python pytesseract Pillow numpy pyautogui` 명령어를 사용하여 모든 필수 라이브러리를 설치했는지 확인하십시오 (1.2단계 참조). 가상 환경을 사용 중이라면 해당 가상 환경에 라이브러리가 설치되었는지 확인하십시오.
Tesseract 텍스트 인식률이 매우 낮거나 잘못된 텍스트를 인식함	이미지 전처리가 불충분하거나 부적절함. Tesseract 언어 팩이 설치되지 않았거나 잘못 지정됨. 이미지 해상도가 낮거나 텍스트가 너무 작음. 화면 캡처 영역이 텍스트를 정확히 포함하지 않음.	2.2단계의 이미지 전처리 코드를 검토하고, 필요에 따라 `kernel` 크기나 이진화 임계값을 조정하십시오. 3.1단계에서 `lang='kor+eng'`와 같이 올바른 언어 팩이 지정되었는지 확인하고, 해당 언어 팩이 Tesseract 설치 폴더의 `tessdata` 안에 존재하는지 확인하십시오. 더 높은 해상도로 화면을 캡처하거나, 텍스트가 잘 보이도록 화면을 확대하십시오. `pyautogui.displayMousePosition()`을 사용하여 캡처 영역 좌표를 다시 정확하게 설정하십시오.
`pyautogui` 동작(클릭, 입력)이 예상과 다르게 작동하거나 오류 발생	잘못된 좌표 또는 텍스트 입력 시점이 부적절함. 스크립트 실행 중 사용자가 마우스/키보드 조작. `pyautogui.FAILSAFE` 기능이 의도치 않게 발동됨.	`pyautogui.displayMousePosition()`으로 정확한 클릭 좌표를 확인하고, `click_at_center_of_region` 함수를 수정하여 특정 좌표를 클릭하도록 변경하십시오. 스크립트 실행 중에는 마우스와 키보드 조작을 삼가십시오. `pyautogui.FAILSAFE = False`로 설정하여 강제 종료 기능을 비활성화할 수 있지만, 주의해서 사용하십시오. (0,0) 위치로 마우스를 이동하면 스크립트가 강제 종료되는 기본 기능은 유지하는 것이 안전합니다. `time.sleep()`을 적절히 사용하여 시스템이 다음 동작을 처리할 시간을 주십시오.
스크립트 실행 중 갑자기 멈추거나 종료됨	`pyautogui.FAILSAFE` 기능이 발동됨. 파이썬 코드 내 예외 처리 부족. 메모리 부족 또는 시스템 리소스 한계.	마우스 커서가 화면의 좌상단(0,0)으로 이동하지 않았는지 확인하십시오. 이 기능은 `pyautogui`의 기본 안전 장치입니다. `try-except` 블록을 사용하여 코드의 잠재적 오류를 처리하고, 오류 메시지를 출력하도록 하십시오. 대규모 이미지를 처리하거나 매우 빠른 반복을 수행할 경우, 시스템 리소스를 확인하십시오.

결론

본 튜토리얼을 통해 파이썬, OpenCV, 그리고 Tesseract-OCR을 활용하여 화면 이미지 인식 기반의 자동화 매크로를 성공적으로 구현했습니다. 학습 목표에서 제시된 바와 같이, 개발 환경 설정부터 화면 캡처, 이미지 전처리, 텍스트 인식, 그리고 최종적인 자동화 로직 구현까지 모든 단계를 실습했습니다. 이 기술은 반복적인 데이터 입력, 특정 알림 감지 및 반응, 게임 자동화 등 다양한 실무 시나리오에 적용될 수 있습니다.

이제 여러분은 단순한 키보드/마우스 매크로를 넘어, ‘보는’ 능력을 갖춘 지능형 자동화 도구를 만들 수 있는 기반을 마련했습니다. 더 나아가 이미지 매칭, 객체 탐지 등 OpenCV의 고급 기능을 학습하고, Tesseract의 다양한 설정 옵션을 탐구한다면 더욱 정교하고 강력한 자동화 시스템을 구축할 수 있을 것입니다. 꾸준한 실습과 탐구를 통해 여러분의 자동화 기술 역량을 지속적으로 발전시키기를 바랍니다.