GrabBag/AppModel/lib/Arm/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。

#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）：

$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 根目录运行）：

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 以以下四行格式为准（像素整数）：

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

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