地图管理

地图的加载、建图和管理功能。

地图操作

加载地图

load_map(map_name, auto_reload=True, block=False, timeout=30)

Load an existing map from the map resource directory.

Parameters:

map_name (str) – Name of the map to load (must exist in /root/data/daystar_api/maps)
auto_reload (bool) – Deprecated and kept only for backward compatibility (default: True). The navigation stack dropped /nav/relo_load_map, so the map is always loaded the same way regardless of this flag; passing False only logs a warning.
block (bool) – If True, block until the underlying reload service returns (up to the internal max wait); if False, use timeout (default: False)
timeout (int) – Timeout in seconds; only effective when block=False (default: 30)

Return type:

LoadMapResponse

Returns:

LoadMapResponse.

Examples:

# Load a map
result = load_map("office_floor1")
if result.response.success:
    print("Map loaded successfully")

# Load map with custom timeout (non blocking wait)
result = load_map("large_map", block=False, timeout=60)

# Switch between maps
available = get_available_maps()
for map_name in available.maps:
    print(f"Available: {map_name}")
load_map("office_floor2")

Note

auto_reload has no effect anymore; do not rely on it to distinguish permanent and temporary map switching.
建图会话进行中会拒绝切图（切图意味着丢弃正在建的图）：须先 stop_mapping 保存或放弃本次建图，再加载目标地图；导航任务进行中同样拒绝切图。

底层 ROS2 接口

通道 1（仅 ``auto_reload=False`` 时先调，切换重定位地图）:
- 类型: Service daystar_navigation_msgs/srv/LoadMap
- 名称: /nav/relo_load_map
- 参数映射:
封装参数

原生字段（Request）

map_name

request.map_dir（floor / init_pose 留默认）

timeout

客户端行为，不下发（等待服务响应的时长）

通道 2（切换定位地图，始终调用）:

类型: Service daystar_navigation_msgs/srv/LoadMap
名称: /nav/load_map
参数映射:

封装参数	原生字段（Request）
`map_name`	`request.map_dir`（`floor` / `init_pose` 留默认）
`block` / `timeout`	客户端行为，不下发（`block=True` 等到内部上限，否则等 `timeout` 秒）

获取可用地图

get_available_maps(timeout=30)

Get all available maps from the map resource directory.

Parameters:: timeout (int) – Timeout in seconds for query (default: 30)
Return type:: GetAvailableMapsResponse
Returns:: GetAvailableMapsResponse.

Examples:

# Get all available maps
result = get_available_maps()
if result.success:
    print("Available maps:")
for map_name in result.maps:
    print(f"  - {map_name}")

# Get maps with custom timeout
result = get_available_maps(timeout=10)

# Check if specific map exists before loading
result = get_available_maps()
if "office_map" in result.maps:
    load_map("office_map")
else:
    print("Map not found")

# List and select map interactively
maps = get_available_maps()
if maps.success:
    for i, name in enumerate(maps.maps):
    print(f"{i+1}. {name}")
load_map(maps.maps[selection])

底层 ROS2 接口

类型: Service daystar_navigation_msgs/srv/ListMaps
名称: /nav/list_maps
参数映射:

封装参数	原生字段（Request）
（无业务参数）	Request 为空（服务端返回 `maps` 列表，封装层转为 `map_names` / `maps`）
`timeout`	客户端行为，不下发（等待服务响应的时长）

建图模式

开始建图

start_mapping(timeout=120, enable_loop_closure=True)

Start SLAM mapping mode to create a new map.

Parameters:

timeout (int) – Timeout in seconds for mapping mode to start (default: 120)
enable_loop_closure (bool) – 是否开启闭环检测，默认 True。仅建图模式有效；开启会存储局部地图（最长 15min），关闭退化为纯里程计、适合长时运行。（默认: True）

Return type:

StartMappingResponse

Returns:

StartMappingResponse. response.already_mapping 为 True 表示拒绝：调用时已在建图会话，本次未启动（success=False；不清暂存点、不改闭环配置，enable_loop_closure 入参被忽略）。

Examples:

result = start_mapping()
if result.response.success:
    print("Mapping mode started")
# Drive robot around to build map
time.sleep(300)
stop_mapping("new_map")

# Start mapping with custom timeout
result = start_mapping(timeout=180)

# Start mapping without loop closure (long-duration odometry mode)
result = start_mapping(timeout=180, enable_loop_closure=False)

# Complete mapping workflow
if start_mapping().response.success:
    print("Drive the robot to map the area...")
stop_mapping("office_map", auto_reload=True)

Note

enable_loop_closure=True 时后端存储局部地图帧用于回环检测，最多持续 15 分钟；False 时退化为纯里程计建图，适合超长距离建图场景。

底层 ROS2 接口

通道 1（切入 SLAM 模式）:
- 类型: Service daystar_navigation_msgs/srv/SetLocalizationMode
- 名称: /nav/set_localization_mode
- 参数映射:
封装参数

原生字段（Request）

（固定值）

request.localization_mode = 1（SLAM）

timeout

客户端行为，不下发（等待服务响应的时长）
通道 2（仅 ``enable_loop_closure=False`` 时追加，关闭闭环检测）:
- 类型: Service std_srvs/srv/SetBool
- 名称: /nav/trigger_loop
- 参数映射:
封装参数

原生字段（Request）

enable_loop_closure

request.data = False（仅显式关闭时下发；True 时不调用，依赖后端默认开启）
说明: 另含纯本地动作——清除上次建图会话残留的暂存点位（points/.mapping_session/），不经 ROS2。

停止建图

stop_mapping(map_name, auto_reload=True, need_2d_map=True, block=True, timeout=30)

