colmap 0.1.2

# COLMAP Rust 库

[![Crates.io](https://img.shields.io/crates/v/colmap.svg)](https://crates.io/crates/colmap)
[![Documentation](https://docs.rs/colmap/badge.svg)](https://docs.rs/colmap)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个用 Rust 实现的 COLMAP（Structure-from-Motion 和 Multi-View Stereo）库，提供完整的 3D 重建管道。

## 🚀 主要功能

- **特征提取和匹配**：支持 SIFT、ORB、FAST 等多种特征检测算法
- **Structure from Motion (SfM)**：增量式稀疏 3D 重建
- **Multi-View Stereo (MVS)**：密集重建和点云生成
- **相机标定**：支持针孔、鱼眼等多种相机模型和畸变校正
- **几何验证**：RANSAC、本质矩阵估计等几何约束验证
- **束调整优化**：全局优化相机参数和 3D 点位置

## 📦 安装

在你的 `Cargo.toml` 中添加：

```toml
[dependencies]
colmap = "0.1.0"
```

## 🏗️ 架构设计

库采用模块化设计，主要包含以下模块：

- **`core`** - 核心数据结构和类型定义
- **`feature`** - 特征提取、描述符计算和匹配
- **`sfm`** - Structure from Motion 稀疏重建
- **`mvs`** - Multi-View Stereo 密集重建
- **`math`** - 数学工具和算法
- **`io`** - 数据输入输出
- **`utils`** - 通用工具函数

## 🎯 快速开始

### 基本使用流程

```rust
use colmap::*;

// 1. 创建相机模型
let intrinsics = CameraIntrinsics::pinhole(800.0, 800.0, 320.0, 240.0);
let camera = Camera::new(1, intrinsics, (640, 480), "Camera1".to_string());

// 2. 特征提取
let pipeline = FeaturePipeline::new(PipelineConfig::default());
// let features = pipeline.extract_features(&images)?;

// 3. SfM 重建
let sfm_config = SfmConfig::default();
let mut reconstructor = IncrementalSfm::new(sfm_config);
// let sparse_reconstruction = reconstructor.reconstruct(&images, &matches)?;

// 4. MVS 密集重建
let mvs_config = MvsConfig::default();
let mvs_reconstructor = MvsReconstructor::new(mvs_config);
// let dense_reconstruction = mvs_reconstructor.reconstruct(&views)?;

println!("重建完成！");
```

### 完整重建示例

```rust
use colmap::*;
use std::path::Path;

fn reconstruct_from_images(image_dir: &Path) -> Result<()> {
    // 1. 加载图像
    let images = load_images_from_directory(image_dir)?;
    
    // 2. 特征提取和匹配
    let feature_config = PipelineConfig {
        detector_type: DetectorType::Sift,
        max_features: 8000,
        ..Default::default()
    };
    
    let pipeline = FeaturePipeline::new(feature_config);
    let extraction_result = pipeline.extract_and_match_all(&images)?;
    
    println!("提取了 {} 个图像的特征", extraction_result.features.len());
    println!("找到 {} 个匹配对", extraction_result.matches.len());
    
    // 3. SfM 稀疏重建
    let sfm_config = SfmConfig {
        min_track_length: 2,
        max_reprojection_error: 4.0,
        ..Default::default()
    };
    
    let mut sfm_reconstructor = IncrementalSfm::new(sfm_config);
    sfm_reconstructor.set_features(extraction_result.features);
    sfm_reconstructor.set_matches(extraction_result.matches);
    
    let sparse_reconstruction = sfm_reconstructor.reconstruct()?;
    
    println!("稀疏重建统计:");
    println!("  - 注册图像: {}", sparse_reconstruction.registered_images());
    println!("  - 3D 点数量: {}", sparse_reconstruction.points.len());
    println!("  - 平均重投影误差: {:.2}", sparse_reconstruction.mean_reprojection_error());
    
    // 4. MVS 密集重建
    let mvs_config = MvsConfig {
        min_num_views: 3,
        max_image_size: 1600,
        depth_range: (0.1, 100.0),
        ..Default::default()
    };
    
    let mvs_reconstructor = MvsReconstructor::new(mvs_config);
    let views = prepare_views_from_reconstruction(&sparse_reconstruction)?;
    let dense_reconstruction = mvs_reconstructor.reconstruct(&views)?;
    
    println!("密集重建统计:");
    println!("  - 点云大小: {}", dense_reconstruction.point_cloud.points.len());
    println!("  - 网格三角形: {}", dense_reconstruction.mesh.triangles.len());
    
    // 5. 保存结果
    save_reconstruction(&sparse_reconstruction, "sparse_reconstruction")?;
    save_point_cloud(&dense_reconstruction.point_cloud, "dense_point_cloud.ply")?;
    save_mesh(&dense_reconstruction.mesh, "mesh.obj")?;
    
    Ok(())
}
```

## 📚 详细文档

### 特征提取和匹配

```rust
use colmap::feature::*;

// 创建 SIFT 检测器
let config = DetectorConfig::sift();
let detector = DetectorFactory::create(DetectorType::Sift, config)?;

// 检测特征点
let keypoints = detector.detect(&image)?;
println!("检测到 {} 个特征点", keypoints.len());

// 特征匹配
let config = MatcherConfig::default();
let matcher = MatcherFactory::create(MatcherType::BruteForce, config)?;
let matches = matcher.match_features(&features1, &features2)?;
```

### SfM 重建

```rust
use colmap::sfm::*;

// 配置 SfM 参数
let config = SfmConfig {
    min_track_length: 2,
    max_reprojection_error: 4.0,
    ..Default::default()
};

// 执行增量式重建
let mut reconstructor = IncrementalSfm::new(config);
let reconstruction = reconstructor.reconstruct()?;
```

### MVS 密集重建

```rust
use colmap::mvs::*;

// 配置 MVS 参数
let config = MvsConfig {
    min_num_views: 3,
    max_image_size: 1600,
    depth_range: (0.1, 100.0),
    ..Default::default()
};

// 执行密集重建
let reconstructor = MvsReconstructor::new(config);
let result = reconstructor.reconstruct(&views)?;
```

## ⚡ 性能优化建议

- **图像尺寸**：推荐使用 1600x1200 以下的图像以平衡质量和速度
- **特征点数量**：根据场景复杂度调整特征点数量（通常 4000-8000 个）
- **内存管理**：对于大规模数据集，考虑分块处理
- **并行处理**：利用多线程处理独立的图像对

## 🔧 配置选项

### 特征提取配置

```rust
let config = PipelineConfig {
    detector_type: DetectorType::Sift,
    max_features: 8000,
    quality_threshold: 0.01,
    min_distance: 1.0,
};
```

### SfM 配置

```rust
let config = SfmConfig {
    min_track_length: 2,
    max_reprojection_error: 4.0,
    bundle_adjustment: BundleAdjustmentConfig {
        max_iterations: 100,
        convergence_threshold: 1e-6,
        optimize_intrinsics: true,
        optimize_distortion: false,
    },
};
```

### MVS 配置

```rust
let config = MvsConfig {
    min_num_views: 3,
    max_image_size: 1600,
    depth_range: (0.1, 100.0),
    stereo_config: StereoMatchConfig::default(),
    depth_config: DepthEstimationConfig::default(),
    fusion_config: FusionConfig::default(),
};
```

## 🚨 错误处理

库使用统一的错误类型 `ColmapError`，支持详细的错误信息：

```rust
match reconstruct_scene() {
    Ok(reconstruction) => {
        println!("重建成功！");
    }
    Err(ColmapError::FeatureExtraction(msg)) => {
        eprintln!("特征提取失败: {}", msg);
    }
    Err(ColmapError::SfmReconstruction(msg)) => {
        eprintln!("SfM 重建失败: {}", msg);
    }
    Err(e) => {
        eprintln!("其他错误: {}", e);
    }
}
```

## 🧪 测试

运行测试套件：

```bash
cargo test
```

运行特定模块的测试：

```bash
cargo test feature
cargo test sfm
cargo test mvs
```

## 📖 API 文档

完整的 API 文档可以通过以下命令生成：

```bash
cargo doc --open
```

或访问在线文档：[https://docs.rs/colmap](https://docs.rs/colmap)

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 这个仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 📄 许可证

本项目使用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 👥 作者

- **Amos Ryan** - *初始工作* - [amosryan](https://github.com/amosryan)

## 🙏 致谢

- 感谢原始 COLMAP 项目的启发
- 感谢 Rust 社区的优秀库支持
- 感谢所有贡献者的努力

## 📞 联系方式

- 邮箱：self@zhichao.ren
- 项目主页：https://atomgit.com/amosryan/colmap
- 文档：https://docs.rs/colmap

---

**注意**：这是一个实验性项目，仍在积极开发中。API 可能会发生变化。