#图像增强与滤波：高斯模糊、中值滤波、直方图均衡化完整指南

"""
卷积操作原理：

卷积核（Kernel）：一个小矩阵，如 3×3、5×5
卷积过程：
1. 将卷积核放置在图像的每个像素位置
2. 计算核内像素值与核权重的乘积和
3. 将结果作为中心像素的新值
4. 重复此过程直到遍历整个图像
"""

import numpy as np

def manual_convolution(image, kernel):
    """
    手动实现卷积操作（演示原理）
    """
    # 获取图像和卷积核尺寸
    img_h, img_w = image.shape
    kernel_h, kernel_w = kernel.shape
    
    # 计算输出图像尺寸
    output_h = img_h - kernel_h + 1
    output_w = img_w - kernel_w + 1
    
    # 初始化输出图像
    output = np.zeros((output_h, output_w))
    
    # 执行卷积
    for i in range(output_h):
        for j in range(output_w):
            # 提取图像区域
            region = image[i:i+kernel_h, j:j+kernel_w]
            # 计算卷积
            output[i, j] = np.sum(region * kernel)
    
    return output

# 示例：简单的锐化卷积核
sharpen_kernel = np.array([
    [0, -1, 0],
    [-1, 5, -1],
    [0, -1, 0]
])

import cv2
import numpy as np
import matplotlib.pyplot as plt

def gaussian_blur_demo(image_path):
    """
    高斯模糊演示
    """
    img = cv2.imread(image_path)
    
    # 不同参数的高斯模糊
    blur_small = cv2.GaussianBlur(img, (3, 3), 0)      # 小核，轻微模糊
    blur_medium = cv2.GaussianBlur(img, (15, 15), 0)   # 中等核，适度模糊
    blur_large = cv2.GaussianBlur(img, (25, 25), 0)    # 大核，强烈模糊
    
    # 不同sigma值的影响
    blur_sigma_small = cv2.GaussianBlur(img, (15, 15), sigmaX=1.0)
    blur_sigma_large = cv2.GaussianBlur(img, (15, 15), sigmaX=5.0)
    
    return {
        'original': img,
        'small_kernel': blur_small,
        'medium_kernel': blur_medium,
        'large_kernel': blur_large,
        'sigma_small': blur_sigma_small,
        'sigma_large': blur_sigma_large
    }

# 高斯核可视化
def visualize_gaussian_kernel(size, sigma):
    """
    可视化高斯核
    """
    kernel = cv2.getGaussianKernel(size, sigma)
    # 创建2D高斯核
    kernel_2d = kernel * kernel.T
    
    plt.figure(figsize=(8, 6))
    plt.imshow(kernel_2d, cmap='hot', interpolation='nearest')
    plt.title(f'Gaussian Kernel (size={size}, sigma={sigma})')
    plt.colorbar()
    plt.show()
    
    return kernel_2d

# 使用示例
# gaussian_kernel = visualize_gaussian_kernel(5, 1.0)

def mean_filter_demo(image_path):
    """
    均值滤波演示
    """
    img = cv2.imread(image_path)
    
    # 使用blur函数实现均值滤波
    mean_filtered = cv2.blur(img, (5, 5))
    
    # 使用boxFilter函数（更灵活）
    box_filtered = cv2.boxFilter(img, -1, (5, 5))
    
    # 手动实现均值滤波（演示原理）
    def manual_mean_filter(image, kernel_size):
        kernel = np.ones((kernel_size, kernel_size), dtype=np.float32) / (kernel_size * kernel_size)
        return cv2.filter2D(image, -1, kernel)
    
    manual_filtered = manual_mean_filter(img, 5)
    
    return {
        'original': img,
        'mean_filtered': mean_filtered,
        'box_filtered': box_filtered,
        'manual_filtered': manual_filtered
    }

# 均值滤波的优缺点分析
"""
优点：
- 计算简单快速
- 有效平滑图像
- 降低噪声

缺点：
- 会模糊边缘
- 对椒盐噪声效果差
- 可能丢失细节
"""

def box_filter_comparison(image_path):
    """
    方框滤波与均值滤波比较
    """
    img = cv2.imread(image_path)
    
    # 标准均值滤波（归一化）
    mean_blur = cv2.blur(img, (5, 5))
    
    # 方框滤波（归一化）
    box_normalized = cv2.boxFilter(img, -1, (5, 5), normalize=True)
    
    # 方框滤波（非归一化）
    box_unnormalized = cv2.boxFilter(img, -1, (5, 5), normalize=False)
    
    return {
        'original': img,
        'mean_blur': mean_blur,
        'box_normalized': box_normalized,
        'box_unnormalized': box_unnormalized
    }

