地图匹配

功能介绍

地图匹配能力负责接收 GNSS（卫星定位）、DR（航位推算） 等车辆定位数据，通过 SDK 定位引擎进行 地图匹配（Map Matching），输出稳定、连续且贴合道路的车辆位置与道路上下文信息，为 HMI、算路、导航及地图渲染等功能提供位置基础能力。

本文档建议按以下顺序阅读：

序号	文档	说明
1	位置输入	通过 `LocationProvider` 注入原始 GNSS 或 DR 处理后的 `VehicleLocation`
2	地图匹配输出	通过 `PositionEventListener` 接收地图匹配后的车辆位置 `Location` 与道路上下文 `PositionInfo`
3	平行路校准	通过 `onCandidateRoadDetected` 与 `RoadCalibrator`，处理主辅路、高架路等多候选道路场景

数据流概览

地图匹配数据流概览

核心接口

接口 / 类	作用
`LocationProvider`	位置输入抽象类；实现 `onStart` / `onStop`，并通过 `updateLocation(...)` 注入车辆位置数据
`VehicleLocation`	单帧位置输入数据结构，包含坐标、航向、速度、卫星数、DR 累计量等信息
`SDK.injectLocationProvider(...)`	注册自定义位置输入源；传入 null 时回退系统定位
`NavigationService` / `NavigationServiceOptions`	创建导航服务并完成定位引擎初始化，以及日志、算法等相关配置
`NavigationService.eventHub`	事件分发通道，用于注册定位、导航等事件监听
`PositionEventListener`	地图匹配结果监听接口，包含 `onLocationUpdated(...)` 与 `onCandidateRoadDetected(...)` 等回调
`PositionInfo`	地图匹配后的道路上下文信息，包含道路、区域、隧道、路口等状态
`RoadCalibrator`	多候选道路场景下，用于获取候选道路列表，并通过 `setRoad(...)` 对地图匹配结果进行道路校准

航位推算（DR）协同

弱 GNSS 场景连续性： 在隧道、城市峡谷、立交重叠区域等 GNSS 不稳定场景中，DR 可提供连续位姿输入，降低车位跳变。
匹配稳定性： DR 的速度、航向、累计里程等信息可帮助定位引擎提升道路吸附稳定性，减少主辅路和高架层级误匹配。
职责与边界： 车端负责 GNSS/IMU/车身信号采集输入到DR，DR融合数据输出融合定位结果；地图匹配模块仅消费通过 LocationProvider 输入的 VehicleLocation，并输出匹配结果与道路上下文。DR 能力原理与输出定义见航位推算
闭环机制： DR融合定位 -> VehicleLocation（输入）→ 地图匹配输出 PositionInfo.feedback（校准反馈）→ DR 模块按项目策略回灌修正 → 下一帧 VehicleLocation 再输入，引导稳定收敛。

定位引擎（Position Engine）初始化与配置

定位引擎（Position Engine）在创建 NavigationService 时完成初始化。调用 NavigationService.Factory.createInstance(...) 时需传入 NavigationServiceOptions 用于配置日志、算法参数等选项。 NavigationService 必须在 SDK initialize(...) 成功之后创建，详见 SDK 初始化。

定位引擎相关配置（`NavigationServiceOptions`）

API	说明	推荐场景	默认值
`setPositionAlgorithmConfiguration(jsonConfig)`	配置定位引擎内部算法参数，参数为 JSON 字符串，结构需与定位配置文件保持一致	需要按车型或项目定制定位算法参数时	未设置
`enableSelfPropellingUponWeakGPS(enabled)`	GNSS 信号丢失时，会在隧道等场景触发自推算；开启后建议持续提供有效的 `speed`，以提升推算位置准确性。	无外部 DR，且存在隧道丢失 GNSS 场景时	`false`
`enableHeadingCalibrateEnabled(enabled)`	使用车辆轨迹方向校准输入航向，以提升地图匹配稳定性。	移动导航，需要提升地图匹配稳定性时	`false`
`enablePositionEngineLog(enabled)`	开启或关闭定位引擎文件日志	联调、问题定位、路测分析阶段（生产环境建议关闭）	`false`
`setPositionEngineLogStorePath(path)`	定位引擎日志目录，须已存在且可写；默认不设置；当已开启日志且未指定目录时，日志默认写入 `PE_Logs` 子目录	已开启日志，且需要指定日志存储目录时	未设置

