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() 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() and sp500_yolo_decode_anchor() take the raw head tensors and do everything.
- 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, sp500_yolo_segmentation or sp500_yolo_pose according to the task; 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() returned.
Example
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 |
One detection. 6 floats; the layout of a SP500_YOLO_TASK_DETECT record. |
sp500_yolo_keypoint |
One keypoint of a pose record. |
sp500_yolo_output |
Where the results go. |
sp500_yolo_params |
Model shape and thresholds. |
sp500_yolo_pose |
One pose result. 57 floats; the layout of a SP500_YOLO_TASK_POSE record. |
sp500_yolo_raw |
Raw head tensors as separate planes, one set per feature level. |
sp500_yolo_raw_anchor |
Raw head tensors as one combined tensor per level. SP500_YOLO_HEAD_ANCHOR only. |
sp500_yolo_result |
What a YOLO call produced. |
sp500_yolo_segmentation |
One segmentation result. 11 floats; the layout of a SP500_YOLO_TASK_SEGMENT record. |
Macros¶
SP500_YOLO_LEVELS¶
Feature levels a YOLO head produces: strides 8, 16 and 32.
SP500_YOLO_POSE_KEYPOINTS¶
Keypoints in a pose record; the fixed COCO 17-point layout.
SP500_YOLO_DETECT_RECORD_FLOATS¶
Floats per record, by task.
SP500_YOLO_SEGMENT_RECORD_FLOATS¶
SP500_YOLO_POSE_RECORD_FLOATS¶
SP500_YOLO_MASK_NONE¶
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¶
Candidates above the confidence threshold that the DSP ranks. Beyond this many, the surplus is dropped before duplicate removal.
Enumerations¶
(anonymous 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)¶
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¶
Mask offset of a segmentation record, decoded from its float slot. Returns SP500_YOLO_MASK_NONE when no mask was stored.
sp500_yolo_params_init¶
Fill params with the defaults documented above.
sp500_yolo_raw_init¶
Zero raw so every plane reads as unused.
sp500_yolo_raw_anchor_init¶
Zero raw so every plane reads as unused.
sp500_yolo_output_init¶
Zero output so every buffer reads as unused.
sp500_yolo_record_floats¶
Floats in one record of task, or 0 for an unknown task.
sp500_yolo_records_bytes¶
Bytes needed by output.records for max_detections records of task, or 0 for invalid arguments.
sp500_yolo_grid_cells¶
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¶
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, or SP500_ERR_INVALID_ARG 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¶
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() for the anchor family.
Parameters
head— ::SP500_YOLO_HEAD_ANCHORLESS, ::SP500_YOLO_HEAD_NMSFREE or ::SP500_YOLO_HEAD_DFLFREE.task— SP500_YOLO_TASK_DETECT, SP500_YOLO_TASK_SEGMENT or SP500_YOLO_TASK_POSE. NMSFREE supports detection only.raw— Raw head planes for all three levels.params— Model shape and thresholds. For segmentation also setproto,mask_coeffs,proto_h,proto_wandmask_threshold.output— Result buffers.recordsis required;maskis required for segmentation.result— Receives the record count. May be NULL.
Returns
SP500_OK on success. SP500_ERR_UNSUPPORTED when the family does not implement task, SP500_ERR_INVALID_ARG for a bad or incomplete parameter, SP500_ERR_BUFFER_TOO_SMALL when output.records cannot hold max_detections records, SP500_ERR_NOT_READY, SP500_ERR_TIMEOUT or SP500_ERR_DSP.
Note
A frame with no detection is SP500_OK with result->count == 0.
sp500_yolo_decode_anchor¶
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 or SP500_YOLO_TASK_SEGMENT. This family has no pose head.raw— One combined tensor per level.params— Model shape and thresholds, plusanchors_per_levelandanchors.output— Result buffers.result— Receives the record count. May be NULL.
Returns
sp500_yolo_postprocess¶
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_rowsrows of4 + objectness + num_classes + extrafloats, where objectness is 1 for ::SP500_YOLO_HEAD_ANCHOR and 0 otherwise, and extra ismask_coeffsfor segmentation or 51 for pose.num_rows— Rows indecoded. Required and must be positive; for a standard head this is sp500_yolo_grid_cells(), timesanchors_per_levelfor the anchor family.params— Model shape and thresholds.output— Result buffers.result— Receives the record count. May be NULL.
Returns