#OpenCV实战指南：从图像处理到深度学习的完整教程

import cv2

# 打印 OpenCV 版本
print(f"当前版本: {cv2.__version__}")

# 检查是否支持DNN模块
print(f"DNN模块可用: {'dnn' in dir(cv2)}")
print(f"贡献模块可用: {'xfeatures2d' in dir(cv2)}")

import cv2
import sys

def basic_image_operations(image_path):
    """
    基本图像操作示例
    """
    # 载入图像 (默认读取为 BGR 彩色模式)
    img = cv2.imread(image_path)
    
    # 健壮性检查：确保文件路径正确且文件未损坏
    if img is None:
        sys.exit("错误：无法读取图像，请检查文件路径是否正确。")
    
    print(f"图像形状: {img.shape}")
    print(f"图像数据类型: {img.dtype}")
    
    # 显示图像
    # 第一个参数是窗口标题，第二个参数是图像对象
    cv2.imshow('Image Display', img)
    
    # 等待键盘输入：0 表示无限期等待，直到按下任意键
    cv2.waitKey(0)
    
    # 释放内存：关闭所有由 OpenCV 创建的窗口
    cv2.destroyAllWindows()
    
    # 保存图像
    # 可以通过文件后缀名自动识别格式（如 .jpg, .png, .webp）
    output_path = 'output_processed.jpg'
    cv2.imwrite(output_path, img)
    print(f"图像已保存到: {output_path}")
    
    return img

# 使用示例
# img = basic_image_operations('image.jpg')

def image_properties_and_pixels(img):
    """
    图像属性获取和像素操作
    """
    # 获取属性
    h, w, c = img.shape  # 高度、宽度、通道数
    print(f"维度: {img.shape} | 总像素: {img.size} | 数据类型: {img.dtype}")
    
    # 访问特定像素 (注意顺序是：y, x / 行, 列)
    px = img[100, 100]
    print(f"坐标(100,100)处的BGR值: {px}")
    
    # 修改像素值 (例如将该点设为蓝色)
    img[100, 100] = [255, 0, 0] 
    
    return img

def region_of_interest(img):
    """
    感兴趣区域(ROI)操作
    """
    # 提取坐标为 (y:100~200, x:100~200) 的矩形区域
    roi = img[100:200, 100:200]
    
    # 你甚至可以将 ROI 贴回到原图的其他位置
    # img[300:400, 300:400] = roi
    
    return roi

def channel_operations(img):
    """
    通道拆分与合并
    """
    # 拆分通道 (OpenCV 默认顺序是 Blue, Green, Red)
    b, g, r = cv2.split(img)
    
    # 合并通道
    img_merged = cv2.merge((b, g, r))
    
    # 进阶：如果只想将红色通道全部清零
    img_copy = img.copy()
    img_copy[:, :, 2] = 0  # 清零红色通道
    
    return b, g, r, img_merged, img_copy

def color_space_conversions(img):
    """
    色彩空间转换示例
    """
    # 1. 转换为灰度图：大幅降低计算量，常用于边缘检测和人脸识别
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    # 2. 转换为 HSV 空间：符合人类视觉，非常适合根据颜色提取特定物体
    # H (色调), S (饱和度), V (亮度)
    hsv = cv2.cvtColor(img, cv2.COLOR_BGR2HSV)
    
    # 3. 转换为 RGB：如果你需要使用 Matplotlib 进行绘图展示，必须进行此转换
    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    
    # 4. 其他常用转换
    lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)  # LAB色彩空间
    yuv = cv2.cvtColor(img, cv2.COLOR_BGR2YUV)  # YUV色彩空间
    
    print(f"原图形状: {img.shape}")
    print(f"灰度图形状: {gray.shape}")
    print(f"HSV形状: {hsv.shape}")
    
    return gray, hsv, img_rgb, lab, yuv

# 专业贴士：
# 为什么习惯用 HSV 而非 BGR 进行颜色识别？
# 因为在 BGR 空间中，光照的变化会同时改变 B、G、R 三个分量；
# 而在 HSV 中，光照变化主要反映在 V (Value) 分量上，色调 H (Hue) 相对稳定，
# 这使得颜色过滤更加鲁棒。

import cv2
import numpy as np

