实时重建

0 说明

实时重建支持无人机正射航线采集的图像，重叠度满足航线70、旁向70以上。

推荐使用大疆测绘无人机 M3E/M4E。

🚁 无人机正射航线示意图

正射航线规划要点

航线间距：根据相机视场角和飞行高度计算，确保旁向重叠度
拍摄间隔：根据飞行速度和航向重叠度要求设置
飞行高度：影响地面分辨率和拍摄范围
天气条件：选择光照均匀、无风或微风天气

1 概述

实时重建以一个grpc服务端程序提供：realtime_service，启动它即启动了实时重建服务，我们将提供一个proto文件来供开发者开发客户端程序，客户端程序完成以下操作。

（1）Initialize，初始化实时重建服务

（2）AddFrame，添加图像帧

（3）EndTask，结束本次实时重建任务

实时重建服务基于 gRPC 通信协议实现，建议开发者具备 gRPC 客户端开发经验，以便顺利集成和调用相关接口。

下面是实时重建服务的基本流程示意图：

2 Windows系统下提供本地开发包

请找MipMap索要本地开发包。

3 Linux系统下提供docker部署

部署前的环境准备工作请参考：Linux部署指南下载镜像前面章节。

下载镜像

docker pull registry.mipmap3d.com/docker/mipmap/realtime:v1.0-ubuntu22.04

从镜像启动容器

# 启动 Docker 容器
docker run -it --rm \
  -v /tmp:/tmp \             # 挂载宿主机目录 /tmp 到容器[许可访问需要，必须执行且按此命令挂载]
  -v /mnt:/mnt \             # 挂载宿主机目录到容器[示例，按实际情况调整]
  --cpus 8 \                 # 限制容器使用 8 个 CPU
  --gpus all \               # 使用所有 GPU（需要 NVIDIA Container Toolkit）
   --name mipmap_rt \            # 容器名称为 mipmap_rt
  registry.mipmap3d.com/docker/mipmap/realtime:v1.0-ubuntu22.04 \
  /bin/bash                  # 进入容器后启动 bash

重要说明：

/mnt 目录映射：mnt是示例，实际调用者想挂载那个目录灵活执行
/tmp 目录映射：许可访问需要，必须挂载
--cpus 8：限制容器使用8个CPU核心
--gpus all：启用所有GPU支持

运行实时重建服务

通过在命令行启动realtime_service来启动实时重建服务，启动参数解释如下：

字段名	类型	是否必需	说明
`port_number`	number	否	服务端端口号，默认50051
`task_type`	string	否	重建类型，2D-通过GPS和云台角拼接，只执行二维实时快拼；3D-通过SLAM拼接，支持二维实时快拼和三维实时网格，默认3D

# 在容器内运行实时重建服务
./mipmap_engine/realtime_service -port_number 50051(可选) -task_type 3D(可选)

4 参数释义

实时重建需要用一个json来初始化，json的内容释义表如下：

字段名	类型	是否必需	说明
`working_dir`	string	是	工作目录，保存中间文件及最终成果文件。UTF-8编码
`gdal_folder`	string	是	gdal数据路径，MipMap提供的gdal_data目录（可移动），必须是英文目录
`do_realtime_2d_map`	bool	否	是否计算实时二维地图，即二维正射地图
`do_realtime_3d_map`	bool	否	是否计算实时三维地图，即三维网格（暂windows可用）
`target_max_size`	int	否	图像帧缩放后的最长边像素数，实时任务推荐将图像帧缩放，该值控制缩放后的图像大小，越大实时重建效果越好，单帧耗时越长。为0时，调用者需在AddFrame前自行缩放图像并传入缩放后的图像metadata字符串（详情见下文），建议值：2048/1920/1280
`tile_2d_save_type`	int	否	默认0, 实时二维成果格式，0：webp 1：png
`mesh_3d_save_type`	int	否	默认0, 实时三维成果格式，0：ply 1：3dtiles
`rt_mesh_reso_scale_to_gsd`	int	否	实时三维生成的网格分辨率 = rt_mesh_reso_scale_to_gsd*图像gsd，该值越小，网格分辨率越高，颜色越清晰，但效率也会相应降低，默认6

