Struct DecoderBuilder 

pub struct DecoderBuilder { /* private fields */ }

Implementations

impl DecoderBuilder

pub fn new() -> Self

Creates a default DecoderBuilder with no configuration and 0.5 score threshold and 0.5 IoU threshold.

A valid configuration must be provided before building the Decoder.

Examples

let decoder = DecoderBuilder::new()
    .with_config_yaml_str(config_yaml)
    .build()?;
assert_eq!(decoder.score_threshold, 0.5);
assert_eq!(decoder.iou_threshold, 0.5);

pub fn with_config_yaml_str(self, yaml_str: String) -> Self

Loads a model configuration in YAML format. Does not check if the string is a correct configuration file. Use DecoderBuilder.build() to deserialize the YAML and parse the model configuration.

Examples

let config_yaml = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/../../testdata/modelpack_split.yaml")).to_string();
let decoder = DecoderBuilder::new()
    .with_config_yaml_str(config_yaml)
    .build()?;

pub fn with_config_json_str(self, json_str: String) -> Self

Loads a model configuration in JSON format. Does not check if the string is a correct configuration file. Use DecoderBuilder.build() to deserialize the JSON and parse the model configuration.

Examples

let config_json = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/../../testdata/modelpack_split.json")).to_string();
let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .build()?;

pub fn with_config(self, config: ConfigOutputs) -> Self

Loads a model configuration. Does not check if the configuration is correct. Intended to be used when the user needs control over the deserialize of the configuration information. Use DecoderBuilder.build() to parse the model configuration.

Examples

let config_json = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/../../testdata/modelpack_split.json"));
let config = serde_json::from_str(config_json)?;
let decoder = DecoderBuilder::new().with_config(config).build()?;

pub fn with_schema(self, schema: SchemaV2) -> Self

Configure the decoder from a schema v2 metadata document.

Accepts a SchemaV2 as produced by SchemaV2::parse_json, SchemaV2::parse_yaml, SchemaV2::parse_file, or constructed programmatically. The builder validates the schema, compiles a [DecodeProgram] for any split logical outputs (per-scale or channel sub-splits), and downconverts the logical-level semantics to the legacy ConfigOutputs representation consumed by the existing decoder dispatch.

Examples

use edgefirst_decoder::{DecoderBuilder, DecoderResult};
use edgefirst_decoder::schema::SchemaV2;

let schema = SchemaV2::parse_file("model/edgefirst.json")?;
let decoder = DecoderBuilder::new()
    .with_schema(schema)
    .with_score_threshold(0.25)
    .build()?;

pub fn with_decode_dtype(self, dtype: DecodeDtype) -> Self

Choose the output dtype for the per-scale decoder pipeline.

Defaults to DecodeDtype::F32. Has no effect on schemas without per-scale children (which use the legacy decode path). F16 saves ~2× memory bandwidth at the cost of 10-bit mantissa precision; empirically safe for YOLO-family models.

Examples

use edgefirst_decoder::{DecodeDtype, DecoderBuilder, DecoderResult};
use edgefirst_decoder::schema::SchemaV2;

let schema = SchemaV2::parse_file("model/edgefirst.json")?;
let decoder = DecoderBuilder::new()
    .with_schema(schema)
    .with_decode_dtype(DecodeDtype::F32)
    .build()?;

pub fn with_config_yolo_det( self, boxes: Detection, version: Option<DecoderVersion>, ) -> Self

Loads a YOLO detection model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let decoder = DecoderBuilder::new()
    .with_config_yolo_det(
        configs::Detection {
            anchors: None,
            decoder: configs::DecoderType::Ultralytics,
            quantization: Some(configs::QuantTuple(0.012345, 26)),
            shape: vec![1, 84, 8400],
            dshape: Vec::new(),
            normalized: Some(true),
        },
        None,
    )
    .build()?;

pub fn with_config_yolo_split_det(self, boxes: Boxes, scores: Scores) -> Self