def median_filter_demo(image_path):
    """
    中值滤波演示
    """
    img = cv2.imread(image_path)
    
    # 添加椒盐噪声（用于演示）
    def add_salt_pepper_noise(image, salt_vs_pepper=0.5, amount=0.004):
        noisy_img = image.copy()
        total_pixels = noisy_img.size // 3  # 除以3是因为有RGB三个通道
        
        # 添加盐噪声（白色）
        num_salt = int(amount * total_pixels * salt_vs_pepper)
        coords = [np.random.randint(0, i - 1, num_salt) for i in image.shape[:2]]
        noisy_img[coords[0], coords[1], :] = 255
        
        # 添加胡椒噪声（黑色）
        num_pepper = int(amount * total_pixels * (1. - salt_vs_pepper))
        coords = [np.random.randint(0, i - 1, num_pepper) for i in image.shape[:2]]
        noisy_img[coords[0], coords[1], :] = 0
        
        return noisy_img
    
    # 创建带噪声的图像
    noisy_img = add_salt_pepper_noise(img)
    
    # 中值滤波
    median_filtered = cv2.medianBlur(noisy_img, 5)
    
    # 比较效果
    return {
        'original': img,
        'noisy': noisy_img,
        'median_filtered': median_filtered
    }

def adaptive_median_filter(image, max_window_size=7):
    """
    自适应中值滤波（高级技术）
    """
    # 这是一个简化版本，实际实现会更复杂
    h, w = image.shape[:2]
    result = image.copy()
    
    # 对每个像素应用自适应策略
    for i in range(1, h-1):
        for j in range(1, w-1):
            # 从最小窗口开始
            window_size = 3
            while window_size <= max_window_size:
                # 提取当前窗口
                window = image[i-window_size//2:i+window_size//2+1, 
                              j-window_size//2:j+window_size//2+1]
                
                # 计算中值和极值
                median_val = np.median(window)
                min_val = np.min(window)
                max_val = np.max(window)
                
                # 检查中心像素是否为噪声
                center_val = image[i, j]
                if min_val < center_val < max_val:
                    # 中心像素不是噪声，使用中值
                    result[i, j] = median_val
                    break
                else:
                    # 可能是噪声，扩大窗口
                    window_size += 2
                    
    return result

def bilateral_filter_demo(image_path):
    """
    双边滤波演示
    """
    img = cv2.imread(image_path)
    
    # 双边滤波参数说明：
    # d: 邻域直径，如果为0则自动计算
    # sigmaColor: 颜色空间的标准差，值越大表示更远的颜色会被混合
    # sigmaSpace: 坐标空间的标准差，值越大表示更远的像素会影响结果
    
    # 轻度双边滤波（保留较多细节）
    bilateral_light = cv2.bilateralFilter(img, 9, 50, 50)
    
    # 中度双边滤波
    bilateral_medium = cv2.bilateralFilter(img, 9, 100, 100)
    
    # 强度双边滤波（类似磨皮效果）
    bilateral_heavy = cv2.bilateralFilter(img, 15, 200, 200)
    
    # 参数调整指南
    """
    参数调整建议：
    - d: 一般设为5-9，过大会影响性能
    - sigmaColor: 通常为sigmaSpace的2倍左右
    - sigmaSpace: 根据图像内容调整，小值保留更多细节
    """
    
    return {
        'original': img,
        'light_bilateral': bilateral_light,
        'medium_bilateral': bilateral_medium,
        'heavy_bilateral': bilateral_heavy
    }

def compare_smoothing_methods(image_path):
    """
    比较不同的平滑方法
    """
    img = cv2.imread(image_path)
    
    # 不同方法的结果
    results = {}
    
    # 高斯模糊
    results['gaussian'] = cv2.GaussianBlur(img, (15, 15), 0)
    
    # 均值滤波
    results['mean'] = cv2.blur(img, (15, 15))
    
    # 中值滤波
    results['median'] = cv2.medianBlur(img, 15)
    
    # 双边滤波
    results['bilateral'] = cv2.bilateralFilter(img, 15, 150, 150)
    
    # 导向滤波（需要额外库）
    # results['guided'] = guided_filter(img, ...)
    
    return results

def morphological_operations_demo(image_path):
    """
    形态学操作演示
    """
    img = cv2.imread(image_path, 0)  # 灰度图
    
    # 创建结构元素（核）
    kernel_3x3 = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
    kernel_5x5 = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
    kernel_cross = cv2.getStructuringElement(cv2.MORPH_CROSS, (5, 5))
    
    # 腐蚀（Erosion）
    erosion = cv2.erode(img, kernel_5x5, iterations=1)
    
    # 膨胀（Dilation）
    dilation = cv2.dilate(img, kernel_5x5, iterations=1)
    
    # 开运算（先腐蚀后膨胀，去除小物体）
    opening = cv2.morphologyEx(img, cv2.MORPH_OPEN, kernel_5x5)
    
    # 闭运算（先膨胀后腐蚀，填充小洞）
    closing = cv2.morphologyEx(img, cv2.MORPH_CLOSE, kernel_5x5)
    
    # 形态学梯度（膨胀-腐蚀，提取边缘）
    gradient = cv2.morphologyEx(img, cv2.MORPH_GRADIENT, kernel_5x5)
    
    # 礼帽（原图-开运算，提取小亮点）
    tophat = cv2.morphologyEx(img, cv2.MORPH_TOPHAT, kernel_5x5)
    
    # 黑帽（闭运算-原图，提取小暗点）
    blackhat = cv2.morphologyEx(img, cv2.MORPH_BLACKHAT, kernel_5x5)
    
    return {
        'original': img,
        'erosion': erosion,
        'dilation': dilation,
        'opening': opening,
        'closing': closing,
        'gradient': gradient,
        'tophat': tophat,
        'blackhat': blackhat
    }

def advanced_morphology_techniques(image_path):
    """
    高级形态学技术
    """
    img = cv2.imread(image_path, 0)
    
    # 创建不同形状的结构元素
    rect_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (5, 5))
    ellipse_kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5))
    cross_kernel = cv2.getStructuringElement(cv2.MORPH_CROSS, (5, 5))
    
    # 使用不同核的形态学操作
    rect_opening = cv2.morphologyEx(img, cv2.MORPH_OPEN, rect_kernel)
    ellipse_opening = cv2.morphologyEx(img, cv2.MORPH_OPEN, ellipse_kernel)
    cross_opening = cv2.morphologyEx(img, cv2.MORPH_OPEN, cross_kernel)
    
    # 迭代形态学操作
    iterative_opening = cv2.morphologyEx(img, cv2.MORPH_OPEN, rect_kernel, iterations=2)
    iterative_closing = cv2.morphologyEx(img, cv2.MORPH_CLOSE, rect_kernel, iterations=2)
    
    return {
        'rect_opening': rect_opening,
        'ellipse_opening': ellipse_opening,
        'cross_opening': cross_opening,
        'iterative_opening': iterative_opening,
        'iterative_closing': iterative_closing
    }