服务端程序 realtime_service

realtime_service是一个gRPC实时重建服务端程序，客户端可以通过该服务完成以下任务：

（1）初始化服务，启动实时任务。

（2）逐帧传递图像路径，进行实时SLAM定位和二维地图|三维网格计算。

（3）执行后处理并自动结束任务。

（4）主动结束任务。

以下是客户端使用该服务端程序的详细说明：

服务端监听端口号默认50051，也可通过启动参数自由配置端口号

API 接口说明

服务定义了以下 gRPC 接口：

Initialize

功能：初始化服务端并启动实时任务，客户端需在调用其他接口之前调用此接口，传递任务配置。

请求格式 (InitRequest)

字段名	类型	说明
`task_json`	string	task json内容字符串

响应格式 (InitResponse)

字段名	类型	说明
`state`	int32	初始化状态（0表示成功，其他值表示失败）码

AddFrame

功能：逐帧传递图像路径进行实时处理。客户端通过该接口持续添加图片帧，服务端实时运算。

请求格式 (AddFrameRequest)

字段名	类型	说明
`image_path`	string	图像的文件路径，utf-8编码
`image_meta_data`	string	图像的元数据metadata json内容字符串，设置为空字符串时，实时服务将自动内部解析图像元数据（调用方需确保图像文件头的EXIF信息写入了相机焦距以及GPS位置信息）

图像元数据释义（Image Metadata）

字段名	类型	是否必需	说明
`width`	int	是	图像宽度（像素）
`height`	int	是	图像高度（像素）
`camera_id`	int	否	对应相机ID
`focal_length_in_35mm`	double	否	35mm等效焦距（毫米），pre_calib_param未设置时必需设置此值
`pos`	array[3]	是	位置 [经度/X, 纬度/Y, 高程/Z]
`pos_sigma`	array[3]	否	位置精度（米），RTK:[0.03,0.03,0.06], 普通GPS: [2.0,2.0,5.0]
`orientation`	array[9]	否	旋转矩阵（9个值，行优先，单位向量，若有外参可填写，世界坐标系到相机坐标系的旋转矩阵，笛卡尔坐标系）
`position_constant`	bool	否	是否固定位置（true/false）
`relative_altitude`	double	否	相对飞行高度（米）
`pre_calib_param`	array	否	预标定参数（如有，填写相机内参）
`dewarp_flag`	bool	否	畸变校正标志（如来自DJI XMP数据，true表示已去畸变）

示例：

{
    "width": 5280,
    "height": 3956,
    "camera_id": 1,
    "pos": [
        121.11150580555555,
        31.788278305555558,
        21.226
    ],
    "pos_sigma": [
        0.03,
        0.03,
        0.06
    ],
    "orientation": [
        -0.3583679497241974,
        0.9335803985595703,
        0,
        0.7533622980117798,
        0.2891887128353119,
        -0.5906056761741638,
        -0.5513778924942017,
        -0.21165414154529572,
        -0.8069602847099304
    ],
    "relative_altitude": 6.012,
    "focal_length_in_35mm": 24,
    "pre_calib_param": [
        3713.29,
        3713.29,
        2647.02,
        1969.28,
        -0.11257524,
        0.01487443,
        -0.00008572,
        1e-7,
        -0.02706411
    ],
    "dewarp_flag": false
}

响应格式 (AddFrameResponse)

字段名	类型	说明
`update_json`	string	存储当前帧更新量的json字符串，含义见下

update_json的字段含义：

字段名	类型	说明
`tile2d_folder`	string	二维正射快拼图的瓦片成果文件夹路径
`updated_2d_tiles`	array	当前帧更新的瓦片路径列表，相对路径，以`tile2d_folder`为根目录
`tile3d_folder`	string	三维网格成果的瓦片成果文件夹路径
`updated_3d_tiles`	array	当前帧更新的网格模型路径列表，相对路径，以`tile3d_folder`为根目录

二维实时成果：

工作目录的2D/dom_tiles目录存储Web Mercator（EPSG:3857）坐标系的正射图瓦片格式，用第三方GIS库来读取瓦片显示。客户端可以根据返回的update_2d_tiles集合增量更新渲染瓦片数据，提高渲染效率。