def thresholding_operations(img):
    """
    图像阈值化操作
    """
    # 以灰度模式加载图像
    if len(img.shape) == 3:
        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    else:
        gray = img
    
    # 基础阈值化：将大于 127 的像素设为 255 (白色)，其余设为 0 (黑色)
    ret, thresh1 = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY)
    
    # 反向阈值化
    ret, thresh2 = cv2.threshold(gray, 127, 255, cv2.THRESH_BINARY_INV)
    
    # 截断阈值化
    ret, thresh3 = cv2.threshold(gray, 127, 255, cv2.THRESH_TRUNC)
    
    # 进阶建议：自适应阈值 (Adaptive Thresholding)
    # 能够处理光照不均匀的场景
    adaptive_mean = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_MEAN_C, 
                                        cv2.THRESH_BINARY, 11, 2)
    adaptive_gaussian = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, 
                                            cv2.THRESH_BINARY, 11, 2)
    
    # Otsu's二值化 - 自动选择最佳阈值
    ret, thresh_otsu = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    
    print(f"Otsu's最佳阈值: {ret}")
    
    return {
        'original': gray,
        'binary': thresh1,
        'binary_inv': thresh2,
        'trunc': thresh3,
        'adaptive_mean': adaptive_mean,
        'adaptive_gaussian': adaptive_gaussian,
        'otsu': thresh_otsu
    }

def edge_detection(img):
    """
    边缘检测算法
    """
    if len(img.shape) == 3:
        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    else:
        gray = img
    
    # 1. Canny 边缘检测
    # 100 和 200 分别是低阈值和高阈值，建议根据图像噪声调整
    edges = cv2.Canny(gray, 100, 200)
    
    # 技巧：在边缘检测前进行高斯模糊，可以显著减少噪声生成的假边缘
    img_blur = cv2.GaussianBlur(gray, (5, 5), 0)
    edges_blur = cv2.Canny(img_blur, 50, 150)
    
    # 2. Sobel 边缘检测
    sobelx = cv2.Sobel(gray, cv2.CV_64F, 1, 0, ksize=3)
    sobely = cv2.Sobel(gray, cv2.CV_64F, 0, 1, ksize=3)
    sobel_combined = np.sqrt(sobelx**2 + sobely**2)
    
    # 3. Laplacian 边缘检测
    laplacian = cv2.Laplacian(gray, cv2.CV_64F)
    
    return {
        'canny': edges,
        'canny_blur': edges_blur,
        'sobel_x': np.uint8(np.absolute(sobelx)),
        'sobel_y': np.uint8(np.absolute(sobely)),
        'sobel_combined': np.uint8(sobel_combined),
        'laplacian': np.uint8(np.absolute(laplacian))
    }

def image_filtering(img):
    """
    图像滤波操作
    """
    if len(img.shape) == 3:
        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    else:
        gray = img
    
    # 1. 均值滤波：取邻域平均值，简单但容易使图像模糊
    blur = cv2.blur(gray, (5, 5))
    
    # 2. 使用高斯滤波进行平滑处理 (5x5 是核大小，0 表示自动计算标准差)
    gaussian_blur = cv2.GaussianBlur(gray, (5, 5), 0)
    
    # 3. 使用中值滤波去除噪点（对椒盐噪声特别有效）
    median_blur = cv2.medianBlur(gray, 5)
    
    # 4. 双边滤波：既能降噪又能保持边缘
    bilateral_filter = cv2.bilateralFilter(gray, 9, 75, 75)
    
    return {
        'original': gray,
        'mean_blur': blur,
        'gaussian_blur': gaussian_blur,
        'median_blur': median_blur,
        'bilateral_filter': bilateral_filter
    }

def morphological_operations(binary_img):
    """
    形态学操作
    """
    # 定义结构元素 (5x5 矩阵)
    kernel = np.ones((5, 5), np.uint8)
    
    # 1. 腐蚀 (Erosion)：收缩物体边界，消除细小的白色噪点
    erosion = cv2.erode(binary_img, kernel, iterations=1)
    
    # 2. 膨胀 (Dilation)：扩张物体边界，连接被断开的物体部分
    dilation = cv2.dilate(binary_img, kernel, iterations=1)
    
    # 3. 开运算 (Opening)：先腐蚀后膨胀，用于移除外部噪点
    opening = cv2.morphologyEx(binary_img, cv2.MORPH_OPEN, kernel)
    
    # 4. 闭运算 (Closing)：先膨胀后腐蚀，用于填充物体内部的小孔
    closing = cv2.morphologyEx(binary_img, cv2.MORPH_CLOSE, kernel)
    
    # 5. 形态学梯度
    gradient = cv2.morphologyEx(binary_img, cv2.MORPH_GRADIENT, kernel)
    
    # 6. 礼帽操作
    tophat = cv2.morphologyEx(binary_img, cv2.MORPH_TOPHAT, kernel)
    
    # 7. 黑帽操作
    blackhat = cv2.morphologyEx(binary_img, cv2.MORPH_BLACKHAT, kernel)
    
    return {
        'original': binary_img,
        'erosion': erosion,
        'dilation': dilation,
        'opening': opening,
        'closing': closing,
        'gradient': gradient,
        'tophat': tophat,
        'blackhat': blackhat
    }

