edgefirst_decoder/

tiling.rs

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

//! SAHI-style tiled-inference postprocessing: lift per-tile detections to
//! full-frame coordinates and merge them across tiles.
//!
//! A high-resolution frame is covered by a uniform overlapping grid of tiles
//! (geometry lives in the `edgefirst-image` crate). Each tile is run through
//! the small tile-input model and decoded independently to normalized `[0,1]`
//! detections over the model input. This module lifts those to full-frame
//! pixels ([`lift_tile_boxes`]) and merges duplicates at tile seams
//! ([`merge_tiled_detections`]): a greedy, class-aware pass under the **IOS**
//! (intersection-over-smaller) match metric that, by default, **keeps the
//! highest-scoring box of each overlapping group unchanged** rather than
//! growing it ([`MergeMode::KeepBest`]). [`TiledFrameAccumulator`] is a streaming
//! collector so a pipelined runtime can push each tile's detections as
//! inference completes and finalize once the frame's last tile arrives.
//!
//! IOS matters because an object split across a tile overlap appears as two
//! partial boxes whose IoU is low but whose IoS is high, so IoS joins them
//! where IoU leaves duplicates.
//!
//! # Merge mode (affects mAP)
//!
//! The original GREEDYNMM merge replaced each matched group with its
//! **enclosing union** carrying the group's max score. On the Ocean Cleanup
//! ADIS 4K validation set (5823 frames, one evaluator; TOP2-836) that union
//! cost about **0.05 AP50 on every frame, tiled or not**: a whole frame with
//! plain NMS scored 0.491 AP50, the same predictions after the union merge
//! 0.437, and the same IoS-0.5 class-aware matching with the best box kept
//! unchanged 0.490; a 28-tile pipeline scored 0.500 with keep-best against
//! 0.442 with the union. Only ~5 % of boxes are touched, but a union inflates
//! a true positive past IoU 0.5 and swallows the small, low-score true
//! positives that lie mostly inside a larger same-class box. The seam case
//! the union was built for is negligible next to that, so
//! [`MergeMode::KeepBest`] is the default and [`MergeMode::Union`] is opt-in
//! (it stays bit-exact with the original reference for parity work).
//!
//! # Per-tile decode guidance (affects mAP)
//!
//! Run the per-tile [`crate::Decoder`] with a **low score threshold** (e.g.
//! 0.05) and **class-aware** NMS, and a modest per-tile `max_det`. The merge's
//! own [`MergeConfig::score_threshold`] defaults to `0.0` precisely because
//! per-tile decode is the real flood control — a high per-tile threshold
//! discards true-positive fragments before the merge can join them, collapsing
//! the recall the IOS design buys. Final score gating belongs in
//! [`MergeConfig::score_threshold`].
//!
//! # Known limitations
//!
//! - **Objects larger than one tile** are not reconstructed: every tile sees
//!   only a fragment. Keep-best reports the highest-scoring fragment;
//!   [`MergeMode::Union`] grows the kept box over the fragments that match
//!   it, but with no whole-object box to anchor the group the fragments may
//!   not mutually pass the IOS threshold either. Choose a tile size that
//!   exceeds the largest expected object, or add the optional full-frame
//!   downscaled pass (push it as one extra tile into the accumulator).
//!
//! # Reference implementations
//!
//! - **Grid spacing (EvenDist):** the canonical authority is HAL's own
//!   `edgefirst_image::tile_grid` (ported from the adis-uav-model `sahi()`
//!   function). `overlap_ratio` is a *minimum*; realized overlap is never
//!   rounded below it. ModelPack's validator is slated to adopt this same grid.
//! - **Merge:** ModelPack `metrics/tiled.py::merge_tiled_detections` — mirrored
//!   here numerically, mode for mode (ModelPack carries the same `merge_mode`
//!   switch with the same keep-best default; its original union-only merge is
//!   [`MergeMode::Union`]). The only deliberate difference is tie-breaking on
//!   exactly equal scores (ascending original index here vs NumPy's unstable
//!   `argsort`), which makes the streaming accumulator order-independent;
//!   results are identical on non-degenerate inputs.

use crate::float::{box_area, intersection_area, ios_value, iou_value};
use crate::{BoundingBox, DetectBox};
// `pub use`: TilePlacement is part of this module's public surface --
// `lift_tile_boxes` and `push_tile` take one, and the doctests below
// import it from here. A private import compiles but leaves the type
// unnameable by callers.
pub use edgefirst_decoder_abi::TilePlacement;
use edgefirst_tensor::unletter_norm;

/// Overlap metric used by the tiled-detection merge to decide whether two boxes
/// belong to the same object.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum MatchMetric {
    /// Intersection-over-Union (standard NMS metric).
    Iou,
    /// Intersection-over-Smaller (default): `inter / min(area_a, area_b)`. A
    /// seam-split object has low IoU but high IoS, so IoS merges the fragment.
    #[default]
    Ios,
}

impl MatchMetric {
    /// Metric value in `[0, 1]` for two boxes.
    #[inline]
    pub fn value(self, a: &BoundingBox, b: &BoundingBox) -> f32 {
        match self {
            MatchMetric::Iou => iou_value(a, b),
            MatchMetric::Ios => ios_value(a, b),
        }
    }
}

