1. 开发环境搭建

AR特效与人脸检测项目的开发环境搭建是后续所有案例实现的基础。本章将引导你选择并配置合适的开发工具链，确保OpenCV与MediaPipe库能够正确集成，并通过一个基础的人脸检测Demo验证环境的可用性。

1.1 选择IDE与SDK

根据目标平台选择主流的开发环境：

1.2 配置OpenCV与MediaPipe

OpenCV 提供了基础图像处理和人脸检测的经典算法；MediaPipe 则提供高效、轻量级的机器学习模型管线。两者协同工作，实现高帧率下的稳定人脸跟踪。

1.2.1 Android项目中的CMake集成

以Android Studio + CMake为例，在模块级 build.gradle 中指定NDK版本，并链接预编译的OpenCV native库与MediaPipe AAR包。

// app/build.gradle
android {
    compileSdk 34
    ndkVersion "27.0.12077973"

    defaultConfig {
        minSdk 24
        targetSdk 34
        externalNativeBuild {
            cmake {
                cppFlags "-std=c++17 -frtti -fexceptions"
                arguments "-DOpenCV_DIR=${project.projectDir}/../sdk/native/jni"
            }
        }
    }
    externalNativeBuild {
        cmake {
            path "src/main/cpp/CMakeLists.txt"
        }
    }
}

dependencies {
    // OpenCV Java API (用于辅助加载)
    implementation 'com.quickbirdstudios:opencv:4.9.0-beta-2'
    // MediaPipe Face Detection API
    implementation 'com.google.mediapipe:facedetection:0.10.14'
}

CMakeLists.txt 核心片段：

cmake_minimum_required(VERSION 3.22)
project("ar_face_detection")

# 导入OpenCV
set(OpenCV_DIR ${PROJECT_SOURCE_DIR}/../../sdk/native/jni)
find_package(OpenCV REQUIRED)

# 添加MediaPipe的C++接口
add_library(mediapipe_jni SHARED IMPORTED)
set_target_properties(mediapipe_jni PROPERTIES
    IMPORTED_LOCATION ${PROJECT_SOURCE_DIR}/../libs/${ANDROID_ABI}/libmediapipe_jni.so
)

add_library(native-lib SHARED
    native-lib.cpp
    face_pipeline.cpp
)

target_link_libraries(native-lib
    ${OpenCV_LIBS}
    mediapipe_jni
    log
    android
)

1.2.2 MediaPipe图配置

MediaPipe使用二进制图（.binarypb）描述处理管线。人脸检测常使用 face_detection_front_short_range.tflite 模型，通过 CalculatorGraphConfig 构建推理节点。

# 简化配置示意：MediaPipe图定义
input_stream: "input_video"
output_stream: "detections"

node {
  calculator: "FlowLimiterCalculator"
  input_stream: "input_video"
  output_stream: "throttled_input_video"
}
node {
  calculator: "FaceDetectionShortRangeCpu"
  input_stream: "IMAGE:throttled_input_video"
  output_stream: "DETECTIONS:detections"
}

1.3 验证人脸检测基础Demo

配置完成后，通过一个简单的C++调用验证环境是否正常工作。核心逻辑：初始化MediaPipe图，将OpenCV的Mat转换为MediaPipe的ImageFrame，输入图并获取人脸检测结果。

关键代码流程：

#include <opencv2/opencv.hpp>
#include "mediapipe/framework/calculator_framework.h"
#include "mediapipe/framework/formats/image_frame.h"

// 1. 初始化MediaPipe图
mediapipe::CalculatorGraph graph;
mediapipe::Status status = graph.Initialize(kFaceDetectionGraphConfig);
if (!status.ok()) { LOGE("初始化失败: %s", status.message().c_str()); return; }

// 2. 启动图
graph.StartRun({});

// 3. 将OpenCV Mat转换为MediaPipe ImageFrame
cv::Mat frame = /* 从相机或图片读取 */;
auto input_frame = std::make_unique<mediapipe::ImageFrame>(
    mediapipe::ImageFormat::SRGB, frame.cols, frame.rows,
    mediapipe::ImageFrame::kDefaultAlignmentBoundary);
frame.copyTo(mediapipe::formats::MatView(input_frame.get()));

// 4. 输入帧并获取结果
graph.AddPacketToInputStream("input_video",
    mediapipe::Adopt(input_frame.release()).At(mediapipe::Timestamp(0)));

// 5. 在输出流回调中提取人脸框
graph.ObserveOutputStream("detections", [](const mediapipe::Packet& packet) {
    auto detections = packet.Get<std::vector<mediapipe::Detection>>();
    // 遍历detections，绘制人脸框
    return mediapipe::OkStatus();
});

1.4 常见环境错误处理

完整环境搭建结构