Python + MediaPipe 手勢控制 UR10 機械臂：由零開始的分享

用一隻手掌控制 UR10 機械臂——詳細介紹我的 FYP：UR10 Vision Control

工業機械臂的操作，向來都是捧著示教器（Teach Pendant）逐個鍵慢慢撳。我的畢業專題想試另一條路：舉起手掌，鏡頭讀手勢，機械臂跟住你郁。UR10 Vision Control 就是一套用 Python 寫的視覺控制系統——用一部普通鏡頭（Mac 內置鏡頭或 RTSP 網絡攝影機都得），即時控制 Universal Robots UR10，全程經 RTDE 協定向機械臂下指令。

一、控制模型：畫面就是搖桿

鏡頭畫面（640×480）被劃分成幾個互斥的區域，同一時間只會輸出一個方向：

・畫面左邊約 38% → 向左（LEFT）

・畫面右邊約 38% → 向右（RIGHT）

・中央、中性點以上 → 向上（UP）

・中央、中性點以下 → 向下（DOWN）

・中央中性帶、手掌明顯變大 → 向前（FWD）

・中央中性帶、手掌明顯變小 → 向後（BACK）

・握拳、沒有手、信心不足或動作未確認 → 立即 STOP

幾個值得講的細節：

關於死區。水平區域的分界在畫面 38% 與 62%，中央另有 10% 的垂直死區與 6% 的深度死區，避免手掌輕微顫動就觸發指令。死區與平滑程度都可以在介面即場微調。

關於深度。先做一次中性姿勢校準（按下 Calibrate Neutral，量度當下的手掌位置與大小），之後手掌比基準大就前進、細就後退，等於用人手做「變焦搖桿」。

關於確認。MediaPipe 手部關鍵點信心值至少要 75%，而且要連續六幀方向一致，才會發出非 STOP 指令；STOP 反而是即時的，不等確認——寧願慢半拍，都不要亂郁。

二、架構：一條流水線，兩個 process

整條資料流是：鏡頭或 RTSP 串流 → OpenCV 擷取畫面 → MediaPipe Hands 取出手部關鍵點 → 校準、區域過濾與安全檢查 → Qt 儀表板 → RTDE worker（獨立 process）→ URSim 或 UR10。

機械臂側透過兩個 TCP 埠溝通：29999 是 Dashboard 介面（開機、放剎車、查詢遠端狀態），30004 是 RTDE（即時下速度指令）。連線之前，程式會自動檢查 PolyScope 版本、確認機械臂已切換到遠端模式，CB3 與新一代控制器都有處理。

工程上最值錢的一個決定，是把 RTDE 連線搬進獨立 process。ur-rtde 這個函式庫在 URSim 斷線時，原生重連 thread 有機會直接崩潰——如果它跟 UI 同生共死，一次斷線就等於整套軟體死機。現在的設計是：worker process 出事也不影響介面，UI 只會停用控制、顯示原因，可以安全重試。

三、安全設計：fail-closed 哲學

這是一個會實際郁動機械臂的原型，所以我把整個系統設計成「唔肯定就唔郁」：

關於速度。預設上限 0.02 m/s；任何速度向量先經過 sanitising——格式不對、含非數值直接拒收（fail closed），XYZ 歐氏範數超標則等比縮放。

關於工作區。實體 UR10 的工作區邊界在程式裡預設是「未設定」，未量度、未確認之前，實機根本無法被移動——設定不正確，比沒有設定更危險。

關於舊設定。切換回實機時，絕不還原之前儲存的速度，一律回到 0.02 m/s 起步。

關於介面。動作指令以「連線時擷取的身分」核對，而不是介面上顯示的目標字樣，避免標籤與實際目標不符。

關於虛擬牆。URSim 內，接近工作區邊界 0.10 m 會進入慢速區，撞牆即 STOP，再以 0.005 m/s 直線返回示範用安全原點 (0.40, 0.00, 0.40)，30 秒超時；過程中任何異常（位姿過期、安全狀態異常、斷線）都會中止返回並鎖定。實機永不自動返回，只會停止並鎖定。

關於人的環節。啟用實機控制前，程式會彈出確認清單要求逐項確認；緊急停止按鈕常駐介面；所有邏輯、方向、虛擬牆測試都在 URSim 完成，實機只是最後一步。

四、測試：安全規則不是口講

tests/test_safety_policy.py 有八個單元測試守住這些規則，例如：工作區設定不正確時必須 fail closed；速度上限必須以歐氏範數計算並拒收非數值向量；切換目標後不得還原實機高速度；發送指令前的最後一關必須再 cap 一次範數；測試與自動返回只接受已擷取的 URSim 身分，實機目標一律拒絕；區域判斷在垂直方向明確時，優先於深度漂移。改動安全邏輯而無更新測試，自己這一關已經過不了。

五、使用體驗上的小事

Windows 做了一個雙擊即用的啟動腳本：第一次執行自動建立 venv、裝好依賴，之後一撳就開；macOS 有對應版本。介面用 PySide6 做卡片式儀表板——鏡頭預覽、機械狀態、事件日誌、微調欄（平滑度、死區）、分區顯示開關全部一目了然。手勢、指令與延遲可以用 CSV 記錄下來做分析。macOS 編譯 ur-rtde 要先裝 Boost，是個小坑，README 已記下解法。機器 IP 等本機設定放在 settings.json，已被 gitignore 排除，不會誤傳上 GitHub。

六、接下來想做的

RTDE 回讀實際 TCP 位姿與安全狀態、更完整的 CSV 延遲分析、可設定的軸反轉與控制設定檔、手勢啟用前的手動軸測試面板、工作區邊界減速區，以及用獨立手勢控制夾爪。

專案已開源：UR10_PythonCamCode（學術用途，歡迎交流）。