# desk-mouse

**Repository Path**: per_info/desk-mouse

## Basic Information

- **Project Name**: desk-mouse
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-01-08
- **Last Updated**: 2025-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 图片预处理系统使用说明

## 系统概述

图片预处理系统是一个智能的图像识别优化工具，通过预先生成多种图像变体来提高图像识别的成功率和性能。

### 主要特性

- **多策略预处理**: 支持背景去除、二值化、对比度增强等多种预处理方法
- **智能缓存管理**: 内存+磁盘双重缓存，提高访问速度
- **批量处理**: 支持批量预处理整个目录的图片
- **配置化管理**: 通过YAML配置文件灵活控制预处理参数
- **向后兼容**: 保持原有图像查找接口的兼容性

## 系统架构

```
图片预处理系统
├── 图片预处理器 (ImagePreprocessor)
│   ├── 背景去除 (remove_background)
│   ├── 二值化转换 (convert_to_binary)
│   ├── 对比度增强 (enhance_image_contrast)
│   └── 变体生成 (create_preprocessing_variants)
├── 缓存管理器 (PreprocessingCache)
│   ├── 内存缓存 (memory_cache)
│   ├── 磁盘缓存 (disk_cache)
│   └── 缓存索引 (preprocessing_index.json)
└── 图像查找优化 (findImageOptimized)
    ├── 多策略查找 (find_all_images_with_preprocessing)
    ├── SIFT特征匹配 (find_image_sift_with_image)
    └── PyAutoGUI降级 (find_all_images_pyautogui_fallback)
```

## 安装和配置

### 1. 依赖安装

```bash
pip install opencv-python numpy PyYAML
```

### 2. 配置文件

在 `config/devices.yaml` 中配置预处理参数：

```yaml
image_recognition:
  preprocessing:
    enabled: true                    # 启用预处理
    cache_directory: "resource/preprocessed"  # 缓存目录
    auto_generate: true             # 自动生成预处理图片
    force_regenerate: false         # 强制重新生成
    cleanup_unused: true            # 清理未使用的缓存
    max_cache_size_mb: 100         # 最大缓存大小(MB)
    
    # 背景去除配置
    background_removal:
      enabled: true
      white_threshold: 200
      light_threshold: 150
      edge_detection_fallback: true
    
    # 二值化配置
    binary_conversion:
      enabled: true
      adaptive_block_size: 11
      adaptive_c: 2
      morph_kernel_size: 2
    
    # 对比度增强配置
    contrast_enhancement:
      enabled: true
      alpha: 1.5
      beta: 10
      histogram_equalization: true
```

## 使用方法

### 1. 命令行工具

#### 批量预处理目录
```bash
# 预处理整个目录
python utils/imagePreprocessor.py --dir resource/app-jyx --batch

# 预处理单个图片
python utils/imagePreprocessor.py --image resource/app-jyx/home-1-1.png

# 生成预处理索引
python utils/imagePreprocessor.py --index

# 清理过期缓存
python utils/imagePreprocessor.py --cleanup
```

#### 帮助信息
```bash
python utils/imagePreprocessor.py --help
```

### 2. 编程接口

#### 创建预处理器
```python
from utils.imagePreprocessor import ImagePreprocessor

# 创建预处理器
preprocessor = ImagePreprocessor()

# 预处理单个图片
success = preprocessor.preprocess_single_image("resource/app-jyx/home-1-1.png")

# 批量预处理目录
results = preprocessor.scan_and_preprocess_directory("resource/app-jyx")
```

#### 使用缓存管理器
```python
from utils.preprocessingCache import PreprocessingCache

# 创建缓存管理器
cache = PreprocessingCache()

# 检查是否有预处理变体
available = cache.is_preprocessing_available("resource/app-jyx/home-1-1.png")

# 获取可用变体
variants = cache.get_available_variants("resource/app-jyx/home-1-1.png")

# 获取预处理图片
image = cache.get_preprocessed_image("resource/app-jyx/home-1-1.png", "no_background")
```

#### 图像查找（自动使用预处理）
```python
from utils.findImageOptimized import find_all_images

# 启用预处理（默认）
result = find_all_images("resource/app-jyx/home-1-1.png", use_preprocessing=True)

# 禁用预处理
result = find_all_images("resource/app-jyx/home-1-1.png", use_preprocessing=False)
```

## 预处理变体类型