def histogram_equalization_demo(image_path):
    """
    直方图均衡化演示
    """
    img = cv2.imread(image_path, 0)  # 灰度图
    
    # 标准直方图均衡化
    equalized = cv2.equalizeHist(img)
    
    # 彩色图像的直方图均衡化（转换到YUV空间）
    img_color = cv2.imread(image_path)
    img_yuv = cv2.cvtColor(img_color, cv2.COLOR_BGR2YUV)
    
    # 对Y通道进行直方图均衡化
    img_yuv[:,:,0] = cv2.equalizeHist(img_yuv[:,:,0])
    
    # 转换回BGR
    img_output = cv2.cvtColor(img_yuv, cv2.COLOR_YUV2BGR)
    
    # 显示直方图
    def plot_histograms(original, equalized):
        plt.figure(figsize=(12, 5))
        
        plt.subplot(1, 2, 1)
        plt.hist(original.ravel(), 256, [0, 256], alpha=0.7)
        plt.title('Original Histogram')
        plt.xlabel('Pixel Intensity')
        plt.ylabel('Frequency')
        
        plt.subplot(1, 2, 2)
        plt.hist(equalized.ravel(), 256, [0, 256], alpha=0.7, color='orange')
        plt.title('Equalized Histogram')
        plt.xlabel('Pixel Intensity')
        plt.ylabel('Frequency')
        
        plt.tight_layout()
        plt.show()
    
    # plot_histograms(img, equalized)
    
    return {
        'original': img,
        'equalized': equalized,
        'color_equalized': img_output
    }

