edgefirst_decoder/decoder/

mod.rs

// SPDX-FileCopyrightText: Copyright 2025 Au-Zone Technologies
// SPDX-License-Identifier: Apache-2.0

use ndarray::{ArrayView, ArrayViewD, Dimension};
use num_traits::{AsPrimitive, Float};

use crate::{DecoderError, DetectBox, ProtoData, Segmentation};

pub mod config;
pub mod configs;

use configs::ModelType;

#[derive(Debug)]
pub struct Decoder {
    model_type: ModelType,
    pub iou_threshold: f32,
    pub score_threshold: f32,
    /// NMS mode (always a concrete variant after build — `Nms::Auto` is
    /// resolved during `DecoderBuilder::build()` and never stored here):
    /// - `Some(ClassAgnostic)` — class-agnostic NMS
    /// - `Some(ClassAware)` — class-aware NMS
    /// - `None` — NMS bypassed (end-to-end models)
    ///
    /// Assigning `Some(Nms::Auto)` to this field directly violates that
    /// invariant: `Nms::Auto` must be resolved by
    /// [`DecoderBuilder::build`](crate::DecoderBuilder::build). Debug builds
    /// panic on it at decode (a `debug_assert!` in NMS dispatch); release
    /// builds treat it as class-aware without consulting the config.
    pub nms: Option<configs::Nms>,
    /// Maximum number of candidate boxes fed into NMS after score filtering.
    /// Reduces O(N²) NMS cost when many low-confidence proposals pass the
    /// threshold (common during COCO mAP evaluation with threshold ≈ 0.001).
    /// Candidates are ranked by score, equal scores by anchor index; only the
    /// top `pre_nms_top_k` proceed to NMS. Applies to every NMS decode path;
    /// ignored when `nms` is `None`.
    ///
    /// - `None` (the default unless the builder was given a cap): resolved
    ///   per decode by [`Decoder::pre_nms_top_k_for`] —
    ///   [`MULTI_LABEL_PRE_NMS_TOP_K`] (30 000, Ultralytics' `max_nms`) for a
    ///   multi-label decode, [`DEFAULT_PRE_NMS_TOP_K`] (300) for an argmax
    ///   decode, including the tracking entry points of a multi-label decoder.
    /// - `Some(n)`: an explicit cap used by every decode as given; `Some(0)`
    ///   is unbounded. Assigning it after build is as explicit as
    ///   [`DecoderBuilder::with_pre_nms_top_k`](crate::DecoderBuilder::with_pre_nms_top_k).
    ///
    /// # ⚠️ Validation vs Deployment
    ///
    /// The default of 300 is tuned for **deployment** (score threshold ≥ 0.25)
    /// where few anchors pass the score filter, making top-K a no-op in
    /// practice while bounding worst-case NMS cost.
    ///
    /// For **mAP evaluation** (score threshold ≈ 0.001), most of the 8 400
    /// YOLO anchors pass the score filter. At `pre_nms_top_k = 300`, roughly
    /// 74 % of candidates that would survive NMS are discarded *before* NMS
    /// runs, causing **~9 pp box mAP loss** — a measurement artifact, not a
    /// model quality issue.
    ///
    /// | Use case | `pre_nms_top_k` | `score_threshold` |
    /// |----------|----------------:|------------------:|
    /// | Deployment | `None` (300) | ≥ 0.25 |
    /// | COCO mAP evaluation, argmax | `Some(0)`, or ≥ the anchor count (8 400) | 0.001 |
    /// | COCO mAP evaluation, multi-label | `Some(0)`, or `None` (30 000) | 0.001 |
    ///
    /// Post-processing latency scales with the number of candidates entering
    /// NMS. At deployment thresholds the candidate count is already small, so
    /// raising `pre_nms_top_k` has negligible cost. At validation thresholds
    /// the increase is measurable but necessary for correct recall.
    pub pre_nms_top_k: Option<usize>,
    /// Maximum number of detections returned after NMS. Matches the
    /// Ultralytics `max_det` parameter.  Default: 300.
    ///
    /// This bound applies uniformly across all segmentation and detection
    /// decode paths reached via [`Decoder::decode`] / [`Decoder::decode_proto`].
    /// The output `Vec`'s capacity is only an allocation hint; the post-NMS
    /// detection count is bounded solely by `max_det` (EDGEAI-1302).
    pub max_det: usize,
    /// Whether decoded boxes are in normalized [0,1] coordinates.
    /// - `Some(true)`: Coordinates in [0,1] range
    /// - `Some(false)`: Pixel coordinates
    /// - `None`: Unknown, caller must infer (e.g., check if any coordinate >
    ///   1.0)
    normalized: Option<bool>,
    /// Model input spatial dimensions `(width, height)`, captured from
    /// the schema's `input.shape` / `input.dshape` at builder time.
    /// Required to honour `normalized: false`: pixel-space box coords
    /// emitted by the model are divided by these dimensions before NMS
    /// so the post-NMS bbox is in `[0, 1]`. `None` when no schema input
    /// spec is available — the legacy >2.0 reject in `protobox` then
    /// preserves the previous safety net (EDGEAI-1303).
    input_dims: Option<(usize, usize)>,
    /// Schema v2 merge program. Present when the decoder was built from
    /// a [`crate::schema::SchemaV2`] whose logical outputs carry
    /// physical children. Absent for flat configurations (v1 and
    /// flat-v2).
    pub(crate) decode_program: Option<merge::DecodeProgram>,
    /// When `true`, emit one detection per (anchor, class) pair for every
    /// class whose score meets the threshold — matching Ultralytics `val`
    /// multi-label decode.  **OFF by default.**
    ///
    /// # Deployment safety
    /// `Decoder::decode_tracked` ignores this and decodes one label per
    /// box: ByteTrack matches on IoU only, so per-class duplicates of one
    /// anchor would spawn phantom tracks.
    pub(crate) multi_label: bool,
    /// Where `multi_label` came from; named in the tracked-decode warning.
    pub(crate) multi_label_source: MultiLabelSource,
    /// Set once this decoder has logged that tracked decode ignores
    /// multi-label, so each decoder warns once.
    tracked_multi_label_warned: std::sync::atomic::AtomicBool,
    /// Per-scale fast path. Constructed at build time from a schema-v2
    /// document with per-scale children. Wrapped in `Mutex` because
    /// `Decoder::decode_proto` and `Decoder::decode` are `&self` but
    /// the per-scale buffers are mutated per-frame.
    pub(crate) per_scale: Option<std::sync::Mutex<crate::per_scale::PerScaleDecoder>>,
}

/// Where a decoder's multi-label setting came from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub(crate) enum MultiLabelSource {
    /// Neither the caller nor the model config set it.
    #[default]
    Default,
    /// Declared by the model config's `nms_multi_label`.
    Metadata,
    /// Set by the caller through [`DecoderBuilder::with_multi_label`].
    Explicit,
}

impl PartialEq for Decoder {
    fn eq(&self, other: &Self) -> bool {
        // DecodeProgram and PerScaleDecoder have non-comparable embedded
        // data; compare by the config-derived fields only.
        self.model_type == other.model_type
            && self.iou_threshold == other.iou_threshold
            && self.score_threshold == other.score_threshold
            && self.nms == other.nms
            && self.pre_nms_top_k == other.pre_nms_top_k
            && self.max_det == other.max_det
            && self.normalized == other.normalized
            && self.input_dims == other.input_dims
            && self.multi_label == other.multi_label
            && self.decode_program.is_some() == other.decode_program.is_some()
            && self.per_scale.is_some() == other.per_scale.is_some()
    }
}

