平行路校准

功能介绍

当车辆位于 主路 / 辅路、平行路、高架上下层等存在多条相近候选道路的场景时，定位引擎可能无法唯一确定当前所在道路。此时 SDK 通过 PositionEventListener.onCandidateRoadDetected 通知应用，并提供 RoadCalibrator 用于：

获取候选道路列表
查询当前候选道路信息
手动指定目标道路
修正当前地图匹配结果

本能力用于提升复杂道路场景下的道路匹配稳定性，避免：

车标吸附到错误道路
导航路线位于错误层级
算路起点与真实道路不一致
主辅路或高架切换错误

前置条件： 已完成位置输入，并在 NavigationService.eventHub 上注册 PositionEventListener（见地图匹配输出）。

适用场景

场景	说明
主路 / 辅路	主辅路平行且距离接近，GNSS 难以准确区分
平行路	多条走向相似、间距较近的平行道路
高架 / 地面	高架与地面道路重叠区域
高架上下层	上下层道路存在投影重叠
分岔口附近	道路分叉、汇合或拓扑快速变化区域

无上述歧义时，该回调可能长期不触发，属正常现象。

接入流程

平行路校准接入流程

在 PositionEventListener 中实现 onCandidateRoadDetected。
调用 roadCalibrator.getCandidateRoads() 获取候选列表。
由用户点选或按业务规则选定一条道路，调用 roadCalibrator.setRoad(roadInfo)。
setRoad 成功后，后续 onLocationUpdated 将反映纠正后的车位。

onCandidateRoadDetected

fun onCandidateRoadDetected(roadCalibrator: RoadCalibrator)

参数	说明
`roadCalibrator`	候选道路校准器，用于获取候选道路列表并设置当前目标道路

触发时机：

候选道路数量发生变化；
候选道路 数量 ≥ 2 且候选道路信息发生变化。

回调线程与 onLocationUpdated 相同；不宜在回调内执行长时间阻塞操作。

RoadCalibrator

方法	说明
`getCandidateRoads()`	返回当前缓存的全部候选道路（`List<RoadInfo>`）
`setRoad(roadInfo)`	从候选列表中指定车辆所在道路；成功返回 `true`，失败返回 `false`

传入的 roadInfo 应来自 getCandidateRoads() 返回的列表；勿构造列表外的 RoadInfo 对象。

候选道路展示字段（`RoadInfo`）

向用户展示时可参考以下字段：

字段	说明
`roadName / combinedRoadName`	道路名称 / 组合道路名称
`roadType / roadSubType`	道路类型 / 子类型
`confidence`	当前候选道路匹配置信度（0.0～1.0）
`probability`	当前候选道路匹配概率（0.0～1.0）
`bearingAligned`	当前车辆航向是否与候选道路方向一致

示例代码

val navigationService = NavigationService.Factory.createInstance()

navigationService.eventHub.addPositionEventListener(object : PositionEventListener {
    override fun onLocationUpdated(vehicleLocation: Location, positionInfo: PositionInfo) {
        // 常规车位更新，见「地图匹配输出」
    }

    override fun onCandidateRoadDetected(roadCalibrator: RoadCalibrator) {
        val candidates = roadCalibrator.getCandidateRoads()
        if (candidates.size < 2) {
            return
        }

        // 方式一：弹窗让用户选择
        showRoadPicker(candidates) { selected ->
            if (!roadCalibrator.setRoad(selected)) {
                // 设置失败，可提示重试
            }
        }

        // 方式二：按置信度自动选择（示例）
        // val best = candidates.maxByOrNull { it.confidence } ?: return
        // roadCalibrator.setRoad(best)
    }
})

注意事项

回调注册依赖（必须）： 需与地图匹配输出中的 onLocationUpdated 一并注册使用；仅实现 onCandidateRoadDetected 无法获得连续车位更新。
回调触发特性（说明）： 在无主辅路或平行路歧义的情况下，onCandidateRoadDetected 可能长期不触发，属于正常现象。
校准失败处理（建议）： setRoad 返回 false 表示校准失败，此时建议保留当前匹配结果，或提示用户重新选择候选道路。
算路起点一致性（建议）： 用户完成道路纠正后，算路或导航时，算路起点应使用最新 onLocationUpdated 中的校准后 vehicleLocation（GeoLocation(Location)），勿使用原始 GNSS 坐标，以保证 Link Id 与当前道路一致，详见路线规划-算路请求。