ReconstructFull API

ReconstructFull 是最简单易用的全流程重建接口，适合快速启动项目和新手用户。它会自动处理图像元数据提取、空三计算和三维重建的完整流程。

🎯 接口特点

✅ 自动化程度高：自动从图像 EXIF 读取 GPS 和相机信息
✅ 配置简单：最少只需要提供图像路径
✅ 一步到位：从图像直接生成最终成果
✅ 智能优化：自动选择最佳处理参数

📋 参数详解

必需参数

参数名	类型	说明	示例值
`license_id`	int	SDK 许可证 ID	`9200`
`working_dir`	string	工作目录路径	`"C:/Projects/MyProject"`
`gdal_folder`	string	GDAL 数据目录	`"C:/MipMap/SDK/data"`
`coordinate_system`	object	输入坐标系	见下方说明
`image_meta_data`	array	图像列表	见下方说明
`input_image_type`	int	图像类型	`1`=RGB, `2`=多光谱, `3`=红外
`resolution_level`	int	精度等级	`1`=高, `2`=中, `3`=低

可选参数 - 输出控制

参数名	类型	默认值	说明
`generate_obj`	bool	false	生成 OBJ 格式模型
`generate_ply`	bool	false	生成 PLY 格式模型
`generate_osgb`	bool	false	生成 OSGB 格式（倾斜摄影）
`generate_3d_tiles`	bool	false	生成 3D Tiles（Cesium）
`generate_las`	bool	false	生成 LAS 点云
`generate_pc_ply`	bool	false	生成点云 PLY
`generate_pc_osgb`	bool	false	生成点云 OSGB (LOD)
`generate_pc_pnts`	bool	false	生成点云 PNTS (3D Tiles)
`generate_geotiff`	bool	false	生成正射影像
`generate_tile_2D`	bool	false	生成 2D 瓦片
`generate_2D_from_3D_model`	bool	false	从 3D 模型生成正射

可选参数 - 坐标系

参数名	类型	默认值	说明
`coordinate_system_3d`	object	Local/LocalENU	输出 3D 坐标系
`coordinate_system_2d`	object	LocalENU	输出 2D 坐标系

可选参数 - 高级功能

参数名	类型	默认值	说明
`gcp_path`	string	-	控制点文件路径
`gcp_coor_sys`	object	-	控制点坐标系
`use_image_position_constraint`	bool	true	使用图像位置约束
`fast_mode`	bool	false	快速模式（降低质量）
`min_avali_memory_size`	float	16.0	最小可用内存（GB）
`output_block_change_xml`	bool	false	输出 Block Exchange XML

📝 数据结构详解

coordinate_system 对象

{
  "type": 2,              // 1=投影, 2=地理, 3=地心
  "type_name": "Geographic",
  "label": "WGS 84",     // 坐标系名称
  "epsg_code": 4326      // EPSG 代码
}

image_meta_data 数组元素

基础格式（自动读取 EXIF）

{
  "id": 1,                           // 唯一标识符
  "path": "C:/Images/DJI_0001.JPG",  // 图像路径
  "group": "camera_1"                // 可选：相机分组
}

完整格式（自定义元数据）

{
  "id": 1,
  "path": "C:/Images/IMG_0001.JPG",
  "group": "nadir",                  // 相机组名称
  "meta_data": {                     // 自定义元数据
    "width": 6000,                   // 图像宽度（像素）
    "height": 4000,                  // 图像高度（像素）
    "pos": [114.123456, 22.123456, 100.5],  // [经度, 纬度, 高程]
    "pos_sigma": [0.05, 0.05, 0.10], // [X精度, Y精度, Z精度]（米）
    "focal_length": 24.0,            // 焦距（毫米）
    "pixel_size": 0.00391            // 像元大小（毫米）
  }
}

相机分组（group）参数

用于多相机系统，将不同相机的图像分组处理：

"image_meta_data": [
  {"id": 1, "path": "nadir/IMG_001.jpg", "group": "nadir"},
  {"id": 2, "path": "nadir/IMG_002.jpg", "group": "nadir"},
  {"id": 3, "path": "oblique_f/IMG_001.jpg", "group": "oblique_forward"},
  {"id": 4, "path": "oblique_b/IMG_001.jpg", "group": "oblique_backward"},
  {"id": 5, "path": "oblique_l/IMG_001.jpg", "group": "oblique_left"},
  {"id": 6, "path": "oblique_r/IMG_001.jpg", "group": "oblique_right"}
]

常见分组场景：

五目倾斜相机：nadir, oblique_forward, oblique_backward, oblique_left, oblique_right
双相机系统：wide_angle, telephoto
多机协同：drone_1, drone_2, drone_3
多时相：morning, afternoon

pos 和 pos_sigma 参数说明

pos 参数：

