尧图网站建设 
简介Android人体检测APP Demo压缩包提供可直接在Android设备上安装运行的APK与项目元数据JSON面向需要快速落地移动端人体/行人检测能力的开发者、算法工程师及学生可作为移动端目标检测应用开发的起点工程。包内APK支持实时人体检测便于实验验证、产品原型制作或学习目标检测模型在端侧部署流程JSON文件为构建输出信息可用来确认版本与打包配置。资源共2个文件总大小约50.6MB轻量精简下载与安装测试都很方便。截至当前已有2908人学习使用作者为CSDN博主guyuealian内容与其行人检测系列技术文章配套可结合具体教程进一步理解数据集准备、模型训练与端侧部署细节。整体来看这份Demo能帮助开发者跳过复杂环境搭建直接体验实时检测效果也为后续二次开发和算法优化提供了清晰的基线工程。 在移动端做实时人体检测第一反应往往是“又要接一堆SDK”“模型跑不动”“帧率上不去”但实话实说Android平台上借助现成的深度学习推理框架做一个能跑起来的人体检测Demo并没有想象中那么复杂。这个标题里的zip包本质上就是一个可运行的项目模板今天这篇东西我就按“从零拉到能跑”这个目标把整个路上要踩的坑、要做的关键决策全部捋一遍争取让一个刚接触Android开发但懂点基础的朋友也能在半天内把Demo跑起来并且跑到手机上真机预览。先说这个项目是什么它不依赖云服务器所有检测都在手机本地完成模型可以做到实时处理摄像头画面在画面上框出人体位置并给出置信度。适合的人群主要是这几类想入门端侧AI应用的Android开发同学需要快速验证人体检测效果的算法工程师以及做智能硬件、需要把人体识别能力集成进移动端的嵌入式朋友。整个拆解会分五个部分方案选型、环境配置、核心代码实现、性能调优、常见问题。每个部分我都会给出真实可用的经验和建议也会把一些常见的“想当然”误区挑明帮你避开一些会白耗时间的地方。1. 技术方案选型为什么综合下来选定了MediaPipe加TFLite的组合人体检测在移动端目前的成熟路线大概有三条直接调用系统级的人脸/人体检测接口使用第三方云服务SDK以及在本地跑一个深度学习模型。这个Demo最终采用的是第三条路线具体组合是MediaPipe的Pose或Detection模块配合TensorFlow Lite作为底层推理引擎这个选择的理由需要展开说清楚。1.1 三条路线的真实对比系统级接口这条路比如Android自带的FaceDetector优点是零额外依赖、调用简单但缺点很明显它只支持人脸检测很少支持全身人体包围框即便某些系统有Person Detection能力也只有部分机型开放。对于“人体检测”这个需求来说覆盖度和跨机型一致性都不太行。云服务SDK这条路例如某些大厂的视觉API精度通常不错但实时性很难保证。实时预览场景要求单帧处理在100毫秒以内网络往返一次就很容易超时丢帧、卡顿也是家常便饭。而且云服务需要注册、获取密钥、计费对Demo来说比较麻烦断网环境直接就废了。本地模型这条路也就是MediaPipe在这类场景下的做法算是实时性和精度权衡之后的最佳解。模型直接打包在APK里推理全部走手机端的CPU或GPU不依赖网络单帧推理时间在主流中端机上可以做到20-50毫秒配合摄像头采集和渲染整体帧率能稳定在20到30FPS之间对于实时人体检测这个场景来说已经足够顺滑了。1.2 为什么单独提MediaPipe而不是直接上裸TFLiteTensorFlow Lite本身只是一个推理引擎它负责把训练好的模型跑起来但如果你直接用裸TFLite做人体检测还要自己做很多周边工作相机流的采集和格式转换、图像预处理缩放、归一化、通道顺序调整、模型输入输出的张量封装、检测结果的坐标解析和非极大值抑制、最后在预览画面上绘制框体。这一套下来核心的“检测”逻辑其实只占一小部分大部分时间都花在图像处理和工程封装上。MediaPipe则把这些周边能力全部抽象成了流水线组件。它本身基于图Graph的机制把输入视频流、预处理算子、模型推理、后处理算子串起来开发者只需要配置图和节点然后从输出端拿到解析好的检测结果。对做Demo这个目标来说MediaPipe能省掉至少一半的工程代码量而且官方维护的模型在移动端做过针对性的优化模型尺寸也控制得比较小。1.3 这个方案最大的代价是什么MediaPipe也不是没有成本。它引入了一个相对独立的框架层如果后续需要深度定制模型结构或者自己训练一个专用人体检测模型MediaPipe的封装反而会有点约束你需要自己导出TFLite模型并接入自定义算子。另外有段时间MediaPipe的Android依赖版本拆分得比较碎稍不小心就会遇到依赖冲突不过现在已经统一了。对于Demo阶段“能跑、能看效果、代码简洁”胜过一切所以综合选型就这么定了。2. 开发环境与准备工作Android Studio配置、依赖引入和模型文件部署很多朋友拿到一个可运行的zip项目第一件事就是直接打开、同步、点Run结果一上来就报错。倒不是代码的问题而是本地开发环境和项目原作者的版本不匹配。这里把环境准备阶段的事项理清楚照着操作可以少走很多弯路。2.1 开发工具与SDK版本选择建议这个Demo的构建是基于Android Gradle Plugin的所以首先需要安装Android Studio。官方推荐用最新稳定版其实只要版本不低于项目里Gradle插件要求的版本就行。建议直接安装Android Studio Hedgehog及以后的版本Gradle插件版本保持在7.5以上。SDK方面建议安装API 33或34的平台同时保证Build-Tools版本不低于30.0.0。如果你电脑上同时装了多个JDK注意Android Studio所用的JDK版本不能太高或太低目前比较稳的是JDK 11或JDK 17。Gradle本身和JDK版本有兼容关系JDK版本过高会导致DSL解析错误过低则某些新语法不支持这个属于最典型的“环境不一致”报错来源。提示打开zip项目后如果Gradle同步卡在下载依赖的步骤很久建议先检查网络环境Android开发常见的依赖源是Google Maven和Maven Central这两个仓库在国内访问速度不算快可以考虑配置镜像仓库。2.2 在build.gradle中引入MediaPipe和Camera相关依赖环境准备的核心步骤是在模块级别的build.gradle文件里加入MediaPipe的依赖。需要注意2023年以后MediaPipe的Android依赖改成了以功能模块划分的独立aar不再是一个大而全的包。以人体检测为例需要加入mediapipe-tasks-vision这个依赖它提供了统一的视觉任务API。dependencies { // MediaPipe视觉任务库包含人体检测器 implementation com.google.mediapipe:tasks-vision:0.10.14 // Android相机核心库用于接入CameraX或Camera2 implementation androidx.camera:camera-core:1.3.0 implementation androidx.camera:camera-camera2:1.3.0 implementation androidx.camera:camera-lifecycle:1.3.0 implementation androidx.camera:camera-view:1.3.0 // 异步执行相关协程也可以但这里用简单的ExecutorService implementation androidx.concurrent:concurrent-futures:1.1.0 }关于CameraX和Camera2的选择新的项目我比较推荐直接用CameraX。它在Camera2之上封装了一层生命周期感知的抽象ImageAnalysis用例会自动处理图像格式和旋转角度开发效率明显更高。这个Demo用CameraX来实现实时预览用一个分析用例把每一帧图像交给人体检测器处理。2.3 模型文件的放置路径和配置方式MediaPipe提供了一套官方训练好的模型文件人体检测这个场景直接用MoveNet或Pose Landmarker模型都可以。其中MoveNet是一个轻量级的姿态估计模型能够输出人的17个关键点足以画出人体骨架框。Pose Landmarker则更进一步它会输出33个关键点和连接关系可以描绘非常细致的人体姿态。对于纯检测框需求MoveNet就够用了对于姿态可视化选Pose Landmarker。模型文件的放置路径需要记住Android项目里需要新建assets目录然后把.tflite模型文件拷贝进去。app/ src/ main/ assets/ movenet.tflite // 人体姿态/检测模型在代码中通过MediaPipe的ModelPath参数来指定模型路径。这里有个小坑如果你把模型文件放在了assets的子目录里路径要写对例如“models/movenet.tflite”不能只写文件名否则会抛出文件找不到的异常。// 构建人体检测器选项 PoseLandmarkerOptions options PoseLandmarkerOptions.builder() .setBaseOptions(BaseOptions.builder() .setModelAssetPath(movenet.tflite) .setDelegate(Delegate.GPU) .build()) .setRunningMode(RunningMode.LIVE_STREAM) .build();3. 核心实现逻辑与代码级详解相机流接入、模型推理与结果渲染整个Demo的运行时流程可以拆成三个部分相机帧的获取与格式转换、将帧送入模型做推理、拿到检测结果后绘制到预览界面。这三部分在MediaPipe的LIVE_STREAM模式下是并行流水线工作的这也是实时性的关键。3.1 相机预览与图像分析链路CameraX的ImageAnalysis是接住相机帧的核心入口。它会在后台线程回调每一帧的ImageProxy我们在这个回调里完成格式转换和推理操作。默认的ImageProxy格式是YUV_420_888MediaPipe的API可以直接接收Bitmap或MediaImage所以需要先把YUV转成Bitmap。CameraX提供了一行代码搞定这个转换基于新的接口很方便。ImageProxy imageProxy image; // 将YUV格式图像转换为Bitmap注意这里必须拷贝一次因为ImageProxy在回调结束后会被回收 Bitmap bitmap ImageUtils.imageProxyToBitmap(imageProxy);媒体库会把每一帧通过ImageProxy传递给我但这里一定要留意ImageProxy是一个可复用对象如果不及时关闭渲染管线会卡死。正确的做法是在推理完成并把Bitmap数据用完之后立刻调用imageProxy.close()。3.2 使用MediaPipe的LIVE_STREAM模式进行检测MediaPipe的PoseLandmarker支持三种运行模式IMAGE、VIDEO和LIVE_STREAM。IMAGE模式适合单张图片检测一次就返回VIDEO模式需要显式传入时间戳适合离线视频文件LIVE_STREAM模式为摄像头实时流设计底层会自动做异步调度同时支持通过ResultListener回调结果。// 初始化PoseLandmarker实例 PoseLandmarker poseLandmarker PoseLandmarker.createFromOptions(context, options); // 在ImageAnalysis的分析器中每帧调用检测 long frameTime SystemClock.uptimeMillis(); // 必须使用递增的时间戳 poseLandmarker.detectAsync(bitmap, frameTime);3.3 获取人体关键点与绘制检测框检测完成后结果会通过ResultListener回调返回。PoseLandmarkerResult里面包含了每个被检测到的人体关键点坐标列表坐标是归一化的0到1之间绘制时需要乘以视图的实际宽高。poseLandmarker.detectAsync(bitmap, frameTime, result - { ListPoseLandmarkerResult.Pose poses result.landmarks(); // 在UI线程更新自定义View绘制骨架和检测框 runOnUiThread(() - { overlayView.setPoses(poses); overlayView.invalidate(); }); });绘制部分建议自己写一个自定义View继承自View在onDraw里用Canvas绘制。遍历每一个Pose先连接关键点之间的线比如肩到肘肘到腕再根据关键点坐标的最小和最大值生成人体包围盒用Paint画出矩形顺手把置信度文本也画出来。一个关键技巧预览画面、图像分析的分辨率、自定义View的尺寸这三者之间往往不一致绘制时必须把归一化坐标转换成View坐标转换公式是像素坐标 归一化坐标 × View宽度或高度。否则会出现框能画出来但框和人体错位严重的情况排查这个问题的过程很折磨人。3.4 图像旋转与镜像问题的处理手机上摄像头采集到的图像默认带有旋转角度Android的传感器方向通常是90度或270度。CameraX的ImageAnalysis在内部会处理好目标旋转但在转换成Bitmap做模型推理的时候如果直接拿原始旋转的Bitmap模型看到的可能是一个歪着的人体检测效果会明显变差。处理方式是在ImageAnalysis.Builder里设置setTargetRotation(Surface.ROTATION_90)让CameraX在分析链路里提前处理好旋转。前置摄像头还有一个镜像问题很多人习惯自拍时看到的是镜像画面但分析帧可能不是镜像的两者对不上会显得很别扭。简单的做法是统一用Matrix给Bitmap做一次水平翻转保证预览和检测结果都在同一坐标系下。4. 实时性能调优与实践心得帧率、延迟、耗电的三方权衡Demo能跑起来是一回事跑得顺不顺是另一回事。自己在调这个项目时试了几组不同的参数组合中间也踩过一些明显的坑这里直接给结论。4.1 模型分辨率与输入尺寸的极限测试MoveNet有两种输入分辨率256x256和128x128。256版本的精度相对好一些但推理时间大约是128版本的1.5到2倍。在Pixel 5这类中端机上实测256版本CPU推理大约45毫秒128版本大约25毫秒。GPU委托之后能再快30%左右。实时预览场景我倾向于把分析用例的分辨率控制在640x480然后模型输入用256这样既能保证画面清晰度又不会让检测精度掉太多。4.2 关于GPU委托和NNAPI的一点个人看法MediaPipe支持通过BaseOptions.setDelegate(Delegate.GPU)把推理任务放到GPU上执行这个对多数机型有效但不绝对。某些老款机型或特定GPU驱动下GPU委托反而会导致初始化失败或者推理变慢此时需要动态降级BaseOptions.Builder baseOptionsBuilder BaseOptions.builder() .setModelAssetPath(movenet.tflite) .setDelegate(Delegate.GPU); // 尝试创建如果失败则回退到CPU try { PoseLandmarker.createFromOptions(context, options); } catch (Exception e) { baseOptionsBuilder.setDelegate(Delegate.CPU); options PoseLandmarkerOptions.builder() .setBaseOptions(baseOptionsBuilder.build()) .setRunningMode(RunningMode.LIVE_STREAM) .build(); }NNAPI这个方案在多数Android设备上支持情况一般特别是厂商驱动版本差异大我自己的实测结果是兼容性不如GPU委托稳定。所以如果GPU不可用直接回退CPU不要恋战NNAPI。4.3 帧处理节奏的控制丢帧策略比贪多更实际实时检测时如果每一帧都送进模型在机型配置不够的情况下待处理帧会越积越多延迟越来越高。一个比较稳的控制策略是只有当上一帧处理完成之后才从ImageAnalysis中获取最新的一帧进行处理。实现方式是设置一个AtomicBoolean标志位处理完一帧再置为false否则本次回调直接关闭ImageProxy并返回。这个小小的丢帧策略可以让整体的视觉流畅度提升一个档次因为永远在处理最新的那一帧而不是堵在旧帧上。5. 常见问题与排查技巧实录从Gradle崩溃到画面全黑的实战记录5.1 编译期问题依赖冲突、命名空间错误、Gradle插件兼容实际在跑项目时碰到的第一个报错几乎都集中在Gradle同步阶段。最常见的一个是“Conflict with dependency com.google.guava:listenablefuture in project”这是Guava依赖冲突的老问题在app模块的build.gradle里加一行配置就能解决configurations.all { exclude group: com.google.guava, module: listenablefuture }另一个高频报错是“Namespace not specified”这出现在AGP 8.0之后的Android Gradle插件中新版本要求必须在模块级build.gradle里显式声明namespace如果项目原作者没有加需要手动补充android { namespace com.example.humandetection }5.2 运行期画面黑屏但应用不崩溃画面黑屏的情况我刚开始调试时也遇到过。排查思路按顺序来先确认权限相机权限没有授予SurfaceView拿到的是黑屏再确认CameraX的绑定流程是否有将PreviewView和分析用例绑定到同一个生命周期最后确认相机是否被其他应用占用。其中比较隐蔽的一个坑是在Android 6.0以上系统运行应用即使你在Manifest里声明了相机权限运行时仍然需要动态申请权限。如果漏了申请CameraX的绑定过程会静默失败不会抛异常但画面就是黑的。务必在MainActivity的onCreate里加上运行时权限请求逻辑。5.3 检测框位置偏移或显示比例错乱检测框出现但不贴合人体通常原因是坐标系换算弄错了。模型输出的是归一化坐标计算实际坐标时必须基于当前预览画面的实际尺寸而不是屏幕尺寸。如果预览画面是16:9而自定义View被拉伸成4:3画出来的框就会整体偏离。建议自定义View在onLayout中获取实际宽高并且按分析帧的比例做fitCenter适配保证View内部的坐标系和分析帧保持一致。5.4 内存占用过高和连续运行发热问题端侧模型推理虽然不像训练那样吃显存但长时间运行后内存也会缓慢上涨。排查重点放在ImageProxy泄漏上确保每个分析回调都执行了close操作。此外确认没有在每帧创建Bitmap后忘记回收。一旦确认存在泄漏可以用Android Studio自带的Memory Profiler抓一次内存快照对象分配时会非常直观地看到哪些对象没有被释放。发热问题本质上就是性能策略没有做好。在备用机比如只有中低端芯片的老机型上强行跑高分辨率模型几轮之后就会降频掉帧。建议在检测结果回调里做一次性能统计通过计算相邻两帧的时间差动态调整图像分辨率或检测频率效果会比固定参数好一些。5.5 常见问题速查表问题现象主要原因快速排查与建议Gradle同步失败依赖冲突或仓库配置缺失添加配置检查Google Maven和Maven Central仓库运行即崩溃模型文件路径错误或模型未拷贝确认assets目录与ModelAssetPath完全匹配预览黑屏缺少相机运行时权限动态权限申请务必完整检查绑定流程每帧卡顿严重CPU委托处理高分辨率图像降低分析分辨率开启GPU委托画面能跑但检测不到人体输入图像旋转或镜像未处理设置targetRotation统一坐标系内存持续上涨ImageProxy未及时关闭每个回调中确保imageProxy.close()被调用最后一个很实在的建议做实时人体检测Demo最忌一上来就想做一套完美的产品。先把“打开App - 看到相机画面 - 画面里有人体框跟着动”这条最简单的链路跑通再谈优化模型精度、降低延迟、适配更多设备。我自己在实际操作中的体会是端侧AI应用最核心的调试工具不是IDE而是你对整条数据流的理解有多深从相机的像素矩阵到模型的张量输入再到屏幕上的坐标矩形每一环的格式和坐标系是否对齐直接决定了最终效果是否可用。这个zip项目如果能跑通建议接着自己动手改一改换成自己的模型、调整帧率策略甚至接上蓝牙上报检测结果都是很好的扩展方向很多智能硬件原型就是这样一点点长出来的。本文还有配套的精品资源点击获取 Android端实时人体检测实战：MediaPipe与TFLite从零搭建
简介Android人体检测APP Demo压缩包提供可直接在Android设备上安装运行的APK与项目元数据JSON面向需要快速落地移动端人体/行人检测能力的开发者、算法工程师及学生可作为移动端目标检测应用开发的起点工程。包内APK支持实时人体检测便于实验验证、产品原型制作或学习目标检测模型在端侧部署流程JSON文件为构建输出信息可用来确认版本与打包配置。资源共2个文件总大小约50.6MB轻量精简下载与安装测试都很方便。截至当前已有2908人学习使用作者为CSDN博主guyuealian内容与其行人检测系列技术文章配套可结合具体教程进一步理解数据集准备、模型训练与端侧部署细节。整体来看这份Demo能帮助开发者跳过复杂环境搭建直接体验实时检测效果也为后续二次开发和算法优化提供了清晰的基线工程。 在移动端做实时人体检测第一反应往往是“又要接一堆SDK”“模型跑不动”“帧率上不去”但实话实说Android平台上借助现成的深度学习推理框架做一个能跑起来的人体检测Demo并没有想象中那么复杂。这个标题里的zip包本质上就是一个可运行的项目模板今天这篇东西我就按“从零拉到能跑”这个目标把整个路上要踩的坑、要做的关键决策全部捋一遍争取让一个刚接触Android开发但懂点基础的朋友也能在半天内把Demo跑起来并且跑到手机上真机预览。先说这个项目是什么它不依赖云服务器所有检测都在手机本地完成模型可以做到实时处理摄像头画面在画面上框出人体位置并给出置信度。适合的人群主要是这几类想入门端侧AI应用的Android开发同学需要快速验证人体检测效果的算法工程师以及做智能硬件、需要把人体识别能力集成进移动端的嵌入式朋友。整个拆解会分五个部分方案选型、环境配置、核心代码实现、性能调优、常见问题。每个部分我都会给出真实可用的经验和建议也会把一些常见的“想当然”误区挑明帮你避开一些会白耗时间的地方。1. 技术方案选型为什么综合下来选定了MediaPipe加TFLite的组合人体检测在移动端目前的成熟路线大概有三条直接调用系统级的人脸/人体检测接口使用第三方云服务SDK以及在本地跑一个深度学习模型。这个Demo最终采用的是第三条路线具体组合是MediaPipe的Pose或Detection模块配合TensorFlow Lite作为底层推理引擎这个选择的理由需要展开说清楚。1.1 三条路线的真实对比系统级接口这条路比如Android自带的FaceDetector优点是零额外依赖、调用简单但缺点很明显它只支持人脸检测很少支持全身人体包围框即便某些系统有Person Detection能力也只有部分机型开放。对于“人体检测”这个需求来说覆盖度和跨机型一致性都不太行。云服务SDK这条路例如某些大厂的视觉API精度通常不错但实时性很难保证。实时预览场景要求单帧处理在100毫秒以内网络往返一次就很容易超时丢帧、卡顿也是家常便饭。而且云服务需要注册、获取密钥、计费对Demo来说比较麻烦断网环境直接就废了。本地模型这条路也就是MediaPipe在这类场景下的做法算是实时性和精度权衡之后的最佳解。模型直接打包在APK里推理全部走手机端的CPU或GPU不依赖网络单帧推理时间在主流中端机上可以做到20-50毫秒配合摄像头采集和渲染整体帧率能稳定在20到30FPS之间对于实时人体检测这个场景来说已经足够顺滑了。1.2 为什么单独提MediaPipe而不是直接上裸TFLiteTensorFlow Lite本身只是一个推理引擎它负责把训练好的模型跑起来但如果你直接用裸TFLite做人体检测还要自己做很多周边工作相机流的采集和格式转换、图像预处理缩放、归一化、通道顺序调整、模型输入输出的张量封装、检测结果的坐标解析和非极大值抑制、最后在预览画面上绘制框体。这一套下来核心的“检测”逻辑其实只占一小部分大部分时间都花在图像处理和工程封装上。MediaPipe则把这些周边能力全部抽象成了流水线组件。它本身基于图Graph的机制把输入视频流、预处理算子、模型推理、后处理算子串起来开发者只需要配置图和节点然后从输出端拿到解析好的检测结果。对做Demo这个目标来说MediaPipe能省掉至少一半的工程代码量而且官方维护的模型在移动端做过针对性的优化模型尺寸也控制得比较小。1.3 这个方案最大的代价是什么MediaPipe也不是没有成本。它引入了一个相对独立的框架层如果后续需要深度定制模型结构或者自己训练一个专用人体检测模型MediaPipe的封装反而会有点约束你需要自己导出TFLite模型并接入自定义算子。另外有段时间MediaPipe的Android依赖版本拆分得比较碎稍不小心就会遇到依赖冲突不过现在已经统一了。对于Demo阶段“能跑、能看效果、代码简洁”胜过一切所以综合选型就这么定了。2. 开发环境与准备工作Android Studio配置、依赖引入和模型文件部署很多朋友拿到一个可运行的zip项目第一件事就是直接打开、同步、点Run结果一上来就报错。倒不是代码的问题而是本地开发环境和项目原作者的版本不匹配。这里把环境准备阶段的事项理清楚照着操作可以少走很多弯路。2.1 开发工具与SDK版本选择建议这个Demo的构建是基于Android Gradle Plugin的所以首先需要安装Android Studio。官方推荐用最新稳定版其实只要版本不低于项目里Gradle插件要求的版本就行。建议直接安装Android Studio Hedgehog及以后的版本Gradle插件版本保持在7.5以上。SDK方面建议安装API 33或34的平台同时保证Build-Tools版本不低于30.0.0。如果你电脑上同时装了多个JDK注意Android Studio所用的JDK版本不能太高或太低目前比较稳的是JDK 11或JDK 17。Gradle本身和JDK版本有兼容关系JDK版本过高会导致DSL解析错误过低则某些新语法不支持这个属于最典型的“环境不一致”报错来源。提示打开zip项目后如果Gradle同步卡在下载依赖的步骤很久建议先检查网络环境Android开发常见的依赖源是Google Maven和Maven Central这两个仓库在国内访问速度不算快可以考虑配置镜像仓库。2.2 在build.gradle中引入MediaPipe和Camera相关依赖环境准备的核心步骤是在模块级别的build.gradle文件里加入MediaPipe的依赖。需要注意2023年以后MediaPipe的Android依赖改成了以功能模块划分的独立aar不再是一个大而全的包。以人体检测为例需要加入mediapipe-tasks-vision这个依赖它提供了统一的视觉任务API。dependencies { // MediaPipe视觉任务库包含人体检测器 implementation com.google.mediapipe:tasks-vision:0.10.14 // Android相机核心库用于接入CameraX或Camera2 implementation androidx.camera:camera-core:1.3.0 implementation androidx.camera:camera-camera2:1.3.0 implementation androidx.camera:camera-lifecycle:1.3.0 implementation androidx.camera:camera-view:1.3.0 // 异步执行相关协程也可以但这里用简单的ExecutorService implementation androidx.concurrent:concurrent-futures:1.1.0 }关于CameraX和Camera2的选择新的项目我比较推荐直接用CameraX。它在Camera2之上封装了一层生命周期感知的抽象ImageAnalysis用例会自动处理图像格式和旋转角度开发效率明显更高。这个Demo用CameraX来实现实时预览用一个分析用例把每一帧图像交给人体检测器处理。2.3 模型文件的放置路径和配置方式MediaPipe提供了一套官方训练好的模型文件人体检测这个场景直接用MoveNet或Pose Landmarker模型都可以。其中MoveNet是一个轻量级的姿态估计模型能够输出人的17个关键点足以画出人体骨架框。Pose Landmarker则更进一步它会输出33个关键点和连接关系可以描绘非常细致的人体姿态。对于纯检测框需求MoveNet就够用了对于姿态可视化选Pose Landmarker。模型文件的放置路径需要记住Android项目里需要新建assets目录然后把.tflite模型文件拷贝进去。app/ src/ main/ assets/ movenet.tflite // 人体姿态/检测模型在代码中通过MediaPipe的ModelPath参数来指定模型路径。这里有个小坑如果你把模型文件放在了assets的子目录里路径要写对例如“models/movenet.tflite”不能只写文件名否则会抛出文件找不到的异常。// 构建人体检测器选项 PoseLandmarkerOptions options PoseLandmarkerOptions.builder() .setBaseOptions(BaseOptions.builder() .setModelAssetPath(movenet.tflite) .setDelegate(Delegate.GPU) .build()) .setRunningMode(RunningMode.LIVE_STREAM) .build();3. 核心实现逻辑与代码级详解相机流接入、模型推理与结果渲染整个Demo的运行时流程可以拆成三个部分相机帧的获取与格式转换、将帧送入模型做推理、拿到检测结果后绘制到预览界面。这三部分在MediaPipe的LIVE_STREAM模式下是并行流水线工作的这也是实时性的关键。3.1 相机预览与图像分析链路CameraX的ImageAnalysis是接住相机帧的核心入口。它会在后台线程回调每一帧的ImageProxy我们在这个回调里完成格式转换和推理操作。默认的ImageProxy格式是YUV_420_888MediaPipe的API可以直接接收Bitmap或MediaImage所以需要先把YUV转成Bitmap。CameraX提供了一行代码搞定这个转换基于新的接口很方便。ImageProxy imageProxy image; // 将YUV格式图像转换为Bitmap注意这里必须拷贝一次因为ImageProxy在回调结束后会被回收 Bitmap bitmap ImageUtils.imageProxyToBitmap(imageProxy);媒体库会把每一帧通过ImageProxy传递给我但这里一定要留意ImageProxy是一个可复用对象如果不及时关闭渲染管线会卡死。正确的做法是在推理完成并把Bitmap数据用完之后立刻调用imageProxy.close()。3.2 使用MediaPipe的LIVE_STREAM模式进行检测MediaPipe的PoseLandmarker支持三种运行模式IMAGE、VIDEO和LIVE_STREAM。IMAGE模式适合单张图片检测一次就返回VIDEO模式需要显式传入时间戳适合离线视频文件LIVE_STREAM模式为摄像头实时流设计底层会自动做异步调度同时支持通过ResultListener回调结果。// 初始化PoseLandmarker实例 PoseLandmarker poseLandmarker PoseLandmarker.createFromOptions(context, options); // 在ImageAnalysis的分析器中每帧调用检测 long frameTime SystemClock.uptimeMillis(); // 必须使用递增的时间戳 poseLandmarker.detectAsync(bitmap, frameTime);3.3 获取人体关键点与绘制检测框检测完成后结果会通过ResultListener回调返回。PoseLandmarkerResult里面包含了每个被检测到的人体关键点坐标列表坐标是归一化的0到1之间绘制时需要乘以视图的实际宽高。poseLandmarker.detectAsync(bitmap, frameTime, result - { ListPoseLandmarkerResult.Pose poses result.landmarks(); // 在UI线程更新自定义View绘制骨架和检测框 runOnUiThread(() - { overlayView.setPoses(poses); overlayView.invalidate(); }); });绘制部分建议自己写一个自定义View继承自View在onDraw里用Canvas绘制。遍历每一个Pose先连接关键点之间的线比如肩到肘肘到腕再根据关键点坐标的最小和最大值生成人体包围盒用Paint画出矩形顺手把置信度文本也画出来。一个关键技巧预览画面、图像分析的分辨率、自定义View的尺寸这三者之间往往不一致绘制时必须把归一化坐标转换成View坐标转换公式是像素坐标 归一化坐标 × View宽度或高度。否则会出现框能画出来但框和人体错位严重的情况排查这个问题的过程很折磨人。3.4 图像旋转与镜像问题的处理手机上摄像头采集到的图像默认带有旋转角度Android的传感器方向通常是90度或270度。CameraX的ImageAnalysis在内部会处理好目标旋转但在转换成Bitmap做模型推理的时候如果直接拿原始旋转的Bitmap模型看到的可能是一个歪着的人体检测效果会明显变差。处理方式是在ImageAnalysis.Builder里设置setTargetRotation(Surface.ROTATION_90)让CameraX在分析链路里提前处理好旋转。前置摄像头还有一个镜像问题很多人习惯自拍时看到的是镜像画面但分析帧可能不是镜像的两者对不上会显得很别扭。简单的做法是统一用Matrix给Bitmap做一次水平翻转保证预览和检测结果都在同一坐标系下。4. 实时性能调优与实践心得帧率、延迟、耗电的三方权衡Demo能跑起来是一回事跑得顺不顺是另一回事。自己在调这个项目时试了几组不同的参数组合中间也踩过一些明显的坑这里直接给结论。4.1 模型分辨率与输入尺寸的极限测试MoveNet有两种输入分辨率256x256和128x128。256版本的精度相对好一些但推理时间大约是128版本的1.5到2倍。在Pixel 5这类中端机上实测256版本CPU推理大约45毫秒128版本大约25毫秒。GPU委托之后能再快30%左右。实时预览场景我倾向于把分析用例的分辨率控制在640x480然后模型输入用256这样既能保证画面清晰度又不会让检测精度掉太多。4.2 关于GPU委托和NNAPI的一点个人看法MediaPipe支持通过BaseOptions.setDelegate(Delegate.GPU)把推理任务放到GPU上执行这个对多数机型有效但不绝对。某些老款机型或特定GPU驱动下GPU委托反而会导致初始化失败或者推理变慢此时需要动态降级BaseOptions.Builder baseOptionsBuilder BaseOptions.builder() .setModelAssetPath(movenet.tflite) .setDelegate(Delegate.GPU); // 尝试创建如果失败则回退到CPU try { PoseLandmarker.createFromOptions(context, options); } catch (Exception e) { baseOptionsBuilder.setDelegate(Delegate.CPU); options PoseLandmarkerOptions.builder() .setBaseOptions(baseOptionsBuilder.build()) .setRunningMode(RunningMode.LIVE_STREAM) .build(); }NNAPI这个方案在多数Android设备上支持情况一般特别是厂商驱动版本差异大我自己的实测结果是兼容性不如GPU委托稳定。所以如果GPU不可用直接回退CPU不要恋战NNAPI。4.3 帧处理节奏的控制丢帧策略比贪多更实际实时检测时如果每一帧都送进模型在机型配置不够的情况下待处理帧会越积越多延迟越来越高。一个比较稳的控制策略是只有当上一帧处理完成之后才从ImageAnalysis中获取最新的一帧进行处理。实现方式是设置一个AtomicBoolean标志位处理完一帧再置为false否则本次回调直接关闭ImageProxy并返回。这个小小的丢帧策略可以让整体的视觉流畅度提升一个档次因为永远在处理最新的那一帧而不是堵在旧帧上。5. 常见问题与排查技巧实录从Gradle崩溃到画面全黑的实战记录5.1 编译期问题依赖冲突、命名空间错误、Gradle插件兼容实际在跑项目时碰到的第一个报错几乎都集中在Gradle同步阶段。最常见的一个是“Conflict with dependency com.google.guava:listenablefuture in project”这是Guava依赖冲突的老问题在app模块的build.gradle里加一行配置就能解决configurations.all { exclude group: com.google.guava, module: listenablefuture }另一个高频报错是“Namespace not specified”这出现在AGP 8.0之后的Android Gradle插件中新版本要求必须在模块级build.gradle里显式声明namespace如果项目原作者没有加需要手动补充android { namespace com.example.humandetection }5.2 运行期画面黑屏但应用不崩溃画面黑屏的情况我刚开始调试时也遇到过。排查思路按顺序来先确认权限相机权限没有授予SurfaceView拿到的是黑屏再确认CameraX的绑定流程是否有将PreviewView和分析用例绑定到同一个生命周期最后确认相机是否被其他应用占用。其中比较隐蔽的一个坑是在Android 6.0以上系统运行应用即使你在Manifest里声明了相机权限运行时仍然需要动态申请权限。如果漏了申请CameraX的绑定过程会静默失败不会抛异常但画面就是黑的。务必在MainActivity的onCreate里加上运行时权限请求逻辑。5.3 检测框位置偏移或显示比例错乱检测框出现但不贴合人体通常原因是坐标系换算弄错了。模型输出的是归一化坐标计算实际坐标时必须基于当前预览画面的实际尺寸而不是屏幕尺寸。如果预览画面是16:9而自定义View被拉伸成4:3画出来的框就会整体偏离。建议自定义View在onLayout中获取实际宽高并且按分析帧的比例做fitCenter适配保证View内部的坐标系和分析帧保持一致。5.4 内存占用过高和连续运行发热问题端侧模型推理虽然不像训练那样吃显存但长时间运行后内存也会缓慢上涨。排查重点放在ImageProxy泄漏上确保每个分析回调都执行了close操作。此外确认没有在每帧创建Bitmap后忘记回收。一旦确认存在泄漏可以用Android Studio自带的Memory Profiler抓一次内存快照对象分配时会非常直观地看到哪些对象没有被释放。发热问题本质上就是性能策略没有做好。在备用机比如只有中低端芯片的老机型上强行跑高分辨率模型几轮之后就会降频掉帧。建议在检测结果回调里做一次性能统计通过计算相邻两帧的时间差动态调整图像分辨率或检测频率效果会比固定参数好一些。5.5 常见问题速查表问题现象主要原因快速排查与建议Gradle同步失败依赖冲突或仓库配置缺失添加配置检查Google Maven和Maven Central仓库运行即崩溃模型文件路径错误或模型未拷贝确认assets目录与ModelAssetPath完全匹配预览黑屏缺少相机运行时权限动态权限申请务必完整检查绑定流程每帧卡顿严重CPU委托处理高分辨率图像降低分析分辨率开启GPU委托画面能跑但检测不到人体输入图像旋转或镜像未处理设置targetRotation统一坐标系内存持续上涨ImageProxy未及时关闭每个回调中确保imageProxy.close()被调用最后一个很实在的建议做实时人体检测Demo最忌一上来就想做一套完美的产品。先把“打开App - 看到相机画面 - 画面里有人体框跟着动”这条最简单的链路跑通再谈优化模型精度、降低延迟、适配更多设备。我自己在实际操作中的体会是端侧AI应用最核心的调试工具不是IDE而是你对整条数据流的理解有多深从相机的像素矩阵到模型的张量输入再到屏幕上的坐标矩形每一环的格式和坐标系是否对齐直接决定了最终效果是否可用。这个zip项目如果能跑通建议接着自己动手改一改换成自己的模型、调整帧率策略甚至接上蓝牙上报检测结果都是很好的扩展方向很多智能硬件原型就是这样一点点长出来的。本文还有配套的精品资源点击获取