/// What the tiled-detection merge emits for a group of boxes the match
/// metric has joined.
///
/// Measured on the Ocean Cleanup ADIS 4K validation set (TOP2-836), the
/// enclosing union cost about 0.05 AP50 on every frame (whole frame: 0.491
/// AP50 with plain NMS, 0.437 after the union merge, 0.490 with keep-best;
/// 28-tile pipeline: 0.500 keep-best vs 0.442 union), so [`Self::KeepBest`]
/// is the default. See the [module docs](self#merge-mode-affects-map).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum MergeMode {
    /// Keep the group's highest-scoring box — its coordinates and its score
    /// — and drop the boxes it matched. Greedy NMS under the configured
    /// metric. Default.
    ///
    /// The kept box is never grown, rescored or relabelled. It is emitted
    /// [canonicalized](crate::BoundingBox::to_canonical), which every box
    /// entering the merge is, so it differs from the input only for a
    /// degenerate input box whose `min` exceeded its `max`.
    #[default]
    KeepBest,
    /// Replace the group with its enclosing union carrying the group's max
    /// score: the original GREEDYNMM merge (ModelPack `metrics/tiled.py`
    /// before `merge_mode`). Opt-in; inflates boxes and costs mAP.
    Union,
}

/// Configuration for the tiled-detection merge.
///
/// The defaults are IoS at 0.5, class-aware, [`MergeMode::KeepBest`],
/// `max_det` 300 and no score gate. Keep-best rather than the enclosing union
/// because the union measured about −0.05 AP50 on every frame of the Ocean
/// Cleanup ADIS 4K validation (TOP2-836); see [`MergeMode`].
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct MergeConfig {
    /// Overlap metric (default [`MatchMetric::Ios`]).
    pub metric: MatchMetric,
    /// Merge two boxes when `metric.value(a, b) >= threshold` (default 0.5).
    pub threshold: f32,
    /// Merge across classes when true (default false).
    pub class_agnostic: bool,
    /// Cap on returned detections after the merge (default 300).
    pub max_det: usize,
    /// Drop merged groups whose max score is below this (default 0.0 = keep
    /// all; per-tile decode is the real flood control).
    pub score_threshold: f32,
    /// What a matched group becomes (default [`MergeMode::KeepBest`]).
    pub mode: MergeMode,
}

impl Default for MergeConfig {
    fn default() -> Self {
        Self {
            metric: MatchMetric::Ios,
            threshold: 0.5,
            class_agnostic: false,
            max_det: 300,
            score_threshold: 0.0,
            mode: MergeMode::KeepBest,
        }
    }
}

/// Lift tile-local **normalized** `[0,1]` xyxy detections (over the model
/// input) to full-frame **pixel** xyxy. Mirrors
/// `metrics/tiled.py::lift_tile_boxes`: optionally invert the letterbox, then
/// `full = origin + norm * crop_size`. Consumes and rewrites `boxes` in place.
///
/// # Examples
/// ```
/// use edgefirst_decoder::tiling::{lift_tile_boxes, TilePlacement};
/// use edgefirst_decoder::{BoundingBox, DetectBox};
///
/// let placement = TilePlacement {
///     index: 0, count: 1,
///     origin: (100.0, 200.0), crop_size: (640.0, 640.0),
///     letterbox: None, frame_dims: (3840.0, 2160.0),
/// };
/// let tile_local = DetectBox { bbox: BoundingBox::new(0.0, 0.0, 1.0, 1.0), score: 0.9, label: 0 };
/// let lifted = lift_tile_boxes(vec![tile_local], &placement);
/// assert_eq!(lifted[0].bbox, BoundingBox::new(100.0, 200.0, 740.0, 840.0));
/// ```
#[must_use]
pub fn lift_tile_boxes(mut boxes: Vec<DetectBox>, placement: &TilePlacement) -> Vec<DetectBox> {
    let _s = tracing::trace_span!("decoder.tiled.lift", boxes = boxes.len()).entered();
    let (ox, oy) = placement.origin;
    let (cw, ch) = placement.crop_size;
    for d in &mut boxes {
        let n = match placement.letterbox {
            Some(lb) => unletter_norm(d.bbox, lb),
            None => d.bbox,
        };
        d.bbox = BoundingBox {
            xmin: ox + n.xmin * cw,
            ymin: oy + n.ymin * ch,
            xmax: ox + n.xmax * cw,
            ymax: oy + n.ymax * ch,
        };
    }
    boxes
}

/// Match metric using precomputed areas (avoids recomputing both operands'
/// areas on every pair in the O(N^2) merge). Equivalent to
/// [`MatchMetric::value`].
#[inline]
fn metric_value_with_areas(
    metric: MatchMetric,
    a: &BoundingBox,
    area_a: f32,
    b: &BoundingBox,
    area_b: f32,
) -> f32 {
    let inter = intersection_area(a, b);
    let denom = match metric {
        MatchMetric::Iou => area_a + area_b - inter,
        MatchMetric::Ios => area_a.min(area_b),
    };
    inter / denom.max(1e-9)
}

