# match_image

**Repository Path**: py_hanyx/match_image

## Basic Information

- **Project Name**: match_image
- **Description**: 匹配图片
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-14
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片匹配解决方案

## 简介

本项目提供了一个基于Python的图片匹配解决方案，专门用于比较客户端界面图片，能够排除右上角时钟区域的影响，并处理图片间的细微差异（如不同的商品价格）。

## 技术方案

### 核心算法

1. **特征点匹配**：使用ORB（Oriented FAST and Rotated BRIEF）算法提取图片特征点，具有尺度不变性和旋转不变性，适合处理不同时间截图的匹配。

2. **多种哈希算法**：结合phash（感知哈希）、ahash（平均哈希）和dhash（差值哈希）三种哈希算法，快速筛选出潜在的相似图片。

3. **结构相似性指数（SSIM）**：计算图片的结构相似性，从亮度、对比度和结构三个方面评估图片相似度。

4. **综合相似度**：将哈希相似度、特征相似度和SSIM相似度进行加权平均，得到最终的综合相似度评分。

### 特殊处理

1. **排除时钟区域**：通过掩码法将右上角时钟区域填充为白色，避免时钟变化对匹配结果的影响。时钟区域格式为(x, y, width, height)。

2. **处理细微差异**：通过调整相似度阈值和加权系数，能够识别出具有细微差异（如不同商品价格）的相似界面。

## 项目结构

```
.
├── image_matcher.py      # 核心图片匹配类和主程序
├── input_images/         # 要比较的图片目录（需手动创建）
├── image_library/        # 图片库目录
├── results/              # 结果保存目录（自动生成）
├── requirements.txt      # 依赖库列表
└── README.md             # 项目说明文档
```

## 安装依赖

```bash
pip install -r requirements.txt
```

## 快速开始

### 1. 直接运行程序

将需要比较的图片放入 `input_images` 目录，然后直接运行程序：

```bash
python image_matcher.py
```

程序将：
- 加载 `image_library` 目录中的所有图片
- 处理 `input_images` 目录中的所有图片
- 将结果保存在 `results/YYYYMMDD_HHMMSS` 目录中，包括：
  - 可视化匹配图片（每个80分以上的匹配生成一张）
  - 匹配结果文本文件（包含最佳匹配和所有80分以上的匹配）

### 2. 编程使用

```python
from image_matcher import ImageMatcher

# 配置参数
IMAGE_LIB_PATH = "./image_library"  # 图片库路径
CLOCK_AREA = (780, 0, 250, 100)  # 右上角时钟区域 (x, y, width, height)
INPUT_IMAGE_PATH = "./input_images/test.png"  # 测试图片路径

# 创建图片匹配器
matcher = ImageMatcher(IMAGE_LIB_PATH, CLOCK_AREA)

# 匹配图片
result = matcher.match_image(INPUT_IMAGE_PATH)

# 输出最佳匹配结果
print(f"最佳匹配结果:")
print(f"图片名称: {result['best_match']['image_name']}")
print(f"图片路径: {result['best_match']['image_path']}")
print(f"平均哈希相似度: {result['best_match']['avg_hash_similarity']:.4f}")
print(f"特征相似度: {result['best_match']['feature_similarity']:.4f}")
print(f"SSIM相似度: {result['best_match']['ssim_similarity']:.4f}")
print(f"综合相似度: {result['best_match']['combined_similarity']:.4f}")
print(f"是否匹配: {'是' if result['best_match']['is_match'] else '否'}")

# 输出所有80分以上的匹配结果
if result['qualified_matches']:
    print(f"\n所有综合相似度80分以上的匹配结果 ({len(result['qualified_matches'])} 个):")
    for i, match in enumerate(result['qualified_matches'], 1):
        print(f"{i}. {match['image_name']} - 综合相似度: {match['combined_similarity']:.4f}")
```

### 3. 可视化匹配结果

```python
# 可视化最佳匹配结果
vis_img = matcher.visualize_match(INPUT_IMAGE_PATH, result['best_match'], save_path="./best_match.jpg")

# 可视化所有80分以上的匹配结果
for i, match in enumerate(result['qualified_matches'], 1):
    output_path = f"./match_{i}.jpg"
    vis_img = matcher.visualize_match(INPUT_IMAGE_PATH, match, save_path=output_path)
    print(f"已生成匹配结果图片: {output_path}")
```

### 4. 调整匹配参数

```python
# 调整匹配参数
result = matcher.match_image(
    INPUT_IMAGE_PATH,
    hash_threshold=0.75,      # 哈希相似度阈值
    feature_threshold=0.6,     # 特征相似度阈值
    ssim_threshold=0.8,        # SSIM相似度阈值
    combined_threshold=0.8     # 综合相似度阈值（80分）
)
```

## 匹配结果格式

### match_image 方法返回值

