@trillboards/edge-sdk 0.2.85 → 0.2.91

package/deploy/detector/trillboards_detector/decode.py

@@ -0,0 +1,373 @@
+"""Three output layouts, three decodes, and the coordinate space each is in.
+
+WHY THIS IS A SEPARATE MODULE FROM `session.py`
+-----------------------------------------------
+`session.py` needs onnxruntime and Pillow. This file needs numpy and nothing
+else, so the arithmetic that turns a tensor into boxes can be exercised against
+hand-built arrays on any machine that has numpy — no 128 MiB artifact, no ORT.
+That is the same argument `detections.py` and `registry.py` already make for
+being stdlib-only, one dependency further up: the decode is the newest and
+least-exercised code in the service, and a decode that transposes an axis, or
+applies a sigmoid twice, or reads the box channels as class scores, produces a
+complete and entirely plausible table.
+
+It is also what lets the LiteRT cross-check in `bench/verify_detector_decode.py`
+run the SAME decode over a `.tflite` tensor. Two decoders for one contract is how
+the units drift apart in the first place.
+
+THE LAYOUT IS DECLARED, NEVER SNIFFED
+-------------------------------------
+Every function here takes the layout from the caller and each is reachable only
+through `YOLO_DECODERS`. Nothing in this file looks at a tensor and decides what
+it is.
+That is deliberate and it is the whole reason `model_platform_variants` grew an
+`output_layout` column: `[1, 300, 6]` and `[1, 6, 8400]` are both rank-3 with a 6
+in them, and a sniffer that gets it backwards reads x1,y1,x2,y2,score,cls as four
+box channels and two classes without erroring. The declaration is the artifact's
+own property, committed next to its class list in `labels.py` and mirrored in the
+registry row; the graph is then CHECKED against it (`session._read_graph_spec`)
+and refused on disagreement.
+
+THE COORDINATE SPACE IS DECLARED TOO, AND FOR A SHARPER REASON
+--------------------------------------------------------------
+Ultralytics wraps a `task=detect`, `end2end=False` TFLite export in
+`_NormalizeCoords`, dividing the four box channels by (W, H). Measured on all 17
+committed LiteRT twins: 16 of 17 emit ONNX boxes in pixels 0..640 and LiteRT
+boxes in 0..1, agreeing to 0.00018 px after multiplying by 640, with class scores
+agreeing to 5.5e-06. `queue_supermarket`, the one end2end twin, is pixels on both
+sides — an end2end head emits pixels everywhere. Every other check passes on that
+pair: same shape, same dtype, both load, both run, identical scores. A decoder
+that assumes pixels draws every box 640x too small on 16 of 17 models and nothing
+reports an error. So `box_scale_to_pixels` arrives with the tensor and is applied
+here; a contract that declares neither units nor a scale is refused in
+`labels.py` rather than defaulted.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# The layout and box-unit names live in `labels.py`, which imports nothing
+# heavier than the standard library. `registry.py` and `server.py` are testable
+# on a bare interpreter BECAUSE `labels.py` is, so the vocabulary that names
+# these values cannot be allowed to reach numpy through this module.
+from .labels import ANCHOR_4_PLUS_NC, END2END_N_6, OUTPUT_LAYOUTS, RFDETR_DETS_LABELS
+
+#: `ultralytics/cfg/default.yaml`: `iou: 0.7`, `max_det: 300`. These are the
+#: settings the published accuracy of an Ultralytics detector is quoted at, so
+#: they are the settings a candidate's score has to be reproducible under.
+#:
+#: THEY ARE CONSTANTS AND NOT A KNOB, deliberately. `run_candidate.py` makes the
+#: same argument about its own conf floor: a suppression setting that can vary
+#: per request is one nobody can reconstruct from a score card later, and two
+#: arms at different IoU thresholds are not a comparison
+#: (`docs/runbooks/cctv-detector-tier.md` §5 rule 1).
+NMS_IOU_THRESHOLD = 0.7
+MAX_DETECTIONS = 300
+
+#: `ultralytics/utils/nms.py::non_max_suppression`, `max_nms=30000`. Never binds
+#: at imgsz 640 (8,400 anchors) and does bind at 1280 (33,600), so it is
+#: transcribed rather than dropped as dead — an artifact at a larger imgsz would
+#: otherwise decode differently here than it scored upstream.
+MAX_NMS_CANDIDATES = 30000
+
+#: `max_wh=7680` in the same function. Boxes are offset by `class * 7680` so one
+#: suppression pass over all classes can never let one class suppress another —
+#: `agnostic=False` is the Ultralytics default and the one every score assumes.
+CLASS_OFFSET_STRIDE = 7680
+
+
+class LetterboxGeometry:
+    """How a submitted frame was mapped onto the model's square input.
+
+    Carried from preprocessing to decode rather than recomputed, because the two
+    must agree exactly: a box is un-mapped with the SAME gain and padding that
+    put the pixels there. Recomputing it from shapes is how a half-pixel
+    convention drifts between the two halves of one transform.
+    """
+
+    __slots__ = ("gain", "pad_x", "pad_y", "frame_w", "frame_h")
+
+    def __init__(self, gain: float, pad_x: float, pad_y: float, frame_w: int, frame_h: int):
+        if not gain > 0.0:
+            raise ValueError(f"letterbox gain must be positive, got {gain}")
+        self.gain = float(gain)
+        self.pad_x = float(pad_x)
+        self.pad_y = float(pad_y)
+        self.frame_w = int(frame_w)
+        self.frame_h = int(frame_h)
+
+
+def box_iou_against(box: np.ndarray, others: np.ndarray) -> np.ndarray:
+    """IoU of one xyxy box against many. Symmetric similarity, for suppression.
+
+    THE ONE IoU IN THE PYTHON TREE, and it is written here rather than imported
+    because there was none: `FaceDetector.ts:243` is the TypeScript kernel and
+    `BoxTracking.kt:36` the Kotlin one, and neither is reachable from a Python
+    service. `zoneContainment.ts` records the standing instruction for this file
+    type — "if NMS lands it must call FaceDetector's iou, not a copy" — which is
+    a rule about the TypeScript tree; the equivalent obligation here is that this
+    stays the only one. `edge-core/src/CentroidTracker.ts` is not a precedent to
+    follow either: that tracker is nearest-centroid and contains no IoU at all.
+    """
+    x1 = np.maximum(box[0], others[:, 0])
+    y1 = np.maximum(box[1], others[:, 1])
+    x2 = np.minimum(box[2], others[:, 2])
+    y2 = np.minimum(box[3], others[:, 3])
+    inter = np.clip(x2 - x1, 0.0, None) * np.clip(y2 - y1, 0.0, None)
+    area = (box[2] - box[0]) * (box[3] - box[1])
+    areas = (others[:, 2] - others[:, 0]) * (others[:, 3] - others[:, 1])
+    union = area + areas - inter
+    # A zero-area box can only arise from a degenerate prediction; scoring it 0
+    # keeps it from suppressing a real neighbour, and `_to_wire` drops it later.
+    return np.where(union > 0.0, inter / np.where(union > 0.0, union, 1.0), 0.0)
+
+
+def greedy_nms(boxes: np.ndarray, scores: np.ndarray, iou_threshold: float) -> np.ndarray:
+    """torchvision's `ops.nms` semantics: keep the best, drop what overlaps it.
+
+    `np.argsort(-scores, kind="stable")` and NOT `argsort(scores)[::-1]`, for the
+    reason `postprocess` already spells out one file over: reversing an ascending
+    sort reverses the ties too, so two boxes with identical scores swap places
+    and the one that survives suppression changes. A stable descending sort is
+    what torch's `argsort(descending=True, stable=True)` does.
+    """
+    if scores.shape[0] == 0:
+        return np.zeros((0,), dtype=np.int64)
+    order = np.argsort(-scores, kind="stable")
+    keep: "list[int]" = []
+    while order.size:
+        best = int(order[0])
+        keep.append(best)
+        if order.size == 1:
+            break
+        rest = order[1:]
+        overlaps = box_iou_against(boxes[best], boxes[rest])
+        order = rest[overlaps <= iou_threshold]
+    return np.asarray(keep, dtype=np.int64)
+
+
+def _to_frame_pixels(xyxy: np.ndarray, geometry: LetterboxGeometry):
+    """Un-letterbox: model-input pixels -> the SUBMITTED frame's pixels.
+
+    Mirrors `ultralytics/utils/ops.py::scale_boxes` — subtract the padding,
+    divide by the gain, clip to the frame — because the wire contract is the
+    submitted frame's pixels (`session.postprocess` scales by frame_w/frame_h for
+    the same reason) and a consumer that received model-input coordinates would
+    draw every box on the wrong geometry with no error anywhere.
+    """
+    out = xyxy.astype(np.float32, copy=True)
+    out[:, 0] -= geometry.pad_x
+    out[:, 2] -= geometry.pad_x
+    out[:, 1] -= geometry.pad_y
+    out[:, 3] -= geometry.pad_y
+    out /= np.float32(geometry.gain)
+    x0 = np.clip(out[:, 0], 0.0, geometry.frame_w)
+    y0 = np.clip(out[:, 1], 0.0, geometry.frame_h)
+    x1 = np.clip(out[:, 2], 0.0, geometry.frame_w)
+    y1 = np.clip(out[:, 3], 0.0, geometry.frame_h)
+    return x0, y0, x1, y1
+
+
+def _scaled_box_channels(raw: np.ndarray, box_scale_to_pixels: float) -> np.ndarray:
+    """Box channels in pixels of the model input, whatever they arrived as."""
+    scaled = raw.astype(np.float32, copy=True)
+    if box_scale_to_pixels != 1.0:
+        scaled *= np.float32(box_scale_to_pixels)
+    return scaled
+
+
+def decode_anchor_4_plus_nc(
+    raw: np.ndarray,
+    geometry: LetterboxGeometry,
+    min_confidence: float,
+    *,
+    box_scale_to_pixels: float,
+    expected_classes: int,
+):
+    """`[1, 4+nc, A]` — the raw Ultralytics head. NEEDS SUPPRESSION.
+
+    Transcribed from `ultralytics/utils/nms.py::non_max_suppression`, the branch
+    taken when the last axis is not 6 and `end2end` is false, followed by
+    `ops.scale_boxes`. Four steps, each named at its call site:
+
+      candidates  `xc = prediction[:, 4:mi].amax(1) > conf_thres`
+      boxes       `prediction[..., :4] = xywh2xyxy(...)`
+      best class  `conf, j = cls.max(1, keepdim=True)`  (multi_label is False)
+      suppression `boxes = x[:, :4] + cls * max_wh`, then `nms(boxes, scores)`
+
+    THE SCORES ARE ALREADY SIGMOID. An Ultralytics detect head applies it inside
+    the graph, unlike RF-DETR's, whose `labels` output is logits and which
+    `session.postprocess` sigmoids itself. Applying it twice here would squash
+    every confidence toward 0.5-0.73 and leave a table that still looks like
+    confidences — no NaN, no exception, nothing out of range.
+
+    CLASS FILTERING DOES NOT HAPPEN HERE. `wanted` is applied by `_to_wire`,
+    after `MAX_DETECTIONS`, so asking for one class cannot change which boxes the
+    model was allowed to keep. Narrowing first would make a two-class profile and
+    a ten-class profile disagree about the same frame.
+
+    NOTHING IS CLAMPED BEFORE SUPPRESSION. A real head puts boxes off the frame —
+    measured min -45.1 px on a committed artifact — and clipping them to the
+    frame first would move their IoU, change which one survives, and hide a
+    wrong-layout decode behind coordinates that had been made to look sane. The
+    only clamp is `_to_frame_pixels`, at the end, on what is about to go out.
+    """
+    if raw.ndim != 3 or raw.shape[0] != 1:
+        raise ValueError(f"{ANCHOR_4_PLUS_NC} expects a (1, 4+nc, anchors) tensor, got {raw.shape}")
+    grid = raw[0]
+    num_classes = grid.shape[0] - 4
+    if num_classes <= 0:
+        raise ValueError(f"{ANCHOR_4_PLUS_NC} needs 4 box channels plus at least one class, got {grid.shape}")
+    if num_classes != expected_classes:
+        # THE SECOND HALF OF THE LAYOUT REFUSAL, and the one that catches the
+        # case the graph check cannot: an `end2end_n_6` tensor is `[1, 300, 6]`,
+        # which arrives here as 300 - 4 = 296 "classes" over 6 "anchors" and
+        # decodes without raising into a confident, meaningless table.
+        # `_read_graph_spec` refuses that at LOAD from the DECLARED shape; this
+        # refuses it from the tensor ORT actually returned, which is not the same
+        # claim when an axis is dynamic. A decode that "works" on the wrong
+        # layout is the failure mode — there is no clamp, no NaN and no wrong
+        # dtype to notice.
+        raise ValueError(
+            f"{ANCHOR_4_PLUS_NC}: tensor has {num_classes} class channels but this model's "
+            f"vocabulary names {expected_classes}. Refusing rather than labelling a channel by "
+            f"position — a {raw.shape} tensor read as an anchor head is what {END2END_N_6} "
+            "looks like from here."
+        )
+
+    scores_by_class = grid[4:, :].T                     # (A, nc)
+    cxcywh = _scaled_box_channels(grid[:4, :].T, box_scale_to_pixels)
+
+    best = scores_by_class.max(axis=1)
+    class_idx = scores_by_class.argmax(axis=1).astype(np.int64)
+    keep = best > np.float32(min_confidence)
+    cxcywh, best, class_idx = cxcywh[keep], best[keep], class_idx[keep]
+    if best.shape[0] == 0:
+        return _empty()
+
+    xyxy = np.empty_like(cxcywh)
+    half = cxcywh[:, 2:] / np.float32(2.0)
+    xyxy[:, :2] = cxcywh[:, :2] - half
+    xyxy[:, 2:] = cxcywh[:, :2] + half
+
+    if best.shape[0] > MAX_NMS_CANDIDATES:
+        trimmed = np.argsort(-best, kind="stable")[:MAX_NMS_CANDIDATES]
+        xyxy, best, class_idx = xyxy[trimmed], best[trimmed], class_idx[trimmed]
+
+    offset = xyxy + (class_idx[:, None] * np.float32(CLASS_OFFSET_STRIDE))
+    kept = greedy_nms(offset, best, NMS_IOU_THRESHOLD)[:MAX_DETECTIONS]
+    x0, y0, x1, y1 = _to_frame_pixels(xyxy[kept], geometry)
+    return best[kept], class_idx[kept], x0, y0, x1, y1
+
+
+def decode_end2end_n_6(
+    raw: np.ndarray,
+    geometry: LetterboxGeometry,
+    min_confidence: float,
+    *,
+    box_scale_to_pixels: float,
+    expected_classes: int,
+):
+    """`[1, N, 6]` — x1,y1,x2,y2,score,cls, ALREADY SUPPRESSED.
+
+    Transcribed from the first branch of the same function
+    (`if prediction.shape[-1] == 6 or end2end`), which is a threshold and a
+    `[:max_det]` and nothing else. Running NMS over these rows would be a second
+    suppression the model was neither trained nor scored with.
+
+    The rows arrive score-descending and that order is preserved: the `[:max_det]`
+    upstream takes the FIRST max_det survivors of the mask, not the highest, so
+    re-ranking here would keep a different set on a frame with more than 300
+    detections.
+
+    `expected_classes` IS TAKEN AND DELIBERATELY NOT ENFORCED. The class rides in
+    a COLUMN here rather than being an axis, so there is no width to check it
+    against, and refusing a row whose `cls` is out of range would turn what
+    `_to_wire` correctly handles as one dropped-and-counted detection into the
+    loss of the whole frame. It is in the signature so both decodes are one
+    dispatch: a table whose entries take different arguments is a dispatch with a
+    branch in it, and the branch is the thing being removed. The shape check
+    above is what refuses an anchor tensor sent here.
+    """
+    if raw.ndim != 3 or raw.shape[0] != 1 or raw.shape[2] != 6:
+        raise ValueError(f"{END2END_N_6} expects a (1, N, 6) tensor, got {raw.shape}")
+    rows = raw[0]
+    if rows.shape[0] == 0:
+        return _empty()
+
+    keep = np.nonzero(rows[:, 4] > np.float32(min_confidence))[0][:MAX_DETECTIONS]
+    if keep.shape[0] == 0:
+        return _empty()
+
+    selected = rows[keep]
+    xyxy = _scaled_box_channels(selected[:, :4], box_scale_to_pixels)
+    x0, y0, x1, y1 = _to_frame_pixels(xyxy, geometry)
+    return (
+        selected[:, 4].astype(np.float32, copy=True),
+        selected[:, 5].astype(np.int64),
+        x0,
+        y0,
+        x1,
+        y1,
+    )
+
+
+def _empty():
+    z32 = np.zeros((0,), dtype=np.float32)
+    return z32, np.zeros((0,), dtype=np.int64), z32, z32.copy(), z32.copy(), z32.copy()
+
+
+#: Layout -> the decode that reads it. A layout with no entry here is not
+#: decodable by this build, and `labels.VariantContract` refuses one at import
+#: rather than letting a model load and answer `[]` — the collapse
+#: `DetectorNotReady` exists to prevent. `rfdetr_dets_labels` is absent on
+#: purpose: its decode is `session.postprocess`, which needs the top-k selection
+#: and the sigmoid this file does not do, and giving it a stub entry here would
+#: put two decodes in the tree for one contract.
+YOLO_DECODERS = {
+    ANCHOR_4_PLUS_NC: decode_anchor_4_plus_nc,
+    END2END_N_6: decode_end2end_n_6,
+}
+
+#: Every layout this build can decode at all, by whatever route. Asserted equal
+#: to the declarable set at import: a layout `labels.py` will accept and this
+#: file cannot read would load a model that answers `[]` forever.
+DECODABLE_LAYOUTS = frozenset(YOLO_DECODERS) | {RFDETR_DETS_LABELS}
+assert DECODABLE_LAYOUTS == OUTPUT_LAYOUTS, (
+    f"every declarable output layout must have a decode: {sorted(OUTPUT_LAYOUTS - DECODABLE_LAYOUTS)} has none"
+)
+
+#: Which preprocessing each layout's artifact was exported with, REPORTED on
+#: /health rather than left implicit. The shipped RF-DETR path STRETCHES to a
+#: square and normalises by ImageNet statistics; an Ultralytics export is
+#: letterboxed to 114-grey and scaled by 1/255 and nothing else. Using the wrong
+#: one is not a rounding difference — it changes the aspect of every object in
+#: the frame — and it is invisible to every shape and dtype check, so the name
+#: rides on the health payload where a reader can see which arm produced a
+#: number. `bench/run_candidate.py` names its two preprocessors for the same
+#: reason: an arm can never be compared against one preprocessed differently.
+PREPROCESSING_BY_LAYOUT = {
+    RFDETR_DETS_LABELS: "imagenet-normalised-stretch",
+    ANCHOR_4_PLUS_NC: "ultralytics-letterbox-114-centred",
+    END2END_N_6: "ultralytics-letterbox-114-centred",
+}
+
+
+__all__ = [
+    "ANCHOR_4_PLUS_NC",
+    "CLASS_OFFSET_STRIDE",
+    "DECODABLE_LAYOUTS",
+    "END2END_N_6",
+    "LetterboxGeometry",
+    "MAX_DETECTIONS",
+    "MAX_NMS_CANDIDATES",
+    "NMS_IOU_THRESHOLD",
+    "PREPROCESSING_BY_LAYOUT",
+    "RFDETR_DETS_LABELS",
+    "YOLO_DECODERS",
+    "box_iou_against",
+    "decode_anchor_4_plus_nc",
+    "decode_end2end_n_6",
+    "greedy_nms",
+]

package/deploy/detector/trillboards_detector/labels.py

@@ -111,6 +111,122 @@ def normalize_class_name(name: str) -> str:
 #: platforms, so it is held to the intersection of what all three accept.
 _MODEL_NAME_RE = re.compile(r"[a-z0-9][a-z0-9._-]*")
 
+# ── what a variant's numbers MEAN ────────────────────────────────────────────
+#
+# These three names and their value sets are the box-side copy of three columns
+# on `model_platform_variants`, added by
+# `trillboard-api/postgres/migrations/20260825032444_add_variant_coordinate_space.sql`
+# (`output_layout`, `box_units`, `box_scale_to_pixels`) — the registry row is the
+# authority and this is the copy the service reads, because there is no
+# PostgreSQL on a shop PC. The two sets must stay identical: a value the
+# registry accepts and this build drops is a variant that publishes and then
+# cannot be decoded, and a value this build accepts and the registry rejects is
+# a model that can never ship. `test_decode.py` pins both sets against that
+# migration's CHECK constraints by name.
+
+#: `dets` + `labels`, the shipped RF-DETR contract. Decoded by
+#: `session.postprocess` (top-k over sigmoid'd logits, cxcywh normalised).
+RFDETR_DETS_LABELS = "rfdetr_dets_labels"
+#: `[1, 4+nc, A]`, the raw Ultralytics head. Scores already sigmoid, boxes
+#: cxcywh in model-input units, and it NEEDS non-maximum suppression.
+ANCHOR_4_PLUS_NC = "anchor_4_plus_nc"
+#: `[1, N, 6]`, rows of x1,y1,x2,y2,score,cls. Already suppressed.
+END2END_N_6 = "end2end_n_6"
+
+OUTPUT_LAYOUTS = frozenset({RFDETR_DETS_LABELS, ANCHOR_4_PLUS_NC, END2END_N_6})
+
+#: The box channels are already in pixels of the model input.
+BOX_UNITS_PIXELS = "pixels"
+#: They are 0..1 and must be multiplied by `box_scale_to_pixels`.
+BOX_UNITS_NORMALIZED = "normalized"
+
+BOX_UNITS = frozenset({BOX_UNITS_PIXELS, BOX_UNITS_NORMALIZED})
+
+
+@dataclass(frozen=True)
+class VariantContract:
+    """What one ARTIFACT's output numbers mean. Declared, never inferred.
+
+    NAMED FOR THE FORMAT, NOT THE MODEL, and that is the entire point.
+    `model_platform_variants` is keyed `(model_id, format)` because the answer
+    differs by format for identical weights: Ultralytics wraps a `task=detect`,
+    `end2end=False` TFLite export in `_NormalizeCoords`, dividing the four box
+    channels by (W, H). Measured across all 17 committed LiteRT twins, 16 emit
+    ONNX boxes in pixels 0..640 and LiteRT boxes in 0..1 — the same weights,
+    640x apart — while their class channels agree to 5.5e-06. So a contract
+    carried across from a sibling format is wrong on 94% of the library, and
+    every shape, dtype and score check passes on the pair.
+    `queue_supermarket`, the one `end2end_n_6` twin, is pixels on both sides;
+    an end2end head emits pixels everywhere, which is why the exemption is real
+    and why this cannot be a property of the model.
+
+    THERE IS NO DEFAULT AND THERE MUST NOT BE. A default would be a guess about
+    an artifact nobody measured, and ON AN UNPADDED FRAME the wrong guess is
+    perfectly silent. Measured on `ppe_keremberke_v8n` over 200 frames resized
+    square, declaring a normalised artifact `pixels` kept all 707 detections,
+    dropped none, and changed nothing but the boxes: zero label mismatches,
+    `max |confidence delta|` 0.0 EXACTLY, widths a clean 639.9987-640.0012x too
+    small.
+
+    It is NOT silent on a letterboxed frame, and the difference is `decode.
+    _to_frame_pixels` subtracting the padding before it clips: the same 640x-small
+    boxes land at a negative offset, clip to zero extent, and every one is dropped
+    as degenerate — 848 of 848 on the same frames as submitted. So the failure is
+    loud exactly when the camera happens to be padded and silent when it does not,
+    which is not a property anything may rely on to notice.
+    `test_session.TestWrongBoxUnitsAtTheWire` pins both regimes.
+
+    `run_candidate.py` measures the units from a forward pass over real frames and
+    REFUSES the run when the ratio lands between the two bands; this is where that
+    measurement gets written down.
+    """
+
+    #: Which decode reads this artifact. One of `OUTPUT_LAYOUTS`.
+    output_layout: str
+    #: `pixels` or `normalized`.
+    box_units: str
+    #: Multiply a box coordinate by this to get pixels of the model input. 1.0
+    #: for `pixels`, the input edge (e.g. 640.0) for `normalized`. STORED rather
+    #: than derived from imgsz because a non-square input has two scales and the
+    #: consumer must not have to work out which one it needs — the same reason
+    #: the column exists rather than a boolean.
+    box_scale_to_pixels: float
+
+    def __post_init__(self) -> None:
+        if self.output_layout not in OUTPUT_LAYOUTS:
+            raise ValueError(
+                f"output_layout {self.output_layout!r} is not one of {sorted(OUTPUT_LAYOUTS)}; "
+                "refusing rather than decoding a tensor by guessing what its axes mean"
+            )
+        if self.box_units not in BOX_UNITS:
+            raise ValueError(
+                f"box_units {self.box_units!r} is not one of {sorted(BOX_UNITS)}. A variant that "
+                "cannot say what its coordinates mean is as unusable as one with a NULL checksum: "
+                "the consumer cannot tell it is wrong"
+            )
+        # Mirrors `model_platform_variants_box_scale_ck` exactly. A scale without
+        # units, or normalised units without a scale, reads as a declaration and
+        # cannot be acted on.
+        if self.box_units == BOX_UNITS_PIXELS and self.box_scale_to_pixels != 1.0:
+            raise ValueError(
+                f"box_units 'pixels' means the numbers are already pixels, so the scale must be "
+                f"1.0, got {self.box_scale_to_pixels}"
+            )
+        if self.box_units == BOX_UNITS_NORMALIZED and not self.box_scale_to_pixels > 0.0:
+            raise ValueError(
+                f"box_units 'normalized' needs a positive box_scale_to_pixels, got "
+                f"{self.box_scale_to_pixels}"
+            )
+
+
+#: The shipped RF-DETR ONNX export, measured. `detector-score-cards/rfdetr_medium.json`
+#: records max|box| 639.29 over imgsz 640 = 0.9989, so `pixels`.
+RFDETR_MEDIUM_ONNX = VariantContract(
+    output_layout=RFDETR_DETS_LABELS,
+    box_units=BOX_UNITS_PIXELS,
+    box_scale_to_pixels=1.0,
+)
+
 
 @dataclass(frozen=True)
 class ModelVocabulary:
@@ -146,6 +262,19 @@ class ModelVocabulary:
     logit_slots: int
     #: Peak RSS of ONE resident session, in bytes.
     approx_ram_bytes: int
+    #: What the ONNX artifact's numbers MEAN — the box-side copy of this model's
+    #: `('onnx')` row in `model_platform_variants`. NAMED FOR THE FORMAT because
+    #: that table is keyed `(model_id, format)` and the answer genuinely differs
+    #: between them: the LiteRT twin of the same weights is a DIFFERENT row with
+    #: a different `box_units`. `OnnxDetector` is the only consumer and it loads
+    #: ONNX, so a future LiteRT loader must read its own row rather than this
+    #: one — which is what the name is for.
+    #:
+    #: REQUIRED, like the class list and for the same reason: §4 rule 1 is "read
+    #: the class list, never the title", and this is the same instruction one
+    #: axis over. A model whose output layout is inferred is a model whose boxes
+    #: are plausible and wrong.
+    onnx_variant: "VariantContract"
 
     def __post_init__(self) -> None:
         # The model name IS A DIRECTORY NAME — `resolve_model_path` puts the
@@ -200,6 +329,7 @@ RFDETR_MEDIUM = ModelVocabulary(
     slot_names=COCO91_CLASS_NAMES,
     logit_slots=EXPECTED_LOGIT_SLOTS,
     approx_ram_bytes=632 * 1024 * 1024,
+    onnx_variant=RFDETR_MEDIUM_ONNX,
 )
 
 #: Every model this build knows how to label, IN PRIORITY ORDER.
@@ -311,12 +441,21 @@ class ClassIndex:
 
 
 __all__ = [
+    "ANCHOR_4_PLUS_NC",
+    "BOX_UNITS",
+    "BOX_UNITS_NORMALIZED",
+    "BOX_UNITS_PIXELS",
     "BUILTIN_VOCABULARIES",
     "COCO91_CLASS_NAMES",
+    "END2END_N_6",
     "EXPECTED_LOGIT_SLOTS",
+    "OUTPUT_LAYOUTS",
     "PERSON_SLOT",
+    "RFDETR_DETS_LABELS",
     "RFDETR_MEDIUM",
+    "RFDETR_MEDIUM_ONNX",
     "ClassIndex",
     "ModelVocabulary",
+    "VariantContract",
     "normalize_class_name",
 ]

package/deploy/detector/trillboards_detector/loader.py

@@ -264,7 +264,21 @@ class DetectorLoader:
         reason = pinned.get("reason")
         if reason:
             payload["reason"] = reason
-        for key in ("warmup_inference_ms", "loaded_at", "input", "classes", "providers"):
+        # `output_layout` and `preprocessing` are additive, like every key added
+        # here since the first release: the three installers' post-install probes
+        # and the integration test read `state`, and nothing has ever failed on
+        # an unrecognised key. They are worth the two bytes because an operator
+        # reading `curl /health` on a box that answers plausible nonsense needs
+        # to see WHICH decode ran before anything else is worth checking.
+        for key in (
+            "warmup_inference_ms",
+            "loaded_at",
+            "input",
+            "classes",
+            "providers",
+            "output_layout",
+            "preprocessing",
+        ):
             if key in pinned:
                 payload[key] = pinned[key]
         return payload

package/deploy/detector/trillboards_detector/registry.py

@@ -707,6 +707,15 @@ class ModelRegistry:
                     row["input"] = f"{spec.width}x{spec.height}"
                     row["classes"] = spec.num_classes
                     row["providers"] = list(spec.providers)
+                    # WHICH DECODE AND WHICH PREPROCESSING PRODUCED THIS MODEL'S
+                    # NUMBERS. Three layouts now reach this service and their
+                    # preprocessors are not interchangeable, so a confidence with
+                    # no attributable arm is the `agent_version` shape:
+                    # `docs/runbooks/ctv-agent-version-map.md` is a whole runbook
+                    # about one column that nine artifacts write. Cheap: two
+                    # strings already on the spec, read under the same lock.
+                    row["output_layout"] = getattr(spec, "output_layout", None)
+                    row["preprocessing"] = getattr(spec, "preprocessing", None)
                 models[name] = row
 
             # Counted from `present` directly rather than through