Skip to content

地图匹配输出

功能介绍

SDK 定位引擎在接收到 位置输入 的 VehicleLocation 后，会执行 地图匹配（Map Matching），将原始 GNSS / DR 位置吸附到道路网络，并通过 PositionEventListener 回调匹配结果。

匹配结果主要用于：

  • 地图车标显示与路径跟随
  • 算路起点（GeoLocation(Location)，包含匹配后的 Link Id、航向与速度）
  • 导航过程中的车道级引导、道路属性识别与偏航判断

监听入口为 NavigationService（或已创建的导航服务实例）的 eventHub。

接入流程

地图匹配输出接入流程

  1. 完成位置输入接入（见 位置输入）。
  2. 在 NavigationService.eventHub 注册 PositionEventListener。
  3. 在 onLocationUpdated 中获取匹配后的 vehicleLocation 与 positionInfo。
  4. 平行路等多候选场景处理见 平行路校准。
  5. 页面或模块销毁时调用 removePositionEventListener。

PositionEventListener

PositionEventListener 提供两个回调，均运行在与定位引擎约定的回调线程上；不宜在回调内执行长时间阻塞操作。平行路等候选道路纠正见 平行路校准。

onLocationUpdated

1
fun onLocationUpdated(vehicleLocation: Location, positionInfo: PositionInfo)
参数 说明
vehicleLocation 地图匹配后的车辆位置（Android Location）。包含匹配得到的道路 Link Id 等扩展信息，用于地图展示与算路起点
positionInfo 当前道路与区域上下文信息

触发时机： 车辆真实位置变化或虚拟定位更新时触发。

算路建议： 从当前位置触发求路时，应将此回调的 vehicleLocation（第一个参数） 作为起点传入 GeoLocation(vehicleLocation)，详见 路线规划-算路请求。SDK 会读取匹配后的 Link Id；若 RouteRequest 未单独设置 heading / speedInMps，还会使用其中的 bearing 与 speed。

onCandidateRoadDetected

多候选道路（主辅路、平行路、高架上下层等）场景下的回调与 RoadCalibrator 用法，见 平行路校准。

PositionInfo

PositionInfo 描述地图匹配后的道路、区域及相关上下文信息。

字段 说明
currentRoad 当前匹配到的道路信息（RoadInfo）。未匹配到道路时为 null，表示 off-road（未吸附到道路网络）
regionalInfo 区域信息（国家 / 城市 / 时区等）
feedback 地图匹配反馈（MMFeedback），用于 DR 校准输入。包含匹配后的位置信息、航向及道路上下文等
aheadIntersection 前方路口信息（仅在已匹配道路且存在前方路口时有效）
behindIntersection 后方路口信息（仅在已匹配道路且存在后方路口时有效）
nearbyRoad 附近道路信息（未匹配到道路但周围存在可候选道路时有效）
isOffRoad() 是否处于 off-road 状态（currentRoad == null）

RoadInfo（currentRoad）常用字段

字段 说明
roadType / roadSubType 道路类型 / 子类型
roadName / combinedRoadName 当前道路名称 / 组合道路名称
speedLimit 当前匹配道路的限速
confidence 匹配置信度（0.0～1.0）
probability 匹配概率（0.0～1.0）
bearingAligned 当前车头航向是否与道路方向一致
parkingLot 是否为停车场道路

MMFeedback（feedback）

MMFeedback 是定位引擎在完成地图匹配后输出的 DR 校准反馈。车端 DR 模块可结合其中的匹配位置、航向、时间戳及道路上下文，修正累积误差（尤其在隧道、分岔口、弱 GNSS 等场景）。

应用若自行实现 DR，可在 onLocationUpdated 中读取 positionInfo.feedback，并按项目需求回灌至 DR 模块；是否使用该数据由系统架构决定。

字段 说明
location 匹配反馈位置（WGS84），用于 DR 位置校准
bearing 匹配反馈航向（北为 0，顺时针），用于 DR 航向校准
timestamp 反馈时间戳（毫秒），对应 VehicleLocation.elapsedTime，用于与 DR 时间轴对齐
confidence / probability 匹配反馈置信度与概率（0.0～1.0），用于 DR 评估本次校准可靠性
inTunnel 是否处于隧道场景，用于 DR 切换推算模式
distToBifurcationAhead / distFromBifurcationBehind 前/后分岔点距离（米），用于 DR 岔口约束；无效为 -1

注册与注销

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
val navigationService = NavigationService.Factory.createInstance()

val positionListener = object : PositionEventListener {
    override fun onLocationUpdated(
        vehicleLocation: Location,
        positionInfo: PositionInfo
    ) {
        latestMatchedLocation = vehicleLocation
        // 示例：更新地图车标 / 速度 / UI 状态
        if (positionInfo.isOffRoad()) {
            // off-road 状态处理
        }
    }

    override fun onCandidateRoadDetected(
        roadCalibrator: RoadCalibrator
    ) {
        // 平行路 / 主辅路校准处理（见「平行路校准」）
    }
}

navigationService.eventHub.addPositionEventListener(positionListener)

算路起点示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
private var latestMatchedLocation: Location? = null

// 在 onLocationUpdated 中更新 latestMatchedLocation

fun requestRouteFromCurrentPosition(destination: GeoLocation) {
    val originLocation = latestMatchedLocation ?: return
    val request = RouteRequest.Builder(
        GeoLocation(originLocation),
        destination
    )
        .routeStyle(RouteStyle.FASTEST)
        .build()

    navigationService
        .createNavigableRouteTask(request)
        .runAsync {
            // 见「路线规划」
        }
}

注意事项

  • 回调频率（说明）： PositionEventListener 回调频率与位置输入频率一致；输入频率规则见 位置输入。
  • off-road 状态（说明）： 当 positionInfo.isOffRoad() == true 时，表示当前位置未匹配到道路（currentRoad == null）；此时仍会持续收到位置更新。
  • 多候选道路场景（说明）： 平行路、主辅路、高架上下层等多候选道路场景，见 平行路校准。
  • 线程与性能（建议）： PositionEventListener 回调中不建议执行耗时操作，以避免阻塞定位与导航链路。
  • 算路起点一致性（建议）： 算路或导航时，算路起点应使用最新 onLocationUpdated 中的匹配后 vehicleLocation（GeoLocation(Location)），勿使用原始 GNSS 坐标，以保证 Link Id 与当前道路一致，详见 路线规划-算路请求。