# examples/espdl/human_face_detect/validation ### [.gitignore](.gitignore) ``` *face_test.* ``` ### [generate_test_images.py](generate_test_images.py) ```python #!/usr/bin/env python3 """ Generate 224×224 raw RGB888 test images for the human_face_detect example. Outputs (written next to this script): face_test.raw -- real face image resized to 224×224 face_test.png -- visual preview no_face_test.raw -- plain sky gradient (no face) no_face_test.png -- visual preview The .raw files are plain packed RGB888 (no header), exactly 224*224*3 = 150528 bytes each. Copy them to the device VFS alongside the model and test script. Usage: pip install Pillow python generate_test_images.py # looks for test1.jpg next to this script python generate_test_images.py --face /path/to/selfie.jpg The face image should contain a clearly visible human face. Any JPEG or PNG works; it will be centre-cropped to square and resized to 224×224 automatically. """ import argparse import os from PIL import Image W, H = 224, 224 _DEFAULT_FACE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "test1.jpg") def make_face_image(source_path: str) -> Image.Image: """Load a face photo and resize to 224×224 RGB for the model.""" if not os.path.isfile(source_path): raise FileNotFoundError( f"Face image not found: {source_path}\n" " Supply a path with --face /path/to/selfie.jpg" ) img = Image.open(source_path).convert("RGB") # Centre-crop to square before resizing so faces don't get stretched w, h = img.size side = min(w, h) left = (w - side) // 2 top = (h - side) // 2 img = img.crop((left, top, left + side, top + side)) img = img.resize((W, H), Image.LANCZOS) return img def make_no_face_image() -> Image.Image: """Create a plain sky-gradient image with no face features.""" img = Image.new("RGB", (W, H)) pixels = img.load() for y in range(H): r = min(255, 100 + y // 3) g = min(255, 150 + y // 5) b = min(255, max(0, 220 - y // 3)) for x in range(W): pixels[x, y] = (r, g, b) return img def save_raw(img: Image.Image, path: str) -> None: data = img.tobytes() # 'RGB' mode → packed, interleaved RGB888 assert len(data) == W * H * 3, f"Unexpected data size {len(data)}" with open(path, "wb") as f: f.write(data) print(f" Saved {path} ({len(data):,} bytes)") png = path.replace(".raw", ".png") img.save(png) print(f" Saved {png} (visual preview)") if __name__ == "__main__": parser = argparse.ArgumentParser(description="Generate ESPDet 224×224 test images") parser.add_argument( "--face", "-f", default=_DEFAULT_FACE, metavar="IMAGE", help="Path to a JPEG/PNG containing a human face (default: test1.jpg next to this script)", ) args = parser.parse_args() out_dir = os.path.dirname(os.path.abspath(__file__)) print(f"Face source: {args.face}") print("Generating face_test.raw ...") save_raw(make_face_image(args.face), os.path.join(out_dir, "face_test.raw")) print("Generating no_face_test.raw ...") save_raw(make_no_face_image(), os.path.join(out_dir, "no_face_test.raw")) print() print("Done.") print(f"Image size: {W}×{H}×3 = {W*H*3:,} bytes each.") print() ``` ### [test_human_face.py](test_human_face.py) ```python """ Human face detection — ESPDet Pico 224×224 on ESP32-S3. Model : espdet_pico_224_224_face.espdl (485 KB, single-stage) Module: espdl (Phase 1b binding — no C++ detection bridge needed) Preprocessing (Python-side): ESPDet normalises with mean = {0,0,0}, std = {255,255,255} float_val = pixel_uint8 / 255.0 int8_val = round(float_val / 2^exponent) = round(pixel * 2^(-exponent) / 255) The model exposes multiple output tensors (score + box heads per stride stage). Run m.summary() on device to see their exact names and shapes; decoding anchor offsets and running NMS can then be added once the format is known. """ import os import math import espdl # --------------------------------------------------------------------------- # Configuration # --------------------------------------------------------------------------- MODEL_FILE = "espdet_pico_224_224_face.espdl" IMAGE_W = 224 IMAGE_H = 224 SCORE_THR = 0.5 # sigmoid threshold for "might be a face" heuristic # --------------------------------------------------------------------------- # Helpers # --------------------------------------------------------------------------- def _quantize_rgb(raw_bytes, exponent): """Convert uint8 RGB888 bytes to signed-INT8 for ESPDet (mean=0, std=255). Uses integer arithmetic only — avoids float per-pixel for MicroPython speed. int8 = round(pixel * 2^(-exponent) / 255) With a negative exponent like -7: scale_num = 128 (= 2^7), scale_den = 255 pixel=255 → (255*128 + 127)//255 = 128 → clamped to 127 pixel=0 → (0 +127)//255 = 0 """ if exponent <= 0: scale_num = 1 << (-exponent) scale_den = 255 else: scale_num = 1 scale_den = 255 * (1 << exponent) half = scale_den >> 1 # round(x) ≈ (x*2 + den) // (2*den) out = bytearray(len(raw_bytes)) for i, p in enumerate(raw_bytes): v = (p * scale_num + half) // scale_den if v > 127: v = 127 elif v < -128: v = -128 out[i] = v & 0xFF # store unsigned; tensor reads as INT8 return bytes(out) def _dequant_max(tensor_bytes, exponent): """Return the maximum dequantised float across a signed-INT8 tensor.""" mx = -128 for b in tensor_bytes: s = b if b < 128 else b - 256 # unsigned → signed if s > mx: mx = s return mx * (2.0 ** exponent) def _dequant_range(tensor_bytes, exponent): """Return (min_f, max_f) of a signed-INT8 tensor.""" mn, mx = 127, -128 for b in tensor_bytes: s = b if b < 128 else b - 256 if s < mn: mn = s if s > mx: mx = s scale = 2.0 ** exponent return mn * scale, mx * scale def _is_score_tensor(name): """Return True if the tensor name looks like a detection score head. ESPDet names score outputs 'score0', 'score1', ... and box outputs 'box0', 'box1', ... Applying sigmoid to box offsets is meaningless; only score tensors represent face-detection confidence. """ n = name.lower() return n.startswith("score") or n.endswith("score") or "_score" in n or "cls" in n def _sigmoid(x): try: return 1.0 / (1.0 + math.exp(-x)) except OverflowError: return 0.0 if x < 0 else 1.0 # --------------------------------------------------------------------------- # Load model # --------------------------------------------------------------------------- print("=" * 55) print("Human Face Detection — ESPDet Pico 224×224") print("=" * 55) print() print("Loading model:", MODEL_FILE) with open(MODEL_FILE, "rb") as _f: _model_bytes = _f.read() print(" {} bytes ({:.1f} KB)".format(len(_model_bytes), len(_model_bytes) / 1024)) espdl.set_log_level(espdl.LOG_INFO) m = espdl.Model(_model_bytes) del _model_bytes # release heap before inference print(" ", m) print() # --------------------------------------------------------------------------- # Inspect I/O tensors # --------------------------------------------------------------------------- n_in = m.input_count() n_out = m.output_count() print("Inputs: {}".format(n_in)) for i in range(n_in): info = m.input_info(i) print(" [{i}] {name} shape={shape} dtype={dtype} " "bytes={bytes} exp={exponent}".format(i=i, **info)) print("Outputs: {}".format(n_out)) for i in range(n_out): info = m.output_info(i) print(" [{i}] {name} shape={shape} bytes={bytes} " "exp={exponent}".format(i=i, **info)) print() print("--- model.summary() ---") m.summary() print("--- end summary ---") print() # --------------------------------------------------------------------------- # Smoke test — all-zero input (just verify the pipeline doesn't crash) # --------------------------------------------------------------------------- _in_info = m.input_info(0) _in_bytes = _in_info["bytes"] _in_exp = _in_info["exponent"] print("Smoke test: {} bytes of zeros (exponent={})".format(_in_bytes, _in_exp)) _zero = bytes(_in_bytes) _outputs = m.run_all(_zero) print(" Inference OK — {} output tensor(s)".format(len(_outputs))) for i, out in enumerate(_outputs): info = m.output_info(i) if _is_score_tensor(info["name"]): max_f = _dequant_max(out, info["exponent"]) print(" out[{}] '{}' (score): {} bytes max_score_sigmoid={:.4f}".format( i, info["name"], len(out), _sigmoid(max_f))) else: mn_f, mx_f = _dequant_range(out, info["exponent"]) print(" out[{}] '{}' (box): {} bytes dequant=[{:.3f}, {:.3f}]".format( i, info["name"], len(out), mn_f, mx_f)) print() # --------------------------------------------------------------------------- # Image inference (if test images are present) # --------------------------------------------------------------------------- _test_images = ["face_test.raw", "no_face_test.raw"] _found_any = False for img_file in _test_images: try: with open(img_file, "rb") as _f: raw = _f.read() _found_any = True except OSError: print("Skipping {} (not found).".format(img_file)) print(" Run generate_test_images.py on the host and copy the .raw files here.") continue expected = IMAGE_W * IMAGE_H * 3 if len(raw) != expected: print("ERROR: {} is {} bytes (expected {})".format( img_file, len(raw), expected)) continue print("--- {} ---".format(img_file)) print(" Quantizing {} bytes (this takes ~1-2 s in Python)...".format(expected)) quant = _quantize_rgb(raw, _in_exp) print(" Running inference...") outputs = m.run_all(quant) any_face = False for i, out in enumerate(outputs): info = m.output_info(i) if _is_score_tensor(info["name"]): max_f = _dequant_max(out, info["exponent"]) sig = _sigmoid(max_f) mark = " <-- FACE DETECTED" if sig >= SCORE_THR else "" print(" score '{}': max_sigmoid={:.4f}{}".format( info["name"], sig, mark)) if sig >= SCORE_THR: any_face = True else: mn_f, mx_f = _dequant_range(out, info["exponent"]) print(" box '{}': dequant=[{:.3f}, {:.3f}]".format( info["name"], mn_f, mx_f)) if not any_face: print(" No score tensor above sigmoid threshold {:.2f} — no face detected".format(SCORE_THR)) print() if not _found_any: print() print("Tip: generate test images on the host, then copy to this directory:") print(" python generate_test_images.py --face /path/to/selfie.jpg") print(" # Upload face_test.raw + no_face_test.raw alongside the model") m.close() print("Done.") ```