Manipulator

本範例示範一套以視覺為基礎的機器手臂工作流程，整合 RGB-D 相機、彩色方塊偵測、位置估算、MoveIt 與機器手臂。

原始 Demo 使用 Color Profile Creation 與 Color Block Detection & Position Estimation 偵測彩色方塊並估算其位置。系統同時提供錄製好的 ROS bag，讓使用者即使未連接實體相機或機器手臂，也能在 RViz 中觀察感知結果與機器手臂動作。

安裝

注意

請確認目標系統符合以下條件：

研華平台

至少 4 GB 的可用磁碟空間

需要可正常使用的網路連線

Ubuntu OS 請使用英文語系環境

依照安裝程式說明選擇並安裝 Manipulator 後，可在以下位置找到 manipulator 目錄：

/usr/local/Advantech/ros/container/ros-demokit/

進入範例目錄後，指定 ROS 2 版本啟動：

./launch.sh <ros_distro>

資訊

請將 <ros_distro> 替換為 Robotic Suite 安裝過程中偵測並安裝的 ROS 2 版本。

ROS 2 版本	啟動指令
ROS 2 Humble	`./launch.sh humble`
ROS 2 Jazzy	`./launch.sh jazzy`

例如，若要啟動 ROS 2 Jazzy 環境：

./launch.sh jazzy

提示

指定的 ROS 2 版本必須與 Robotic Suite 實際安裝的版本一致。實際版本可能會依目標系統所支援的 ROS 2 版本而有所不同。

Manipulator 範例會自動顯示於 RViz 中。

提示

第一次執行此程式時，系統可能需要下載或準備必要檔案，因此可能需要一些時間。

設定指南

本範例示範以視覺為基礎的機器手臂應用基本工作流程，包含：

使用 RGB-D 相機取得 RGB 與深度資訊
使用 Color Profile Creation 建立可重複使用的 HSV 顏色設定檔
使用 Color Block Detection & Position Estimation 偵測方塊並估算其位置
在原始即時 Demo 中使用 MoveIt 進行機器人運動規劃
使用 Robot URDF 與 Mesh 檔案建立機器手臂模型
使用 robot_state_publisher 產生機器人 TF Tree
使用 RViz 顯示感知結果、深度影像與機器手臂動作
使用錄製好的 ROS bag，在不依賴實體硬體的情況下進行播放

本範例的目的是協助您了解感知、位置估算、運動規劃與機器人視覺化如何彼此整合。本範例主要作為教學與設定參考，而不是一套可直接套用到任何機器手臂上的完整控制方案。

原始 Demo 工作流程

原始的即時 Manipulator Demo 採用以下流程：

Color Profile Creation
        |
        | color_profiles.json
        v
RGB Image + Aligned Depth + Camera Information
        |
        v
Color Block Detection & Position Estimation
        |
        | detected block position and approximate orientation
        v
Target Pose Generation
        |
        v
MoveIt Motion Planning
        |
        v
Robot Arm Action

此 Pipeline 遵循常見的機器人工作流程：Sensing → Perception → Planning → Action：

Sensing – RGB-D 相機提供彩色影像、對齊後的深度影像與相機校正資訊。
Perception – 系統偵測指定顏色的方塊，並估算其 3D 位置與近似方向。
Planning – 偵測結果會轉換為機器人的目標 Pose，並傳送給 MoveIt。
Action – 機器手臂執行規劃完成的動作。

本範例使用的核心技術

1. Color Profile Creation

執行 Detector 之前，會先使用 Color Profile Creation。

使用者會在 RGB 影像中的目標物件上選取數個點。工具會收集 HSV 樣本，並將計算出的顏色範圍儲存於：

color_profiles.json

產生的設定檔可讓 Detector 重複使用相同的顏色設定，而不需要直接在偵測程式碼中寫死 HSV 數值。

此步驟可協助使用者了解如何：

從即時影像中收集顏色樣本
了解為何 HSV 適合用於基於顏色的偵測
建立可重複使用的顏色設定檔
依不同光線條件調整設定檔

2. Color Block Detection & Position Estimation

Color Block Detection & Position Estimation 會搭配產生的顏色設定檔與 RGB-D 資料進行處理。

主要處理流程如下：

RGB image
    |
    v
HSV mask from color_profiles.json
    |
    v
Contour and block center
    |
    +-------------------+
    |                   |
    v                   v
Aligned depth      Rotated rectangle
    |                   |
    v                   v
3D position       Approximate yaw
    |                   |
    +---------+---------+
              |
              v
     Detection result and debug image

Detector 會執行以下工作：

在指定的 Region of Interest 中尋找目標顏色
過濾過小的輪廓
估算偵測到之方塊的中心點
讀取中心點周圍的深度中位數
使用相機內參，將像素位置與深度轉換為 3D 位置
使用旋轉矩形估算近似的 2D yaw
將除錯影像發布至 /color_block/debug_image
發布偵測到的 Pose，供後續機器手臂工作流程使用

在原始即時 Demo 中，偵測結果會用來準備 MoveIt 所需的目標 Pose。在這個離線範例中，感知結果與機器人動作已預先錄製於 ROS bag 中，並透過播放方式供教學使用。

此範例會啟動的元件

執行：

./launch.sh jazzy

後，系統會啟動以下元件：

