source: D798 INT8 recipe (Detect head in float, MIXED, full bias correction); archive the 2026-10-08 convert_lib

source/README.md

@@ -89,11 +89,44 @@ INT8 files are skipped and the run says so.
 Until 2026-10-08 the calibration padded TOP-LEFT. On that date every INT8 IR
 was re-quantised centred from the hosted ONNX (`--reuse-onnx`, OpenVINO
 2026.2.1 + NNCF 3.2.0) and measured against the old one. 13 replaced the old
-IR; 8 measured worse and were kept, so they still carry the top-left
-calibration. `build-camstack-models.py` lists which is which. The kept ones are
-reproduced by [`archive/convert_lib-before-2026-10-08.py`](archive/convert_lib-before-2026-10-08.py),
-which rebuilds the hosted `yolov9m-640` INT8 IR bit for bit. The replaced old
-IRs are under `archive/2026-10-08-int8-topleft-calibration/` at the mirror root.
+IR, 8 measured worse and were kept. The replaced IRs are under
+`archive/2026-10-08-int8-topleft-calibration/` at the mirror root.
+[`archive/convert_lib-before-2026-10-08.py`](archive/convert_lib-before-2026-10-08.py)
+reproduces the top-left ones; it rebuilds the hosted `yolov9m-640` INT8 IR bit
+for bit.
+
+### INT8 recipe (since 2026-10-09)
+
+`convert_lib.quantize_openvino_int8` keeps the YOLO Detect head in float.
+
+- **YOLOv9:** the head's own ops stay float: the DFL softmax and the box
+  decode (anchor ± distance, ×stride, class sigmoid). The conv branches stay
+  INT8.
+- **YOLO26:** the whole end-to-end head stays float.
+- **Every model:** NNCF preset MIXED and full bias correction.
+
+This follows the Ultralytics OpenVINO INT8 exporter and NNCF's YOLO26 example.
+The previous recipe quantised the decode, which put box coordinates on a
+256-level grid.
+
+**Result:**
+
+- On all 8 YOLOv9 IRs, mAP50-95 went from 0.01–0.18 below float to within noise
+  of it, at NPU latency within 1 %.
+- 14 IRs were replaced in place: every `yolov9*-int8`, `yolo26{n,s,l}-int8`,
+  `yolo26n-320-int8` and `yolo26{n,s}-256-int8`.
+- The previous files are under `archive/2026-10-09-int8-before-head-float-recipe/`
+  at the mirror root.
+
+Seven YOLO26 IRs were kept, because the float head cost 11–22 % latency on the
+Intel iGPU:
+
+- `yolo26{m,x}-int8` and `yolo26{m,l}-256-int8` (centred) are reproduced by
+  [`archive/convert_lib-before-2026-10-09.py`](archive/convert_lib-before-2026-10-09.py);
+- `yolo26{s,m,l}-320-int8` (top-left) are reproduced by
+  `archive/convert_lib-before-2026-10-08.py`.
+
+`build-camstack-models.py` lists which IR carries which recipe.
 
 ## Licences
 

source/archive/convert_lib-before-2026-10-09.py