Stop SLAM mapping, save the map, and switch back to MAP mode.

Parameters:

map_name (str) – Name for the saved map
auto_reload (bool) – 存图后是否自动加载新地图（default: True）。置 False 时只保存地图并切回 MAP 模式，导航栈继续用原地图，也不做停图后快速重定位；新图上的点位需 load_map 之后才可见
need_2d_map (bool) – If True, generate 2D map in addition to 3D map; if False, only save 3D map (default: True)
block (bool) – If True, block until the underlying save service returns (up to the internal max wait); if False, use timeout (default: True)
timeout (int) – Timeout in seconds; only effective when block=False (default: 30)

Return type:

StopMappingResponse

Returns:

StopMappingResponse. response.map_saved 标记本次是否真正保存了地图—— 若建图会话以 enable_loop_closure=False 启动（纯里程计模式，不积累地图数据），则无图可存，本调用只切回 MAP 模式，map_saved=False``（success 仍为 True）。失败语义：存图失败时放弃会话并尝试切回 MAP，``response.mode_reverted 标记是否切回成功（False=仍卡 SLAM）；调用时不在建图会话则直接拒绝，response.not_mapping=True。

Examples:

# Stop mapping and save (with 2D map); the new map is loaded automatically
result = stop_mapping("warehouse_map")
if result.state.code == 0 and result.response.map_saved:
    print(f"Map saved: {result.response.message}")

# Stop mapping without 2D map generation
result = stop_mapping("new_office_map", auto_reload=True, need_2d_map=False)

# Non-blocking save with custom timeout
result = stop_mapping("quick_map", block=False, timeout=60)

# Complete mapping session with all options
start_mapping()
print("Drive robot to map the area...")
input("Press Enter when done")
result = stop_mapping("my_map", auto_reload=True, need_2d_map=True, block=True)
if result.state.code == 0:
    print("Mapping complete, new map loaded")

# Fast save without waiting for 2D map generation
result = stop_mapping("temp_map", auto_reload=True, need_2d_map=False, block=False, timeout=30)

底层 ROS2 接口

auto_reload 决定存图后是否加载新地图（默认 True）。置 False 时跳过下方通道 3：地图照常保存、照常切回 MAP 模式，但导航栈继续用原地图，停图后的快速重定位也一并跳过（新图上的点位要等显式 load_map 后才可见）。

按顺序调用（若建图会话以 enable_loop_closure=False 启动，则跳过通道 1 与通道 3，仅走通道 2 切回 MAP 模式，map_saved=False）：

通道 1（保存地图）:

类型: Service daystar_navigation_msgs/srv/SaveMap
名称: /nav/slam/save_map
参数映射:

封装参数	原生字段（Request）
`map_name`	`request.file_destination = "/root/data/daystar_api/maps/<map_name>"`
`need_2d_map`	`request.need_2d_map`
（固定值）	`request.resolution = 0.05`
`block` / `timeout`	客户端行为，不下发（`block=True` 等到内部上限，否则等 `timeout` 秒）

通道 2（切回 MAP 模式）:
- 类型: Service daystar_navigation_msgs/srv/SetLocalizationMode
- 名称: /nav/set_localization_mode
- 参数映射: 固定 request.localization_mode = 0（MAP）； block / timeout 为客户端行为
通道 3（重载新图，仅 ``auto_reload=True`` 时调用）:
- 类型: Service daystar_navigation_msgs/srv/LoadMap
- 名称: /nav/load_map
- 参数映射: map_name → request.map_dir（floor / init_pose 留默认）；block / timeout 为客户端行为
说明: 另含纯本地动作——地图保存成功后把建图会话暂存点位（points/.mapping_session/）迁移到 points/<map_name>/，不经 ROS2。

切换定位模式

set_localization_mode(localization_mode, block=True, timeout=30)

切换定位模式（0=MAP 地图定位、1=SLAM 建图、2=REFLECTOR 反光柱定位）。

用途：单独恢复 MAP 定位模式（如建图后未自动切回、或需要从反光柱定位切回地图定位）。

Parameters:

localization_mode (int) – 目标模式：0=MAP（地图定位）、1=SLAM（建图）、2=REFLECTOR（反光柱定位）
block (bool) – True 则阻塞等待底层切换服务返回（内部最大等待上限）；False 时用 timeout 作轮询上限（默认: True）
timeout (int) – 超时秒数，仅 block=False 时生效（默认: 30）

Return type:

SetLocalizationModeResponse

Returns:

SetLocalizationModeResponse.

Examples:

# 切回地图定位模式
result = set_localization_mode(0)
if result.response.success:
    print("已切回 MAP 模式")

# 切到反光柱定位
result = set_localization_mode(2)

Note

常规建图请用 start_mapping / stop_mapping（含闭环配置、打点会话与地图保存管理），不要用本接口切 SLAM。
切换离开 SLAM 而未经 stop_mapping 保存地图时，建图期间打的暂存点位会被清除（无图可归属）。

底层 ROS2 接口

类型: Service daystar_navigation_msgs/srv/SetLocalizationMode
名称: /nav/set_localization_mode
参数映射:

封装参数	原生字段（Request）
`localization_mode`	`request.localization_mode`（0=MAP / 1=SLAM / 2=REFLECTOR）
`block` / `timeout`	客户端行为，不下发（`block=True` 等到内部上限，否则等 `timeout` 秒）

说明: 切换成功后另含纯本地动作——同步维护建图会话状态与暂存点位（进 SLAM 清残留、离开 SLAM 清孤儿暂存点），不经 ROS2。

地图管理

地图操作

加载地图

获取可用地图

建图模式

开始建图

停止建图

切换定位模式

相关数据类型