# 工作台與腕相機校正 這份選用設定讓 AtomiClaw 把腕相機圖像上的一個點轉為 [[SO-101]] 可執行的桌面抓放。只需做關節操作或用相機找物件時,可以直接使用既有的馬達內存校正。量測工具會讀取 EEPROM 和實際關節位置,由操作者移動手臂。所有採樣影像、計算及校正檔儲存在本機。 ## 印標靶 先執行 `atomiclaw setup` 安裝原生設備套件。校正使用現有環境的 OpenCV ChArUco 和 NumPy。以下範例產生一張 7 × 5 格的標靶,方格邊長 20 mm,內部標記邊長 14 mm。 ```sh atomiclaw calibrate board --out board.png atomiclaw devices ``` 將有標記的區域印成 **140 × 100 mm**,四周留白。用尺實測方格邊長,將標靶平整固定在希望使用的桌面範圍。若使用其他公制尺寸,在 `board` 與 `capture` 兩個命令一起指定 `--squares-x`、`--squares-y`、`--square-mm` 和 `--marker-mm`。 ## 採集 將下方設備路徑與相機索引替換為 `atomiclaw devices` 列出的實際值。可以沿用同一個資料夾接續採樣。 ```sh atomiclaw calibrate capture --out ./wrist-session --port /dev/cu.usbmodemXXXX --camera 0 ``` 1. 在提示符輸入 `state` 顯示六顆馬達的原始位置、編碼器範圍及偏移。支撐手臂並避免其他控制器同時驅動。核對官方新校正模型各軸的正向旋轉與讀值增減,依 shoulder_pan、shoulder_lift、elbow_flex、wrist_flex、wrist_roll、gripper 的順序,輸入 `directions`、空格和六個逗號分隔的 1 或 −1(負號使用 ASCII `-`)。原廠夾爪採編碼器增大時打開的配置。[上游 New Calib 模型](https://github.com/TheRobotStudio/SO-ARM100/blob/main/Simulation/SO101/so101_new_calib.xml) 2. 將手臂支撐在與該模型 **六軸 0 rad** 相符的已知參考姿態,再輸入 `zero`。這會從實際馬達讀取六個基準 tick 與 EEPROM 指紋。零位和方向需由已核對的組裝、量具或既有量測確認。僅靠編碼器的最大與最小值無法識別。已有可信的獨立量測時,也可直接使用下方資料集格式。 3. 保持工作板固定,手動移動腕相機,改變視野位置、距離與傾斜方向。至少繞兩個不同軸取得明顯角度變化,也讓角點覆蓋影像的中央與四周。每次停穩按 Enter,工具會檢查兩次關節讀值、相機與關節時間戳,再保存一組資料。建議取得 18–30 組,求解至少需要 12 組可辨識的影像。 4. 輸入 `done` 關閉裝置。擬合時不必連手臂或相機。 ## 求解與載入 ```sh atomiclaw calibrate fit ./wrist-session/capture.json --out ./worktable.json --board-thickness-mm 1.5 ``` 將最後一個數字替換為標靶印刷面與桌面之間的實測厚度。每五組觀測保留一組驗證。工具求出鏡頭內參和五項相機畸變參數(此擬合固定第三個徑向係數為零)、相機相對手爪的剛體變換、水平桌面的基座高度,以及落在所測標靶內的可操作矩形。角點或姿態覆蓋不足、桌面偏離水平超過 2°、重投影誤差或固定標靶的估計位移過大時,會回報原因。[OpenCV 相機標定與眼在手上標定](https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html) CLI 使用 `ATOMICLAW_RIG_PROFILE` 指向輸出的 JSON,例如執行 `ATOMICLAW_RIG_PROFILE=./worktable.json atomiclaw tui`。Web 請在設備的「機構設定」載入對應檔案。瀏覽器的相機識別碼依站點分配。確認同一顆相機、安裝、焦距、模式及全幅取像一致後,用 `fit … --camera-id <瀏覽器的腕相機識別碼> --out web-worktable.json` 為該介面輸出設定。這個檔案保存的像素內參適用於全幅、未鏡射的 240 × 180 RGB 取樣。 ## 資料集與設定格式 離線資料集是一個 `capture.json` 加上同目錄的影像。以下是欄位定義,實際量測數字來自採集。 | 欄位 | 意義 | | --- | --- | | `version`, `cameraId` | 格式版本 1 與腕相機識別碼 | | `board` | `squaresX`, `squaresY`, `squareMm`, `markerMm` 與 `dictionary: "DICT_4X4_50"` | | `joints` | 依 ID 1–6 排列的六筆 `id, name, model, min, max, offset, zeroTick, direction`。原廠 STS3215 型號值 777,編碼器每轉 4096 ticks | | `samples` | 每筆 `file, rawPositions, observedAt, capturedAt`。影像相對於資料夾,六軸是已套用韌體 homing offset 的原始 tick,時間戳使用毫秒 | 輸出 JSON 使用 `version: 1`、`rig: "so101-new-calib-stock-jaws"`、`kinematicConvention: "lerobot-so101-new-calib"` 與上述 `joints`。其 `camera` 內含 `id,width,height,fx,fy,cx,cy,distortion,originInGripperMm,opticalToGripperWxyz`,光學座標軸依序為右、下、前,四元數將光學座標轉到固定手爪本體。`table` 包含基座座標中的 `planeZMm,xBoundsMm,yBoundsMm`。 ## 驗證範圍 在這台 Mac 以 28 張帶已知鏡頭畸變的合成標靶影像及量化編碼器資料實跑,5 張只供驗證。最大保留影像重投影誤差為 0.305 px,回推相機安裝位置與已知值相差 1.15 mm,旋轉相差 0.24°,桌面高度相差 0.31 mm。錯配保留影像與編碼器讀值時,求解器拒絕輸出設定。資料可用 `python calibration/synthetic_test.py --out ./synthetic-session` 重建。這些數字描述合成資料的測試。實際鏡頭、列印尺寸、桌面與安裝會影響實機誤差。