source: centred INT8 calibration; keep the pre-2026-10-08 converter for the IRs that kept it

source/README.md

@@ -80,11 +80,20 @@ python build-camstack-models.py --family yolo26 --calib-dir ./val2017
 
 The recipe takes the first N images in file-name order: 128 for YOLO26, 300
 for YOLOv9, as recorded in each IR's `rt_info`. Each image is letterboxed to
-the model's input size with grey (114) padding and scaled to [0, 1], the way
-CamStack feeds the model at runtime. `--calib-samples` overrides N. An IR does
-not record WHICH images calibrated it, so a different set gives an equivalent
-INT8 model, not a bit-identical one. Without calibration images the INT8 files
-are skipped and the run says so.
+the model's input size, CENTRED with grey (114) padding, and scaled to [0, 1],
+the way CamStack feeds the model at runtime. `--calib-samples` overrides N. An
+IR does not record WHICH images calibrated it, so a different set gives an
+equivalent INT8 model, not a bit-identical one. Without calibration images the
+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.
 
 ## Licences
 

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

@@ -0,0 +1,170 @@
+"""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")
+
+
+def quantize_openvino_int8(
+    onnx_path: str, out_xml: str, calib_dir: str, imgsz: int, max_samples: int = 300
+) -> None:
+    import cv2
+    import numpy as np
+    import openvino as ov
+    import nncf
+
+    calib = Path(calib_dir)
+    images = sorted(
+        p for p in calib.iterdir() if p.suffix.lower() in {".jpg", ".jpeg", ".png"}
+    )[:max_samples]
+    if not images:
+        raise ValueError(f"no calibration images in {calib_dir}")
+
+    def preprocess(path: Path):
+        img = cv2.imread(str(path))
+        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        h, w = img.shape[:2]
+        scale = imgsz / max(h, w)
+        nh, nw = int(round(h * scale)), int(round(w * scale))
+        resized = cv2.resize(img, (nw, nh))
+        canvas = np.full((imgsz, imgsz, 3), 114, dtype=np.uint8)
+        canvas[:nh, :nw] = resized
+        chw = canvas.transpose(2, 0, 1).astype(np.float32) / 255.0
+        return chw[np.newaxis, ...]
+
+    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

@@ -28,6 +28,11 @@ Usage:
   python build-camstack-models.py --model yolo26n --imgsz 416 \
       --openvino fp16,int8 --calib-samples 128
 
+  # A fine-tuned local checkpoint, INT8-calibrated on your own frames (a
+  # folder of images, or an extracted retrain export: its frames/ are used):
+  python build-camstack-models.py --checkpoint runs/train/weights/best.pt \
+      --imgsz 640 --openvino fp16,int8 --calib-dir ./my-export --name custom-yolov9m-640
+
 Outputs land in `--out` (default ./exported-models) under the MIRROR's paths,
 e.g. exported-models/objectDetection/yolo26/openvino/camstack-yolo26n-320-int8.xml.
 
@@ -38,17 +43,33 @@ Formats:
   openvino  convert_lib.export_openvino: ov.convert_model(ONNX) + ov.save_model
             (compress_to_fp16 per precision) — never the Ultralytics OV exporter
   int8      convert_lib.quantize_openvino_int8: NNCF post-training quantisation
-            of the ONNX, calibrated on the first N images (sorted by file name)
-            of --calib-dir (default $CAMSTACK_CALIB_DIR or ./calibration-images)
+            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)
 
 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
 set is COCO val2017: unpack http://images.cocodataset.org/zips/val2017.zip and
 point --calib-dir at it — the recipe's N is taken in file-name order. Images are letterboxed to
-the recipe's input size with grey (114) padding and scaled to [0, 1], exactly
-as the CamStack runtime feeds the model. A different calibration set yields an
+the recipe's input size, CENTRED with grey (114) padding, and scaled to [0, 1],
+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,
+    yolo26{s,m,l}-320
+The top-left padding (`canvas[:nh, :nw]`, sizes by round()) reproduces the
+hosted yolov9m-640 IR bit for bit.
+
 Toolchain: each recipe names the Ultralytics / torch / coremltools / OpenVINO
 versions its hosted files record. Other versions produce the same model with a
 possibly different graph layout; the script warns when they differ.
@@ -128,7 +149,8 @@ class Recipe:
     imgsz: int
     toolchain: Toolchain
     # The PyTorch checkpoint: an Ultralytics asset id (`yolo26n` -> yolo26n.pt,
-    # auto-downloaded by Ultralytics).
+    # auto-downloaded by Ultralytics), or — `--checkpoint` — the absolute path
+    # of a local `.pt` (a fine-tune), used verbatim.
     checkpoint: str
     onnx: Optional[OnnxExport]
     coreml: Optional[CoremlExport]
@@ -304,6 +326,8 @@ def place(src: Path, dest: Path) -> Path:
 
 
 def checkpoint_path(recipe: Recipe) -> str:
+    if recipe.checkpoint.endswith('.pt'):
+        return recipe.checkpoint  # a local checkpoint (--checkpoint), verbatim
     return f'{recipe.checkpoint}.pt'  # Ultralytics downloads its own assets
 
 
@@ -468,13 +492,18 @@ def run_step(report: Report, label: str, step: Callable[[], object]) -> object:
 
 
 def build(recipe: Recipe, formats: set[str], out: Path, calib_dir: Path,
-          calib_samples: Optional[int], verify_coreml: bool, report: Report) -> None:
+          calib_samples: Optional[int], verify_coreml: bool, report: Report,
+          reuse_onnx: bool = False) -> None:
     print('\n' + '=' * 70 + f'\n{recipe.name}  ({recipe.folder}, {recipe.imgsz}×{recipe.imgsz})\n' + '=' * 70)
     if recipe.note:
         print(f'  {recipe.note}')
     warn_toolchain(recipe)
     onnx_path: Optional[Path] = None
-    if formats & {'onnx', 'openvino'} and recipe.onnx:
+    existing_onnx = out / recipe.folder / 'onnx' / f'{recipe.name}.onnx'
+    if reuse_onnx and recipe.onnx and existing_onnx.is_file():
+        print(f'  → ONNX: reusing {existing_onnx} (--reuse-onnx)')
+        onnx_path = existing_onnx
+    elif formats & {'onnx', 'openvino'} and recipe.onnx:
         result = run_step(report, f'{recipe.name} onnx', lambda: build_onnx(recipe, out))
         onnx_path = result if isinstance(result, Path) else None
     if 'coreml' in formats and recipe.coreml is not None:
@@ -496,12 +525,23 @@ def adhoc_recipe(args: argparse.Namespace) -> Recipe:
     bad = [p for p in precisions if p not in ('fp32', 'fp16', 'int8')]
     if bad:
         sys.exit(f'--openvino accepts fp32, fp16, int8; got {bad}')
-    name = args.name or f'camstack-{args.model}-{args.imgsz}'
+    if args.checkpoint is not None:
+        local = Path(args.checkpoint).expanduser().resolve()
+        if not local.is_file() or local.suffix != '.pt':
+            sys.exit(f'--checkpoint {args.checkpoint}: not a .pt file')
+        checkpoint, stem = str(local), local.stem
+    else:
+        checkpoint, stem = args.model, args.model
+    name = args.name or f'camstack-{stem}-{args.imgsz}'
+    coreml_dynamic = args.dynamic and args.checkpoint is None
     return Recipe(
         name=name, folder=args.folder, imgsz=args.imgsz,
-        toolchain=Toolchain('any', 'any', 'any', 'any'), checkpoint=args.model,
+        toolchain=Toolchain('any', 'any', 'any', 'any'), checkpoint=checkpoint,
         onnx=OnnxExport(dynamic=args.dynamic, opset=args.opset),
-        coreml=CoremlExport(dynamic=args.dynamic, batch=16 if args.dynamic else 1, half=True),
+        # A local checkpoint's architecture is not in its name, so the D742
+        # check cannot tell a YOLO26 fine-tune: its CoreML export is always
+        # static, the shape every architecture loads.
+        coreml=CoremlExport(dynamic=coreml_dynamic, batch=16 if coreml_dynamic else 1, half=True),
         openvino=tuple(OpenvinoOutput(f'-{p}', p) for p in precisions),
         calib_samples=args.calib_samples or 300,
     )
@@ -572,8 +612,16 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     p.add_argument('--verify-coreml', action='store_true',
                    help='predict N=1 and N=4 on each flexible-batch CoreML package (in a child process)')
     p.add_argument('--calib-samples', type=int, help="override the recipe's INT8 calibration image count")
+    p.add_argument('--reuse-onnx', action='store_true',
+                   help='an ONNX already at its mirror path under --out is used as is, not re-exported: '
+                        'download the hosted ONNX there to re-quantise an IR from the exact graph the '
+                        'mirror serves (no Ultralytics needed)')
     adhoc = p.add_argument_group('ad-hoc build (not a hosted file)')
-    adhoc.add_argument('--model', help='Ultralytics id, e.g. yolo26n, yolov9m, yolo26s-seg')
+    source = adhoc.add_mutually_exclusive_group()
+    source.add_argument('--model', help='Ultralytics id, e.g. yolo26n, yolov9m, yolo26s-seg')
+    source.add_argument('--checkpoint',
+                        help='a local .pt (e.g. a fine-tune), exported exactly like --model; '
+                             'pair with --calib-dir <your frames> for its INT8 IR')
     adhoc.add_argument('--imgsz', type=int, default=640)
     adhoc.add_argument('--name', help='output stem (default camstack-<model>-<imgsz>)')
     adhoc.add_argument('--folder', default='custom')
@@ -584,7 +632,7 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
 
 
 def select(args: argparse.Namespace) -> list[Recipe]:
-    if args.model:
+    if args.model or args.checkpoint:
         return [adhoc_recipe(args)]
     by_name = {r.name: r for r in RECIPES}
     unknown = [v for v in (args.variant or []) if v not in by_name]
@@ -625,7 +673,7 @@ def main(argv: list[str]) -> int:
     report = Report()
     for r in recipes:
         build(r, formats, args.out, args.calib_dir, args.calib_samples,
-              args.verify_coreml, report)
+              args.verify_coreml, report, reuse_onnx=args.reuse_onnx)
     print('\nDone.' + (f' Failed: {report.failed}.' if report.failed else '')
           + (f' Skipped: {report.skipped}.' if report.skipped else ''))
     return 1 if report.failed else 0

source/convert_lib.py

@@ -64,32 +64,61 @@ def validate_openvino_ir(xml_path: str) -> None:
             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 numpy as np
     import openvino as ov
     import nncf
 
-    calib = Path(calib_dir)
-    images = sorted(
-        p for p in calib.iterdir() if p.suffix.lower() in {".jpg", ".jpeg", ".png"}
-    )[:max_samples]
-    if not images:
-        raise ValueError(f"no calibration images in {calib_dir}")
+    images = calibration_images(calib_dir, max_samples)
 
     def preprocess(path: Path):
         img = cv2.imread(str(path))
-        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
-        h, w = img.shape[:2]
-        scale = imgsz / max(h, w)
-        nh, nw = int(round(h * scale)), int(round(w * scale))
-        resized = cv2.resize(img, (nw, nh))
-        canvas = np.full((imgsz, imgsz, 3), 114, dtype=np.uint8)
-        canvas[:nh, :nw] = resized
-        chw = canvas.transpose(2, 0, 1).astype(np.float32) / 255.0
-        return chw[np.newaxis, ...]
+        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)