OpenCV XY Vision Automation
智慧化視覺辨識與自動化操作系統

錯誤的寫法：直覺的固定像素 RGB 比對（光影或按鈕微小變色即失效）

# ❌ 舊型自動化腳本片段：RGB 色值硬比對
import cv2
import numpy as np

def find_button_naive(screenshot_path):
    img = cv2.imread(screenshot_path)
    # 嘗試尋找畫面中接近特定藍色 (R:0, G:120, B:255) 的區域
    # 在工廠日光燈反光或變色主題下，色值稍微偏差 5 個單位就完全失效
    lower_blue = np.array([115, 50, 50])
    upper_blue = np.array([125, 255, 255])
    
    hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
    mask = cv2.inRange(hsv, lower_blue, upper_blue)
    
    # 尋找輪廓並點擊幾何中心
    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
    if contours:
        largest = max(contours, key=cv2.contourArea)
        M = cv2.moments(largest)
        if M["m00"] != 0:
            cX = int(M["m10"] / M["m00"])
            cY = int(M["m01"] / M["m00"])
            return cX, cY # 返回像素坐標，沒有與手臂座標校準映射
    return None

改良後寫法：OpenCV 模板匹配與透視變換座標計算

# 🚀 現代化視覺定位與實體映射模組
import cv2
import numpy as np

class VisionLocator:
    def __init__(self, perspective_matrix_path=None):
        # 載入預先校正好的 3x3 透視變換矩陣
        if perspective_matrix_path and os.path.exists(perspective_matrix_path):
            self.M = np.load(perspective_matrix_path)
        else:
            # 預設單位矩陣 (不做轉換)
            self.M = np.eye(3, dtype=np.float32)

    def set_calibration(self, src_pts: np.ndarray, dst_pts: np.ndarray):
        """傳入三個/四個基準像素坐標(src)與對應手臂坐標(dst)，動態計算轉換矩陣"""
        self.M, _ = cv2.findHomography(src_pts, dst_pts)

    def locate_and_convert(self, scene_img_path, template_img_path, threshold=0.85):
        # 1. 讀取並轉為灰階
        scene = cv2.imread(scene_img_path)
        template = cv2.imread(template_img_path)
        
        scene_gray = cv2.cvtColor(scene, cv2.COLOR_BGR2GRAY)
        template_gray = cv2.cvtColor(template, cv2.COLOR_BGR2GRAY)
        
        # 2. 進行限制對比度直方圖等化 (CLAHE) 以消除反光
        clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
        scene_gray = clahe.apply(scene_gray)
        template_gray = clahe.apply(template_gray)

        # 3. 模板匹配
        w, h = template_gray.shape[::-1]
        res = cv2.matchTemplate(scene_gray, template_gray, cv2.TM_CCOEFF_NORMED)
        min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(res)

        # 判斷匹配度是否合規
        if max_val < threshold:
            print(f"⚠️ 辨識置信度不足: {max_val:.2f} < {threshold}")
            return None

        # 取得匹配中心點像素坐標 (u, v)
        pixel_x = max_loc[0] + w // 2
        pixel_y = max_loc[1] + h // 2
        
        # 4. 關鍵步驟：利用 Homography Matrix 將像素坐標轉換為物理空間坐標
        pixel_vector = np.array([pixel_x, pixel_y, 1.0], dtype=np.float32)
        physical_vector = np.dot(self.M, pixel_vector)
        
        # 歸一化齊次坐標
        physical_x = physical_vector[0] / physical_vector[2]
        physical_y = physical_vector[1] / physical_vector[2]
        
        return (pixel_x, pixel_y), (float(physical_x), float(physical_y))

if __name__ == "__main__":
    locator = VisionLocator()
    
    # 模擬動態校正過程：定義手機畫面上的三個角點像素坐標，以及對應實體點擊器的 XY 坐標 (mm)
    pixel_points = np.array([[100, 100], [900, 100], [500, 1800]], dtype=np.float32)
    physical_points = np.array([[10.0, 15.0], [90.0, 15.0], [50.0, 190.0]], dtype=np.float32)
    locator.set_calibration(pixel_points, physical_points)
    
    # 執行定位與映射
    # result = locator.locate_and_convert("scene.jpg", "confirm_btn.jpg")
    # if result:
    #     pixel_pos, robot_pos = result
    #     print(f"🎯 成功識別按鈕像素: {pixel_pos} -> 機械手實體座標: {robot_pos} mm")