企业官网建设流程全解析

• 无人机
• 智能硬件

本文基于 QGroundControl 用户指南中的 What's New 发布说明（docs/ko/qgc-user-guide/getting_started/whats_new.md），系统梳理自上一稳定版 V5.1 以来面向用户的三项核心变化：实验性的 GeoMap 3D 地图引擎、Fly View 中可设置高度的 ROI（感兴趣区域）点击操作，以及 Custom Builds 的 JSON 驱动自定义设置页。读完后，你将掌握这三项新特性的启用方式、操作细节与底层实现原理，能够在自己的 QGroundControl 构建中直接使用或扩展它们。

总览：这份发布说明覆盖了什么

QGroundControl 的 What's New 页面用于汇总自上一稳定版（V5.1）以来、面向普通用户可见的功能变化，属于"增量发布说明"而非完整用户手册。V5.1 之后的这份说明聚焦于三件事：

1. GeoMap 引擎（技术预览）——一个全新的实验性地图引擎，把 2D/3D 地图渲染统一起来；
2. Fly View 的 "ROI at location" 高度设置——地图点击操作的一次小但实用的增强；
3. Custom Builds 的自定义设置页——针对二次开发者的 JSON 驱动设置页扩展能力。

三个主题分别对应不同的用户群体：前两项面向最终使用者，第三项面向基于 QGC 做定制构建的开发者。下文按此顺序逐一展开，并在每个主题中补充对应源码与配置文件的实现细节。

GeoMap 引擎（技术预览）：让地图"站起来"的 3D 新地图引擎

它是什么

GeoMap 引擎是 QGroundControl 的一套新地图引擎，核心能力是渲染一张无缝的 2D/3D 地图：你选择的地图影像（卫星图/街道图）被"披挂"在真实地形高程之上，并配备 Google Earth 风格的相机操控。启用后，它取代 Fly View 中的地图，把以下对象以真 3D形式呈现：

• 无人机（车辆）图标；
• 规划的任务（含航点标记、连接路径、以及显示每个航点相对地形高度的"垂线"）；
• 已飞行的航迹；
• 起飞地点；
• 地面站位置。

文档明确标注这是实验性技术预览（Tech Preview），仍在积极开发中，存在功能缺失和粗糙之处，官方甚至提示"现在报告问题还为时过早"。它的长期目标是最终取代 QGroundControl 中所有地图使用场景（包括 Plan 视图），提供全应用一致的 2D/3D 地图体验。

注意：依据当前文档，地图点击操作（goto、orbit、ROI 等）目前仅在 2D 模式下可用，3D 模式暂时只可查看；而解锁、起飞、引导操作、仪表等其他 Fly View 控件在两种模式下均正常工作。

如何启用与重启注意事项

GeoMap 引擎默认禁用。启用步骤：

1. 打开Application Settings（应用设置）> Fly View；
2. 打开Use GeoMap engine (preview)开关；
3. 重启 QGroundControl。

重启后，Fly View 的地图便由 GeoMap 引擎渲染。

从源码可以印证"必须重启"并非偶然设计。在 src/FlyView/FlyView.qml 中，地图引擎的选择通过一个Loader完成，加载哪个引擎取决于QGroundControl.settingsManager.flyViewSettings.useGeoMapEngine.rawValue，且该选择在启动时快照（qgcRebootRequired）。源码注释（issue #14901）明确指出：如果运行中热切换引擎，会遗留跨地图的过期状态（引导控制器注册、ROI 坐标等），因此刻意要求重启后生效。

相机视角控制

GeoMap 引擎的相机手势遵循 Google Earth 语义：手势开始时光标下的地面点在整个手势过程中保持钉在光标下方，保证操控的直观性。

鼠标操作：

触控操作：

键盘辅助（适用于单键鼠标和触控板）：

• Shift + 左键拖拽：环绕（等价于右键/中键拖拽）；
• Ctrl + 左键拖拽：第一人称视角（相机原地不动、视野旋转，如同转头看向目标方向）；macOS 上Ctrl与Cmd均可。

2D/3D 模式切换：

• 右上角3D/2D按钮用于切换模式，切换时相机会做倾角动画，地形随之"升起/压平"；2D 模式如同传统俯视地图（倾角锁定）；
• 罗盘按钮随当前航向旋转，点击它可动画回到正北朝上。

影像与地形数据来源

GeoMap 引擎的地表影像直接复用你在Application Settings > Maps中选择的地图影像；而地形高程来自 Mapzen/Tilezen Terrain Tiles 数据集，该数据集融合了多国/多机构的高程数据源，包括（按文档列出的数据归属）：

