# yolo.h

YOLO decode and postprocess on the SP500 DSP.

A YOLO network does not return boxes. It returns a grid of raw numbers, one vector per candidate location - 8400 candidates for a 640x640 anchor-free head, 25200 for an anchor-based one. Turning those numbers into a list of detections is the postprocess: decode the coordinates, drop candidates below the confidence threshold, and remove duplicates. Each call below does all of that in a single DSP round trip.

**Head families**

YOLO generations encode boxes and remove duplicates differently, so pick the family your network belongs to. [sp500\_yolo\_head\_for\_model()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-head-for-model>) maps a model name onto one; the table is:

| Family | Box encoding | Duplicates | Tasks | Models |
| --- | --- | --- | --- | --- |
| ::SP500\_YOLO\_HEAD\_ANCHORLESS | DFL, 4 x 16 logits | per-class NMS | detect, segment, pose | v3u, v5u, v8, v9, GELAN, 11, 12 |
| ::SP500\_YOLO\_HEAD\_ANCHOR | anchor offsets + objectness | per-class NMS | detect, segment | v3, v5, v7 |
| ::SP500\_YOLO\_HEAD\_NMSFREE | DFL, 4 x 16 logits | dual top-k | detect | v10 |
| ::SP500\_YOLO\_HEAD\_DFLFREE | 4 direct distances | dual top-k | detect, segment, pose | 26 |

The `u` suffix matters: YOLOv3u and YOLOv5u are retrained with an anchor-free DFL head and belong to ::SP500\_YOLO\_HEAD\_ANCHORLESS, not to the anchor family that plain YOLOv3 and YOLOv5 use.

**Two entry points per family**

- [sp500\_yolo\_decode()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-decode>) and [sp500\_yolo\_decode\_anchor()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-decode-anchor>) take the raw head tensors and do everything.
- [sp500\_yolo\_postprocess()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-postprocess>) starts from an already-decoded anchor table, for networks that decode boxes inside the graph.

**Results**

