MediaPipe手势（Hands）实战：从源码编译到自定义AAR集成

1. 为什么需要自定义MediaPipe Hands的AAR文件

第一次接触MediaPipe的Hands模块时，我也和大多数开发者一样，直接使用官方提供的Maven依赖。但实际开发中很快就遇到了问题：官方库的版本更新不及时，某些优化参数无法调整，甚至遇到CameraX等依赖库的版本冲突。这时候才意识到，掌握从源码编译到集成的完整流程是多么重要。

MediaPipe作为Google开源的跨平台机器学习解决方案，其手势识别（Hands）模块在移动端表现尤为出色。但官方提供的预编译AAR文件存在几个明显局限：

1. 功能固化：无法根据项目需求裁剪不需要的功能模块
2. 参数锁定：关键性能参数如模型精度、推理线程数等无法调整
3. 依赖绑定：强制使用特定版本的配套库（如CameraX 1.0.0-beta10）
4. 定制困难：难以添加业务特有的预处理或后处理逻辑

举个例子，在开发一款AR手势游戏时，我们需要降低模型精度来提升FPS，同时要去除官方库中的日志输出以减少性能开销。这些需求只有通过源码编译才能实现。下面这张对比表能清晰看出差异：

2. 搭建MediaPipe编译环境

2.1 基础环境准备

在Ubuntu 20.04 LTS上搭建MediaPipe的Android编译环境，需要以下组件：

bash复制# 安装必备工具链
sudo apt-get update && sudo apt-get install -y \
    git python3 python3-dev python3-pip \
    openjdk-8-jdk android-sdk-platform-tools \
    bazel build-essential zip unzip

这里有个新手常踩的坑：必须使用OpenJDK 8而非更高版本。我在JDK 11上折腾了半天，直到看到Bazel的报错才恍然大悟。配置环境变量时要注意：

bash复制# 在~/.bashrc末尾添加
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools

2.2 获取MediaPipe源码

推荐使用SSH方式克隆仓库，避免后续认证问题：

bash复制git clone git@github.com:google/mediapipe.git
cd mediapipe
git checkout v0.9.1  # 建议锁定特定版本

如果网络条件不允许，也可以用HTTPS方式克隆，但要注意后续可能需要配置Git凭证：

bash复制git clone https://github.com/google/mediapipe.git

2.3 配置Android NDK和SDK

MediaPipe对NDK版本有严格要求，我测试发现21.1.6352462版本最稳定：

bash复制# 在Android Studio的SDK Manager中安装：
- NDK 21.1.6352462
- Build-Tools 30.0.3
- Platform API 30

# 验证安装
ls $ANDROID_HOME/ndk/21.1.6352462

配置MediaPipe的WORKSPACE文件时，需要修改以下关键参数：

python复制android_sdk_repository(
    name = "androidsdk",
    api_level = 30,
    build_tools_version = "30.0.3",
)

android_ndk_repository(
    name = "androidndk",
    api_level = 21,
)

3. 编译自定义Hands模块

3.1 理解MediaPipe的构建系统

MediaPipe使用Bazel作为构建工具，其核心编译单元是BUILD文件。以Hands模块为例，关键目标位于：

code复制mediapipe/graphs/hand_tracking/
├── BUILD
├── desktop/
├── mobile/
└── subgraphs/

编译前需要明确两个关键产物：

1. solution_core.aar：MediaPipe的核心运行时
2. hands.aar：手势识别的具体实现

3.2 优化编译参数

这是经过多次测试得出的最佳编译配置，在保持性能的同时减小了包体积：

bash复制# 编译solution_core.aar
bazel build -c opt --config=android_arm64 \
    --linkopt=-Wl,--gc-sections \
    --copt=-fvisibility=hidden \
    --copt=-ffunction-sections \
    --copt=-fdata-sections \
    --copt=-Oz \
    //mediapipe/java/com/google/mediapipe/solutioncore:solution_core.aar

