Skip to content

快速开始

HDMapSDK 的最小集成路径包括接入交付包、准备配置、激活、创建服务、读取地图版本、查询一个 Lane Group，并按顺序关闭服务。Lane Group 遍历、路线关联和交通查询的独立代码见场景示例。

前置条件

  • 交付包与目标平台、处理器架构、编译器 ABI 和运行库匹配，并包含 include/hdmap、hdmapservice 库及依赖清单；
  • 项目已获得激活端点、地图数据端点、应用凭据、授权信息、地图版本、覆盖区域和目标坐标；
  • 设备已部署 CA 证书，具备可信系统时间、可用网络和 HDMapSDK 独占的可写持久目录；
  • 使用路线关联、前路或交通能力时，还需准备导航支持连接设置并保证车辆/路线上下文持续更新。

参与方和运行边界见产品架构与生命周期。

1. 集成交付包

交付包通常包含以下内容，具体文件名以项目交付清单为准：

1
2
3
4
hdmap-sdk/
├── include/hdmap/
├── lib/
└── CHANGELOG.md

应用使用 C++14 编译，加入公共头文件目录并链接交付的 hdmapservice 库。例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
cmake_minimum_required(VERSION 3.8)
project(hdmap_quick_start LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 14)
set(HDMAP_SDK_ROOT "" CACHE PATH "HDMapSDK delivery root")
set(HDMAP_SDK_LIBRARY "" CACHE FILEPATH "HDMapSDK link library")

add_executable(hdmap_quick_start hdmap_quick_start.cpp)
target_include_directories(hdmap_quick_start PRIVATE "${HDMAP_SDK_ROOT}/include")
target_link_libraries(hdmap_quick_start PRIVATE "${HDMAP_SDK_LIBRARY}")

运行时库及其依赖由应用私有库目录、镜像清单或目标平台的加载配置提供。

2. 准备配置

HDMapServiceOptions 和 ActivationRequest 的值来自项目交付配置。秘密值和设备标识由安全配置提供器注入，不写入源码、命令行或日志。

配置 使用条件
persistent_path 始终设置为应用独占、持续可写的持久目录
configuration_path 可选；未设置时使用 SDK 默认配置
cloud_url 在线数据模式设置；离线预置数据方案可为空
nav_sdk_broker_address 仅路线关联、前路和交通等导航支持能力需要
activation_url、应用凭据、授权代码、凭据类型 按项目激活配置设置
device_uid、CA 证书和 DeviceInfo 按设备身份、TLS 和平台信息设置

启动前确认持久目录可写、CA 文件可读、系统时间可信。其他公共选项、默认值和影响见可调整参数。

3. 激活、创建服务并查询

下面的代码片段假设 options、activation_request 和覆盖区域内的 WGS84 坐标 center 已由应用准备。它只展示 HDMapSDK 公共调用关系，配置加载和错误上报由应用实现。

 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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
#include <memory>
#include <string>
#include <vector>

#include "hdmap/hd_map_activation.h"
#include "hdmap/hd_map_service.h"

bool queryOneLaneGroup(
    const tn::hdmap::HDMapServiceOptions& options,
    const tn::hdmap::ActivationRequest& activation_request,
    const tn::hdmap::models::LatLon& center,
    tn::hdmap::models::LaneGroup& lane_group)
{
    const auto activation = tn::hdmap::activate(activation_request);
    if (activation.status != tn::hdmap::ActivationStatusCode::OK)
    {
        return false;
    }

    auto service = tn::hdmap::HDMapServiceFactory::createHDMapService(options);
    if (!service)
    {
        return false;
    }

    std::string map_version;
    std::vector<tn::hdmap::models::LaneGroupId> lane_group_ids;

    const bool map_ready =
        service->getMapVersion(map_version) == tn::hdmap::Status::OK &&
        !map_version.empty();
    const bool ids_ready = map_ready &&
        service->fetchLaneGroups(lane_group_ids, center, 100) ==
            tn::hdmap::Status::OK;
    const bool result_ready = ids_ready && !lane_group_ids.empty() &&
        service->queryLaneGroupInfo(lane_group, lane_group_ids.front()) ==
            tn::hdmap::Status::OK;

    service->shutdown();
    return result_ready;
}

fetchLaneGroups(...) 返回与查询范围相交的 Lane Group 运行时 ID；queryLaneGroupInfo(...) 再读取 Lane、边界、参考线和拓扑关系。示例半径单位为米，公共接口建议不超过 10 km，实际集成使用满足业务需要的最小范围。

OK 且 ID 数组为空表示当前范围没有返回 Lane Group，不是 SDK 错误。应用只在接口返回 OK 后读取输出对象；服务重建或地图版本变化后重新执行空间查询，不复用旧的 LaneGroupId。

4. 处理状态与生命周期

  • ActivationStatusCode 表示激活结果，Status 表示服务和查询结果；
  • DataPending 只对幂等查询执行有截止时间和取消条件的有限重试；
  • DataNotFound 进入无高精数据路径，不解释为临时等待；
  • 关闭时先停止新调用和重试，再调用 shutdown()；其返回后不再使用该服务句柄。

状态含义、导航协作信号和 DataError 恢复见错误处理与可观测性，数据版本和运行模式见数据与版本管理。

5. 按能力继续集成

能力 示例
局部地图查询 查询并遍历局部 Lane Group
路线关联与前路 消费路线关联与前路结果
交通 查询 Lane Group 交通

应用从 Lane Group 结果读取哪些对象和字段，见核心能力与数据模型。