PyNvVideoCodec 2.2.1__cp314-cp314-win_arm64.whl

samples/jupyter/face_protect_tutorial.ipynb

@@ -0,0 +1,881 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<!--\n",
+    "This copyright notice applies to this file only\n",
+    "\n",
+    "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\n",
+    "SPDX-License-Identifier: MIT\n",
+    "\n",
+    "Permission is hereby granted, free of charge, to any person obtaining a\n",
+    "copy of this software and associated documentation files (the \"Software\"),\n",
+    "to deal in the Software without restriction, including without limitation\n",
+    "the rights to use, copy, modify, merge, publish, distribute, sublicense,\n",
+    "and/or sell copies of the Software, and to permit persons to whom the\n",
+    "Software is furnished to do so, subject to the following conditions:\n",
+    "\n",
+    "The above copyright notice and this permission notice shall be included in\n",
+    "all copies or substantial portions of the Software.\n",
+    "\n",
+    "THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n",
+    "IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n",
+    "FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL\n",
+    "THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n",
+    "LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\n",
+    "FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\n",
+    "DEALINGS IN THE SOFTWARE.\n",
+    "-->"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Face De-identification (Blur) using PyNvVideoCodec + RetinaFace\n",
+    "\n",
+    "This tutorial demonstrates a face de-identification pipeline that detects faces\n",
+    "with **RetinaFace-ResNet34** and blurs them in real time. Decoded frames are\n",
+    "displayed inline with Matplotlib.\n",
+    "\n",
+    "The detector backend is platform-specific:\n",
+    "\n",
+    "- Windows ARM64 uses ONNX Runtime with the ONNX model directly.\n",
+    "- Other platforms keep the original TensorRT FP16 engine flow.\n",
+    "\n",
+    "## Pipeline Overview\n",
+    "\n",
+    "1. **Decode** - `ThreadedDecoder` decodes the input MP4 into RGB frames on the GPU\n",
+    "2. **Detect** - RetinaFace detects faces with the platform-selected backend\n",
+    "3. **Blur** - Gaussian blur is applied to every detected face region\n",
+    "4. **Display** - The blurred frame is shown inline (no output file written)\n",
+    "\n",
+    "### Prerequisites\n",
+    "\n",
+    "| Dependency | Purpose |\n",
+    "|---|---|\n",
+    "| PyNvVideoCodec 2.x | GPU video decode via `ThreadedDecoder` |\n",
+    "| TensorRT >= 8.6 | RetinaFace FP16 inference on non-Windows ARM64 platforms |\n",
+    "| ONNX Runtime | RetinaFace ONNX inference on Windows ARM64 |\n",
+    "| PyCUDA | CUDA memory management |\n",
+    "| PyTorch >= 2.0 | DLPack to tensor conversion for decoded frames |\n",
+    "| torchvision >= 0.15 | GPU Gaussian blur (`F.gaussian_blur`) |\n",
+    "| OpenCV | Letterbox resize and RGB/BGR conversion on non-Windows ARM64 platforms |\n",
+    "| Pillow | Letterbox resize on Windows ARM64 |\n",
+    "| NumPy, Matplotlib | Array ops and inline display |\n",
+    "\n",
+    "> Windows ARM64 uses ONNX Runtime and Pillow because compatible TensorRT and OpenCV pip wheels are not available for that environment. Other platforms keep TensorRT and OpenCV to preserve the original accelerated sample flow."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Install Dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import platform, subprocess, sys\n",
+    "\n",
+    "def _is_windows_arm64():\n",
+    "    return sys.platform == \"win32\" and platform.machine().upper() == \"ARM64\"\n",
+    "\n",
+    "NVTORCH_WINDOWS_ARM64_INDEX = \"https://pypi.nvidia.com/nvtorch_oot_nightly\"\n",
+    "TORCH_WINDOWS_ARM64_PACKAGE = \"torch==2.15.0.dev20260820+cu134\"\n",
+    "TORCHVISION_WINDOWS_ARM64_PACKAGE = \"torchvision==0.30.0.dev20260820+cu134\"\n",
+    "\n",
+    "def _pip_install(*packages):\n",
+    "    subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", *packages])\n",
+    "\n",
+    "def _install_windows_arm64_torch(*packages):\n",
+    "    if not ((3, 11) <= sys.version_info[:2] < (3, 15)):\n",
+    "        raise RuntimeError(\"Windows ARM64 Torch wheels are available for CPython 3.11 through 3.14. Re-run this notebook with a supported kernel.\")\n",
+    "    _pip_install(\"--extra-index-url\", NVTORCH_WINDOWS_ARM64_INDEX, *packages)\n",
+    "\n",
+    "# Lightweight CPU-side deps\n",
+    "if _is_windows_arm64():\n",
+    "    _pip_install(\"matplotlib\", \"numpy\", \"onnxruntime\", \"pillow\", \"requests\")\n",
+    "else:\n",
+    "    _pip_install(\"matplotlib\", \"numpy\", \"opencv-python\", \"requests\")\n",
+    "\n",
+    "if _is_windows_arm64():\n",
+    "    print(\"Skipping PyCUDA install on Windows ARM64; use the native Windows ARM64 CUDA wheel.\")\n",
+    "else:\n",
+    "    _pip_install(\"pycuda\")\n",
+    "\n",
+    "# PyTorch + torchvision  (used for DLPack frame conversion and GPU Gaussian blur).\n",
+    "# Pick the wheel that matches your CUDA runtime:\n",
+    "#\n",
+    "#   CUDA 12.1 :  %pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121\n",
+    "#   CUDA 12.6 :  %pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126\n",
+    "#\n",
+    "# On Jetson / Tegra (Thor): use the torch/torchvision shipped with JetPack.\n",
+    "# On Windows ARM64: use NVIDIA's ARM CUDA wheels from nvtorch_oot_nightly.\n",
+    "if _is_windows_arm64():\n",
+    "    _install_windows_arm64_torch(TORCH_WINDOWS_ARM64_PACKAGE, TORCHVISION_WINDOWS_ARM64_PACKAGE)\n",
+    "else:\n",
+    "    _pip_install(\"torch\", \"torchvision\")\n",
+    "\n",
+    "# Face detector backend\n",
+    "if _is_windows_arm64():\n",
+    "    print(\"Using ONNX Runtime for face detection on Windows ARM64; skipping TensorRT pip install.\")\n",
+    "else:\n",
+    "    import torch\n",
+    "\n",
+    "    cuda_version = (torch.version.cuda or \"\")\n",
+    "    if cuda_version.startswith(\"12\"):\n",
+    "        tensorrt_pkg = \"tensorrt-cu12>=10.16.1,<10.17.0\"\n",
+    "    elif cuda_version.startswith(\"13\"):\n",
+    "        tensorrt_pkg = \"tensorrt-cu13>=10.16.1,<10.17.0\"\n",
+    "    else:\n",
+    "        raise RuntimeError(\n",
+    "            f\"Unsupported / unknown torch CUDA version: {cuda_version!r}. \"\n",
+    "            \"Install a CUDA 12.x or 13.x build of torch, then re-run this cell.\"\n",
+    "        )\n",
+    "\n",
+    "    print(f\"Installing {tensorrt_pkg} (torch CUDA {cuda_version})\")\n",
+    "    _pip_install(tensorrt_pkg)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Imports and CUDA Initialization"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from PyNvVideoCodec import ThreadedDecoder, OutputColorType\n",
+    "import pycuda.driver as cuda\n",
+    "from pycuda.autoinit import context\n",
+    "import numpy as np\n",
+    "from pathlib import Path\n",
+    "\n",
+    "if _is_windows_arm64():\n",
+    "    import onnxruntime as ort\n",
+    "    from PIL import Image\n",
+    "else:\n",
+    "    import cv2\n",
+    "    import tensorrt as trt\n",
+    "\n",
+    "import torch\n",
+    "import torchvision.transforms.functional as TF\n",
+    "\n",
+    "import matplotlib.pyplot as plt\n",
+    "from IPython.display import clear_output\n",
+    "%matplotlib inline\n",
+    "\n",
+    "_BLUR_DEVICE = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n",
+    "\n",
+    "if _is_windows_arm64():\n",
+    "    print(f\"ONNX Runtime: {ort.__version__}\")\n",
+    "else:\n",
+    "    print(f\"TensorRT    : {trt.__version__}\")\n",
+    "print(f\"PyCUDA      : device {cuda.Device(0).name()}\")\n",
+    "print(f\"Torch       : {torch.__version__} (blur device: {_BLUR_DEVICE})\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Download ONNX Model & Prepare Face Detector\n",
+    "\n",
+    "This cell downloads the **RetinaFace-ResNet34** ONNX model (~84 MB) from\n",
+    "[yakhyo/retinaface-pytorch](https://github.com/yakhyo/retinaface-pytorch)\n",
+    "(MIT License). A SHA-256 check is performed as a warning only (the upstream\n",
+    "model may be updated).\n",
+    "\n",
+    "- Windows ARM64 loads this ONNX model directly with ONNX Runtime.\n",
+    "- Other platforms build or reuse a TensorRT FP16 engine from the same ONNX model.\n",
+    "- If the ONNX file already exists and passes the hash check, the download is skipped.\n",
+    "- If the TensorRT engine already exists it is reused on non-Windows ARM64 platforms (set `FORCE_REBUILD = True` to override)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hashlib\n",
+    "import tempfile\n",
+    "import requests\n",
+    "from pathlib import Path\n",
+    "\n",
+    "# ----- Paths and constants -----\n",
+    "MODELS_DIR   = Path(\"models\")\n",
+    "ONNX_URL     = (\"https://github.com/yakhyo/retinaface-pytorch/releases/\"\n",
+    "                \"download/v0.0.1/retinaface_r34.onnx\")\n",
+    "ONNX_SHA256  = \"df36df61476e043603925e70df0e1a90b0ef2200e5e1c069810b5dbff4645dc6\"\n",
+    "ONNX_PATH    = MODELS_DIR / \"retinaface_r34.onnx\"\n",
+    "ENGINE_PATH  = Path(\"retinaface_r34.engine\")\n",
+    "INPUT_SHAPE  = (1, 3, 960, 960)\n",
+    "\n",
+    "FORCE_REBUILD = False\n",
+    "\n",
+    "\n",
+    "def _sha256(path):\n",
+    "    h = hashlib.sha256()\n",
+    "    with open(path, \"rb\") as f:\n",
+    "        for chunk in iter(lambda: f.read(1 << 20), b\"\"):\n",
+    "            h.update(chunk)\n",
+    "    return h.hexdigest()\n",
+    "\n",
+    "\n",
+    "def download_onnx(url, dest, expected_sha256):\n",
+    "    \"\"\"Download ONNX with SHA-256 verification (atomic write via requests).\"\"\"\n",
+    "    if dest.is_file():\n",
+    "        size_mb = dest.stat().st_size / (1024 * 1024)\n",
+    "        if expected_sha256:\n",
+    "            actual = _sha256(dest)\n",
+    "            if actual == expected_sha256:\n",
+    "                print(f\"ONNX already exists and verified: {dest} ({size_mb:.1f} MB)\")\n",
+    "            else:\n",
+    "                print(f\"ONNX exists ({size_mb:.1f} MB) - SHA-256 differs from expected (OK if upstream updated)\")\n",
+    "        else:\n",
+    "            print(f\"ONNX already exists: {dest} ({size_mb:.1f} MB)\")\n",
+    "        return\n",
+    "\n",
+    "    dest.parent.mkdir(parents=True, exist_ok=True)\n",
+    "    print(f\"Downloading RetinaFace-ResNet34 ONNX from:\\n  {url}\")\n",
+    "\n",
+    "    headers = {\n",
+    "        \"User-Agent\": (\n",
+    "            \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) \"\n",
+    "            \"AppleWebKit/537.36 (KHTML, like Gecko) \"\n",
+    "            \"Chrome/124.0.0.0 Safari/537.36\"\n",
+    "        ),\n",
+    "        \"Accept\": \"*/*\",\n",
+    "    }\n",
+    "\n",
+    "    tmp_fd, tmp_path = tempfile.mkstemp(dir=dest.parent, suffix=\".onnx.part\")\n",
+    "    tmp = Path(tmp_path)\n",
+    "\n",
+    "    try:\n",
+    "        with requests.get(url, headers=headers, stream=True, timeout=120) as resp:\n",
+    "            resp.raise_for_status()\n",
+    "            total = int(resp.headers.get(\"Content-Length\", 0))\n",
+    "            downloaded = 0\n",
+    "            with open(tmp_fd, \"wb\") as f:\n",
+    "                for chunk in resp.iter_content(chunk_size=1 << 20):\n",
+    "                    if not chunk:\n",
+    "                        continue\n",
+    "                    f.write(chunk)\n",
+    "                    downloaded += len(chunk)\n",
+    "                    if total > 0:\n",
+    "                        pct = downloaded / total * 100\n",
+    "                        print(f\"\\r  {downloaded / (1024*1024):.1f}/\"\n",
+    "                              f\"{total / (1024*1024):.1f} MB ({pct:.0f}%)\",\n",
+    "                              end=\"\", flush=True)\n",
+    "            print()\n",
+    "\n",
+    "        if expected_sha256:\n",
+    "            actual = _sha256(tmp)\n",
+    "            if actual != expected_sha256:\n",
+    "                print(f\"WARNING: SHA-256 mismatch (upstream model may have been updated)\\n\"\n",
+    "                      f\"  expected: {expected_sha256}\\n\"\n",
+    "                      f\"  got:      {actual}\")\n",
+    "        tmp.replace(dest)\n",
+    "    except BaseException:\n",
+    "        tmp.unlink(missing_ok=True)\n",
+    "        raise\n",
+    "\n",
+    "    print(f\"Saved: {dest} ({dest.stat().st_size / (1024*1024):.1f} MB)\")\n",
+    "\n",
+    "\n",
+    "def build_trt_engine(onnx_path, engine_path):\n",
+    "    \"\"\"Parse ONNX and build a TensorRT FP16 engine.\"\"\"\n",
+    "    logger  = trt.Logger(trt.Logger.INFO)\n",
+    "    builder = trt.Builder(logger)\n",
+    "    network = builder.create_network(\n",
+    "        1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))\n",
+    "    parser  = trt.OnnxParser(network, logger)\n",
+    "\n",
+    "    with open(onnx_path, \"rb\") as f:\n",
+    "        if not parser.parse(f.read()):\n",
+    "            errors = [str(parser.get_error(i)) for i in range(parser.num_errors)]\n",
+    "            raise RuntimeError(\"ONNX parse failed:\\n  \" + \"\\n  \".join(errors))\n",
+    "\n",
+    "    print(f\"Model: {onnx_path.name}\")\n",
+    "    for i in range(network.num_inputs):\n",
+    "        t = network.get_input(i)\n",
+    "        print(f\"  Input  [{i}] {t.name}: shape={t.shape} dtype={t.dtype}\")\n",
+    "    for i in range(network.num_outputs):\n",
+    "        t = network.get_output(i)\n",
+    "        print(f\"  Output [{i}] {t.name}: shape={t.shape} dtype={t.dtype}\")\n",
+    "\n",
+    "    config = builder.create_builder_config()\n",
+    "    config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 1 << 30)\n",
+    "\n",
+    "    if builder.platform_has_fast_fp16:\n",
+    "        config.set_flag(trt.BuilderFlag.FP16)\n",
+    "        print(\"FP16 precision enabled\")\n",
+    "\n",
+    "    inp = network.get_input(0)\n",
+    "    if any(d == -1 for d in inp.shape):\n",
+    "        print(f\"Dynamic input - setting profile to {INPUT_SHAPE}\")\n",
+    "        profile = builder.create_optimization_profile()\n",
+    "        profile.set_shape(inp.name, INPUT_SHAPE, INPUT_SHAPE, INPUT_SHAPE)\n",
+    "        config.add_optimization_profile(profile)\n",
+    "\n",
+    "    print(\"Building TensorRT engine (this may take a minute) ...\")\n",
+    "    serialised = builder.build_serialized_network(network, config)\n",
+    "    if serialised is None:\n",
+    "        raise RuntimeError(\"TensorRT engine build failed\")\n",
+    "\n",
+    "    engine_path.parent.mkdir(parents=True, exist_ok=True)\n",
+    "    with open(engine_path, \"wb\") as f:\n",
+    "        f.write(serialised)\n",
+    "\n",
+    "    print(f\"Engine saved: {engine_path} \"\n",
+    "          f\"({engine_path.stat().st_size / (1024*1024):.1f} MB)\")\n",
+    "\n",
+    "\n",
+    "# ----- Run: download + backend preparation -----\n",
+    "download_onnx(ONNX_URL, ONNX_PATH, ONNX_SHA256)\n",
+    "\n",
+    "if _is_windows_arm64():\n",
+    "    print(\"Using ONNX Runtime on Windows ARM64; TensorRT engine build is skipped.\")\n",
+    "elif ENGINE_PATH.is_file() and not FORCE_REBUILD:\n",
+    "    size_mb = ENGINE_PATH.stat().st_size / (1024 * 1024)\n",
+    "    print(f\"Engine already exists: {ENGINE_PATH} ({size_mb:.1f} MB) \"\n",
+    "          f\"- set FORCE_REBUILD=True to rebuild\")\n",
+    "else:\n",
+    "    build_trt_engine(ONNX_PATH, ENGINE_PATH)\n",
+    "\n",
+    "print(\"\\nDone!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Configuration\n",
+    "\n",
+    "Set paths and tuning knobs here.  The engine was built in the previous step."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "VIDEO_URL   = \"https://videos.pexels.com/video-files/19527870/19527870-hd_1920_1080_24fps.mp4\"\n",
+    "INPUT_VIDEO = \"test_faces.mp4\"\n",
+    "\n",
+    "if not Path(INPUT_VIDEO).is_file():\n",
+    "    import requests\n",
+    "    print(f\"Downloading sample video from:\\n  {VIDEO_URL}\")\n",
+    "    with requests.get(VIDEO_URL, stream=True, timeout=120) as r:\n",
+    "        r.raise_for_status()\n",
+    "        with open(INPUT_VIDEO, \"wb\") as f:\n",
+    "            for chunk in r.iter_content(chunk_size=8192):\n",
+    "                if chunk:\n",
+    "                    f.write(chunk)\n",
+    "    print(f\"Saved: {INPUT_VIDEO} \"\n",
+    "          f\"({Path(INPUT_VIDEO).stat().st_size / (1024*1024):.1f} MB)\")\n",
+    "else:\n",
+    "    print(f\"Using existing video: {INPUT_VIDEO}\")\n",
+    "\n",
+    "RETINAFACE_INPUT_SIZE = 960\n",
+    "\n",
+    "CONF_THRESH  = 0.4\n",
+    "NMS_IOU      = 0.4\n",
+    "BBOX_SCALE   = 1.0\n",
+    "PRE_NMS_TOPK = 5000\n",
+    "\n",
+    "BLUR_KSIZE   = 151\n",
+    "BLUR_SIGMA   = 45\n",
+    "\n",
+    "DISPLAY_EVERY_N = 5          # show every Nth frame (1 = show all)\n",
+    "MAX_FRAMES      = 200        # stop after N frames (0 = all)\n",
+    "\n",
+    "assert Path(INPUT_VIDEO).is_file(), f\"Input video not found: {INPUT_VIDEO}\"\n",
+    "assert ONNX_PATH.is_file(), f\"ONNX model not found: {ONNX_PATH} - run step 3 above\"\n",
+    "if not _is_windows_arm64():\n",
+    "    assert ENGINE_PATH.is_file(), f\"Engine not found: {ENGINE_PATH} - run step 3 above\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. RetinaFace Utilities\n",
+    "\n",
+    "Self-contained: letterbox resize, prior-box generation, bbox decode, NMS,\n",
+    "and the full post-processing pipeline.  No imports from the main project."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ----- RetinaFace constants -----\n",
+    "MIN_SIZES = [[16, 32], [64, 128], [256, 512]]\n",
+    "STRIDES   = [8, 16, 32]\n",
+    "VARIANCE  = (0.1, 0.2)\n",
+    "BGR_MEAN  = np.array([104.0, 117.0, 123.0], dtype=np.float32)\n",
+    "\n",
+    "\n",
+    "def letterbox(image, target_size, pad_val=0):\n",
+    "    \"\"\"Resize preserving aspect ratio with symmetric zero-padding.\"\"\"\n",
+    "    h_src, w_src = image.shape[:2]\n",
+    "    scale = min(target_size / w_src, target_size / h_src)\n",
+    "    new_w, new_h = int(w_src * scale), int(h_src * scale)\n",
+    "    if _is_windows_arm64():\n",
+    "        resized = np.asarray(Image.fromarray(image).resize((new_w, new_h), Image.Resampling.BILINEAR))\n",
+    "    else:\n",
+    "        resized = cv2.resize(image, (new_w, new_h), interpolation=cv2.INTER_LINEAR)\n",
+    "    dx = (target_size - new_w) // 2\n",
+    "    dy = (target_size - new_h) // 2\n",
+    "    canvas = np.full((target_size, target_size, image.shape[2]), pad_val, dtype=np.uint8)\n",
+    "    canvas[dy:dy + new_h, dx:dx + new_w, :] = resized\n",
+    "    return canvas, scale, dx, dy\n",
+    "\n",
+    "\n",
+    "def generate_prior_boxes(input_size):\n",
+    "    \"\"\"Generate RetinaFace anchors in normalised [cx, cy, w, h].\"\"\"\n",
+    "    anchors = []\n",
+    "    for k, step in enumerate(STRIDES):\n",
+    "        fmap = int(np.ceil(input_size / step))\n",
+    "        for i in range(fmap):\n",
+    "            for j in range(fmap):\n",
+    "                for min_size in MIN_SIZES[k]:\n",
+    "                    s = min_size / input_size\n",
+    "                    cx = (j + 0.5) * step / input_size\n",
+    "                    cy = (i + 0.5) * step / input_size\n",
+    "                    anchors.append([cx, cy, s, s])\n",
+    "    return np.array(anchors, dtype=np.float32)\n",
+    "\n",
+    "\n",
+    "def decode_boxes(loc, priors):\n",
+    "    \"\"\"Decode regression deltas into [x1, y1, x2, y2].\"\"\"\n",
+    "    cxcy = priors[:, :2] + loc[:, :2] * VARIANCE[0] * priors[:, 2:]\n",
+    "    wh   = priors[:, 2:] * np.exp(np.clip(loc[:, 2:] * VARIANCE[1], -50, 50))\n",
+    "    boxes = np.empty_like(loc)\n",
+    "    boxes[:, :2] = cxcy - wh / 2\n",
+    "    boxes[:, 2:] = cxcy + wh / 2\n",
+    "    return boxes\n",
+    "\n",
+    "\n",
+    "def _compute_iou(box, boxes):\n",
+    "    x1 = np.maximum(box[0], boxes[:, 0])\n",
+    "    y1 = np.maximum(box[1], boxes[:, 1])\n",
+    "    x2 = np.minimum(box[2], boxes[:, 2])\n",
+    "    y2 = np.minimum(box[3], boxes[:, 3])\n",
+    "    inter = np.maximum(0, x2 - x1) * np.maximum(0, y2 - y1)\n",
+    "    area_box   = (box[2] - box[0]) * (box[3] - box[1])\n",
+    "    area_boxes = (boxes[:, 2] - boxes[:, 0]) * (boxes[:, 3] - boxes[:, 1])\n",
+    "    return inter / np.maximum(area_box + area_boxes - inter, 1e-6)\n",
+    "\n",
+    "\n",
+    "def nms(boxes, scores, iou_threshold):\n",
+    "    \"\"\"Greedy NMS with center-distance merge.\"\"\"\n",
+    "    if len(boxes) == 0:\n",
+    "        return np.array([], dtype=int)\n",
+    "    order = scores.argsort()[::-1]\n",
+    "    keep = []\n",
+    "    while len(order) > 0:\n",
+    "        idx = order[0]\n",
+    "        keep.append(idx)\n",
+    "        if len(order) == 1:\n",
+    "            break\n",
+    "        ious = _compute_iou(boxes[idx], boxes[order[1:]])\n",
+    "        order = order[np.where(ious <= iou_threshold)[0] + 1]\n",
+    "\n",
+    "    keep_arr = np.array(keep, dtype=int)\n",
+    "    kept = boxes[keep_arr]\n",
+    "    cx = (kept[:, 0] + kept[:, 2]) / 2\n",
+    "    cy = (kept[:, 1] + kept[:, 3]) / 2\n",
+    "    w  = kept[:, 2] - kept[:, 0]\n",
+    "    h  = kept[:, 3] - kept[:, 1]\n",
+    "    final, suppressed = [], np.zeros(len(keep_arr), dtype=bool)\n",
+    "    for i in range(len(keep_arr)):\n",
+    "        if suppressed[i]:\n",
+    "            continue\n",
+    "        final.append(keep_arr[i])\n",
+    "        for j in range(i + 1, len(keep_arr)):\n",
+    "            if not suppressed[j]:\n",
+    "                if abs(cx[j] - cx[i]) < max(w[i], w[j]) and abs(cy[j] - cy[i]) < max(h[i], h[j]):\n",
+    "                    suppressed[j] = True\n",
+    "    return np.array(final, dtype=int)\n",
+    "\n",
+    "\n",
+    "def postprocess_detections(loc, conf, priors, input_size, scale, dx, dy,\n",
+    "                           conf_thresh, nms_iou, bbox_scale):\n",
+    "    \"\"\"Decode + threshold + NMS + reverse-letterbox.\"\"\"\n",
+    "    boxes  = decode_boxes(loc, priors) * input_size\n",
+    "    scores = conf[:, 1]\n",
+    "\n",
+    "    mask = scores >= conf_thresh\n",
+    "    boxes, scores = boxes[mask], scores[mask]\n",
+    "    if len(boxes) == 0:\n",
+    "        return np.empty((0, 4), dtype=np.float32)\n",
+    "\n",
+    "    order = scores.argsort()[::-1][:PRE_NMS_TOPK]\n",
+    "    boxes, scores = boxes[order], scores[order]\n",
+    "\n",
+    "    keep = nms(boxes, scores, iou_threshold=nms_iou)\n",
+    "    boxes = boxes[keep]\n",
+    "\n",
+    "    # Reverse letterbox\n",
+    "    out = boxes.copy()\n",
+    "    out[:, [0, 2]] = (out[:, [0, 2]] - dx) / scale\n",
+    "    out[:, [1, 3]] = (out[:, [1, 3]] - dy) / scale\n",
+    "\n",
+    "    # Enlarge for blur coverage\n",
+    "    cx = (out[:, 0] + out[:, 2]) / 2\n",
+    "    cy = (out[:, 1] + out[:, 3]) / 2\n",
+    "    w  = (out[:, 2] - out[:, 0]) * bbox_scale\n",
+    "    h  = (out[:, 3] - out[:, 1]) * bbox_scale\n",
+    "    out[:, 0] = cx - w / 2\n",
+    "    out[:, 1] = cy - h / 2\n",
+    "    out[:, 2] = cx + w / 2\n",
+    "    out[:, 3] = cy + h / 2\n",
+    "    return out\n",
+    "\n",
+    "\n",
+    "print(f\"Prior boxes for {RETINAFACE_INPUT_SIZE}x{RETINAFACE_INPUT_SIZE}: \"\n",
+    "      f\"{generate_prior_boxes(RETINAFACE_INPUT_SIZE).shape[0]}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Face Detector Inference Wrapper"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class ORTInference:\n",
+    "    \"\"\"Load RetinaFace ONNX model and run inference with ONNX Runtime.\"\"\"\n",
+    "\n",
+    "    def __init__(self, onnx_path):\n",
+    "        available = ort.get_available_providers()\n",
+    "        providers = [\"CUDAExecutionProvider\"] if \"CUDAExecutionProvider\" in available else [\"CPUExecutionProvider\"]\n",
+    "        self.session = ort.InferenceSession(str(onnx_path), providers=providers)\n",
+    "        self.input_name = self.session.get_inputs()[0].name\n",
+    "        self.output_names = [out.name for out in self.session.get_outputs()]\n",
+    "        self.loc_name = next((name for name in self.output_names if \"loc\" in name.lower()), self.output_names[0])\n",
+    "        self.conf_name = next((name for name in self.output_names if \"conf\" in name.lower()), self.output_names[1])\n",
+    "\n",
+    "        print(f\"ONNX model loaded: {onnx_path}\")\n",
+    "        print(f\"  Provider: {self.session.get_providers()[0]}\")\n",
+    "        print(f\"  Input   : {self.input_name} {self.session.get_inputs()[0].shape}\")\n",
+    "        print(f\"  Outputs : {self.output_names}\")\n",
+    "\n",
+    "    def infer(self, preprocessed):\n",
+    "        raw_outputs = self.session.run(\n",
+    "            self.output_names,\n",
+    "            {self.input_name: np.ascontiguousarray(preprocessed, dtype=np.float32)},\n",
+    "        )\n",
+    "        outputs = dict(zip(self.output_names, raw_outputs))\n",
+    "        outputs[\"loc\"] = outputs[self.loc_name]\n",
+    "        outputs[\"conf\"] = outputs[self.conf_name]\n",
+    "        return outputs\n",
+    "\n",
+    "\n",
+    "class TRTInference:\n",
+    "    \"\"\"Load a serialised TensorRT engine and run inference.\"\"\"\n",
+    "\n",
+    "    def __init__(self, engine_path):\n",
+    "        logger = trt.Logger(trt.Logger.WARNING)\n",
+    "        with open(engine_path, \"rb\") as f:\n",
+    "            self.engine = trt.Runtime(logger).deserialize_cuda_engine(f.read())\n",
+    "        assert self.engine is not None, f\"Failed to load engine: {engine_path}\"\n",
+    "\n",
+    "        self.context = self.engine.create_execution_context()\n",
+    "        self._stream  = cuda.Stream()\n",
+    "        self._d_bufs  = {}\n",
+    "        self._h_outs  = {}\n",
+    "        self._input_name  = \"\"\n",
+    "        self._input_shape = ()\n",
+    "\n",
+    "        for i in range(self.engine.num_io_tensors):\n",
+    "            name  = self.engine.get_tensor_name(i)\n",
+    "            shape = tuple(self.engine.get_tensor_shape(name))\n",
+    "            nbytes = int(np.prod(shape)) * np.dtype(np.float32).itemsize\n",
+    "            d_mem = cuda.mem_alloc(nbytes)\n",
+    "            self._d_bufs[name] = d_mem\n",
+    "            self.context.set_tensor_address(name, int(d_mem))\n",
+    "\n",
+    "            if self.engine.get_tensor_mode(name) == trt.TensorIOMode.OUTPUT:\n",
+    "                self._h_outs[name] = np.empty(shape, dtype=np.float32)\n",
+    "            else:\n",
+    "                self._input_name  = name\n",
+    "                self._input_shape = shape\n",
+    "\n",
+    "        self.output_names = list(self._h_outs.keys())\n",
+    "        self.loc_name = next((name for name in self.output_names if \"loc\" in name.lower()), self.output_names[0])\n",
+    "        self.conf_name = next((name for name in self.output_names if \"conf\" in name.lower()), self.output_names[1])\n",
+    "\n",
+    "        print(f\"Engine loaded: {engine_path}\")\n",
+    "        print(f\"  Input : {self._input_name} {self._input_shape}\")\n",
+    "        print(f\"  Outputs: {self.output_names}\")\n",
+    "\n",
+    "    def infer(self, preprocessed):\n",
+    "        cuda.memcpy_htod(self._d_bufs[self._input_name],\n",
+    "                         np.ascontiguousarray(preprocessed))\n",
+    "        self.context.execute_async_v3(stream_handle=self._stream.handle)\n",
+    "        self._stream.synchronize()\n",
+    "        outputs = {\n",
+    "            name: (cuda.memcpy_dtoh(buf, self._d_bufs[name]), buf.copy())[1]\n",
+    "            for name, buf in self._h_outs.items()\n",
+    "        }\n",
+    "        outputs[\"loc\"] = outputs[self.loc_name]\n",
+    "        outputs[\"conf\"] = outputs[self.conf_name]\n",
+    "        return outputs\n",
+    "\n",
+    "\n",
+    "face_model = ORTInference(ONNX_PATH) if _is_windows_arm64() else TRTInference(ENGINE_PATH)\n",
+    "priors     = generate_prior_boxes(RETINAFACE_INPUT_SIZE)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. Preprocessing and Blur Helpers"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def preprocess_retinaface(bgr_image):\n",
+    "    \"\"\"BGR mean subtraction + HWC -> NCHW float32.\"\"\"\n",
+    "    img = bgr_image.astype(np.float32) - BGR_MEAN\n",
+    "    return np.ascontiguousarray(img.transpose(2, 0, 1)[np.newaxis, ...])\n",
+    "\n",
+    "\n",
+    "def _largest_odd_le(n: int) -> int:\n",
+    "    \"\"\"Largest odd integer <= n (torchvision requires odd kernel sizes).\"\"\"\n",
+    "    n = int(n)\n",
+    "    return n if n % 2 == 1 else n - 1\n",
+    "\n",
+    "\n",
+    "def blur_faces_rgb(rgb_image, bboxes, ksize=BLUR_KSIZE, sigma=BLUR_SIGMA):\n",
+    "    \"\"\"Gaussian blur on face ROIs using torchvision on CUDA (falls back to CPU).\n",
+    "\n",
+    "    Returns a blurred RGB copy.\n",
+    "    Each ROI is uploaded to the GPU, blurred, and written back in-place.\n",
+    "    \"\"\"\n",
+    "    img = rgb_image.copy()\n",
+    "    if len(bboxes) == 0:\n",
+    "        return img\n",
+    "\n",
+    "    h, w = img.shape[:2]\n",
+    "    k = ksize if ksize % 2 == 1 else ksize + 1\n",
+    "    sigma_f = float(sigma)\n",
+    "\n",
+    "    for x1, y1, x2, y2 in bboxes:\n",
+    "        x1i, y1i = max(0, int(x1)), max(0, int(y1))\n",
+    "        x2i, y2i = min(w, int(x2)), min(h, int(y2))\n",
+    "        if x2i <= x1i or y2i <= y1i:\n",
+    "            continue\n",
+    "\n",
+    "        # Kernel must be odd and not larger than the ROI\n",
+    "        roi_h, roi_w = y2i - y1i, x2i - x1i\n",
+    "        kh = min(k, _largest_odd_le(roi_h))\n",
+    "        kw = min(k, _largest_odd_le(roi_w))\n",
+    "        if kh < 1 or kw < 1:\n",
+    "            continue\n",
+    "\n",
+    "        roi_np = img[y1i:y2i, x1i:x2i]                                       # HWC uint8\n",
+    "        roi = (torch.from_numpy(roi_np)\n",
+    "                    .to(_BLUR_DEVICE, non_blocking=True)\n",
+    "                    .permute(2, 0, 1)                                        # HWC -> CHW\n",
+    "                    .unsqueeze(0)                                            # 1xCxHxW\n",
+    "                    .float())\n",
+    "\n",
+    "        blurred = TF.gaussian_blur(roi, kernel_size=[kh, kw],\n",
+    "                                   sigma=[sigma_f, sigma_f])\n",
+    "\n",
+    "        out = (blurred.squeeze(0)\n",
+    "                       .clamp_(0, 255)\n",
+    "                       .to(torch.uint8)\n",
+    "                       .permute(1, 2, 0)                                     # CHW -> HWC\n",
+    "                       .cpu()\n",
+    "                       .numpy())\n",
+    "        img[y1i:y2i, x1i:x2i] = out\n",
+    "\n",
+    "    return img\n",
+    "\n",
+    "\n",
+    "print(\"Helpers ready.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 8. Display Helper"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def show_frame(rgb_image, frame_idx, num_faces):\n",
+    "    \"\"\"Display an RGB frame inline with frame number and face count.\"\"\"\n",
+    "    plt.figure(figsize=(10, 6))\n",
+    "    plt.imshow(rgb_image)\n",
+    "    plt.title(f\"Frame {frame_idx}  —  {num_faces} face(s) detected\",\n",
+    "              fontsize=12)\n",
+    "    plt.axis(\"off\")\n",
+    "    clear_output(wait=True)\n",
+    "    plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 9. Run the Pipeline\n",
+    "\n",
+    "Decode → detect → blur → display in a single loop.\n",
+    "\n",
+    "The `ThreadedDecoder` decodes video frames on a background thread so inference\n",
+    "never stalls waiting for the next frame.  We request **RGB** output so each\n",
+    "frame arrives as an `(H, W, 3)` uint8 tensor that we can convert to BGR for\n",
+    "RetinaFace and display directly with matplotlib."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "color_format = OutputColorType.RGB\n",
+    "batch_size   = 1\n",
+    "\n",
+    "decoder = ThreadedDecoder(\n",
+    "    enc_file_path=INPUT_VIDEO,\n",
+    "    buffer_size=12,\n",
+    "    gpu_id=0,\n",
+    "    use_device_memory=False,\n",
+    "    output_color_type=color_format,\n",
+    ")\n",
+    "\n",
+    "frame_count  = 0\n",
+    "total_faces  = 0\n",
+    "\n",
+    "while True:\n",
+    "    if MAX_FRAMES > 0 and frame_count >= MAX_FRAMES:\n",
+    "        break\n",
+    "\n",
+    "    frames = decoder.get_batch_frames(batch_size)\n",
+    "    if len(frames) == 0:\n",
+    "        break\n",
+    "\n",
+    "    for frame in frames:\n",
+    "        # Convert dlpack frame to numpy RGB (H, W, 3)\n",
+    "        rgb = torch.from_dlpack(frame).cpu().numpy()\n",
+    "        if rgb.ndim == 3 and rgb.shape[0] == 3:\n",
+    "            rgb = rgb.transpose(1, 2, 0)           # CHW to HWC\n",
+    "        rgb = np.ascontiguousarray(rgb, dtype=np.uint8)\n",
+    "\n",
+    "        # RGB to BGR for RetinaFace\n",
+    "        if _is_windows_arm64():\n",
+    "            bgr = rgb[..., ::-1]\n",
+    "        else:\n",
+    "            bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)\n",
+    "\n",
+    "        # Letterbox + preprocess\n",
+    "        lb, scale, dx, dy = letterbox(bgr, RETINAFACE_INPUT_SIZE)\n",
+    "        inp = preprocess_retinaface(lb)\n",
+    "\n",
+    "        # Face detector inference\n",
+    "        outputs = face_model.infer(inp)\n",
+    "\n",
+    "        # Post-process to face bboxes in original coords\n",
+    "        faces = postprocess_detections(\n",
+    "            outputs[\"loc\"].squeeze(0),\n",
+    "            outputs[\"conf\"].squeeze(0),\n",
+    "            priors,\n",
+    "            RETINAFACE_INPUT_SIZE,\n",
+    "            scale, dx, dy,\n",
+    "            conf_thresh=CONF_THRESH,\n",
+    "            nms_iou=NMS_IOU,\n",
+    "            bbox_scale=BBOX_SCALE,\n",
+    "        )\n",
+    "\n",
+    "        total_faces += len(faces)\n",
+    "\n",
+    "        # Blur faces on RGB image\n",
+    "        blurred = blur_faces_rgb(rgb, faces)\n",
+    "\n",
+    "        # Display periodically\n",
+    "        if frame_count % DISPLAY_EVERY_N == 0:\n",
+    "            show_frame(blurred, frame_count, len(faces))\n",
+    "\n",
+    "        frame_count += 1\n",
+    "\n",
+    "print(f\"\\nDone: {frame_count} frames processed, {total_faces} total faces detected.\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "| Component | Implementation |\n",
+    "|---|---|\n",
+    "| Video decode | `ThreadedDecoder` (PyNvVideoCodec 2.x) - background-threaded NVDEC |\n",
+    "| Face detection | Windows ARM64: RetinaFace ONNX via ONNX Runtime; other platforms: RetinaFace FP16 via TensorRT |\n",
+    "| Image helpers | Windows ARM64: Pillow and NumPy channel swap; other platforms: OpenCV |\n",
+    "| Post-processing | NumPy: bbox decode, threshold, NMS, reverse letterbox |\n",
+    "| Blur | `torchvision.transforms.functional.gaussian_blur` on face ROIs (GPU) |\n",
+    "| Display | `matplotlib` + `IPython.display.clear_output` for inline animation |"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}