mapoi_server

English version (primary): README.md 本ファイルは日本語スナップショットです。最新の内容は英語版を参照してください。

mapoi のメインパッケージです。 地図と POI の情報を管理し、他のパッケージにサービスとして提供します。また、POI 名を指定した自律走行やPOI半径イベントの検知を行います。

自分のロボットへの組み込み方

4 つの core node (mapoi_server / mapoi_nav2_bridge / mapoi_amcl_localization_bridge / mapoi_rviz2_publisher) と、必要に応じてシミュレータ連動 bridge をまとめて起動する bringup launch を提供しています。自前の launch から以下のように include してください:

- include:
    file: "$(find-pkg-share mapoi_server)/launch/mapoi_bringup.launch.yaml"
    arg:
      - {name: maps_path, value: "/path/to/your/maps"}    # REQUIRED
      - {name: map_name, value: "initial_map_name"}        # REQUIRED
      - {name: config_file, value: "mapoi_config.yaml"}    # optional
      - {name: state_path, value: "/var/lib/mapoi"}        # optional (実機運用では推奨、#297)
      - {name: simulator, value: "none"}                   # gazebo|gz|none (default: none)
      - {name: robot_entity_name, value: "burger"}         # simulator=gazebo|gz のとき必要
      - {name: robot_sdf_path, value: "/path/.../model.sdf"} # simulator=gazebo のとき必要
      - {name: init_world_name, value: "default"}          # simulator=gz のとき必要 (gz_sim 起動時の world 名)