格式：[经度, 纬度, 高程] 或 [X, Y, Z]（取决于坐标系）
单位：地理坐标系为度和米，投影坐标系为米
用途：覆盖 EXIF 中的 GPS 信息或为无 GPS 图像提供位置

pos_sigma 参数：

格式：[σ_X, σ_Y, σ_Z]
单位：米
含义：各方向的位置测量标准差（1σ）
用途：在空三优化中作为权重，精度越高（σ越小）权重越大

典型值：

定位方式	σ_X/σ_Y	σ_Z	说明
RTK 固定解	0.02-0.05m	0.05-0.10m	最高精度
PPK 后处理	0.03-0.08m	0.08-0.15m	高精度
普通 GPS	2-5m	3-8m	标准精度
手动估算	0.5-2m	1-3m	低精度

📝 配置示例

最简配置

{
  "license_id": 9200,
  "working_dir": "C:/Projects/QuickStart",
  "gdal_folder": "C:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 2,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  "image_meta_data": [
    {"id": 1, "path": "C:/Images/DJI_0001.JPG"},
    {"id": 2, "path": "C:/Images/DJI_0002.JPG"},
    {"id": 3, "path": "C:/Images/DJI_0003.JPG"},
    {"id": 4, "path": "C:/Images/DJI_0004.JPG"},
    {"id": 5, "path": "C:/Images/DJI_0005.JPG"}
  ],
  "generate_obj": true,
  "generate_geotiff": true
}

多相机组配置示例

{
  "license_id": 9200,
  "working_dir": "D:/Projects/MultiCamera",
  "gdal_folder": "D:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 1,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  
  // 多相机图像分组
  "image_meta_data": [
    // 下视相机
    {"id": 1, "path": "nadir/IMG_001.jpg", "group": "nadir"},
    {"id": 2, "path": "nadir/IMG_002.jpg", "group": "nadir"},
    
    // 前视倾斜相机
    {"id": 3, "path": "forward/IMG_001.jpg", "group": "oblique_f"},
    {"id": 4, "path": "forward/IMG_002.jpg", "group": "oblique_f"},
    
    // 更多相机组...
  ],
  
  "generate_osgb": true,
  "generate_3d_tiles": true
}

自定义 POS 配置示例

{
  "license_id": 9200,
  "working_dir": "D:/Projects/PPK_Project",
  "gdal_folder": "D:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 1,
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  
  // 使用高精度 PPK 处理后的位置数据
  "image_meta_data": [
    {
      "id": 1,
      "path": "images/DJI_0001.JPG",
      "meta_data": {
        "width": 5472,
        "height": 3648,
        "pos": [114.305421, 22.596013, 120.543],  // PPK 处理后的精确位置
        "pos_sigma": [0.03, 0.03, 0.05]  // PPK 精度
      }
    },
    {
      "id": 2,
      "path": "images/DJI_0002.JPG",
      "meta_data": {
        "width": 5472,
        "height": 3648,
        "pos": [114.305512, 22.596089, 120.621],
        "pos_sigma": [0.03, 0.03, 0.05]
      }
    }
    // ... more images
  ],
  
  "generate_obj": true,
  "generate_geotiff": true
}

完整配置示例（含 GCP）

{
  "license_id": 9200,
  "working_dir": "D:/Projects/HighPrecision",
  "gdal_folder": "D:/MipMap/SDK/data",
  "input_image_type": 1,
  "resolution_level": 1,
  
  // 输入坐标系 - WGS84
  "coordinate_system": {
    "type": 2,
    "label": "WGS 84",
    "epsg_code": 4326
  },
  
  // 输出坐标系 - UTM
  "coordinate_system_3d": {
    "type": 3,
    "label": "WGS 84 / UTM zone 50N",
    "epsg_code": 32650
  },
  
  // 控制点
  "gcp_path": "D:/Projects/HighPrecision/gcps.txt",
  "gcp_coor_sys": {
    "type": 3,
    "label": "WGS 84 / UTM zone 50N",
    "epsg_code": 32650
  },
  
  // 图像列表
  "image_meta_data": [
    {"id": 1, "path": "D:/Data/flight1/IMG_001.JPG"},
    {"id": 2, "path": "D:/Data/flight1/IMG_002.JPG"},
    // ... more images
  ],
  
  // 输出所有格式
  "generate_obj": true,
  "generate_osgb": true,
  "generate_3d_tiles": true,
  "generate_las": true,
  "generate_geotiff": true,
  "generate_tile_2D": true
}

💾 输出结构

处理完成后，在工作目录中会生成以下结构：

