4、Person Detection示例工程解析：官方示例的目录结构、代码模块、数据流与推理流程

在TinyML应用开发中，官方示例工程是理解嵌入式机器学习工作流的最佳起点。Person Detection（人员检测）示例基于Arduino Nano 33 BLE Sense开发板，使用TensorFlow Lite Micro框架，在Cortex-M4F内核上运行一个经过量化的MobileNetV1模型，实现对视频流中人体目标的实时检测。本章将逐层拆解该工程的物理目录结构、核心代码模块的职责划分、数据从摄像头到推理输出的完整流动路径，以及推理循环的精确时序逻辑。理解这些内容，是后续进行模型替换、输入尺寸调整、输出后处理定制和性能优化的前提。

上图展示了Person Detection示例的整体架构。左侧为工程目录中的关键文件，右侧为数据从摄像头到输出的流动路径，底部则概括了各模块的职责与推理循环的典型时序。下面我们将从目录结构开始，逐层深入。

4.1 官方示例的目录结构与文件职责

Person Detection示例位于TensorFlow官方仓库的 tensorflow/lite/micro/examples/person_detection 目录下。该工程采用“核心逻辑 + 平台适配”的分层设计，核心代码与硬件无关，平台相关部分通过抽象接口隔离。理解这种结构对于后续移植到其他开发板至关重要。

文件/目录	职责说明	关键接口或内容
main_functions.cc/.h	程序入口与主循环调度	setup() 初始化模型与TFLite解释器；loop() 循环执行图像获取→推理→输出
model_settings.cc/.h	模型参数与输入输出配置	定义 kNumCols、kNumRows（96x96）、kNumChannels（3）、kPersonScoreThreshold（0.5）等常量
image_provider.cc/.h	图像采集与预处理	GetImage() 函数从摄像头获取一帧图像，并完成裁剪、格式转换、归一化
detector_responder.cc/.h	推理结果输出	HandleOutput() 根据置信度控制LED或串口打印
person_detect_model_data.cc	模型权重数据	包含量化后的MobileNetV1模型，以C数组形式存储（约300KB）
arduino/ 子目录	Arduino平台适配层	包含摄像头驱动（OV7675）、时钟配置、内存分配等底层实现

这种结构设计的核心思想是可移植性。如果你要将示例移植到ESP32或STM32，只需替换 arduino/ 目录下的平台相关代码，并保持 image_provider 和 detector_responder 的接口不变即可。

4.2 核心代码模块的深入拆解

我们以 main_functions.cc 中的主循环为切入点，分析各模块如何协同工作。以下代码是经过精简后的核心逻辑：

// main_functions.cc 核心片段
void setup() {
  // 1. 初始化模型数据
  model = tflite::GetModel(g_person_detect_model_data);
  // 2. 创建解释器并分配张量内存
  static tflite::MicroMutableOpResolver<5> resolver;
  resolver.AddConv2D(); resolver.AddDepthwiseConv2D();
  resolver.AddAveragePool2D(); resolver.AddSoftmax(); resolver.AddReshape();
  static tflite::MicroInterpreter static_interpreter(
      model, resolver, tensor_arena, kTensorArenaSize);
  interpreter = &static_interpreter;
  // 3. 分配张量内存
  TfLiteStatus allocate_status = interpreter->AllocateTensors();
  // 4. 获取输入输出张量指针
  input = interpreter->input(0);
  output = interpreter->output(0);
}

void loop() {
  // 1. 获取图像数据（阻塞直到一帧就绪）
  TfLiteStatus get_status = GetImage(kNumCols, kNumRows, kNumChannels, input->data.uint8);
  // 2. 执行推理
  TfLiteStatus invoke_status = interpreter->Invoke();
  // 3. 读取输出并响应
  float person_score = output->data.uint8[1] / 255.0f;
  RespondToDetection(person_score);
}

这段代码揭示了几个关键设计点：

• 静态内存分配：使用 static 关键字和固定大小的 tensor_arena（通常为 100KB 左右），避免动态内存分配带来的碎片化问题。
• 算子注册：MicroMutableOpResolver 只注册模型实际用到的算子，减少代码体积。MobileNetV1 需要 Conv2D、DepthwiseConv2D、AveragePool2D、Softmax 和 Reshape 五种算子。
• 输入输出类型：输入为 uint8 类型（量化后的灰度或RGB），输出同样为 uint8，通过除以 255.0f 转换为浮点置信度。

4.3 数据流与推理流程的完整链路

从摄像头捕获原始图像到最终输出检测结果，数据经历了五个阶段。每个阶段都有明确的性能开销和优化空间。

