顏色設定檔建立

本教學說明如何從即時 RGB 相機影像串流建立 HSV 顏色設定檔。 產生的設定檔可重複用於以顏色為基礎的偵測程式，例如 彩色方塊偵測與位置估算（Color Block Detection & Position Estimation）。

顏色設定檔描述目標顏色的 HSV 範圍。例如，它可以描述目前光線條件下紅色、綠色或藍色方塊的顏色範圍。

---

概述

在機器手臂堆疊方塊的應用中，系統必須先偵測目標物件，才能進一步估算方塊位置並規劃手臂動作。

本教學著重於第一個步驟：建立顏色設定檔。

此工具會在 OpenCV 視窗中顯示相機影像。使用者可在目標彩色方塊上點選數個位置，程式會從點選區域擷取 HSV 樣本，計算一組或多組 HSV 範圍，並將結果儲存為 JSON 檔案。

儲存後的 JSON 檔案可供下一個模組使用，以即時偵測方塊顏色。

---

您將學到什麼

完成本教學後，您將了解如何：

• 從 ROS 2 image topic 接收 RGB 影像
• 從即時相機影像中選取目標顏色樣本
• 了解為什麼在簡單的顏色閾值處理中，HSV 通常比 RGB 更適合
• 將影像像素從 BGR 色彩空間轉換為 HSV 色彩空間
• 從多個樣本產生 HSV 閾值範圍
• 將 HSV 範圍儲存為可重複使用的 JSON 顏色設定檔
• 將設定檔作為後續彩色方塊偵測流程的輸入

---

念概

Color Profile Creation 會將使用者選取的目標顏色轉換成程式可使用的參數。

基本流程如下：

1. 啟動會發布彩色影像 topic 的相機節點。
2. 執行 color profile picker。
3. 在目標彩色方塊上點選數個位置。
4. 將點選區域的影像從 BGR 轉換為 HSV，以便更清楚地分離顏色與亮度資訊。
5. 估算所選顏色的 HSV 範圍。
6. 將 HSV 範圍儲存至 color_profiles.json。
7. 在顏色偵測程式中重複使用此設定檔。

---

為什麼使用 HSV？

許多使用者一開始可能會考慮直接使用 RGB 進行顏色偵測。然而，RGB 並不適合簡單的顏色閾值處理，因為顏色資訊與亮度資訊混合在一起。

例如，同一個藍色方塊在不同光線條件下可能會有非常不同的 RGB 數值：

Bright blue area: R=40,  G=90,  B=220
Dark blue area:   R=15,  G=35,  B=100

對人眼而言，這兩個像素仍然都是藍色，但其 RGB 數值差異很大。如果只使用 RGB 閾值，偵測範圍通常會變得難以調整。目標位於陰影中時可能會無法偵測，或在不同光線條件下誤將背景像素包含進來。

HSV 更適合這類任務，因為它將顏色資訊分成三個部分：

Channel	意義	用途
H Hue	主要顏色類型，例如紅色、綠色或藍色	用於選取目標顏色
S Saturation	顏色的飽和或純度程度	有助於排除灰色、白色或低彩度區域
V Value	像素的明暗程度	有助於容忍陰影與光線變化

在彩色方塊偵測中，我們通常最重視 Hue 值，接著使用 Saturation 與 Value 範圍排除低彩度區域、陰影或背景雜訊。

因此，此工具會在建立設定檔前，先將點選的影像區域從 BGR 轉換為 HSV。產生的設定檔會儲存 HSV 的上下限，後續即可搭配 OpenCV cv2.inRange() 進行快速顏色分割。

提示

HSV 並不能完全解決所有光線問題。強烈反光、過暗影像、自動曝光變化，或背景中存在相似顏色，都可能影響偵測結果。為獲得較佳效果，建議在與實際機器人展示相同的光線條件下建立設定檔。

OpenCV 使用以下 HSV 數值範圍：

Hue:        0 to 180
Saturation: 0 to 255
Value:      0 to 255

這與一般常見的 Hue 0 到 360 度不同。使用 OpenCV 時，請記得 Hue 會縮放至 0 到 180。

---

檔案

本教學使用以下程式：

color_profile_creation.py

資訊

Source code:

• View on GitHub

