qt第一版可视化

gripper_control_02/README.md

@@ -12,8 +12,9 @@
 6. 像 01 一样进入 `gripping`，慢慢加力到 `HOLD_FORCE`。
 7. 进入 `hold_check` 后记录夹持参考力。
 8. 后续法向力或切向力变化超过阈值，夹爪直接张开到 `OPEN_POS`。
-9. 张开后进入 `open_recover`，保持张开并等待传感器力清空。
-10. 法向和切向读数都低于恢复阈值并稳定后，才回到 `open_wait` 等待下一次单侧扫过触发。
+9. 张开后进入 `open_recover`，保持张开并等待恢复条件。
+10. 夹爪回到 `OPEN_POS` 初始点位，或法向/切向读数都低于恢复阈值并稳定后，回到 `open_wait`。
+11. 回到 `open_wait` 后，程序必须先看到触发力清掉并稳定，才会重新武装；下一次扫过才允许闭合。
 
 ## 运行
 
@@ -30,6 +31,24 @@ python -m gripper_control_02.main
 python -m gripper_control_02.main --dry-run
 ```
 
+PyQt 可视化展示：
+
+```powershell
+python -m gripper_control_02.visualizer
+```
+
+窗口模式运行：
+
+```powershell
+python -m gripper_control_02.visualizer --windowed
+```
+
+兼容入口：
+
+```powershell
+python examples\gripper_demo_02_viewer.py
+```
+
 默认配置文件：
 
 ```text
@@ -40,6 +59,7 @@ gripper_control_02\config\gripper_demo_02.py
 
 - `TRIGGER_NORMAL_FORCE`: 单侧法向力触发阈值。
 - `TRIGGER_SHEAR_FORCE`: 单侧切向力触发阈值。
+- `TRIGGER_CLEAR_STABLE_SECONDS`: 张开恢复后，触发力必须清掉并稳定多久，才允许下一次扫过触发。
 - `GRIP_NORMAL_FORCE`: 夹住时左右接触阈值。
 - `GRIP_REQUIRES_BOTH`: 是否必须左右都接触才算夹住。
 - `GRIP_START_FORCE`: 检测到物体后先切到的低力。
@@ -49,10 +69,17 @@ gripper_control_02\config\gripper_demo_02.py
 - `GRIP_SETTLE_SECONDS`: 夹住后等待稳定多久再记录参考力。
 - `RELEASE_NORMAL_CHANGE`: 夹住后法向力变化超过它就松开。
 - `RELEASE_SHEAR_CHANGE`: 夹住后切向力变化超过它就松开。
+- `RELEASE_OPEN_SPEED`: 检测到松开后，张开到 `OPEN_POS` 使用的速度。
+- `RELEASE_OPEN_ACCEL`: release 张开的加速度。
+- `RELEASE_OPEN_DECEL`: release 张开的减速度。
 - `REARM_SECONDS`: 张开后最短等待时间，防止刚松开马上又误触发。
 - `RECOVER_NORMAL_FORCE`: 张开恢复时允许重新触发的最大法向残余力。
 - `RECOVER_SHEAR_FORCE`: 张开恢复时允许重新触发的最大切向残余力。
 - `RECOVER_STABLE_SECONDS`: 力清空后需要连续稳定多久，才重新等待触发。
+- `OPEN_POSITION_RECOVER_ENABLED`: 是否允许夹爪回到 `OPEN_POS` 后直接恢复等待。
+- `OPEN_POSITION_TOLERANCE`: 当前点位和 `OPEN_POS` 差值小于它，就认为已经回到初始点位。
+- `OPEN_POSITION_STABLE_SECONDS`: 回到初始点位后需要稳定多久，才重新等待触发。
+- `OPEN_POSITION_CHECK_INTERVAL`: `open_recover` 中读取夹爪当前位置的间隔。
 
 ## 日志字段
 
@@ -60,6 +87,7 @@ gripper_control_02\config\gripper_demo_02.py
 - `maxN`: 左右法向力最大值，单位 N。
 - `shear`: 左右切向力最大值，单位 N。
 - `trigger`: 是否满足单侧触发条件。
+- `armed`: 是否已经重新武装；只有 `trigger=1 armed=1` 才会闭合。
 - `grip_contact`: 是否满足夹住接触条件。
 - `dN`: 夹住后当前法向力相对参考值的最大变化，单位 N。
 - `dShear`: 夹住后当前切向力相对参考值的变化，单位 N。
@@ -68,17 +96,31 @@ gripper_control_02\config\gripper_demo_02.py
 - `force_pct`: 当前夹爪目标力百分比。
 - `action`: 当前动作。
 
+## 可视化展示
+
+- 左右两边的光流箭头图。
+- 左右两边的光流幅值图。
+- 左右法向力、最大切向力、左右差值。
+- 当前 `state`、`action`、`trigger/armed`、`grip_contact`。
+- 当前 `force_pct`、速度 `speed_pct`、`hold_pos`。
+- 左右传感器 FPS、接触标志、光流均值/最大值。
+
 ## 状态说明
 
 - `open_wait`: 夹爪张开，等待任意单侧触发。
 - `closing`: 单侧触发后正在闭合，等待检测到物体。
 - `gripping`: 检测到物体后低力保持当前位置，并慢慢加力。
 - `hold_check`: 已夹住并记录参考力，监测法向/切向变化；变化超过阈值会直接张开。
-- `open_recover`: 已经张开到初始位置，正在等待法向/切向残余力清空；这个状态不会闭合夹爪。
+- `open_recover`: 已经发出张开命令，正在等待回到初始点位或等待法向/切向残余力清空；这个状态不会闭合夹爪。
 
 ## 常见动作说明
 
 - `force-change-release-open`: 检测到夹住后的法向或切向变化，已经发出张开命令。
+- `open-recover-position`: 夹爪当前位置已经接近 `OPEN_POS`，正在等待到位稳定。
+- `open-ready-position`: 夹爪已经回到初始点位，重新进入等待下一次扫过触发。
+- `open-wait-clear-trigger`: 已经回到等待状态，但当前力还超过触发阈值，暂时不会闭合。
+- `open-wait-trigger-clearing`: 触发力已经低于阈值，正在等待清零稳定时间。
+- `open-wait-armed`: 触发已经清掉并稳定，下一次扫过可以闭合。
 - `open-recover-wait-force-clear`: 夹爪保持张开，但传感器还有残余力，不允许重新闭合。
 - `open-recover-stabilizing`: 力已经低于恢复阈值，正在等待稳定时间。
 - `open-ready`: 力已经清空并稳定，重新进入等待下一次扫过触发。