核心能力与数据模型
产品概念 Lane Group 对应公共类型 LaneGroup。应用先获取局部区域内的 LaneGroupId，再按 ID 读取 Lane、车道边界线、道路属性、参考线、ADAS Values 与拓扑关系。
车道路网建模
HDMapSDK 公共模型将车道路网表达为以 Lane Group 为节点、以前驱和后继关系为连接的有向图：
| 建模层次 | 主要对象 | 形成的关系 |
|---|---|---|
| 车道 | Lane、左右 LaneBoundary |
中心线和边界描述车道的方向、范围和标线 |
| 方向道路单元 | LaneGroup |
相同行驶方向、共享起始与结束 Connector 的 Lane 组成一个 Lane Group |
| Lane Group 拓扑 | predecessors、successors、adjacent_lane_group_id |
每条连接指向一个相邻 Lane Group；多个连接表达路口、分流、合流与道路延续 |
| 逐车道连通 | lane_num_map、from_lane_num、to_lane_num |
每条相邻 Lane Group 连接分别保存从当前车道号到相邻车道号的多对多映射 |
| 道路信息 | 道路属性、reference_line、adas_info 与三维几何 |
属性和 ADAS Values 附着于 Lane Group |
应用通过这些对象和关系读取车道路网，无需参与 Lane Group 的数据生产与构建过程。
LaneGroup::lanes 组织车道，Lane::left/right 组织边界，predecessors/successors 连接相邻 Lane Group，每条连接中的 lane_num_map 再描述两组 Lane 之间的对应。
局部查询
| 接口 | 输入 | 输出 |
|---|---|---|
fetchLaneGroups(ids, location, radius) |
WGS84 中心点和半径（米） | 区域内的 LaneGroupId |
fetchLaneGroups(ids, sw, ne) |
西南角和东北角 | 包围盒内的 LaneGroupId |
queryLaneGroupInfo(group, id) |
LaneGroupId |
完整 LaneGroup |
局部查询结果
| 调用结果 | 含义与应用处理 |
|---|---|
OK 且 ID 非空 |
调用成功并返回可继续查询的 Lane Group ID |
OK 且 ID 为空 |
调用成功，但本次范围没有返回 Lane Group ID；进入无结果路径 |
其他 Status |
按服务状态处理，不读取未成功赋值的输出对象 |
SDK 不进一步区分 OK 空结果的具体原因。应用不把空结果解释为数据仍在准备，也不根据空数组单独推断目标区域覆盖状态。
fetchLaneGroups 的查询半径建议不超过 10 km。实际应用使用与当前业务区域对应的局部窗口，并只查询当前需要的 Lane Group 详情。
matchLaneGroup(...) 是测试接口，可用于调试坐标附近的候选 Lane Group。正式定位结果由上层定位或融合系统提供。
场景代码见查询局部 Lane Group。
静态车道模型
Lane Group
公共类型 LaneGroup 描述产品概念 Lane Group：共享同一起始 Connector 与结束 Connector 的一组 Lane。Connector 是垂直于道路中心线的道路横截线。每个 Lane Group 具有预设行驶方向；反向行驶使用另一个 Lane Group 表示，同一物理 Lane 可能属于多个 Lane Group。
LaneGroup 字段
| 字段组 | 字段 | 说明 |
|---|---|---|
| 标识 | id、native_lane_group_id |
id 是运行时标识；native_lane_group_id 是原始数据引用 |
| 道路分类 | road_function_class、road_type、road_sub_type |
道路等级、道路类型以及匝道、桥、隧道等子类型 |
| 道路属性 | is_toll、is_toll_booth、is_gateway、is_controlled_access、is_limited_access、is_connect_highway_ramp |
收费、出入口控制和高速连接属性 |
| 几何 | reference_line、length |
Lane Group 参考线及其长度 |
| ADAS | adas_info |
沿参考线组织的曲率、坡度和航向样本 |
| 车道 | lanes |
按车道号顺序保存的车道对象 |
| 拓扑 | predecessors、successors |
前驱、后继 Lane Group 及车道连接关系 |
Lane Group 参考线等于最左侧车道的左边界几何，即 lanes[0].left.geometry。length 是这条参考线的长度，单位为米。
Lane 与车道边界线
Lane 包含车道本身的几何和属性，也直接包含左右边界：
| 字段 | 内容 |
|---|---|
id |
当前运行期的 LaneId |
lane_type |
普通、入口、出口、出入口、公共交通停靠区或等待区 |
lane_properties |
管制、自行车、公交、铁路、停车、应急、潮汐、拼车、加速和减速等属性 |
transit_type |
无变化、分流或合流 |
geometry、length |
WGS84 三维中心线及其长度（米） |
left、right |
相对于行驶方向的 LaneBoundary |
speed_limit |
限速值及公制或英制单位 |
min_width、max_width |
最小和最大宽度（厘米） |
车道号从 1 开始。车道号 n 对应 lanes[n - 1]，这也是 lane_num_map 连接拓扑时使用的编号。LaneId 的低位包含同一个车道号，但应用应通过当前 LaneGroup 的 lanes 数组访问车道，而不是自行解析 ID。
LaneBoundary 作为值对象嵌入 Lane：
| 字段 | 内容 |
|---|---|
id |
当前运行期的边界 ID |
geometry |
WGS84 三维折线 |
style |
无标线、实线、虚线、双实线或混合样式 |
material |
未知、油漆或道路凸点 |
color |
未知、白色或黄色 |
相邻车道的右边界和左边界可以描述同一条物理分隔线。模型仍会在两条车道中分别返回边界对象，LaneBoundaryId 用于识别当前运行期内的边界。
车道级地图数据
车道级地图包含 Lane::geometry、左右 LaneBoundary、宽度和标线属性；predecessors、successors 与 lane_num_map 描述分流、合流和车道延续；中心线与边界中的经纬度和高程描述三维道路形态。
读取这些数据时保留以下对象语义：
left和right相对于车道行驶方向定义；reference_line是最左侧车道的左边界，不是道路中心线；- 相邻车道可以分别包含同一物理分隔线的边界对象；
LaneBoundary::material或color为Unknown、Lane 宽度为0，或几何缺失时，数据保持未知；- 运行时 ID 在服务重建或地图版本变化后重新获取。
车道拓扑
LaneGroup::Connectivity 同时表达 Lane Group 级和车道级连接：
adjacent_lane_group_id指向一个前驱或后继 Lane Group；lane_num_map中的from_lane_num是当前 Lane Group 的车道号；to_lane_num是相邻 Lane Group 的车道号；- 同一车道号可以映射到多个车道号，多个车道号也可以汇入同一车道号。
例如，from_lane_num = 2、to_lane_num = 1 表示当前 Lane Group 的 lanes[1] 连接到相邻 Lane Group 的 lanes[0]。
在路口中，一个入口 Lane Group 可以包含多个 successors。例如，三车道入口 A 分流时，A 到两车道后继 B 的连接可以保存 1 → 1、2 → 2，A 到单车道后继 C 的另一条连接可以保存 3 → 1。三条 Lane 沿各自后继道路的几何延续且互不交叉，B、C 的 predecessors 分别指回 A。对应示意见路口拓扑与逐车道连通。
一个 Lane Group 可以有多个前驱和后继，车道网络中也可能出现环。沿拓扑展开时设置距离、节点数或深度上限，并记录已访问的 LaneGroupId。
参考线与 ADAS Values
adas_info 中的每个 AdasValue 描述参考线上的一个 ADAS 样本：
| 字段 | 含义 | 特殊值 |
|---|---|---|
offset |
样本到参考线起点的距离（米） | 0 表示参考线起点 |
curvature |
曲率编码 | -1 无数据；511 直线 |
slope |
坡度编码 | 65535 无数据 |
heading |
当前点指向下一点的航向（度） | -1 无下一点或无数据 |
这些字段描述地图中的道路几何。读取时按 offset 关联到 reference_line，并先处理特殊值。
标识与单位
标识符
| 类型 | 生命周期 | 使用方式 |
|---|---|---|
LaneGroupId |
当前服务实例和地图版本 | 从空间查询或拓扑中获取 |
LaneId |
当前服务实例和地图版本 | 在所属 LaneGroup 中使用 |
LaneBoundaryId |
当前服务实例和地图版本 | 在所属 Lane Group 中识别边界 |
native_lane_group_id |
原始数据引用 | 作为不透明字段记录 |
服务重建或地图版本变化后，重新执行空间查询并更新以运行时 ID 为键的缓存。版本切换行为见数据与版本管理。
坐标、单位和特殊值
| 内容 | 单位或坐标系 | 特殊值 |
|---|---|---|
| 纬度、经度 | WGS84 十进制度 | 按有效经纬度范围校验 |
| 高程 | 米 | 垂直基准随数据交付 |
| 几何长度、查询半径、ADAS 偏移 | 米 | — |
| 车道宽度 | 厘米 | 0 表示无数据 |
| ADAS 航向 | 从正北顺时针，范围 [0, 360) |
-1 表示无下一点或无数据 |
| 限速 | km/h 或 mph | -1 未知；255 无限制 |