Sample Postprocess Library Configuration Reference - Sample Postprocess Library Configuration Reference - 6.2 English - XD056

Vitis Video Analytics SDK (VVAS) 6.2 User Guide (XD056)

Document_ID
XD056
Release_Date
2026-06-12
Version
6.2 English

The vvas_xinfer plugin loads a postprocess shared library at runtime to decode inference output tensors into structured results (classifications, detections). The library is specified by the library-path field inside the postprocess-config JSON object, and library-specific options are passed through the library-config JSON object.

Three reference postprocess libraries are shipped as source under vvas-gst-plugins/sys/infer/vvas_postprocess_models/ in the vvas repository. They are built as standalone shared libraries and installed to /usr/lib/ on the target.

Table 29 Shipped Postprocess Libraries

Library

Model Type

Source File

libvvascore_postprocess_resnet50-1.0.so

Classification

postprocess_resnet50.cpp

libvvascore_postprocess_resnet18-1.0.so

Classification

postprocess_resnet18.cpp

libvvascore_postprocess_yolo-1.0.so

Detection (YOLO family)

postprocess_yolo.cpp

Classification: ResNet50 / ResNet18

Both libraries perform ImageNet-style top-k classification on a single output tensor with 1000 logits. They support INT8 (auto-dequantized), FP32, BF16, and FP16 tensor data types.

Table 30 library-config fields (classification)

Key

Type

Default

Description

topk

int

1

Number of top-scoring classes to return.

label-file-path

string

(required)

Path to a text file with one class label per line (1000 lines for ImageNet). Initialization fails if the file is missing or unreadable.

disable-softmax

bool

false

Skip the softmax computation before top-k selection. Use this when the model already outputs probabilities. ResNet50 only – the ResNet18 library always applies softmax and does not recognize this field.

Example library-config for ResNet50:

{
  "library-config": {
    "topk": 5,
    "label-file-path": "/usr/share/vvas/resnet50/labels.txt",
    "disable-softmax": false
  }
}

Detection: YOLO Family

The YOLO postprocess library decodes bounding-box predictions from a single output tensor and applies Non-Maximum Suppression (NMS). It supports both anchor-based models (YOLOv3, YOLOv5) and anchor-free models (YOLOv8 and later).

YOLO Output Tensor Layout

Anchor-based models (YOLOv3/v5) produce predictions with the layout [num_predictions, 5 + num_classes] where attribute index 4 is the objectness score. The final detection confidence is objectness * class_probability.

Anchor-free models (YOLOv8+) produce predictions with the layout [num_predictions, 4 + num_classes]. There is no objectness score; the class score is used directly as the detection confidence.

The library auto-detects whether the tensor is transposed ([attributes, predictions] vs [predictions, attributes]) from the tensor shape. No configuration is needed for this.

Table 31 library-config fields (YOLO detection)

Key

Type

Default

Description

conf_thresh

float

0.25

Minimum confidence score to keep a candidate detection. Must be finite and in the range [0.0, 1.0].

iou_thresh

float

0.45

IoU (Intersection over Union) threshold for NMS. Overlapping boxes above this threshold are suppressed. Must be finite and in the range [0.0, 1.0].

preset

string

(empty)

Apply defaults for a known YOLO model family. Supported families are yolo[v]5, yolo[v]7, yolo[v]8, yolo[v]9, yolo[v]11, yolo[v]12, and yolo[v]x. Explicit fields in library-config override preset values.

has_objectness_score

bool

Preset-dependent

Set to true for models that output an objectness score at tensor attribute index 4 (YOLOv3, YOLOv5). Set to false for anchor-free models that have no objectness channel (YOLOv8+). This must match the model architecture regardless of the model’s internal precision (FP16, INT8, etc.).

apply_sigmoid

bool

Preset-dependent

Apply sigmoid activation to raw objectness and class scores before thresholding. Enable when the model outputs raw logits instead of probabilities.

multi_label

bool

false

When true, each class score above the confidence threshold produces a separate detection for the same box. When false, only the highest-scoring class is used.

