06-四种漂相识别：下顿顶漂黑漂点漂的状态机设计
auto-fishing钓鱼漂相识别系统全栈实战系列 · 第6篇
前五篇搭好了整条流水线：CameraX推流 → HSV检测 → 卡尔曼平滑 → ByteTrack跟踪。现在每一帧，我们手里都攥着一条带稳定ID、丝般顺滑的浮漂轨迹。最后一问，也是整个系统存在意义的一问：这条轨迹里，藏着鱼吗？ 这一篇讲auto-fishing的灵魂模块------FloatSignalRecognizer，怎么用一台状态机，从y坐标的起起伏伏里，认出下顿、顶漂、黑漂、点漂四种漂相。
一、问题引入：这一下，是鱼还是浪？
拿到平滑轨迹后的第一反应，多半是"这不简单吗，漂动了就是鱼咬"。真上手做才知道，水面上的每一次坐标变化，都可能是以下四件事之一：
- 鱼咬钩（我们想要的信号）；
- 波浪推漂（低频、周期性的整体起伏，和某些漂相神似）；
- 风吹线动（漂被风线牵着缓慢平移）；
- 小鱼闹窝（连续的小幅点动------这个虽然也是鱼，但钓鱼佬管它叫"干扰"，一般不提竿）。
难点在于，这四种情况在坐标序列上的形态高度重叠 ：一个中等浪头能把漂推出20px的起伏，幅度和一次正经的下顿不相上下；而一次有气无力的鱼口，可能只有几个像素的动静。漂相识别的本质，是在噪声时序里找特定的模式------不仅要看"动了多少"，还要看"怎么动的"：多快、多久、是否回位、是否反复。
好消息是，钓鱼这项运动流传了几千年，四种漂相的"动作特征"早被钓鱼佬总结得明明白白。我们做的，就是把老师傅的经验翻译成代码。
1.1 四种漂相：钓鱼佬的经验词典
先补课，没钓过鱼的读者也能三分钟入门（钓过的请核对，看是不是这么回事）：
| 漂相 | 俗称 | 水下发生了什么 | 轨迹长相 |
|---|---|---|---|
| 下顿 | 顿口 | 鱼吸饵入嘴，拉动铅坠下沉 | 漂尖猛地下沉一小段（几厘米），随即弹回 |
| 顶漂 | 送漂 | 鱼叼着饵上浮，把漂顶起来 | 漂身持续上浮，缓慢而坚定 |
| 黑漂 | 吞死口 | 饵被拖走，整根漂被拖下水 | 漂持续大幅下沉直到没入水中 |
| 点漂 | 小鱼试探 | 小鱼在啄饵，还没吞 | 漂尖小幅高频抖动，反复上下 |
注意画面坐标系里y轴向下（OpenCV惯例，原点在左上角），所以：
- 下沉（下顿、黑漂）→ y坐标增大；
- 上浮（顶漂）→ y坐标减小。
后面所有判据的符号方向都由这条约定决定，先钉死，免得晕。
二、新手科普：状态机与EMA
2.1 状态机：给"漂的心跳"分阶段
状态机（State Machine） 是一种把"系统在任意时刻处于哪个阶段、什么条件才能切换到下一阶段"写得明明白白的设计。红绿灯就是天然的状态机：红灯→（计时到）→绿灯→（计时到）→黄灯→（计时到）→红灯，循环往复。
漂相识别为什么适合状态机？因为一次漂相是一个有头有尾的过程，不是一帧的瞬时事件：
漂相的生命周期：
静止 → 动作开始 → 动作进行中 → 特征满足 → 触发事件 → 冷却 → 复位如果不用状态机，每帧独立判断"这是不是下顿"，会出现同一动作被连续触发十几次的惨剧（漂下沉的那10帧，每帧都满足"在下沉"）。状态机用"冷却期"和"复位条件"保证：一次动作，最多报一次。
2.2 EMA：指数移动平均
EMA（Exponential Moving Average，指数移动平均） 是最便宜的低通滤波：
ini
ema = α × new_value + (1 - α) × emaα是平滑系数：α=1完全不平滑，α越小越平滑也越迟钝。EMA的妙处是一行代码、O(1)内存、天然适合流式数据。
本项目用了三通道EMA：对原始信号同时维护快、中、慢三个不同α的EMA。为什么三个？因为不同漂相的动作频率不一样------下顿是瞬时冲击（快通道抓），顶漂黑漂是持续趋势（中通道看），波浪是低频背景（慢通道测幅度）。一个α吃遍天下是不可能的，三根均线各司其职，这就是信号处理版的"长短结合"。
举个具体例子（α_fast=0.5, α_slow=0.05）：
makefile
输入: 210 210 210 220 230 210 210 210 210 210
快EMA: 210 210 210 215 222 216 213 211 210 210 ← 灵敏，跟住了第4帧的脉冲
慢EMA: 210 210 210 210 211 211 211 210 210 210 ← 迟钝，脉冲基本被抹平一帧的脉冲（可能是单帧检测噪声）在快通道留下痕迹但会被判据的持续性条件排除；持续的趋势（真鱼口）则快慢通道一起响应。快慢通道的差值本身也是信息------它近似"去趋势后的瞬时波动"，是点漂判据的核心原料。
2.3 为什么以y坐标为主信号
所有漂相的本质都是垂直方向的运动 （下沉/上浮/抖动），水平方向只受风线牵引，不含鱼口信息。所以识别器以卡尔曼平滑后的y坐标序列为主信号，全程只分析这一个通道------一维信号，判据、调试、可视化全都简单一个数量级。这是"选对特征，问题就解决了一半"的教科书案例。
三、FloatSignalRecognizer 的设计骨架
先看整体结构（精简版骨架，完整判据后面逐个拆）：
python
class FloatSignalRecognizer:
"""以y坐标为主信号的漂相识别器（每条已确认轨迹一个实例）。"""
def __init__(self, track_id):
self.track_id = track_id
# ---- 主信号缓冲区 ----
self.y_hist = [] # 平滑后y坐标历史（定长滑窗）
self.t_hist = [] # 对应时间戳
# ---- 三通道EMA ----
self.ema_fast = None # α=0.5，抓瞬时冲击（下顿）
self.ema_mid = None # α=0.2，看中等趋势（顶漂/黑漂位移）
self.ema_slow = None # α=0.05，测波浪背景幅度
# ---- 状态机 ----
self.state = "IDLE" # IDLE → ACTIVE → COOLDOWN → IDLE
self.last_event_time = 0.0 # 冷却计时起点
self.cooldown = 2.0 # 冷却时长（秒）
# ---- 波浪幅度（抗风浪联动，第7篇主角）----
self.wave_amp = 0.0 # 慢波浪幅度估计（px）
def update(self, y, t, tracked):
"""每帧喂入：平滑后y坐标、时间戳、跟踪是否正常。"""
self._push(y, t) # 维护历史和三通道EMA
if not tracked:
return self._handle_lost(t) # 漂消失 → 黑漂兜底判定
if self._in_cooldown(t):
return None # 冷却期，闭麦
return self._check_patterns(t) # 逐个判据检查主循环的状态流转：
scss
┌──────────────────────────────────────────────┐
│ │
▼ │
┌────────┐ 检测到漂，轨迹确认 ┌────────┐ │
│ 等待 │ ───────────────────▶ │ 跟踪中 │ │
│ DETECT │ │ ACTIVE │ │
└────────┘ └───┬────┘ │
▲ 某判据满足 │ 持续喂数据 │
│ ┌──────────────────┼───────┐ │
│ ▼ ▼ │ │
│ ┌─────────┐ (无漂相) │ │
│ │ 触发事件 │ _emit()发射事件 │ │
│ └────┬────┘ │ │
│ │ 进入冷却 │ │
│ ┌────▼─────┐ │ │
│ │ COOLDOWN│──── 冷却期满复位 ───┼───────┘
│ └──────────┘ │
│ ▲ │
└───────────┴── 漂丢失超时 → 轨迹终结 ──┘
(_handle_lost 可能先触发黑漂)四个状态含义：
- DETECT（等待）：轨迹刚建立，攒数据。历史窗口不满、EMA未热身时不做任何判断（否则前几帧必误报）；
- ACTIVE（跟踪中）：正常状态，每帧跑四套判据；
- 确认漂相 ：任一判据的全部条件同时满足，调用
_emit()发射事件； - COOLDOWN（冷却）：事件发出后2秒内不再判断。物理依据：鱼口之间通常有间隔，连珠炮式的漂相在自然界几乎不存在，冷却期是性价比最高的防误报手段。
四、四种漂相的判据（系统灵魂，逐个精讲）
约定：以下y均为卡尔曼平滑后的坐标，"速度"指相邻帧y差（px/帧，30fps下乘30换算成px/秒）。
4.1 下顿（顿口）：快、深、弹得回
下顿是钓鱼佬最爱的漂相------鲫鱼吃口的经典信号。它的动作指纹有三条：
- 快：下沉速度突增，峰值速度要够猛；
- 深：从动作起点到谷底要有足够深度；
- 弹回 ：这是区分"鱼口"和"水流"的分水岭------鱼吸饵是一瞬间的力，漂被拉下去后会弹回来；水流推漂是持续的力，漂下去了就不回来。回位程度是下顿判据里最精妙的一票。
判据四条（全部AND）：
erlang
① 速度 > 3.5 px/帧 （瞬时冲击，快通道）
② 局部深度 ≥ 12 px （从峰值前的高点到谷底的落差）
③ 回位到 35% （谷底后回弹超过深度的35%）
④ 峰值速度 ≥ 4 px/帧 （窗口内最大速度，兜底确认"猛"）①和④看起来重复，其实分工不同：①是"当前帧在下沉"的触发器，④是"这个动作整体够猛"的确认器。配合使用可以滤掉"缓慢但持续"的假动作。
核心代码：
python
def _check_dip(self, t):
"""下顿检测：快下沉 + 足够深度 + 回位。"""
n = len(self.y_hist)
if n < 15: # 数据不足，先攒着
return None
# ---- ① 当前速度：最近3帧的平均下沉速度 ----
# 用3帧均值而非单帧差分，抗单帧毛刺
vel = (self.y_hist[-1] - self.y_hist[-4]) / 3.0 # px/帧，正=下沉
if vel <= 3.5: # 判据①
return None
# ---- ② 局部深度：向前找一个局部高点，量到当前谷底 ----
# 从当前往回搜，高点=y最小的帧（y最小=漂位置最高）
window = self.y_hist[-20:] # 最近20帧找局部结构
peak_idx = int(np.argmin(window)) # 局部高点（漂的最高位置）
depth = window[-1] - window[peak_idx] # 高点到当前的落差
if depth < 12.0: # 判据②
return None
# ---- ③④ 回位确认：等几帧看它弹不弹回来 ----
# 动作进行中先记下谷底，回位后一次性确认
if self._dip_pending: # 已进入"疑似下顿"待确认态
rebound = self._dip_peak_y - min(self.y_hist[-5:]) # 弹回量
if rebound >= self._dip_depth * 0.35: # 判据③ 回位35%
if self._dip_peak_vel >= 4.0: # 判据④ 峰值速度
return self._emit("dip", t) # 实锤下顿！
else:
# 记录疑似下顿的现场，下一轮来验收
self._dip_pending = True
self._dip_peak_y = window[peak_idx]
self._dip_depth = depth
self._dip_peak_vel = vel
return None逐行拆解三个关键计算：
- 速度怎么算 ：
(y[-1] - y[-4]) / 3.0，3帧平均速度。为什么不用y[-1]-y[-2]？单帧差分对噪声太敏感（哪怕平滑后仍有±0.8px残差，除以1帧就是±0.8px/帧的速度噪声）；3帧均值把速度噪声再压一半，而3帧（0.1秒）的时间颗粒度对下顿这种0.2秒级的动作完全够细； - 局部深度怎么算：在最近20帧里找y的最小值（漂的最高点）当基准，从它量到当前。为什么不直接用"固定基准点"？因为漂的静止水位本身在漂移（波浪、水位变化），相对局部高点的深度才是"动作本身的幅度"；
- 回位怎么判 ：记下动作的谷底y，之后每帧看
rebound = 高点y - 最近5帧最小y，弹回超过深度的35%即认为"弹回来了"。35%这个数字来自实测：真顿口的回位普遍在50%以上（甚至完全复位），水流感假动作的回位通常不足20%，35%是留了余量的分界线。
4.2 顶漂（送漂）：持续、坚定、方向朝上
顶漂是鱼叼饵上浮把漂顶起来的漂相，典型如鲫鱼抬头游走。动作指纹：方向朝上（y减小）+ 持续 + 幅度可观。判据：
scss
位移 < -阈值，持续 ≥ 12帧（0.4秒）
其中 阈值 = max(20px, 1.8 × 慢波浪幅度)注意负号：y减小是上浮。这条判据的灵魂在阈值的自适应公式：
python
def _check_float_up(self, t):
"""顶漂检测：持续上浮，阈值随波浪幅度自适应。"""
n = len(self.y_hist)
if n < 20:
return None
# ---- 动态阈值：跟慢波浪幅度联动 ----
# 静水: wave_amp≈2px → 阈值=max(20, 3.6)=20px
# 中浪: wave_amp≈25px → 阈值=max(20, 45)=45px
thr = max(20.0, 1.8 * self.wave_amp)
# ---- 最近12帧（0.4s）的整体位移：首尾之差 ----
seg = self.y_hist[-12:]
disp = seg[-1] - seg[0] # 负 = 上浮
if disp < -thr: # 上浮幅度超过阈值
# 追加确认：中途不能出现大幅反向下沉（那是下顿/浪头）
if max(seg) - min(seg) < thr * 2.0:
return self._emit("float_up", t)
return None为什么要跟"慢波浪幅度"联动？ 这是抗风浪设计的点睛之笔。波浪对漂的推动是低频起伏，一个中浪能轻松把漂顶起25px------比静水里的顶漂阈值（20px）还大。如果阈值写死20px，起浪后每一次浪头都会被误判成顶漂，误报刷屏。把阈值和波浪幅度绑定后：
- 静水 ：wave_amp≈2px，阈值=max(20, 3.6)=20px------只认正经的上浮；
- 中浪 ：wave_amp≈25px，阈值=max(20, 45)=45px------浪能推25px没关系，要顶着比浪高近一倍的位移才算顶漂；
- 大浪 ：wave_amp≈40px，阈值=max(20, 72)=72px------门槛继续抬高。
同一套判据，在不同浪况下自动"水涨船高"，这就是**"同一判据在不同浪况下自适应"**的具体含义。1.8倍这个系数留了0.8倍的安全余量------浪的瞬时峰值会超过慢通道估计的平均幅度，不留余量的话大浪的单个浪头还是会漏过来。而持续12帧（0.4秒）的条件是另一道闸门：浪头推动的节奏是波浪周期（通常1~2秒一个），0.4秒内的持续单向位移与浪的往复节奏错开，进一步降低混淆。
4.3 黑漂（吞死口）：要么沉到底，要么直接消失
黑漂是最有戏剧性的漂相------鱼（常见鲤鱼、鲶鱼）把饵连漂一起拖下水，漂身没入水中，所以叫"黑"（漂不见了，水面一片黑）。动作指纹：大幅持续下沉，或干脆人间蒸发。判据是"或"的关系：
位移 > 阈值，持续 ≥ 10帧（0.33秒） ------ 轨迹路线：看着漂被拖下去
或 漂消失判定（_handle_lost触发） ------ 兜底路线：漂直接没了
python
def _check_black(self, t):
"""黑漂检测：持续大幅下沉（消失兜底在_handle_lost里）。"""
n = len(self.y_hist)
if n < 20:
return None
thr = max(25.0, 2.0 * self.wave_amp) # 黑漂阈值也跟浪联动，稍宽于顶漂
seg = self.y_hist[-10:] # 10帧 ≈ 0.33秒
disp = seg[-1] - seg[0] # 正 = 下沉
if disp > thr: # 大幅持续下沉
# 方向一致性：中途不能有大幅回弹（那是浪的往复）
if max(seg) - seg[0] < thr * 0.5: # 回弹不超过阈值一半
return self._emit("black", t)
return None为什么黑漂比顶漂宽松（10帧 vs 12帧、阈值系数2.0但基数25px）？两个原因：①黑漂的商业价值最高（吞死口中鱼率极高），宁可灵敏度高一档；②黑漂的运动形态（持续单向大幅下沉）本身比顶漂更容易和波浪区分------浪是往复的，黑漂是一去不回头，"中途回弹不超过阈值一半"这个条件把它锁得很死。
4.4 点漂：高频、反复、有节奏地啄
点漂最难写，因为它的单次动作幅度最小（小鱼啄一口就几像素），必须靠统计特征 而不是单次动作来识别。动作指纹：高频抖动 + 反复翻转 + 有基本的速度底线。判据三条AND：
① 峰峰值 ≥ 8.5px，持续 0.7秒（21帧）
② 0.8秒内 ≥ 3次强翻转
③ 平均速度 ≥ 1.6 px/帧
python
def _check_nibble(self, t):
"""点漂检测：小鱼连续啄饵的高频抖动。"""
n = len(self.y_hist)
if n < 21: # 0.7s @ 30fps
return None
seg = self.y_hist[-21:] # 最近0.7秒窗口
# ---- ① 峰峰值：窗口内最高与最低的落差 ----
pp = max(seg) - min(seg) # peak-to-peak
if pp < 8.5:
return None
# ---- ② 强翻转计数：方向反转且摆幅够大的次数 ----
# "强"= 每段单向运动至少2px，滤掉纯噪声的高频计数
flips, last_y, seg_start = 0, seg[0], seg[0]
direction = 0 # 0=未定 1=向下 -1=向上
for y in seg:
d = y - last_y
if direction == 0:
if abs(y - seg_start) >= 2.0: # 攒够2px才认方向
direction = 1 if d > 0 else -1
elif d * direction < 0: # 方向反了
if abs(y - seg_start) >= 2.0: # 且反摆够2px → 强翻转
flips += 1
direction = -direction # 更新当前方向
seg_start = y # 重置段起点
last_y = y
if flips < 3: # 0.8s内至少3次强翻转
return None
# ---- ③ 平均速度：0.7秒内的平均绝对速度 ----
diffs = [abs(seg[i+1] - seg[i]) for i in range(len(seg)-1)]
mean_vel = sum(diffs) / len(diffs)
if mean_vel >= 1.6: # 抖动要有速度底线
return self._emit("nibble", t)
return None翻转怎么数是这段代码的精髓，展开讲讲。所谓强翻转，就是轨迹"调头"且调头前后的摆幅都超过2px。为什么要强调"强"？看这段对比：
makefile
纯噪声（平滑后残差±0.8px）：
y: 210.3 210.8 210.2 210.9 210.4 ...
相邻差一正一负，"方向"每帧都在变，但摆幅<2px
→ 每次都不满足"攒够2px"，flips恒为0 ✓ 正确忽略
真点漂（小鱼啄饵）：
y: 210 213 215 214 211 209 210 213 214 ...
下→上→下，每次摆幅3~5px
→ 每段都攒够2px，flips蹭蹭上涨 ✓ 正确捕获"2px段幅"这道门槛把"方向翻转"这个噪声敏感的统计量，变成了鲁棒的判别特征。三条件缺一不可：①峰峰值保证总体动静够大；②翻转数保证"反复啄"的节奏感（这是点漂区别于单次下顿的本质）；③平均速度保证持续的活跃度（排除缓慢的漂移）。压测数据里中浪下依然保持100%查全率，点漂这条三重门功不可没------浪再大，它也造不出"0.7秒3次强翻转+高速"的节奏，浪是宏观的，啄饵是微观的。
五、_handle_lost()：漂消失的黑漂兜底
还记得第5篇的max_lost=30吗？跟踪器判定轨迹丢失后，会通知识别器。这里面藏着黑漂的第二条判定路线：
python
def _handle_lost(self, t):
"""跟踪丢失处理：之前轨迹正常 + 突然消失 → 黑漂兜底。"""
# ---- 前提1：消失前轨迹是"正常"的 ----
# 丢了不能丢得太凑巧------如果消失前正在剧烈运动
# （比如正在大幅下沉），消失本身就是被拖下水的铁证
recent = self.y_hist[-10:]
if len(recent) < 10:
return None # 历史不足，无从判断
pre_disp = recent[-1] - recent[0] # 消失前10帧位移
# ---- 前提2：消失前有明显的下沉趋势 ----
if pre_disp > 8.0: # 消失前在下沉 ≥8px
return self._emit("black", t, reason="lost") # 黑漂！
return None物理逻辑：鱼把漂拖入水下，HSV检测找不到目标色块，跟踪器丢失目标。如果丢失恰好发生在持续下沉之后------下沉8px以上然后人间蒸发------这几乎不可能是别的原因（浪盖漂通常伴随幅度回归、镜头遮挡会让所有漂一起丢）。"下沉+消失"的组合证据链，比单纯"消失"可信得多，所以代码里特意检查了pre_disp而不是见到丢失就报黑漂。
这条兜底路线的价值：轨迹路线的黑漂判定（4.3节）需要"看到"漂沉下去的全过程，而消失兜底在漂还没沉完就没了的极端场景下依然能触发------鱼太猛、直接把漂拖爆了画面，判据反而更简单。
六、_emit()：事件的最后一公里
所有判据的终点都是 _emit()，它负责三件事：组装事件、查冷却、切状态。
python
def _emit(self, event_type, t, reason=""):
"""发射漂相事件。返回事件dict，冷却期内返回None（吞掉）。"""
# ---- 冷却检查：上次事件后2秒内不发新事件 ----
if t - self.last_event_time < self.cooldown:
return None
# ---- 组装事件 ----
event = {
"track_id": self.track_id, # 哪根漂
"type": event_type, # dip / float_up / black / nibble
"time": t, # 时间戳（秒）
"y": self.y_hist[-1], # 事件发生时的漂位置
"reason": reason, # 触发细节（调试用）
}
# ---- 切状态：进入冷却 ----
self.last_event_time = t
self.state = "COOLDOWN"
# 复位各判据的中间状态（比如下顿的pending标记）
self._dip_pending = False
return event冷却机制的双重意义：
- 物理合理性：一竿子鱼口之间有间隔，2秒内的连发事件大概率是同一次动作的余波被重复判定；
- 系统礼仪：下游（App提醒、语音播报）不希望被刷屏。一次漂相一次提醒，钓鱼佬的手机才不会变成复读机。
冷却期结束后（_in_cooldown()返回False），状态机回到ACTIVE，识别器继续待命。整个生命周期里，识别器就在ACTIVE和COOLDOWN之间来回摆，状态极简------好的状态机不是状态多，而是每个状态都不可再删。
七、为什么是规则，而不是机器学习？
写到这，一定有读者嘀咕：都2026年了，四大判据+一堆阈值，是不是太"手工"了？上个LSTM/Transformer把y序列分类一下不香吗？
这个问题值得认真回答，因为它是auto-fishing项目最重要的技术决策之一。规则方案（多条件AND+阈值）的三大优势：
- 可解释：每个误报都能追溯到具体判据、具体阈值。实测发现大浪下点漂误报，一看是wave_amp联动系数1.8不够，调到2.0，问题解决------从定位到修复半小时。换成黑盒模型，你只能对着混淆矩阵干瞪眼，重训一轮赌运气；
- 可调参：钓鱼场景的个体差异极大（漂型、水深、流速、鱼种），用户完全可以微调阈值适配自己的钓场。规则系统的参数有物理含义（"回位到35%"），说明书上一句话讲明白；模型的参数是浮点矩阵，无从下手；
- 零数据标注成本：训练模型需要成千上万条带标注的漂相序列。漂相数据采集极难（要蹲守真鱼口），标注极贵（要钓鱼老手逐帧看）。规则方案把这个成本直接归零------这也是项目能以"零模型零依赖"姿态跑在一台老笔记本上的前提。
那什么时候该上模型？ 给一个诚实的判断框架：
| 情形 | 建议 |
|---|---|
| 目标类别少（个位数）、特征清晰、有领域知识可编码 | 规则够用（本项目） |
| 类别多、特征模糊、领域专家也说不清判据 | 上模型 |
| 需要跨场景泛化（不同水质、漂色、鱼种混战） | 规则+模型混合，规则兜底 |
| 边缘部署、无GPU、无训练数据 | 规则优先 |
本项目压力测试的成绩单------平静水面查全率/查准率100%/100% ，小浪92%/100% ，中浪100%/100% ，大浪76%/76% ------证明了在这个场景下，规则方案的上限足够高。大浪下76%的查全率掉档，根因是波浪幅度估计本身在大浪下不够准（估计偏低导致联动阈值不够高），这是信号质量问题而不是范式问题，换模型同样要吃这个瘪。真要突破大浪，方向是改进波浪估计，而不是把判据换成黑盒。
一句话总结选型哲学：规则不是低级的代名词，模型不是高级的护身符；能把领域知识写清楚的，写清楚就是最优解。
再补一笔成绩单背后的"术语账"：系统输出的下顿（顿口）、顶漂（送漂）、黑漂（吞死口/大鱼拖走）、点漂（小鱼试探/口轻）------四种漂相全是钓鱼佬口中的真实术语，不是抽象的"异常动作1/2/3/4"，判据的每一条都对应老师傅的一句口诀。判据触发后，安卓App上画面实时标注，中文语音播报「下顿！提竿！」第一时间响起------手机端就能跑，纯局域网、不依赖云端。效果数据上，中小浪况查全率/查准率保持92%100%、表现优异；大浪（16px波浪 vs 1026px咬口信号）接近物理可分极限，肉眼同样难以判读，系统优先保证不误报（宁缺毋滥）。也就是说，在钓鱼佬真正会看漂出手的浪况里，这套状态机的表现是拿得出手的。
八、调参实战：让判据适配你的钓场
四个判据、十来个阈值，新手拿到手怎么调？给一套实测验证过的流程：
第一步：先固定物理量纲。 确认帧率（判据里的"帧"全部按30fps标定；如果你的推流是15fps，所有"持续N帧"翻倍、"px/帧"阈值减半）。这是新手翻车重灾区------参数没错，量纲错了。
第二步：静水基线。 无风无浪无鱼的水面跑10分钟，要求零事件。有误报 → 看事件reason字段定位是哪个判据 → 该判据的幅度类阈值+30%再试。静水都过不了，别急着下水。
第三步：单漂相标定。 手拿漂在镜头前模拟四种动作（下沉回弹=下顿、缓慢上提=顶漂、快速按入水中=黑漂、高频抖动=点漂），每种20次，统计触发率。低于90%就调低对应判据的核心阈值。
第四步：波浪边界测试。 往水里扔石子造浪，从小浪到大浪逐级测试，观察wave_amp读数和各判据阈值是否联动。联动失效（浪大但阈值没涨）优先查波浪幅度估计模块，而不是改判据。
第五步：实战回归。 真钓一场，记录全部事件和当时的视频，误报漏报逐条复盘。记住调参铁律：一次只改一个参数，每改一次做一轮完整回归------多参数齐动的调参等于赌博。
九、新手常见坑
- 坐标方向搞反：OpenCV的y轴向下！下沉是y增大。判据符号错一个，下顿和顶漂互换，全系统行为镜像错乱且不报错。写代码前先在注释里钉死"y增大=下沉"；
- 判据用原始坐标而不是平滑坐标：绕过卡尔曼直接拿检测y做判据，第4篇算过账------静水噪声速度就有±6px/帧，3.5的阈值形同虚设，误报爆炸；
- 冷却期太短或没有：同一次下顿触发3个dip事件，用户直接卸载App。2秒是实测甜点值，钓鱼频率再高也不会1秒两口；
- 阈值写死不跟波浪联动 ：静水调好的参数，起浪必误报。所有幅度类阈值一律写成
max(基础值, 系数×wave_amp)的自适应形式； - 历史窗口用list无脑append ：跑两小时内存吃光。
y_hist必须是定长滑窗（deque(maxlen=N)或手动pop），这是长时值守（钓鱼动辄半天）的基本要求； - 点漂的翻转计数不设幅度门槛：数"方向变化"不数"强翻转"，平滑后的±0.8px残差每帧都算翻转，flips爆表，点漂满天飞。2px段幅门槛是命根子，不能省。
十、小结
漂相识别是整个auto-fishing系统的最后一环，也是最"懂钓鱼"的一环：
- 特征选择：所有漂相都是垂直运动，以卡尔曼平滑后的y坐标为单一主信号，配三通道EMA（快抓冲击、中看趋势、慢测波浪），问题从二维降到一维；
- 四套判据：下顿=快+深+回位35%（回位是鱼口与水流的分水岭）；顶漂=位移<-max(20px, 1.8×浪幅)持续12帧；黑漂=大幅持续下沉或消失兜底；点漂=峰峰值≥8.5+3次强翻转+速度底线------每条判据都对应老师傅的一句口诀；
- 状态机：DETECT→ACTIVE→确认→COOLDOWN→复位的极简循环，保证一次动作最多报一次；
- 自适应抗浪：幅度阈值与波浪幅度联动，静水严格、大浪宽松，同一套判据通吃四种浪况，中浪下依然保持100%查全率；
- 选型哲学：类别少、特征清晰、有领域知识 → 规则优于模型：可解释、可调参、零标注成本。
至此，auto-fishing的核心算法全貌已经完整：HSV检测（零模型抠漂）→ 2D恒速卡尔曼（轨迹熨平）→ ByteTrack两级匹配（身份不乱）→ 四漂相状态机（读懂鱼口），识别核心零第三方依赖，一部安卓手机加一台任意能跑Python的机器，纯局域网就能搭起一套自己的钓鱼AI。压力测试里那组数字------静水100%/100%、中浪100%/100%------不是靠某个单点黑科技，而是这条流水线上每一环各守一格、环环相扣的结果。把这套架构吃透，你收获的不只是一个钓鱼工具，而是一整套"传感器→滤波→跟踪→事件识别"的通用时序感知框架：换成监控水位、观察鸟类、分析乒乓球落点，骨架原样能跑。
🎣 关于 Auto-Fishing 项目
钓鱼漂相识别 ------ 让每一次咬口都不被错过
台钓/野钓时，盯漂是最累也最关键的环节：下顿、顶漂、黑漂、点漂四种真实漂相稍纵即逝，大风大浪时更是难以判读，很多钓友因此错过提竿时机。Auto-Fishing 用计算机视觉自动识别浮漂的四种漂相，并在第一时间给出语音提醒，把钓友从"死盯漂"中解放出来。
核心特性
| 特性 | 说明 |
|---|---|
| 四种真实漂相 | 下顿（顿口，经典咬口信号）、顶漂（送漂）、黑漂（吞死口/大鱼拖走）、点漂（小鱼试探/口轻） |
| 抗风浪 | 实时估计波浪幅度，速度/频率/持续时长三重判据，大风大浪下不误报不漏报 |
| 手机端可跑 | 安卓 App 调用摄像头，画面实时标注 + 中文语音播报「下顿！提竿！」 |
| 不依赖云端 | 纯局域网部署，数据不出本地，无订阅费用、无隐私风险 |
| 技术栈灵活 | Python 识别核心 + 卡尔曼滤波 + ByteTrack 跟踪；检测器可无缝切换 YOLO 深度学习 |
| 可自证 | 内置合成视频自检与压力测试，识别效果可量化评估（查全率/查准率） |
识别效果（合成演示视频，5 组随机场景）
| 浪况 | 波浪幅度 | 查全率 | 查准率 |
|---|---|---|---|
| 平静 | 4px | 100% | 100% |
| 小浪 | 8px | 92% | 100% |
| 中浪 | 12px | 100% | 100% |
| 大浪 | 16px | 76% | 76% |
大浪（16px 波浪 vs 10~26px 咬口信号）接近物理可分极限，该浪况下肉眼同样难以判读；系统优先保证不误报（宁缺毋滥），在中小浪况下表现优异。
三分钟跑起来（三种演示方式）
- 零素材演示 ：
python main.py demo------ 自动生成含四种漂相的合成钓鱼视频，识别并输出评估报告，一分钟内跑通全流程； - 实时演示 ：电脑跑
python main.py server，手机装 App 后同一 Wi-Fi 连上即可，摄像头对准水面浮漂，语音播报实时响起； - 压力演示 ：
python tools/stress_test.py------ 4 档波浪 × 多场景，直观展示抗风浪能力。
适用场景
- 台钓/竞技钓：代替人工盯漂，抓顿口、抓送漂；
- 教学演示：向新手展示什么是下顿/顶漂/黑漂/点漂；
- 技术验证：目标检测 + 跟踪 + 时序状态机 + 抗噪的完整示例工程；
- 产品化起点：识别核心可对接后台 Spring Boot 等，升级 YOLO 模型提升复杂场景鲁棒性。
获取方式
本项目为 demo 版本，源码、文档、安卓工程完整开放（README 快速开始 / 二次开发文档 / 部署文档）。系列文章里出现的每一个模块，仓库里都有完整可跑的实现------看完就能上手改。