Zephyr Sample: fix MobileNetV2 sample input normalization (#23283)

The mv2-ethosu sample scaled uint8 input with (x - 128) / 128, which
maps to [-1, 1]. torchvision's MobileNetV2 is trained with ImageNet
per-channel mean and standard deviation, so a real photograph fed
through the sample was normalized with the wrong transform. This went
unnoticed because the bundled mv2_input.h holds a synthetic tensor, and
noise in produces noise out either way.

Apply ImageNet normalization per channel instead, and add gen_input.py
to regenerate mv2_input.h from a real image. The script resizes to 256,
centre-crops to 224x224, stores uint8 RGB in NCHW order, and records the
float32 torchvision prediction in a comment so the device output has a
reference to compare against.

Verified on an Alif Ensemble E8 DevKit (Cortex-M55 HP + Ethos-U55 256
MAC) with ExecuTorch v1.5.1, Zephyr 4.4.0 and Zephyr SDK 1.0.1. With
INT8 quantization calibrated on 250 ImageNet photographs, the device
top-1 matched the float32 torchvision reference on three of three test
images that the reference classified confidently.

Authored with assistance from Claude Code.

Author: psiddh

zephyr/samples/mv2-ethosu/README.md

@@ -6,6 +6,36 @@ model on the Arm Ethos-U NPU using ExecuTorch within a Zephyr RTOS application.
 The model classifies a static RGB test input tensor with shape `[1, 3, 224, 224]`
 (NCHW) into one of 1000 ImageNet classes and prints the top-5 predictions.
 
+## Using a real image
+
+The bundled `src/mv2_input.h` holds a synthetic tensor, not a photograph. It
+exercises the full runtime path (load, delegate, execute) but the predictions it
+produces are meaningless. To classify something real, regenerate the header:
+
+```bash
+python gen_input.py your_photo.jpg
+```
+
+The script resizes to 256, centre-crops to 224x224, stores the result as uint8
+RGB in NCHW order, and records what float32 torchvision MobileNetV2 predicts.
+Rebuild and reflash after regenerating.
+
+Two things are required for that recorded prediction to be a valid reference.
+Export with `--model_name=mv2` rather than the `mv2_untrained` used in the
+commands below, since untrained weights produce arbitrary class IDs. And supply
+representative calibration data with `--calibration_data`, because the default
+calibrates on the model's example input, which is random:
+
+```bash
+python -m executorch.backends.arm.scripts.aot_arm_compiler \
+    --model_name=mv2 --quantize --delegate \
+    --target=ethos-u55-256 --calibration_data=<dir-of-pt-tensors> \
+    --output=mv2_ethosu.pte
+```
+
+ImageNet has no "person" class, so portraits return an unrelated label with low
+confidence. Photographs of animals, objects, food and vehicles work well.
+
 ## Prerequisites
 
 - Zephyr SDK with ExecuTorch module enabled

zephyr/samples/mv2-ethosu/gen_input.py

@@ -0,0 +1,102 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Generate src/mv2_input.h from a real image.
+
+The sample ships with a synthetic input so it can run without bundling an
+image. That exercises the runtime but produces meaningless predictions. Point
+this script at a photograph to get a header the device can actually classify:
+
+    python gen_input.py cat.jpg
+
+The image is resized to 256, centre-cropped to 224x224 and stored as uint8 RGB
+in NCHW order, matching the normalisation main.cpp applies on device. The
+float32 torchvision prediction is recorded in a comment so the device output
+has a reference to be compared against.
+
+Requires: pillow, torch, torchvision.
+"""
+
+import argparse
+import os
+
+import numpy as np
+import torch
+import torchvision
+from PIL import Image
+from torchvision import transforms
+
+HEADER = os.path.join(os.path.dirname(os.path.abspath(__file__)), "src", "mv2_input.h")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", help="path to a source image")
+    parser.add_argument("-o", "--output", default=HEADER, help="header to write")
+    args = parser.parse_args()
+
+    weights = torchvision.models.MobileNet_V2_Weights.IMAGENET1K_V1
+    model = torchvision.models.mobilenet_v2(weights=weights).eval()
+    categories = weights.meta["categories"]
+
+    crop = transforms.Compose([transforms.Resize(256), transforms.CenterCrop(224)])
+    normalize = transforms.Compose(
+        [
+            transforms.ToTensor(),
+            transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+        ]
+    )
+
+    image = crop(Image.open(args.image).convert("RGB"))
+    with torch.no_grad():
+        logits = model(normalize(image).unsqueeze(0))[0]
+    probs = torch.softmax(logits, dim=0)
+    top1 = int(torch.argmax(logits))
+    print(
+        f"{os.path.basename(args.image)} -> class {top1} "
+        f"({categories[top1]}) {probs[top1].item() * 100:.1f}%"
+    )
+
+    chw = np.transpose(np.asarray(image, dtype=np.uint8), (2, 0, 1)).copy()
+    raw = chw.tobytes()
+
+    lines = [
+        "/* Copyright (c) Meta Platforms, Inc. and affiliates.",
+        " * All rights reserved.",
+        " *",
+        " * This source code is licensed under the BSD-style license found in the",
+        " * LICENSE file in the root directory of this source tree.",
+        " *",
+        f" * Generated by gen_input.py from {os.path.basename(args.image)}.",
+        " * Resized 256, centre-cropped 224, uint8 RGB in NCHW order.",
+        " *",
+        f" * float32 torchvision MobileNetV2 predicts class {top1} "
+        f"({categories[top1]}) at {probs[top1].item() * 100:.1f}%.",
+        " */",
+        "",
+        "#ifndef MV2_INPUT_H",
+        "#define MV2_INPUT_H",
+        "",
+        "#include <stdint.h>",
+        "",
+        f"#define MV2_INPUT_SIZE {len(raw)}",
+        f"#define MV2_HOST_TOP1 {top1}",
+        f'#define MV2_HOST_LABEL "{categories[top1]}"',
+        "",
+        "static const uint8_t mv2_input_data[MV2_INPUT_SIZE] __attribute__((aligned(4)))",
+        '__attribute__((section(".rodata.mv2_input"))) = {',
+    ]
+    for i in range(0, len(raw), 16):
+        lines.append("    " + ",".join(f"0x{b:02x}" for b in raw[i : i + 16]) + ",")
+    lines += ["};", "", "#endif /* MV2_INPUT_H */"]
+
+    with open(args.output, "w") as handle:
+        handle.write("\n".join(lines) + "\n")
+    print(f"wrote {args.output}")
+
+
+if __name__ == "__main__":
+    main()

zephyr/samples/mv2-ethosu/src/main.cpp

@@ -90,6 +90,11 @@ unsigned char* ethosu_fast_scratch = dedicated_sram;
 
 namespace {
 
+// Preprocessing constants for torchvision's ImageNet-trained MobileNetV2.
+constexpr size_t kNumChannels = 3;
+constexpr float kImageNetMean[kNumChannels] = {0.485f, 0.456f, 0.406f};
+constexpr float kImageNetStd[kNumChannels] = {0.229f, 0.224f, 0.225f};
+
 Error prepare_input_tensors(
     Method& method,
     MemoryAllocator& allocator,
@@ -147,9 +152,19 @@ Error prepare_input_tensors(
           Info,
           "Converting uint8 input (%lu elements) to float32",
           static_cast<unsigned long>(input_size));
+      // torchvision MobileNetV2 is trained with ImageNet normalisation, so the
+      // uint8 image has to be scaled to [0,1] and then standardised per
+      // channel. The tensor is NCHW, so each channel is a contiguous plane.
       float* float_data = static_cast<float*>(data_ptr);
-      for (size_t j = 0; j < input_size; j++) {
-        float_data[j] = (static_cast<float>(input_data[j]) - 128.0f) / 128.0f;
+      const size_t plane = input_size / kNumChannels;
+      for (size_t c = 0; c < kNumChannels; c++) {
+        const float mean = kImageNetMean[c];
+        const float stddev = kImageNetStd[c];
+        for (size_t j = 0; j < plane; j++) {
+          const size_t idx = c * plane + j;
+          float_data[idx] =
+              ((static_cast<float>(input_data[idx]) / 255.0f) - mean) / stddev;
+        }
       }
     } else if (input_size == tensor_meta->nbytes()) {
       ET_LOG(