GrabBag/AppModel/lib/Windows/docs/MODEL_CONFIG.md

# Model configuration

The YAML file next to the RKNN model is part of the deployment contract.

- `task` selects the task backend.
- `model` is relative to the YAML directory.
- `input` records width, height, layout, format and normalization.
- `postprocess` records adapter and thresholds. For Seg models,
  `class_agnostic_nms: true` suppresses highly overlapping lower-score boxes
  even when their predicted class IDs differ; `false` suppresses only within
  the same class.
- Imported source contracts may use `labels_file`. Studio resolves it during
  import and writes one canonical inline `labels` list into the delivery YAML.

Do not replace files inside an existing delivery manually. Import a new model
version into the same business project and regenerate both platform archives;
the fixed paths remain unchanged and `manifest.json` records the new hashes.


## ROI 使用说明：WHLT 与只传 LT

公共接口接收完整原图和最终 ROI。坐标以原图左上角为 (0,0)，向右为 X，向下为 Y，单位为像素。
结构体字段顺序仍为 `struct_size, version, x, y, width, height, reserved`；不要按 WHLT 顺序直接聚合初始化结构体。
以下辅助函数只存在于 C/C++ 头文件，不新增 DLL/SO 导出，ABI 保持 5。

```c
#include "yolo_runtime.h"

/* 方式一：完整 W,H,L,T（宽、高、左、上）。 */
yolo_roi_v1_t roi = yolo_roi_from_whlt(771, 609, 217, 738);
/* 等价于 x=217, y=738, width=771, height=609。 */

/* 方式二：先初始化默认 W=800,H=736,L=0,T=0，再只设置 L、T。 */
yolo_roi_v1_t roi_lt = yolo_roi_default();
roi_lt.x = 217;  /* L */
roi_lt.y = 738;  /* T；宽高仍为 800×736。 */

/* runtime、full_image、options、error 已按公开接口正确初始化。 */
yolo_result_set_t* results = NULL;
yolo_status_t status = yolo_runtime_infer_image_roi(
    runtime, &full_image, &roi_lt, &options, &results, &error);
if (status == YOLO_STATUS_OK) {
    /* 使用 yolo_result_set_get_* 读取结果。 */
    yolo_result_set_release(results);
}
```

- `YOLO_ROI_DEFAULT_WIDTH=800`、`YOLO_ROI_DEFAULT_HEIGHT=736` 仅用于显式默认初始化，可以自行覆盖。
- 结构体清零后仅填写 L/T 无效：宽高为 0 时接口报错，不会自动补默认值。
- ROI 区间为 `[L,L+W)`、`[T,T+H)`。右、下边界不包含；若已有 x1,y1,x2,y2，则 W=x2-x1，H=y2-y1。
- 默认尺寸加 L=217,T=738 要求原图至少 1017×1474；完整 WHLT 示例要求至少 988×1347。
- 辅助函数只负责构造，不检查范围。推理接口拒绝非正宽高、负坐标和越界，不自动裁边。
- `roi=NULL` 表示全图推理，不会启用 800×736。
- 检测框、OBB、分割几何、掩膜原点、关键点使用原图坐标；掩膜像素仍局部存储，释放结果前有效。
  分类结果描述裁剪区域，无位置坐标。
- `performance.total_ms` 包含内部裁剪、预处理、推理、后处理和坐标映射；相机采集及业务文件读写在接口外。

默认 ROI 的初始化、L/T 赋值与 WHLT 构造直接位于 `examples/c/main.c` 和 `examples/cpp/main.cpp`，并附中文注释。
公共示例头文件只解析命令行数值；可以直接查看 main 文件中的 ROI 代码进行业务集成。

### 运行 C/C++ 示例

两个示例均支持以下参数（需先提供 `--config`、`--image`、`--json`）：

| 参数 | 行为 |
|---|---|
| `--roi-lt 217 738` | 默认 W=800,H=736，只设置 L=217,T=738 |
| `--roi-whlt 771 609 217 738` | 按 W,H,L,T 指定完整 ROI |
| 不传 ROI 参数 | 读取模型目录的 roi_info.txt；文件不存在时全图推理 |

命令行 ROI 明确覆盖模型 TXT，不与其字段合并；两种参数不能同时使用或重复。
参数缺失、非整数、整数溢出、非正尺寸或越界会返回非零退出码。
TXT 保留既有严格字段/原图尺寸校验；TXT 不支持只写 L/T 来隐式补默认值。
默认宽高是 ROI 裁剪尺寸，与模型 YAML 中的网络输入宽高不同。

Windows PowerShell（在解压后的 SDK 根目录运行，按实际模型槽替换 primary）：

```powershell
$env:PATH = (Join-Path $PWD 'lib') + ';' + $env:PATH
.\examples\bin\yolo_c_example.exe --config models/primary/model.yaml --image examples/assets/sample.bmp --json result-lt.json --roi-lt 217 738
.\examples\bin\yolo_cpp_example.exe --config models/primary/model.yaml --image examples/assets/sample.bmp --json result-whlt.json --roi-whlt 771 609 217 738
```

RK3588 Linux（在解压后的 SDK 根目录运行）：

```bash
export LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
./examples/bin/yolo_c_example --config models/primary/model.yaml --image examples/assets/sample.bmp --json result-lt.json --roi-lt 217 738
./examples/bin/yolo_cpp_example --config models/primary/model.yaml --image examples/assets/sample.bmp --json result-whlt.json --roi-whlt 771 609 217 738
```

命令中的数值仅演示参数顺序；按实际图像选择 ROI，避免越界。
示例读取 BMP 来演示集成；业务程序可以直接传相机内存，无需保存图片。


### 模型 ROI 文件格式

模型同目录的 `roi_info.txt` 以以下四行格式为准（像素整数）：

```text
w: 800
h: 736
l: 180
t: 640
```

`w/h` 为 ROI 宽高，`l/t` 为原图中的左上角坐标。无需提供原图尺寸；推理时按实际原图检查边界，不缩放、不裁剪越界 ROI。四个字段必须齐全且唯一，不能混用旧字段。缺少文件时使用整图。旧版 `source_width=...` 等格式继续兼容，并保留原图尺寸一致性校验。Studio 的设备测试先将输入保存为整幅 PNG，再读取其实际尺寸传给设备 Runtime。既有 SDK 压缩包需重新生成才包含更新后的 TXT 读取逻辑。