maps_path と map_name は 必須 です。maps_path 未指定 / 存在しないパス / ディレクトリでない場合は RCLCPP_FATAL ログ + 終了コード 1 で起動失敗します (#163)。mapoi_turtlebot3_example の sample を流用するなら $(find-pkg-share mapoi_turtlebot3_example)/maps を指定してください。

CLI から直接起動する例

include せず ros2 launch を直接叩く場合の最小例:

# mapoi_turtlebot3_example の sample maps を流用 (apt / 配布 install 後にも動く)
ros2 launch mapoi_server mapoi_bringup.launch.yaml \
  maps_path:=$(ros2 pkg prefix --share mapoi_turtlebot3_example)/maps \
  map_name:=turtlebot3_world

# ソースツリーから直接 (ros2_ws 内で source 後)
# 注: 本 repo を `<ws>/src/mapoi/` に clone している前提 (ws 直下で `git clone .../mapoi.git src/mapoi`)。
# パッケージを `<ws>/src/mapoi_turtlebot3_example/` のようにフラット展開している場合は
# パスを調整するか、上の `pkg prefix --share` 形式を使う方が確実。
ros2 launch mapoi_server mapoi_bringup.launch.yaml \
  maps_path:=$(pwd)/src/mapoi/mapoi_turtlebot3_example/maps \
  map_name:=turtlebot3_dqn_stage1

引数の取り違え注意

各 launch arg のセマンティクスは以下のとおり ({maps_path}/{map_name}/{config_file} でアクセスする 3 レベルの分割):

実際にロードされるパスは {maps_path}/{map_name}/{config_file} で、上記例なら /path/to/maps/turtlebot3_world/mapoi_config.yaml となります。

maps_path / map_name 必須 (上節参照) の検証は 2 段階: map_name 自体未指定なら ros2 launch が Required launch argument 'map_name' was not provided で fail (node 起動前 / launch system 側)、maps_path がディレクトリでない等のセマンティクス違反は mapoi_server ノード起動時に RCLCPP_FATAL で fail します。

❌ よくある間違い: maps_path に config.yaml ファイルパスを直接指定 してしまう:

# WRONG: maps_path はファイルではなくディレクトリ
ros2 launch mapoi_server mapoi_bringup.launch.yaml \
  maps_path:=./maps/turtlebot3_dqn_stage1/mapoi_config.yaml \
  map_name:=turtlebot3_dqn_stage1

→ 起動時に mapoi_server ノードが以下を 1 行で出力して FATAL 終了します (mapoi_server.cpp 内の RCLCPP_FATAL の実ログ文字列そのまま・英日混在):

[FATAL] maps_path '...mapoi_config.yaml' does not exist or is not a directory. 正しい maps ディレクトリ path を指定してください (例: $(find-pkg-share mapoi_turtlebot3_example)/maps)。

maps_path は 地図群を束ねる親ディレクトリ で、特定の地図ディレクトリやファイルではありません。ディレクトリ構成は本 README 末尾の ディレクトリ構成 節を参照してください。

simulator arg はシミュレータ連動 bridge の起動を制御します:

• gazebo (Gazebo Classic / Humble): mapoi_gazebo_bridge を起動。operator map switch 時に Gazebo 内の world_model entity を入れ替え + ロボットを delete + spawn で POI list 先頭 の座標に再生成 (#144 で旧 initial_pose system tag を廃止し、yaml 順序で表現する semantics に変更)
• gz (gz-sim / Jazzy): mapoi_gz_bridge + parameter_bridge (ros_gz_bridge) を起動。operator map switch 時に gz-sim 内の world_model entity を入れ替え + ロボットを SetEntityPose で POI list 先頭 の座標に teleport (gz-sim では Classic と異なり set_pose service が使えるため delete + spawn は不要)
• none (default): bridge 起動なし (実機運用)

Web UI も使う場合は mapoi_webui.launch.yaml も併せて include:

- include:
    file: "$(find-pkg-share mapoi_webui)/launch/mapoi_webui.launch.yaml"
    arg:
      - {name: maps_path, value: "/path/to/your/maps"}
      - {name: map_name, value: "initial_map_name"}

NOTE: mapoi_webui はシステムタグを mapoi_server の mapoi/get_tag_definitions service 経由で取得します。mapoi_webui 単体を起動しても system tags の表示は service 通信になるため、mapoi_server の package install 自体は不要 (ただし service responder として mapoi_server ノードが起動している必要あり)。

TurtleBot3 を使った動作例は mapoi_turtlebot3_example パッケージを参照してください。

ノード

mapoi_server

File truncated at 100 lines see the full file

Changelog for package mapoi_server

This per-package file lists only the changes affecting mapoi_server (including its mapoi_nav2_bridge / mapoi_amcl_localization_bridge / mapoi_rviz2_publisher / mapoi_gazebo_bridge / mapoi_gz_bridge nodes), in the flat format expected by bloom / buildfarm. Full project-level narrative: root CHANGELOG.rst / the GitHub Releases page.

Forthcoming

0.6.0 (2026-07-15)

• mapoi_rviz2_publisher: rebuild the marker arrays only when the underlying data changed (POIs, routes, highlights, display parameters), republishing the cached arrays with a refreshed stamp on unchanged ticks — the 1 Hz republish itself is kept so late-joining volatile subscribers still receive markers — and skip the tick entirely while both marker topics have zero subscribers (#402).

0.5.0 (2026-07-10)

• Add the request_initial_pose service on mapoi_server as the sole writer of mapoi/initialpose_poi; other nodes request a publish instead of publishing directly, unifying the latched cache (#211).
• Reject request_initial_pose when a non-empty map_name does not match the server's current map, closing the stale-initial-pose map-switch race (#299).
• Optionally persist and restore the last-selected map across a restart via the new state_path parameter (default empty = disabled), avoiding a teleport to the launch-parameter map's POI (#297).
• Validate the select_map service map_name as a single path segment, rejecting path-traversal config loads (#328).
• Namespace all eight mapoi_server services under mapoi/ (e.g. get_pois_info -> mapoi/get_pois_info); no compatibility alias (#341).
• Return success=false from get_route_pois (GetRoutePois) for an unknown route instead of silently returning empty lists; mapoi_nav2_bridge / mapoi_rviz2_publisher check response.success (#342).
• Add waypoint_arrival_mode parameter ("nav2" default / "mapoi") on mapoi_nav2_bridge; "mapoi" sends per-waypoint NavigateToPose goals and advances on tolerance match (#243, #259, #260, #261, #263, #264, #265, #266).
• Add topic mapoi/nav/command_rejected (std_msgs/String) on mapoi_nav2_bridge as an unconditional rejected-command event, independent of the latched mapoi/nav/status (#354).
• Add auto_resume_timeout_sec parameter (default 0.0 = disabled) on mapoi_nav2_bridge to auto-resume a paused route after a timeout (#231, #232).
• Publish rejected:<target> on mapoi/nav/status for commands rejected while idle (unknown goal/route, landmark-as-goal, service not ready) so operators can see they were ignored (#339, #355, #352, #356).
• Fix Jazzy EVENT_PAUSED no longer firing by adding a cmd_vel_msg_type parameter (default "auto") that selects Twist vs TwistStamped from ROS_DISTRO (#249).
• Narrow PoiEvent publishing to ROUTE navigation only (waypoints/landmarks on the active route), remove EVENT_STOPPED / EVENT_RESUMED, add EVENT_PAUSED firing on a real cmd_vel dwell (#220, #227).
• Render a yaw-agnostic POI tolerance (tolerance.yaw >= pi) as a filled disc in mapoi_rviz2_publisher instead of omitting the sector (#267, #268, #271).
• Split mapoi_nav2_bridge.cpp (1,712 lines) into five translation units (route / goal / map-switch / backend-status / core) compiling into one executable; internal refactor, no behavior change (#345).

0.4.0 (2026-05-08)

• Rename the Nav2 bridge node from mapoi_nav_server to mapoi_nav2_bridge (executable, node, C++ class, header, and the with_nav_server -> with_nav2_bridge launch arg); no compatibility alias (#204).
• Split the AMCL adapter out of the bridge into a new mapoi_amcl_localization_bridge executable; the initialpose_* parameters and /initialpose publishing move to it, and it publishes LocalizationBackendStatus (#209).
• Hardcode the system tag definitions in system_tags.hpp (mapoi::kSystemTags) and remove the maps/tag_definitions.yaml file / maps/ directory; get_tag_definitions contract unchanged (#191).
• Publish NavigationBackendStatus at 1 Hz on mapoi/nav/backend_status (transient_local QoS) as the navigation readiness contract (#198).
• Use MANUAL_BY_TOPIC liveliness (5 s lease) on both backend_status topics so consumers detect bridge death; reject infinite-lease publishers via QoS incompatibility (#208).
• Keep the 1 Hz backend_status publish running during blocking LoadMap calls by moving the timer to a separate callback group under a MultiThreadedExecutor (#213).
• mapoi_gazebo_bridge: fix AMCL drift on operator map switch by teleporting via Gazebo Classic delete_entity + spawn_entity to the first non-landmark POI (#91, #200).
• Add CLI launch examples and maps_path / map_name argument semantics to mapoi_server/README.md (#172).

0.3.0 (2026-05-02)

File truncated at 100 lines see the full file