# Recalculate Everything:

CLEAR_SQLITE_DATABASE=1 CLEAR_MEASURE_OUTPUT=1 CLEAR_ACTION_OUTPUT=1 CLEAR_MEDIA=1 CLEAR_STREAM_TMP=1 LD_PRELOAD=/lib/aarch64-linux-gnu/libGLdispatch.so.0  bash scripts/start_fresh.sh



## 配置（环境变量）

| 变量 | 说明 | 默认 |
|------|------|------|
| `PUBLIC_BASE_URL` | 返回 JSON 中 `video_left` / `video_right` 的前缀（勿带末尾 `/`） | `http://127.0.0.1:8000` |
| `INGEST_API_KEY` | 非空时，`/api/v1/ingest/*` 需请求头 `X-API-Key` | 空（不校验） |
| `STREAM_TMP_DIR` | 分块上传临时目录 | `<repo>/fish_api/.data/ingest` |
| `MEDIA_ROOT` | 对外托管每次测量生成的 `*_left.mp4` / `*_right.mp4` | `<repo>/fish_api/.data/media` |
| `FISH_MEASURE_ROOT` | `FishMeasure` 根目录 | 自动相对仓库 |
| `FISH_ACTION_ROOT` | `FishAction` 根目录 | 自动相对仓库 |
| `MEASURE_OUTPUT_ROOT` | 传给 `--save-output` 的目录 | `<repo>/fish_api/.data/measure_output` |
| `YOLO_MODEL` / `WEIGHT_CHECKPOINT` / `ACTION_CHECKPOINT` | 模型路径 | 与仓库内脚本默认一致 |
| `SAM_DEVICE` | `cuda` 或 `cpu` | `cuda` |
| `MEASURE_FINAL_AGGREGATE_MODE` | 齐套后对各段 former 体重/体长聚合：`median` / `mean` / `trimmed_mean` | `median` |
可在 `fish_api/.env` 中填写上述变量（`pydantic-settings` 会读取）。

## 安装与启动

```bash
cd fish_api
python3 -m pip install -e .   # 安装 pyproject 依赖（无 venv 时可用 --user 或系统 site-packages）
./scripts/start_fresh.sh   # 默认仅重置 client_id 投递进度，保留 SQLite 历史与快照
# CLEAR_SQLITE_DATABASE=1 bash start_fresh.sh  # 需要时才彻底清 SQLite
# python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000  # 需自行 prestart
```

## SVO 输入与 ``measure_watch``（两种来源，同一套目录逻辑）

后台 **[``measure_watch``](app/services/measure_watch.py)** 只认 **`MEASURE_WATCH_DIR`** 下一层的 **`fish{N}/`** 子目录及其中的 **``.svo2``**（见 ``iter_svo2_folders``）。与入口无关：

| 方式 | 说明 |
|------|------|
| **ZED 分段录制** | 每次会话分配 ``fish_id``：取库表（``fish_id`` 与 ``output_dir`` 路径）、父目录下 ``fish``+数字 子目录名、以及 ``fish{N}/`` 下已有 ``.svo2`` 路径 四者编号的最大值再加 1（磁盘有数据而库未记时也不冲突）；文件写入 ``{MEASURE_WATCH_DIR}/fish{N}/``（若未配置 ``MEASURE_WATCH_DIR`` 则 ``{STREAM_TMP_DIR}/zed_svo2/fish{N}/``，此时**不会**启用 ``measure_watch``，除非把 ``MEASURE_WATCH_DIR`` 指到 ``…/ingest/zed_svo2``） |
| **手工拷贝** | 将 ``.svo2`` 放入 ``MEASURE_WATCH_DIR/fish{N}/``（自建 ``fish{N}`` 即可） |

**逐段测量与齐套 final**：对每个 ``.svo2`` 稳定后轮询跑 FishMeasure，写入 SQLite；服务端可在 ``calculation_log`` 中区分 segment/final。``GET /api/v1/biomass/real/camera/`` 的 ``data.result[]`` **仅含** ``id``、``type``、``length``、``weight``、``date``（与历史客户端约定一致）；按投递顺序先可能收到多段再收到聚合行。``video_left`` / ``video_right`` 规则不变。

**ingest** 的 ``/api/v1/ingest/svo/...`` 为分块上传流程，落盘与上述 ``fish{N}`` 路径独立；``fish{N}`` 目录的测量以 ``measure_watch`` 为准。

**ZED 相机**：**fish_api 启动/停止不会自动开关相机录制**；录制由独立服务或仓库根 ``start_recording.sh`` / ``zed_record_cli`` 等自行管理，写入 ``MEASURE_WATCH_DIR/fish{N}/`` 后由 ``measure_watch`` 消费。需要时也可调 ``/api/v1/zed/recording/start|stop``（不经过 uvicorn lifespan）。