def static_face_detection(image_path):
    """
    静态图像人脸检测
    """
    # 使用 cv2.data.haarcascades 确保在不同环境下都能正确找到模型路径
    face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_frontalface_default.xml')
    
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    # 参数调优：
    # scaleFactor: 图像缩放比例，1.1意味着每次缩小10%去匹配特征
    # minNeighbors: 确定人脸前的候选矩形数量，值越大检测越严苛
    faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))
    
    for (x, y, w, h) in faces:
        cv2.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 2)
    
    print(f"检测到 {len(faces)} 张人脸")
    return img, faces

def real_time_face_detection():
    """
    实时视频流人脸检测
    """
    # 使用 cv2.data.haarcascades 确保在不同环境下都能正确找到模型路径
    face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_frontalface_default.xml')
    
    cap = cv2.VideoCapture(0) # 0 通常是内置摄像头
    
    print("按 'q' 键退出")
    
    while cap.isOpened():
        ret, frame = cap.read()
        if not ret: 
            break
        
        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
        faces = face_cascade.detectMultiScale(gray, 1.1, 5)
        
        for (x, y, w, h) in faces:
            cv2.rectangle(frame, (x, y), (x+w, y+h), (255, 0, 0), 2)
        
        cv2.imshow('Real-time Face Detection', frame)
        if cv2.waitKey(1) & 0xFF == ord('q'): 
            break
    
    cap.release()
    cv2.destroyAllWindows()

# 眼部检测（可选）
def eye_detection(image_path):
    """
    眼部检测示例
    """
    face_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_frontalface_default.xml')
    eyes_cascade = cv2.CascadeClassifier(cv2.data.haarcascades + 'haarcascade_eye.xml')
    
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    faces = face_cascade.detectMultiScale(gray, 1.1, 5)
    
    for (x, y, w, h) in faces:
        roi_gray = gray[y:y+h, x:x+w]
        roi_color = img[y:y+h, x:x+w]
        
        eyes = eyes_cascade.detectMultiScale(roi_gray)
        for (ex, ey, ew, eh) in eyes:
            cv2.rectangle(roi_color, (ex, ey), (ex+ew, ey+eh), (0, 255, 0), 2)
    
    return img

def meanshift_tracking(video_path=None):
    """
    Meanshift目标跟踪算法
    """
    if video_path:
        cap = cv2.VideoCapture(video_path)
    else:
        cap = cv2.VideoCapture(0)
    
    # 获取第一帧以初始化跟踪窗口
    ret, frame = cap.read()
    if not ret:
        print("无法读取视频")
        return
    
    # 手动选择跟踪目标（使用鼠标选择ROI）
    track_window = cv2.selectROI("Select Target", frame, False)
    cv2.destroyWindow("Select Target")
    
    # 设置初始位置
    x, y, w, h = track_window
    roi = frame[y:y+h, x:x+w]
    
    # 转换到HSV空间以进行更好的颜色跟踪
    hsv_roi = cv2.cvtColor(roi, cv2.COLOR_BGR2HSV)
    
    # 创建掩码以去除低光和高光值
    mask = cv2.inRange(hsv_roi, np.array((0., 60., 32.)), np.array((180., 255., 255.)))
    
    # 计算直方图
    roi_hist = cv2.calcHist([hsv_roi], [0], mask, [180], [0, 180])
    
    # 归一化直方图
    cv2.normalize(roi_hist, roi_hist, 0, 255, cv2.NORM_MINMAX)
    
    # 设置终止条件
    term_criteria = (cv2.TERM_CRITERIA_EPS | cv2.TERM_CRITERIA_COUNT, 10, 1)
    
    while True:
        ret, frame = cap.read()
        if not ret:
            break
        
        # 转换到HSV空间
        hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)
        
        # 计算反向投影
        dst = cv2.calcBackProject([hsv], [0], roi_hist, [0, 180], 1)
        
        # 应用meanshift获取新位置
        ret, track_window = cv2.meanShift(dst, track_window, term_criteria)
        
        # 绘制跟踪结果
        x, y, w, h = track_window
        img2 = cv2.rectangle(frame, (x, y), (x+w, y+h), 255, 2)
        
        cv2.imshow('Meanshift Tracking', frame)
        
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
    
    cap.release()
    cv2.destroyAllWindows()