此程式是一個互動式 ROS 2 工具。它會訂閱彩色影像 topic，並在 OpenCV 視窗中顯示影像。

前置需求

執行本教學前，請確認已具備以下項目：

• ROS 2 環境
• 可發布 sensor_msgs/msg/Image 的相機節點
• Python 3
• OpenCV for Python
• NumPy
• cv_bridge

同時請確認 RGB 影像 topic 已存在：

ros2 topic list

此工具預設使用的 topic 為：

/camera/color/image_raw

執行教學

進入 Color Profile Creation 目錄：

cd development_utilities/core_techniques/color_profile_creation

使用預設設定執行工具：

python3 color_profile_creation.py

或明確指定參數執行：

python3 color_profile_creation.py \
  --ros-args \
  -p rgb_topic:=/camera/color/image_raw \
  -p profile_file:=./color_profiles.json \
  -p profile_name:=blue \
  -p note:="blue block under lab lighting"

程式啟動後，會顯示 OpenCV 視窗。

使用者操作

操作	說明
滑鼠左鍵點擊	從點選的影像區域收集一筆 HSV 樣本
s	將目前的顏色設定檔儲存至 JSON
c	清除所有已收集的樣本
q	結束工具

建議操作方式：

1. 在目標彩色方塊上點選多個位置。
2. 樣本應包含較亮區域、較暗區域與不同觀看角度。
3. 確認畫面上顯示的 HSV 範圍。
4. 按下 s 儲存設定檔。

提示

建議至少收集三筆樣本，以建立較穩定的設定檔。通常樣本數越多，設定檔對光線變化的容忍度也會越高。

參數

此工具可透過 ROS 2 parameters 進行設定。

參數	預設值	說明
rgb_topic	/camera/color/image_raw	作為 RGB 相機輸入的 ROS 2 image topic
profile_file	./color_profiles.json	輸出的 JSON 檔案路徑
profile_name	blue	要儲存的顏色設定檔名稱
note	""	儲存在 JSON 檔案中的選用備註
patch_radius	4	點選區域的半徑，單位為像素。4 代表使用 9x9 的影像區域
h_margin	10	額外增加至 Hue 的容許範圍
s_margin	40	額外增加至 Saturation 的容許範圍
v_margin	40	額外增加至 Value 的容許範圍
use_percentiles	True	當樣本數足夠時，使用百分位數而不是最小值 / 最大值
low_percentile	10.0	用於穩健範圍估算的較低百分位數
high_percentile	90.0	用於穩健範圍估算的較高百分位數

範例：建立紅色設定檔並儲存到自訂檔案：

python3 color_profile_creation.py \
  --ros-args \
  -p profile_name:=red \
  -p profile_file:=./my_color_profiles.json

---

輸入與輸出

輸入

輸入為即時 ROS 2 RGB 影像 topic：

sensor_msgs/msg/Image

影像會在程式內部轉換為 OpenCV BGR 格式，以供顯示與處理。

輸出

輸出為包含一個或多個 HSV 顏色設定檔的 JSON 檔案。

輸出範例如下：

{
  "profiles": {
    "blue": {
      "ranges": [
        {
          "lower": [90, 80, 80],
          "upper": [130, 255, 255]
        }
      ],
      "created_from": {
        "rgb_topic": "/camera/color/image_raw",
        "note": "blue block under lab lighting",
        "samples": 8
      }
    }
  }
}

每個設定檔包含：

• ranges：用於顏色閾值處理的 HSV 上下限
• created_from：記錄設定檔建立方式的 metadata
• samples：建立設定檔時使用的點選樣本數量

提示

以上數值僅為範例。實際 HSV 範圍會依相機、光線條件、物件材質與環境而有所不同。

---

運作方式

1. 接收相機影像

此工具會訂閱已設定的 ROS 2 image topic，並將影像轉換為 OpenCV BGR 格式。

2. 收集 HSV 樣本

相機影像會以 RGB image topic 的形式接收，並轉換成 OpenCV BGR 格式以供顯示。使用者點選影像後，所選取的影像區域會先從 BGR 轉換成 HSV，再進行取樣。

此工具並不是只取單一像素，而是會對點選位置周圍的一小塊影像區域進行取樣。

例如，當 patch_radius 設為 4 時，工具會使用 9x9 像素的影像區域。