Loads a YOLO split detection model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let boxes_config = configs::Boxes {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.012345, 26)),
    shape: vec![1, 4, 8400],
    dshape: Vec::new(),
    normalized: Some(true),
};
let scores_config = configs::Scores {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 80, 8400],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_yolo_split_det(boxes_config, scores_config)
    .build()?;

pub fn with_config_yolo_segdet( self, boxes: Detection, protos: Protos, version: Option<DecoderVersion>, ) -> Self

Loads a YOLO segmentation model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let seg_config = configs::Detection {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.012345, 26)),
    shape: vec![1, 116, 8400],
    anchors: None,
    dshape: Vec::new(),
    normalized: Some(true),
};
let protos_config = configs::Protos {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 160, 160, 32],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_yolo_segdet(
        seg_config,
        protos_config,
        Some(configs::DecoderVersion::Yolov8),
    )
    .build()?;

pub fn with_config_yolo_split_segdet( self, boxes: Boxes, scores: Scores, mask_coefficients: MaskCoefficients, protos: Protos, ) -> Self

Loads a YOLO split segmentation model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let boxes_config = configs::Boxes {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.012345, 26)),
    shape: vec![1, 4, 8400],
    dshape: Vec::new(),
    normalized: Some(true),
};
let scores_config = configs::Scores {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.012345, 14)),
    shape: vec![1, 80, 8400],
    dshape: Vec::new(),
};
let mask_config = configs::MaskCoefficients {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.0064123, 125)),
    shape: vec![1, 32, 8400],
    dshape: Vec::new(),
};
let protos_config = configs::Protos {
    decoder: configs::DecoderType::Ultralytics,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 160, 160, 32],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_yolo_split_segdet(boxes_config, scores_config, mask_config, protos_config)
    .build()?;

pub fn with_config_modelpack_det(self, boxes: Boxes, scores: Scores) -> Self

Loads a ModelPack detection model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let boxes_config = configs::Boxes {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.012345, 26)),
    shape: vec![1, 8400, 1, 4],
    dshape: Vec::new(),
    normalized: Some(true),
};
let scores_config = configs::Scores {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 8400, 3],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_modelpack_det(boxes_config, scores_config)
    .build()?;

pub fn with_config_modelpack_det_split(self, boxes: Vec<Detection>) -> Self

Loads a ModelPack split detection model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let config0 = configs::Detection {
    anchors: Some(vec![
        [0.13750000298023224, 0.2074074000120163],
        [0.2541666626930237, 0.21481481194496155],
        [0.23125000298023224, 0.35185185074806213],
    ]),
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.012345, 26)),
    shape: vec![1, 17, 30, 18],
    dshape: Vec::new(),
    normalized: Some(true),
};
let config1 = configs::Detection {
    anchors: Some(vec![
        [0.36666667461395264, 0.31481480598449707],
        [0.38749998807907104, 0.4740740656852722],
        [0.5333333611488342, 0.644444465637207],
    ]),
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 9, 15, 18],
    dshape: Vec::new(),
    normalized: Some(true),
};

let decoder = DecoderBuilder::new()
    .with_config_modelpack_det_split(vec![config0, config1])
    .build()?;

pub fn with_config_modelpack_segdet( self, boxes: Boxes, scores: Scores, segmentation: Segmentation, ) -> Self

Loads a ModelPack segmentation detection model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let boxes_config = configs::Boxes {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.012345, 26)),
    shape: vec![1, 8400, 1, 4],
    dshape: Vec::new(),
    normalized: Some(true),
};
let scores_config = configs::Scores {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 8400, 2],
    dshape: Vec::new(),
};
let seg_config = configs::Segmentation {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 640, 640, 3],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_modelpack_segdet(boxes_config, scores_config, seg_config)
    .build()?;

pub fn with_config_modelpack_segdet_split( self, boxes: Vec<Detection>, segmentation: Segmentation, ) -> Self