def clahe_demo(image_path):
    """
    CLAHE（限制对比度自适应直方图均衡化）演示
    """
    img = cv2.imread(image_path, 0)  # 灰度图
    
    # 创建CLAHE对象
    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
    
    # 应用CLAHE
    clahe_result = clahe.apply(img)
    
    # 不同参数的CLAHE比较
    clahe_low_clip = cv2.createCLAHE(clipLimit=1.0, tileGridSize=(8, 8))
    clahe_high_clip = cv2.createCLAHE(clipLimit=4.0, tileGridSize=(8, 8))
    
    clahe_low = clahe_low_clip.apply(img)
    clahe_high = clahe_high_clip.apply(img)
    
    # 不同网格大小的比较
    clahe_small_grid = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(4, 4))
    clahe_large_grid = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(16, 16))
    
    clahe_small = clahe_small_grid.apply(img)
    clahe_large = clahe_large_grid.apply(img)
    
    return {
        'original': img,
        'clahe_default': clahe_result,
        'clahe_low_clip': clahe_low,
        'clahe_high_clip': clahe_high,
        'clahe_small_grid': clahe_small,
        'clahe_large_grid': clahe_large
    }

def clahe_on_color_image(image_path):
    """
    在彩色图像上应用CLAHE
    """
    img = cv2.imread(image_path)
    
    # 转换到LAB颜色空间（更好的亮度分离）
    lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
    
    # 对L通道应用CLAHE
    clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
    lab[:,:,0] = clahe.apply(lab[:,:,0])
    
    # 转换回BGR
    enhanced_img = cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)
    
    # 也可以在YCrCb空间中处理
    ycrcb = cv2.cvtColor(img, cv2.COLOR_BGR2YCrCb)
    ycrcb[:,:,0] = clahe.apply(ycrcb[:,:,0])
    enhanced_img_ycrcb = cv2.cvtColor(ycrcb, cv2.COLOR_YCrCb2BGR)
    
    return {
        'original': img,
        'enhanced_lab': enhanced_img,
        'enhanced_ycrcb': enhanced_img_ycrcb
    }

def guided_filter_demo():
    """
    导向滤波演示（概念介绍）
    注意：OpenCV中没有内置的导向滤波函数，
    需要使用第三方库如cv2.ximgproc.guidedFilter
    """
    try:
        import cv2.ximgproc as xip
        
        def apply_guided_filter(image, guide, radius, eps):
            """
            应用导向滤波
            """
            return xip.guidedFilter(guide, image, radius, eps)
        
        # 示例使用（需要实际图像）
        # filtered = apply_guided_filter(img, guide_img, 8, 0.01)
        
        print("导向滤波可用")
        
    except AttributeError:
        print("cv2.ximgproc.guidedFilter不可用，需要安装支持扩展模块的OpenCV")
        
        # 简单的边缘保留平滑替代方案
        def simple_edge_preserving_smooth(image, sigma_s=50, sigma_r=0.4):
            """
            简化的边缘保留平滑
            """
            return cv2.edgePreservingFilter(image, flags=1, sigma_s=sigma_s, sigma_r=sigma_r)

def non_local_means_denoising(image_path):
    """
    非局部均值去噪
    """
    img = cv2.imread(image_path)
    
    # 彩色图像去噪
    denoised_color = cv2.fastNlMeansDenoisingColored(
        img, 
        None,           # destination image
        10,             # h: filter strength for luminance component
        10,             # hForColorComponents: filter strength for color components
        7,              # templateWindowSize
        21              # searchWindowSize
    )
    
    # 灰度图像去噪
    img_gray = cv2.imread(image_path, 0)
    denoised_gray = cv2.fastNlMeansDenoising(
        img_gray,
        None,
        10,             # h: filter strength
        7,              # templateWindowSize
        21              # searchWindowSize
    )
    
    return {
        'original': img,
        'denoised_color': denoised_color,
        'original_gray': img_gray,
        'denoised_gray': denoised_gray
    }

def custom_kernels_demo(image_path):
    """
    自定义卷积核演示
    """
    img = cv2.imread(image_path)
    
    # 锐化核
    sharpen_kernel = np.array([
        [0, -1, 0],
        [-1, 5, -1],
        [0, -1, 0]
    ])
    
    # 边缘检测核（Sobel X）
    sobel_x_kernel = np.array([
        [-1, 0, 1],
        [-2, 0, 2],
        [-1, 0, 1]
    ])
    
    # 边缘检测核（Sobel Y）
    sobel_y_kernel = np.array([
        [-1, -2, -1],
        [0, 0, 0],
        [1, 2, 1]
    ])
    
    # 浮雕效果
    emboss_kernel = np.array([
        [-2, -1, 0],
        [-1, 1, 1],
        [0, 1, 2]
    ])
    
    # 应用自定义卷积核
    sharpened = cv2.filter2D(img, -1, sharpen_kernel)
    sobel_x = cv2.filter2D(img, -1, sobel_x_kernel)
    sobel_y = cv2.filter2D(img, -1, sobel_y_kernel)
    embossed = cv2.filter2D(img, -1, emboss_kernel)
    
    # 计算梯度幅度
    sobel_combined = np.sqrt(sobel_x.astype(float)**2 + sobel_y.astype(float)**2)
    sobel_combined = np.uint8(sobel_combined)
    
    return {
        'original': img,
        'sharpened': sharpened,
        'sobel_x': sobel_x,
        'sobel_y': sobel_y,
        'sobel_combined': sobel_combined,
        'embossed': embossed
    }

