Wiki
map_server（已有二維地圖加載與發佈）
本文由簡體中文內容確定性轉換，並受版本化術語表保護。
1.map_server（已有二維地圖加載與發佈）
1.1.實車先看：空路徑由誰填寫，讀的是哪一張地圖
map_server讀取已有二維地圖的YAML及配套圖片，發佈OccupancyGrid給靜態代價層；當前工程通過launch的map參數填寫yaml_filename。 因此這裏的空字符串是啓動時重寫的佔位值，不能單看這行就判斷沒有地圖。
实物／仿真入口：map启动参数
→ bringup_launch → localization_launch
→ 重写map_server.ros__parameters.yaml_filename
→ map_server：读取地图YAML → 找到配套PGM／PNG → 转为二维占用网格
→ 配置、激活生命周期节点 → 发布namespace/map
→ local_costmap、global_costmap中的static_layer
prior_pcd_file → small_gicp：用实时三维点云匹配先验PCD，提供定位TF二維圖加載與三維PCD定位是不同的輸入鏈。map_server不讀取PCD，不把當前雷達點雲拿去匹配二維圖片，也不自行產生map→odom定位變換。兩種地圖仍須採用一致的尺度、方向和座標約定。二維圖與PCD的分工、先驗點雲定位
| 實車上看到的現象 | 先核對什麼 | 當前配置怎樣理解 |
|---|---|---|
| YAML路徑為空，卻能夠加載地圖 | launch傳入的map及有效yaml_filename | 當前重寫流程會替換已有空值；實際路徑來自啓動參數 |
| 修改nav2_params.yaml中的路徑，啓動後仍用舊圖 | 上層map啓動參數 | 當前launch總會用map值重寫該鍵；單改參數文件中的字符串可能被覆蓋 |
| 實物入口默認啓動失敗，提示找不到地圖 | 實物默認地圖文件是否存在 | 當前默認map/reality/rmul_2024.yaml在源碼和安裝目錄均不存在，需提供自己的有效二維圖 |
| 節點啓動了，/map卻沒有地圖消息 | 最終路徑、文件讀取及生命週期狀態 | 有節點／發佈器不等於已經加載並激活地圖；空路徑可以配置，但不會自動產生地圖 |
| 建圖時沒看到map_server | slam啓動分支 | slam=True使用slam_toolbox發佈/map；此節點在slam=False的定位分支啓動 |
| 圖片看起來灰色，加載後卻成了空閒 | 地圖文件的mode、free_thresh與像素灰度 | 保存和讀取的門檻不是同一計算；本版本三態灰205與0.25的組合有已驗證的未知狀態丟失問題 |
本次安裝的nav2_map_server為1.1.20，安裝的map_server／map_io頭文件與該版本一致。以下按此版本及當前工程啓動文件説明。MapServer實現
1.2.參數
保留髮送的參數與上方原註釋。註釋中的tb3_simulation_launch.py是通用示例名稱；當前工程實際使用rm_navigation_reality_launch.py、rm_navigation_simulation_launch.py、bringup_launch.py和localization_launch.py。
# The yaml_filename does not need to be specified since it going to be set by defaults in launch.
# If you'd rather set it in the yaml, remove the default "map" value in the tb3_simulation_launch.py
# file & provide full path to map below. If CLI map configuration or launch default is provided, that will be used.
map_server:
ros__parameters:
yaml_filename: ""1.2.1.ros__parameters（地圖文件入口）
1.2.1.1.參數表
| 參數名 | 當前值 | 單位 | 實車處理建議 | 作用 | 調大效果 | 調小效果 | 生效條件／備註 |
|---|---|---|---|---|---|---|---|
yaml_filename |
""；整套啓動時由map參數重寫 |
不適用，地圖YAML文件路徑字符串 | 上實物前必須核對並正確配置 | 指定初始加載的二維地圖元數據文件 | 不適用 | 不適用 | 當前可保留空值佔位，通過map:=實際絕對路徑配置；文件與圖片均需存在；直接啓動並留空則不加載初始地圖 |
1.2.1.2.參數詳解
1.2.1.2.1.yaml_filename（節點參數文件與地圖文件是兩種YAML）
nav2_params.yaml是ROS節點參數文件，裏面有map_server、map_saver、costmap等參數分組。yaml_filename指向的是一張二維地圖的元數據YAML，其中寫image、resolution、origin等；不能把它設成nav2_params.yaml本身，也不能直接指向PGM、PNG或PCD。
1.1.20在configure階段讀取yaml_filename。非空時讀取地圖YAML和圖片，失敗會使配置過程失敗；空字符串則跳過初始加載，建立話題與服務，允許之後通過load_map服務裝入地圖。空字符串不表示自動建圖、不表示讀取當前目錄的某張圖，也不表示使用PCD替代二維圖。初始加載與空路徑分支
當前安裝的RewrittenYaml只替換已有葉子鍵，bare key形式的yaml_filename重寫不會自動補入缺失鍵。保留yaml_filename這一行，空值可交給launch填寫；不能按註釋把整個鍵刪掉。 MapServer源碼聲明的是字符串類型而不是一個自動場地路徑默認值，路徑默認來自工程launch。1.1.20參數重寫
1.2.1.2.2.當前launch怎樣決定最終地圖
| 啓動位置 | map參數來源 | 對yaml_filename的作用 |
|---|---|---|
| rm_navigation_reality_launch.py | 用户map:=路徑；未指定時按world生成share/map/reality/場地名.yaml | 傳給bringup；當前world缺省rmul_2024 |
| rm_navigation_simulation_launch.py | 用户map:=路徑；未指定時按world生成share/map/simulation/場地名.yaml | 傳給bringup；當前world缺省rmuc_2025 |
| bringup_launch.py | 接收上層map | 用RewrittenYaml重寫已有yaml_filename，再傳給定位分支 |
| localization_launch.py | 接收map，單獨啓動時此參數無默認值 | 再用map重寫yaml_filename，獨立進程與組件兩種分支均加載結果 |
| 直接啓動map_server並提供節點參數 | 用户傳入yaml_filename | 未經過上述重寫時，直接使用節點得到的值；生命週期另需配置和激活 |
當前整套啓動以map啓動參數為準。 想改用自己的地圖，優先明確傳map:=地圖YAML的絕對路徑；修改nav2_params.yaml中的值並不能阻止兩處重寫。若要改成完全由節點參數文件決定，必須調整當前bringup與localization的重寫邏輯，並核對上層必需參數；不是隻去修改註釋提到的TB3文件。本文只記錄接線，沒有修改啓動文件。
實際重寫位置見bringup_launch.py、localization_launch.py。
1.2.1.2.3.本次默認文件檢查（實物默認圖尚未提供）
當前安裝包share目錄為：
/home/tungchiahui/UserFolder/MySource/ysu2026_rm_sentry/ysu2026_rm_sentry_nav/install/pb2025_nav_bringup/share/pb2025_nav_bringup| 默認入口 | 默認相對share目錄的路徑 | 本次靜態檢查 |
|---|---|---|
| 實物，world=rmul_2024 | map/reality/rmul_2024.yaml | 源碼和安裝副本均沒有該文件；當前源碼map/reality僅有reserve佔位文件 |
| 仿真，world=rmuc_2025 | map/simulation/rmuc_2025.yaml | 源碼和安裝副本均存在，配套rmuc_2025.pgm也存在 |
這是對當前這份工作空間和默認入口的文件檢查，不表示其他工作空間沒有實物圖，也不表示用户曾經指定的map路徑失敗。使用自己建的二維圖時，還要給prior_pcd_file選擇與之座標一致的PCD，不能只讓兩份文件名看起來相同。
當前仿真默認地圖元數據為：
image: rmuc_2025.pgm
mode: trinary
resolution: 0.05
origin: [-3.58, -9.44, 0]
negate: 0
occupied_thresh: 0.65
free_thresh: 0.25這裏只引用已有地圖文件説明格式，不是map_server的額外ROS參數。原文件見rmuc_2025.yaml。
1.2.1.2.4.地圖元數據（圖片如何變成真實座標和佔用值）
| 地圖文件字段 | 單位／含義 | 當前應怎樣核對 |
|---|---|---|
| image | 配套圖片路徑 | 相對路徑按地圖YAML所在目錄解析；搬移時需同時保留圖片，不能只複製YAML |
| resolution | m／圖片像素 | 決定真實平面格距；此例5 cm，不是定位精度；修改它會改變整圖物理尺度 |
| origin | [x米、y米、yaw弧度] | 第三個數是繞z的偏航角，不是z高度；載入的二維原點z設為0 |
| negate | 0／1，像素明暗是否反轉 | 此例0：深色表示較高佔用；不是把地圖座標軸反轉 |
| mode | trinary／scale／raw | trinary按閾值輸出0、100、-1；scale還表達中間值；raw按像素數直接解釋，不能隨意換模式後繼續按普通黑白圖理解 |
| free_thresh、occupied_thresh | 無量綱，像素換算後的佔用門檻 | 加載時讀的是本地圖文件的值，不讀取map_saver節點的default門檻 |
普通無透明通道灰度圖、negate=0、trinary時，令灰度g為0～255，則佔用比例為1−g/255；嚴格大於occupied_thresh設100，嚴格小於free_thresh設0，其餘設-1。保存時對輸入0～100佔用值採用另一套包含邊界的比較，不能把兩種門檻比較混寫。元數據解析與像素加載
本版本默認三態保存的未知灰205重新讀取時，1−205/255≈0.19608，小於0.25，會變成空閒0。 本次已直接用安裝的libmap_io在臨時文件中驗證：輸入未知-1，用trinary、0.25／0.65保存再讀取得到0；free改0.196後該未知格仍為-1。這個問題只針對滿足上述讀寫條件的圖片，不能據此斷言所有來源的地圖都丟未知。完整閾值條件、驗證數據和處理建議見map_saver。
1.2.1.2.5.與global_costmap和三維定位的幾何關係
前面global_costmap默認不滾動，StaticLayer會按/map元數據調整主圖尺寸、格距和平面原點；這裏加載哪張圖，直接決定它的有效網格，而不是由costmap中的初始0.05獨立決定。全局圖的尺寸接管
MapServer把origin第三個數寫入地圖四元數，但當前Nav2 1.1.20的StaticLayer平面網格主要使用origin.position.x／y與格距，非滾動合成按同格索引，不按任意origin yaw重新旋轉網格。當前示例yaw=0；若將地圖YAML改為非零yaw，應單獨核對消費者，不能認為所有節點都會自動正確旋轉。靜態層網格建立
frame_id只是消息座標系名稱。給圖片改原點、旋轉、裁剪或重採樣後，需同時考慮PCD定位和map↔odom；僅把frame_id寫成map不證明實際對齊。
1.2.2.相關源碼默認項（原YAML未顯式配置）
1.2.2.1.參數表
| 參數名 | 當前值 | 單位 | 實車處理建議 | 作用 | 調大效果 | 調小效果 | 生效條件／備註 |
|---|---|---|---|---|---|---|---|
topic_name |
map，MapServer默認 |
不適用，話題名稱 | 上實物前必須核對並正確配置 | 選擇完整OccupancyGrid發佈話題 | 不適用 | 不適用 | 相對名稱按節點namespace解析；例如/red_standard_robot1/map；需與兩張costmap的static_layer輸入一致 |
frame_id |
map，MapServer默認 |
不適用，座標系名稱 | 上實物前必須核對並正確配置 | 設置地圖消息header.frame_id | 不適用 | 不適用 | 不創建TF、不變換圖片或原點；當前應與全局網格、PCD定位約定一致 |
use_sim_time |
原分組未寫；標準ROS默認False | 不適用，布爾 | 上實物前必須核對並正確配置 | 決定MapServer填寫加載時間和消息時間戳時使用的時鐘 | 不適用 | 不適用 | 當前bare-key重寫只改已有鍵，沒有給本分組補入此鍵；仿真不能只憑入口True推斷本節點也True，外部覆蓋需另查 |
兩份節點參數文件的map_server段完全一致，均只有yaml_filename空字符串。當前默認接線未在此分組補入use_sim_time；在沒有其他覆蓋時標準默認為False，仿真入口傳True不會經該重寫自動補到這裏。此結論來自參數及啓動源碼，未對運行節點取快照；需要統一時間域時應顯式配置，再檢查有效參數。加載後的時間戳
1.2.3.生命週期、換圖與驗證範圍
1.2.3.1.發佈與服務
MapServer是生命週期節點。configure時加載初始圖並建立服務／發佈器；activate時發佈已加載完整圖。當前localization_launch的lifecycle_manager_localization管理map_server，autostart=True時自動配置、激活；單獨運行可執行程序不能只停在“進程已創建”。
完整地圖使用Transient Local、Reliable、KeepLast(1)，保留最近一張圖供兼容的晚加入訂閲者讀取。它不是週期性重讀磁盤或定時發佈新地圖；原文件改了不會自動熱更新。地圖發佈與激活
| 接口 | 默認名稱，帶機械人namespace時示例 | 行為 |
|---|---|---|
| 完整地圖話題 | /red_standard_robot1/map | 初始激活有圖時發佈；成功load_map後發佈新圖；保留最近完整圖 |
| GetMap服務 | /red_standard_robot1/map_server/map | 返回當前內存OccupancyGrid；Active狀態才處理；Active但尚未加載圖時不能當作已有有效地圖 |
| LoadMap服務 | /red_standard_robot1/map_server/load_map | 請求map_url加載地圖YAML；Active狀態才處理，成功後更新內存併發布新圖 |
當前MapServer沒有為yaml_filename、topic_name、frame_id建立運行中重讀／重建的參數回調。參數設置成功不代表換圖成功；換圖應走LoadMap服務或重新配置／重啓。服務加載成功也不自動更換small_gicp的目標PCD，切換場地時還要同步定位目標與座標約定。服務加載
1.2.3.2.本次核對與後續實物檢查
- 本次已核對： nav2_map_server 1.1.20及安裝頭文件；兩套節點參數與安裝副本一致；五份相關launch與安裝副本一致；實際map重寫接線；實物默認地圖缺失、仿真默認YAML／圖片存在。
- 本次離線驗證： 在臨時目錄直接調用已安裝地圖IO庫完成小地圖保存／讀取，確認trinary灰205、free=0.25會丟未知身份，0.196的對應例子保留；未啓動ROS地圖節點、話題或服務，未寫入工程地圖目錄。
- 源碼能確認： 空路徑分支、configure／activate行為、完整圖QoS、Active服務條件、相對圖片路徑解析、地圖元數據含義，以及參數重寫與運行中換圖的邊界。
- 實物待核實： 啓動時實際map與有效yaml_filename、二維圖／PCD對齊、圖中未知區域保存和重新加載、時間域、生命週期狀態及靜態層的有效地圖元數據；本次未運行整套導航或進行實車驗證。