`output->records` receives `result->count` fixed-size records. Cast the buffer to [sp500\_yolo\_detection](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_detection/index.md>), [sp500\_yolo\_segmentation](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_segmentation/index.md>) or [sp500\_yolo\_pose](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_pose/index.md>) according to the task; [sp500\_yolo\_records\_bytes()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-records-bytes>) sizes it. Box coordinates are pixels in the NETWORK INPUT frame - if you letterboxed the source, map them back with the scale and padding [sp500\_letterbox()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/letterbox-h/#sp500-letterbox>) returned.

**Example**

```cpp
sp500_dsp_open(0);

sp500_yolo_params p;
sp500_yolo_params_init(&p);
p.num_classes = 80;
p.max_detections = 300;

sp500_yolo_detection dets[300];
sp500_yolo_output out;
sp500_yolo_output_init(&out);
out.records = sp500_buffer_wrap(dets, sizeof dets);

sp500_yolo_raw raw;
sp500_yolo_raw_init(&raw);
raw.box[0] = sp500_buffer_wrap(box_p3, box_p3_bytes);
raw.cls[0] = sp500_buffer_wrap(cls_p3, cls_p3_bytes);
// ... levels 1 and 2 ...

sp500_yolo_result r;
if(sp500_yolo_decode(SP500_YOLO_HEAD_ANCHORLESS, SP500_YOLO_TASK_DETECT,
                     &raw, &p, &out, &r) == SP500_OK)
{
    for(uint32_t i = 0; i < r.count; ++i) { use(&dets[i]); }
}
```

## Data structures

| Name | Description |
| --- | --- |
| [`sp500_yolo_detection`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_detection/index.md>) | One detection. 6 floats; the layout of a [SP500\_YOLO\_TASK\_DETECT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>) record. |
| [`sp500_yolo_keypoint`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_keypoint/index.md>) | One keypoint of a pose record. |
| [`sp500_yolo_output`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_output/index.md>) | Where the results go. |
| [`sp500_yolo_params`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_params/index.md>) | Model shape and thresholds. |
| [`sp500_yolo_pose`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_pose/index.md>) | One pose result. 57 floats; the layout of a [SP500\_YOLO\_TASK\_POSE](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>) record. |
| [`sp500_yolo_raw`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_raw/index.md>) | Raw head tensors as separate planes, one set per feature level. |
| [`sp500_yolo_raw_anchor`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_raw_anchor/index.md>) | Raw head tensors as one combined tensor per level. SP500\_YOLO\_HEAD\_ANCHOR only. |
| [`sp500_yolo_result`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_result/index.md>) | What a YOLO call produced. |
| [`sp500_yolo_segmentation`](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_segmentation/index.md>) | One segmentation result. 11 floats; the layout of a [SP500\_YOLO\_TASK\_SEGMENT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>) record. |

## Macros

### SP500\_YOLO\_LEVELS

```cpp
#define SP500_YOLO_LEVELS 3
```

Feature levels a YOLO head produces: strides 8, 16 and 32.

### SP500\_YOLO\_POSE\_KEYPOINTS

```cpp
#define SP500_YOLO_POSE_KEYPOINTS 17
```

Keypoints in a pose record; the fixed COCO 17-point layout.

### SP500\_YOLO\_DETECT\_RECORD\_FLOATS

```cpp
#define SP500_YOLO_DETECT_RECORD_FLOATS 6
```

Floats per record, by task.

### SP500\_YOLO\_SEGMENT\_RECORD\_FLOATS

```cpp
#define SP500_YOLO_SEGMENT_RECORD_FLOATS 11
```

### SP500\_YOLO\_POSE\_RECORD\_FLOATS

```cpp
#define SP500_YOLO_POSE_RECORD_FLOATS 57
```

### SP500\_YOLO\_MASK\_NONE

```cpp
#define SP500_YOLO_MASK_NONE 0xFFFFFFFFu
```

[sp500\_yolo\_segmentation::mask\_offset](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/sp500_yolo_segmentation/#mask-offset>) value meaning "no mask stored for this box" - the snapped box was empty, or the mask buffer was full. The detection itself is still valid.

### SP500\_YOLO\_MAX\_CANDIDATES

```cpp
#define SP500_YOLO_MAX_CANDIDATES 1024
```

Candidates above the confidence threshold that the DSP ranks. Beyond this many, the surplus is dropped before duplicate removal.

## Enumerations

### (anonymous enum)

```cpp
enum
```

Head family; see the table at the top of this file.

| Value | Description |
| --- | --- |
| `SP500_YOLO_HEAD_ANCHORLESS = 0` |  |
| `SP500_YOLO_HEAD_ANCHOR = 1` |  |
| `SP500_YOLO_HEAD_NMSFREE = 2` |  |
| `SP500_YOLO_HEAD_DFLFREE = 3` |  |

### (anonymous enum)

```cpp
enum
```

What the head predicts.

| Value | Description |
| --- | --- |
| `SP500_YOLO_TASK_DETECT = 0` | boxes only |
| `SP500_YOLO_TASK_SEGMENT = 1` | boxes plus per-box masks |
| `SP500_YOLO_TASK_POSE = 2` | boxes plus 17 COCO keypoints |

## Functions

### sp500\_yolo\_mask\_offset

```cpp
uint32_t sp500_yolo_mask_offset(const sp500_yolo_segmentation *record)
```

Mask offset of a segmentation record, decoded from its float slot. Returns [SP500\_YOLO\_MASK\_NONE](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-mask-none>) when no mask was stored.

### sp500\_yolo\_params\_init

```cpp
void sp500_yolo_params_init(sp500_yolo_params *params)
```

Fill `params` with the defaults documented above.

### sp500\_yolo\_raw\_init

```cpp
void sp500_yolo_raw_init(sp500_yolo_raw *raw)
```

Zero `raw` so every plane reads as unused.

### sp500\_yolo\_raw\_anchor\_init

```cpp
void sp500_yolo_raw_anchor_init(sp500_yolo_raw_anchor *raw)
```

Zero `raw` so every plane reads as unused.

### sp500\_yolo\_output\_init

```cpp
void sp500_yolo_output_init(sp500_yolo_output *output)
```

Zero `output` so every buffer reads as unused.

### sp500\_yolo\_record\_floats

```cpp
int32_t sp500_yolo_record_floats(int32_t task)
```

Floats in one record of `task`, or 0 for an unknown task.

### sp500\_yolo\_records\_bytes

```cpp
uint32_t sp500_yolo_records_bytes(int32_t task, int32_t max_detections)
```

Bytes needed by `output.records` for `max_detections` records of `task`, or 0 for invalid arguments.

### sp500\_yolo\_grid\_cells

```cpp
int32_t sp500_yolo_grid_cells(int32_t img_w, int32_t img_h)
```

Grid cells summed over the three levels for a `img_w` x `img_h` input: the row count of a decoded anchor-free table. Multiply by `anchors_per_level` for an anchor head.

### sp500\_yolo\_head\_for\_model

```cpp
sp500_status sp500_yolo_head_for_model(const char *model_name, int32_t *head)
```

Head family for a model name, so you do not have to memorise the table.

Matching is case-insensitive, ignores `-`, `_`, `.` and spaces, treats the `v` as optional, and skips a size suffix - so "yolov8n", "YOLOv8-seg", "yolo8" and "yolov8" all resolve to ::SP500\_YOLO\_HEAD\_ANCHORLESS. Generations 3 and 5 exist in both families, and are read as the anchor-free retrained export when the name carries a `u` right after the generation or at the end: "yolov3u", "yolov3-sppu", "yolov5nu" and "yolov5n6u" are ::SP500\_YOLO\_HEAD\_ANCHORLESS, while "yolov5n" and "yolov5n6" are ::SP500\_YOLO\_HEAD\_ANCHOR. Recognised generations: 3, 5, 7, 8, 9, 10, 11, 12, 26, plus "gelan".

**Parameters**

- `model_name` — The model name, for example "yolo11" or "yolov8n".
- `head` — Receives one of the SP500\_YOLO\_HEAD\_\* values.

**Returns**

[SP500\_OK](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>), or [SP500\_ERR\_INVALID\_ARG](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) for a NULL argument or a name that is not recognised - in which case pick the family from the table at the top of this file.

### sp500\_yolo\_decode

```cpp
sp500_status sp500_yolo_decode(int32_t head, int32_t task, const sp500_yolo_raw *raw, const sp500_yolo_params *params, sp500_yolo_output *output, sp500_yolo_result *result)
```

Decode a split-plane head and remove duplicates, in one DSP call.

For ::SP500\_YOLO\_HEAD\_ANCHORLESS, ::SP500\_YOLO\_HEAD\_NMSFREE and ::SP500\_YOLO\_HEAD\_DFLFREE. Use [sp500\_yolo\_decode\_anchor()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-decode-anchor>) for the anchor family.

**Parameters**

- `head` — ::SP500\_YOLO\_HEAD\_ANCHORLESS, ::SP500\_YOLO\_HEAD\_NMSFREE or ::SP500\_YOLO\_HEAD\_DFLFREE.
- `task` — [SP500\_YOLO\_TASK\_DETECT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>), [SP500\_YOLO\_TASK\_SEGMENT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>) or [SP500\_YOLO\_TASK\_POSE](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>). NMSFREE supports detection only.
- `raw` — Raw head planes for all three levels.
- `params` — Model shape and thresholds. For segmentation also set `proto`, `mask_coeffs`, `proto_h`, `proto_w` and `mask_threshold`.
- `output` — Result buffers. `records` is required; `mask` is required for segmentation.
- `result` — Receives the record count. May be NULL.

**Returns**

[SP500\_OK](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) on success. [SP500\_ERR\_UNSUPPORTED](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) when the family does not implement `task`, [SP500\_ERR\_INVALID\_ARG](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) for a bad or incomplete parameter, [SP500\_ERR\_BUFFER\_TOO\_SMALL](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) when `output.records` cannot hold `max_detections` records, [SP500\_ERR\_NOT\_READY](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>), [SP500\_ERR\_TIMEOUT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) or [SP500\_ERR\_DSP](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>).

> [!NOTE]
>
> A frame with no detection is [SP500\_OK](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/dsp-h/#sp500-ok>) with `result->count == 0`.

### sp500\_yolo\_decode\_anchor

```cpp
sp500_status sp500_yolo_decode_anchor(int32_t task, const sp500_yolo_raw_anchor *raw, const sp500_yolo_params *params, sp500_yolo_output *output, sp500_yolo_result *result)
```

Decode an anchor head and remove duplicates, in one DSP call. ::SP500\_YOLO\_HEAD\_ANCHOR only.

**Parameters**

- `task` — [SP500\_YOLO\_TASK\_DETECT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>) or [SP500\_YOLO\_TASK\_SEGMENT](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-task-detect>). This family has no pose head.
- `raw` — One combined tensor per level.
- `params` — Model shape and thresholds, plus `anchors_per_level` and `anchors`.
- `output` — Result buffers.
- `result` — Receives the record count. May be NULL.

**Returns**

As [sp500\_yolo\_decode()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-decode>).

### sp500\_yolo\_postprocess

```cpp
sp500_status sp500_yolo_postprocess(int32_t head, int32_t task, const sp500_buffer *decoded, int32_t num_rows, const sp500_yolo_params *params, sp500_yolo_output *output, sp500_yolo_result *result)
```

Select detections from an already-decoded anchor table.

For networks that decode boxes inside the graph and hand you one table of candidate rows. Works for every family; the family still decides how duplicates are removed and whether rows carry an objectness column.

**Parameters**

- `head` — The family the network belongs to.
- `task` — The task the table was produced for.
- `decoded` — The decoded table: `num_rows` rows of `4 + objectness + num_classes + extra` floats, where objectness is 1 for ::SP500\_YOLO\_HEAD\_ANCHOR and 0 otherwise, and extra is `mask_coeffs` for segmentation or 51 for pose.
- `num_rows` — Rows in `decoded`. Required and must be positive; for a standard head this is [sp500\_yolo\_grid\_cells()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-grid-cells>), times `anchors_per_level` for the anchor family.
- `params` — Model shape and thresholds.
- `output` — Result buffers.
- `result` — Receives the record count. May be NULL.

**Returns**

As [sp500\_yolo\_decode()](<https://docs.mobilint.com/regulus/kr/v4.1/api/cpp/yolo-h/#sp500-yolo-decode>).