working_dir/
├── products/              # 最终成果
│   ├── models/           # 三维模型
│   │   ├── model.obj    # OBJ 格式
│   │   ├── model.mtl    # 材质文件
│   │   ├── textures/    # 纹理图片
│   │   └── tileset.json # 3D Tiles
│   ├── pointcloud/       # 点云数据
│   │   └── cloud.las    # LAS 格式点云
│   └── orthophoto/       # 正射影像
│       ├── ortho.tif    # GeoTIFF
│       └── tiles/       # 瓦片数据
├── milestones/           # 中间结果
│   ├── at_result/       # 空三结果
│   ├── roi.json         # ROI 范围
│   └── report.html      # 处理报告
└── log/                  # 日志文件
    └── log.txt          # 详细日志

🎯 使用建议

适用场景

✅ 快速原型和测试
✅ 标准航拍项目
✅ 自动化批处理
✅ 新手入门学习

不适用场景

❌ 需要精细控制处理参数
❌ 需要使用控制点
❌ 需要检查中间结果
❌ 特殊相机或传感器

🔧 高级技巧

1. 批量处理多个项目

import json
import subprocess
from pathlib import Path

def batch_process(project_list):
    for project in project_list:
        # 创建配置
        config = {
            "license_id": 9200,
            "working_dir": f"./output/{project['name']}",
            "gdal_folder": "./data",
            "coordinate_system": {"type": 2, "epsg_code": 4326},
            "image_meta_data": [
                {"id": i+1, "path": str(img)} 
                for i, img in enumerate(project['images'])
            ],
            "input_image_type": 1,
            "resolution_level": 2,
            "generate_obj": True,
            "generate_geotiff": True
        }
        
        # 保存配置
        config_path = f"./config_{project['name']}.json"
        with open(config_path, 'w') as f:
            json.dump(config, f, indent=2)
        
        # 执行处理
        subprocess.run([
            "reconstruct_full_engine.exe",
            "-reconstruct_type", "0",
            "-task_json", config_path
        ])

2. 自动参数优化

def optimize_parameters(image_count, available_memory_gb):
    """根据项目规模自动选择参数"""
    
    # 分辨率等级
    if image_count < 100:
        resolution_level = 1  # 高精度
    elif image_count < 500:
        resolution_level = 2  # 中精度
    else:
        resolution_level = 3  # 低精度（大项目）
    
    # 输出格式
    if available_memory_gb > 32:
        formats = {
            "generate_obj": True,
            "generate_osgb": True,
            "generate_3d_tiles": True,
            "generate_las": True
        }
    else:
        formats = {
            "generate_obj": True,
            "generate_las": False
        }
    
    return resolution_level, formats

3. 进度监控

import re
import time
from threading import Thread

def monitor_progress(log_file):
    """监控处理进度"""
    
    def read_progress():
        with open(log_file, 'r') as f:
            f.seek(0, 2)  # 移到文件末尾
            while True:
                line = f.readline()
                if line:
                    match = re.search(r'\[PROGRESS\] (\d+)%', line)
                    if match:
                        progress = int(match.group(1))
                        print(f"\r进度: {'█' * (progress//2)}{'░' * (50-progress//2)} {progress}%", end='')
                time.sleep(0.1)
    
    thread = Thread(target=read_progress, daemon=True)
    thread.start()

❓ 常见问题

Q: 为什么有些图像没有被使用？

A: ReconstructFull 会自动过滤质量差的图像：

模糊的图像
没有 GPS 信息的图像
重复或相似度过高的图像

您可以在日志中查看被过滤的图像及原因。

Q: 如何处理没有 GPS 的图像？

A: 对于没有 GPS 信息的图像，您需要：

使用 ReconstructAT 接口（支持无 GPS 处理）
或者手动添加 GPS 信息到 EXIF
或者使用外部 POS 文件

Q: 处理大型项目内存不足？

A: 解决方案：

降低 resolution_level 到 2 或 3
减少同时生成的输出格式
使用分块处理（需要使用其他接口）

🔗 相关链接

坐标系统详解
图像元数据说明
输出格式对比
ReconstructAT 接口（更多控制）

ReconstructFull 是开始使用 MipMapEngine SDK 的最佳选择。随着经验增长，您可以探索其他接口以获得更多控制。

🎯 接口特点​

📋 参数详解​

必需参数​

可选参数 - 输出控制​

可选参数 - 坐标系​

可选参数 - 高级功能​

📝 数据结构详解​

coordinate_system 对象​

image_meta_data 数组元素​

基础格式（自动读取 EXIF）​

完整格式（自定义元数据）​

相机分组（group）参数​

pos 和 pos_sigma 参数说明​

📝 配置示例​

最简配置​

多相机组配置示例​

自定义 POS 配置示例​

完整配置示例（含 GCP）​

💾 输出结构​

🎯 使用建议​

适用场景​

不适用场景​

🔧 高级技巧​

1. 批量处理多个项目​

2. 自动参数优化​

3. 进度监控​

❓ 常见问题​

🔗 相关链接​