三维实时成果：

工作目录的3D/mesh存储三维网格模型，三维模型存储为二进制格式（ply或3dtiles），且会根据地理范围分块，客户端可以根据返回的update_3d_tiles集合增量更新渲染块数据，提高渲染效率。

稳定性说明

为了保证稳定性，前N帧（N≈10）一般不会出定位和网格成果，到定位达到稳定状态后，定位和成果开始更新到磁盘。

EndTask

功能：结束当前实时任务。

请求格式 (EndTaskRequest)

字段名	类型	描述
无字段	无	结束任务请求

响应格式 (EndTaskResponse)

字段名	类型	描述
`state`	int32	任务结束状态（0 表示成功，其他值表示失败）

5 客户端开发指南

前期准备

安装 gRPC 与 Protocol Buffers

请确保已在开发环境中正确安装 gRPC 及 Protocol Buffers（protoc 编译器）。推荐参考官方文档完成安装，确保版本兼容。
生成客户端代码

使用MipMap提供的 .proto 文件，通过 protoc 工具生成对应语言的客户端代码。具体命令及参数请参考 gRPC 官方文档或项目内说明。
准备任务配置 JSON 文件

实时重建服务初始化时需提供任务配置 JSON 文件。请确保该文件内容完整、路径正确，且服务端具备访问权限。

路径访问

请确保客户端配置文件中涉及的图像路径为服务端可直接访问的本地或网络路径，避免因路径不可达导致任务失败。

实时重建服务标准使用流程

启动服务端（realtime_service）

启动服务端程序，保持监听状态。可通过 -port_number 参数指定监听端口，例如：
```
realtime_service -port_number 50051
```
支持同时启动多个服务端实例，通过不同端口号区分。
启动客户端并建立连接

启动客户端程序，指定服务端端口号，建立 gRPC 通信连接。按照以下顺序调用接口：
- Initialize：初始化实时重建任务
- AddFrame：逐帧添加图像数据
- EndTask：结束当前实时任务
任务管理与多次调用

服务端进程可持续运行，支持多次任务。客户端每次调用 EndTask 结束任务后自动退出。若需发起新任务，可重新启动客户端并与服务端建立新连接，重复上述流程。

客户端程序realtime_client

客户端程序realtime_client提供给对grpc调用不熟悉且使用方式单一的用户（下面称为调用者），不需要编写客户端代码，启动realtime_client可执行程序和服务端程序即可。

步骤：

（1）初始化的json参数需要增加图像目录和实时计算的目标图像大小，请确保目录有效

字段名	类型	说明
`image_dir`	string	图像文件夹目录，utf-8编码
`target_max_size`	int	图像帧缩放后的最长边像素数，实时任务推荐将图像帧缩放，该值控制缩放后的图像大小，值越大实时重建效果越好，单帧耗时越长。为0时，调用者在外部缩放并传入图像metadata字符串（详情见下文）

（2）控制台命令启动realtime_service，启动的可选参数是端口号，不同的端口号代表不同的服务端口，不传参数则默认使用端口50051。

realtime_service -port_number 50051

（3）控制台命令启动realtime_client，启动的可选参数是端口号，不同的端口号代表不同的服务端口，不传参数则默认使用端口50051。

realtime_client -port_number 50051

client启动后，控制台要求输入参数json的路径来初始化服务，请调用者往控制台输入参数json文件的路径（不带双引号），输入后，服务端开始运行实时重建并打印日志

（4）调用者定时访问二维实时成果和三维实时成果文件，刷新渲染

（5）实时任务启动后客户端将等待调用者输入end指令，输入end后服务端会结束帧添加并结束本次实时任务。

目录​

0 说明​

🚁 无人机正射航线示意图​

1 概述​

2 Windows系统下提供本地开发包​

3 Linux系统下提供docker部署​

下载镜像​

从镜像启动容器​

运行实时重建服务​

4 参数释义​

服务端程序 realtime_service​

API 接口说明​

Initialize​

AddFrame​

图像元数据释义（Image Metadata）​

二维实时成果：​

三维实时成果：​

EndTask​

5 客户端开发指南​

前期准备​

实时重建服务标准使用流程​

客户端程序realtime_client​

目录