#特征匹配实战：SIFT/ORB算法、图像拼接、关键点检测完整指南

import cv2
import numpy as np

def feature_pipeline_demo(img1, img2):
    """简化但核心的特征匹配流程"""
    # 1. 转灰度（减少计算量，特征对亮度更敏感）
    gray1, gray2 = cv2.cvtColor(img1, cv2.COLOR_BGR2GRAY), cv2.cvtColor(img2, cv2.COLOR_BGR2GRAY)
    
    # 2. 特征检测+描述
    detector = cv2.SIFT_create()  # 或cv2.ORB_create()
    kp1, desc1 = detector.detectAndCompute(gray1, None)
    kp2, desc2 = detector.detectAndCompute(gray2, None)
    
    # 3. 匹配+过滤
    matcher = cv2.BFMatcher()
    matches = matcher.knnMatch(desc1, desc2, k=2)
    good = [m for m,n in matches if m.distance < 0.75*n.distance]  # Lowe's Ratio Test
    
    # 4. （可选）RANSAC几何验证
    # 5. 应用
    return kp1, kp2, good

def sift_kp_demo(img_path):
    """SIFT关键点检测可视化"""
    img = cv2.imread(img_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    # 参数调整提示：nfeatures=500-2000控制数量，contrastThreshold=0.03-0.06控制抗噪
    sift = cv2.SIFT_create(nfeatures=1000)
    kp, _ = sift.detectAndCompute(gray, None)
    
    # 绘制方向+大小的关键点
    return cv2.drawKeypoints(img, kp, None, flags=cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS)

def orb_matching_demo(img1_path, img2_path):
    """ORB特征匹配可视化"""
    img1, img2 = cv2.imread(img1_path), cv2.imread(img2_path)
    gray1, gray2 = cv2.cvtColor(img1, cv2.COLOR_BGR2GRAY), cv2.cvtColor(img2, cv2.COLOR_BGR2GRAY)
    
    orb = cv2.ORB_create(nfeatures=1000)
    kp1, desc1 = orb.detectAndCompute(gray1, None)
    kp2, desc2 = orb.detectAndCompute(gray2, None)
    
    # ORB是二进制描述符，必须用汉明距离！
    bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)  # crossCheck强制一对一匹配
    matches = sorted(bf.match(desc1, desc2), key=lambda x: x.distance)[:50]  # 取前50好的
    
    return cv2.drawMatches(img1, kp1, img2, kp2, matches, None, flags=cv2.DrawMatchesFlags_NOT_DRAW_SINGLE_POINTS)

def ransac_homography(kp1, kp2, good_matches):
    """用RANSAC计算单应矩阵（图像拼接的核心变换）"""
    if len(good_matches) < 4:
        return None, None
    
    # 提取匹配点坐标
    src = np.float32([kp1[m.queryIdx].pt for m in good_matches]).reshape(-1,1,2)
    dst = np.float32([kp2[m.trainIdx].pt for m in good_matches]).reshape(-1,1,2)
    
    # 计算单应矩阵：ransacReprojThreshold=5.0（重投影误差≤5像素算内点）
    H, mask = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
    return H, mask

def simple_stitch(img1, img2):
    """简易的两张图像拼接"""
    gray1, gray2 = cv2.cvtColor(img1, cv2.COLOR_BGR2GRAY), cv2.cvtColor(img2, cv2.COLOR_BGR2GRAY)
    
    # 1. SIFT检测（精度高）
    sift = cv2.SIFT_create(nfeatures=1500)
    kp1, desc1 = sift.detectAndCompute(gray1, None)
    kp2, desc2 = sift.detectAndCompute(gray2, None)
    
    # 2. FLANN匹配（比暴力匹配快，适合SIFT高维特征）
    FLANN_INDEX_KDTREE = 1
    index_params = dict(algorithm=FLANN_INDEX_KDTREE, trees=5)
    search_params = dict(checks=50)  # 搜索每个点的邻居数
    flann = cv2.FlannBasedMatcher(index_params, search_params)
    matches = flann.knnMatch(desc1, desc2, k=2)
    good = [m for m,n in matches if m.distance < 0.7*n.distance]  # ORB可放宽到0.8
    
    # 3. RANSAC计算单应矩阵
    H, _ = ransac_homography(kp1, kp2, good)
    if H is None:
        return None
    
    # 4. 拼接（计算画布尺寸→变换第二张图→粘贴第一张图）
    h1, w1 = img1.shape[:2]
    h2, w2 = img2.shape[:2]
    # 求第二张图变换后的四个角点
    corners2 = cv2.perspectiveTransform(np.float32([[0,0],[0,h2],[w2,h2],[w2,0]]).reshape(-1,1,2), H)
    # 求两张图的整体边界
    all_corners = np.concatenate((np.float32([[0,0],[0,h1],[w1,h1],[w1,0]]).reshape(-1,1,2), corners2), axis=0)
    x_min, y_min = np.int32(all_corners.min(axis=0).ravel())
    x_max, y_max = np.int32(all_corners.max(axis=0).ravel())
    # 平移矩阵（避免负坐标）
    trans = np.array([[1,0,-x_min],[0,1,-y_min],[0,0,1]])
    # 变换第二张图
    warped = cv2.warpPerspective(img2, trans@H, (x_max-x_min, y_max-y_min))
    # 粘贴第一张图
    warped[-y_min:h1-y_min, -x_min:w1-x_min] = img1
    return warped

def feature_object_detect(template, scene):
    """在场景图中定位模板图"""
    gray_t, gray_s = cv2.cvtColor(template, cv2.COLOR_BGR2GRAY), cv2.cvtColor(scene, cv2.COLOR_BGR2GRAY)
    
    # 1. ORB检测（适合快速定位）
    orb = cv2.ORB_create(nfeatures=2000)
    kp_t, desc_t = orb.detectAndCompute(gray_t, None)
    kp_s, desc_s = orb.detectAndCompute(gray_s, None)
    
    # 2. 暴力汉明匹配
    bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)
    matches = bf.knnMatch(desc_t, desc_s, k=2)
    good = [m for m,n in matches if m.distance < 0.8*n.distance]
    
    # 3. RANSAC+透视变换画框
    if len(good) >= 15:
        src = np.float32([kp_t[m.queryIdx].pt for m in good]).reshape(-1,1,2)
        dst = np.float32([kp_s[m.trainIdx].pt for m in good]).reshape(-1,1,2)
        H, _ = cv2.findHomography(src, dst, cv2.RANSAC, 5.0)
        if H is not None:
            h, w = template.shape[:2]
            corners = cv2.perspectiveTransform(np.float32([[0,0],[0,h],[w,h],[w,0]]).reshape(-1,1,2), H)
            return cv2.polylines(scene.copy(), [np.int32(corners)], True, (0,255,0), 3, cv2.LINE_AA)
    return scene