# ai_shoe_det - 鞋子检测节点

专门针对鞋子检测优化的节点，支持滑动窗口提高小目标检测率。

## 特性

- **滑动窗口支持**：可配置多窗口覆盖全图，提高小鞋子检测精度
- **动态 ROI 支持**：可直接读取上一阶段的人框，只在脚部区域跑鞋模型
- **单类优化**：专门针对 shoe 单类检测优化
- **自动 NMS**：多窗口结果自动合并去重
- **轻量快速**：基于 RK3588 NPU 加速
- **低频运行**：支持 `infer_fps` / `infer_interval_ms` 控制推理频次

## 配置参数

```json
{
  "id": "shoe_det",
  "type": "ai_shoe_det",
  "model_path": "./models/shoe_detector.rknn",
  "model_w": 640,
  "model_h": 640,
  "infer_fps": 5,
  "conf": 0.25,
  "nms": 0.45,
  "windows": [
    {"x": 0, "y": 0, "w": 960, "h": 1080},
    {"x": 960, "y": 0, "w": 960, "h": 1080}
  ]
}
```

### 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `model_path` | string | - | RKNN 模型路径 |
| `model_w` | int | 640 | 模型输入宽度 |
| `model_h` | int | 640 | 模型输入高度 |
| `infer_fps` | float | 0 | 推理帧率限制，0 表示每帧都跑 |
| `infer_interval_ms` | int | 0 | 推理间隔，优先级高于 `infer_fps` |
| `conf` | float | 0.25 | 置信度阈值 |
| `nms` | float | 0.45 | NMS IoU 阈值 |
| `append_detections` | bool | false | 是否保留前级检测结果并追加鞋框 |
| `windows` | array | - | 滑动窗口配置，不配置则使用全图单窗口 |
| `dynamic_roi` | object | - | 动态脚部 ROI 配置，启用后会根据 person 框生成检测窗口 |

### 窗口配置

- **单窗口（全图）**：不配置 `windows` 或配置 `[{"x":0,"y":0,"w":0,"h":0}]`
- **双窗口（推荐）**：左右各 960x1080
  ```json
  "windows": [
    {"x": 0, "y": 0, "w": 960, "h": 1080},
    {"x": 960, "y": 0, "w": 960, "h": 1080}
  ]
  ```

## 动态 ROI 配置

适合两阶段检测链路：先用 `ai_yolo` 检 `person`，再由 `ai_shoe_det` 读取人框生成脚部 ROI。

```json
{
  "id": "shoe_det",
  "type": "ai_shoe_det",
  "model_path": "./models/shoe_detector_openimages_ppe_v1.rknn",
  "model_w": 640,
  "model_h": 640,
  "infer_fps": 3,
  "conf": 0.35,
  "nms": 0.45,
  "append_detections": true,
  "dynamic_roi": {
    "enable": true,
    "person_class_id": 0,
    "shoe_class_id": 0,
    "max_rois": 6,
    "min_person_height": 80,
    "x_offset": -0.15,
    "y_offset": 0.72,
    "width_scale": 1.30,
    "height_scale": 0.38
  }
}
```

### `dynamic_roi` 字段说明

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `enable` | false | 是否启用基于人框的动态脚部 ROI |
| `person_class_id` | 0 | 前级 person 类别 ID |
| `shoe_class_id` | 0 | 追加到结果中的鞋类别 ID |
| `max_rois` | 8 | 每帧最多处理多少个人 |
| `min_person_height` | 0 | 忽略过小的人框，减少无效 ROI |
| `max_box_area_ratio` | 0.0 | 鞋框相对脚部 ROI 的最大面积占比，超过则过滤 |
| `x_offset` | -0.15 | ROI 左上角相对人框左上角的横向偏移系数 |
| `y_offset` | 0.72 | ROI 左上角相对人框左上角的纵向偏移系数 |
| `width_scale` | 1.30 | ROI 宽度相对人框宽度的放大系数 |
| `height_scale` | 0.38 | ROI 高度相对人框高度的放大系数 |

## Pipeline 示例

```json
{
  "nodes": [
    {"id": "in", "type": "input_rtsp", "url": "rtsp://..."},
    {"id": "pre", "type": "preprocess", "dst_w": 1920, "dst_h": 1080, "dst_format": "rgb"},
    {
      "id": "shoe_det",
      "type": "ai_shoe_det",
      "model_path": "./models/shoe_detector_openimages_ppe_v1.rknn",
      "model_w": 640,
      "model_h": 640,
      "conf": 0.25,
      "windows": [
        {"x": 0, "y": 0, "w": 960, "h": 1080},
        {"x": 960, "y": 0, "w": 960, "h": 1080}
      ]
    },
    {"id": "osd", "type": "osd"},
    {"id": "pub", "type": "publish"}
  ],
  "edges": [
    ["in", "pre"],
    ["pre", "shoe_det"],
    ["shoe_det", "osd"],
    ["osd", "pub"]
  ]
}
```

## 两阶段示例

```json
{
  "nodes": [
    {"id": "pre", "type": "preprocess", "dst_w": 1920, "dst_h": 1080, "dst_format": "rgb"},
    {
      "id": "person",
      "type": "ai_yolo",
      "model_path": "./models/yolov8n-640.rknn",
      "model_version": "v8",
      "model_w": 640,
      "model_h": 640,
      "num_classes": 80,
      "class_filter": [0],
      "infer_fps": 5
    },
    {
      "id": "shoe_det",
      "type": "ai_shoe_det",
      "model_path": "./models/shoe_detector_openimages_ppe_v1.rknn",
      "model_w": 640,
      "model_h": 640,
      "infer_fps": 3,
      "append_detections": true,
      "dynamic_roi": {
        "enable": true,
        "person_class_id": 0,
        "shoe_class_id": 1,
        "max_rois": 6,
        "x_offset": -0.15,
        "y_offset": 0.72,
        "width_scale": 1.30,
        "height_scale": 0.38
      }
    }
  ]
}
```

## 编译

```bash
cd build
cmake ..
make ai_shoe_det -j4
```

## 注意事项

1. 模型必须是单类（shoe）YOLOv8 格式
2. 多窗口会增加 NPU 负载（2窗口 = 2倍推理时间）
3. 动态 ROI 模式依赖前级 `frame->det` 中已经存在 person 检测结果
4. 两阶段模式建议开启 `append_detections=true`，否则会覆盖前级的人框
5. 窗口之间有重叠时，NMS 会自动去重