class ImageEnhancementToolbox:
    """
    图像增强工具箱
    """
    
    def __init__(self, image_path):
        self.original_image = cv2.imread(image_path)
        if self.original_image is None:
            raise ValueError(f"无法读取图像: {image_path}")
        self.current_image = self.original_image.copy()
    
    def gaussian_blur(self, kernel_size=5, sigma=0):
        """高斯模糊"""
        self.current_image = cv2.GaussianBlur(self.current_image, (kernel_size, kernel_size), sigma)
        return self
    
    def median_blur(self, kernel_size=5):
        """中值滤波"""
        self.current_image = cv2.medianBlur(self.current_image, kernel_size)
        return self
    
    def bilateral_filter(self, d=9, sigma_color=75, sigma_space=75):
        """双边滤波"""
        self.current_image = cv2.bilateralFilter(self.current_image, d, sigma_color, sigma_space)
        return self
    
    def histogram_equalization(self):
        """直方图均衡化（彩色图像）"""
        if len(self.current_image.shape) == 3:
            # 转换到YUV空间
            yuv = cv2.cvtColor(self.current_image, cv2.COLOR_BGR2YUV)
            yuv[:,:,0] = cv2.equalizeHist(yuv[:,:,0])
            self.current_image = cv2.cvtColor(yuv, cv2.COLOR_YUV2BGR)
        else:
            self.current_image = cv2.equalizeHist(self.current_image)
        return self
    
    def clahe_enhancement(self, clip_limit=2.0, tile_grid_size=(8, 8)):
        """CLAHE增强"""
        if len(self.current_image.shape) == 3:
            # 转换到LAB空间
            lab = cv2.cvtColor(self.current_image, cv2.COLOR_BGR2LAB)
            clahe = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=tile_grid_size)
            lab[:,:,0] = clahe.apply(lab[:,:,0])
            self.current_image = cv2.cvtColor(lab, cv2.COLOR_LAB2BGR)
        else:
            clahe = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=tile_grid_size)
            self.current_image = clahe.apply(self.current_image)
        return self
    
    def noise_reduction(self, h=10, h_color=10, template_ws=7, search_ws=21):
        """非局部均值去噪"""
        if len(self.current_image.shape) == 3:
            self.current_image = cv2.fastNlMeansDenoisingColored(
                self.current_image, None, h, h_color, template_ws, search_ws
            )
        else:
            self.current_image = cv2.fastNlMeansDenoising(
                self.current_image, None, h, template_ws, search_ws
            )
        return self
    
    def apply_custom_filter(self, kernel):
        """应用自定义滤波器"""
        self.current_image = cv2.filter2D(self.current_image, -1, kernel)
        return self
    
    def reset(self):
        """重置为原始图像"""
        self.current_image = self.original_image.copy()
        return self
    
    def get_current_image(self):
        """获取当前处理后的图像"""
        return self.current_image
    
    def show(self, window_name="Enhanced Image"):
        """显示当前图像"""
        cv2.imshow(window_name, self.current_image)
        cv2.waitKey(0)
        cv2.destroyAllWindows()
        return self
    
    def save(self, output_path):
        """保存图像"""
        success = cv2.imwrite(output_path, self.current_image)
        return success

# 使用示例
def demo_enhancement_pipeline(image_path):
    """
    演示增强流水线
    """
    toolbox = ImageEnhancementToolbox(image_path)
    
    # 创建几种不同的增强效果
    result1 = (ImageEnhancementToolbox(image_path)
              .gaussian_blur(kernel_size=5)
              .clahe_enhancement()
              .get_current_image())
    
    result2 = (ImageEnhancementToolbox(image_path)
              .bilateral_filter()
              .histogram_equalization()
              .get_current_image())
    
    result3 = (ImageEnhancementToolbox(image_path)
              .noise_reduction()
              .median_blur(kernel_size=3)
              .get_current_image())
    
    return {
        'original': cv2.imread(image_path),
        'pipeline1': result1,
        'pipeline2': result2,
        'pipeline3': result3
    }