Skip to content

路口放大图

功能介绍

为了帮助用户更容易通过路口（尤其是复杂路口），导航会在车辆到达前检测前方路口并透出图形信息，供 HMI 在导航界面显示。两种能力对比如下：

类型 数据形态 导航透出 HMI 集成 适用场景与特点
Junction View（JV） 地图编译数据中的预渲染位图；导航做路牌剪切、拼接 NavigationEventListener.onJunctionViewUpdated HMI 用 ImageView 等直接显示 场景：高速/快速路分叉、出口 · 样式：昼夜（SDK.updateDayNightMode） · 特点：预编译、性能好；尺寸比例不可改
Intersection View（IV） 依导航路线实时生成的引导场景（Protobuf） GuidanceEventListener.onIntersectionGuidanceInfoUpdated MapView IntersectionView 渲染（地图渲染） 适用：无 JV 的转向路口 · 排除：直行、途经点/终点、跨国界、收费站、渡口、大环岛及已有 JV · 特点：非位图，TSS 可按项目配置

Junction View Junction View 展示

Intersection View Intersection View 展示

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
                    导航（检测车前路口）
                              │
              ┌───────────────┴───────────────┐
              │                               │
         有 JV 数据                     无 JV，且符合 IV 条件
              │                               │
              ▼                               ▼
   onJunctionViewUpdated              onIntersectionGuidanceInfoUpdated
   (JunctionViewInfo + Bitmap)        (IntersectionGuidanceInfo + ByteArray)
              │                               │
              ▼                               ▼
        HMI 直接显示 JV                  MapView IntersectionView
        （ImageView 等）                 addIntersectionViewData → 实时绘制

优先级： 有 JV 数据则只返回 JV；无 JV 且机动点符合 IV 条件时，才通过 GuidanceEventListener 返回 IV（见 setIntersectionDisplayDistanceThreshold）。

前置条件： 已按 真实导航与模拟导航 启动导航并注册相应监听器；Intersection View 另需 MapView 模块提供 IntersectionView（如 TnIntersectionView）及独立 Surface / TextureView。

能力对比

维度 Junction View Intersection View
监听器注册 eventHub.addNavigationEventListener eventHub.addGuidanceEventListener
功能开关 随地图数据与导航能力启用 NavigationServiceOptions.Builder.enableIntersectionGuidance(true)（默认 true）
提前触发距离 高速默认 700 m、普通道路 400 m（可配置，二者共用） 同上；有 JV 时不触发 IV 回调

配置

创建 NavigationService 时通过 NavigationServiceOptions.Builder 配置：

1
2
3
4
5
6
7
8
NavigationServiceOptions.Builder()
    .enableIntersectionGuidance(true)   // 默认 true；false 则不下发 IV 引导
    // JV、IV 共用探测距离：自车距路口 ≤ 阈值时，才可能透出对应信息（有 JV 则只返 JV）
    .setIntersectionDisplayDistanceThreshold(
        highwayIntersectionDistanceThreshold = 700,  // 高速，米（JV / IV 探测距离）
        localIntersectionDistanceThreshold = 400      // 普通道路，米（JV / IV 探测距离）
    )
    .build()

当自车距路口 ≤ 上述阈值 时才会透出路口图：有 JV 数据则触发 onJunctionViewUpdated；无 JV 且符合 IV 条件、且 IV 已开启时，触发 onIntersectionGuidanceInfoUpdated。

1. Junction View — 导航透出位图，HMI 直接显示

图片直接来自编译好的地图原始数据；导航根据当前路线与机动点，对路牌等元素做剪切与拼接后，通过 JunctionViewInfo.image（Bitmap）交给 HMI 显示，无需 Map 模块参与绘制。

