pointcloud_to_laserscan（三維地形點雲轉二維掃描）

1.pointcloud_to_laserscan（三維地形點雲轉二維掃描）

1.1.實車先看：哪些三維點會被畫進二維地圖

當前建圖鏈為：

terrain_map_ext（odom系地形点）
    → pointcloud_to_laserscan（转到底盘系，筛选并投影）
    → obstacle_scan（base_footprint系二维扫描）
    → slam_toolbox（二维建图）

這個節點在整套 slam:=True 啓動中使用。已有地圖導航 slam:=False 不走這個入口；當前局部／全局代價地圖直接使用地形點雲，並非依靠這份二維掃描更新障礙。

掃描以 base_footprint 原點為中心，方向按底盤系表達。 輸入雖來自MID360，卻不是原始雷達點雲，而是 terrain_map_ext；其中 intensity 已被改成相對估計地面的高差，單位m，不是雷達反射強度。

1.2.參數

1.2.1.ros__parameters（ROS節點參數）

1.2.1.1.參數表

前13項對應當前實物 YAML；仿真僅 use_sim_time=True。另外列出源碼默認的3項，明確TF等待與無回波編碼的條件。

pointcloud_to_laserscan:
  ros__parameters:
    use_sim_time: False
    target_frame: base_footprint
    min_height: -0.5
    max_height: 6.0
    min_intensity: 0.1
    max_intensity: 2.0
    angle_min: -3.1415926                   # 约 -π，-180°
    angle_max: 3.1415926                    # 约 +π，+180°
    angle_increment: 0.00872665             # 约 π/360，0.5°
    scan_time: 0.05
    range_min: 0.3
    range_max: 10.0
    use_inf: true

原配置把 angle_min/max 的註釋寫成 ±π/2，與數值不符；當前數值對應約±π，掃描角域約360°，不是180°。

1.2.1.2.參數詳解

1.2.1.2.1.target_frame：掃描的中心和方向是底盤，不是雲台或雷達

當前輸入 terrain_map_ext 的點座標在odom中；轉換使用輸入消息時間戳對應的 base_footprint←odom，隨後以轉換後的x、y、z篩選。輸出 obstacle_scan.header.frame_id 為base_footprint，時間戳沿用輸入。

平面角度以該系+x為0，繞+z逆時針為正；距離以該系原點計算。它與 fake_vel_transform 最終按雲台系表達的速度指令是兩條不同接口：這裏處理測距輪廓，沒有給底盤或雲台下運動指令。

因此這是底盤原點上的虛擬二維掃描，不是MID360原點上的真實激光束。MID360與底盤有安裝偏移，不能把range_min理解成“離雷達外殼0.3 m”。輸入是累積地形結果，含不同時間、不同高度的點；同一角度格只留最近的合格點，也不重新驗證從底盤虛擬中心到該點是否存在真實光路或遮擋。

正確的上游配準和機械TF應讓獨立雲台yaw轉動後的靜態環境仍轉換到底盤方向；不能對這份點再手工重複加一個雲台角。MID360掛在gimbal_yaw、隨yaw不隨pitch轉動，兩條odom關節固定的機械約定繼續適用。

base_footprint 這個名字不會自動把TF中的z、roll、pitch清零。當前sensor_scan_generation保留完整三維位姿，所以投影是該系的x-y平面；上坡時它是否真正與地面投影／預期水平面對應，需要核對參考系定義及上游姿態，不能僅憑名稱判斷。

若target_frame設空，源碼不轉換點，直接在輸入系中計算。當前輸入為odom，這就變成以odom原點和方向作虛擬中心；機械人移動後，它不等價於仍以底盤為中心投影。

1.2.1.2.2.min_height、max_height 與兩項intensity：兩把不同的尺

高度窗口看 z_base_footprint，即點相對底盤原點、沿底盤z軸的座標；高差窗口看 intensity，即上游地形分析給出的“離估計地面多遠”。它們單位都是m，但基準不同。

假設上游已保留這些點，其他條件也滿足：

所以遠處下坡點即使通過擴展地形節點隨距離放寬的窗口，仍可能在這裏被固定下界刪掉。上坡、下坡是否連續可見，要同時看target_frame的方向與高度窗口；disRatioZ 不會替本節點放寬範圍。

min_intensity=0.1 把10 cm作為進入二維障礙輪廓的高差下限，不是説車輛能跨10 cm台階。降低它可能看見更低障礙，也可能把正常地面或坡面誤差畫進地圖；提高它會減少小高差輪廓，卻可能漏掉對實車危險的低障礙。遠場地形高差取絕對值，坡面較低一側也可能過門檻；近場目前忽略負高差，4 m交接處的差異仍會傳入掃描。

max_height=6.0 的窗口很寬。若高處橫樑等點通過上游和高差篩選，就會被壓到二維地圖中，即使車本來能從下面通過也可能形成障礙輪廓。應該根據底盤、雲台活動包絡與懸空結構核對要保留的高度，不能把它當模型尺寸；同時也不能只調小上限而漏掉障礙唯一可見的部位。

當前正常地形輸出近場高差低於0.5 m、遠場低於1 m，因此max_intensity=2 m通常不額外刪點；這不表示參數沒被讀取。若換輸入、調整上游或出現其他標記點，效果會改變。高度與高差門檻使用“小於下界／大於上界則刪除”，邊界值可通過。

本地實現要求float類型的XYZ與intensity字段；沒有intensity字段的點雲不能直接套用。若接原始雷達點，intensity可能恢復為反射強度，這時0.1／2.0不再代表10 cm／2 m；不應僅換話題繼續沿用當前解釋。

