# Gripper

程序只是常驻监听单侧触发，每次触发后执行一次“闭合夹住 -> 监测变化 -> 直接张开”的流程。

## 展示流程

1. 程序启动后，夹爪先张开。
2. 程序等待任意一侧触觉传感器感受到法向力或切向力。
3. 展示时，把物体从某个侧边扫一下，触发单侧力变化。
4. 触发后夹爪开始闭合，你把物体移动到中间。
5. 闭合过程中检测到物体后，切到低力并保持当前位置。
6. 像 01 一样进入 `gripping`，先慢慢加力到基础 `HOLD_FORCE`。
7. 进入 `hold_check` 后，根据切向力估计物体负载；切向力越大，目标夹紧力越高，并按小步进继续补力。
8. 自适应补力停止并稳定 `RELEASE_ARM_DELAY_SECONDS` 后，重新记录释放参考力，才开始检测人取物松开。
9. 后续法向力或切向力变化超过阈值，夹爪直接张开到 `OPEN_POS`。
10. 张开后进入 `open_recover`，保持张开并等待恢复条件。
11. 夹爪回到 `OPEN_POS` 初始点位，或法向/切向读数都低于恢复阈值并稳定后，继续休息至少 `REARM_SECONDS`。
12. 休息结束后才回到 `open_wait` 并重新武装；休息期间不管有没有物体扫过，都不会闭合。

## 运行

GUI 的完整模块说明、操作流程、参数表和故障排查见
[GUI 使用说明书](docs/GUI_USER_MANUAL.zh-CN.md)。
正式产品使用说明书（HTML，含界面截图，可打印/导出 PDF）见
[产品使用说明书](docs/PRODUCT_MANUAL.zh-CN.html)。

从项目根目录运行：

```powershell
conda activate py311
python -m gripper.main
```

只看逻辑、不打开串口：

```powershell
python -m gripper.main --dry-run
```

PyQt 可视化展示：

```powershell
python -m gripper.visualizer
```

窗口模式运行：

```powershell
python -m gripper.visualizer --windowed
```

兼容入口：

```powershell
python -m gripper.visualizer
```

默认配置文件：

```text
config\gripper.json
```

## 打包

先在 `py311` 环境里安装 PyInstaller：

```powershell
conda activate py311
pip install pyinstaller PyOpenGL PyOpenGL_accelerate
```

然后从项目根目录运行：

```powershell
python build\build_exe.py
```

默认使用轻量打包配置，使用 OpenCV DIS 光流和 CPU Poisson 后端，不打包
Torch/CUDA、CuPy 和 Orisys 可选的 Open3D 查看器。项目自己的 PyOpenGL
夹爪 3D 模型仍然可用。当前参考产物约为 340 MiB：

```powershell
python build\build_exe.py --profile lite --clean-dist
```

只有需要 RAFT/CUDA 或 CuPy 后端时才使用完整配置。完整配置会包含 CUDA
运行库，产物通常为数 GB：

```powershell
python build\build_exe.py --profile full --clean-dist
```

需要包含源码和 Python 3.11 虚拟环境的 Windows x64 包时，在 `py311`
环境运行：

```powershell
conda activate py311
python build\build_venv_bundle.py
```

该包使用精简运行环境，不包含 Torch/CUDA、CuPy 和 Open3D。输出位于
`release\GripperDemo02-windows-x64-py311-venv-YYYYMMDD.zip`。

轻量配置要求传感器配置中的 `tracker.algorithm` 为 `dis`；打包脚本会在
构建前检查并阻止错误的 RAFT 轻量包。

输出文件在：

```text
dist\GripperDemo02\GripperDemo02.exe
```

打包完成后，脚本会把 `config` 和 `sdk` 复制到 exe 同级目录：

```text
dist\GripperDemo02\config
dist\GripperDemo02\sdk
```

现场修改参数时，直接改 exe 同级的 `config\gripper.json`。

窗口版 EXE 的运行日志保存在同级 `logs` 目录。`logs\latest.txt` 记录最近
一次运行的会话目录；其中 `main.log` 是 GUI/控制日志，`worker_*.log` 是
左右传感器进程日志，并包含 OpenCV 原生警告和异常 traceback。程序自动保留
最近 10 次运行。

### Linux

