# opencv_fish_detect **Repository Path**: jzcode/opencv_fish_detect ## Basic Information - **Project Name**: opencv_fish_detect - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-16 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 浮漂咬钩检测(OpenCV + 树莓派 4B) 用摄像头实时识别水面浮漂位置,并根据浮漂的运动轨迹判断是否被鱼咬钩。 ## 原理 分两步: 1. **定位浮漂**([detector.py](detector.py)):HSV 颜色阈值分割出浮漂的红/橙/黄 顶部 → 形态学去噪 → 轮廓提取 → 输出质心坐标。已定位过时优先在上次位置附近 的 ROI 内搜索(省 CPU),找不到再回退全帧。 2. **判断咬钩**([bite_detector.py](bite_detector.py)):对质心的时间序列做分析, 识别三种咬钩信号: - `submerge`:浮漂连续多帧检测不到(被拉入水中); - `dip`:相对基线突然下沉超过阈值; - `agitation`:短时间内垂直方向剧烈抖动。 基线是缓慢自适应的参考深度,用来抵消风浪的缓慢漂移,只在浮漂靠近基线时才 更新,因此咬钩瞬间能正确触发。触发后有不应期,避免一次咬钩重复报警。 3. **判断姿态**([posture_detector.py](posture_detector.py)):侧视/斜视下,直立时 彩色漂尾露出水面的高度最大;被拉倾斜、躺平或倒立时漂尾朝下没入水中,可见高度 缩短。用「当前高度 / 直立基准高度 ≈ cos(倾角)」估计倾角,倾角超阈值即判定为 倾斜/倒立,用于触发停止信号。 ## 安装 **树莓派 4B 推荐用系统自带的预编译 OpenCV**(省去编译、兼容 32/64 位系统): ```bash sudo apt update sudo apt install -y python3-opencv python3-numpy python3-pil ``` > 画面上的中文用 PIL 渲染([text_util.py](text_util.py)),需要 Pillow 和中文字体 > `fonts-noto-cjk`(提供 `NotoSansCJK-Regular.ttc`)。若字体缺失会回退到其他常见 > 中文字体,再不行中文会显示成方框但不影响程序运行。 > 字体缺失时补装:`sudo apt install -y fonts-noto-cjk`。 如果是 64 位系统且用虚拟环境,也可: ```bash python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt ``` ## 使用 ### 1. 现场校准颜色(重要) 不同浮漂颜色、光照条件差异很大,建议先跑调参工具,把滑条调到「只框住浮漂、 不误框水面反光」,按 `s` 打印 HSV 区间: ```bash python3 scripts/tune.py # 用摄像头 python3 scripts/tune.py --video a.mp4 # 用视频文件校准 ``` 把打印出的 `lower/upper` 值填进 [config.json](config.json) 的 `detector.hsv_ranges` (可只保留一组),并同步调整 `min_area`/`max_area`。 ### 2. 运行检测 ```bash python3 scripts/main.py # 用摄像头 + config.json python3 scripts/main.py --video a.mp4 # 用视频文件调试(无需摄像头) python3 scripts/main.py --config b.json # 指定其他配置 ``` 检测到咬钩时在控制台打印,并追加写入 `bites.log`(`output.log_file`)。按 `q` 退出。 ### 3. 视频离线测试(校准/排查推荐) ```bash python3 scripts/test_video.py --video 浮漂.mp4 # 保存标注视频 + 打印统计 python3 scripts/test_video.py --video 浮漂.mp4 --csv t.csv # 额外导出轨迹 CSV python3 scripts/test_video.py --video 浮漂.mp4 --no-preview # 不弹窗,只跑分析 ``` 运行结束后会打印:检测率、轨迹 x/y 范围、每个咬钩事件的时间/原因/位置, 并生成一份标注视频(框、质心、基线、轨迹、咬钩闪烁),便于判断是误报还是漏报。 ### 4. ROS2 发布浮漂状态(自定义消息 FishStatus) 通过 [bite_publisher.py](bite_publisher.py) 发布单一 topic `fish_status`, 消息类型为自定义的 [FishStatus.msg](fish_interfaces/msg/FishStatus.msg): | 字段 | 类型 | 含义 | | --- | --- | --- | | `bite` | `bool` | 是否被鱼咬钩(下沉/消失/抖动/倾斜倒立任一事件触发后,在 `bite_hold_seconds` 内保持 True) | | `angle` | `float32` | 浮漂倾角(度),0=直立,趋近 90=躺平/倒立 | 下游可用 `angle` 超过阈值作为**停止电机**信号(防止收线卡死)。 **首次使用先构建接口包**(一次性,之后每次开新终端 source 即可): ```bash source /opt/ros/humble/setup.bash colcon build --packages-select fish_interfaces \ --cmake-args -DPython3_EXECUTABLE=/usr/bin/python3 -DPYTHON_EXECUTABLE=/usr/bin/python3 source install/setup.bash ``` **运行节点**: ```bash source /opt/ros/humble/setup.bash source install/setup.bash /usr/bin/python3 bite_publisher.py # 摄像头 /usr/bin/python3 bite_publisher.py --video a.mp4 # 视频调试 # 另开终端接收 ros2 topic echo /fish_status ``` **浏览器看画面**(适合 Ubuntu Server 无显示器的场景):节点默认在 `8080` 端口起一个 MJPEG 视频流,用手机/电脑浏览器打开即可实时看到标注后的画面: ``` http://<树莓派IP>:8080/ # 实时画面 http://<树莓派IP>:8080/snapshot.jpg # 单帧截图 ``` 画面在后台用线程编码 JPEG,不影响检测主流程;无浏览器访问时几乎零开销。 > ⚠️ 注意 Python 版本:ROS2 Humble 用系统 Python **3.10**(`/usr/bin/python3`), > 而 conda 的 base 是 3.13、环境 `opencv_fish_detect` 是 3.11,rclpy 在这些版本下 > 无法 import。所以 ROS2 节点要用 `/usr/bin/python3` 运行,构建接口包时也必须 > 显式指定 `-DPython3_EXECUTABLE=/usr/bin/python3`(否则会生成到错误的 python 目录)。 > 并确保系统 python3.10 已装 cv2/numpy:`sudo apt install -y python3-opencv python3-numpy`。 > topic 名、保持时长、QoS 深度在 `config.json` 的 `ros2` 段修改。 ## 配置说明(config.json) | 参数 | 含义 | | --- | --- | | `camera.index / width / height / fps` | 摄像头编号、分辨率、帧率 | | `camera.fourcc` | 像素格式,`MJPG` 通常帧率更高;若摄像头不支持导致黑屏,改成 `""` | | `detector.hsv_ranges` | HSV 颜色区间(lower/upper 各为 H/S/V) | | `detector.min_area / max_area` | 轮廓面积过滤范围(像素) | | `detector.use_roi / roi_margin` | 是否启用 ROI 局部搜索及半径 | | `bite.sensitivity` | 灵敏度,越大越灵敏(按比例缩放下列四个阈值) | | `bite.missing_seconds` | 连续丢失多久判定为 `submerge` | | `bite.dip_pixels` | 相对基线突降多少像素判定为 `dip` | | `bite.baseline_window_seconds` | 基线窗口(取该窗口内 y 的中位数作参考深度) | | `bite.agitation_window_seconds` | 抖动判定窗口 | | `bite.agitation_min_step` | 计为一次摆动的单帧最小幅度(像素) | | `bite.agitation_reversals` | 窗口内方向反转次数达到该值判定为 `agitation` | | `bite.refractory_seconds` | 一次触发后的不应期 | | `posture.baseline_window_seconds` | 直立基准高度窗口(取中位数) | | `posture.baseline_adapt_angle_deg` | 倾角小于此值才更新直立基准 | | `posture.tilt_trigger_angle_deg` | 倾角超过此值判定为倾斜/倒立 | | `posture.tilt_min_seconds` | 持续倾斜多久才触发(防抖) | | `posture.refractory_seconds` | 姿态触发后的不应期 | | `output.show_window` | 是否显示实时画面(无屏幕/无头运行时设 `false`) | | `output.log_file` | 日志文件名,`null` 表示不写文件 | | `ros2.topic_status` | 发布 topic 名(默认 `fish_status`) | | `ros2.bite_hold_seconds` | 咬钩/倾斜触发后 `bite` 保持 True 的时长 | | `ros2.qos_depth` | 发布队列深度 | | `web.enable` | 是否开启 Web 视频流(默认 `true`) | | `web.host / web.port` | 监听地址/端口,浏览器访问 `http://<主机IP>:<端口>/` | | `web.jpeg_quality` | JPEG 压缩质量(1-100,越大越清晰但带宽越高) | | `record.enable` | 是否开启原始视频录制(默认 `true`,仅摄像头模式生效) | | `record.dir` | 原始视频保存目录(建议设绝对路径,如 `/home/pi/videos`) | | `record.segment_seconds` | 每个视频文件时长(秒,默认 60 = 1 分钟一个) | | `record.min_free_gb` | 磁盘剩余低于该值(GB)时删除最早的视频,循环覆盖 | | `record.fps` | 录制帧率(默认 15,可调高但会增加 CPU 开销) | | `record.fourcc` | 视频编码(`mp4v`,一般不用改) | | `yolo.enable` | 是否开启 YOLO 粗定位(默认 `false`,需先训练好模型) | | `yolo.model` | YOLO ONNX 模型路径 | | `yolo.interval_seconds` | YOLO 每多少秒跑一次(默认 30) | | `yolo.conf_thresh` | 置信度阈值 | | `yolo.topic_adjust` | YOLO 发布浮漂框的 topic 名(默认 `adjust_float`) | `dip_pixels` / `agitation_min_step` 依赖摄像头离浮漂的距离与分辨率, 需要按实际现场微调:太小容易误报(风浪),太大容易漏报(轻口)。 ### 灵敏度怎么调 `sensitivity` 是一个总旋钮,按比例缩放 `dip_pixels`、`agitation_min_step`、 `agitation_reversals`、`missing_seconds` 四个阈值(`1.0` 即 config 里的原值): | 场景 | 建议 sensitivity | 效果 | | --- | --- | --- | | 风平浪静 | 1.5 ~ 2.5 | 阈值减半左右,能抓到很轻的顿口 | | 有波纹/风浪 | 0.5 ~ 0.8 | 阈值放大,避免波浪起伏误报 | 命令行可临时覆盖,不用改 config: ```bash python3 scripts/main.py --sensitivity 2.0 python3 scripts/test_video.py --video 浮漂.mp4 --sensitivity 0.7 python3 bite_publisher.py --sensitivity 2.0 ``` ## 性能提示(树莓派 4B) - 分辨率 640x480 足够,不必更高。 - 保持 `use_roi=true`,浮漂定位后大部分帧只在局部处理。 - 若帧率仍不足,把 `camera.process_every_n` 设为 2(隔帧处理)。 - 无屏幕部署时把 `output.show_window` 设为 `false`。 ## 项目结构 ``` opencv_fish_detect/ ├── bite_publisher.py # ROS2 主节点:采集+检测+判钩+录制+发布 ├── detector.py # 浮漂定位 ├── bite_detector.py # 轨迹判钩 ├── posture_detector.py # 姿态判断(倾斜/倒立) ├── text_util.py # 中文文本绘制(PIL) ├── web_stream.py # Web MJPEG 视频流 ├── video_recorder.py # 原始视频录制 ├── yolo_detector.py # YOLO 粗定位(ONNX Runtime) ├── config.json # 全部可调参数 ├── fish_interfaces/ # 自定义 ROS2 接口包(FishStatus/FloatBox) ├── scripts/ # 工具脚本 │ ├── main.py # 非 ROS2 主程序 │ ├── test_video.py # 视频离线测试 │ ├── tune.py # HSV 颜色调参 │ ├── collect_float_data.py # 采集浮漂图片 │ ├── label_float_data.py # 简易标注工具 │ ├── extract_frames.py # 视频抽帧 │ └── labelme_to_yolo.py # labelme 转 YOLO 格式 ├── start_bite_publisher.sh # systemd 启动脚本 ├── bite_publisher.service # systemd 服务单元 ├── TRAIN_YOLO.md # YOLO 训练指南 └── requirements.txt ```