# 图像配准工具集 (Image Registration Toolkit)

这是一个基于 Python 的遥感图像配准工具集，主要用于批量配准 .bip 格式的影像文件到参考 .tif 文件。支持多种变换模型和质量控制机制，特别适用于森林、水体等复杂地物场景。

## 功能特性

### 核心功能
- **批量配准**: 支持批量处理多个 .bip 文件到参考 .tif 文件
- **多种变换模型**: 支持相似变换、仿射变换、单应变换等
- **智能掩膜**: 使用有效区域掩膜和水体分割提高配准质量
- **质量控制**: 基于内点数、内点比例和重投影误差的质量评估
- **可视化输出**: 自动生成匹配结果和关键点可视化图像

### 高级特性
- **RANSAC 参数控制**: 可配置的重投影误差阈值、置信度和最大迭代次数
- **纹理过滤**: 基于梯度幅值的纹理质量筛选
- **几何约束**: 距离边界限制和空间分布均匀性检查
- **多尺度处理**: 支持不同分辨率的匹配和变换

## 文件说明

### 核心脚本
- `test V8.py`: 最新版本的主配准脚本，支持有效区域掩膜
- `test V9.py`: 增强版本，包含软掩膜和纹理过滤
- `demo.py`: 基础演示脚本，展示匹配和可视化功能

### 工具脚本
- `mask_water.py`: 基于 ROI 文件掩膜 TIF 图像的工具
- `test V5.py` - `test V7.py`: 早期版本的配准脚本

## 环境要求

### 依赖包
```
numpy
opencv-python
rasterio
geopandas
shapely
scikit-image
matplotlib
scipy
torch (用于 vismatch)
vismatch
```

### 安装
```bash
pip install numpy opencv-python rasterio geopandas shapely scikit-image matplotlib scipy torch
# 安装 vismatch (假设已配置)
```

## 使用方法

### 基本配准
```bash
python test_V8.py  # 运行主配准脚本
```

### 参数配置
在脚本开头修改以下关键参数：

```python
# 文件路径
REF_TIF = r"E:\path\to\reference.tif"  # 参考影像路径
BIP_DIR = Path(r"E:\path\to\bip\directory")  # BIP文件目录
OUT_DIR = Path(r"E:\path\to\output")  # 输出目录

# 匹配参数
MATCHER_NAME = "matchanything-roma"  # 匹配器选择
MATCH_MAX_SIDE = 1200  # 匹配最大边长
DEVICE = "cuda"  # 或 "cpu"

# 变换方法优先级
TRANSFORM_METHODS = ["similarity", "affine", "homography"]

# RANSAC参数
RANSAC_REPROJ_THRESHOLD = 3.0  # 重投影误差阈值
RANSAC_CONFIDENCE = 0.99       # 置信度
RANSAC_MAX_ITERS = 1000        # 最大迭代次数

# 质量控制
MIN_INLIERS = 10       # 最少内点数
MIN_INLIER_RATIO = 0.01 # 最少内点比例
```

### ROI掩膜工具
```bash
python mask_water.py input.tif roi.shp -o output_masked.tif
```

## 算法流程

1. **粗定位**: 使用源影像有效区域确定参考影像的感兴趣区域 (ROI)
2. **数据读取**: 读取源影像和参考影像的对应区域
3. **掩膜处理**: 应用有效区域掩膜和水体分割
4. **特征匹配**: 使用深度学习匹配器提取和匹配特征点
5. **几何变换**: 尝试多种变换模型，选择最优的几何变换
6. **质量评估**: 基于重投影误差评估变换质量
7. **输出生成**: 生成配准后的影像和可视化结果

## 关键参数说明

### 匹配参数
- `MATCH_MAX_SIDE`: 控制匹配时的图像尺寸，越小速度越快但细节损失越多
- `ROI_PAD_PX`: ROI扩展像素，影响匹配区域范围

### RANSAC参数
- `RANSAC_REPROJ_THRESHOLD`: 内点判断的误差阈值，越小内点质量越高但数量越少
- `RANSAC_CONFIDENCE`: 算法置信度，影响迭代次数
- `RANSAC_MAX_ITERS`: 最大迭代次数上限

### 质量控制
- `MIN_INLIERS`: 最少内点数量要求
- `MIN_INLIER_RATIO`: 内点比例要求

## 场景优化建议

### 森林场景
```python
MATCH_MAX_SIDE = 1600
MIN_INLIERS = 25
MIN_INLIER_RATIO = 0.025
# 启用纹理过滤和边界距离限制
```

### 水体场景
```python
# 使用水体掩膜预处理
MASK_PAD_PX = 100
# 调大RANSAC阈值容忍岸线变化
RANSAC_REPROJ_THRESHOLD = 4.0
```

### 城市/结构化场景
```python
MATCH_MAX_SIDE = 1000  # 结构特征明显，不需要很高分辨率
RANSAC_REPROJ_THRESHOLD = 2.0  # 严格质量控制
```

## 输出结果

### 文件输出
- `*_registered.bip`: 配准后的影像文件
- `visualizations/*_matches.png`: 匹配结果可视化
- `visualizations/*_keypoints_src.png`: 源影像关键点
- `visualizations/*_keypoints_ref.png`: 参考影像关键点

### 统计输出
- `stats/registration_stats.csv`: 包含每对影像的配准统计信息

## 故障排除

### 常见问题
1. **内点数过少**: 检查影像质量，调整 RANSAC 参数，或扩大匹配区域
2. **内存不足**: 降低 `MATCH_MAX_SIDE` 或使用 CPU 模式
3. **配准失败**: 检查坐标系统一致性，调整质量阈值

### 调试建议
- 查看可视化输出了解匹配情况
- 检查统计 CSV 文件的各项指标
- 调整参数时从小范围测试开始

## 版本历史

- **test V8.py**: 支持有效区域掩膜和 RANSAC 参数控制
- **test V9.py**: 增加软掩膜和纹理过滤
- **早期版本**: 基础配准功能实现

## 许可证

本项目遵循 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request 来改进这个工具集。