• ArcticDEM 地形数据（源自 DigitalGlobe 影像，由美国国家科学基金会资助）；
• 澳大利亚地形数据 © Geoscience Australia；
• 奥地利地形数据 © offene Daten Österreichs（DGM）；
• 加拿大地形数据按加拿大开放政府许可提供；
• 欧洲地形数据基于 Copernicus 计划与欧盟资金支持（EU-DEM 图层）；
• 全球 ETOPO1 地形数据（美国 NOAA）；
• 墨西哥地形数据（INEGI，2016 年大陆地貌）；
• 新西兰地形数据（2011 Crown copyright，Land Information New Zealand）；
• 挪威地形数据 © Kartverket；
• 英国地形数据 © Environment Agency；
• 美国 3DEP（原 NED）及全球 GMTED2010、SRTM 地形数据（美国地质调查局）。

详细说明与启用指引参见 docs/ko/qgc-user-guide/fly_view/geoview.md。

源码层面：引擎切换机制

在代码层面，GeoMap 引擎与原有 QtLocation 引擎是互斥共存的关系：Fly View 中只同时实例化其中一个。相关实现集中在 src/FlyView/FlyView.qml 的mapEngineLoader中——它注册了qtLocationEngineComponent与geoMapEngineComponent两个组件，并依据设置快照选择。地图点击操作的引导弹窗则通过 src/FlyView/FlyViewMapClickDropPanel.qml 实现，该弹窗被 QtLocation FlyViewMap 与 GeoMap 引擎适配器（src/FlyView/FlyViewGeoMapAdapter.qml）共享。

Fly View 新功能：点击地图设置 ROI 高度

功能说明

Fly View 的地图点击菜单中有一项ROI at location（在位置处设置感兴趣区域），用于让相机/传感器对准地图上点击的某个点。V5.1 之后的改进是：该操作现在支持设置 ROI 的高度。

• 点击地图并选择 ROI 后，会先弹出一个高度滑块；
• 滑块单位为米（相对起飞点），默认值为0，即默认对准地面；
• 通过滑块可以给 ROI 一个高于地面的高度，让云台/相机对准高处目标（如楼顶、山坡上的物体），而不是只能对准地面点。

操作流程

1. 在 Fly View 地图上点击目标位置（2D 模式下）；
2. 在弹出的地图点击操作面板中选择ROI at location（对应按钮的 objectName 为mapClickROI，见 src/FlyView/FlyViewMapClickDropPanel.qml）；
3. 在确认前通过高度滑块设置 ROI 高度（米，相对起飞点，默认 0 = 地面）；
4. 确认后，地面站向飞控下发 ROI 指令，云台/相机转向该点。

MAVLink 命令对应与源码实现

ROI 功能在 MAVLink 协议层对应一组MAV_CMD_DO_SET_ROI系列命令，QGroundControl 的命令元数据定义在 src/MissionManager/MavCmdInfoCommon.json 中，包括：

• MAV_CMD_DO_SET_ROI_LOCATION（id 195）：按坐标设置相机感兴趣区域；
• MAV_CMD_DO_SET_ROI_WPNEXT_OFFSET（id 196）：对准下一航点并带偏移；
• MAV_CMD_DO_SET_ROI_NONE（id 197）：取消 ROI；
• MAV_CMD_DO_SET_ROI（id 201）：通用 ROI 命令，其 param1 为模式枚举（None / Next waypoint / Mission item / Location / ROI item）。

在车辆端，引导模式 ROI 的入口是 src/Vehicle/Vehicle.cc 中的Vehicle::guidedModeROI(const QGeoCoordinate& centerCoord, double relativeAltitudeMeters)：

• 坐标无效时直接返回失败；
• 若飞控不支持 ROI 模式（roiMode()为假），会弹出提示"ROI mode not supported by Vehicle."并拒绝执行；
• 高度参数若非有限数（qIsFinite检查失败）则回退为 0；
• 最终将相对高度传给固件插件（_firmwarePlugin->guidedModeROI）执行，并在成功时发出roiCoordChanged信号，供地图 UI 同步。

取消 ROI 则走Vehicle::stopGuidedModeROI()，通过MAV_CMD_DO_SET_ROI_NONE命令实现。由此可见，新增的"高度滑块"本质上就是为guidedModeROI的relativeAltitudeMeters参数提供用户输入入口。

Custom Builds：JSON 驱动的自定义设置页面

背景：设置页的 JSON 生成机制

QGroundControl 的应用设置页并非手写 QML，而是由 JSON 定义在构建期自动生成。其运行时链路为：