创建 NavigationService 示例

val peLogDir = File(context.getExternalFilesDir(null), "peLog").apply { mkdirs() }

val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        // 可选：按项目配置定位引擎算法参数
        // .setPositionAlgorithmConfiguration(positionConfigJson)

        // 可选：存在外部 DR 输入时建议保持关闭
        // .enableSelfPropellingUponWeakGPS(false)

        // 可选：仅移动导航且需要提升地图匹配稳定性时打开
        // .enableHeadingCalibrateEnabled(false)

        // 建议：仅调试、路测环境打开，生产环境关闭
        .enablePositionEngineLog(true)
        .setPositionEngineLogStorePath(peLogDir.absolutePath)

        .build()
)
)

定位引擎日志

定位引擎日志与 TaLog 相互独立，用于记录定位引擎内部运行信息，包括地图匹配、轨迹推算及 GNSS 处理等过程。配置时机及 API 说明见日志管理 — 定位引擎日志。生产环境不建议长期开启。

快速接入示例

以下示例展示从位置数据输入到地图匹配结果输出的完整链路（需已完成 SDK 初始化，见初始化）。

// 1. 注入位置数据源（应用启动后执行一次）
val locationProvider = GnssLocationProvider(context)
SDK.getInstance().injectLocationProvider(locationProvider)

// 2. 创建 NavigationService（自动初始化定位引擎）并注册回调
val navigationService = NavigationService.Factory.createInstance(
    NavigationServiceOptions.Builder()
        // .enablePositionEngineLog(BuildConfig.DEBUG)   // 仅示例：调试环境开启
        .build()
)
var latestMatchedLocation: Location? = null

val positionListener = object : PositionEventListener {
    override fun onLocationUpdated(location: Location, positionInfo: PositionInfo) {
        latestMatchedLocation = location
    }

    override fun onCandidateRoadDetected(roadCalibrator: RoadCalibrator) {
        // 见「平行路校准」
    }
}
navigationService.eventHub.addPositionEventListener(positionListener)

// 3. 使用匹配后位置发起算路（起点为当前车位）
fun planRouteTo(destination: GeoLocation) {
    val origin = latestMatchedLocation ?: return
    val request = RouteRequest.Builder(
        GeoLocation(origin),
        destination
    ).build()
    navigationService.createNavigableRouteTask(request).runAsync { /* … */ }
}

// 4. 销毁时注销监听
navigationService.eventHub.removePositionEventListener(positionListener)

关键要点

主题	说明
输入频率	自定义 LocationProvider 支持 1～15 Hz；未注入或 `null` 时默认 Provider 为 4 Hz
坐标系	WGS84；有效范围：纬度 [-85, 85]，经度 [-180, 180]
隧道/GNSS丢失	可使用 `VehicleLocation.INVALID_COORDINATE`，此时仅需更新 `speed`、`satelliteNumber` 等字段
算路起点	使用 `onLocationUpdated` 回调的 Location 构造 `GeoLocation(Location)`，以携带道路匹配信息（如 Link Id )
off-road	当`positionInfo.isOffRoad()` 为 `true` 时表示未匹配到道路（`currentRoad == null`）
初始化	`NavigationService.Factory.createInstance(options)`，必须在 SDK 初始化之后调用
日志	通过`enablePositionEngineLog` / `setPositionEngineLogStorePath`配置，见日志管理 — 定位引擎日志

注意事项

初始化顺序（必须）： 先在 SDK initialize(...) 成功后创建 NavigationService 完成定位引擎初始化，再注入位置数据源并注册 PositionEventListener。
配置决策时机（必须）： NavigationServiceOptions 中的定位引擎能力开关（如 enableSelfPropellingUponWeakGPS）应在接入阶段确定，不可以在运行中临时切换。
日志策略（建议）： 定位引擎日志仅用于联调与问题定位，生产环境不建议长期开启；配置方法见日志管理 — 定位引擎日志。
生命周期管理（必须）： 组件或服务销毁时应释放 LocationProvider 与 PositionEventListener 相关资源，避免泄漏。
权限要求（必须）： 使用 GNSS 或系统定位回退能力时，需确保已授予定位权限。