@@ -0,0 +1,199 @@
+"""Shared model converter: ONNX -> OpenVINO IR (fp16/int8/CoreML) + validation.
+
+Used by both the runtime model-convert cap (convert.py) and the offline
+scripts/build-camstack-models.py. Conversion ALWAYS starts from ONNX via
+ov.convert_model (never the Ultralytics OV exporter, which emits unnamed
+tensors that break the runtime's named-output postprocess)."""
+from __future__ import annotations
+import os
+from pathlib import Path
+
+# OpenVINO sizes the pool that COMPILES a model to the machine's core count and
+# TBB never gives those workers back. A container cgroup counts THREADS, and
+# this one has been measured refusing forks against `pids.max=2048` — so a
+# conversion running beside the live pools must not spend `nproc` of the budget
+# just to validate an IR. Same knob, same env var and same default (4) as
+# OV_COMPILATION_NUM_THREADS in
+# packages/addon-pipeline/python/inference_pool.py, which carries the
+# measurement; this process is short-lived, so the saving here is a spike, not
+# the 214-thread accumulation that motivated the bound. 0 disables it.
+_OV_COMPILATION_NUM_THREADS: int = 4
+try:
+    _OV_COMPILATION_NUM_THREADS = int(
+        os.environ.get("CAMSTACK_OV_COMPILATION_THREADS", "4")
+    )
+except ValueError:
+    _OV_COMPILATION_NUM_THREADS = 4
+
+
+def export_openvino(onnx_path: str, out_xml: str, *, fp16: bool) -> None:
+    import openvino as ov
+    ov_model = ov.convert_model(onnx_path)
+    Path(out_xml).parent.mkdir(parents=True, exist_ok=True)
+    ov.save_model(ov_model, out_xml, compress_to_fp16=fp16)
+
+
+def validate_openvino_ir(xml_path: str) -> None:
+    """Compile the IR and assert every input/output tensor carries a name.
+    This is the exact defect (unnamed tensors) that broke 14/26 catalog IRs."""
+    import openvino as ov
+    core = ov.Core()
+    model = core.read_model(xml_path)
+    # Bound the compilation pool (see _OV_COMPILATION_NUM_THREADS). A plugin
+    # REJECTS a property it does not know, and this compile is the VALIDATION —
+    # it must never fail for a reason that has nothing to do with the IR, so a
+    # refused property falls back to the unbounded compile rather than
+    # reporting a bad model.
+    if _OV_COMPILATION_NUM_THREADS > 0:
+        try:
+            compiled = core.compile_model(
+                model,
+                "CPU",
+                {"COMPILATION_NUM_THREADS": _OV_COMPILATION_NUM_THREADS},
+            )
+        except Exception:
+            compiled = core.compile_model(model, "CPU")
+    else:
+        compiled = core.compile_model(model, "CPU")
+    for port in list(compiled.inputs) + list(compiled.outputs):
+        try:
+            name = port.get_any_name()
+        except Exception as exc:  # ov raises when a tensor has no names
+            raise ValueError(f"IR {xml_path} has an unnamed tensor: {exc}") from exc
+        if not name:
+            raise ValueError(f"IR {xml_path} has an empty-named tensor")
+
+
+CALIBRATION_SUFFIXES = {".jpg", ".jpeg", ".png"}
+
+
+def calibration_images(calib_dir: str, max_samples: int) -> "list[Path]":
+    """The first ``max_samples`` calibration images of ``calib_dir``, in path order.
+
+    A flat folder (COCO val2017) is read exactly as before: file-name order. A
+    folder is walked recursively, so the operator's own frames work as they
+    come. The hub's annotated export (a folder holding ``annotations.json``)
+    calibrates on its ``frames/`` only: its ``crops/`` are classifier inputs,
+    not what a root detector is fed.
+    """
+    root = Path(calib_dir)
+    if not root.is_dir():
+        raise ValueError(f"calibration folder {calib_dir} does not exist")
+    base = root / "frames" if (root / "annotations.json").is_file() else root
+    images = sorted(
+        (p for p in base.rglob("*") if p.is_file() and p.suffix.lower() in CALIBRATION_SUFFIXES),
+        key=lambda p: p.relative_to(base).as_posix(),
+    )[:max_samples]
+    if not images:
+        raise ValueError(f"no calibration images in {calib_dir}")
+    return images
+
+
+def letterbox_for_calibration(rgb, imgsz: int):
+    """``rgb`` (HxWx3 uint8) → ``[1,3,imgsz,imgsz]`` float32 in [0,1], letterboxed
+    as the inference pool does (``inference_pool.letterbox_image``): scale by the
+    long side, truncate, CENTRE with grey 114 padding."""
+    import cv2
+    import numpy as np
+
+    h, w = rgb.shape[:2]
+    scale = imgsz / max(h, w)
+    nw, nh = int(w * scale), int(h * scale)
+    pad_x, pad_y = (imgsz - nw) // 2, (imgsz - nh) // 2
+    resized = rgb if (nw, nh) == (w, h) else cv2.resize(rgb, (nw, nh), interpolation=cv2.INTER_LINEAR)
+    canvas = np.full((imgsz, imgsz, 3), 114, dtype=np.uint8)
+    canvas[pad_y : pad_y + nh, pad_x : pad_x + nw] = resized
+    chw = canvas.transpose(2, 0, 1).astype(np.float32) / 255.0
+    return chw[np.newaxis, ...]
+
+
+def quantize_openvino_int8(
+    onnx_path: str, out_xml: str, calib_dir: str, imgsz: int, max_samples: int = 300
+) -> None:
+    import cv2
+    import openvino as ov
+    import nncf
+
+    images = calibration_images(calib_dir, max_samples)
+
+    def preprocess(path: Path):
+        img = cv2.imread(str(path))
+        return letterbox_for_calibration(cv2.cvtColor(img, cv2.COLOR_BGR2RGB), imgsz)
+
+    dataset = nncf.Dataset(images, lambda p: preprocess(p))
+    ov_model = ov.convert_model(onnx_path)
+    quantized = nncf.quantize(ov_model, dataset, subset_size=len(images))
+    Path(out_xml).parent.mkdir(parents=True, exist_ok=True)
+    ov.save_model(quantized, out_xml)
+
+
+def export_coreml_from_onnx(
+    onnx_path: str,
+    out_pkg: str,
+    imgsz: int,
+    *,
+    input_shape: "tuple[int, ...] | None" = None,
+    fp32: bool = False,
+) -> None:
+    """ONNX -> CoreML mlpackage (darwin only).
+
+    Modern coremltools (>=6) dropped the ONNX frontend entirely — ``ct.convert``
+    only accepts TensorFlow / PyTorch / MIL sources, so feeding it an ``.onnx``
+    raises "Unable to determine the type of the model". We bridge through
+    PyTorch: ``onnx2torch`` rebuilds the ONNX graph as an ``nn.Module``, we trace
+    it with a representative image input, then coremltools converts the
+    TorchScript. Image models are NCHW ``(1, 3, imgsz, imgsz)``.
+
+    ``input_shape`` overrides that square-NCHW assumption for models whose input
+    is neither square nor channels-first — the plate recognizer is NHWC
+    ``(1, 64, 128, 3)``. Without it the trace runs on a wrongly-shaped tensor and
+    either throws deep inside the graph or, worse, produces a package whose
+    declared input silently disagrees with the real one. ``imgsz`` stays the
+    positional contract for every existing caller.
+
+    ``fp32`` keeps full precision instead of coremltools' default fp16 weights.
+    Detectors and embedders absorb fp16 — a box moves a fraction of a pixel, a
+    cosine moves 5e-5 — but a RECOGNIZER cannot: its output is an argmax plus a
+    confidence threshold, so a small shift in one softmax flips a stored
+    character or silences a real read. Measured on the plate recognizer, fp16
+    moved the weakest-character probability by up to 0.16 and changed the label
+    on a ground-truthed plate. The default stays fp16 so nothing already
+    published moves.
+
+    Dynamic-shape models (e.g. YOLO) emit ``Shape`` ops that coremltools' Torch
+    converter cannot lower ("Converter is not implemented … 'Shape'"). We first
+    run onnx-simplifier with the input shape pinned, which constant-folds those
+    Shape ops away, so the traced graph is static and convertible.
+    """
+    import coremltools as ct
+    import onnx
+    import torch
+    from onnx2torch import convert as onnx_to_torch
+    from onnxsim import simplify
+
+    shape = list(input_shape) if input_shape is not None else [1, 3, imgsz, imgsz]
+    onnx_model = onnx.load(onnx_path)
+    input_name = onnx_model.graph.input[0].name
+    simplified, ok = simplify(onnx_model, overwrite_input_shapes={input_name: shape})
+    if not ok:
+        simplified = onnx_model  # fall back to the original if simplify bailed
+
+    model = onnx_to_torch(simplified).eval()
+    example = torch.rand(*shape)
+    with torch.no_grad():
+        traced = torch.jit.trace(model, example, strict=False)
+
+    mlmodel = ct.convert(
+        traced,
+        source="pytorch",
+        inputs=[ct.TensorType(name="input", shape=example.shape)],
+        minimum_deployment_target=ct.target.iOS16,
+        **({"compute_precision": ct.precision.FLOAT32} if fp32 else {}),
+    )
+    Path(out_pkg).parent.mkdir(parents=True, exist_ok=True)
+    mlmodel.save(out_pkg)
+
+
+def validate_coreml(pkg_path: str) -> None:
+    import coremltools as ct
+    ct.models.MLModel(pkg_path)  # load; raises if malformed