/// Greedy merge of lifted full-frame detections. Mirrors
/// `metrics/tiled.py::merge_tiled_detections`:
///
/// 1. Sort descending by score (ties broken by ascending original index so the
///    result is deterministic — this differs from NumPy's unstable `argsort`
///    only on exact ties).
/// 2. For each unused `base` in order, find later unused boxes (same class
///    unless `class_agnostic`) whose `metric.value(base, cand) >= threshold` —
///    matched against the **original** base box — and mark them used. With
///    [`MergeMode::KeepBest`] (default) the base box is emitted unchanged
///    (canonicalized, never grown or rescored); with [`MergeMode::Union`] the group is
///    replaced by its **enclosing union** carrying the group's **max** score.
///    Either way the output carries the base's label.
/// 3. Drop groups below `score_threshold` and truncate to `max_det`.
///
/// Keep-best is the default because the union measured about −0.05 AP50 on
/// every frame of the Ocean Cleanup ADIS 4K validation (TOP2-836): whole
/// frame 0.491 AP50 with plain NMS, 0.437 after the union, 0.490 with
/// keep-best. Operates in pixel space (the metric's `1e-9` epsilon is
/// calibrated to pixel areas).
///
/// # Examples
/// ```
/// use edgefirst_decoder::tiling::{merge_tiled_detections, MatchMetric, MergeConfig, MergeMode};
/// use edgefirst_decoder::{BoundingBox, DetectBox};
///
/// // A fragment (B) fully inside the full detection (A): IoS=1.0, IoU≈0.17.
/// let a = DetectBox { bbox: BoundingBox::new(100.0, 100.0, 400.0, 300.0), score: 0.9, label: 0 };
/// let b = DetectBox { bbox: BoundingBox::new(350.0, 100.0, 400.0, 300.0), score: 0.7, label: 0 };
///
/// // IOS matches the fragment; keep-best (the default) suppresses it and
/// // leaves A's box unchanged…
/// let ios = merge_tiled_detections(vec![a, b], &MergeConfig::default());
/// assert_eq!(ios.len(), 1);
/// assert_eq!(ios[0].bbox, a.bbox);
/// assert_eq!(ios[0].score, 0.9);
///
/// // …while IOU leaves the two separate.
/// let cfg = MergeConfig { metric: MatchMetric::Iou, ..MergeConfig::default() };
/// assert_eq!(merge_tiled_detections(vec![a, b], &cfg).len(), 2);
///
/// // A box that extends past A at IoS 0.5: keep-best still returns A as is,
/// // the legacy union mode grows A to the group's enclosing union.
/// let c = DetectBox { bbox: BoundingBox::new(350.0, 100.0, 450.0, 300.0), score: 0.7, label: 0 };
/// let keep = merge_tiled_detections(vec![a, c], &MergeConfig::default());
/// assert_eq!(keep[0].bbox, a.bbox);
/// let union = MergeConfig { mode: MergeMode::Union, ..MergeConfig::default() };
/// let grown = merge_tiled_detections(vec![a, c], &union);
/// assert_eq!(grown.len(), 1);
/// assert_eq!(grown[0].bbox, BoundingBox::new(100.0, 100.0, 450.0, 300.0));
/// ```
#[must_use]
pub fn merge_tiled_detections(dets: Vec<DetectBox>, cfg: &MergeConfig) -> Vec<DetectBox> {
    if dets.is_empty() {
        return dets;
    }

    // Descending score, ties by ascending original index (deterministic).
    let mut order: Vec<usize> = (0..dets.len()).collect();
    order.sort_by(|&i, &j| dets[j].score.total_cmp(&dets[i].score).then(i.cmp(&j)));

    // Canonicalize once so degenerate (inverted) boxes have well-defined areas,
    // and precompute each box's area once (the O(N^2) loop below would otherwise
    // recompute both operands' areas on every pair).
    let boxes: Vec<BoundingBox> = dets.iter().map(|d| d.bbox.to_canonical()).collect();
    let areas: Vec<f32> = boxes.iter().map(box_area).collect();

    let n = dets.len();
    let mut used = vec![false; n];
    let mut out: Vec<DetectBox> = Vec::with_capacity(n);

    for oi in 0..n {
        let i = order[oi];
        if used[i] {
            continue;
        }
        used[i] = true;
        let base_box = boxes[i];
        let base_area = areas[i];
        let base_label = dets[i].label;
        // What the group becomes. Keep-best never touches these; union grows
        // the box over every matched candidate and takes the max score.
        let mut out_box = base_box;
        let mut out_score = dets[i].score;

        for &j in &order[(oi + 1)..] {
            if used[j] {
                continue;
            }
            if !cfg.class_agnostic && dets[j].label != base_label {
                continue;
            }
            // Metric measured against the ORIGINAL base box (parity with the
            // reference), using cached areas.
            if metric_value_with_areas(cfg.metric, &base_box, base_area, &boxes[j], areas[j])
                >= cfg.threshold
            {
                used[j] = true;
                match cfg.mode {
                    MergeMode::KeepBest => {}
                    MergeMode::Union => {
                        let c = boxes[j];
                        out_box.xmin = out_box.xmin.min(c.xmin);
                        out_box.ymin = out_box.ymin.min(c.ymin);
                        out_box.xmax = out_box.xmax.max(c.xmax);
                        out_box.ymax = out_box.ymax.max(c.ymax);
                        out_score = out_score.max(dets[j].score);
                    }
                }
            }
        }

        out.push(DetectBox {
            bbox: out_box,
            score: out_score,
            label: base_label,
        });
    }

    if cfg.score_threshold > 0.0 {
        out.retain(|d| d.score >= cfg.score_threshold);
    }
    out.truncate(cfg.max_det);
    out
}