1.1 注册与回调

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
navigationService.eventHub.addNavigationEventListener(object : NavigationEventListener {
    override fun onJunctionViewUpdated(info: JunctionViewInfo) {
        mainHandler.post {
            when (info.status) {
                JunctionViewInfo.Status.ENTERED -> {
                    info.image?.let { showJunctionBitmap(it) }  // HMI 直接显示
                }
                JunctionViewInfo.Status.IN_TRANSITION -> setJunctionAlpha(0.5f)
                JunctionViewInfo.Status.PASSED -> hideJunctionView()
            }
        }
    }
    // 其它方法按需实现
})

1.2 JunctionViewInfo

字段 / 状态 说明
status ENTERED：显示；IN_TRANSITION：可半透明（非每次都有）；PASSED：隐藏
image PNG 位图；数据不可用时为 null
legIndex / stepIndex 所属 leg、step（从 0 开始）
dayNightMode DAY / NIGHT，对应白天 / 黑夜两套路口图样式

2. Intersection View — 导航透出引导数据，MapView 模块实时渲染

Intersection View 根据当前导航路线生成车道级矢量路口引导场景（非位图）。导航在前方复杂路口且无 Junction 图时下发 Protobuf 数据；HMI 将 ByteArray 交给 MapView 模块的 IntersectionView，由引擎在独立 Surface 上实时渲染。

IV 的初始化、Surface 生命周期、addIntersectionViewData 等详见 地图渲染 — 路口放大图。本文说明导航侧如何接收并转交数据。

2.1 流程概览

1
2
3
4
5
6
7
8
9
addGuidanceEventListener
        ↓
startNavigation
        ↓
onIntersectionGuidanceInfoUpdated
        ↓
DETECTED → IntersectionView.addIntersectionViewData(data) → 显示 TextureView/SurfaceView
        ↓
PASSED → clearIntersectionViewData() → 隐藏

2.2 注册与转交 Map 模块

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
navigationService.eventHub.addGuidanceEventListener(object : GuidanceEventListener {
    override fun onIntersectionGuidanceInfoUpdated(info: IntersectionGuidanceInfo) {
        mainHandler.post {
            when (info.status) {
                IntersectionGuidanceInfo.Status.DETECTED -> {
                    val data = info.detailedIntersectionGuidanceInfo?.data ?: return@post
                    val recommended = intersectionView?.addIntersectionViewData(
                        data,
                        object : IntersectionRenderListener {
                            override fun onIntersectionRendered() { /* 首帧绘制完成 */ }
                        }
                    ) ?: false
                    if (recommended) showIntersectionSurface()
                }
                IntersectionGuidanceInfo.Status.PASSED -> {
                    intersectionView?.clearIntersectionViewData()
                    hideIntersectionSurface()
                }
            }
        }
    }
})

// stopNavigation 后：
navigationService.eventHub.removeGuidanceEventListener(listener)

2.3 IntersectionGuidanceInfo

字段 说明
status DETECTED：新检测到前方路口；PASSED：已通过
detailedIntersectionGuidanceInfo 详细数据；PASSED 时为 null
detailedIntersectionGuidanceInfo.data Protobuf ByteArray，传给 IntersectionView.addIntersectionViewData

addIntersectionViewData 返回 true 表示建议显示；false 表示当前条件不适合展示（HMI 仍可自行决定）。

注意事项

  • 分工： JV 由 HMI 显示 Bitmap；IV 由 Map 模块 IntersectionView 渲染，导航只负责下发 ByteArray。
  • 互斥： 同一路口有 JV 时，一般只收到 onJunctionViewUpdated，不会收到该路口的 onIntersectionGuidanceInfoUpdated。
  • 回调线程： NavigationEventListener 与 GuidanceEventListener 均在 Message 线程，更新 UI / Surface 请切主线程。
  • 判空： JunctionViewInfo.image、detailedIntersectionGuidanceInfo 可能为空。
  • 生命周期： 退出导航时 removeNavigationEventListener / removeGuidanceEventListener；IntersectionView 在 onDestroy 中释放。
  • 关闭 IV： enableIntersectionGuidance(false) 后不再下发 IntersectionGuidanceInfo，不影响 Junction View。

相关文档