Output postprocessing

Understand how to fine-tune postprocessing parameters to control model output—filter predictions, apply suppression, and reduce clutter for more usable results.

Estimated read time: 4 minutes

Postprocessing turns raw model predictions into the final list you work with. The goal is simple: keep the predictions you care about, drop the rest, and do it in a way that’s stable and fast. This page focuses on runtime-adjustable knobs and why you’d change them.

Model family notes

• Detection/instance tasks (e.g., object detection, instance segmentation): main knobs are output_confidence_threshold, output_nms_threshold, result caps, and output_class_set.

• Classification: main knob is output_top_k (how many labels to return). NMS doesn’t apply.

• Pose/keypoints: output_pose_threshold filters low‑confidence landmarks; other detection knobs may still apply if bounding boxes are present.

Compare postprocessing configurations using the tabs below.

Default

Baseline settings: confidence 0.25 and NMS 0.45.

High confidence

Looser NMS

Tight NMS

Person-only

Detection cap

Basic Parameters

1

Confidence threshold: output_confidence_threshold

Minimum score to keep a prediction.

• Higher values → fewer boxes, more precision

• Lower values → more boxes, better recall (but more false positives)

• Suggested values: 0.25 for exploration, 0.4–0.6 for production (tune per model)

2

NMS overlap: output_nms_threshold

IoU threshold for non‑maximum suppression—how much overlap is allowed before suppressing a box.

• Lower values (e.g., 0.4) → aggressive suppression (cleaner but may remove nearby objects)

• Higher values (e.g., 0.6) → keeps more overlapping boxes (better for crowded scenes)

3

Caps: size and balance of the output list

• Detection/instance tasks:

  • output_max_detections: upper bound for total detections (global cap)

  • output_max_detections_per_class: per‑class limit (prevents one class from dominating)

  • output_max_classes_per_detection: max labels per box (for multi‑label outputs)

• Classification:

  • output_top_k: number of top labels to return (e.g., 1 for single‑label, 5–10 for exploratory UIs)

4

Focus by class: output_class_set

Allowlist of classes you want to keep (use label strings).

• Example: ["person", "car", "truck"]

Inspect label_dictionary to avoid typos and confirm canonical names.

Advanced Parameters

• output_use_regular_nms (bool): toggles NMS algorithm if supported. Use only if the default behaves poorly.

• output_pose_threshold (float): filters low-confidence keypoints in pose models.

• output_postprocess_type (info): reports model’s postprocessing type. Informational only (see advanced guide).

• inference_results_type (info): indicates result format variant. Leave as default unless your integration requires changes.

• custom_postprocessor (advanced): attach your own logic for decoding or filtering results (see advanced guide).

Pitfalls to avoid

• Too low confidence + low NMS → too many overlapping boxes → UI lag, noisy metrics

• Too high confidence → misses small/faint objects → high precision, low recall

• Small output_max_detections → drops valid detections (especially long‑tail classes)

• Wrong class names → output_class_set must match label_dictionary exactly

Minimal Inspection

Run this quick check to confirm the postprocessing settings applied by the model.

Example

from degirum_tools import ModelSpec, remote_assets

spec = ModelSpec(
    model_name="yolov8n_coco--640x640_quant_hailort_multidevice_1",
    zoo_url="degirum/hailo",
    inference_host_address="@local",
    model_properties={
        "device_type": ["HAILORT/HAILO8L", "HAILORT/HAILO8"],
    },
)
model = spec.load_model()
result = model(remote_assets.urban_picnic_elephants)

print("conf:", model.output_confidence_threshold)
print("nms:", model.output_nms_threshold)
print("max det:", model.output_max_detections)
print("per-class:", model.output_max_detections_per_class)
print("top-k:", model.output_top_k)
print("class set:", model.output_class_set)
print("pose thr:", getattr(model, "output_pose_threshold", None))
print("nms flavor:", getattr(model, "output_use_regular_nms", None))
print("results type:", model.inference_results_type)
print("custom postprocess:", getattr(result, "custom_postprocess_data", None))

Example output:

conf: 0.25
nms: 0.45
max det: 200
per-class: 200
top-k: None
class set: None
pose thr: None
nms flavor: None
results type: InferenceResults.DETECTION
custom postprocess: None