Windows 生成的 `.exe` 仅用于 Windows。Linux 需要在 Linux 环境使用同一份
源码重新安装依赖和打包，推荐 Python 3.11：

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
pip install -e ../orisys-sdk
python build/build_exe.py --profile lite --clean-dist
```

Linux 产物没有 `.exe` 后缀，位于 `dist/GripperDemo02/GripperDemo02`。直接
运行源码可使用：

```bash
python -m gripper.visualizer --windowed
```

将 `config/gripper.json` 的串口从 `COM*` 改为实际设备，例如
`/dev/ttyUSB0`；摄像头通常对应 `/dev/video0` 和 `/dev/video1`。运行用户需
拥有 `video` 与 `dialout` 设备组权限。WSL 还需要先透传 USB 摄像头和串口。

## 关键配置

- `trigger_normal_force`: 单侧法向力触发阈值。
- `trigger_shear_force`: 单侧切向力触发阈值。
- `trigger_clear_stable_seconds`: 张开恢复后，触发力必须清掉并稳定多久，才允许下一次扫过触发。
- `grip_normal_force`: 夹住时左右接触阈值。
- `grip_requires_both`: 是否必须左右都接触才算夹住。
- `grip_start_force`: 检测到物体后先切到的低力。
- `force_ramp_step`: 慢慢加力时每次增加多少 force_pct。
- `force_ramp_interval`: 慢慢加力时两次加力的间隔。
- `hold_force`: 慢慢加力到这个值后进入 `hold_check`。
- `grip_settle_seconds`: 夹住后等待稳定多久再记录参考力。
- `adaptive_grip_enabled`: 是否启用按切向力估计负载并自适应补夹紧力。
- `adaptive_shear_start_force`: 切向力低于这个值时，认为是轻物体，只使用最小目标力。
- `adaptive_shear_full_force`: 切向力达到这个值时，认为负载较大，目标力加到最大目标力。
- `adaptive_force_min`: 自适应夹持的最小目标力。
- `adaptive_force_max`: 自适应夹持的最大目标力；重物夹不住优先加这个，但不要超过 `force_max`。
- `adaptive_force_step`: 自适应补力时每次增加多少 `force_pct`。
- `adaptive_force_interval`: 自适应补力两次之间的间隔，越大越柔和。
- `release_arm_delay_seconds`: 自适应补力停止后，等待多久再启用“人取物松开”检测。
- `release_normal_change`: 夹住后法向力变化超过它就松开。
- `release_shear_change`: 夹住后切向力变化超过它就松开。
- `release_open_speed`: 检测到松开后，张开到 `open_pos` 使用的速度。
- `release_open_accel`: release 张开的加速度。
- `release_open_decel`: release 张开的减速度。
- `rearm_seconds`: 夹爪回到 `open_pos` 或恢复条件成立后，至少休息多久才重新等待触发；休息期间扫过也不会闭合。
- `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` 中读取夹爪当前位置的间隔。
- `normal_force_calibration`: 法向力标定，配置在 `config\gripper.json`。
- `shear_force_calibration`: 切向力标定，配置在 `config\gripper.json`。

## 日志字段

- `L/R`: 左右法向力，单位 N。
- `maxN`: 左右法向力最大值，单位 N。
- `shear`: 左右切向力最大值，单位 N。
- `trigger`: 是否满足单侧触发条件。
- `armed`: 是否已经重新武装；只有 `trigger=1 armed=1` 且是新的一次触发上升沿才会闭合。
- `grip_contact`: 是否满足夹住接触条件。
- `dN`: 夹住后当前法向力相对参考值的最大变化，单位 N。
- `dShear`: 夹住后当前切向力相对参考值的变化，单位 N。
- `state`: 当前状态。
- `hold_pos`: 夹住后保持的位置。
- `force_pct`: 当前夹爪目标力百分比。
- `target`: 当前根据切向力计算出来的自适应目标力。
- `release_armed`: 是否已经启用释放检测；`0` 表示还在补力/等待稳定，`1` 表示法向或切向变化会触发张开。
- `action`: 当前动作。

## 可视化展示

- 左右两边的光流箭头图。
- 左右两边的光流幅值图。
- 左右法向力、左切向力、右切向力。
- 当前 `state`、`action`、`trigger/armed`、`grip_contact`。
- 当前 `force_pct`、自适应目标力、速度 `speed_pct`、`hold_pos`。
- 顶部有 `重启` 按钮，会先停止当前控制线程，释放相机与夹爪后再重新启动。
- 当前 `release_armed`，用于判断系统是在补夹紧力，还是已经开始检测人取物松开。
- 折线图带图例，默认固定 y 轴为 `0~3 N`，范围在 `visualizer.py` 顶部的 `PLOT_FORCE_Y_MIN_N / PLOT_FORCE_Y_MAX_N` 调整。
- 左右传感器 FPS、接触标志、光流均值/最大值。
- 中间 3D 夹爪使用 `crt_ctag2f90d_gripper_visualization` 里的完整 STL/URDF 实体面片模型；启动时会预缓存 41 个开合档位，运行中只按实际位置切换缓存，避免拖慢控制延迟。

## 状态说明

- `open_wait`: 夹爪张开，等待任意单侧触发。
- `closing`: 单侧触发后正在闭合，等待检测到物体。
- `gripping`: 检测到物体后低力保持当前位置，并慢慢加力。
- `hold_check`: 已夹住；先根据切向力自适应补夹紧力，补力稳定后再监测法向/切向变化；变化超过阈值会直接张开。
- `open_recover`: 已经发出张开命令，正在等待回到初始点位或等待法向/切向残余力清空；这个状态不会闭合夹爪。

## 常见动作说明

- `force-change-release-open`: 检测到夹住后的法向或切向变化，已经发出张开命令。
- `adaptive-grip-ramp`: 切向力显示负载较大，正在按小步进增加夹紧力。
- `adaptive-grip-wait`: 已经需要更高目标力，但还没到下一次加力时间。
- `release-arm-delay`: 补力刚停止，正在等待力稳定，暂时不触发松开。
- `release-reference-armed`: 已重新记录释放参考力，后续法向/切向变化会触发张开。
- `open-recover-position`: 夹爪当前位置已经接近 `OPEN_POS`，正在等待到位稳定。
- `open-ready-position`: 夹爪已经回到初始点位，并且休息时间结束，重新进入等待下一次扫过触发；此时会直接武装，但残余触发保持不变不会自动闭合。
- `open-wait-clear-trigger`: 已经回到等待状态，但当前力还超过触发阈值，暂时不会闭合。
- `open-wait-trigger-clearing`: 触发力已经低于阈值，正在等待清零稳定时间。
- `open-wait-armed`: 触发已经清掉并稳定，下一次扫过可以闭合。
- `open-wait-trigger-held`: 已经武装，但当前触发不是新上升沿，等待力先降下去再下一次扫过。
- `open-recover-wait-force-clear`: 夹爪保持张开，但传感器还有残余力，不允许重新闭合。
- `open-recover-stabilizing`: 力已经低于恢复阈值，正在等待稳定和休息时间结束。
- `open-ready`: 力已经清空并稳定，并且休息时间结束，重新进入等待下一次扫过触发。