程式會使用該區域 HSV 值的中位數作為一筆樣本。這能降低影像雜訊與局部反光對取樣結果的影響。

3. 估算 HSV 範圍

收集多筆樣本後，工具會估算所選顏色的 HSV 範圍。

如果啟用 use_percentiles 且樣本數足夠，工具會使用百分位數降低離群樣本的影響。

接著加入額外容許範圍：

Hue range        +/- h_margin
Saturation range +/- s_margin
Value range      +/- v_margin

如此可建立對實際相機影像具有較高容忍度的設定檔。

4. 處理 Hue 環繞問題

OpenCV 使用以下 HSV 範圍：

Hue:        0 to 180
Saturation: 0 to 255
Value:      0 to 255

Hue 是循環值。某些顏色，特別是紅色，可能同時出現在 Hue 範圍的兩端。

例如，紅色設定檔可能需要兩個範圍：

"ranges": [
  {"lower": [0, 120, 80], "upper": [10, 255, 255]},
  {"lower": [170, 120, 80], "upper": [180, 255, 255]}
]

當計算出的 Hue 範圍跨越 0 / 180 邊界時，此工具會自動處理這種情況。

5. 儲存設定檔

按下 s，即可將目前的設定檔儲存至 JSON 檔案。

如果 JSON 檔案已存在，新設定檔會加入同一個檔案中。如果已有相同 profile_name 的設定檔，則會覆寫原有內容。

如何使用產生的設定檔

產生的 JSON 檔案可由下一個模組載入，例如 彩色方塊偵測與位置估算（Color Block Detection & Position Estimation）。

典型的偵測流程如下：

1. 載入 color_profiles.json。
2. 選擇目標設定檔，例如 blue。
3. 將即時相機影像轉換為 HSV。
4. 使用 cv2.inRange() 套用每一組 HSV 範圍。
5. 如果設定檔包含多組範圍，將各個 mask 合併。
6. 從 mask 中找出彩色方塊。
7. 使用影像座標與深度資訊估算方塊位置。
8. 將估算的 pose 傳送至機器人運動規劃模組。

建立更好設定檔的技巧

• 請在與實際展示相同的光線條件下建立設定檔。
• 避免物件表面出現強烈反光。
• 同時點選目標物件上較亮與較暗的區域。
• 如果物件顏色會隨光線改變，請點選物件的不同側面或角度。
• 為不同顏色使用不同的設定檔名稱，例如 red、green 與 blue。
• 如果不同環境之間的光線差異很大，可為不同環境分別儲存設定檔。
• 如果偵測條件過於嚴格，可稍微增加 h_margin、s_margin 或 v_margin。
• 如果偵測結果包含過多背景，可減少 margin，或重新收集更適合的樣本。

---

疑難排解

沒有顯示影像

確認相機節點正在執行，且 image topic 名稱正確。

ros2 topic list
ros2 topic echo /camera/color/image_raw --once

接著使用正確的 topic 再次執行工具：

python3 color_profile_creation.py \
  --ros-args \
  -p rgb_topic:=<your_rgb_topic>

儲存的設定檔無法正確偵測物件

請嘗試以下方式：

• 從目標物件收集更多樣本。
• 在與實際機器人展示相同的光線條件下重新建立設定檔。
• 調整 h_margin、s_margin 與 v_margin。
• 確認相機曝光設定穩定。

偵測到過多背景

請嘗試以下方式：

• 降低 HSV margin。
• 避免點選背景像素。
• 建立設定檔時使用較乾淨的背景。
• 僅使用目標物件的樣本重新建立設定檔。

可重複使用的概念

本教學並不限於彩色方塊。同樣的概念也可以重複應用於其他需要簡單顏色物件偵測的機器人應用。

例如，可以使用此方法偵測：

• 彩色方塊
• 按鈕或標記
• 產品標籤
• 機器人操作使用的視覺引導標記
• 簡單的檢測目標

將顏色設定檔建立與物件偵測分離後，使用者只需調整一次顏色設定，即可在多個應用程式中重複使用。

---

下一步

建立顏色設定檔後，請繼續進行：

Color Block Detection & Position Estimation

此模組會使用產生的 HSV 設定檔偵測目標方塊，並估算其位置，供機器手臂操作使用。