包含所需相依套件的 Docker-based ROS 2 環境
adv_manipulator ROS 2 套件，其中包含：
- Robot URDF/Xacro 模型
- Robot Mesh 檔案
- Manipulator Launch File
- 預先定義的 RViz 設定
robot_state_publisher，會利用 Robot Model 與 /joint_states 產生機器人 TF Tree
發布已錄製 Topic 的 ROS bag
RViz，用於顯示：
- 機器手臂模型與動作
- 彩色方塊偵測除錯影像
- 錄製的深度影像

資訊

離線播放不會重新執行 Color Profile Creation 或 Color Block Detection & Position Estimation。系統會重播原始 Demo 產生的除錯影像與機器手臂動作。上述兩篇教學則說明這些錄製結果是如何產生的。

錄製的 ROS bag

提供的 ROS bag 大約為 1.8 GiB，包含約 64 秒的錄製資料。

Topic	Message type	用途
`/color_block/debug_image`	`sensor_msgs/msg/Image`	錄製的彩色方塊偵測結果
`/camera/camera/depth/image_raw`	`sensor_msgs/msg/Image`	錄製的深度影像
`/camera/camera/depth/camera_info`	`sensor_msgs/msg/CameraInfo`	深度相機校正資訊
`/joint_states`	`sensor_msgs/msg/JointState`	錄製的機器手臂關節位置
`/tf`	`tf2_msgs/msg/TFMessage`	錄製的動態座標轉換
`/tf_static`	`tf2_msgs/msg/TFMessage`	錄製的靜態座標轉換

此 ROS bag 可讓相同 Demo 重複播放，不需要原始 RGB-D 相機、MoveIt 設定或實體機器手臂。

使用方式

在 Advantech Robotic Suite 中，所需的 ROS 2 環境與 Manipulator 相依套件已準備於 Docker-based Sample Environment 中，因此不需要手動安裝相關套件。

執行範例時：

準備 Docker 環境。
載入 Robot URDF/Xacro 模型。
robot_state_publisher 建立機器人 TF Tree。
RViz 使用預先定義的設定開啟。
ROS bag 使用 Simulation Time 開始播放。
/joint_states 重現錄製的機器手臂動作。
彩色方塊除錯影像與深度影像會顯示於 RViz 中。
錄製的 Demo 播放完成後停止。

主要的動作播放概念如下：

Recorded /joint_states
        |
        v
robot_state_publisher
        |
        v
Robot TF tree
        |
        v
RViz RobotModel movement

ROS bag 中也包含原始 Demo 的 /tf 與 /tf_static。依照 Launch 設計，可以選擇：

重播 /joint_states，並由 robot_state_publisher 產生 TF，或
直接重播錄製的 /tf 與 /tf_static

請避免同時發布兩份相同的 Robot Transform。

將此範例作為參考

本範例使用預先定義的 Robot Model、Topic 配置、RViz 設定與錄製 Demo。由於使用者可能使用不同的機器手臂、相機、Controller 與 Workspace，因此不應預期可以：

直接啟動此範例控制自己的機器手臂
在離線播放期間執行新的 MoveIt 規劃
在未啟動即時感知節點的情況下偵測新的方塊
在不修改設定的情況下，直接將此範例套用到不同的 Robot Model

您可以改為使用此範例來：

了解 RGB-D 感知如何連接至機器手臂工作流程
觀察 Color Block Detection & Position Estimation 的輸出結果
了解 /joint_states、URDF、TF 與 RViz 如何共同運作
在沒有實體硬體的情況下研究可重複執行的 Demo
將內附 ROS bag 作為參考資料集

若要將相同概念套用至自己的機器手臂，需要：

依照自己的物件與光線環境建立顏色設定檔
設定 RGB、Aligned Depth 與 CameraInfo Topic
提供正確的 Camera-to-Robot 座標轉換
將 URDF/Xacro 與 Mesh 檔案替換為自己的 Robot Model
確保 Joint Name 與 Robot Description 中的名稱一致
為實際硬體設定 MoveIt 與 Robot Driver
更新 RViz 設定與 Launch Script
若希望建立自己的離線教學範例，可重新錄製 ROS bag

所提供的設定主要作為了解各元件如何整合的範本，而不是可直接套用到任意硬體的即用型設定。

適用情境

在以下情況下，可以使用此範例：

剛開始接觸以視覺為基礎的機器手臂應用，希望了解整體工作流程
想了解如何使用顏色設定檔與 RGB-D 資料估算物件位置
想在不連接實體硬體的情況下觀察機器手臂 Demo
需要 ROS 2 Image、Depth、Joint State、TF、URDF 與 RViz 整合的參考
需要可重複使用於訓練、簡報或驗證的範例

本範例著重於以下基本流程：

建立 HSV 顏色設定檔
偵測目標彩色方塊
估算方塊位置與近似方向
將結果轉換為機器人的目標 Pose
在原始即時系統中規劃並執行機器手臂動作
在離線 Sample 中重播錄製的感知結果與機器手臂動作

後續可在此基礎上進一步：

使用自己的 RGB-D 相機執行感知教學
將偵測結果串接至自己的座標轉換與 MoveIt Pipeline
將預先定義的 Manipulator 替換為自己的 Robot Model
錄製自己的 ROS bag，以進行可重複的開發與展示

安裝​

設定指南​

原始 Demo 工作流程​

本範例使用的核心技術​

1. Color Profile Creation​

2. Color Block Detection & Position Estimation​

此範例會啟動的元件​

錄製的 ROS bag​

使用方式​

將此範例作為參考​

適用情境​

安裝