Loads a ModelPack segmentation split detection model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let config0 = configs::Detection {
    anchors: Some(vec![
        [0.36666667461395264, 0.31481480598449707],
        [0.38749998807907104, 0.4740740656852722],
        [0.5333333611488342, 0.644444465637207],
    ]),
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.08547406643629074, 174)),
    shape: vec![1, 9, 15, 18],
    dshape: Vec::new(),
    normalized: Some(true),
};
let config1 = configs::Detection {
    anchors: Some(vec![
        [0.13750000298023224, 0.2074074000120163],
        [0.2541666626930237, 0.21481481194496155],
        [0.23125000298023224, 0.35185185074806213],
    ]),
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.09929127991199493, 183)),
    shape: vec![1, 17, 30, 18],
    dshape: Vec::new(),
    normalized: Some(true),
};
let seg_config = configs::Segmentation {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 640, 640, 2],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_modelpack_segdet_split(vec![config0, config1], seg_config)
    .build()?;

pub fn with_config_modelpack_seg(self, segmentation: Segmentation) -> Self

Loads a ModelPack segmentation model configuration. Use DecoderBuilder.build() to parse the model configuration.

Examples

let seg_config = configs::Segmentation {
    decoder: configs::DecoderType::ModelPack,
    quantization: Some(configs::QuantTuple(0.0064123, -31)),
    shape: vec![1, 640, 640, 3],
    dshape: Vec::new(),
};
let decoder = DecoderBuilder::new()
    .with_config_modelpack_seg(seg_config)
    .build()?;

pub fn add_output(self, output: ConfigOutput) -> Self

Add an output to the decoder configuration.

Incrementally builds the model configuration by adding outputs one at a time. The decoder resolves the model type from the combination of outputs during build().

If dshape is non-empty on the output, shape is automatically derived from it (the size component of each named dimension). This prevents conflicts between shape and dshape.

This uses the programmatic config path. Calling this after with_config_json_str() or with_config_yaml_str() replaces the string-based config source.

Examples

let decoder = DecoderBuilder::new()
    .add_output(ConfigOutput::Scores(configs::Scores {
        decoder: configs::DecoderType::Ultralytics,
        dshape: vec![
            (configs::DimName::Batch, 1),
            (configs::DimName::NumClasses, 80),
            (configs::DimName::NumBoxes, 8400),
        ],
        ..Default::default()
    }))
    .add_output(ConfigOutput::Boxes(configs::Boxes {
        decoder: configs::DecoderType::Ultralytics,
        dshape: vec![
            (configs::DimName::Batch, 1),
            (configs::DimName::BoxCoords, 4),
            (configs::DimName::NumBoxes, 8400),
        ],
        ..Default::default()
    }))
    .build()?;

pub fn with_decoder_version(self, version: DecoderVersion) -> Self

Sets the decoder version for Ultralytics models.

This is used with add_output() to specify the YOLO architecture version when it cannot be inferred from the output shapes alone.

• Yolov5, Yolov8, Yolo11: Traditional models requiring external NMS
• Yolo26: End-to-end models with NMS embedded in the model graph

Examples

let decoder = DecoderBuilder::new()
    .add_output(ConfigOutput::Detection(configs::Detection {
        decoder: configs::DecoderType::Ultralytics,
        dshape: vec![
            (configs::DimName::Batch, 1),
            (configs::DimName::NumBoxes, 100),
            (configs::DimName::NumFeatures, 6),
        ],
        ..Default::default()
    }))
    .with_decoder_version(configs::DecoderVersion::Yolo26)
    .build()?;

pub fn with_score_threshold(self, score_threshold: f32) -> Self

Sets the scores threshold of the decoder

Examples

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_score_threshold(0.654)
    .build()?;
assert_eq!(decoder.score_threshold, 0.654);

pub fn with_iou_threshold(self, iou_threshold: f32) -> Self

Sets the IOU threshold of the decoder. Has no effect when NMS is set to None

Examples

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_iou_threshold(0.654)
    .build()?;
assert_eq!(decoder.iou_threshold, 0.654);

pub fn with_nms(self, nms: Option<Nms>) -> Self

Sets the NMS mode for the decoder.

