推理结果 JSON 说明

本文描述 YOLO 模块 15 个推理接口 的统一返回格式。下列接口返回值均为 PascalCase JSON 字符串指针，须 FreeStringPtr 释放：

任务	屏幕区域	图像指针	文件路径
Detect	YoloDetect	YoloDetectFromPtr	YoloDetectFromFile
Classify	YoloClassify	YoloClassifyFromPtr	YoloClassifyFromFile
Segment	YoloSegment	YoloSegmentFromPtr	YoloSegmentFromFile
Pose	YoloPose	YoloPoseFromPtr	YoloPoseFromFile
Obb	YoloObb	YoloObbFromPtr	YoloObbFromFile

推理入参（confidence、iou、topK 等）见推理输入参数说明；模型元数据与调参 JSON 见 ModelInfo与ModelConfig说明；模块总览见 YOLO 模块总览。

通用约定

项	说明
键名风格	PascalCase（如 `ModelHandle`、`RegionCount`），与 ModelInfo / ModelConfig 一致
编码	UTF-8 JSON 文本；由插件分配，调用方只读
可选字段	无数据或当前任务不适用时，对应键可能不出现（勿假定始终存在）
任务字段名	推理结果使用 `TaskType`；YoloGetModelInfo 使用 `InferenceType`（语义相同）
坐标原点	图像左上角为 `(0, 0)`，x 向右、y 向下
坐标参照	屏幕区域接口：坐标为屏幕绝对坐标；图像指针 / 文件接口：坐标相对该张输入图左上角
数值类型	坐标多为整数像素；`Score`、`TopScore`、`LatencyMs` 等为浮点数

解析顺序建议：先读 Success → 失败则读 Error 并释放；成功再按 TaskType 分支解析 Regions 及任务专有字段。

顶层字段（Envelope）

字段	类型	必有	说明
`Success`	bool	✓	`true` 表示推理流程完成且 JSON 有效；`false` 表示加载/推理/参数等错误
`Error`	string	失败时	人类可读错误信息；成功时通常不出现
`ModelHandle`	int64	成功时	本次推理使用的模型句柄
`ModelType`	string	成功时	后端：`Onnx` / `Ncnn` / `Trt`
`TaskType`	string	成功时	任务：`Detect` / `Classify` / `Segment` / `Pose` / `Obb`，应与加载时的 inferenceType 一致
`InferenceDevice`	string	成功时	实际推理设备：`CPU` 或 `GPU0`、`GPU1`…（可能与请求设备不同，见 ModelInfo 回退说明）
`LatencyMs`	number	成功时	端到端耗时（毫秒），含预处理、推理、后处理
`ClassNames`	string[]	有则输出	模型类别名表（加载时提供了 names 文件或加密包内嵌标签）
`RegionCount`	int	成功时	`Regions` 数组长度，与 `Regions.length` 一致
`Regions`	array	成功时	检测结果列表；无目标时为空数组 `[]`
`ClassFilterSkipped`	bool	条件	类别过滤条件与模型类别无交集、跳过实际推理时为 `true`
`TopClassName`	string	Classify	Top-1 类别名称，与 `Regions[0]` 一致
`TopScore`	number	Classify	Top-1 置信度，与 `Regions[0].Score` 一致

`ClassFilterSkipped`

ClassFilterSkipped：在 YoloDetect 的 classes 参数，或 YoloSetModelConfig 的 Classes / ClassesFilter 生效且过滤名与模型类别表无匹配时出现；此时 Success 仍为 true，RegionCount 为 0，Regions 为空，未执行 GPU/CPU 推理。

Region 公共字段

每个 Regions[] 元素表示一个检测目标或一条分类结果。

字段	类型	说明
`Score`	number	置信度，一般范围 0~1（Classify 为各类别概率/分数）
`ClassName`	string	类别名称；模型未加载 names 时可能为数字字符串形式的 `class_id`
`ClassId`	int	类别索引（模型提供类别表时输出，与 `ClassNames` 下标对应）

排序：Detect / Segment / Pose / Obb 通常按 Score 降序；Classify 的 Regions 按 Rank 升序（0 为 Top-1）。

几何与任务专有字段

下表「✓」表示该任务在 Region 中可能输出；「—」表示该任务 JSON 中不输出此键。