def image_stitching(image_paths):
    """
    图像拼接实现全景图
    """
    images = []
    for path in image_paths:
        img = cv2.imread(path)
        if img is not None:
            images.append(img)
        else:
            print(f"无法读取图像: {path}")
    
    if len(images) < 2:
        print("需要至少2张图像进行拼接")
        return None
    
    # 创建拼接器对象 (在 4.x/5.x 版本中建议使用 create 方法)
    stitcher = cv2.Stitcher.create()
    status, pano = stitcher.stitch(images)
    
    if status == cv2.Stitcher_OK:
        print("图像拼接成功!")
        cv2.imshow('Panorama Result', pano)
        cv2.waitKey(0)
        cv2.destroyAllWindows()
        return pano
    else:
        # 状态码说明：1=需要更多图像, 2=特征点匹配失败, 3=相机参数估计失败
        print(f"拼接失败，状态码: {status}")
        return None

def simple_feature_matching(img1_path, img2_path):
    """
    简单的特征点匹配示例
    """
    # 读取图像
    img1 = cv2.imread(img1_path, 0)
    img2 = cv2.imread(img2_path, 0)
    
    # 使用ORB特征检测器
    orb = cv2.ORB_create()
    
    # 寻找关键点和描述子
    kp1, des1 = orb.detectAndCompute(img1, None)
    kp2, des2 = orb.detectAndCompute(img2, None)
    
    # 创建BFMatcher对象
    bf = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=True)
    
    # 匹配描述子
    matches = bf.match(des1, des2)
    
    # 按距离排序
    matches = sorted(matches, key=lambda x: x.distance)
    
    # 绘制前10个匹配
    img3 = cv2.drawMatches(img1, kp1, img2, kp2, matches[:10], None, flags=2)
    
    return img3

def load_pretrained_models():
    """
    加载不同格式的预训练模型
    """
    # 加载 Caffe 模型 (需配置文件 .prototxt 和权重文件 .caffemodel)
    # net = cv2.dnn.readNetFromCaffe('bvlc_googlenet.prototxt', 'bvlc_googlenet.caffemodel')
    
    # 加载 TensorFlow 模型
    # net = cv2.dnn.readNetFromTensorflow('tensorflow_model.pb')
    
    # 加载 ONNX 模型（目前最通用）
    # net = cv2.dnn.readNetFromONNX('model.onnx')
    
    # 加载 Torch 模型
    # net = cv2.dnn.readNetFromTorch('torch_model.t7')
    
    print("模型加载方法说明:")
    print("Caffe: cv2.dnn.readNetFromCaffe()")
    print("TensorFlow: cv2.dnn.readNetFromTensorflow()")
    print("ONNX: cv2.dnn.readNetFromONNX()")
    print("Torch: cv2.dnn.readNetFromTorch()")

def image_classification(image_path, model_path, config_path, labels_path):
    """
    使用预训练模型进行图像分类
    """
    # 加载模型
    net = cv2.dnn.readNetFromCaffe(config_path, model_path)
    
    # 加载标签
    with open(labels_path, 'r') as f:
        labels = [line.strip().split(' ', 1)[1] for line in f.readlines()]
    
    # 读取图像
    image = cv2.imread(image_path)
    
    # 预处理：创建 4D Blob
    # (224, 224) 是 GoogLeNet 的输入尺寸，(104, 117, 123) 是均值减法参数
    blob = cv2.dnn.blobFromImage(image, 1.0, (224, 224), (104, 117, 123))
    
    # 设置输入
    net.setInput(blob)
    
    # 前向传播
    outputs = net.forward()
    
    # 解析结果
    class_id = np.argmax(outputs)
    confidence = outputs[0][class_id]
    
    print(f"预测类别: {labels[class_id]}")
    print(f"置信度: {confidence:.2f}")
    
    return labels[class_id], confidence