impl Clone for Decoder {
    /// Cloning a `Decoder` preserves the legacy decode path
    /// (`decode_program`) but drops the per-scale fast path:
    /// `PerScaleDecoder` owns mutable per-frame scratch buffers and is
    /// not `Clone`. Decoders built from a per-scale schema should be
    /// rebuilt via [`DecoderBuilder`] rather than cloned to preserve the
    /// fast path; cloning is intended for tests and rare configs.
    fn clone(&self) -> Self {
        Self {
            model_type: self.model_type.clone(),
            iou_threshold: self.iou_threshold,
            score_threshold: self.score_threshold,
            nms: self.nms,
            pre_nms_top_k: self.pre_nms_top_k,
            max_det: self.max_det,
            normalized: self.normalized,
            input_dims: self.input_dims,
            multi_label: self.multi_label,
            multi_label_source: self.multi_label_source,
            tracked_multi_label_warned: std::sync::atomic::AtomicBool::new(false),
            decode_program: self.decode_program.clone(),
            per_scale: None,
        }
    }
}

#[derive(Debug)]
pub(crate) enum ArrayViewDQuantized<'a> {
    UInt8(ArrayViewD<'a, u8>),
    Int8(ArrayViewD<'a, i8>),
    UInt16(ArrayViewD<'a, u16>),
    Int16(ArrayViewD<'a, i16>),
    UInt32(ArrayViewD<'a, u32>),
    Int32(ArrayViewD<'a, i32>),
}

impl<'a, D> From<ArrayView<'a, u8, D>> for ArrayViewDQuantized<'a>
where
    D: Dimension,
{
    fn from(arr: ArrayView<'a, u8, D>) -> Self {
        Self::UInt8(arr.into_dyn())
    }
}

impl<'a, D> From<ArrayView<'a, i8, D>> for ArrayViewDQuantized<'a>
where
    D: Dimension,
{
    fn from(arr: ArrayView<'a, i8, D>) -> Self {
        Self::Int8(arr.into_dyn())
    }
}

impl<'a, D> From<ArrayView<'a, u16, D>> for ArrayViewDQuantized<'a>
where
    D: Dimension,
{
    fn from(arr: ArrayView<'a, u16, D>) -> Self {
        Self::UInt16(arr.into_dyn())
    }
}

impl<'a, D> From<ArrayView<'a, i16, D>> for ArrayViewDQuantized<'a>
where
    D: Dimension,
{
    fn from(arr: ArrayView<'a, i16, D>) -> Self {
        Self::Int16(arr.into_dyn())
    }
}

impl<'a, D> From<ArrayView<'a, u32, D>> for ArrayViewDQuantized<'a>
where
    D: Dimension,
{
    fn from(arr: ArrayView<'a, u32, D>) -> Self {
        Self::UInt32(arr.into_dyn())
    }
}

impl<'a, D> From<ArrayView<'a, i32, D>> for ArrayViewDQuantized<'a>
where
    D: Dimension,
{
    fn from(arr: ArrayView<'a, i32, D>) -> Self {
        Self::Int32(arr.into_dyn())
    }
}

impl<'a> ArrayViewDQuantized<'a> {
    /// Returns the shape of the underlying array.
    pub(crate) fn shape(&self) -> &[usize] {
        match self {
            ArrayViewDQuantized::UInt8(a) => a.shape(),
            ArrayViewDQuantized::Int8(a) => a.shape(),
            ArrayViewDQuantized::UInt16(a) => a.shape(),
            ArrayViewDQuantized::Int16(a) => a.shape(),
            ArrayViewDQuantized::UInt32(a) => a.shape(),
            ArrayViewDQuantized::Int32(a) => a.shape(),
        }
    }
}

/// WARNING: Do NOT nest `with_quantized!` calls. Each level multiplies
/// monomorphized code paths by 6 (one per integer variant), so nesting
/// N levels deep produces 6^N instantiations.
///
/// Instead, dequantize each tensor sequentially with `dequant_3d!`/`dequant_4d!`
/// (6*N paths) or split into independent phases that each nest at most 2 levels.
macro_rules! with_quantized {
    ($x:expr, $var:ident, $body:expr) => {
        match $x {
            ArrayViewDQuantized::UInt8(x) => {
                let $var = x;
                $body
            }
            ArrayViewDQuantized::Int8(x) => {
                let $var = x;
                $body
            }
            ArrayViewDQuantized::UInt16(x) => {
                let $var = x;
                $body
            }
            ArrayViewDQuantized::Int16(x) => {
                let $var = x;
                $body
            }
            ArrayViewDQuantized::UInt32(x) => {
                let $var = x;
                $body
            }
            ArrayViewDQuantized::Int32(x) => {
                let $var = x;
                $body
            }
        }
    };
}

mod builder;
mod helpers;
mod merge;
mod per_scale_bridge;
mod postprocess;
mod tensor_bridge;
mod tests;

pub use builder::{DecoderBuilder, DEFAULT_PRE_NMS_TOP_K, MULTI_LABEL_PRE_NMS_TOP_K};
pub use config::{ConfigOutput, ConfigOutputRef, ConfigOutputs};

impl Decoder {
    /// Static label identifying which dispatch path `decode` / `decode_proto`
    /// will take, used as a tracing-span attribute. Lets profiling tools
    /// distinguish `per_scale` (the fast path), `decode_program` (schema-v2
    /// merge), and `legacy` (config-driven) without requiring callers to
    /// inspect the model.
    fn decode_path_label(&self) -> &'static str {
        if self.per_scale.is_some() {
            "per_scale"
        } else if self.decode_program.is_some() {
            "decode_program"
        } else {
            "legacy"
        }
    }

    /// Whether [`Decoder::decode`] and [`Decoder::decode_proto`] emit one box
    /// per class above the score threshold instead of one per anchor.
    ///
    /// [`Self::decode_for_tracking`], and `Decoder::decode_tracked` /
    /// `Decoder::decode_proto_tracked` (behind the `tracker` feature), ignore
    /// this and always use one label per box.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use edgefirst_decoder::{DecoderBuilder, DecoderResult};
    /// # fn main() -> DecoderResult<()> {
    /// #    let config_yaml = edgefirst_bench::testdata::read_to_string("modelpack_split.yaml").to_string();
    ///     let decoder = DecoderBuilder::default()
    ///         .with_config_yaml_str(config_yaml)
    ///         .with_multi_label(true)
    ///         .build()?;
    ///     assert!(decoder.multi_label());
    /// #    Ok(())
    /// # }
    /// ```
    pub fn multi_label(&self) -> bool {
        self.multi_label
    }

    /// The pre-NMS cap a decode uses: the explicit
    /// [`pre_nms_top_k`](Self::pre_nms_top_k) when set, else
    /// [`MULTI_LABEL_PRE_NMS_TOP_K`] for a multi-label decode and
    /// [`DEFAULT_PRE_NMS_TOP_K`] for an argmax one. `0` means unbounded.
    ///
    /// Pass [`multi_label()`](Self::multi_label) for what `decode` /
    /// `decode_proto` use, and `false` for the tracking entry points, which
    /// always decode argmax.
    ///
    /// # Examples
    /// ```rust
    /// # use edgefirst_decoder::{DecoderBuilder, DecoderResult};
    /// # fn main() -> DecoderResult<()> {
    /// # let config_json = edgefirst_bench::testdata::read_to_string("modelpack_split.json").to_string();
    /// let mut decoder = DecoderBuilder::new()
    ///     .with_config_json_str(config_json)
    ///     .with_multi_label(true)
    ///     .build()?;
    /// assert_eq!(decoder.pre_nms_top_k, None);
    /// assert_eq!(decoder.pre_nms_top_k_for(true), 30_000);
    /// assert_eq!(decoder.pre_nms_top_k_for(false), 300);
    /// decoder.pre_nms_top_k = Some(30_000);
    /// assert_eq!(decoder.pre_nms_top_k_for(false), 30_000);
    /// # Ok(())
    /// # }
    /// ```
    pub fn pre_nms_top_k_for(&self, multi_label: bool) -> usize {
        match self.pre_nms_top_k {
            Some(k) => k,
            None if multi_label => MULTI_LABEL_PRE_NMS_TOP_K,
            None => DEFAULT_PRE_NMS_TOP_K,
        }
    }

    /// Log, the first time this decoder decodes for tracking with
    /// multi-label enabled, that tracking ignores it. Returns whether this
    /// call logged.
    pub(crate) fn warn_once_tracked_multi_label(&self) -> bool {
        if !self.multi_label
            || self
                .tracked_multi_label_warned
                .swap(true, std::sync::atomic::Ordering::Relaxed)
        {
            return false;
        }
        tracing::warn!(
            source = ?self.multi_label_source,
            "multi_label is ignored when decoding for tracking; one label per box"
        );
        true
    }

    /// This function returns the parsed model type of the decoder.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use edgefirst_decoder::{DecoderBuilder, DecoderResult, configs::ModelType};
    /// # fn main() -> DecoderResult<()> {
    /// #    let config_yaml = edgefirst_bench::testdata::read_to_string("modelpack_split.yaml").to_string();
    ///     let decoder = DecoderBuilder::default()
    ///         .with_config_yaml_str(config_yaml)
    ///         .build()?;
    ///     assert!(matches!(
    ///         decoder.model_type(),
    ///         ModelType::ModelPackDetSplit { .. }
    ///     ));
    /// #    Ok(())
    /// # }
    /// ```
    pub fn model_type(&self) -> &ModelType {
        &self.model_type
    }

    /// Returns the coordinate format of the boxes the decoder emits to
    /// the caller.
    ///
    /// - `Some(true)`: Boxes are in normalized `[0, 1]` coordinates
    /// - `Some(false)`: Boxes are in pixel coordinates relative to the
    ///   model input
    /// - `None`: Unknown, caller must infer (e.g., check if any coordinate
    ///   > 1.0)
    ///
    /// This describes the **post-decode** coordinate space, not the raw
    /// schema annotation. The decoder applies EDGEAI-1303 normalization
    /// (dividing bbox channels by `(input_w, input_h)`) on a per-path
    /// basis, not unconditionally. Four paths are known to invoke the
    /// helper uniformly across all of their entry points (`decode`,
    /// `decode_proto`, and — where applicable — `decode_tracked` and
    /// `decode_tracked_proto`):
    ///
    /// 1. The **per-scale fast path** (DFL/LTRB → dist2bbox → sigmoid),
    ///    which emits pixel-space boxes by design and always normalizes
    ///    before returning.
    /// 2. [`ModelType::YoloSegDet`](crate::configs::ModelType::YoloSegDet), whose
    ///    quantized and float, tracked and untracked, masks and proto
    ///    variants each call the helper after NMS.
    /// 3. [`ModelType::YoloSplitSegDet`](crate::configs::ModelType::YoloSplitSegDet),
    ///    aligned across `decode`, `decode_proto`, `decode_tracked`,
    ///    and `decode_tracked_proto` for both quantized and float
    ///    variants.
    /// 4. [`ModelType::YoloSegDet2Way`](crate::configs::ModelType::YoloSegDet2Way),
    ///    aligned across the same four entry points and both element
    ///    type variants.
    ///
    /// When any of those paths is active and the schema declares
    /// `normalized: false` with valid [`input_dims`](Self::input_dims),
    /// this accessor reports `Some(true)` to match what the caller
    /// actually receives.
    ///
    /// The remaining model types still surface the raw schema flag
    /// because their post-decode contract differs:
    /// [`ModelType::YoloDet`](crate::configs::ModelType::YoloDet) and
    /// [`ModelType::YoloSplitDet`](crate::configs::ModelType::YoloSplitDet)
    /// (detection-only, no protobox crop coupling), the
    /// `YoloEndToEnd*` family (model embeds its own NMS and emits its
    /// own coordinate space), and the `ModelPack*` family (separate
    /// model conventions). For those, this accessor returns
    /// `self.normalized` verbatim and leaves it to the caller to
    /// handle pixel-space output explicitly (e.g. divide by
    /// `input_dims()` themselves).
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use edgefirst_decoder::{DecoderBuilder, DecoderResult};
    /// # fn main() -> DecoderResult<()> {
    /// #    let config_yaml = edgefirst_bench::testdata::read_to_string("modelpack_split.yaml").to_string();
    ///     let decoder = DecoderBuilder::default()
    ///         .with_config_yaml_str(config_yaml)
    ///         .build()?;
    ///     // Config doesn't specify normalized, so it's None
    ///     assert!(decoder.normalized_boxes().is_none());
    /// #    Ok(())
    /// # }
    /// ```
    pub fn normalized_boxes(&self) -> Option<bool> {
        // Four paths invoke `yolo::maybe_normalize_boxes_in_place`
        // uniformly across every entry point that can reach them:
        //   - the per-scale fast path (always normalizes by design),
        //   - `ModelType::YoloSegDet` (helper fires in
        //     `decode`/`decode_proto` via `yolo::impl_yolo_segdet_*` and
        //     in `decode_tracked`/`decode_tracked_proto` via the
        //     `process_tracked_yolo_segmentation!` macro and
        //     `process_tracked_yolo_segdet_float`),
        //   - `ModelType::YoloSplitSegDet` (helper fires in
        //     `decode_yolo_split_segdet_*`, `impl_yolo_split_segdet_*`,
        //     `process_tracked_yolo_segmentation_split!`, and
        //     `process_tracked_yolo_segdet_split_float`), and
        //   - `ModelType::YoloSegDet2Way` (helper fires in
        //     `decode_yolo_segdet_2way_*`, the float decode routes
        //     through `impl_yolo_split_segdet_float*`,
        //     `process_tracked_yolo_segmentation_2way!`, and the
        //     inline tracked-2way float helpers).
        // For those, `normalized == Some(false)` with valid `input_dims`
        // upgrades to a post-decode `Some(true)`. Other paths invoke
        // the helper inconsistently across `ModelType` variants and
        // tracked/proto entry points — surface the raw schema flag
        // there and let callers handle pixel-space output explicitly.
        if self.per_scale.is_some() || self.legacy_path_normalizes_uniformly() {
            match (self.normalized, self.input_dims) {
                (Some(true), _) => Some(true),
                (Some(false), Some((w, h))) if w != 0 && h != 0 => Some(true),
                (Some(false), _) => Some(false),
                (None, _) => None,
            }
        } else {
            self.normalized
        }
    }

    /// Returns true for legacy `ModelType` dispatch paths that are known
    /// to call `yolo::maybe_normalize_boxes_in_place` on every entry
    /// point (`decode`, `decode_proto`, `decode_tracked`,
    /// `decode_tracked_proto`, both quantized and float variants).
    ///
    /// Used by [`normalized_boxes`](Self::normalized_boxes) to gate the
    /// pixel→normalized upgrade for non-per-scale model types whose
    /// post-decode contract matches the per-scale path. Extend this
    /// list as additional `ModelType` variants are brought into
    /// uniform-normalization alignment.
    fn legacy_path_normalizes_uniformly(&self) -> bool {
        matches!(
            self.model_type,
            ModelType::YoloSegDet { .. }
                | ModelType::YoloSplitSegDet { .. }
                | ModelType::YoloSegDet2Way { .. }
        )
    }

    /// Model input dimensions `(width, height)` captured from the
    /// schema's `input.shape` / `input.dshape`, or `None` when the
    /// schema did not declare an input spec (e.g. flat YAML configs
    /// or `DecoderBuilder::add_output(...)` programmatic builds).
    ///
    /// Drives EDGEAI-1303 normalization on the paths that invoke the
    /// helper uniformly: when the schema declares pixel-space outputs
    /// and `input_dims()` is `Some((w, h))`, the per-scale bridge and
    /// the `ModelType::YoloSegDet`, `ModelType::YoloSplitSegDet`, and
    /// `ModelType::YoloSegDet2Way` dispatch paths divide post-NMS
    /// bbox coordinates by `(w, h)` so they enter the canonical
    /// `[0, 1]` range before mask cropping / tracker dispatch, and
    /// [`normalized_boxes`](Self::normalized_boxes) reports
    /// `Some(true)` to match. The remaining legacy `ModelType`
    /// dispatch paths (detection-only `YoloDet`/`YoloSplitDet`, the
    /// `YoloEndToEnd*` family, and the `ModelPack*` family) do not
    /// apply this division — see
    /// [`normalized_boxes`](Self::normalized_boxes) for the per-path
    /// contract. The legacy `protobox` `> 2.0` reject acts as a safety
    /// net for paths that emit pixel-space coordinates.
    ///
    /// # Examples
    ///
    /// ```rust
    /// # use edgefirst_decoder::{schema::SchemaV2, DecoderBuilder, DecoderResult};
    /// # fn main() -> DecoderResult<()> {
    ///     let json = r#"{
    ///         "schema_version": 2,
    ///         "nms": "class_agnostic",
    ///         "input": {
    ///             "shape": [1, 640, 640, 3],
    ///             "dshape": [{"batch": 1}, {"height": 640}, {"width": 640}, {"num_features": 3}]
    ///         },
    ///         "outputs": [{
    ///             "name": "out", "type": "detection",
    ///             "shape": [1, 38, 256],
    ///             "dshape": [{"batch": 1}, {"num_features": 38}, {"num_boxes": 256}],
    ///             "decoder": "ultralytics", "encoding": "direct", "normalized": false
    ///         }]
    ///     }"#;
    ///     let schema: SchemaV2 = serde_json::from_str(json).unwrap();
    ///     let decoder = DecoderBuilder::default().with_schema(schema).build()?;
    ///     assert_eq!(decoder.input_dims(), Some((640, 640)));
    /// #   Ok(())
    /// # }
    /// ```
    pub fn input_dims(&self) -> Option<(usize, usize)> {
        self.input_dims
    }

    /// Decode quantized model outputs into detection boxes and segmentation
    /// masks. The quantized outputs can be of u8, i8, u16, i16, u32, or i32
    /// types. Clears the provided output vectors before populating them.
    ///
    /// Test-only: calls [`Self::decode_quantized_impl`] with the decoder's
    /// own multi-label setting.
    #[cfg(test)]
    pub(crate) fn decode_quantized(
        &self,
        outputs: &[ArrayViewDQuantized],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
    ) -> Result<(), DecoderError> {
        self.decode_quantized_impl(outputs, output_boxes, output_masks, self.multi_label)
    }

    /// Dispatch with an explicit multi-label setting; tracked decode passes `false`.
    pub(crate) fn decode_quantized_impl(
        &self,
        outputs: &[ArrayViewDQuantized],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
        multi_label: bool,
    ) -> Result<(), DecoderError> {
        output_boxes.clear();
        output_masks.clear();
        match &self.model_type {
            ModelType::ModelPackSegDet {
                boxes,
                scores,
                segmentation,
            } => {
                self.decode_modelpack_det_quantized(
                    outputs,
                    boxes,
                    scores,
                    multi_label,
                    output_boxes,
                )?;
                self.decode_modelpack_seg_quantized(outputs, segmentation, output_masks)
            }
            ModelType::ModelPackSegDetSplit {
                detection,
                segmentation,
            } => {
                self.decode_modelpack_det_split_quantized(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
                self.decode_modelpack_seg_quantized(outputs, segmentation, output_masks)
            }
            ModelType::ModelPackDet { boxes, scores } => self.decode_modelpack_det_quantized(
                outputs,
                boxes,
                scores,
                multi_label,
                output_boxes,
            ),
            ModelType::ModelPackDetSplit { detection } => self
                .decode_modelpack_det_split_quantized(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                ),
            ModelType::ModelPackSeg { segmentation } => {
                self.decode_modelpack_seg_quantized(outputs, segmentation, output_masks)
            }
            ModelType::YoloDet { boxes } => {
                self.decode_yolo_det_quantized(outputs, boxes, multi_label, output_boxes)
            }
            ModelType::YoloSegDet { boxes, protos } => self.decode_yolo_segdet_quantized(
                outputs,
                boxes,
                protos,
                multi_label,
                output_boxes,
                output_masks,
            ),
            ModelType::YoloSplitDet { boxes, scores } => self.decode_yolo_split_det_quantized(
                outputs,
                boxes,
                scores,
                multi_label,
                output_boxes,
            ),
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => self.decode_yolo_split_segdet_quantized(
                outputs,
                boxes,
                scores,
                mask_coeff,
                protos,
                multi_label,
                output_boxes,
                output_masks,
            ),
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => self.decode_yolo_segdet_2way_quantized(
                outputs,
                boxes,
                mask_coeff,
                protos,
                multi_label,
                output_boxes,
                output_masks,
            ),
            ModelType::YoloEndToEndDet { boxes } => {
                self.decode_yolo_end_to_end_det_quantized(outputs, boxes, output_boxes)
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => self
                .decode_yolo_end_to_end_segdet_quantized(
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_masks,
                ),
            ModelType::YoloSplitEndToEndDet {
                boxes,
                scores,
                classes,
            } => self.decode_yolo_split_end_to_end_det_quantized(
                outputs,
                boxes,
                scores,
                classes,
                output_boxes,
            ),
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => self.decode_yolo_split_end_to_end_segdet_quantized(
                outputs,
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
                output_boxes,
                output_masks,
            ),
            ModelType::PerScale => Err(DecoderError::Internal(
                "per-scale path must be intercepted before ModelType dispatch".into(),
            )),
        }
    }

    /// Decode floating point model outputs into detection boxes and
    /// segmentation masks. Clears the provided output vectors before
    /// populating them.
    ///
    /// Test-only: calls [`Self::decode_float_impl`] with the decoder's own
    /// multi-label setting.
    #[cfg(test)]
    pub(crate) fn decode_float<T>(
        &self,
        outputs: &[ArrayViewD<T>],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
    ) -> Result<(), DecoderError>
    where
        T: Float + AsPrimitive<f32> + AsPrimitive<u8> + Send + Sync + 'static,
        f32: AsPrimitive<T>,
    {
        self.decode_float_impl(outputs, output_boxes, output_masks, self.multi_label)
    }

    /// Dispatch with an explicit multi-label setting; tracked decode passes `false`.
    pub(crate) fn decode_float_impl<T>(
        &self,
        outputs: &[ArrayViewD<T>],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
        multi_label: bool,
    ) -> Result<(), DecoderError>
    where
        T: Float + AsPrimitive<f32> + AsPrimitive<u8> + Send + Sync + 'static,
        f32: AsPrimitive<T>,
    {
        output_boxes.clear();
        output_masks.clear();
        match &self.model_type {
            ModelType::ModelPackSegDet {
                boxes,
                scores,
                segmentation,
            } => {
                self.decode_modelpack_det_float(outputs, boxes, scores, multi_label, output_boxes)?;
                self.decode_modelpack_seg_float(outputs, segmentation, output_masks)?;
            }
            ModelType::ModelPackSegDetSplit {
                detection,
                segmentation,
            } => {
                self.decode_modelpack_det_split_float(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
                self.decode_modelpack_seg_float(outputs, segmentation, output_masks)?;
            }
            ModelType::ModelPackDet { boxes, scores } => {
                self.decode_modelpack_det_float(outputs, boxes, scores, multi_label, output_boxes)?;
            }
            ModelType::ModelPackDetSplit { detection } => {
                self.decode_modelpack_det_split_float(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
            }
            ModelType::ModelPackSeg { segmentation } => {
                self.decode_modelpack_seg_float(outputs, segmentation, output_masks)?;
            }
            ModelType::YoloDet { boxes } => {
                self.decode_yolo_det_float(outputs, boxes, multi_label, output_boxes)?;
            }
            ModelType::YoloSegDet { boxes, protos } => {
                self.decode_yolo_segdet_float(
                    outputs,
                    boxes,
                    protos,
                    multi_label,
                    output_boxes,
                    output_masks,
                )?;
            }
            ModelType::YoloSplitDet { boxes, scores } => {
                self.decode_yolo_split_det_float(
                    outputs,
                    boxes,
                    scores,
                    multi_label,
                    output_boxes,
                )?;
            }
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => {
                self.decode_yolo_split_segdet_float(
                    outputs,
                    boxes,
                    scores,
                    mask_coeff,
                    protos,
                    multi_label,
                    output_boxes,
                    output_masks,
                )?;
            }
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => {
                self.decode_yolo_segdet_2way_float(
                    outputs,
                    boxes,
                    mask_coeff,
                    protos,
                    multi_label,
                    output_boxes,
                    output_masks,
                )?;
            }
            ModelType::YoloEndToEndDet { boxes } => {
                self.decode_yolo_end_to_end_det_float(outputs, boxes, output_boxes)?;
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => {
                self.decode_yolo_end_to_end_segdet_float(
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_masks,
                )?;
            }
            ModelType::YoloSplitEndToEndDet {
                boxes,
                scores,
                classes,
            } => {
                self.decode_yolo_split_end_to_end_det_float(
                    outputs,
                    boxes,
                    scores,
                    classes,
                    output_boxes,
                )?;
            }
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => {
                self.decode_yolo_split_end_to_end_segdet_float(
                    outputs,
                    boxes,
                    scores,
                    classes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_masks,
                )?;
            }
            ModelType::PerScale => {
                return Err(DecoderError::Internal(
                    "per-scale path must be intercepted before ModelType dispatch".into(),
                ));
            }
        }
        Ok(())
    }

    /// Decodes quantized model outputs into detection boxes, returning raw
    /// `ProtoData` for segmentation models instead of materialized masks.
    ///
    /// Returns `Ok(None)` for detection-only and ModelPack models (detections
    /// are still decoded into `output_boxes`). Returns `Ok(Some(ProtoData))`
    /// for YOLO segmentation models.
    ///
    /// Test-only: calls [`Self::decode_quantized_proto_impl`] with the
    /// decoder's own multi-label setting.
    #[cfg(test)]
    pub(crate) fn decode_quantized_proto(
        &self,
        outputs: &[ArrayViewDQuantized],
        output_boxes: &mut Vec<DetectBox>,
    ) -> Result<Option<ProtoData>, DecoderError> {
        self.decode_quantized_proto_impl(outputs, output_boxes, self.multi_label)
    }

    /// Dispatch with an explicit multi-label setting; tracked decode passes `false`.
    pub(crate) fn decode_quantized_proto_impl(
        &self,
        outputs: &[ArrayViewDQuantized],
        output_boxes: &mut Vec<DetectBox>,
        multi_label: bool,
    ) -> Result<Option<ProtoData>, DecoderError> {
        output_boxes.clear();
        match &self.model_type {
            // Detection-only variants: decode boxes, return None for proto data.
            ModelType::ModelPackDet { boxes, scores } => {
                self.decode_modelpack_det_quantized(
                    outputs,
                    boxes,
                    scores,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::ModelPackDetSplit { detection } => {
                self.decode_modelpack_det_split_quantized(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::YoloDet { boxes } => {
                self.decode_yolo_det_quantized(outputs, boxes, multi_label, output_boxes)?;
                Ok(None)
            }
            ModelType::YoloSplitDet { boxes, scores } => {
                self.decode_yolo_split_det_quantized(
                    outputs,
                    boxes,
                    scores,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::YoloEndToEndDet { boxes } => {
                self.decode_yolo_end_to_end_det_quantized(outputs, boxes, output_boxes)?;
                Ok(None)
            }
            ModelType::YoloSplitEndToEndDet {
                boxes,
                scores,
                classes,
            } => {
                self.decode_yolo_split_end_to_end_det_quantized(
                    outputs,
                    boxes,
                    scores,
                    classes,
                    output_boxes,
                )?;
                Ok(None)
            }
            // ModelPack seg/segdet variants have no YOLO proto data.
            ModelType::ModelPackSegDet { boxes, scores, .. } => {
                self.decode_modelpack_det_quantized(
                    outputs,
                    boxes,
                    scores,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::ModelPackSegDetSplit { detection, .. } => {
                self.decode_modelpack_det_split_quantized(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::ModelPackSeg { .. } => Ok(None),

            ModelType::YoloSegDet { boxes, protos } => {
                let proto = self.decode_yolo_segdet_quantized_proto(
                    outputs,
                    boxes,
                    protos,
                    multi_label,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_yolo_split_segdet_quantized_proto(
                    outputs,
                    boxes,
                    scores,
                    mask_coeff,
                    protos,
                    multi_label,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_yolo_segdet_2way_quantized_proto(
                    outputs,
                    boxes,
                    mask_coeff,
                    protos,
                    multi_label,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => {
                let proto = self.decode_yolo_end_to_end_segdet_quantized_proto(
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_yolo_split_end_to_end_segdet_quantized_proto(
                    outputs,
                    boxes,
                    scores,
                    classes,
                    mask_coeff,
                    protos,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::PerScale => Err(DecoderError::Internal(
                "per-scale path must be intercepted before ModelType dispatch".into(),
            )),
        }
    }

    /// Decodes floating-point model outputs into detection boxes, returning
    /// raw `ProtoData` for segmentation models instead of materialized masks.
    ///
    /// Returns `Ok(None)` for detection-only and ModelPack models (detections
    /// are still decoded into `output_boxes`). Returns `Ok(Some(ProtoData))`
    /// for YOLO segmentation models.
    ///
    /// Test-only: calls [`Self::decode_float_proto_impl`] with the decoder's
    /// own multi-label setting.
    #[cfg(test)]
    pub(crate) fn decode_float_proto<T>(
        &self,
        outputs: &[ArrayViewD<T>],
        output_boxes: &mut Vec<DetectBox>,
    ) -> Result<Option<ProtoData>, DecoderError>
    where
        T: Float + AsPrimitive<f32> + AsPrimitive<u8> + Send + Sync + crate::yolo::FloatProtoElem,
        f32: AsPrimitive<T>,
    {
        self.decode_float_proto_impl(outputs, output_boxes, self.multi_label)
    }

    /// Dispatch with an explicit multi-label setting; tracked decode passes `false`.
    pub(crate) fn decode_float_proto_impl<T>(
        &self,
        outputs: &[ArrayViewD<T>],
        output_boxes: &mut Vec<DetectBox>,
        multi_label: bool,
    ) -> Result<Option<ProtoData>, DecoderError>
    where
        T: Float + AsPrimitive<f32> + AsPrimitive<u8> + Send + Sync + crate::yolo::FloatProtoElem,
        f32: AsPrimitive<T>,
    {
        output_boxes.clear();
        match &self.model_type {
            // Detection-only variants: decode boxes, return None for proto data.
            ModelType::ModelPackDet { boxes, scores } => {
                self.decode_modelpack_det_float(outputs, boxes, scores, multi_label, output_boxes)?;
                Ok(None)
            }
            ModelType::ModelPackDetSplit { detection } => {
                self.decode_modelpack_det_split_float(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::YoloDet { boxes } => {
                self.decode_yolo_det_float(outputs, boxes, multi_label, output_boxes)?;
                Ok(None)
            }
            ModelType::YoloSplitDet { boxes, scores } => {
                self.decode_yolo_split_det_float(
                    outputs,
                    boxes,
                    scores,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::YoloEndToEndDet { boxes } => {
                self.decode_yolo_end_to_end_det_float(outputs, boxes, output_boxes)?;
                Ok(None)
            }
            ModelType::YoloSplitEndToEndDet {
                boxes,
                scores,
                classes,
            } => {
                self.decode_yolo_split_end_to_end_det_float(
                    outputs,
                    boxes,
                    scores,
                    classes,
                    output_boxes,
                )?;
                Ok(None)
            }
            // ModelPack seg/segdet variants have no YOLO proto data.
            ModelType::ModelPackSegDet { boxes, scores, .. } => {
                self.decode_modelpack_det_float(outputs, boxes, scores, multi_label, output_boxes)?;
                Ok(None)
            }
            ModelType::ModelPackSegDetSplit { detection, .. } => {
                self.decode_modelpack_det_split_float(
                    outputs,
                    detection,
                    multi_label,
                    output_boxes,
                )?;
                Ok(None)
            }
            ModelType::ModelPackSeg { .. } => Ok(None),

            ModelType::YoloSegDet { boxes, protos } => {
                let proto = self.decode_yolo_segdet_float_proto(
                    outputs,
                    boxes,
                    protos,
                    multi_label,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_yolo_split_segdet_float_proto(
                    outputs,
                    boxes,
                    scores,
                    mask_coeff,
                    protos,
                    multi_label,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_yolo_segdet_2way_float_proto(
                    outputs,
                    boxes,
                    mask_coeff,
                    protos,
                    multi_label,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => {
                let proto = self.decode_yolo_end_to_end_segdet_float_proto(
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_yolo_split_end_to_end_segdet_float_proto(
                    outputs,
                    boxes,
                    scores,
                    classes,
                    mask_coeff,
                    protos,
                    output_boxes,
                )?;
                Ok(Some(proto))
            }
            ModelType::PerScale => Err(DecoderError::Internal(
                "per-scale path must be intercepted before ModelType dispatch".into(),
            )),
        }
    }

    // ========================================================================
    // TensorDyn-based public API
    // ========================================================================

    /// Decode model outputs into detection boxes and segmentation masks.
    ///
    /// This is the primary decode API. Accepts `TensorDyn` outputs directly
    /// from model inference. Automatically dispatches to quantized or float
    /// paths based on the tensor dtype.
    ///
    /// # Arguments
    ///
    /// * `outputs` - Tensor outputs from model inference
    /// * `output_boxes` - Destination for decoded detection boxes (cleared first)
    /// * `output_masks` - Destination for decoded segmentation masks (cleared first)
    ///
    /// # `output_boxes` / `output_masks` capacity
    ///
    /// The capacity of the supplied `Vec`s is **only** an allocation hint —
    /// it is **not** a cap on the number of detections returned. The
    /// post-NMS detection count is bounded by [`Decoder::max_det`] (set
    /// via [`DecoderBuilder::with_max_det`], default `300`). Passing
    /// `Vec::new()` (capacity 0) returns up to `max_det` detections;
    /// pre-allocating with [`Vec::with_capacity`] only avoids the
    /// reallocation when the decoder grows the buffer.
    ///
    /// # Errors
    ///
    /// Returns `DecoderError` if tensor mapping fails, dtypes are unsupported,
    /// or the outputs don't match the decoder's model configuration.
    pub fn decode(
        &self,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
    ) -> Result<(), DecoderError> {
        self.decode_impl(outputs, output_boxes, output_masks, self.multi_label)
    }

    /// Decode with one label per box, whatever [`Self::multi_label`] says.
    ///
    /// Use this when the boxes feed an external tracker: trackers match on
    /// IoU only, so per-class duplicates of one anchor become phantom tracks.
    /// Logs a warning once per decoder when the decoder has multi-label
    /// enabled. `Decoder::decode_tracked` and `Decoder::decode_proto_tracked`
    /// (behind the `tracker` feature) apply the same rule. When the builder
    /// raised [`Self::pre_nms_top_k`] to [`MULTI_LABEL_PRE_NMS_TOP_K`] only
    /// because multi-label was on, this argmax decode uses
    /// [`DEFAULT_PRE_NMS_TOP_K`]; an explicit cap is used as given.
    ///
    /// # Errors
    ///
    /// The same as [`Self::decode`].
    pub fn decode_for_tracking(
        &self,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
    ) -> Result<(), DecoderError> {
        self.warn_once_tracked_multi_label();
        self.decode_impl(outputs, output_boxes, output_masks, false)
    }

    /// [`Self::decode`] with an explicit multi-label setting.
    fn decode_impl(
        &self,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
        multi_label: bool,
    ) -> Result<(), DecoderError> {
        let path = self.decode_path_label();
        let _span = tracing::trace_span!("decoder.decode", path = path, n_outputs = outputs.len())
            .entered();
        // Per-scale fast path — selected at builder time when the schema
        // declares per-scale children with DFL or LTRB encoding.
        if let Some(per_scale_mutex) = &self.per_scale {
            let mut ps = per_scale_mutex
                .lock()
                .map_err(|e| DecoderError::Internal(format!("per_scale mutex poisoned: {e}")))?;
            let decoded = ps.run(outputs)?;
            return per_scale_bridge::per_scale_to_masks(
                &decoded,
                output_boxes,
                output_masks,
                self.iou_threshold,
                self.score_threshold,
                self.nms,
                self.pre_nms_top_k_for(multi_label),
                self.max_det,
                self.normalized,
                self.input_dims,
                multi_label,
            );
        }

        // Schema v2 merge path: dequantize physical children into
        // logical float32 tensors, then feed through the float dispatch.
        if let Some(program) = &self.decode_program {
            let merged = program.execute(outputs)?;
            let views: Vec<_> = merged.iter().map(|a| a.view()).collect();
            return self.decode_float_impl(&views, output_boxes, output_masks, multi_label);
        }

        let mapped = tensor_bridge::map_tensors(outputs)?;
        match &mapped {
            tensor_bridge::MappedOutputs::Quantized(maps) => {
                let views = tensor_bridge::quantized_views(maps)?;
                self.decode_quantized_impl(&views, output_boxes, output_masks, multi_label)
            }
            tensor_bridge::MappedOutputs::Float16(maps) => {
                let views = tensor_bridge::f16_views(maps)?;
                self.decode_float_impl(&views, output_boxes, output_masks, multi_label)
            }
            tensor_bridge::MappedOutputs::Float32(maps) => {
                let views = tensor_bridge::f32_views(maps)?;
                self.decode_float_impl(&views, output_boxes, output_masks, multi_label)
            }
            tensor_bridge::MappedOutputs::Float64(maps) => {
                let views = tensor_bridge::f64_views(maps)?;
                self.decode_float_impl(&views, output_boxes, output_masks, multi_label)
            }
        }
    }

    /// Decode model outputs into detection boxes, returning raw proto data
    /// for segmentation models instead of materialized masks.
    ///
    /// Accepts `TensorDyn` outputs directly from model inference.
    /// Detections are always decoded into `output_boxes` regardless of model type.
    /// Returns `Ok(None)` for detection-only and ModelPack models.
    /// Returns `Ok(Some(ProtoData))` for YOLO segmentation models.
    ///
    /// # Arguments
    ///
    /// * `outputs` - Tensor outputs from model inference
    /// * `output_boxes` - Destination for decoded detection boxes (cleared first)
    ///
    /// # `output_boxes` capacity
    ///
    /// The capacity of `output_boxes` is **only** an allocation hint — it
    /// is **not** a cap on the number of detections returned. The
    /// post-NMS detection count is bounded by [`Decoder::max_det`] (set
    /// via [`DecoderBuilder::with_max_det`], default `300`). Passing
    /// `Vec::new()` (capacity 0) returns up to `max_det` detections.
    ///
    /// # Errors
    ///
    /// Returns `DecoderError` if tensor mapping fails, dtypes are unsupported,
    /// or the outputs don't match the decoder's model configuration.
    pub fn decode_proto(
        &self,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
    ) -> Result<Option<ProtoData>, DecoderError> {
        self.decode_proto_impl(outputs, output_boxes, self.multi_label)
    }

    /// [`Self::decode_proto`] with an explicit multi-label setting.
    fn decode_proto_impl(
        &self,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
        multi_label: bool,
    ) -> Result<Option<ProtoData>, DecoderError> {
        let path = self.decode_path_label();
        let _span = tracing::trace_span!(
            "decoder.decode_proto",
            path = path,
            n_outputs = outputs.len()
        )
        .entered();
        // Per-scale fast path — selected at builder time when the schema
        // declares per-scale children with DFL or LTRB encoding.
        if let Some(per_scale_mutex) = &self.per_scale {
            let mut ps = per_scale_mutex
                .lock()
                .map_err(|e| DecoderError::Internal(format!("per_scale mutex poisoned: {e}")))?;
            let decoded = ps.run(outputs)?;
            return per_scale_bridge::per_scale_to_proto_data(
                &decoded,
                output_boxes,
                self.iou_threshold,
                self.score_threshold,
                self.nms,
                self.pre_nms_top_k_for(multi_label),
                self.max_det,
                self.normalized,
                self.input_dims,
                multi_label,
            );
        }

        // Schema v2 merge path: dequantize physical children into
        // logical float32 tensors, then feed through the float dispatch.
        if let Some(program) = &self.decode_program {
            let merged = program.execute(outputs)?;
            let views: Vec<_> = merged.iter().map(|a| a.view()).collect();
            return self.decode_float_proto_impl(&views, output_boxes, multi_label);
        }

        let mapped = tensor_bridge::map_tensors(outputs)?;
        let result = match &mapped {
            tensor_bridge::MappedOutputs::Quantized(maps) => {
                let views = tensor_bridge::quantized_views(maps)?;
                self.decode_quantized_proto_impl(&views, output_boxes, multi_label)
            }
            tensor_bridge::MappedOutputs::Float16(maps) => {
                let views = tensor_bridge::f16_views(maps)?;
                self.decode_float_proto_impl(&views, output_boxes, multi_label)
            }
            tensor_bridge::MappedOutputs::Float32(maps) => {
                let views = tensor_bridge::f32_views(maps)?;
                self.decode_float_proto_impl(&views, output_boxes, multi_label)
            }
            tensor_bridge::MappedOutputs::Float64(maps) => {
                let views = tensor_bridge::f64_views(maps)?;
                self.decode_float_proto_impl(&views, output_boxes, multi_label)
            }
        };
        result
    }

    /// Run the per-scale pipeline and return pre-NMS buffers as owned f32.
    ///
    /// Test-only entry point used by the parity-fixture tests to compare
    /// HAL stage output against the NumPy reference's stage output
    /// without NMS ordering noise. Returns an error if the decoder
    /// isn't configured for per-scale decoding.
    #[doc(hidden)]
    pub fn _testing_run_per_scale_pre_nms(
        &self,
        outputs: &[&edgefirst_tensor::TensorDyn],
    ) -> Result<crate::per_scale::PreNmsCapture, crate::error::DecoderError> {
        let mutex = self.per_scale.as_ref().ok_or_else(|| {
            crate::error::DecoderError::Internal("decoder not configured for per-scale".into())
        })?;
        let mut ps = mutex.lock().map_err(|e| {
            crate::error::DecoderError::Internal(format!("per_scale mutex poisoned: {e}"))
        })?;
        // Drop the borrowed view immediately so we can reborrow buffers below.
        {
            ps.run(outputs)?;
        }
        let total_anchors = ps.plan.total_anchors;
        let num_classes = ps.plan.num_classes;
        let num_mc = ps.plan.num_mask_coefs;
        Ok(ps
            .buffers
            .snapshot_owned_f32(total_anchors, num_classes, num_mc))
    }
}

#[cfg(feature = "tracker")]
pub use edgefirst_tracker::TrackInfo;

#[cfg(feature = "tracker")]
pub use edgefirst_tracker::Tracker;

#[cfg(feature = "tracker")]
impl Decoder {
    /// Decode quantized model outputs into detection boxes and segmentation
    /// masks with tracking. Clears the provided output vectors before
    /// populating them.
    pub(crate) fn decode_tracked_quantized<TR: edgefirst_tracker::Tracker<DetectBox>>(
        &self,
        tracker: &mut TR,
        timestamp: u64,
        outputs: &[ArrayViewDQuantized],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
        output_tracks: &mut Vec<edgefirst_tracker::TrackInfo>,
    ) -> Result<(), DecoderError> {
        output_boxes.clear();
        output_masks.clear();
        output_tracks.clear();

        // yolo segdet variants require special handling to separate boxes that come from decoding vs active tracks.
        // Only boxes that come from decoding can be used for proto/mask generation.
        match &self.model_type {
            ModelType::YoloSegDet { boxes, protos } => self.decode_tracked_yolo_segdet_quantized(
                tracker,
                timestamp,
                outputs,
                boxes,
                protos,
                output_boxes,
                output_masks,
                output_tracks,
            ),
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => self.decode_tracked_yolo_split_segdet_quantized(
                tracker,
                timestamp,
                outputs,
                boxes,
                scores,
                mask_coeff,
                protos,
                output_boxes,
                output_masks,
                output_tracks,
            ),
            ModelType::YoloEndToEndSegDet { boxes, protos } => self
                .decode_tracked_yolo_end_to_end_segdet_quantized(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_masks,
                    output_tracks,
                ),
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => self.decode_tracked_yolo_split_end_to_end_segdet_quantized(
                tracker,
                timestamp,
                outputs,
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
                output_boxes,
                output_masks,
                output_tracks,
            ),
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => self.decode_tracked_yolo_segdet_2way_quantized(
                tracker,
                timestamp,
                outputs,
                boxes,
                mask_coeff,
                protos,
                output_boxes,
                output_masks,
                output_tracks,
            ),
            _ => {
                self.decode_quantized_impl(outputs, output_boxes, output_masks, false)?;
                Self::update_tracker(tracker, timestamp, output_boxes, output_tracks);
                Ok(())
            }
        }
    }

    /// This function decodes floating point model outputs into detection boxes
    /// and segmentation masks. Up to `max_det` boxes and
    /// masks will be decoded. The function clears the provided output
    /// vectors before populating them with the decoded results.
    ///
    /// This function returns an `Error` if the provided outputs don't
    /// match the configuration provided by the user when building the decoder.
    ///
    /// Any quantization information in the configuration will be ignored.
    pub(crate) fn decode_tracked_float<TR: edgefirst_tracker::Tracker<DetectBox>, T>(
        &self,
        tracker: &mut TR,
        timestamp: u64,
        outputs: &[ArrayViewD<T>],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
        output_tracks: &mut Vec<edgefirst_tracker::TrackInfo>,
    ) -> Result<(), DecoderError>
    where
        T: Float + AsPrimitive<f32> + AsPrimitive<u8> + Send + Sync + 'static,
        f32: AsPrimitive<T>,
    {
        output_boxes.clear();
        output_masks.clear();
        output_tracks.clear();
        match &self.model_type {
            ModelType::YoloSegDet { boxes, protos } => {
                self.decode_tracked_yolo_segdet_float(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )?;
            }
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => {
                self.decode_tracked_yolo_split_segdet_float(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    scores,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )?;
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => {
                self.decode_tracked_yolo_end_to_end_segdet_float(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )?;
            }
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => {
                self.decode_tracked_yolo_split_end_to_end_segdet_float(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    scores,
                    classes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )?;
            }
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => {
                self.decode_tracked_yolo_segdet_2way_float(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )?;
            }
            _ => {
                self.decode_float_impl(outputs, output_boxes, output_masks, false)?;
                Self::update_tracker(tracker, timestamp, output_boxes, output_tracks);
            }
        }
        Ok(())
    }

    /// Decodes quantized model outputs into detection boxes, returning raw
    /// `ProtoData` for segmentation models instead of materialized masks.
    ///
    /// Returns `Ok(None)` for detection-only and ModelPack models (use
    /// `decode_quantized` for those). Returns `Ok(Some(ProtoData))` for
    /// YOLO segmentation models.
    pub(crate) fn decode_tracked_quantized_proto<TR: edgefirst_tracker::Tracker<DetectBox>>(
        &self,
        tracker: &mut TR,
        timestamp: u64,
        outputs: &[ArrayViewDQuantized],
        output_boxes: &mut Vec<DetectBox>,
        output_tracks: &mut Vec<edgefirst_tracker::TrackInfo>,
    ) -> Result<Option<ProtoData>, DecoderError> {
        output_boxes.clear();
        output_tracks.clear();
        match &self.model_type {
            ModelType::YoloSegDet { boxes, protos } => {
                let proto = self.decode_tracked_yolo_segdet_quantized_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_tracked_yolo_split_segdet_quantized_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    scores,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_tracked_yolo_segdet_2way_quantized_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => {
                let proto = self.decode_tracked_yolo_end_to_end_segdet_quantized_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_tracked_yolo_split_end_to_end_segdet_quantized_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    scores,
                    classes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            // Non-seg variants: decode boxes via the non-proto path, then track.
            _ => {
                let mut masks = Vec::new();
                self.decode_quantized_impl(outputs, output_boxes, &mut masks, false)?;
                Self::update_tracker(tracker, timestamp, output_boxes, output_tracks);
                Ok(None)
            }
        }
    }

    /// Decodes floating-point model outputs into detection boxes, returning
    /// raw `ProtoData` for segmentation models instead of materialized masks.
    ///
    /// Detections are always decoded into `output_boxes` regardless of model type.
    /// Returns `Ok(None)` for detection-only and ModelPack models. Returns
    /// `Ok(Some(ProtoData))` for YOLO segmentation models.
    pub(crate) fn decode_tracked_float_proto<TR: edgefirst_tracker::Tracker<DetectBox>, T>(
        &self,
        tracker: &mut TR,
        timestamp: u64,
        outputs: &[ArrayViewD<T>],
        output_boxes: &mut Vec<DetectBox>,
        output_tracks: &mut Vec<edgefirst_tracker::TrackInfo>,
    ) -> Result<Option<ProtoData>, DecoderError>
    where
        T: Float + AsPrimitive<f32> + AsPrimitive<u8> + Send + Sync + crate::yolo::FloatProtoElem,
        f32: AsPrimitive<T>,
    {
        output_boxes.clear();
        output_tracks.clear();
        match &self.model_type {
            ModelType::YoloSegDet { boxes, protos } => {
                let proto = self.decode_tracked_yolo_segdet_float_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitSegDet {
                boxes,
                scores,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_tracked_yolo_split_segdet_float_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    scores,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSegDet2Way {
                boxes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_tracked_yolo_segdet_2way_float_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloEndToEndSegDet { boxes, protos } => {
                let proto = self.decode_tracked_yolo_end_to_end_segdet_float_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            ModelType::YoloSplitEndToEndSegDet {
                boxes,
                scores,
                classes,
                mask_coeff,
                protos,
            } => {
                let proto = self.decode_tracked_yolo_split_end_to_end_segdet_float_proto(
                    tracker,
                    timestamp,
                    outputs,
                    boxes,
                    scores,
                    classes,
                    mask_coeff,
                    protos,
                    output_boxes,
                    output_tracks,
                )?;
                Ok(Some(proto))
            }
            // Non-seg variants: decode boxes via the non-proto path, then track.
            _ => {
                let mut masks = Vec::new();
                self.decode_float_impl(outputs, output_boxes, &mut masks, false)?;
                Self::update_tracker(tracker, timestamp, output_boxes, output_tracks);
                Ok(None)
            }
        }
    }

    // ========================================================================
    // TensorDyn-based tracked public API
    // ========================================================================

    /// Decode model outputs with tracking.
    ///
    /// Accepts `TensorDyn` outputs directly from model inference. Automatically
    /// dispatches to quantized or float paths based on the tensor dtype, then
    /// updates the tracker with the decoded boxes.
    ///
    /// Always decodes one label per box, regardless of [`Self::multi_label`]:
    /// trackers match on IoU only, so per-class duplicates of one anchor would
    /// spawn phantom tracks. Logs a warning once per decoder when the decoder
    /// has multi-label enabled. Like [`Self::decode_for_tracking`], it uses
    /// the argmax default pre-NMS cap unless the cap was set explicitly.
    ///
    /// # Arguments
    ///
    /// * `tracker` - The tracker instance to update
    /// * `timestamp` - Current frame timestamp
    /// * `outputs` - Tensor outputs from model inference
    /// * `output_boxes` - Destination for decoded detection boxes (cleared first)
    /// * `output_masks` - Destination for decoded segmentation masks (cleared first)
    /// * `output_tracks` - Destination for track info (cleared first)
    ///
    /// # Errors
    ///
    /// Returns `DecoderError` if tensor mapping fails, dtypes are unsupported,
    /// or the outputs don't match the decoder's model configuration.
    pub fn decode_tracked<TR: edgefirst_tracker::Tracker<DetectBox>>(
        &self,
        tracker: &mut TR,
        timestamp: u64,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
        output_masks: &mut Vec<Segmentation>,
        output_tracks: &mut Vec<edgefirst_tracker::TrackInfo>,
    ) -> Result<(), DecoderError> {
        self.warn_once_tracked_multi_label();
        // Per-scale fast path: route via the basic decode then update the
        // tracker. The current implementation keeps the tracker integration simple; per-frame
        // decoupling between detection and tracking is preserved.
        if self.per_scale.is_some() {
            output_tracks.clear();
            self.decode_impl(outputs, output_boxes, output_masks, false)?;
            Self::update_tracker(tracker, timestamp, output_boxes, output_tracks);
            return Ok(());
        }

        let mapped = tensor_bridge::map_tensors(outputs)?;
        match &mapped {
            tensor_bridge::MappedOutputs::Quantized(maps) => {
                let views = tensor_bridge::quantized_views(maps)?;
                self.decode_tracked_quantized(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )
            }
            tensor_bridge::MappedOutputs::Float16(maps) => {
                let views = tensor_bridge::f16_views(maps)?;
                self.decode_tracked_float(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )
            }
            tensor_bridge::MappedOutputs::Float32(maps) => {
                let views = tensor_bridge::f32_views(maps)?;
                self.decode_tracked_float(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )
            }
            tensor_bridge::MappedOutputs::Float64(maps) => {
                let views = tensor_bridge::f64_views(maps)?;
                self.decode_tracked_float(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_masks,
                    output_tracks,
                )
            }
        }
    }

    /// Decode model outputs with tracking, returning raw proto data for
    /// segmentation models.
    ///
    /// Accepts `TensorDyn` outputs directly from model inference.
    /// Returns `Ok(None)` for detection-only and ModelPack models.
    /// Returns `Ok(Some(ProtoData))` for YOLO segmentation models.
    ///
    /// Always decodes one label per box, regardless of [`Self::multi_label`]:
    /// trackers match on IoU only, so per-class duplicates of one anchor would
    /// spawn phantom tracks. Logs a warning once per decoder when the decoder
    /// has multi-label enabled. Like [`Self::decode_for_tracking`], it uses
    /// the argmax default pre-NMS cap unless the cap was set explicitly.
    ///
    /// # Arguments
    ///
    /// * `tracker` - The tracker instance to update
    /// * `timestamp` - Current frame timestamp
    /// * `outputs` - Tensor outputs from model inference
    /// * `output_boxes` - Destination for decoded detection boxes (cleared first)
    /// * `output_tracks` - Destination for track info (cleared first)
    ///
    /// # Errors
    ///
    /// Returns `DecoderError` if tensor mapping fails, dtypes are unsupported,
    /// or the outputs don't match the decoder's model configuration.
    pub fn decode_proto_tracked<TR: edgefirst_tracker::Tracker<DetectBox>>(
        &self,
        tracker: &mut TR,
        timestamp: u64,
        outputs: &[&edgefirst_tensor::TensorDyn],
        output_boxes: &mut Vec<DetectBox>,
        output_tracks: &mut Vec<edgefirst_tracker::TrackInfo>,
    ) -> Result<Option<ProtoData>, DecoderError> {
        self.warn_once_tracked_multi_label();
        // Per-scale fast path: route via the basic decode_proto then
        // update the tracker on the resulting boxes.
        if self.per_scale.is_some() {
            output_tracks.clear();
            let proto = self.decode_proto_impl(outputs, output_boxes, false)?;
            Self::update_tracker(tracker, timestamp, output_boxes, output_tracks);
            return Ok(proto);
        }

        let mapped = tensor_bridge::map_tensors(outputs)?;
        match &mapped {
            tensor_bridge::MappedOutputs::Quantized(maps) => {
                let views = tensor_bridge::quantized_views(maps)?;
                self.decode_tracked_quantized_proto(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_tracks,
                )
            }
            tensor_bridge::MappedOutputs::Float16(maps) => {
                let views = tensor_bridge::f16_views(maps)?;
                self.decode_tracked_float_proto(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_tracks,
                )
            }
            tensor_bridge::MappedOutputs::Float32(maps) => {
                let views = tensor_bridge::f32_views(maps)?;
                self.decode_tracked_float_proto(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_tracks,
                )
            }
            tensor_bridge::MappedOutputs::Float64(maps) => {
                let views = tensor_bridge::f64_views(maps)?;
                self.decode_tracked_float_proto(
                    tracker,
                    timestamp,
                    &views,
                    output_boxes,
                    output_tracks,
                )
            }
        }
    }
}