## ZED 分段录制 CLI

每次 **开始/停止** 录制会在 SQLite 表 ``zed_recording_sessions`` 中记录一行（``fish_id``、``started_at`` / ``stopped_at``、``output_dir``；分配规则见上表）。

在 `fish_api` 目录下执行（与 `app` 包路径一致；依赖已 `pip install -e .`）：

```bash
# 本机直连相机：前台录制，终端不关，Ctrl+C 结束（终端会打印分配的 fish_id）
python3 -m app.zed_record_cli start [--segment-sec SEC]

# 仅向已运行的 fish_api 发请求（不阻塞）
python3 -m app.zed_record_cli start --remote [--segment-sec SEC]

# 停止 / 查询状态（HTTP，需 uvicorn 已监听；基址见 FISH_API_BASE_URL 或 PUBLIC_BASE_URL）
python3 -m app.zed_record_cli stop
python3 -m app.zed_record_cli status
```

若已通过 `pip install -e .` 安装了控制台脚本，也可使用 `fish-zed-record`（与上表等价）。

也可使用仓库根目录下的封装脚本：

```bash
# 在 FishServer 仓库根目录执行
./start_recording.sh              # 本地前台；可选 --remote / --segment-sec
./stop_recording.sh               # HTTP 停止（需 API 已启动）
```

## Weight Rule (Current)

最终体重 `pred_weight_g` 由以下规则链决定（按优先级从高到低）：

1. **440g 全池均值保护**（规则 B）：若 `avg_g_filtered`（所有 candidates 均值）> `--mean-pool-fallback-max-if-over-g`（默认 440g），则 `pred_weight_g = max_predicted_weight_g_after_filter`，`pred_weight_rule = "max_after_filter_high_mean_pool_over_g"`。
2. **400g mean-all fallback**（规则 A，仅 `--average-all-after-filter` 开启时）：若全池 mean > `--average-all-fallback-max-if-mean-over-g`（默认 400g），则 `pred_weight_g = max_predicted_weight_g_after_filter`，`pred_weight_rule = "max_after_filter_high_mean_all"`。
3. **`--average-all-after-filter`**（默认关）：全部 candidates 均值作为最终值，`pred_weight_rule = "mean_all_filtered"`。
4. **Top-K 聚合**（默认路径）：按 `--top-by-length`（默认开）选 top-K 帧，对选中帧的预测重量取**算术平均**（与日志中 `top{k}_avg` 一致），`pred_weight_rule = "top_k_aggregate"`。

DGCNN 明细中同时输出 `mean_all_pred_g_after_filters`、`avg_topk_mean_pred_g` 等供对比参考。

## Debug：单条鱼测量（与 fish_api 同逻辑）

不启动 uvicorn、**不写 SQLite**、**不发布** `MEDIA_ROOT`（与 `run_full_measure_batch` 相比仅少快照与媒体发布；FishMeasure 子进程与 `measure_output/fish{N}` 与线上一致）。

调用 [`app/services/measure.py`](app/services/measure.py) 中的 `run_measure_batch_subprocess`，配置与 `fish_api/.env` 相同（`get_settings()`）。

**必须在 `fish_api` 下执行 `python -m app...`，或从仓库根用下面脚本**；若在仓库根直接运行 `python -m app.measure_debug_cli`，会因找不到 `app` 包报错（`ModuleNotFoundError: No module named 'app'`）。

```bash
# 方式 A：仓库根（推荐）
bash scripts/measure_debug.sh --fish-id 14

# 方式 B：先进入 fish_api
cd fish_api
python3 -m pip install -e .   # 若尚未安装依赖
# 默认：MEASURE_WATCH_DIR/fish{N}/ 下所有 .svo2 → 输出到 MEASURE_OUTPUT_ROOT/fish{N}（默认 fish_api/.data/measure_output/fish{N}）
python3 -m app.measure_debug_cli --fish-id 1

# 或等价入口（须在 fish_api 目录，且已 pip install -e .）
fish-measure-debug --fish-id 1

# 指定 SVO 目录或输出目录（在 fish_api 目录下）
python3 -m app.measure_debug_cli --batch-folder /path/to/fish1 --fish-id 1 --output-root /path/to/out
```

结束后会在终端打印 `weight_prediction.json` 中的 `pred_weight_g`、`pred_weight_rule` 等摘要。

## 演进建议

- RTSP：用 `ffmpeg` 切段写入 MP4 后调用现有 `finalize` 逻辑
- 任务状态：`finalize` 返回 `job_id`，增加 `GET /jobs/{id}` 查询进度