Top-level structure

A complete configuration has six top-level keys: four required, two optional. Click a card below to jump straight to its parameter reference.

A minimal skeleton with every top-level key in place:

{
  "inputs":             { ... },
  "calibration_method": "...",
  "calibration_num":    100,
  "default_loader":     { ... },
  "enhanced_scheme":    { ... },  // optional
  "ppu":                { ... }   // optional
}

inputs

Defines the input tensor name and shape of your ONNX model.

{
  "inputs": {
    "images": [1, 3, 640, 640]
  }
}

Calibration parameters

Two parameters control how DX-COM estimates the FP32 → INT8 quantisation ranges. calibration_method picks the algorithm; calibration_num sets how many samples it processes.

{
  "calibration_method": "ema"
}

{
  "calibration_num": 100
}

default_loader

Configures the calibration data pipeline: where to find images, which file types to accept, and how to preprocess them before feeding them to the compiler.

{
  "default_loader": {
    "dataset_path":    "./calibration_images",
    "file_extensions": ["jpeg", "jpg", "png", "JPEG"],
    "preprocessings": [
      {"resize":       {"width": 640, "height": 640}},
      {"convertColor": {"form": "BGR2RGB"}},
      {"div":          {"x": 255}},
      {"normalize":    {"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]}},
      {"transpose":    {"axis": [2, 0, 1]}},
      {"expandDim":    {"axis": 0}}
    ]
  }
}

enhanced_scheme — DXQ accuracy recovery

Enables DXQ, a set of accuracy-recovery algorithms that reduce the accuracy loss introduced by INT8 quantisation. Schemes range from P0 (fast, modest improvement) to P5 (slow, high improvement).

{
  "enhanced_scheme": {
    "DXQ-P3": {
      "num_samples": 1024
    }
  }
}

ppu — Post-Processing Unit

The Post-Processing Unit (PPU) is a hardware block inside the DX-M1 NPU designed to accelerate object detection post-processing. Enabling PPU offloads parts of the detection pipeline from the host CPU to the NPU, reducing CPU load and end-to-end latency.

Should I enable PPU?

Three PPU paths

Pick the path that matches your model's detection head. If you're using YOLOv8 or later, see the Type 1 vs Type 2 decision below.

Type 0 — anchor-based models (YOLOv3, v4, v5, v7)

Offloads confidence filtering and Argmax class selection for anchor-based detection heads to the NPU hardware.

ppu — type 0

Optional

example — anchor-based YOLO

{
  "ppu": {
    "type":        0,
    "conf_thres":  0.25,
    "activation":  "Sigmoid",
    "num_classes": 80,
    "layer": {
      "Conv_245": {"num_anchors": 3},
      "Conv_294": {"num_anchors": 3},
      "Conv_343": {"num_anchors": 3}
    }
  }
}

Parameter	Type	Description
type	int	Set to 0 for anchor-based models
conf_thres	float	Confidence threshold. Detections below this value are filtered at compile time. Fixed at compile time, changing it requires recompilation.
activation	string	Activation applied to outputs. Typically "Sigmoid" for anchor-based YOLO models.
num_classes	int	Number of detection classes in your model
layer	object	Maps Conv node names to their anchor count. Each key is a node name from the ONNX graph.

Finding layer node names

Open your model in Netron. Trace backward from the model outputs and locate the final Conv layers in the detection head. For anchor-based models, these Conv layers output feature maps with shape [1, num_anchors × (5 + num_classes), H, W]. There is typically one Conv per detection scale (small, medium, large objects).

The output channel count confirms the right node. For example, with 3 anchors and 80 classes: 3 × (5 + 80) = 255. Copy the node name exactly from the Node Properties panel on the right side of Netron.

Type 1 — anchor-free models (YOLOX, YOLOv8–v12)

Offloads confidence filtering and class selection to the NPU hardware for anchor-free detection architectures. The exact layer structure depends on whether your model is YOLOX (separate objectness and class confidence branches) or YOLOv8 and later (merged confidence output).

ppu — type 1 (YOLOX)

Optional

example — YOLOX

{
  "ppu": {
    "type":        1,
    "conf_thres":  0.25,
    "num_classes": 80,
    "layer": [
      {"bbox": "output_bbox_1", "obj_conf": "output_obj_1", "cls_conf": "output_cls_1"},
      {"bbox": "output_bbox_2", "obj_conf": "output_obj_2", "cls_conf": "output_cls_2"},
      {"bbox": "output_bbox_3", "obj_conf": "output_obj_3", "cls_conf": "output_cls_3"}
    ]
  }
}

Finding layer node names

The YOLOX head has three detection scales, each with three separate Conv branches: bbox, obj_conf, and cls_conf. Locate the Conv node for each branch at each scale and copy the node names into the layer array, 9 entries total (3 scales × 3 branches). The node name is shown in the Node Properties panel on the right side of Netron.

ppu — type 1 (YOLOv8 / v9 / v10 / v11 / v12)

Optional

example — YOLOv8+

{
  "ppu": {
    "type":        1,
    "conf_thres":  0.25,
    "num_classes": 80,
    "layer": [
      {"bbox": "Mul_441", "cls_conf": "Sigmoid_442"}
    ]
  }
}

Finding layer node names

Open the model in Netron. Locate the final Concat node in the detection head. Trace backward from it to find the bbox source (the Mul node) and the cls_conf source (the Sigmoid node). Click each node to read its exact name from the Node Properties panel on the right.

Type 1 — parameter reference

Layer entry fields

Type 2 — DFL-based anchor-free models, CPU-side TopK (YOLOv8–v12)

type: 2 does not use PPU hardware. It is a CPU-side optimisation that runs TopK candidate reduction before the DFL decoding and NMS stages. By reducing the number of candidates that flow into the heavier CPU-side post-processing steps, it lowers CPU workload and improves runtime efficiency.

Use type: 2 when your model uses a DFL-based head and you can map per-scale bbox and cls_conf nodes, but the type: 1 mapping is unavailable or produces a compile error. This path was validated with YOLOv8, v9, v10, v11, and v12 in DX-COM v2.3.0.

{
  "ppu": {
    "type":        2,
    "topk":        512,
    "num_classes": 80,
    "layer": [
      {"bbox": "bbox_head_p3", "cls_conf": "cls_head_p3"},
      {"bbox": "bbox_head_p4", "cls_conf": "cls_head_p4"},
      {"bbox": "bbox_head_p5", "cls_conf": "cls_head_p5"}
    ]
  }
}

Type 1 vs Type 2 — which should you use?

For YOLOv8 and later, both paths are valid. Use this matrix to pick the right one.

Complete configuration examples

Two end-to-end configurations you can copy into your own project as a starting point. Both have been compiled against DX-COM v2.3.0.

Classification model (no PPU)

A typical ImageNet-style classification model (ResNet, MobileNet, EfficientNet) with standard normalisation and 224×224 input.

{
  "inputs":             {"input": [1, 3, 224, 224]},
  "calibration_method": "ema",
  "calibration_num":    100,
  "default_loader": {
    "dataset_path":    "./calibration_images",
    "file_extensions": ["jpeg", "jpg", "png", "JPEG"],
    "preprocessings": [
      {"resize":       {"width": 224, "height": 224}},
      {"convertColor": {"form": "BGR2RGB"}},
      {"div":          {"x": 255}},
      {"normalize":    {"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]}},
      {"transpose":    {"axis": [2, 0, 1]}},
      {"expandDim":    {"axis": 0}}
    ]
  }
}

YOLOv11n with PPU type 1

YOLOv11n object detection at 640×640 with hardware-accelerated post-processing. Note the absence of normalize, YOLO models do not use ImageNet normalisation.

{
  "inputs":             {"images": [1, 3, 640, 640]},
  "calibration_method": "ema",
  "calibration_num":    100,
  "default_loader": {
    "dataset_path":    "./calibration_images",
    "file_extensions": ["jpeg", "jpg", "png", "JPEG"],
    "preprocessings": [
      {"resize":       {"width": 640, "height": 640}},
      {"convertColor": {"form": "BGR2RGB"}},
      {"div":          {"x": 255}},
      {"transpose":    {"axis": [2, 0, 1]}},
      {"expandDim":    {"axis": 0}}
    ]
  },
  "ppu": {
    "type":        1,
    "conf_thres":  0.25,
    "num_classes": 80,
    "layer": [
      {"bbox": "Mul_441", "cls_conf": "Sigmoid_442"}
    ]
  }
}

Preprocessing operations reference

The operations available in the default_loader.preprocessings array. Operations execute in the order they are listed. Operations marked absorbable may be moved into the NPU graph at compile time.

{"convertColor": {"form": "BGR2RGB"}}

{"resize": {"mode": "default", "width": 640, "height": 640, "interpolation": "LINEAR"}}

{"centercrop": {"width": 224, "height": 224}}

{"transpose": {"axis": [2, 0, 1]}}

{"expandDim": {"axis": 0}}

{"normalize": {"mean": [0.485, 0.456, 0.406], "std": [0.229, 0.224, 0.225]}}

{"div": {"x": 255}}

{"mul": {"x": 255}}

{"add": {"x": 128}}

{"subtract": {"x": 127}}

Configuration FAQ