# `-R` 反向 workspace 过滤设计记录

## 背景

当前推理程序通过 `-w/--workspace` 配置一个多边形工作区域。检测结果在进入上报候选前，会用目标框中心点调用 `is_point_in_workspace(left, top, right, bottom)` 判断是否位于该区域内：

- 在 workspace 内：继续进入 `current_objects`，后续按类别编码合并并上报。
- 在 workspace 外：记录 `filtered_workspace`，不参与上报。
- 未传 `-w`：`init_polygon(NULL, 0)`，默认全画面有效。

本次需求是新增 `-R` 参数，让 `-w` 画出来的区域变成排除区域：开启 `-R` 后，区域内的识别结果不上报，只上报区域外的内容。

## 准备实现方式

1. 在命令行参数解析里新增无参数开关：
   - 短参数：`-R`
   - 长参数建议：`--reverse-workspace` 或沿用旧目录线索里的 `--reverse-detect`
   - 默认关闭，保持现有行为完全不变。

2. 增加一个全局配置变量，例如：
   - `bool ReverseWorkspace = false;`
   - 放在 `vertix.cpp/vertix.h` 或更靠近推理过滤逻辑的公共头文件中，供 `main.cpp` 设置、`rknn.cpp` 读取。

3. 不改 YOLO 后处理、NMS、阈值、类别编码和上传 JSON，只改 workspace 过滤判定。

4. 在 `rknn.cpp::print_object_detect_result` 中，把直接判断：

   ```cpp
   if (!is_point_in_workspace(left, top, right, bottom)) {
       ...
       continue;
   }
   ```

   调整成先计算原始位置关系，再根据 `-R` 反转：

   ```cpp
   bool in_workspace = is_point_in_workspace(left, top, right, bottom);
   bool pass_workspace = ReverseWorkspace ? !in_workspace : in_workspace;
   if (!pass_workspace) {
       ...
       continue;
   }
   ```

   这样 `-R` 只改变“是否允许上报”，不改变多边形算法本身。

5. 低置信度日志里的 workspace 判断也需要同步使用同一个通过规则。否则开启 `-R` 后，低置信度日志仍会按原来的“区域内”记录 `weak_present`，和上报语义不一致。

6. 日志名称建议保留现有兼容字段，同时增加模式信息：
   - 正常模式下继续用 `strong_present`、`weak_present`、`filtered_workspace`。
   - `-R` 模式下被过滤的目标本质是“命中排除区域”，建议日志里增加 `workspace_mode=reverse` 或新增 `filtered_reverse_workspace`，便于现场排查。
   - 命令行输出的 `in result` / `not in result` 也建议区分“在多边形内”和“通过过滤后可上报”，避免 `-R` 模式下读日志误判。

## 边界约定

- `-R` 单独使用、未传 `-w` 时，当前默认 workspace 是全画面。如果直接反转，会变成全画面都被排除，导致无目标上报。建议实现时明确处理：
  - 推荐方案：`-R` 必须配合 `-w` 使用；如果未传 `-w`，启动时报错并退出。
  - 备选方案：未传 `-w` 时忽略 `-R` 并打印警告。这个更宽松，但容易让现场误以为反向过滤已生效。

- 多边形仍使用目标框中心点判断，不改成框与区域相交判断。这样和现有 `-w` 行为保持一致。

- `-P/--time-period`、阈值 `-r`、心跳、G1000 截图通知、同 `class_idx` 合并逻辑都不需要变化。

## 需要改动的文件

- `main.cpp`
  - `long_options` 增加 `-R` 对应长参数。
  - `getopt_long_only` 的短参数串加入 `R`。
  - `case 'R'` 中设置全局反向开关。
  - `print_usage` 的帮助信息补充 `-R` 说明。

- `vertix.h` / `vertix.cpp` 或其他公共配置位置
  - 声明和定义反向 workspace 开关。
  - 可选：封装一个 `is_box_allowed_by_workspace(...)`，把反转逻辑集中起来，避免 `rknn.cpp` 多处重复判断。

- `rknn.cpp`
  - 上报候选过滤处使用统一的 `pass_workspace`。
  - 低置信度 `weak_present` / `filtered_low_conf` 日志处同步使用统一规则。
  - 日志追加 `workspace_mode=normal|reverse` 或新增反向过滤事件名。

- `README.md` 或运行说明文档
  - 增加 `-R` 用法和示例。

## 验证计划

1. 编译验证：
   - 按 `docs/cross_compile_wsl_linaro.md` 的 Linaro 路线构建。
   - 确认 aarch64 产物正常生成，且不引入高版本 `glibc/libstdc++` 依赖。

2. 行为验证：
   - 不带 `-R`：`-w` 内目标上报，外部目标过滤，行为和当前版本一致。
   - 带 `-R -w ...`：`-w` 内目标过滤，外部目标上报。
   - 带 `-R` 但不带 `-w`：按最终选定边界策略报错或警告。

3. 日志验证：
   - 反向模式下能看出过滤原因是命中排除区域。
   - `upload_positive` 和 `upload_positive_payload` 只出现于通过反向过滤后的区域外目标。

## 历史线索

`updata/main.cpp` 里曾出现过 `--reverse-detect` 和 `ReverseDetectBox = 1`，但当前主线 `main.cpp/rknn.cpp/vertix.*` 没有完整接入该变量。后续实现可以参考命名，但不要直接认为旧目录已经完成当前需求。

## 实现状态

已按本文方案实现：

- `main.cpp`：新增 `-R/--reverse-workspace`，并要求必须配合 `-w/--workspace` 使用。
- `vertix.cpp` / `vertix.h`：新增 `ReverseWorkspace` 开关和 workspace 模式说明函数。
- `rknn.cpp`：强置信上报候选和低置信日志都按 `ReverseWorkspace ? !in_workspace : in_workspace` 判定。
- `README.md`：补充 `-R` 参数、示例和日志说明。

构建验证已通过：

```text
wsl -d Ubuntu bash -lc "cd /mnt/c/Users/Smos.DESKTOP-6MT98U8/Desktop/yolov5-inference/build-aarch64 && cmake /mnt/c/Users/Smos.DESKTOP-6MT98U8/Desktop/yolov5-inference -DCMAKE_TOOLCHAIN_FILE=/mnt/c/Users/Smos.DESKTOP-6MT98U8/Desktop/yolov5-inference/toolchain-aarch64.cmake && make -j16 && file yolov5"
```

输出产物为 `ELF 64-bit LSB executable, ARM aarch64`。构建过程中出现 `Clock skew detected` 提示，属于 Windows/WSL 时间戳差异提示，不是本次代码编译错误。