字段	Detect	Classify	Segment	Pose	Obb
`Vertices`	✓	—	✓	✓*	✓
`Center`	✓	—	✓	✓*	✓
`Angle`	—	—	—	—	✓
`Rank`	—	✓	—	—	—
`Keypoints`	—	—	—	✓	—
`MaskVertices`	—	—	✓	—	—

* Pose：仅当模型输出人体框时附带 Vertices / Center；关键点始终通过 Keypoints 给出。

`Center` 与 `Vertices`

子字段	类型	说明
`Center.x` / `Center.y`	number	目标框中心像素坐标
`Vertices`	`{x,y}[]`	四边形顶点，一般为 4 个点

Vertices 顺序（Detect 轴对齐框）：依次为左上 → 右上 → 右下 → 左下（顺时针）。示例中 (872,419) 为左上，(998,559) 为右下。

Obb 的 Vertices 为旋转四边形四个角点；Angle 为旋转角（度），与 Ultralytics OBB 后处理一致，用于描述长边方向。

`MaskVertices`（Segment）

说明
实例掩码轮廓的多边形顶点序列 `{x,y}[]`，点数 ≥ 3
与 `Vertices` 外接框配合使用：框用于快速命中，轮廓用于精确分割区域
坐标同样相对输入图（或屏幕绝对坐标）

`Keypoints`（Pose）

数组元素结构：

字段	类型	说明
`x`	number	关键点 x
`y`	number	关键点 y
`score`	number	该点置信度
`index`	int	关键点序号（与 COCO 等骨架定义一致，从 0 起）

`Rank`（Classify）

值	含义
`0`	Top-1
`1`	Top-2
…	与 API 参数 `topK` 对应，最多 `topK` 条 Region

分任务说明

Detect（目标检测）

每个 Region 含 Vertices + Center，无 MaskVertices / Keypoints。
仅 Detect 三接口 支持调用参数 classes（竖线分隔，如 dog|bus）；空字符串表示不过滤。
已加载 names：classes 写类别名；未加载 names：写 class_id 数字字符串。

Classify（图像分类）

无 Vertices / Center。
顶层 TopClassName / TopScore 与 Regions[0] 冗余，便于只读 Top-1。
每条 Region 仅有 Rank、Score、ClassName（及可选 ClassId）。
类别过滤通过 ModelConfig 或内部策略触发时，可能出现 ClassFilterSkipped。

Segment（实例分割）

Region 在 Detect 框字段基础上增加 MaskVertices 轮廓。

Pose（姿态估计）

Region 必含 Keypoints。
人体检测框存在时输出 Vertices / Center，否则仅关键点数组。
ClassName 多为 person 或模型定义的人体类。

Obb（旋转框检测）

Region 含 Vertices（旋转四边形）+ Center + Angle（度）。
适用于遥感、文本行等任意方向目标；Vertices 顺序为四边形绕序顶点。

完整示例

Detect（目标检测）

{
  "Success": true,
  "ModelHandle": 1000,
  "ModelType": "Ncnn",
  "TaskType": "Detect",
  "InferenceDevice": "CPU",
  "LatencyMs": 12.3,
  "RegionCount": 1,
  "Regions": [
    {
      "Score": 0.85,
      "ClassName": "monster",
      "ClassId": 0,
      "Center": { "x": 935, "y": 489 },
      "Vertices": [
        { "x": 872, "y": 419 },
        { "x": 998, "y": 419 },
        { "x": 998, "y": 559 },
        { "x": 872, "y": 559 }
      ]
    }
  ],
}

Classify（图像分类，Top-3）

{
  "Success": true,
  "ModelHandle": 1001,
  "ModelType": "Onnx",
  "TaskType": "Classify",
  "InferenceDevice": "GPU0",
  "LatencyMs": 3.1,
  "RegionCount": 3,
  "TopClassName": "tench",
  "TopScore": 0.92,
  "Regions": [
    { "Rank": 0, "Score": 0.92, "ClassName": "tench", "ClassId": 0 },
    { "Rank": 1, "Score": 0.05, "ClassName": "goldfish", "ClassId": 1 },
    { "Rank": 2, "Score": 0.02, "ClassName": "shark", "ClassId": 2 }
  ]
}