1.2.1.2.3.angle_min、angle_max 與 angle_increment：整圈分成720格

當前角域約為-180°～+180°，增量約0.5°，源碼生成720個距離項。角度是目標系中的 atan2(y,x)，不是雷達垂直視場、安裝傾角或雲台機械yaw範圍。

同一角度格內有多個合格點時，只保留水平距離最近的一個。例如，同方向2 m和5 m處各有點，掃描只留2 m；二維掃描不會同時表達它們的高度或多層結構。

0.5°在10 m處對應橫向約8.7 cm，在1 m處約8.7 mm；這裏只説明角度分格的幾何尺度，不是定位精度，也不保證這麼細的障礙都能看見。輸入點雲經過上游篩選與降採樣，調小角增量不會增加實際回波。

源碼先以 ceil((angle_max-angle_min)/angle_increment) 建數組，再計算下標。當前實現沒有檢查下標是否越界，而角度上界允許通過；當角域與增量恰好形成整數分格時，上界點存在越界路徑。當前近似整圈設置得到720項，不能據此證明其他角度組合的邊界安全；該缺口尚無運行觸發記錄。

1.2.1.2.4.range_min 與 range_max：底盤周圍的水平圓環

當前保留0.3～10.0 m水平距離的點，按 sqrt(x²+y²) 計算，不含z。相同x、y而高度不同的點，只要過高度／高差窗口，測距數值就一樣。

增大range_min可排掉更多近處回波，但也會漏掉車旁障礙；減小則可能帶入車體、雲台或其他自車點。0.3 m圓形門檻不是完整車輛輪廓，距底盤原點更遠的自車回波仍可能留下，需要結合安裝位置與真實車體觀察。

增大range_max只允許更多已經存在的遠點，不能讓雷達看到更遠，也不能恢復上游刪點。當前slam_toolbox另配置min_laser_range=0.3、max_laser_range=10.0，兩級範圍應一起核對；下游參數用途另屬建圖參數塊。

1.2.1.2.5.scan_time：時間字段，不是發佈頻率開關

LaserScan定義中scan_time表示掃描之間的時間間隔。這裏沒有測量實際間隔，只把參數0.05 s寫入消息；輸出由輸入點雲驅動，實際週期取決於地形點雲、TF與計算過程。

time_increment 寫死為0，表示沒有逐束時間差；header.stamp 沿用輸入點雲時間。地形輸入含歷史點，不能把這個結果當成所有射線確實在同一時刻由物理二維雷達採集，也不能用scan_time代替運動補償或修復上游點時間單位。

實際發佈週期應按對應啓動模式測量後核對。修改scan_time只會改字段，不會使10 Hz輸入變成20 Hz掃描，也不會給各個角度格補出真實採樣時間。

1.2.1.2.6.use_inf 與 inf_epsilon：無回波不等於確定空地

True先把每格距離設為+∞，再用最近合格點覆蓋；某格沒有合格點就保留∞。False則先設為range_max+inf_epsilon，當前默認組合是11 m，仍超出10 m有效量程。

“沒有合格點”可以來自真實無回波，也可以來自缺數據、遮擋、上游刪除、高度／高差過濾或角度格里沒有樣本；不能僅憑∞就判斷這條方向安全。下游怎樣處理無效／超量程值，應按對應掃描使用者的實現核對。

輸出只填ranges，不填LaserScan.intensities。這裏的兩項intensity參數用於挑選輸入點，並不把地形高差繼續作為掃描強度發佈。

1.2.1.2.7.默認TF參數與訂閲條件

transform_tolerance=0.01 s 在當前代碼中作為轉換查詢的等待超時；它不是點雲和TF可以錯開0.01秒的補償量，也沒有把消息時間戳前移／後移。TF消息過濾器按輸入時間等待目標變換，queue_size控制其隊列以及點雲訂閲深度。TF轉換失敗的回調直接返回，不用單位變換繼續生成掃描。

節點只有在scan輸出存在訂閲者時才訂閲cloud_in；最後一個掃描訂閲者消失後，會取消點雲訂閲。輸入和輸出均使用SensorDataQoS；兼容的訂閲QoS與有效TF是收到掃描的前提。全是被過濾的點時，仍可發佈一幀全為無回波值的掃描，不能把“有掃描消息”視為障礙輪廓正確。

默認queue_size取硬件併發線程數，適合先沿用；若消息排隊或TF等待導致丟點，再按實際數據率和負載核對，不把隊列長度當成工作線程數。

1.2.1.2.8.啓動來源與驗證狀態

15項自定義參數在構造時讀取，沒有動態參數更新回調；同名參數運行時改變不自動更新這些成員或重建TF過濾器。ROS標準use_sim_time由節點時鐘處理。當前use_inf=True使inf_epsilon不參與輸出，其他門檻仍按各自條件執行。

• 源碼依據： pointcloud_to_laserscan/src/pointcloud_to_laserscan_node.cpp；啓動接線見 pb2025_nav_bringup/launch/slam_launch.py，LaserScan字段定義見ROS2 sensor_msgs。
• 已有驗證範圍： 獨立Point-LIO靜止與短距離往返已有輸出記錄；該轉換節點的二維掃描、建圖輪廓、雲台連續yaw和坡道投影尚未驗證。
• 實物待核實： 底盤原點與投影平面、IMU／雷達／底盤轉換、上下坡點是否被固定高度窗口截掉、低障礙與懸空結構的保留範圍、自車回波、角度覆蓋、實際掃描週期及無回波區域的下游處理。