source/build-camstack-models.py

@@ -45,7 +45,10 @@ Formats:
   int8      convert_lib.quantize_openvino_int8: NNCF post-training quantisation
             of the ONNX, calibrated on the first N images (sorted by path,
             recursively; an export folder's frames/ only) of --calib-dir
-            (default $CAMSTACK_CALIB_DIR or ./calibration-images)
+            (default $CAMSTACK_CALIB_DIR or ./calibration-images). Recipe (D798):
+            preset MIXED, full bias correction, the Detect head in float —
+            its own ops (DFL + box decode) for a YOLOv9 head, all of it for
+            YOLO26's end-to-end head; every conv before it is INT8
 
 INT8 calibration: the hosted INT8 IRs record subset_size 128 (YOLO26) and 300
 (YOLOv9), drawn from COCO; an IR does not record WHICH images. The documented
@@ -56,19 +59,22 @@ exactly as the CamStack runtime feeds the model (the padding sat top-left until
 2026-10-08, which the runtime never does). A different calibration set yields an
 equivalent but not bit-identical IR (NNCF picks ranges from the data).
 
-Which calibration each hosted INT8 IR carries (measured, D739 holdout +
-COCO; docs/benchmarks/2026-10-08-int8-recalibration.md). All were built from
-the HOSTED ONNX with OpenVINO 2026.2.1 + NNCF 3.2.0 on the first N COCO val2017
-images (reproduce with `--reuse-onnx`, the mirror's .onnx placed under --out):
-  centred (this script, since 2026-10-08):
-    yolov9{t,s,m}-320, yolov9s-640, yolo26n-320, yolo26{n,m,l,x} @640,
-    yolo26{n,s,m,l}-256
-  top-left (convert_lib as it was before 2026-10-08 — kept: re-quantising them
-  centred measured WORSE, beyond noise):
-    yolov9m-640, yolov9t-640, yolov9c-320, yolov9c-640, yolo26s @640,
+Which recipe each hosted INT8 IR carries. All were built from the HOSTED ONNX
+with OpenVINO 2026.2.1 + NNCF 3.2.0 on the first N COCO val2017 images
+(reproduce with `--reuse-onnx`, the mirror's .onnx placed under --out):
+  D798 recipe (this script, since 2026-10-09 — MIXED, full bias correction,
+  the Detect head in float; docs/benchmarks/2026-10-09-int8-recipe.md):
+    yolov9{t,s,m,c}-{320,640}, yolo26{n,s,l} @640, yolo26n-320,
+    yolo26{n,s}-256
+  NNCF defaults, centred calibration (convert_lib 2026-10-08 → 2026-10-09,
+  the mirror's source/archive/convert_lib-before-2026-10-09.py — kept: the D798
+  build was more accurate but 11-22 % slower on the Intel iGPU):
+    yolo26{m,x} @640, yolo26{m,l}-256
+  NNCF defaults, top-left calibration (convert_lib before 2026-10-08,
+  source/archive/convert_lib-before-2026-10-08.py — kept, same reason):
     yolo26{s,m,l}-320
-The top-left padding (`canvas[:nh, :nw]`, sizes by round()) reproduces the
-hosted yolov9m-640 IR bit for bit.
+The D798 build reproduces every replaced IR's .bin bit for bit
+(docs/benchmarks/2026-10-09-int8-recipe.md).
 
 Toolchain: each recipe names the Ultralytics / torch / coremltools / OpenVINO
 versions its hosted files record. Other versions produce the same model with a

source/convert_lib.py

@@ -6,7 +6,9 @@ ov.convert_model (never the Ultralytics OV exporter, which emits unnamed
 tensors that break the runtime's named-output postprocess)."""
 from __future__ import annotations
 import os
+import re
 from pathlib import Path
+from typing import Iterable, Optional
 
 # OpenVINO sizes the pool that COMPILES a model to the machine's core count and
 # TBB never gives those workers back. A container cgroup counts THREADS, and
@@ -107,9 +109,55 @@ def letterbox_for_calibration(rgb, imgsz: int):
     return chw[np.newaxis, ...]
 
 
+_HEAD_MODULE = re.compile(r"^(/model\.\d+)/")
+
+
+def detect_head_prefix(ops: "Iterable[tuple[str, str]]") -> "Optional[str]":
+    """The Ultralytics Detect module (``/model.22`` for YOLOv9, ``/model.23``
+    for YOLO26): the module holding the graph's LAST Sigmoid, which is the
+    class-score sigmoid (the Ultralytics exporter finds its head the same way).
+    ``ops`` is ``(friendly_name, type_name)`` in graph order. None when the
+    model is not an Ultralytics export — it is then quantised whole."""
+    last = None
+    for name, kind in ops:
+        if kind == "Sigmoid":
+            last = name
+    match = _HEAD_MODULE.match(last) if last else None
+    return match.group(1) if match else None
+
+
+def is_end_to_end_head(names: "Iterable[str]", head: str) -> bool:
+    """An NMS-free (end-to-end) head — YOLO26's — runs its ``one2one_*`` branches."""
+    return any(n.startswith(f"{head}/one2one") for n in names)
+
+
+def int8_ignored_patterns(head: str, end_to_end: bool) -> "list[str]":
+    """NNCF ignored-scope patterns for the Detect head ``head``.
+
+    - DFL head (YOLOv9): the head's OWN ops stay float — the DFL and the box
+      decode (concat/split, anchor ± distance, ×stride, the class sigmoid). The
+      conv branches (``cv2.*``/``cv3.*``) stay INT8.
+    - End-to-end head (YOLO26): the whole head stays float, its ``one2one``
+      convs included, as NNCF's YOLO26 example keeps it; measured better than
+      the decode alone on YOLO26 (docs/benchmarks/2026-10-09-int8-recipe.md).
+
+    NNCF matches with ``re.match`` — a prefix match — so the own-op pattern is
+    anchored with ``$`` and every pattern ends at a module boundary."""
+    h = re.escape(head)
+    if end_to_end:
+        return [rf"{h}/"]
+    return [rf"{h}/[^/]+$", rf"{h}/dfl/"]
+
+
 def quantize_openvino_int8(
     onnx_path: str, out_xml: str, calib_dir: str, imgsz: int, max_samples: int = 300
 ) -> None:
+    """NNCF post-training INT8. For an Ultralytics detector (D798): preset MIXED
+    (asymmetric activations), full bias correction, and the Detect head in
+    float — its own ops for a DFL head, all of it for an end-to-end one
+    (`int8_ignored_patterns`). Any other model keeps NNCF's defaults. Measured in
+    docs/benchmarks/2026-10-09-int8-recipe.md: the decode in INT8 was where
+    the hosted IRs lost their box precision."""
     import cv2
     import openvino as ov
     import nncf
@@ -122,7 +170,18 @@ def quantize_openvino_int8(
 
     dataset = nncf.Dataset(images, lambda p: preprocess(p))
     ov_model = ov.convert_model(onnx_path)
-    quantized = nncf.quantize(ov_model, dataset, subset_size=len(images))
+    ops = [(op.get_friendly_name(), op.get_type_name()) for op in ov_model.get_ordered_ops()]
+    head = detect_head_prefix(ops)
+    options: dict = {}
+    if head:
+        end_to_end = is_end_to_end_head((name for name, _ in ops), head)
+        options = {
+            "preset": nncf.QuantizationPreset.MIXED,
+            "fast_bias_correction": False,
+            "ignored_scope": nncf.IgnoredScope(patterns=int8_ignored_patterns(head, end_to_end), validate=False),
+        }
+    # Not an Ultralytics detector: NNCF defaults, as before D798 (unmeasured otherwise).
+    quantized = nncf.quantize(ov_model, dataset, subset_size=len(images), **options)
     Path(out_xml).parent.mkdir(parents=True, exist_ok=True)
     ov.save_model(quantized, out_xml)