/// Streaming collector for one frame's tiled detections. A pipelined runtime
/// pushes each tile's per-tile-decoded boxes as inference completes (any
/// order), then finalizes once every tile has arrived — the "collect after the
/// final tile" fan-in. Not internally synchronized; keep one accumulator per
/// in-flight frame.
#[derive(Debug, Clone)]
pub struct TiledFrameAccumulator {
    frame_dims: (f32, f32),
    tiles_total: usize,
    /// Per-tile-index arrival flags — makes `push_tile` idempotent and the
    /// completion fence robust to duplicate / out-of-range / retried pushes
    /// (an at-least-once async pipeline can deliver the same tile twice).
    seen: Vec<bool>,
    received: usize,
    dets: Vec<DetectBox>,
    cfg: MergeConfig,
}

impl TiledFrameAccumulator {
    /// Create an accumulator for a frame with `tiles_total` tiles. `frame_dims`
    /// is `(frame_w, frame_h)` in pixels, used by [`Self::finalize_normalized`].
    /// `est_per_tile` pre-reserves the detection buffer.
    ///
    /// # Examples
    /// ```
    /// use edgefirst_decoder::tiling::{MergeConfig, TiledFrameAccumulator};
    /// let acc = TiledFrameAccumulator::new((1920.0, 1080.0), 12, MergeConfig::default(), 16);
    /// assert_eq!(acc.remaining(), 12);
    /// assert!(!acc.is_complete());
    /// ```
    pub fn new(
        frame_dims: (f32, f32),
        tiles_total: usize,
        cfg: MergeConfig,
        est_per_tile: usize,
    ) -> Self {
        Self {
            frame_dims,
            tiles_total,
            seen: vec![false; tiles_total],
            received: 0,
            dets: Vec::with_capacity(tiles_total.saturating_mul(est_per_tile)),
            cfg,
        }
    }

    /// Lift one tile's per-tile-decoded boxes to full-frame pixels and append
    /// them. Idempotent per `placement.index`: a duplicate, out-of-range, or
    /// foreign placement (one whose `count` disagrees with this accumulator's
    /// `tiles_total`, i.e. from a different plan/frame) is ignored and its boxes
    /// dropped, so out-of-order **and** at-least-once delivery both converge to
    /// the same result. Returns `true` if the tile was newly accepted, `false`
    /// otherwise.
    pub fn push_tile(&mut self, tile_boxes: Vec<DetectBox>, placement: &TilePlacement) -> bool {
        let idx = placement.index;
        // Runtime guard (not debug-only): reject placements from a different
        // plan so a mixed-frame mistake can't corrupt fan-in completion.
        if placement.count != self.tiles_total || idx >= self.tiles_total || self.seen[idx] {
            return false;
        }
        self.seen[idx] = true;
        self.dets.extend(lift_tile_boxes(tile_boxes, placement));
        self.received += 1;
        true
    }

    /// True once every tile of the frame has been pushed (by distinct index).
    #[inline]
    pub fn is_complete(&self) -> bool {
        self.received >= self.tiles_total
    }

    /// Tiles still outstanding.
    #[inline]
    pub fn remaining(&self) -> usize {
        self.tiles_total.saturating_sub(self.received)
    }

    /// Merge all accumulated detections into full-frame **pixel** boxes.
    #[must_use]
    pub fn finalize(self) -> Vec<DetectBox> {
        let span = tracing::trace_span!(
            "decoder.tiled.merge",
            tiles = self.tiles_total,
            boxes_in = self.dets.len(),
            boxes_out = tracing::field::Empty,
        );
        let _s = span.enter();
        let out = merge_tiled_detections(self.dets, &self.cfg);
        span.record("boxes_out", out.len());
        out
    }

