Initial commit: FishServer monorepo (FishAction, FishMeasure, fish_api)

Made-with: Cursor

FishMeasure/docs/TODO.md

@@ -0,0 +1,4 @@
+1. **用图像 bbox 过滤错误点云**：用图像中鱼的检测框来过滤掉「点云长度大于真实鱼长」的点云。失败案例分析表明 top-5 平均在多数情况下有效，失败多来自长度被高估的点云（遮挡、噪声或错误分割）。用 bbox 推导的长度约束过滤这些点云，应能提升重量估计。
+
+2. 能否加一个开关，开启后鱼检测与分割实时进行；若可行，模板匹配和重量计算放到新线程，不必等整段视频播完再做匹配与重量计算。
+

FishMeasure/docs/fish_segmentation_pipeline.md

@@ -0,0 +1,152 @@
+# 鱼类分割功能增强计划
+
+## 概述
+
+本文档描述在现有鱼类测量管道中添加鱼类分割功能的计划。该功能将实现鱼尾、鱼中段和鱼头的自动分割，以支持更智能的模板匹配和朝向检测。
+
+## 功能目标
+
+### 1. 鱼类部位分割
+- **鱼头（Fish Head）**：识别鱼的前端部分
+- **鱼中段（Fish Middle）**：识别鱼的主体部分
+- **鱼尾（Fish Tail）**：识别鱼的后端部分
+
+### 2. 自动朝向检测
+- 基于分割结果自动确定鱼的朝向（头尾方向）
+- 识别鱼是头朝前还是尾朝前
+- 为后续的模板对齐提供方向信息
+
+### 3. 点云完整性检测
+- 检测鱼尾部分是否包含完整的点云数据
+- 判断鱼尾点云是否存在缺失或遮挡
+
+### 4. 智能模板选择
+- **如果鱼尾有点云**：使用包含尾部的完整模板进行对齐
+- **如果鱼尾没有点云**：使用不包含尾部的模板进行对齐
+- 根据分割结果自动选择合适的模板
+
+## 实现方案
+
+### 阶段 1：分割模型开发
+
+#### 1.1 数据准备
+- 收集并标注鱼类点云数据，标记头、中段、尾三个部位
+- 创建分割数据集，包含不同角度、不同姿态的鱼类点云
+- 数据格式：点云 + 部位标签（head/middle/tail）
+
+#### 1.2 模型训练
+- 使用 PointNet++ 或 Point Transformer 进行点云分割
+- 参考现有 `pointcloud_classifier` 模块的架构
+- 训练三分类分割模型（头/中段/尾）
+
+#### 1.3 模型集成
+- 将分割模型集成到主处理管道中
+- 在点云提取后立即进行分割
+- 保存分割结果用于后续处理
+
+### 阶段 2：朝向检测
+
+#### 2.1 基于分割的朝向判断
+- 分析鱼头和鱼尾的空间位置关系
+- 计算鱼的主轴方向（PCA）
+- 确定头尾方向向量
+
+#### 2.2 方向标准化
+- 统一鱼的朝向（例如：统一为头朝正X方向）
+- 与现有的 `head_tail_alignment` 模块集成
+- 确保后续模板匹配的一致性
+
+### 阶段 3：点云完整性检测
+
+#### 3.1 鱼尾点云分析
+- 统计鱼尾部分的点云数量
+- 检测鱼尾点云的连续性
+- 判断是否存在明显的缺失区域
+
+#### 3.2 完整性评估
+- 定义完整性阈值（例如：点云数量、覆盖率等）
+- 输出布尔标志：`has_tail_pointcloud`
+
+### 阶段 4：模板选择逻辑
+
+#### 4.1 模板管理
+- 维护两套模板：
+  - **完整模板**：包含尾部的完整鱼类模板
+  - **无尾模板**：不包含尾部的鱼类模板
+
+#### 4.2 自动选择
+```python
+if has_tail_pointcloud:
+    template = load_template("fish_with_tail.obj")
+else:
+    template = load_template("fish_without_tail.obj")
+```
+
+#### 4.3 模板对齐
+- 根据选择的模板进行点云对齐
+- 利用朝向信息优化对齐过程
+- 确保对齐质量
+
+## 技术实现细节
+
+### 数据流
+
+```
+原始点云
+    ↓
+[分割模块] → 头/中段/尾标签
+    ↓
+[朝向检测] → 方向向量 + 标准化点云
+    ↓
+[完整性检测] → has_tail_pointcloud 标志
+    ↓
+[模板选择] → 选择合适的模板
+    ↓
+[模板对齐] → 对齐后的点云
+    ↓
+[体积计算] → 重量估算
+```
+
+### 模块集成点
+
+1. **在 `fish_video_weight_evaluation.py` 中**：
+   - 在点云提取后添加分割步骤
+   - 在模板匹配前添加模板选择逻辑
+
+2. **在 `template_matching/fish_align_cli.py` 中**：
+   - 添加模板选择参数
+   - 根据分割结果选择模板
+   - 优化对齐算法以利用分割信息
+
+3. **新增模块**：
+   - `segmentation/fish_segmentation.py`：分割模型推理
+   - `segmentation/orientation_detection.py`：朝向检测
+   - `segmentation/tail_completeness.py`：尾部完整性检测
+
+## 预期效果
+
+1. **提高对齐精度**：通过选择合适的模板，提高点云对齐的准确性
+2. **自动化处理**：减少人工干预，自动处理不同完整度的鱼类点云
+3. **鲁棒性增强**：能够处理尾部缺失或遮挡的情况
+4. **朝向一致性**：确保所有处理的鱼类朝向统一，便于后续分析
+
+## 实施优先级
+
+1. **高优先级**：分割模型开发和训练
+2. **中优先级**：朝向检测和点云完整性检测
+3. **低优先级**：模板选择逻辑优化和性能调优
+
+## 相关文件
+
+- `fish_video_weight_evaluation.py`：主处理管道
+- `template_matching/fish_align_cli.py`：模板对齐模块
+- `utils/head_tail_alignment.py`：现有的头尾对齐工具
+- `pointcloud_classifier/`：可参考的点云分类架构
+
+## 后续扩展
+
+- 支持多部位精细分割（例如：鱼鳍、鱼眼等）
+- 基于分割结果进行更精确的体积计算
+- 利用分割信息进行鱼类姿态估计
+- 支持不同鱼类品种的分割模型
+

FishMeasure/docs/ideas.md

@@ -0,0 +1,16 @@
+# Fish Weight Prediction – Ideas
+
+## Multi-modal weight prediction (image + point cloud)
+
+**Idea:** Instead of using only PointNet++ to predict weight from the 3D point cloud, use two separate models and combine their outputs:
+
+1. **Image-based weight predictor** – A model that predicts fish weight from 2D images (e.g., RGB frames from the video).
+2. **Point cloud–based weight predictor** – The existing PointNet++ model that predicts weight from 3D point clouds.
+
+Then **combine the two feature representations** (or predictions) to produce a final weight estimate. This could be done by:
+
+- Concatenating features from both encoders and feeding them into a small fusion head.
+- Averaging or otherwise combining the two predictions (e.g., weighted average).
+- Using a learned fusion module that decides how much to trust each modality.
+
+**Rationale:** 2D images and 3D point clouds provide complementary information. Images capture texture, color, and fine visual details; point clouds capture geometry and scale. Combining both may improve robustness when one modality is noisy or incomplete (e.g., poor depth, occlusion, or low-quality segmentation).