### 1. 原始图像 (original)
- 保持原始图像不变
- 用于标准SIFT特征匹配

### 2. 背景去除 (no_background)
- 去除白色和浅色背景
- 保留主要前景内容
- 适用于有复杂背景的图像

### 3. 自适应二值化 (binary_adaptive)
- 使用自适应阈值进行二值化
- 适合光照不均匀的图像
- 通过形态学操作去除噪点

### 4. Otsu二值化 (binary_otsu)
- 自动计算最佳阈值
- 适合双峰直方图图像
- 全局最优二值化

### 5. 对比度增强 (enhanced)
- 直方图均衡化
- 线性对比度和亮度调整
- 提高图像细节可见性

### 6. 组合处理 (no_bg_enhanced)
- 背景去除 + 对比度增强
- 综合多种预处理效果
- 适用于复杂场景

## 性能优化

### 1. 缓存策略
- **内存缓存**: 频繁访问的图片保持在内存中
- **磁盘缓存**: 预处理变体持久化存储
- **智能清理**: 自动清理不常用的缓存

### 2. 并行处理
- 使用线程池并行预处理多张图片
- 可配置最大并发工作线程数
- 提高批量处理效率

### 3. 渐进式查找
- 按优先级尝试不同预处理变体
- SIFT失败时自动降级到PyAutoGUI
- 动态调整confidence参数

## 故障排除

### 1. 常见问题

#### 预处理变体未生成
```bash
# 检查配置
python utils/imagePreprocessor.py --index

# 强制重新生成
python utils/imagePreprocessor.py --dir resource/app-jyx --batch
```

#### 缓存管理器未启用
- 检查 `config/devices.yaml` 中的 `enabled: true`
- 确保配置文件格式正确
- 重启应用程序

#### 路径匹配失败
- 检查路径分隔符（Windows使用`\`，Linux使用`/`）
- 使用相对路径或绝对路径
- 检查文件权限

### 2. 调试模式

启用调试模式查看详细信息：

```python
# 在图像查找时启用调试
result = find_all_images("image.png", debug=True)

# 查看缓存统计
cache = PreprocessingCache()
stats = cache.get_cache_stats()
print(stats)
```

### 3. 日志输出

系统会输出详细的处理信息：

```
正在预处理图片: resource/app-jyx/home-1-1.png
成功创建 6 个图像预处理变体
保存了 4 个预处理变体到: resource/preprocessed\app-jyx\home-1-1
检测到预处理变体，使用多策略查找...
尝试变体: no_background
变体 no_background 查找成功!
```

## 最佳实践

### 1. 预处理策略
- 根据图像特点选择合适的预处理方法
- 背景复杂的图像优先使用背景去除
- 光照不均匀的图像使用自适应二值化
- 对比度低的图像使用对比度增强

### 2. 缓存管理
- 定期清理过期缓存
- 监控缓存大小，避免占用过多磁盘空间
- 对于频繁使用的图像，保持其预处理变体

### 3. 性能调优
- 调整SIFT参数以平衡速度和准确性
- 配置合适的confidence阈值
- 使用region参数限制搜索范围

### 4. 错误处理
- 实现优雅的降级策略
- 记录预处理失败的原因
- 提供用户友好的错误信息

## 扩展开发

### 1. 添加新的预处理方法

```python
class ImagePreprocessor:
    def new_preprocessing_method(self, image):
        """新的预处理方法"""
        # 实现预处理逻辑
        return processed_image
    
    def create_preprocessing_variants(self, image_path):
        # 添加新变体
        variants.append({
            'image': self.new_preprocessing_method(original),
            'type': 'new_method',
            'description': '新预处理方法'
        })
```

### 2. 自定义缓存策略

```python
class CustomPreprocessingCache(PreprocessingCache):
    def custom_cache_strategy(self):
        """自定义缓存策略"""
        pass
```

### 3. 集成新的图像识别算法

```python
def find_image_with_new_algorithm(image_path, region, confidence):
    """使用新算法的图像查找"""
    pass
```

## 总结

图片预处理系统通过智能的多策略处理和高效的缓存管理，显著提高了图像识别的成功率和性能。系统设计灵活，易于扩展，可以根据具体需求进行定制和优化。

通过合理配置和使用，该系统能够：
- 提高复杂背景图像的识别成功率
- 减少重复的预处理计算
- 支持多种图像处理策略
- 保持与现有系统的兼容性
- 提供良好的用户体验和开发体验