1. 图像采集：OV7675 摄像头输出 RGB565 格式，分辨率为 96x96。Arduino 平台通过 DMA 将图像数据从摄像头 FIFO 传输到内存缓冲区。此阶段耗时约 15ms。
2. 格式转换与裁剪：image_provider.cc 中的 GetImage() 函数将 RGB565 转换为 RGB888，并裁剪到模型输入尺寸。这里有一个常见优化点：如果摄像头输出分辨率大于模型输入，可以直接裁剪而不缩放，减少计算量。
3. 数据拷贝到输入张量：将预处理后的图像数据拷贝到 input->data.uint8 指向的内存区域。由于 TFLite Micro 要求输入张量内存连续，这一步不可避免。
4. 推理执行：interpreter->Invoke() 触发模型计算。MobileNetV1 在 96x96x3 输入下，约执行 1100 万次乘加运算，在 64MHz 的 nRF52840 上耗时约 250ms。
5. 输出后处理：读取输出张量，计算“有人”置信度，并通过 HandleOutput() 控制 LED 闪烁或串口打印。此阶段耗时小于 1ms。

整个循环的瓶颈在推理阶段，占整体耗时的 90% 以上。因此，任何性能优化都应聚焦于减少推理时间，例如使用更小的模型（如 MobileNetV1 0.25 倍宽度）、增加输入步长或使用硬件加速器。

4.4 案例拆解：将输入分辨率从96x96改为64x64

假设我们需要降低功耗或提高帧率，将输入分辨率从 96x96 降至 64x64。这是一个典型的工程改造场景，涉及多个模块的联动修改。

背景与约束：目标设备为 Arduino Nano 33 BLE Sense，电池供电，要求帧率从 3.7 FPS 提升至 8 FPS 以上，同时保持检测准确率下降不超过 5%。

初始现象：当前系统在 96x96 分辨率下，推理耗时 250ms，总循环 270ms。降低分辨率后，推理时间预计可缩短至 110ms（因为计算量约为原来的 0.44 倍）。

操作步骤：

1. 修改 model_settings.h 中的 kNumRows 和 kNumCols 为 64。
2. 重新训练或量化模型，使模型输入层接受 64x64x3 的张量。如果直接使用原模型，输入尺寸不匹配会导致 AllocateTensors() 失败。
3. 更新 image_provider.cc 中的裁剪逻辑，从摄像头图像中心裁剪 64x64 区域。
4. 调整 tensor_arena 大小。64x64 输入下，中间特征图的内存占用会减少，可尝试将 arena 从 100KB 降至 60KB。
5. 重新编译并测量实际帧率和准确率。

结果对比：

指标	96x96 分辨率	64x64 分辨率	变化
推理耗时	250ms	108ms	-56.8%
总循环周期	270ms	125ms	-53.7%
帧率	3.7 FPS	8.0 FPS	+116%
检测准确率（测试集）	91.2%	87.5%	-3.7%

风险与代价：准确率下降 3.7% 在可接受范围内，但需要注意，如果检测目标较小（如远距离的人），64x64 分辨率可能无法捕捉足够特征，导致漏检率上升。此外，摄像头裁剪区域需要重新标定，确保目标位于画面中心。

复盘经验：分辨率调整不是简单的参数修改，必须同步考虑模型重新训练、内存分配调整和摄像头裁剪逻辑。建议在修改前先使用 TensorFlow 官方提供的 person_detection 训练脚本，用 64x64 输入重新训练模型，而不是直接裁剪原模型输入。

4.5 调试方法与性能分析技巧

在实际开发中，我们经常需要定位推理异常或性能瓶颈。以下是针对该示例的实用调试手段：

• 串口日志输出：在 loop() 中添加 Serial.println(person_score)，观察置信度变化。如果始终输出 0 或 1，说明模型可能未正确加载或输入数据异常。
• TFLite Micro 内置日志：在 setup() 中调用 interpreter->EnableDebugLogging(true)，可以输出算子执行时间和内存使用情况。
• 内存溢出检测：如果 AllocateTensors() 返回错误，检查 tensor_arena 大小是否足够。可以通过 interpreter->arena_used_bytes() 获取实际使用量。
• 图像数据可视化：将 input->data.uint8 的前 100 字节通过串口发送到 PC，用 Python 脚本还原为灰度图，确认图像采集和预处理是否正确。

性能分析方面，可以使用 Arduino IDE 的串口绘图器或外部逻辑分析仪测量 loop() 中各个阶段的时间戳。更精确的方法是使用 DWT 周期计数器（Cortex-M4F 内置），在关键代码段前后读取 DWT->CYCCNT 寄存器。