feat(mmdet): compile decoding parameters into the runner

[201815054]

Three things, in the order they build on each other: the decoding parameters stop being a file, the runner produces something a person can look at, and the guide describes what results.

1. Parameters become a generated function

Export wrote <name>.postproc.json — anchor scales, head convolution layout, normalisation values — and the runner read it at startup as a third positional argument:

run_mmdet <gguf> <input> <postproc.json> <out.bin> [size]

Once an architecture is fixed those values never change again. They are constants, and they were being shipped as input, parsed on every run, and carried as a third file that has to stay in step with the second. A .gguf and a .postproc.json from different exports load without complaint and decode wrongly.

mmdet_to_pt.py emits <name>.postproc.h instead:

// Generated by mmdet_to_pt.py — do not edit.
// source: retinanet_r18_fpn_1x_coco.py
inline mmdet_cfg mmdet_params() {
    mmdet_cfg c;
    c.head.stacked_convs = 4;
    c.det.strides = {8.0f, 16.0f, 32.0f, 64.0f, 128.0f};
    /* ... */
    return c;
}

compiled into the runner alongside the head component and the backbone graph.

	Before	After
Files to deploy	3	2
Read at startup	GGUF + JSON	GGUF
Mismatched pair possible	yes, silently	no

build_mmdet_cpp.sh takes the header as an optional second argument and otherwise finds *.postproc.h in the generated directory. A second argument that is not a header is still read as an architecture name, so existing invocations keep working. frcnn_to_pt.py and the two-stage runners keep their own sidecar; only the single-stage path changes here.

2. The result is an image by default

The runner wrote raw float32 and printed a count, so seeing what a detector had found meant writing a script. Every other command-line entry point in this repository produces an image; this one now does too. The output extension decides:

run_mmdet model.gguf image.jpg detected.png 512   # boxes drawn on the image
run_mmdet model.gguf image.jpg boxes.bin     512   # raw float32

Raw output is unchanged and one extension away, because comparing against a reference implementation needs the numbers, not a picture.

tools/detect/draw.h holds the drawing: box outlines, one colour per class, no text. Keeping a font out of the runner costs nothing, because the runner also prints the highest-scoring detections as a table — the image carries where, the table carries what.

Variable	Effect
VISP_DRAW_THRESHOLD	Minimum score to draw. Default 0.3
VISP_PRINT_DETS	How many rows to print. 0 turns the table off

tools/verify/draw_boxes.py draws a .bin kept for comparison, and does add class names and scores as text.

3. Documentation

docs/mmdet-detectors.md documents the whole path: the export frontend, the interface a compiled backbone module must satisfy, the runner, the components in tools/detect, the decoder API in postproc.h, the two-stage and instance-segmentation variants, ByteTrack, and the fields of the generated parameters.

tools/README.md is rewritten in English and describes how the directory is arranged rather than restating the guide.

Verification

Run from an empty directory following the documented steps, on RetinaNet R18 at 512:

Step	Result
Export	backbone.pt + backbone.postproc.h
Compile at 512	136 tensors
Build runner	links against libvisioncpp
Run, image output	100 detections, boxes drawn
Run, .bin output	byte-identical to the previous JSON path (cmp)
VISP_PRINT_DETS=0	table suppressed
VISP_DRAW_THRESHOLD=0.84	6 drawn; draw_boxes.py agrees on the same file

Two documentation defects surfaced during that run and are fixed here:

• The build step was shown without the parameters header, but export writes it next to backbone.pt rather than into the generated directory, so the command as printed could not find it.
• The compile step did not say which resolution to use. A graph built at a different size aborts in ggml_can_repeat once a tensor of the wrong extent reaches a residual addition — a failure a long way from its cause.

Independent of #11 and #13.

🤖 Generated with Claude Code

[201815054]

Closing while a larger issue is investigated: with a trained checkpoint the pipeline does not reproduce the reference detections. Reproduced on main, so it predates these changes, but there is no point reviewing documentation for a flow whose end-to-end correctness is in question.