def yolo_object_detection(image_path, weights_path, config_path, labels_path):
    """
    使用YOLO进行物体检测
    """
    # 加载 YOLO 权重与配置
    net = cv2.dnn.readNet(weights_path, config_path)
    
    # 获取输出层名称 (兼容性修复)
    layer_names = net.getLayerNames()
    try:
        # 针对较旧版本的 OpenCV 返回索引的处理
        output_layers = [layer_names[i - 1] for i in net.getUnconnectedOutLayers()]
    except:
        # 针对新版本直接返回名称的处理
        output_layers = [layer_names[i] for i in net.getUnconnectedOutLayers()]
    
    # 读取图像
    image = cv2.imread(image_path)
    h, w = image.shape[:2]
    
    # 加载类别标签
    with open(labels_path, 'r') as f:
        classes = [line.strip() for line in f.readlines()]
    
    # YOLO 预处理：1/255 归一化，(416, 416) 尺寸，swapRB=True (BGR转RGB)
    blob = cv2.dnn.blobFromImage(image, 1/255.0, (416, 416), swapRB=True, crop=False)
    net.setInput(blob)
    outputs = net.forward(output_layers)
    
    # 初始化检测结果
    boxes = []
    confidences = []
    class_ids = []
    
    # 解析检测框
    for output in outputs:
        for detection in output:
            scores = detection[5:]
            class_id = np.argmax(scores)
            confidence = scores[class_id]
            
            if confidence > 0.5:  # 置信度阈值
                # 还原坐标到原始图像尺寸
                center_x, center_y, bw, bh = (detection[0:4] * np.array([w, h, w, h])).astype("int")
                x = int(center_x - bw / 2)
                y = int(center_y - bh / 2)
                
                boxes.append([x, y, int(bw), int(bh)])
                confidences.append(float(confidence))
                class_ids.append(class_id)
    
    # 应用非极大值抑制
    indexes = cv2.dnn.NMSBoxes(boxes, confidences, 0.5, 0.4)
    
    # 绘制检测结果
    colors = np.random.uniform(0, 255, size=(len(classes), 3))
    
    if len(indexes) > 0:
        for i in indexes.flatten():
            x, y, w, h = boxes[i]
            label = str(classes[class_ids[i]])
            confidence = confidences[i]
            color = colors[class_ids[i]]
            
            cv2.rectangle(image, (x, y), (x + w, y + h), color.tolist(), 2)
            cv2.putText(image, f"{label} {confidence:.2f}", (x, y - 10), 
                       cv2.FONT_HERSHEY_SIMPLEX, 0.5, color.tolist(), 2)
    
    print(f"检测到 {len(indexes)} 个物体")
    return image, indexes, boxes, confidences, class_ids

def performance_optimization_tips():
    """
    OpenCV性能优化技巧
    """
    tips = {
        "内存管理": [
            "使用cv2.UMat替代numpy数组以利用GPU加速",
            "及时释放不需要的图像和变量",
            "批量处理图像而不是逐个处理"
        ],
        "算法选择": [
            "根据应用场景选择合适的算法",
            "对于实时应用，优先选择计算复杂度较低的算法",
            "使用积分图加速计算"
        ],
        "硬件加速": [
            "启用OpenCL以利用GPU加速",
            "使用Intel IPP优化库",
            "利用SIMD指令集"
        ]
    }
    
    for category, items in tips.items():
        print(f"\n{category}:")
        for item in items:
            print(f"  - {item}")

def hardware_acceleration_example():
    """
    硬件加速示例
    """
    # 检查OpenCL是否可用
    if cv2.ocl.haveOpenCL():
        cv2.ocl.setUseOpenCL(True)
        print("OpenCL加速已启用")
    else:
        print("OpenCL加速不可用")
    
    # 使用UMat进行GPU加速计算
    img = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
    umat_img = cv2.UMat(img)
    
    # 在GPU上执行操作
    processed = cv2.GaussianBlur(umat_img, (15, 15), 0)
    
    # 转换回CPU内存
    result = processed.get()
    
    return result

def industrial_inspection_example(image_path):
    """
    工业视觉检测示例：缺陷检测
    """
    img = cv2.imread(image_path)
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    # 应用高斯模糊
    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
    
    # 使用阈值化分离目标
    _, thresh = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    
    # 查找轮廓
    contours, _ = cv2.findContours(thresh, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
    
    defect_count = 0
    for contour in contours:
        area = cv2.contourArea(contour)
        # 假设缺陷面积小于某个阈值
        if area < 100 and area > 10:  # 调整阈值根据实际情况
            defect_count += 1
            # 绘制缺陷区域
            cv2.drawContours(img, [contour], -1, (0, 0, 255), 2)
    
    print(f"检测到 {defect_count} 个缺陷")
    return img, defect_count

def ocr_preprocessing(image_path):
    """
    OCR图像预处理
    """
    img = cv2.imread(image_path)
    
    # 转换为灰度图
    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    
    # 应用高斯模糊
    blurred = cv2.GaussianBlur(gray, (1, 1), 0)
    
    # 应用阈值化
    _, thresh = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    
    # 形态学操作清理图像
    kernel = np.ones((1, 1), np.uint8)
    cleaned = cv2.morphologyEx(thresh, cv2.MORPH_CLOSE, kernel)
    
    return cleaned