# 编译hands.aar
bazel build -c opt --config=android_arm64 \
    --define=MEDIAPIPE_DISABLE_GPU=1 \  # 如果不需GPU加速可禁用
    --copt=-DABSL_MIN_LOG_LEVEL=4 \     # 关闭详细日志
    //mediapipe/java/com/google/mediapipe/solutions/hands:hands.aar

几个实用参数说明：

• --copt=-Oz：最大程度优化大小
• --linkopt=-Wl,--gc-sections：移除未使用的代码段
• --define=MEDIAPIPE_DISABLE_GPU=1：禁用GPU加速（纯CPU模式）

3.3 处理常见编译错误

问题1：Could not find NDK
解决：检查WORKSPACE中的NDK路径，确保与本地安装一致

问题2：No matching toolchains
解决：清理缓存后重试

bash复制bazel clean --expunge

问题3：Out of memory error
解决：限制Bazel内存使用

bash复制export BAZEL_OPTS="--host_jvm_args=-Xmx4g"

4. 集成自定义AAR到Android项目

4.1 替换官方依赖

将生成的aar文件复制到Android项目的libs目录后，需要修改build.gradle：

groovy复制dependencies {
    // 替换这两行
    // implementation 'com.google.mediapipe:solution-core:latest.release'
    // implementation 'com.google.mediapipe:hands:latest.release'
    
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    implementation 'com.google.flogger:flogger:0.7.4'
    implementation 'com.google.guava:guava:30.1.1-android'
}

4.2 解决依赖冲突

最常见的问题是CameraX版本冲突。如果项目中使用的是新版本CameraX，需要同步修改：

groovy复制def camerax_version = "1.1.0-beta01"
implementation "androidx.camera:camera-core:$camerax_version"
implementation "androidx.camera:camera-camera2:$camerax_version"

同时需要提升项目的compileSdkVersion：

groovy复制android {
    compileSdkVersion 31
    defaultConfig {
        targetSdkVersion 31
    }
}

4.3 验证集成效果

创建简单的测试Activity验证手势识别是否正常工作：

kotlin复制class HandTrackingActivity : AppCompatActivity() {
    private lateinit var hands: Hands

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)

        hands = Hands(
            this,
            HandsOptions.builder()
                .setMaxNumHands(2)
                .setRunOnGpu(false)  // 使用我们编译的CPU模式
                .build()
        )

        hands.setResultListener { result ->
            result.multiHandLandmarks()?.forEach { landmarks ->
                // 处理识别结果
            }
        }
    }
}

5. 高级定制技巧

5.1 修改模型参数

要调整手势识别模型的精度或性能，可以修改：

code复制mediapipe/graphs/hand_tracking/subgraphs/
└── hand_landmark_gpu.pbtxt

关键参数示例：

protobuf复制node {
  calculator: "InferenceCalculator"
  input_stream: "TENSORS:input_tensors"
  output_stream: "TENSORS:output_tensors"
  options: {
    [mediapipe.InferenceCalculatorOptions.ext] {
      model_path: "hand_landmark.tflite"
      delegate {
        xnnpack {
          num_threads: 4  # 可调整推理线程数
        }
      }
    }
  }
}

5.2 裁剪无用功能

如果不需要3D手势坐标，可以在BUILD文件中移除相关依赖：

python复制mediapipe_aar(
    name = "hands",
    srcs = [
        "//mediapipe/java/com/google/mediapipe/solutions/hands:Hands.java",
        # 注释掉以下行
        # "//mediapipe/java/com/google/mediapipe/solutions/hands:Hands3d.java",  
    ],
    deps = [
        ":hands_proto_lite",
        "//mediapipe/java/com/google/mediapipe/framework:framework",
    ],
)

5.3 性能优化实测

在我的小米10（骁龙865）上测试不同配置的性能表现：

实现这些优化后，我们的手势识别模块在低端设备上的帧率从15fps提升到了稳定的30fps。这种程度的优化只有通过源码编译才能实现，这也是为什么我认为每个认真使用MediaPipe的开发者都应该掌握这套流程。