    /// Merge then renormalize to `[0,1]` by `frame_dims` (for the tracker,
    /// matching the non-tiled normalized-detection contract).
    ///
    /// Returns an empty list when `frame_dims` are non-finite or non-positive
    /// rather than emitting Inf/NaN coordinates.
    #[must_use]
    pub fn finalize_normalized(self) -> Vec<DetectBox> {
        let (fw, fh) = self.frame_dims;
        if !(fw.is_finite() && fh.is_finite() && fw > 0.0 && fh > 0.0) {
            return Vec::new();
        }
        let inv_w = 1.0 / fw;
        let inv_h = 1.0 / fh;
        let mut merged = {
            let span = tracing::trace_span!(
                "decoder.tiled.merge",
                tiles = self.tiles_total,
                boxes_in = self.dets.len(),
                boxes_out = tracing::field::Empty,
            );
            let _s = span.enter();
            let out = merge_tiled_detections(self.dets, &self.cfg);
            span.record("boxes_out", out.len());
            out
        };
        for d in &mut merged {
            d.bbox.xmin *= inv_w;
            d.bbox.xmax *= inv_w;
            d.bbox.ymin *= inv_h;
            d.bbox.ymax *= inv_h;
        }
        merged
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn det(b: [f32; 4], score: f32, label: usize) -> DetectBox {
        DetectBox {
            bbox: BoundingBox::new(b[0], b[1], b[2], b[3]),
            score,
            label,
        }
    }

    // --- lift -------------------------------------------------------------

    fn placement(origin: (f32, f32), crop: (f32, f32)) -> TilePlacement {
        TilePlacement {
            index: 0,
            count: 1,
            origin,
            crop_size: crop,
            letterbox: None,
            frame_dims: (3840.0, 2160.0),
        }
    }

    #[test]
    fn lift_no_letterbox_matches_origin_plus_scale() {
        let p = placement((100.0, 200.0), (640.0, 640.0));
        let lifted = lift_tile_boxes(
            vec![
                det([0.0, 0.0, 1.0, 1.0], 0.9, 0),
                det([0.25, 0.5, 0.75, 1.0], 0.8, 0),
            ],
            &p,
        );
        assert_eq!(lifted[0].bbox, BoundingBox::new(100.0, 200.0, 740.0, 840.0));
        assert_eq!(lifted[1].bbox, BoundingBox::new(260.0, 520.0, 580.0, 840.0));
    }

    #[test]
    fn lift_with_letterbox_inverts_then_scales() {
        // A box filling the letterbox content region should, after un-padding,
        // fill the crop and lift identically to the no-letterbox full-crop box.
        let mut p = placement((0.0, 0.0), (640.0, 640.0));
        p.letterbox = Some([0.1, 0.1, 0.9, 0.9]);
        let lifted = lift_tile_boxes(vec![det([0.1, 0.1, 0.9, 0.9], 0.9, 0)], &p);
        let b = lifted[0].bbox;
        assert!((b.xmin - 0.0).abs() < 1e-3);
        assert!((b.ymin - 0.0).abs() < 1e-3);
        assert!((b.xmax - 640.0).abs() < 1e-3);
        assert!((b.ymax - 640.0).abs() < 1e-3);
    }

    #[test]
    fn lift_empty_is_empty() {
        let p = placement((0.0, 0.0), (640.0, 640.0));
        assert!(lift_tile_boxes(vec![], &p).is_empty());
    }

    #[test]
    fn lift_roundtrip_with_letterbox() {
        // Project a known full-frame box into tile-normalized (letterboxed)
        // coords, then lift it back and confirm it returns to the original.
        let p = TilePlacement {
            index: 0,
            count: 1,
            origin: (100.0, 200.0),
            crop_size: (640.0, 640.0),
            letterbox: Some([0.1, 0.1, 0.9, 0.9]),
            frame_dims: (1920.0, 1080.0),
        };
        // Full-frame target [228,328,420,520] -> crop-normalized (subtract origin,
        // /crop) -> letterbox-normalized (scale by lb extent + offset).
        let crop_n = [
            (228.0 - 100.0) / 640.0,
            (328.0 - 200.0) / 640.0,
            (420.0 - 100.0) / 640.0,
            (520.0 - 200.0) / 640.0,
        ];
        let [lx0, ly0, lx1, ly1] = [0.1, 0.1, 0.9, 0.9];
        let model_n = det(
            [
                lx0 + crop_n[0] * (lx1 - lx0),
                ly0 + crop_n[1] * (ly1 - ly0),
                lx0 + crop_n[2] * (lx1 - lx0),
                ly0 + crop_n[3] * (ly1 - ly0),
            ],
            0.9,
            0,
        );
        let lifted = lift_tile_boxes(vec![model_n], &p);
        let b = lifted[0].bbox;
        assert!((b.xmin - 228.0).abs() < 1e-2, "xmin {}", b.xmin);
        assert!((b.ymin - 328.0).abs() < 1e-2, "ymin {}", b.ymin);
        assert!((b.xmax - 420.0).abs() < 1e-2, "xmax {}", b.xmax);
        assert!((b.ymax - 520.0).abs() < 1e-2, "ymax {}", b.ymax);
    }

    #[test]
    fn lift_letterbox_clamp_fires_and_no_div_by_zero() {
        // A box outside the letterbox content region clamps to the edge; a
        // degenerate (zero-span) letterbox axis must not divide by zero.
        let p = TilePlacement {
            index: 0,
            count: 1,
            origin: (0.0, 0.0),
            crop_size: (640.0, 640.0),
            letterbox: Some([0.1, 0.1, 0.9, 0.9]),
            frame_dims: (640.0, 640.0),
        };
        // Box at the very top-left, outside [0.1,0.1] content origin.
        let lifted = lift_tile_boxes(vec![det([0.0, 0.0, 0.05, 0.05], 0.9, 0)], &p);
        assert_eq!(lifted[0].bbox.xmin, 0.0);
        assert_eq!(lifted[0].bbox.ymin, 0.0);

        // Degenerate letterbox (lx0 == lx1): unit scale, finite result.
        let pd = TilePlacement {
            letterbox: Some([0.5, 0.1, 0.5, 0.9]),
            ..p
        };
        let out = lift_tile_boxes(vec![det([0.2, 0.2, 0.8, 0.8], 0.9, 0)], &pd);
        assert!(out[0].bbox.xmin.is_finite() && out[0].bbox.xmax.is_finite());
    }

    // --- merge: the canonical IOS-vs-IOU case ----------------------------

    #[test]
    fn ios_merges_fragment_iou_does_not() {
        // From modelpack tests/test_tiled_merge.py: B fully inside A
        // (IoS=1.0, IoU=0.167).
        let a = det([100.0, 100.0, 400.0, 300.0], 0.9, 0);
        let b = det([350.0, 100.0, 400.0, 300.0], 0.7, 0);

        let ios = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                metric: MatchMetric::Ios,
                threshold: 0.5,
                ..Default::default()
            },
        );
        assert_eq!(ios.len(), 1);
        assert_eq!(ios[0].bbox, BoundingBox::new(100.0, 100.0, 400.0, 300.0));
        assert_eq!(ios[0].score, 0.9);