```python
{
    'best_match': {
        'image_path': str,         # 最佳匹配图片路径
        'image_name': str,         # 最佳匹配图片名称
        'avg_hash_similarity': float, # 平均哈希相似度
        'feature_similarity': float,  # 特征相似度
        'ssim_similarity': float,     # SSIM相似度
        'combined_similarity': float, # 综合相似度
        'is_match': bool              # 是否匹配（综合相似度>=阈值）
    },
    'all_matches': [
        # 所有匹配结果，格式同 best_match
    ],
    'qualified_matches': [
        # 所有综合相似度80分以上的匹配结果，格式同 best_match，按综合相似度降序排序
    ]
}
```

## 高级功能

### 1. 动态更新图片库

```python
# 更新图片库
matcher.update_image_library()
```

### 2. 自定义结果保存

```python
import os
import time

# 自定义结果保存目录
results_dir = f"./custom_results/{time.strftime('%Y%m%d_%H%M%S')}"
os.makedirs(results_dir, exist_ok=True)

# 保存匹配结果到文件
def save_results_to_file(input_filename, result, output_dir):
    # 实现自定义保存逻辑
    pass
```

## 算法原理详解

### 1. ORB特征点匹配

ORB算法结合了FAST关键点检测和BRIEF描述符，具有以下特点：
- 计算速度快，适合实时应用
- 具有尺度不变性和旋转不变性
- 对光照变化具有一定的鲁棒性

### 2. 哈希算法

- **phash（感知哈希）**：基于DCT变换，更能反映人类视觉感知的相似性
- **ahash（平均哈希）**：计算简单，速度快，适合初步筛选
- **dhash（差值哈希）**：通过比较相邻像素差异生成哈希值，对细微变化更敏感

### 3. SSIM（结构相似性指数）

SSIM从三个方面评估图片相似度：
- **亮度（Luminance）**：评估图片的平均亮度差异
- **对比度（Contrast）**：评估图片的对比度差异
- **结构（Structure）**：评估图片的结构差异

## 性能优化

1. **哈希算法快速筛选**：首先使用哈希算法快速筛选出潜在的相似图片，减少后续特征匹配的计算量

2. **特征点数量优化**：调整ORB算法的特征点数量，平衡匹配精度和计算速度

3. **并行处理**：对于大规模图片库，可以考虑使用并行处理加速匹配过程

## 应用场景

1. **UI自动化测试**：比较客户端界面截图，验证UI一致性

2. **客户端界面监控**：监控客户端界面变化，及时发现异常

3. **图片检索**：根据示例图片搜索相似的客户端界面

4. **版本控制**：跟踪客户端界面的版本变化

## 注意事项

1. **时钟区域设置**：请根据实际图片调整时钟区域坐标，确保准确排除时钟影响

2. **阈值调整**：根据实际应用场景调整相似度阈值，平衡匹配精度和召回率

3. **图片质量**：确保输入图片清晰，避免模糊或过度压缩的图片影响匹配结果

4. **图片大小**：建议使用相同分辨率的图片进行匹配，提高匹配精度

5. **目录结构**：
   - 确保 `image_library` 目录存在且包含参考图片
   - 确保 `input_images` 目录存在且包含要比较的图片
   - 结果将自动保存到 `results` 目录，无需手动创建

6. **文件命名**：避免使用特殊字符命名图片文件，确保文件名能正常显示和处理

7. **VS Code调试**：项目已配置VS Code调试环境，可直接在VS Code中按F5启动调试

8. **结果解读**：
   - 综合相似度0.8以上（80分）被认为是匹配成功
   - 综合相似度越高，匹配越精准
   - 可视化图片中显示了特征点匹配情况，便于直观比较

## VS Code调试配置

项目已配置好VS Code调试环境，包含两个调试选项：

1. **Python: 图片匹配程序**：直接运行主程序
2. **Python: 图片匹配程序 - 带参数**：支持添加命令行参数

### 使用方法：

1. 打开VS Code（在项目目录中执行 `code .`）
2. 点击左侧活动栏的调试按钮（或按 `Ctrl+Shift+D`）
3. 在顶部的调试配置下拉菜单中选择一个配置
4. 设置断点（在代码行号左侧点击添加）
5. 点击绿色的"启动调试"按钮（或按 `F5`）
6. 在断点处暂停，查看变量值、单步执行等

## 扩展建议

1. **添加深度学习模型**：可以考虑集成预训练的深度学习模型（如ResNet、VGG）提取更高级的图像特征

2. **支持视频流**：扩展支持实时视频流的界面匹配

3. **添加异常检测**：结合异常检测算法，自动发现异常的客户端界面

4. **分布式处理**：对于大规模图片库，实现分布式匹配，提高处理速度

## 许可证

本项目采用MIT许可证，可自由使用和修改。