raulespim/object-detection-lab

# 目标检测实验室

Android 实时设备端目标检测
基于 CameraX、Jetpack Compose、TensorFlow Lite、NDK (C++)、Coroutines/Flow、Hilt 构建，采用模块化 Clean Architecture + MVI 架构。

## 概述 目标检测实验室是一个作品集级别的 Android 项目，专注于一个核心问题：**在设备端运行低延迟、架构边界清晰的实时视觉管道**。 本项目不将计算机视觉视为黑盒 SDK 集成，而是将管道流程明确化： - **CameraX** 以 `YUV_420_888` 格式捕获帧 - **NDK / C++** 处理底层图像预处理 - **TensorFlow Lite** 在设备端本地运行推理 - **Compose** 渲染实时叠加层和运行时 HUD - **MVI + Clean Architecture** 将功能逻辑与基础设施分离 目标是展示工程成熟度，而不仅仅是"能工作"。 ## 工程亮点 ### 低延迟 热路径经过精心设计，以便昂贵的图像处理可以更接近原生内存处理。项目使用 **通过 JNI 调用的 NDK (C++) 层** 进行图像预处理，减少了连续相机采集过程中不必要的托管堆工作，从而为以更低延迟处理 `YUV_420_888` 帧奠定了更强的基础。 ### 模块化 代码库分为 **`:core`** 和 **`:feature`** 模块，使职责保持明确： - `:core` 包含可重用的基础设施和平台能力 - `:feature` 包含流程编排、UI 状态和屏幕级行为 这种分离使项目更容易理解、基准测试、演进，也更容易在高级别面试中讨论。 ### 离线优先 AI 推理设计为使用 TensorFlow Lite **完全在设备端运行**。这带来了实际的产品优势： - 更好的隐私保护 - 更低的服务器成本 - 更低的端到端延迟 - 网络不可用时的韧性 对于移动 AI 产品来说，这通常是演示与可用功能之间的区别。 ## 演示 当前原型演示了： - 实时相机预览 - Compose 中的实时边界框叠加层 - 设备端目标检测 - 显示目标数量和延迟的运行时 HUD - 为 GPU 加速设计（带 CPU 回退）的管道 ## 项目创建原因 许多移动视觉示例仅停留在集成层。本项目有意不同。 它的设计和构建旨在展示如何构建实时 Android 视觉系统，包含强高级/首席工程师预期的决策： - 明确的帧所有权 - 清晰的模块边界 - 最小化主线程工作 - 通过 JNI 进行原生互操作 - 可替换的 ML/运行时层 - UI 叠加层渲染与图像处理分离 - 为基准测试和未来优化留有空间 ## 架构概览 ``` object-detection-lab/ ├── app/ # Android application / composition root ├── core/ │ ├── common/ # Shared contracts and domain models │ ├── dispatchers/ # Coroutine dispatchers / threading abstractions │ ├── designsystem/ # Theme, tokens, visual primitives │ ├── camera/ # CameraX integration and frame ingestion │ ├── cpp/ # JNI bridge + native image processing (C++) │ └── ml/ # TFLite engine and ML-specific wiring ├── feature/ │ └── detection/ # Detection feature: state, use case, ViewModel, UI ├── benchmark/ │ └── macrobenchmark/ # Performance benchmarking module └── gradle/ # Version catalog ``` ### 架构角色 #### :app 组合根。它将模块连接在一起，并负责应用级设置。 #### :core:* 可重用的基础设施和技术能力，例如： - 帧捕获 - 原生处理 - ML 推理 - 调度器 - 设计系统 - UI 构建块 #### :feature:detection 拥有面向用户的检测流程： - 状态 - 意图处理 - 功能编排 - 检测屏幕 UI ## 端到端管道 ``` CameraX (YUV_420_888) ↓ FrameSource / Flow pipeline ↓ NDK / JNI pre-processing ↓ TensorFlow Lite inference ↓ Detection state update ↓ Compose overlay + runtime HUD ``` 这种分离是经过深思熟虑的。它使系统更容易检查、优化、测试和讨论。 ## 面向性能的决策 本项目围绕实际的实时约束构建： - 保持 **主线程** 免于繁重工作 - 将图像预处理视为一等一的性能问题 - 避免在 UI 代码中隐藏昂贵的工作 - 将 ML 运行时关注点隔离在契约之后 - 优先使用明确的管道阶段而非意外耦合 - 在优化前为测量留有空间 ### 为什么 NDK 层很重要 对于连续相机分析，图像转换通常是真正的瓶颈。通过将底层帧处理隔离到 `:core:cpp` 中，项目使这一约束可见，并为以下方面创造了更好的路径： - 更紧密的内存控制 - 更低的分配压力 - 更好的延迟特性 - 更清晰的原生工作所有权 ## 技术栈 - **Kotlin** - **Jetpack Compose** - **CameraX** - **Coroutines & Flow** - **Hilt** - **NDK / C++ / JNI** - **CMake** - **TensorFlow Lite** - **GPU delegate / CPU fallback** - **Clean Architecture + MVI** - **Gradle 多模块设置** ## 入门指南 ### 前置条件 - 已安装 NDK 支持的 Android Studio - JDK 17 - Android SDK 35+ - NDK 26.1.10909125 - CMake 3.22.1 - 用于相机/性能测试的实体 Android 设备 ### 模型资源 TensorFlow Lite 模型应位于： ``` core/ml/src/main/assets/model.tflite ``` ### 构建 ``` ./gradlew clean ./gradlew :app:assembleDebug ``` 然后在设备上运行应用并授予相机权限。 ## 为什么这值得放入作品集 本项目不仅仅是关于目标检测。它旨在展示对现代 Android 角色重要的领域的能力： - 性能感知工程 - 原生互操作 - 模块化系统设计 - 设备端 AI 集成 - 现代 Android UI 架构 - 以管道而非孤立屏幕的思维方式思考 对于审查项目的招聘经理或高级工程师来说，最重要的检查点不仅是屏幕上的输出，还包括系统的结构如何支持正确性、性能和未来迭代。 ## 建议的路线图 演进此实验室的自然后续步骤包括： - 更强的帧到预览坐标映射 - 热路径上的缓冲区复用/池化 - 分阶段计时检测 - 模型标签映射和更丰富的叠加层数据 - 多模型支持和运行时切换 - 推理更新之间的更平滑叠加层动画 ## 审查者指南 如果您从工程角度审查此项目，最好的检查点是： - `:core:camera` → 帧采集和分析边界 - `:core:cpp` → JNI 和原生图像处理职责 - `:core:ml` → 解释器/代理设置和模型边界 - `:feature:detection` → 状态、编排和 Compose 叠加层 - `:benchmark:macrobenchmark` → 性能验证策略 ## 许可证 本项目基于 Apache License 2.0 许可 - 详见 [LICENSE](./LICENSE) 文件。 ## 作者说明 目标检测实验室是一个工程优先的作品集项目。 目的是使重要的决策可见：延迟风险在哪里、模块边界在哪里重要、原生代码如何提供帮助，以及如何将设备端 AI 集成到现代 Android 架构中，而不会将所有内容折叠到单个演示模块中。

标签：Android NDK, Android工程, Android开发, Apex, Bash脚本, C++, CameraX, Clean Architecture, Flow, Hilt依赖注入, Jetpack Compose, JNI, ML推理, MVI架构, TensorFlow Lite, 低延迟处理, 协程, 后台面板检测, 图像预处理, 实时目标检测, 性能优化, 数据擦除, 机器学习, 检测绕过, 模块化架构, 移动端视觉, 端侧AI, 计算机视觉