1. Fact 元数据定义在src/Settings/*.SettingsGroup.json；
2. 设置 Fact 访问器在src/Settings/*Settings.h/.cc中；
3. 设置 UI 页面定义在src/AppSettings/pages/*.SettingsUI.json；
4. 页面清单在src/AppSettings/pages/SettingsPages.json；
5. Python 生成器位于tools/generators/settings_qml；
6. 生成的 QML 由src/QmlControls/AppSettings.qml加载。

生成动作在src/AppSettings/CMakeLists.txt中接线：构建时执行python -m tools.generators.settings_qml.generate_pages --output-dir <build>/generated，输入为上述 JSON 文件，输出为各页面 QML 与SettingsPagesModel.qml。当*.SettingsUI.json中省略control字段时，生成器会根据 Fact 类型自动挑选控件：bool→ 复选框，枚举型 → 下拉框，其他类型 → 文本框。

自定义构建如何叠加设置页

What's New 中宣布的新能力是：Custom Builds 现在可以在 Application Settings 中新增自己的页面，并替换、重排或移除内置页面——同样走 JSON 驱动，无需手写设置 QML。完整开发文档见 docs/ko/qgc-dev-guide/views/settings_generation.md 的 "Custom Build Settings Pages" 一节。机制分为三层：

1. 页面清单叠加（Page List Overlay）

在自定义目录（QGC_CUSTOM_DIR）下创建<custom>/src/AppSettings/pages/SettingsPages.json，其条目在配置期与内置页面清单合并：

• 条目name与内置页面同名时，原地替换该页面；
• 新条目支持insertAfter/insertBefore（引用内置页面的name），否则追加到末尾；
• { "remove": "<name>" }用于移除内置页面。

2. 页面定义（Page Definitions）

将*.SettingsUI.json文件放入同一自定义 pages 目录；文件名与内置定义相同的文件会**遮蔽（shadow）**内置定义。

3. 自定义设置组（Custom Settings Groups）

若要引用内置 QGC 中不存在的 Fact，需要：

• 添加<custom>/src/Settings/<Name>.SettingsGroup.jsonFact 元数据（并编入应用:/json资源前缀）；
• 为其创建SettingsGroup子类；
• 在插件中重写QGCCorePlugin::registerCustomSettings，调用SettingsManager::registerCustomSettingsGroup("<accessor>", new MySettings())（管理器接管所有权）。accessor 必须是"camelCase 的 JSON 文件名 + Settings"，例如Custom.SettingsGroup.json→customSettings，这样生成的页面才能解析QGroundControl.settingsManager.<accessor>.<fact>。

CMake 在自定义目录存在时自动完成上述接线，生成输出清单由生成器的--list-outputs模式计算。

仓库中的完整示例：custom-example

仓库自带的 custom-example 构建包含上述全部机制的可运行完整示例：

• 页面清单叠加 custom-example/src/AppSettings/pages/SettingsPages.json：定义名为Custom的页面（输出 QML 为CustomSettings.qml，图标qrc:/res/gear-white.svg），并insertAfter: "General"将其插入到内置 General 页之后；
• 页面定义 custom-example/src/AppSettings/pages/Custom.SettingsUI.json：一个Custom Example分组，包含三个控件，分别引用customSettings.showAttitudeWidget、customSettings.updateInterval、customSettings.operatorName三个自定义 Fact；
• 自定义设置组定义位于custom-example/src/Settings/Custom.SettingsGroup.json（含 Fact 元数据与对应SettingsGroup子类实现）；
• 插件注册覆盖位于custom-example/src/CustomPlugin.cc/h中。

开发者可以仿照该示例，为自己的定制构建增加设置页面，而无需接触任何手写 QML。

小结

V5.1 之后的这份 What's New 体现了 QGroundControl 在"地图体验"与"定制化能力"两个方向的演进：

• GeoMap 引擎把真实地形高程与无缝 2D/3D 渲染带入 Fly View，默认关闭、需手动开启并重启，作为技术预览面向尝鲜用户，长期目标是统一全应用的地图体验；
• ROI 高度设置用一次小的交互增强，让"对准高处目标"成为可能，底层由guidedModeROI与MAV_CMD_DO_SET_ROI系列命令支撑；
• JSON 驱动的自定义设置页把原本只能手写 QML 的扩展路径简化为纯配置叠加，custom-example提供了端到端的参考实现。

如需更深入的启用步骤、完整设置页生成规范，可继续阅读 docs/ko/qgc-user-guide/fly_view/geoview.md 与 docs/ko/qgc-dev-guide/views/settings_generation.md。

• 无人机
• 智能硬件