• Some(Nms::Auto) — resolve from model config (e.g. edgefirst.json) or fall back to ClassAgnostic (this is the builder default)
• Some(Nms::ClassAgnostic) — class-agnostic NMS: suppress overlapping boxes regardless of class label
• Some(Nms::ClassAware) — class-aware NMS: only suppress boxes that share the same class label AND overlap above the IoU threshold
• None — bypass NMS entirely (for end-to-end models with embedded NMS)

Examples

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_nms(Some(Nms::ClassAware))
    .build()?;
assert_eq!(decoder.nms, Some(Nms::ClassAware));

pub fn with_pre_nms_top_k(self, pre_nms_top_k: usize) -> Self

Sets the maximum number of candidate boxes fed into NMS after score filtering. Uses partial sort (O(N)) to select the top-K candidates, dramatically reducing the O(N²) NMS cost when many low-confidence proposals pass the threshold (common with mAP eval at 0.001).

Default: 300.

⚠️ Validation vs Deployment

The default is appropriate for deployment where score_threshold ≥ 0.25 means few anchors survive filtering and top-K is effectively a no-op.

For COCO mAP evaluation (score_threshold ≈ 0.001), set this to the total anchor count (8 400 for standard 640 × 640 YOLO models) or to 0 (no limit) so that all score-passing candidates reach NMS. Failing to do so causes ~9 pp box mAP loss — the decoder math is correct but the evaluation protocol requires full recall across the confidence range.

Post-processing latency scales with candidate count. At deployment thresholds the cost difference is negligible; at validation thresholds it is measurable but necessary for correct results.

Examples

Deployment (default top-K, high score threshold):

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_score_threshold(0.25)
    // pre_nms_top_k defaults to 300 — appropriate here
    .build()?;

COCO mAP evaluation (pass all anchors to NMS):

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_score_threshold(0.001)
    .with_pre_nms_top_k(8400)  // all YOLO anchors
    .with_max_det(300)
    .build()?;
assert_eq!(decoder.pre_nms_top_k, 8400);

pub fn with_max_det(self, max_det: usize) -> Self

Sets the maximum number of detections returned after NMS. Matches the Ultralytics max_det parameter.

Default: 300.

Examples

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_max_det(100)
    .build()?;
assert_eq!(decoder.max_det, 100);

pub fn with_input_dims(self, width: usize, height: usize) -> Self

Sets the model input dimensions (width, height) consumed by the EDGEAI-1303 normalization path. Use this when building via with_config / add_output (no schema) and the model emits pixel-space boxes that need to be divided by (W, H) before NMS.

When the builder is also configured with with_schema (or with_config_json_str / with_config_yaml_str) and the schema’s input block carries usable dims, this explicit override takes precedence so callers can correct schemas with missing or wrong input specs without rewriting the schema.

Examples

let decoder = DecoderBuilder::new()
    .with_config_yaml_str(config_yaml)
    .with_input_dims(640, 640)
    .build()?;
assert_eq!(decoder.input_dims(), Some((640, 640)));

pub fn build(self) -> Result<Decoder, DecoderError>

Builds the decoder with the given settings. If the config is a JSON or YAML string, this will deserialize the JSON or YAML and then parse the configuration information.

Examples

let decoder = DecoderBuilder::new()
    .with_config_json_str(config_json)
    .with_score_threshold(0.654)
    .build()?;

Trait Implementations

impl Clone for DecoderBuilder

fn clone(&self) -> DecoderBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DecoderBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DecoderBuilder

fn default() -> Self

Creates a default DecoderBuilder with no configuration and 0.5 score threshold and 0.5 IoU threshold.

A valid configuration must be provided before building the Decoder.

Examples

let decoder = DecoderBuilder::default()
    .with_config_yaml_str(config_yaml)
    .build()?;
assert_eq!(decoder.score_threshold, 0.5);
assert_eq!(decoder.iou_threshold, 0.5);

impl PartialEq for DecoderBuilder

fn eq(&self, other: &DecoderBuilder) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for DecoderBuilder