class_agnostic

bool

false

When false, NMS runs per-class (boxes of different classes do not suppress each other). When true, NMS runs across all classes in a shared coordinate space.

max_detections

int

300

Maximum number of detections returned after NMS. Must be a positive integer.

box_grid_decode

bool

Preset-dependent

Enable grid-based box decoding with stride offsets. Required for models whose output tensor contains raw grid-relative predictions. When enabled, the library applies sigmoid to center coordinates and exp to width/height, then offsets by the grid cell position using grid_strides, input_width, input_height, and preds_per_location.

preds_per_location

int

1

Number of predictions per grid cell. Only used when box_grid_decode is true. Must be a positive integer.

grid_strides

int array

[8, 16, 32]

Strides used to generate grid locations when box_grid_decode is true. The array must be non-empty, all values must be positive, no stride can exceed the configured input dimensions, and each stride must divide both input_width and input_height.

input_width

int

640

Model input width used for grid generation when box_grid_decode is true. Must be a positive integer.

input_height

int

640

Model input height used for grid generation when box_grid_decode is true. Must be a positive integer.

class_label_file

string

(empty)

Path to a text file with one class label per line (lines starting with # are treated as comments). If empty or not specified, the built-in 80-class COCO label list is used. The number of classes is inferred from the label count.

log_level

int

(system default)

VVAS log level for the postprocess library.

YOLO Presets

Preset names are case-insensitive. The v after yolo is optional, so yolov5, yolo5, YOLOv5, and yoloV5 select the same preset. After a preset is applied, any explicitly configured field overrides the preset default.

Table 32 YOLO preset defaults

Preset family

Defaults

yolo[v]5, yolo[v]7

has_objectness_score=true, apply_sigmoid=false, box_grid_decode=false, preds_per_location=3

yolo[v]8, yolo[v]9, yolo[v]11, yolo[v]12

has_objectness_score=false, apply_sigmoid=false, box_grid_decode=false, preds_per_location=1

yolo[v]x

has_objectness_score=true, apply_sigmoid=false, box_grid_decode=true, preds_per_location=1, grid_strides=[8, 16, 32]

Example library-config for YOLOv5:

{
  "library-config": {
    "preset": "yolov5",
    "conf_thresh": 0.25,
    "iou_thresh": 0.45,
    "class_label_file": "/usr/share/vvas/yolo/coco.names"
  }
}

Example library-config for YOLOv8:

{
  "library-config": {
    "preset": "yolov8",
    "conf_thresh": 0.25,
    "iou_thresh": 0.45,
    "class_label_file": "/usr/share/vvas/yolo/coco.names"
  }
}

Example library-config for YOLOX grid decode:

{
  "library-config": {
    "preset": "yolox",
    "conf_thresh": 0.35,
    "iou_thresh": 0.30,
    "input_width": 640,
    "input_height": 640,
    "grid_strides": [8, 16, 32],
    "class_label_file": "/usr/share/vvas/yolo/coco.names"
  }
}

Practical Guidance

  • Set has_objectness_score based on model architecture, not the model’s internal precision (INT8/FP16/FP32). Mixed-precision compiled models still follow the same output layout as their architecture defines.

  • For YOLOv8 and later anchor-free models, set has_objectness_score to false and box_grid_decode to false.

  • For YOLOv3/v5 anchor-based models, set has_objectness_score to true. Enable box_grid_decode only if the model outputs raw grid-relative predictions.

  • If using a YOLO preset, remember that explicitly configured JSON fields override the preset defaults.

  • When box_grid_decode is true, configure input_width, input_height, grid_strides, and preds_per_location so the generated grid count matches the model’s prediction count. For example, a P6 model may use [8, 16, 32, 64], and a P2-P5 model may use [4, 8, 16, 32].

  • INT8 tensors are automatically dequantized using the scale coefficient from the tensor info provided by the inference engine.

Adding a Custom Postprocess Library

To create a postprocess library for a model not covered by the reference implementations, see Adding New Postprocessing Implementation to VvasPostprocess.