QGroundControl 离线地图功能完全指南:瓦片缓存、离线集合管理与实战操作
QGroundControl 离线地图功能完全指南:瓦片缓存、离线集合管理与实战操作
本篇技术指南围绕 QGroundControl(QGC)地面站软件的**离线地图(Offline Maps)**功能展开,系统讲解其核心概念——离线地图集合(Tile Set)、缓存瓦片的工作机制、创建与管理离线集合的完整操作流程,并结合仓库源码解析缩放级别、瓦片数量估算、下载任务调度等底层实现。读完本文,你将能够在无网络环境下为不同作业区域规划并管理多套离线地图缓存,并理解 QGC 地图引擎的缓存与任务调度原理。
离线地图:为无网络作业场景准备的地图瓦片缓存
QGroundControl 的离线地图功能允许用户预先将地图瓦片(Map Tiles)缓存到本地磁盘,以便在飞行器作业现场没有互联网连接时,依然可以查看完整的地图底图。这一能力对偏远地区航测、应急巡检等场景尤为重要——任务规划、实时飞行监控都不再依赖网络信号。
其核心设计思路是 "离线集合"(Offline Tile Set):你可以创建多个离线集合,每个集合针对不同的地理位置、使用不同的地图类型,彼此独立管理。从源码结构看,每个集合对应一个 QGCCachedTileSet 实例(QGCCachedTileSet.h),记录着该集合的名称、地图类型、经纬度边界、最小/最大缩放级别以及已下载瓦片的统计信息。
QGC 的地图功能由 QtLocationPlugin 模块承载,其插件声明文件 qgc_maps_plugin.json 明确列出了 OnlineMappingFeature(在线地图)与 OfflineMappingFeature(离线地图)两项能力,说明离线缓存是 QGC 地图引擎的内建功能,而非第三方扩展。
入口与界面总览
离线地图管理界面位于 设置(Settings)→ 地图设置(Maps) 页面中,对应 UI 定义见 Maps.SettingsUI.json,其中 "Offline Maps" 分节的关键词为 offline、download、cache、tile set,方便用户在设置页内快速检索。
从 OfflineMapSettings.qml 的实现可以看到,该页面提供以下核心操作:
- Add New Set:创建新的离线地图集合;
- Import Map Tiles / Export Map Tiles:导入/导出瓦片集合(可通过 QGCOptions.h 中的
showOfflineMapImport、showOfflineMapExport选项控制可见性,默认均为true); - 每个集合以一行条目展示,包含名称、下载状态与瓦片数量,并带有一个"Edit"按钮(见 OfflineMapInfo.qml)。列表右侧的圆点指示器在集合下载完成时显示绿色(
#31f55b),未完成时显示红色(#fc5656)。
导入或导出进行时,页面底部还会显示实时的进度条(ProgressBar),进度数据来自 QGCMapEngineManager.actionProgress。
添加新离线集合:完整操作步骤
点击 "Add"(添加新集合)按钮后,会打开离线地图编辑器(对应 OfflineMapEditor.qml),其界面布局如下:
参考官方中文文档 offline_maps.md 与源码交互逻辑,创建流程分为四步:
-
命名集合:在 "Name" 输入框中为集合指定名称。若名称与已有集合重复,界面会提示 "Tile set with this name already exists" 并阻止下载(QML 中通过
QGroundControl.mapEngineManager.findName()查重)。默认名称由mapEngineManager.getUniqueName()自动生成,保证唯一。 -
选择地图类型:在 "Map type" 下拉框中指定要缓存的地图类型(如卫星图、街景图、混合图等)。可选项来自
mapEngineManager.mapList,实际生效的地图类型为「地图源(mapProvider)+ 地图类型(mapType)」的组合(见OfflineMapEditor.qml中的mapType属性)。若勾选 "Fetch elevation data"(获取高程数据),QGC 还会额外下载对应区域的高程瓦片,用于离线地形分析与地形告警。 -
移动地图到目标位置:在地图上拖动、缩放,把视野中心对准你要缓存的地理区域。编辑器以
QGroundControl.flightMapPosition/flightMapZoom为初始中心(resetMapToDefaults()),并监听地图的centerChanged、zoomLevelChanged、widthChanged、heightChanged事件,实时通过updateForCurrentView()把当前可视范围的经纬度边界上报给地图引擎,用于估算瓦片数量。 -
设置最小/最大缩放级别并下载:拖动 "Min/Max Zoom Levels" 区域中的两个滑块确定缩放范围,界面会同步显示 Tile Count(瓦片总数) 与 Est Size(估算体积),确认无误后点击 Download 开始缓存。
左侧(或编辑器左下区域)的两个小地图分别以当前设置的最小、最大缩放级别渲染同一区域,即文档中提到的 "缩放级别预览",让你直观看到不同缩放级别下的地图细节差异。点击预览区域可临时隐藏它们("Show zoom previews" 按钮可重新显示)。
缩放级别的取值范围
缩放级别的上下限在 OfflineMapEditor.qml 中定义为常量:minZoomLevel: 1、maxZoomLevel: 20,两个滑块均以步长 1 在 [1, 20] 之间取值,且二者互相约束——最小缩放级别不能超过最大缩放级别(反之亦然)。
与缩放相关的三个设置项定义在 OfflineMaps.SettingsGroup.json,对应 C++ 侧的 OfflineMapsSettings.h:
| 设置项 | 类型 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|
minZoomLevelDownload |
Uint32 | 13 | 1–20 | 下载的最小缩放级别 |
maxZoomLevelDownload |
Uint32 | 19 | 1–20 | 下载的最大缩放级别 |
maxTilesForDownload |
Uint32 | 100000 | — | 单次下载允许的最大瓦片数上限 |
其中 maxTilesForDownload 是防止误操作撑爆磁盘的保护阈值:当待下载瓦片总数超过该值时,界面会显示红色的 "Too many tiles" 警告,并禁用 Download 按钮(见 OfflineMapEditor.qml 中的 _tooManyTiles 判断)。合理做法是先选择较小的缩放范围估算瓦片数,再逐步扩大。
瓦片数量与体积的估算原理
点击 Download 之前显示的瓦片数与体积并非猜测值,而是由地图引擎按真实瓦片网格计算得出。在 QGCMapEngineManager.cc 的 updateForCurrentView() 中,QGC 对 minZoom 到 maxZoom 的每一级缩放调用 UrlFactory::getTileCount(),累加各级瓦片数量与体积;若开启了高程获取,还会叠加高程数据源(elevationMapProvider)的瓦片估算,最终通过 tileCountStr() / tileSizeStr() 呈现给用户。这也解释了为何同一个区域,缩放级别每提高一级,瓦片数量都会成倍增长——下载体积随缩放级别急剧膨胀。
集合的信息查看与编辑
点击集合条目旁的 "Edit" 按钮(或直接点击条目)会进入该集合的详情视图(showInfo()),展示以下信息:
- 集合名称与地图类型:对于普通集合显示
(地图类型),对于系统级集合显示 "System Wide Tile Cache"; - 缩放级别范围:
minZoom - maxZoom; - Total(总瓦片数/总估算体积):该区域理论上覆盖的全部瓦片;
- Unique(去重后瓦片数/体积):不同缩放级别之间存在大量重复瓦片,该数值为去重后的实际数据;
- Downloaded(已下载瓦片数/体积):当前实际落盘的瓦片;
- Error Count:下载失败(如网络中断、瓦片源返回错误)的瓦片数量。
以上统计字段均来自 QGCCachedTileSet 的属性定义(见 QGCCachedTileSet.h),并由地图引擎在下载过程中实时刷新。
详情视图还提供以下管理操作:
- Resume Download:继续未完成的下载(对应
resumeDownloadTask(),它会先将未完成瓦片状态重置为待下载,再重新创建下载任务); - Cancel Download:取消进行中的下载(对应
cancelDownloadTask()); - Delete:删除集合及其全部瓦片。删除前会弹出确认对话框,若删除的是默认集合(System Wide Tile Cache),QGC 会明确警告"这将删除包括你自己创建的所有集合在内的全部瓦片";
- 重命名:在名称输入框修改后点击 Ok,通过
mapEngineManager.renameTileSet()生效。
关于"默认集合"
源码中存在一个特殊的 defaultSet 集合(系统级瓦片缓存),用于存放 QGC 在日常使用中产生的临时瓦片。它的下载状态显示逻辑与普通集合不同(直接显示已占用体积,见 QGCCachedTileSet.cpp),且 complete() 判定对默认集合恒为真(_defaultSet || _totalTileCount <= _savedTileCount)。普通集合在任务执行中若中途退出,QGC 会保留进度,下次进入可随时继续下载。
导入与导出离线集合
OfflineMapSettings.qml 提供了集合的导入/导出能力,便于在多台设备间迁移离线地图:
- 导出(Export):弹出对话框,勾选要导出的集合后保存为文件(文件后缀由
appSettings.tilesetFileExtension决定,默认过滤器为Tile Sets (*.<扩展名>)); - 导入(Import):提供两种模式——"Append to existing sets"(追加到已有集合)与 "Replace existing sets"(替换已有集合),由
mapEngineManager.importReplace控制; - 从 QGCMapEngineManager.h 可以看到,底层还支持
importArchive()直接导入.zip、.tar.gz等归档文件(先解压再导入),方便分发打包好的离线地图数据。
底层机制:下载任务的调度与断点续传
离线瓦片下载并非简单的串行拉取,而是由 QGC 地图引擎(QGCMapEngine)以任务队列的方式异步调度的:
- 用户点击 Download 后,
QGCMapEngineManager::startDownload()(QGCMapEngineManager.cc)会把当前视口记录的经纬度边界、缩放级别等参数固化为一个QGCCachedTileSet,并通过QGCCreateTileSetTask任务写入数据库;若开启高程获取,还会额外创建一个名为"<集合名> Elevation"的高程集合; - 下载执行时,
QGCCachedTileSet::createDownloadTask()以每批 256 个瓦片(常量kTileBatchSize,见 QGCCachedTileSet.h)为单位,通过QGCGetTileDownloadListTask向引擎请求待下载瓦片清单,再逐批通过QNetworkAccessManager拉取瓦片数据; - 每个瓦片下载完成后立即落盘并更新统计;出现错误的瓦片计入
errorCount,可在下次 Resume 时重试; - 下载可随时暂停(Cancel)与恢复(Resume),进度保存在本地数据库中,因此断点续传是离线地图的基本能力;
- 下载过程完全异步,不阻塞地图 UI,进度通过
QGCMapEngineManager的信号机制(如tileCountChanged、tileSizeChanged)实时反馈到界面。
实用建议与注意事项
- 按作业区域分集合:每个集合对应一个位置,建议按"机场周边""航线走廊""目标测区"等维度拆分,避免单个集合过大导致下载时间过长、占用过多磁盘;
- 先估算再下载:充分利用 Download 前显示的 Tile Count 与 Est Size 估算值,并结合 10 万瓦片上限(
maxTilesForDownload)控制单次下载规模; - 缩放级别取舍:对多数地面站监控场景,13–19 级已足够;若磁盘紧张,可适当收窄最大缩放级别,因为高缩放级别带来的瓦片增量非常可观;
- 利用高程数据:在山区作业时建议勾选 "Fetch elevation data",缓存的高程瓦片可为离线状态下的地形感知与告警提供数据支撑;
- 设备间迁移:通过导出/导入(含归档文件导入)可快速在笔记本与地面终端之间复制离线地图,减少重复下载;
- 下载中断处理:网络波动导致的失败瓦片会记录在 Error Count 中,重新进入集合详情点击 Resume Download 即可续传,无需重建集合。
小结
QGroundControl 的离线地图功能以"多集合、多位置、可续传"的设计,为无人机在无网络环境下的任务规划与飞行监控提供了可靠的地图保障。从用户视角看,只需"命名 → 定位 → 定级 → 下载"四步即可完成一套离线缓存;从源码视角看,QGCMapEngineManager 负责集合生命周期与任务调度,QGCCachedTileSet 负责单集合的数据统计与下载执行,二者配合实现了高效的瓦片缓存管理。掌握本指南所述的操作流程与参数含义后,你即可在真实作业中灵活规划离线地图资源。

