Gripper

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

展示流程

1. 程序启动后，夹爪先张开。
2. 程序等待任意一侧触觉传感器感受到法向力或切向力。
3. 展示时，把物体从某个侧边扫一下，触发单侧力变化。
4. 触发后夹爪开始闭合，你把物体移动到中间。
5. 闭合过程中检测到物体后，切到低力并保持当前位置。
6. 像 01 一样进入 gripping，先慢慢加力到基础 HOLD_FORCE。
7. 进入 hold_check 后，根据切向力估计物体负载；切向力越大，目标夹紧力越高，并按小步进继续补力。
8. 接触起立即检测新的侧触；侧触释放不等待固定夹稳计时。普通法向变化另有短保护，无需等爬力完成。
9. 新外力偏离既有曲线且持续，经新帧确认后张开到 OPEN_POS；原曲线变平、斜率变号和自然回落继续跟随，不靠累计位移释放。
10. 张开后进入 open_recover，保持张开并等待恢复条件。
11. 夹爪回到 OPEN_POS 初始点位，或法向/切向读数都低于恢复阈值并稳定后，继续休息至少 REARM_SECONDS。
12. 休息结束后才回到 open_wait 并重新武装；休息期间不管有没有物体扫过，都不会闭合。

运行

GUI 的完整模块说明、操作流程、参数表和故障排查见 GUI 使用说明书。 正式产品使用说明书（HTML，含界面截图，可打印/导出 PDF）见 产品使用说明书。

从项目根目录运行：

conda activate py311
python -m gripper.main

只看逻辑、不打开串口：

python -m gripper.main --dry-run

PyQt 可视化展示：

python -m gripper.visualizer

窗口模式运行：

python -m gripper.visualizer --windowed

兼容入口：

python -m gripper.visualizer

默认配置文件：

config\gripper.json

打包

先在 py311 环境里安装 PyInstaller：

conda activate py311
pip install pyinstaller PyOpenGL PyOpenGL_accelerate

然后从项目根目录运行：

python build\build_exe.py

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

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

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

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

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

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 轻量包。

输出文件在：

dist\GripperDemo02\GripperDemo02.exe

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

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：

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。直接 运行源码可使用：

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: gripping 进入 hold_check 的最早时间，不控制释放保护。
• 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: 自运动实际命令执行完成后的短保护，默认 0.12s，不是旧式总释放延时。
• release_min_hold_seconds: 普通法向接触保护，默认 0.28s；即时侧触路径不等待它。
• release_settle_seconds: 脉冲拒绝/断流后的短恢复保护，默认 0.06s；不再要求全局持续安静。
• release_normal_rate / release_shear_rate: 突变释放的速率门槛，默认 1.6 N/s。
• release_min_change: 普通突变/轻触的最小净变化，默认 0.04 N。
• release_side_touch_change: 即时侧触的左右力差变化，默认 0.06 N。
• release_touch_window_seconds: 新外力起始证据有效期，默认 0.2s；不是等待时间。
• release_confirm_samples: 突变确认新帧数，默认 2，包含首帧；平台偏移也能确认。
• release_slow_rate: 慢变日志分类速率，默认 0.4 N/s；参考跟随由曲线延续决定，不门控就绪。
• release_normal_change / release_shear_change: 中速外力累积的弱路径阈值，默认 0.28 N。
• release_slow_confirm_samples: 弱路径确认新帧数，默认 5。
• release_confirm_window_seconds: 释放候选最长有效期，默认 0.2s。
• release_sample_timeout_seconds: 采样断流后重新等待平稳的门槛，默认 0.2s。
• 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: 是否已经获得稳定通道基线；当前值相对该基线增长到触发阈值才会闭合。
• grip_contact: 是否满足夹住接触条件。
• dN: 夹住后当前法向力相对参考值的最大变化，单位 N。
• dShear: 夹住后当前切向力相对参考值的变化，单位 N。
• state: 当前状态。
• hold_pos: 夹住后保持的位置。
• force_pct: 当前夹爪目标力百分比。
• target: 当前根据切向力计算出来的自适应目标力。
• release_armed: 普通监视或候选确认；独立即时侧触是否运行还需看 side_watch。
• side_watch: 即时侧触监视，普通法向保护期间也可以为 1。
• action: 当前动作。

可视化展示

• 左右两边的光流箭头图。
• 左右两边的光流幅值图。
• 左右法向力、左切向力、右切向力。
• 当前 state、action、trigger/armed、grip_contact。
• 当前 force_pct、自适应目标力、速度 speed_pct、hold_pos。
• 顶部有 重启 按钮，会先停止当前控制线程，释放相机与夹爪后再重新启动。
• 当前 release_armed 及 release_side_watch，分别表示普通释放与即时侧触检测。
• 折线图带图例，默认固定 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: 已达到基础保持力；每 tick 先监视释放，再决定是否补力；候选确认优先于补力。
• open_recover: 已经发出张开命令，正在等待回到初始点位或等待法向/切向残余力清空；这个状态不会闭合夹爪。

常见动作说明

• force-change-release-open: 检测到夹住后的法向或切向变化，已经发出张开命令。
• adaptive-grip-ramp: 切向力显示负载较大，正在按小步进增加夹紧力。
• adaptive-grip-wait: 已经需要更高目标力，但还没到下一次加力时间。
• release-grip-settle: 普通法向接触保护，独立即时侧触仍可检测。
• release-self-settle: 普通法向自运动保护，独立即时切向侧触仍可检测。
• release-ready: 夹稳通过，开始监视释放。
• release-sudden: 突变外力候选及确认。
• release-touch: 新的曲线起始变化及轻推偏移确认，不要求大瞬时速率。
• release-side_touch: 即时侧触确认，不等固定夹稳时间。
• release-slow_internal: 缓慢变化跟随参考。
• release-slow_external: 新起始变化后达到弱路径幅度，经较长确认。
• release-transient-rejected: 候选回弹或方向改变，丢弃此次证据。
• release-settling-turn / curve=settling_turn: 平稳拐点，继续夹持。
• release-sample-gap: 传感器断流，丢弃旧证据，等待新帧后恢复监视。
• open-recover-position: 夹爪当前位置已经接近 OPEN_POS，正在等待到位稳定。
• open-ready-position: 夹爪已经回到初始点位，并且休息时间结束，重新进入等待下一次扫过触发；此时重新采集稳定基线，残余力保持不变不会自动闭合。
• open-wait-armed: 已锁定稳定通道基线，下一次增量侧触可以闭合。
• open-recover-wait-force-clear: 夹爪保持张开，但传感器还有残余力，不允许重新闭合。
• open-recover-stabilizing: 力已经低于恢复阈值，正在等待稳定和休息时间结束。
• open-ready: 力已经清空并稳定，并且休息时间结束，重新进入等待下一次扫过触发。

释放状态设计与验证

释放控制说明 包含独立 FSM、参数语义、曲线判据、 回放命令及实机验收步骤。每次自运动稳定后会保留至少约 100ms 的观察窗口；基础爬力 和自适应补力间隔因此可能比配置更长。侧触路径从接触就开始运行，普通法向与两侧共同变化仍有短保护。

python -m unittest discover -s tests -v

软件回放验证稳定后外力至释放决定不超过 200ms；相机、串口和机械延迟需实机测量。

所有释放路径都要求新的曲线起始变化。闭合前的趋势会带入接触阶段，避免把原曲线的拐点当新触碰。 每次自动释放后保存 logs/release-last.json，包含此前最多 120 帧控制快照与判据，用于复核实机误开。