        let iou = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                metric: MatchMetric::Iou,
                threshold: 0.5,
                ..Default::default()
            },
        );
        assert_eq!(iou.len(), 2);
    }

    #[test]
    fn merge_respects_class_unless_agnostic() {
        let a = det([100.0, 100.0, 400.0, 300.0], 0.9, 0);
        let b = det([350.0, 100.0, 400.0, 300.0], 0.7, 1); // different class

        let aware = merge_tiled_detections(vec![a, b], &MergeConfig::default());
        assert_eq!(aware.len(), 2);

        let agnostic = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                class_agnostic: true,
                ..Default::default()
            },
        );
        assert_eq!(agnostic.len(), 1);
        // Merged box keeps the base (highest-score) label.
        assert_eq!(agnostic[0].label, 0);
        assert_eq!(
            agnostic[0].bbox,
            BoundingBox::new(100.0, 100.0, 400.0, 300.0)
        );
    }

    #[test]
    fn merge_enclosing_union_for_partial_overlap() {
        // Legacy `Union` mode: two boxes overlapping >=0.5 IoS merge to their
        // enclosing union carrying the group's max score.
        let a = det([0.0, 0.0, 100.0, 100.0], 0.9, 0);
        let b = det([50.0, 0.0, 150.0, 100.0], 0.8, 0); // IoS = 0.5
        let merged = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                metric: MatchMetric::Ios,
                threshold: 0.5,
                mode: MergeMode::Union,
                ..Default::default()
            },
        );
        assert_eq!(merged.len(), 1);
        assert_eq!(merged[0].bbox, BoundingBox::new(0.0, 0.0, 150.0, 100.0));
        assert_eq!(merged[0].score, 0.9);
    }

    #[test]
    fn keep_best_keeps_base_box_unchanged_for_partial_overlap() {
        // Same geometry as the union test: the lower-scoring box extends
        // beyond the base and matches at IoS >= 0.5. `KeepBest` (the
        // default) suppresses it and leaves the base box's coordinates and
        // score unchanged -- it must not grow into the union.
        let a = det([0.0, 0.0, 100.0, 100.0], 0.9, 0);
        let b = det([50.0, 0.0, 150.0, 100.0], 0.8, 0); // IoS = 0.5
        let merged = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                metric: MatchMetric::Ios,
                threshold: 0.5,
                mode: MergeMode::KeepBest,
                ..Default::default()
            },
        );
        assert_eq!(merged.len(), 1);
        assert_eq!(merged[0].bbox, a.bbox);
        assert_eq!(merged[0].score, a.score);
        assert_eq!(merged[0].label, a.label);

        // The default config is keep-best, so it must give the same answer.
        let by_default = merge_tiled_detections(vec![a, b], &MergeConfig::default());
        assert_eq!(by_default.len(), 1);
        assert_eq!(by_default[0].bbox, a.bbox);
        assert_eq!(by_default[0].score, a.score);
    }

    #[test]
    fn keep_best_still_suppresses_every_matched_box_in_the_group() {
        // Suppression, not a no-op: three same-class boxes chained through
        // the base collapse to the base alone, and a box matched only
        // against a suppressed box (not the base) survives, exactly as the
        // reference's "metric against the ORIGINAL base box" rule dictates.
        let base = det([0.0, 0.0, 100.0, 100.0], 0.9, 0);
        let right = det([50.0, 0.0, 150.0, 100.0], 0.8, 0); // IoS 0.5 with base
        let inside = det([10.0, 10.0, 40.0, 40.0], 0.7, 0); // fully inside base
        let far = det([140.0, 0.0, 200.0, 100.0], 0.6, 0); // IoS 1/6 with base
        let merged =
            merge_tiled_detections(vec![base, right, inside, far], &MergeConfig::default());
        assert_eq!(merged.len(), 2);
        assert_eq!(merged[0].bbox, base.bbox);
        assert_eq!(merged[0].score, 0.9);
        assert_eq!(merged[1].bbox, far.bbox);
        assert_eq!(merged[1].score, 0.6);
    }

    #[test]
    fn default_merge_mode_is_keep_best() {
        // The Ocean Cleanup ADIS 4K study (TOP2-836) measured the enclosing
        // union at about -0.05 AP50 on every frame; keep-best is the default.
        assert_eq!(MergeConfig::default().mode, MergeMode::KeepBest);
        assert_eq!(MergeMode::default(), MergeMode::KeepBest);
    }

    #[test]
    fn merge_disjoint_boxes_pass_through() {
        let a = det([0.0, 0.0, 10.0, 10.0], 0.9, 0);
        let b = det([100.0, 100.0, 110.0, 110.0], 0.8, 0);
        let merged = merge_tiled_detections(vec![a, b], &MergeConfig::default());
        assert_eq!(merged.len(), 2);
    }

    #[test]
    fn merge_empty_is_empty() {
        assert!(merge_tiled_detections(vec![], &MergeConfig::default()).is_empty());
    }

    #[test]
    fn merge_threshold_boundary_is_inclusive() {
        // IoS exactly == threshold must merge (>=, not >).
        let a = det([0.0, 0.0, 100.0, 100.0], 0.9, 0);
        let b = det([50.0, 0.0, 150.0, 100.0], 0.8, 0); // IoS = 0.5 exactly
        let merged = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                metric: MatchMetric::Ios,
                threshold: 0.5,
                ..Default::default()
            },
        );
        assert_eq!(merged.len(), 1);
    }

    #[test]
    fn merge_score_threshold_drops_low_groups() {
        let a = det([0.0, 0.0, 10.0, 10.0], 0.3, 0);
        let b = det([100.0, 100.0, 110.0, 110.0], 0.8, 0);
        let merged = merge_tiled_detections(
            vec![a, b],
            &MergeConfig {
                score_threshold: 0.5,
                ..Default::default()
            },
        );
        assert_eq!(merged.len(), 1);
        assert_eq!(merged[0].score, 0.8);
    }

    #[test]
    fn merge_max_det_caps_highest_scoring() {
        let dets: Vec<DetectBox> = (0..10)
            .map(|i| {
                det(
                    [i as f32 * 50.0, 0.0, i as f32 * 50.0 + 10.0, 10.0],
                    1.0 - i as f32 * 0.05,
                    0,
                )
            })
            .collect();
        let merged = merge_tiled_detections(
            dets,
            &MergeConfig {
                max_det: 3,
                ..Default::default()
            },
        );
        assert_eq!(merged.len(), 3);
        assert!(merged[0].score >= merged[1].score);
        assert!(merged[1].score >= merged[2].score);
    }

    #[test]
    fn merge_max_det_exact_boundary() {
        // N disjoint boxes; max_det == N keeps all, max_det == N-1 drops one.
        let make = || -> Vec<DetectBox> {
            (0..5)
                .map(|i| {
                    det(
                        [i as f32 * 50.0, 0.0, i as f32 * 50.0 + 10.0, 10.0],
                        1.0 - i as f32 * 0.05,
                        0,
                    )
                })
                .collect()
        };
        assert_eq!(
            merge_tiled_detections(
                make(),
                &MergeConfig {
                    max_det: 5,
                    ..Default::default()
                }
            )
            .len(),
            5
        );
        assert_eq!(
            merge_tiled_detections(
                make(),
                &MergeConfig {
                    max_det: 4,
                    ..Default::default()
                }
            )
            .len(),
            4
        );
    }

    #[test]
    fn merge_score_threshold_boundary_is_inclusive() {
        // A group whose max score == score_threshold is kept (>=).
        let a = det([0.0, 0.0, 10.0, 10.0], 0.5, 0);
        let merged = merge_tiled_detections(
            vec![a],
            &MergeConfig {
                score_threshold: 0.5,
                ..Default::default()
            },
        );
        assert_eq!(merged.len(), 1);
    }

    // --- accumulator ------------------------------------------------------

    fn empty_placement(index: usize, count: usize) -> TilePlacement {
        TilePlacement {
            index,
            count,
            origin: (0.0, 0.0),
            crop_size: (640.0, 640.0),
            letterbox: None,
            frame_dims: (640.0, 640.0),
        }
    }

    #[test]
    fn accumulator_fan_in_fence() {
        let mut acc = TiledFrameAccumulator::new((640.0, 640.0), 3, MergeConfig::default(), 8);
        assert!(!acc.is_complete());
        assert_eq!(acc.remaining(), 3);
        assert!(acc.push_tile(vec![], &empty_placement(0, 3)));
        assert!(acc.push_tile(vec![], &empty_placement(1, 3)));
        assert!(!acc.is_complete());
        assert_eq!(acc.remaining(), 1);
        assert!(acc.push_tile(vec![], &empty_placement(2, 3)));
        assert!(acc.is_complete());
        assert_eq!(acc.remaining(), 0);
        assert!(acc.finalize().is_empty());
    }

    #[test]
    fn accumulator_dedups_and_ignores_overpush() {
        let mut acc = TiledFrameAccumulator::new((640.0, 640.0), 2, MergeConfig::default(), 8);
        assert!(acc.push_tile(vec![], &empty_placement(0, 2)));
        // Duplicate index 0 is ignored (idempotent under at-least-once delivery).
        assert!(!acc.push_tile(vec![], &empty_placement(0, 2)));
        assert_eq!(acc.remaining(), 1);
        assert!(!acc.is_complete());
        assert!(acc.push_tile(vec![], &empty_placement(1, 2)));
        assert!(acc.is_complete());
        // Out-of-range index is ignored, never over-counts.
        assert!(!acc.push_tile(vec![], &empty_placement(2, 2)));
        assert_eq!(acc.remaining(), 0);
    }

    #[test]
    fn accumulator_rejects_foreign_plan_count() {
        // A placement from a different plan (count != tiles_total) is rejected
        // at runtime — not just under debug_assert — so a mixed-frame mistake
        // can't corrupt fan-in completion.
        let mut acc = TiledFrameAccumulator::new((640.0, 640.0), 3, MergeConfig::default(), 8);
        assert!(!acc.push_tile(vec![], &empty_placement(0, 4)));
        assert_eq!(acc.remaining(), 3);
        assert!(!acc.is_complete());
        // The same index from the correct plan is still accepted afterward.
        assert!(acc.push_tile(vec![], &empty_placement(0, 3)));
        assert_eq!(acc.remaining(), 2);
    }

    #[test]
    fn accumulator_out_of_order_equals_in_order() {
        let cfg = MergeConfig::default();
        let frame = (1280.0, 640.0);
        // Two tiles side by side, a box near the seam in each.
        let p0 = TilePlacement {
            index: 0,
            count: 2,
            origin: (0.0, 0.0),
            crop_size: (640.0, 640.0),
            letterbox: None,
            frame_dims: frame,
        };
        let p1 = TilePlacement {
            index: 1,
            count: 2,
            origin: (640.0, 0.0),
            crop_size: (640.0, 640.0),
            letterbox: None,
            frame_dims: frame,
        };
        let t0 = vec![det([0.9, 0.4, 1.0, 0.6], 0.8, 0)];
        let t1 = vec![det([0.0, 0.4, 0.1, 0.6], 0.9, 0)];

        let mut a = TiledFrameAccumulator::new(frame, 2, cfg, 8);
        a.push_tile(t0.clone(), &p0);
        a.push_tile(t1.clone(), &p1);
        let in_order = a.finalize();

        let mut b = TiledFrameAccumulator::new(frame, 2, cfg, 8);
        b.push_tile(t1, &p1);
        b.push_tile(t0, &p0);
        let out_order = b.finalize();

        assert_eq!(in_order.len(), out_order.len());
        for (x, y) in in_order.iter().zip(out_order.iter()) {
            assert_eq!(x.bbox, y.bbox);
            assert_eq!(x.score, y.score);
        }
    }

    #[test]
    fn finalize_normalized_equals_finalize_over_frame_dims() {
        let cfg = MergeConfig::default();
        let frame = (1280.0, 640.0);
        let p = TilePlacement {
            index: 0,
            count: 1,
            origin: (100.0, 50.0),
            crop_size: (640.0, 640.0),
            letterbox: None,
            frame_dims: frame,
        };
        let boxes = vec![det([0.1, 0.1, 0.4, 0.4], 0.9, 0)];

        let mut a = TiledFrameAccumulator::new(frame, 1, cfg, 8);
        a.push_tile(boxes.clone(), &p);
        let px = a.finalize();

        let mut b = TiledFrameAccumulator::new(frame, 1, cfg, 8);
        b.push_tile(boxes, &p);
        let norm = b.finalize_normalized();

        assert_eq!(px.len(), norm.len());
        let (fw, fh) = frame;
        for (p, n) in px.iter().zip(norm.iter()) {
            assert!((n.bbox.xmin - p.bbox.xmin / fw).abs() < 1e-4);
            assert!((n.bbox.ymin - p.bbox.ymin / fh).abs() < 1e-4);
            assert!((n.bbox.xmax - p.bbox.xmax / fw).abs() < 1e-4);
            assert!((n.bbox.ymax - p.bbox.ymax / fh).abs() < 1e-4);
        }
    }

    #[test]
    fn finalize_normalized_rejects_invalid_frame_dims() {
        let cfg = MergeConfig::default();
        let boxes = vec![det([10.0, 10.0, 40.0, 40.0], 0.9, 0)];
        for frame in [
            (0.0, 640.0),
            (1280.0, 0.0),
            (f32::NAN, 640.0),
            (1280.0, f32::INFINITY),
        ] {
            let p = TilePlacement {
                index: 0,
                count: 1,
                origin: (0.0, 0.0),
                crop_size: (640.0, 640.0),
                letterbox: None,
                frame_dims: frame,
            };
            let mut acc = TiledFrameAccumulator::new(frame, 1, cfg, 8);
            acc.push_tile(boxes.clone(), &p);
            assert!(
                acc.finalize_normalized().is_empty(),
                "expected empty for frame_dims={frame:?}"
            );
        }
    }

    // --- end-to-end: accumulator -> merge -> tracker ----------------------

    /// One tile sees the whole object, an overlapping tile sees a contained
    /// fragment of it. IOS merges them into a single full-frame detection that
    /// the tracker resolves to ONE track; IOU leaves two, yielding TWO tracks
    /// (the negative control proving IOS does its job, not that it collapses
    /// everything).
    #[cfg(feature = "tracker")]
    #[test]
    fn e2e_ios_one_track_iou_two_tracks() {
        use edgefirst_tracker::{ByteTrackBuilder, Tracker};

        // Two distinct tiles (indices 0 and 1) of a 2-tile frame, each lifted via
        // a whole-frame placement so tile 0 yields the full object and tile 1 a
        // contained fragment — simulating overlapping tiles seeing the same object.
        let p0 = TilePlacement {
            index: 0,
            count: 2,
            origin: (0.0, 0.0),
            crop_size: (640.0, 640.0),
            letterbox: None,
            frame_dims: (640.0, 640.0),
        };
        let p1 = TilePlacement { index: 1, ..p0 };
        let full = det(
            [100.0 / 640.0, 100.0 / 640.0, 400.0 / 640.0, 300.0 / 640.0],
            0.9,
            0,
        );
        let frag = det(
            [350.0 / 640.0, 100.0 / 640.0, 400.0 / 640.0, 300.0 / 640.0],
            0.7,
            0,
        );

        let run = |metric: MatchMetric| -> (usize, usize) {
            let cfg = MergeConfig {
                metric,
                threshold: 0.5,
                ..Default::default()
            };
            let mut acc = TiledFrameAccumulator::new((640.0, 640.0), 2, cfg, 4);
            acc.push_tile(vec![full], &p0);
            acc.push_tile(vec![frag], &p1);
            let merged = acc.finalize_normalized();
            let mut tracker = ByteTrackBuilder::new().build::<DetectBox>();
            let _ = tracker.update(&merged, 1_000);
            (merged.len(), tracker.get_active_tracks().len())
        };

        let (ios_merged, ios_tracks) = run(MatchMetric::Ios);
        assert_eq!(ios_merged, 1, "IOS should merge the fragment");
        assert_eq!(ios_tracks, 1, "merged detection yields one track");

        let (iou_merged, iou_tracks) = run(MatchMetric::Iou);
        assert_eq!(iou_merged, 2, "IOU should leave the fragment separate");
        assert_eq!(iou_tracks, 2, "two detections yield two tracks");
    }
}