COLMAP Rust 库

一个用 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 中添加：

[dependencies]
colmap = "0.1.0"

🏗️ 架构设计

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

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

🎯 快速开始

基本使用流程

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!("重建完成！");

完整重建示例

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(())
}

📚 详细文档

特征提取和匹配

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 重建

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 密集重建

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 个）
• 内存管理：对于大规模数据集，考虑分块处理
• 并行处理：利用多线程处理独立的图像对

🔧 配置选项

特征提取配置

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

SfM 配置

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 配置

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，支持详细的错误信息：

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

🧪 测试

运行测试套件：

cargo test

运行特定模块的测试：

cargo test feature
cargo test sfm
cargo test mvs

📖 API 文档

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

cargo doc --open

或访问在线文档：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 文件。

👥 作者

• Amos Ryan - 初始工作 - amosryan

🙏 致谢

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

📞 联系方式

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

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