导航模块 - 量子一号Pro 1.0

能力概览

导航模块提供机器人地图构建、地图保存和定位管理能力，支持启动或停止建图、将地图保存至机器人本体，以及基于已有地图启动或停止定位。同时支持切换机器人内置导航模式与用户自定义导航模式，便于开发者根据实际场景选择导航能力的实现方式。

start_mapping 接口介绍

字段	内容
函数名	start_mapping()
函数原型	def start_mapping(timeout) -> ExecutionResult
功能概述	开始建图
参数	无
返回值	ExecutionResult
备注	无

示例：

robot.navigation.start_mapping()

stop_mapping 接口介绍

字段	内容
函数名	stop_mapping()
函数原型	def stop_mapping(save_map_param: SaveMapParam, timeout) -> ExecutionResult
功能概述	停止建图并保存地图
参数	save_map_param: SaveMapParammap_name：保存的地图名称，目前只支持将地图保存在机器人本体上
返回值	ExecutionResult
备注	无

示例：

robot.navigation.stop_mapping(
    SaveMapParam(map_name="test")
)

set_navigation_mode 接口介绍

字段	内容
函数名	set_navigation_mode()
函数原型	def set_navigation_mode(navigation_mode_param: NavigationModeParam, timeout) -> ExecutionResult
功能概述	设置导航模式
参数	navigation_mode_param: NavigationModeParammode：导航模式BUILT_IN_NAVIGATION：机器人内置导航模式USER_CUSTOM_NAVIGATION：关闭内置导航，由用户自主实现导航控制
返回值	ExecutionResult
备注	无

示例：

robot.navigation.set_navigation_mode(
    NavigationModeParam(
        mode=NavigationMode.USER_CUSTOM_NAVIGATION
    )
)

start_localization 接口介绍

字段	内容
函数名	start_localization()
函数原型	def start_localization(start_localization_param: StartLocalizationParam, timeout) -> ExecutionResult
功能概述	基于特定地图启动定位
参数	StartLocalizationParam.name：用于启动定位的地图名称
返回值	ExecutionResult
备注

示例：

result = robot.navigation.start_localization(StartLocalizationParam(map_name=map_name, use_init_pose=False))
print(f"start localization success: {result.is_success}")

stop_localization 接口介绍

字段	内容
函数名	stop_localization()
函数原型	def stop_localization(timeout) -> ExecutionResult
功能概述	停止定位
参数	无
返回值	ExecutionResult
备注	无

示例：

robot.navigation.stop_localization()

cancel_navigation 接口介绍

字段	内容
函数名	cancel_navigation()
函数原型	def cancel_navigation(timeout=None) -> ExecutionResult
功能概述	取消当前导航任务。
参数	timeout：可选，RPC 超时时间，单位为秒；None 表示本次调用不显式设置超时。
返回值	ExecutionResult： is_success：是否成功； error_message：失败信息； error_code：失败原因分类。
备注	该接口只取消当前导航任务，不删除地图，也不停止定位服务。没有可取消任务时，以返回结果为准。连接中断或 RPC 超时时，调用可能抛出 gRPC 连接异常。

示例：

result = robot.navigation.cancel_navigation(timeout=10)

if result.is_success:
    print("cancel navigation success")
else:
    print(
        "cancel navigation failed: "
        f"error_code={result.error_code}, "
        f"error_message={result.error_message}"
    )

load_map 接口介绍

字段	内容
函数名	load_map()
函数原型	def load_map(map_name: str, map_path: str) -> TransferResult
功能概述	将 SDK 客户端电脑上的地图目录打包并上传到机器人。
参数	map_name：地图名称，应使用名称而不是路径；不要包含 /、\ 或 ..，也不要以 . 开头。 map_path：SDK 客户端电脑上的地图父目录，不是机器人端路径。接口实际读取 <map_path>/<map_name>/。
返回值	TransferResult： success：是否成功打包并上传； message：失败原因，成功时通常为空。
备注	客户端必须存在非空目录 <map_path>/<map_name>/。目录中的符号链接和硬链接不会被打入地图包。机器人端不能同时执行另一项地图导入或导出操作。路径、打包、传输或机器人端处理失败时，通常通过 success=False 和 message 返回。

示例：

# 读取客户端电脑上的 /home/user/maps/office_1/
result = robot.navigation.load_map(
    map_name="office_1",
    map_path="/home/user/maps",
)

if result.success:
    print("load map success")
else:
    print(f"load map failed: {result.message}")

export_map 接口介绍

字段	内容
函数名	export_map()
函数原型	def export_map(map_name: str, target_path: str) -> TransferResult
功能概述	从机器人下载指定地图，并解压到 SDK 客户端电脑。
参数	map_name：机器人中已存在的地图名称，应使用名称而不是路径；不要包含 /、\ 或 ..，也不要以 . 开头。 target_path：SDK 客户端电脑上的目标父目录，不是机器人端路径。接口实际写入 <target_path>/<map_name>/。
返回值	TransferResult： success：是否成功下载并解压； message：失败原因，成功时通常为空。
备注	机器人中必须存在指定地图。target_path 和已存在的 <target_path>/<map_name> 必须是目录。建议导出到不存在或内容为空的地图目录，避免与旧文件混合。机器人端不能同时执行另一项地图导入或导出操作。

示例：

result = robot.navigation.export_map(
    map_name="office_1",
    target_path="/home/user/exported_maps",
)

if result.success:
    print("map exported to /home/user/exported_maps/office_1")
else:
    print(f"export map failed: {result.message}")

get_map_list 接口介绍

字段	内容
函数名	get_map_list()
函数原型	def get_map_list(timeout: Optional[float] = None) -> GetMapListResponse
功能概述	查询机器人中已保存的地图名称列表。
参数	timeout：可选，RPC 超时时间，单位为秒；None 表示本次调用不显式设置超时。
返回值	GetMapListResponse： header：调用状态，通过 is_success、error_code 和 error_message 判断； map_list：地图名称列表，没有地图时为空列表。
备注	map_list 只包含地图名称，不是客户端或机器人文件系统路径。连接中断或 RPC 超时时，调用可能抛出 gRPC 连接异常。

示例：

result = robot.navigation.get_map_list(timeout=10)

if result.header is not None and result.header.is_success:
    print("saved maps:")
    for map_name in result.map_list:
        print(f"- {map_name}")
else:
    error_code = result.header.error_code if result.header is not None else "UNKNOWN"
    error_message = (
        result.header.error_message
        if result.header is not None
        else "response header is missing"
    )
    print(
        "get map list failed: "
        f"error_code={error_code}, error_message={error_message}"
    )

本页内容