Auto Zoom（自动缩放）

本指南：从驾驶员与 HMI 产品视角说明导航中 自动缩放（Auto-Zoom） 的作用与工作机制。接口调用见显示模式与视角。

功能介绍

在 跟车导航 场景下，地图不必由用户反复捏合缩放。Auto-Zoom 会根据 当前车速、道路类型 以及 前方即将发生的引导动作（如下一个转弯、高速出口、连续转向），自动拉近或拉远地图，使驾驶员始终看到「够用、不过载」的前方路况。

对驾驶员而言，典型体验是：

高速、直行：视野略拉远，前方可见更长路段，便于提前判断车道与出口。
接近转弯、路口或低速区段：视野拉近，转弯点与衔接道路更清晰。
3D 导航视角：在导航过程中靠近路口时，除缩放外还可能配合 倾角（tilt） 调整，变成 2D。

Auto-Zoom 由地图引擎在后台持续演算并 平滑动画 过渡到目标视野，避免画面突然跳变。

适用场景

场景	是否适合 Auto-Zoom	说明
逐向导航、跟车模式	推荐	与 `enableFollowVehicleMode(..., useAutoZoom = true)` 配合
自由巡航（无路线）	支持	主要依据车速与道路类型调整视野
路线全览 / 浏览地图	通常关闭	应关闭跟车与 Auto-Zoom，改用手动或 `showRegion`

核心工作机制

以下描述对应 ATLAS Speed-Based Auto Zoom 与 Look Ahead Distance（前瞻距离） 规则的产品化理解，不涉及引擎内部实现细节。

1. 跟车 + 自动缩放是一组能力

Auto-Zoom 不是独立的「只改 zoom 级别」开关，而是跟车体验的一部分：

相机始终跟随 车辆位置（CVP） 移动（见自车图标显示）。
在跟车开启且 useAutoZoom = true 时，引擎才根据行驶状态调整缩放（3D 下还可能调整 tilt）。

用户手动拖动地图或退出跟车后，自动缩放逻辑会停止或让位于用户操作。

2. 两种行驶上下文

引擎区分两类上下文，采用不同缩放策略：

上下文	含义	视野如何变化
自由行驶（Free Drive）	未沿导航路线行驶，或尚无有效「下一机动」	主要依据实时车速与当前道路类型（如高速、城市道路）决定目标缩放与前瞻距离
主动导航（Active Navigation）	已加载导航路线，并持续收到下一转弯/机动信息	在车速规则基础上，叠加距下一机动的距离、机动复杂度（如高速出口、连续转向）等，在接近关键点前提前拉近

路线绘制与导航进度由路线渲染提供；引擎在导航更新时同步「下一机动」信息，用于 Active Navigation 下的缩放决策。

3. 车速驱动：快则远、慢则近

Speed-Based Auto Zoom 的核心直觉：

车速越高 → 地图倾向拉远，让驾驶员看到更长的前方路段，匹配高速下的反应时间需求。
车速越低 → 地图倾向拉近，突出近处道路细节与车道关系。

道路类型（如高速、主干道、普通道路）会参与分档，避免在同类道路上因瞬时速度波动频繁抖动。

4. 前瞻距离（Look Ahead Distance）

除缩放级别外，系统还维护一个产品向的概念：前瞻距离——地图上希望让驾驶员看到的 前方路段长度。

前瞻距离大：屏幕上可见的前方路线更长，适合高速直行、提前观察出口或车道变化。
前瞻距离小：更聚焦近处路口与转向几何，适合低速或即将转弯。

初始化时的 AutoZoomLevel（见下文）会整体放大或缩小前瞻距离，相当于 OEM 在「看得更远」与「看得更细」之间的产品档位，不改变车速与机动规则本身。

5. 接近机动时的「预判缩放」

进入主动导航后，当车辆 驶向下一转弯、匝道或复杂路口 时：

系统根据 距机动的剩余距离 进入准备阶段，逐步调整视野。
在机动前适当拉近，使用户能辨认转向方向与进入道路。
机动完成后，随车速与下一段路况恢复到车速驱动的远景档位。

接近路口（如低速路口）可能触发更强的拉近或 3D 倾角配合，具体阈值由引擎配置，集成方无需逐条配置。

6. 平滑过渡

缩放与（在 3D 下的）倾角变化通过动画完成，避免一帧跳变。若上一次动画尚未结束，引擎会合并或延后指令，保证观感连贯。可通过地图状态监听的 isAutoZoomAnimationRunning 了解动画是否在执行（多用于调试与状态展示）。

视野档位：AutoZoomLevel

在 MapViewInitConfig（或 Cluster 多屏参数）中设置 autoZoomLevel，用于表达 OEM 对默认「看得多远」的偏好：

档位	产品含义
`DEFAULT`	标准前瞻，适合多数车型
`MEDIUM`	略扩大前方可见范围
`FAR`	明显偏「远看」，适合大屏或偏好提前观察的用户
`VERY_FAR`	更远前瞻
`MAXIMUM`	最大前瞻，前方路线在屏上占比最大

档位越高，同等车速下地图往往 更 zoom out（看到的路段更长）。该参数在 初始化时 生效，运行时如需开关自动缩放请使用 CameraController.setEnableAutoZoom。

集成要点（开发者）

Auto-Zoom 由引擎内部驱动，没有单独的 getAutoZoomController() 对外 API。集成方只需保证前置条件，并在合适场景开关：

// 1) 初始化：选择前瞻档位（可选，默认 DEFAULT）
val config = MapViewInitConfig(
    context = context,
    lifecycleOwner = lifecycleOwner,
    defaultLocation = defaultLocation,
    readyListener = readyListener,
    autoZoomLevel = AutoZoomLevel.DEFAULT
)

// 2) 地图就绪后：导航跟车 + 自动缩放
mapView.getCameraController()?.apply {
    setEnableAutoZoom(true)
    enableFollowVehicleMode(
        Camera.FollowVehicleMode.HeadingUp,
        useAutoZoom = true
    )
}

// 3) 路线全览或用户浏览：关闭
mapView.getCameraController()?.apply {
    setEnableAutoZoom(false)
    disableFollowVehicle()
}

步骤	说明
绘制导航路线	使用 `RoutesController.addRouteLine`，保证引擎能获取路线几何
持续导航更新	由导航模块向地图同步位置、下一机动、距转弯距离等（引擎在 `setEnableAutoZoom(true)` 时自动消费）
跟车模式	`enableFollowVehicleMode(..., useAutoZoom = true)`
全局开关	`setEnableAutoZoom(true/false)` 可在不退出跟车的情况下暂停自动缩放
退出导航	关闭 Auto-Zoom 与跟车，或切换为 `NorthUp` + `useAutoZoom = false` 做全览

各 API 参数表与示例见显示模式与视角 · 跟车与 AutoZoomLevel。

注意事项

须在 MapViewReadyListener.onReady 之后再调用 setEnableAutoZoom 与 enableFollowVehicleMode。
setEnableAutoZoom(false) 不会自动退出跟车，仅停止自动调整缩放。
3D 模式（M3D）下 Auto-Zoom 可能同时改变 tilt，与 2D 仅改 zoom 的体验略有不同。
自动缩放依赖 真实或模拟的车速与导航事件；台架无定位/无导航更新时，可能看不到预期效果。