Segment（实例分割）

{
  "Success": true,
  "TaskType": "Segment",
  "RegionCount": 1,
  "Regions": [
    {
      "Score": 0.91,
      "ClassName": "person",
      "ClassId": 0,
      "Center": { "x": 320, "y": 240 },
      "Vertices": [
        { "x": 280, "y": 120 },
        { "x": 360, "y": 120 },
        { "x": 360, "y": 360 },
        { "x": 280, "y": 360 }
      ],
      "MaskVertices": [
        { "x": 290, "y": 130 },
        { "x": 350, "y": 125 },
        { "x": 355, "y": 350 },
        { "x": 285, "y": 340 }
      ]
    }
  ],
}

Pose（姿态估计）

{
  "Success": true,
  "TaskType": "Pose",
  "RegionCount": 1,
  "Regions": [
    {
      "Score": 0.88,
      "ClassName": "person",
      "ClassId": 0,
      "Center": { "x": 400, "y": 300 },
      "Vertices": [
        { "x": 350, "y": 150 },
        { "x": 450, "y": 150 },
        { "x": 450, "y": 450 },
        { "x": 350, "y": 450 }
      ],
      "Keypoints": [
        { "x": 400, "y": 160, "score": 0.95, "index": 0 },
        { "x": 380, "y": 200, "score": 0.90, "index": 1 }
      ]
    }
  ],
}

Obb（旋转框）

{
  "Success": true,
  "TaskType": "Obb",
  "RegionCount": 1,
  "Regions": [
    {
      "Score": 0.79,
      "ClassName": "ship",
      "ClassId": 2,
      "Angle": 32.5,
      "Center": { "x": 512, "y": 384 },
      "Vertices": [
        { "x": 480, "y": 360 },
        { "x": 550, "y": 370 },
        { "x": 540, "y": 410 },
        { "x": 470, "y": 400 }
      ]
    }
  ],
}

失败与类别过滤跳过

推理失败（如句柄无效、任务类型不匹配）：

{
  "Success": false,
  "Error": "Model handle not found"
}

类别过滤无匹配（跳过推理）：

{
  "Success": true,
  "TaskType": "Detect",
  "ClassFilterSkipped": true,
  "RegionCount": 0,
  "Regions": []
}

调用与解析示例（C++）

long jsonPtr = YoloDetectFromPtr(ola, modelHandle, imagePtr, "monster|boss", 0.5, 0.45, 100);
// 将 jsonPtr 转为字符串后解析；伪代码：
// if (!Success) { 记录 Error; FreeStringPtr(ola, jsonPtr); return; }
// if (ClassFilterSkipped) { /* 无目标，非错误 */ }
// for (region : Regions) { 使用 region.Center / Vertices 点击或画框 }
FreeStringPtr(ola, jsonPtr);

屏幕区域转局部坐标：若全屏检测后只需在子窗口内操作，将 Vertices / Center 减去截屏左上角 (x1, y1) 即可得到相对子区域坐标。

与其他 JSON 的区别

对比	推理结果 JSON	ModelInfo / ModelConfig
接口	`YoloDetect*` 等 15 个推理 API	`YoloGetModelInfo`、`YoloGetModelConfig` 等
任务字段	`TaskType`	`InferenceType`
内容	单次推理的目标列表与耗时	模型路径、输入尺寸、阈值配置等
调试字段	不返回内部 verbose（含 `raw`、`timing` 等），仅 DEBUG 日志可见

常见问题

现象	可能原因
`Success: false`	句柄无效、未开通 Yolos 权限、模型任务与 API 不一致（如对 Classify 模型调 `YoloDetect`）
`Regions` 为空且无 `ClassFilterSkipped`	置信度阈值过高、画面中确实无目标、或 NMS 后无保留框
有 `ClassId` 无 `ClassName` 中文	未加载 names 文件，仅有数字 id
坐标与鼠标位置偏差	屏幕接口用了图像相对坐标未加偏移，或 DPI/多显示器坐标系不一致
`TaskType` 与预期不符	加载模型时 `inferenceType` 与调用 API 不匹配

可视化调试可在业务侧根据 Regions 自行绘制框、关键点与掩码轮廓；亦可结合 LoadImage 与图像处理模块做落盘对比。