MediaPipe face_landmark 模块详解：468/478 关键点人脸网格子图结构与前后端管线实现

MediaPipe face_landmark 模块详解：468/478 关键点人脸网格子图结构与前后端管线实现

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe

本文以 MediaPipe 仓库中的 face_landmark 模块 为核心，系统讲解其对外暴露的四个人脸关键点子图（FaceLandmarkCpu/FaceLandmarkGpu/FaceLandmarkFrontCpu/FaceLandmarkFrontGpu）的输入输出约定、内部计算管线、with_attention机制与多脸跟踪原理。读完本文，你将掌握这些子图在 CPU/GPU 两种计算后端下的调用方式、468 与 478 关键点的差异来源，以及如何在自己的 MediaPipe 图（Graph）中组合使用它们完成单脸/多脸的人脸网格（Face Mesh）回归任务。

一、模块定位与子图总览

face_landmark模块位于 mediapipe/modules/face_landmark，它提供的不是某个独立的"人脸关键点"终端应用，而是一组可被上层图复用的 MediaPipe 子图（Subgraph）。这些子图通过mediapipe_simple_subgraph宏注册，见 BUILD，package(default_visibility = ["//visibility:public"])使它们可以被仓库内其他模块（如face_mesh、holistic_landmark、iris_tracking）直接以 Calculator 形式引用。

模块 README 的核心是一张子图清单，本模块对外提供四种组合：

从结构上可以把这四者分成两组理解：

• FaceLandmarkCpu / FaceLandmarkGpu（单脸回归子图）：只做"在已知 ROI 内回归关键点"这一件事，是纯回归（regression-only）子图，需要调用方先通过人脸检测给出ROI:roi。它们是整个模块的计算核心，内部完成图像裁剪、TFLite 推理、关键点解码与坐标回投；
• FaceLandmarkFrontCpu / FaceLandmarkFrontGpu（多脸检测+跟踪子图）：内部把FaceDetectionShortRange人脸检测子图、单脸回归子图以及一套"基于上一帧关键点回算 ROI"的反馈回路组合起来，形成可端到端输出多张人脸关键点的"前置型"（Front-facing）子图。其文件注释明确说明设计意图是"尽量通过上一帧已检测/回归出的关键点来跳过新一帧的人脸检测"（face_landmark_front_cpu.pbtxt第 1-3 行）。

除 README 表格列出的四者外，模块目录里还有若干内部辅助子图与变体，它们与四张主图共同构成完整实现：

• face_landmark_front_cpu_image.pbtxt、face_landmark_front_gpu_image.pbtxt：面向静态图片的单帧多脸处理变体；
• face_landmark_front_side_model_cpu.pbtxt、face_landmark_front_side_model_gpu.pbtxt：复用侧脸模型的变体；
• face_detection_front_detection_to_roi.pbtxt 与 face_landmark_landmarks_to_roi.pbtxt：两个"检测/关键点 → ROI"转换辅助子图，图中注释明确警告subject to change and should not be used directly（结构可能变更，不建议直接使用）；
• face_landmarks_model_loader.pbtxt：按with_attention标志选择并加载对应 TFLite 模型；
• tensors_to_face_landmarks.pbtxt 与 tensors_to_face_landmarks_with_attention.pbtxt：把推理输出的张量解码为 468 / 478 个归一化关键点。

二、FaceLandmarkCpu / FaceLandmarkGpu：单脸 ROI 回归子图的内部管线

2.1 输入输出契约

以 face_landmark_cpu.pbtxt 为例，其顶部声明的类型与接口即调用方需要遵守的契约：

• input_stream: "IMAGE:image"：CPU 图像（ImageFrame）；
• input_stream: "ROI:roi"：图像内人脸所在区域，类型为归一化矩形NormalizedRect；
• input_side_packet: "WITH_ATTENTION:with_attention"：布尔值，决定是否运行带注意力的人脸网格模型（详见第三节）；
• output_stream: "LANDMARKS:face_landmarks"：ROI 内的人脸关键点列表NormalizedLandmarkList。

文件头部给出了在宿主图中引用该子图的标准写法：

node { calculator: "FaceLandmarkCpu" input_stream: "IMAGE:image" input_stream: "ROI:face_roi" input_side_packet: "WITH_ATTENTION:with_attention" output_stream: "LANDMARKS:face_landmarks" }

FaceLandmarkGpu的接口与 CPU 版本一一对应，仅把图像输入从ImageFrame换成 GPU 缓冲GpuBuffer（IMAGE_GPU标签），其管线下游会生成使用 GPU delegate 的推理图。

2.2 一个关键约定：人脸缺失时"无输出包"

子图注释特别强调了一条容易被忽略的语义（face_landmark_cpu.pbtxt第 39-42 行）：

如果给定 ROI 内不存在人脸，那么在当前时间戳上LANDMARKS流不会有输出包。但 MediaPipe 框架会内部告知下游 Calculator 该包的缺失，使下游不必空等。

也就是说，该子图通过"缺包即信号"的方式表达"当前帧没有脸"，下游 Calculator 应当能正确处理时间戳上有边界（timestamp bound）但无包的输入。这一点在编写自己的下游渲染或逻辑节点时务必注意。

2.3 从输入图到 192×192 张量

子图的第一阶段是把整幅图像按 ROI 变换成模型输入张量，由ImageToTensorCalculator完成：

node: { calculator: "ImageToTensorCalculator" input_stream: "IMAGE:image" input_stream: "NORM_RECT:roi" output_stream: "TENSORS:input_tensors" options: { [mediapipe.ImageToTensorCalculatorOptions.ext] { output_tensor_width: 192 output_tensor_height: 192 output_tensor_float_range { min: 0.0 max: 1.0 } } } }

关键参数：模型输入固定为192×192，像素归一化到浮点区间[0.0, 1.0]（对应 TFLite 输入通常要求的归一化范围）。GPU 版本（face_landmark_gpu.pbtxt）在此节点上额外多出gpu_origin: TOP_LEFT，用来协调 GPU 纹理与 CPU 图像在原点/翻转语义上的差异，保证裁剪与关键点坐标一致。

tensors_to_face_landmarks*.pbtxt里的解码器选项同样写死input_image_width: 192、input_image_height: 192，说明 192 是模型约定的输入尺寸，两处必须保持一致。

2.4 模型加载与推理

模型加载封装在FaceLandmarksModelLoader子图中（face_landmarks_model_loader.pbtxt）。它接收WITH_ATTENTION布尔边包，通过SwitchContainer在两个ConstantSidePacketCalculator之间切换模型文件路径：

• with_attention为 false（或未提供）→ 加载mediapipe/modules/face_landmark/face_landmark.tflite；
• with_attention为 true → 加载mediapipe/modules/face_landmark/face_landmark_with_attention.tflite。

随后ResourceProviderCalculator把路径解析为资源，TfLiteModelCalculator把资源转换成tflite::FlatBufferModel。这一设计说明：两个模型文件是运行期资源，必须在执行环境中位于上述路径，主图文件注释也对这一前提做了明确声明。

推理由InferenceCalculator承担。CPU 版通过delegate { xnnpack {} }显式启用 XNNPACK 委托加速；GPU 版则以空配置占位，并保留注释"Do not remove. Used for generation of XNNPACK/NNAPI graphs."（不要删除，供 XNNPACK/NNAPI 图生成使用）——这意味着同一个 GPU 子图描述可以被工具链离线改写为不同后端的最终图。此外两版图都并联了TfLiteCustomOpResolverCalculator，为模型可能依赖的自定义算子生成 op resolver 边包。

2.5 张量拆分与"人脸是否存在"闸门

推理输出的张量被送入SwitchContainer，其内部按with_attention分支选用两套SplitTensorVectorCalculator的切分方案：

• 不带注意力：ranges { begin: 0 end: 1 }与ranges { begin: 1 end: 2 }——输出两个张量，前者是关键点张量，后者是"人脸标志（face flag）"张量；
• 带注意力：ranges { begin: 0 end: 6 }与ranges { begin: 6 end: 7 }——前 6 个是分区关键点张量（mesh、嘴唇、左右眼、左右虹膜），第 7 个仍为 face flag 张量。

face flag 张量随后进入两条校验链路：

1. TensorsToFloatsCalculator以activation: SIGMOID把其换算为[0,1]的人脸存在置信度face_presence_score；
2. ThresholdingCalculator以threshold: 0.5判定face_presence；
3. 若判定无人脸，GateCalculator（输入landmark_tensors与ALLOW:face_presence）直接丢弃关键点张量，产生 2.2 节所述"无输出包"行为。

2.6 张量解码与坐标回投

通过闸门的关键点张量再次由SwitchContainer按with_attention选择解码器：

• TensorsToFaceLandmarks：把 1 个张量解码为468个归一化关键点；
• TensorsToFaceLandmarksWithAttention：把 6 个分区张量精修后合并为478个归一化关键点。

两个解码子图内部均由TensorsToLandmarksCalculator承担"张量 →NormalizedLandmarkList"的转换，所有输出坐标按模型输入尺寸（192×192）归一化。

最后一步至关重要：解码出的关键点是相对于裁剪后的人脸图的归一化坐标，必须还原到原图上。LandmarkProjectionCalculator接收NORM_LANDMARKS:landmarks与NORM_RECT:roi，利用 ROI 的平移与旋转把关键点投影回整个输入图像坐标系，得到对外输出的face_landmarks。这也解释了为什么整套设计强依赖一个准确的 ROI：ROI 的质量直接决定裁剪内容与最终坐标精度。

三、WITH_ATTENTION 与 468 → 478 关键点的秘密

with_attention是本模块最具差异性的开关。README 与各子图注释均说明：注意力机制在嘴唇、眼睛区域以及虹膜上提供更高精度；开启后多出的10 个关键点正是左右眼的虹膜点。

关键点数量语义可总结为：

• with_attention = false（默认/未设置）：模型为face_landmark.tflite，输出 468 个关键点，其中不包含独立虹膜关键点；
• with_attention = true：模型切换为face_landmark_with_attention.tflite，输出478个关键点，即在 468 个网格点基础上追加 468–477 共 10 个虹膜关键点（左右各 5 个），同时嘴唇、眼睛区域的关键点被分区模型的输出精修替换。

tensors_to_face_landmarks_with_attention.pbtxt 完整展示了这条精修链路，其解码顺序为 6 个张量：

1. mesh_tensor——468 点基础网格；
2. lips_tensor——80 点嘴唇细化；
3. left_eye_tensor——71 点左眼（含眼睑与眼眶外圈 halo）；
4. right_eye_tensor——71 点右眼；
5. left_iris_tensor——5 点左虹膜；
6. right_iris_tensor——5 点右虹膜。

每个分区张量先由独立的TensorsToLandmarksCalculator解码（各节点按张量分别设置num_landmarks: 468 / 80 / 71 / 71 / 5 / 5），再汇入LandmarksRefinementCalculator。精修规则以indexes_mapping把分区关键点映射回 468 点网格的索引（例如嘴唇 80 点映射到网格中的 0、17、61、146 等对应索引），并附加 z 轴细化策略（copy、none、或对虹膜点用眼睑关键点均值assign_average推算 z 值）。虹膜 5 点按固定语义排列：

• 左虹膜：468 中心、469 右缘、470 上缘、471 左缘、472 下缘；
• 右虹膜：473 中心、474 右缘、475 上缘、476 左缘、477 下缘。

值得注意的是SwitchContainer与with_attention的联动遍布整张图：模型文件选择、输出张量切分方式、解码器选择三处都由同一个布尔边包驱动，实现了"同一子图接口、两种模型能力"的动态切换。

四、FaceLandmarkFrontCpu / FaceLandmarkFrontGpu：多脸"检测 + 跟踪"闭环

4.1 比单脸子图多了什么

如果说FaceLandmarkCpu/Gpu是"输入 ROI、输出关键点"，那么FaceLandmarkFrontCpu/Gpu的目标是"输入整幅图、直接输出多张脸的关键点"，因此其内部把单脸子图与检测、跟踪装配在一起，并引入反馈环路。两份前端图的接口几乎一致（face_landmark_front_cpu.pbtxt）：

• input_stream: "IMAGE:image"：整幅输入图像；
• input_side_packet: "NUM_FACES:num_faces"：最大检测/跟踪人脸数（int），通过ClipDetectionVectorSizeCalculator与NormalizedRectVectorHasMinSizeCalculator共同约束；
• input_side_packet: "USE_PREV_LANDMARKS:use_prev_landmarks"：是否用上一帧关键点辅助定位当前帧关键点（bool）；
• input_side_packet: "WITH_ATTENTION:with_attention"：同上文的注意力开关；
• output_stream: "LANDMARKS:multi_face_landmarks"：std::vector<NormalizedLandmarkList>，每张脸一组关键点。

除主输出外，前端图还暴露三路调试用输出：DETECTIONS（检测到的人脸，std::vector<Detection>）、ROIS_FROM_LANDMARKS（由关键点算出的 ROI）、ROIS_FROM_DETECTIONS（由检测框算出的 ROI）。这与上层渲染逻辑（如 face_mesh_desktop.pbtxt 中FaceRendererCpu同时消费LANDMARKS、ROIS_FROM_LANDMARKS、DETECTIONS）直接对应。

4.2 基于上一帧关键点的 ROI 回环

前端图设计的核心思路是尽可能跳过重复的人脸检测。闭环由PreviousLoopbackCalculator完成（见face_landmark_front_cpu.pbtxt第 233-247 行）：

node { calculator: "PreviousLoopbackCalculator" input_stream: "MAIN:image" input_stream: "LOOP:face_rects_from_landmarks" input_stream_info: { tag_index: "LOOP" back_edge: true } output_stream: "PREV_LOOP:prev_face_rects_from_landmarks" }

它的行为是：缓存本帧由关键点反推得到的 ROI，在下一帧图像到达时，把这些缓存的 ROI 以新图像的时间戳输出为prev_face_rects_from_landmarks。由于LOOP流被显式标记为back_edge: true（回边），MediaPipe 调度器会做正确的环形图处理；注释还指出第一帧到达时会触发一次时间戳边界更新以"启动"这条反馈回路。

后续处理围绕这条回边展开，形成"能跳过就跳过"的策略：

1. GateCalculator（ALLOW:use_prev_landmarks，allow: true）：当use_prev_landmarks未提供或为 true 时放行上一帧 ROI；
2. NormalizedRectVectorHasMinSizeCalculator：检查上一帧 ROI 数量是否已 ≥num_faces，产出prev_has_enough_faces；
3. 另一个GateCalculator（DISALLOW:prev_has_enough_faces，empty_packets_as_allow: true）：若上一帧已"认全"了足够多的人脸，则丢弃本帧图像（不触发检测）；否则放行图像进入人脸检测——注意empty_packets_as_allow保证在没有任何历史帧的冷启动阶段，图像可以正常进入检测。

4.3 检测 → ROI 循环

当需要真正检测时，图像被送入FaceDetectionShortRangeCpu/FaceDetectionShortRangeGpu（后者定义于 mediapipe/modules/face_detection 模块的短距离检测子图，对应资源为face_detection_short_range.tflite）。检测结果随后：

1. ClipDetectionVectorSizeCalculator按num_faces截断检测数量；
2. BeginLoopDetectionCalculator把"检测向量"展开为按假时间戳逐个处理的循环，同时Clone图像尺寸边包；
3. 循环体内FaceDetectionFrontDetectionToRoi把单个检测转换为 ROI；
4. EndLoopNormalizedRectCalculator汇总成 ROI 向量face_rects_from_detections。

其中FaceDetectionFrontDetectionToRoi（face_detection_front_detection_to_roi.pbtxt）内部使用DetectionsToRectsCalculator生成一个"人脸包围框且旋转到双眼连线水平"的归一化矩形：旋转向量取关键点 0（左眼）到关键点 1（右眼），目标角度为 0；随后RectTransformationCalculator以scale_x: 1.5、scale_y: 1.5、square_long: true对外扩并化为正方形，确保包含完整人脸。

4.4 历史 ROI 与检测 ROI 的融合去重

AssociationNormRectCalculator把当前帧检测 ROI 与上一帧关键点 ROI 关联融合，min_similarity_threshold: 0.5，其作用（注释所述）是保证输出的face_rects不包含重叠区域。换言之：上一帧已跟踪到的脸不重复检测、不产生重叠框，只有上一帧缺失（新入镜）的脸才由检测分支补充，这正是"检测 + 跟踪"混合架构的收敛点。

4.5 关键点回归循环与跨帧跟踪

融合后的face_rects由BeginLoopNormalizedRectCalculator展开，循环体内对每个 ROI：

• ImagePropertiesCalculator计算图像尺寸；
• 调用单脸子图FaceLandmarkCpu（GPU 版为FaceLandmarkGpu）回归face_landmarks；
• FaceLandmarkLandmarksToRoi由关键点反推更紧凑的 ROIface_rect_from_landmarks——该 ROI 会被送入反馈环（PreviousLoopbackCalculator），供下一帧复用。

FaceLandmarkLandmarksToRoi（face_landmark_landmarks_to_roi.pbtxt）内部先由LandmarksToDetectionCalculator生成紧密包络的检测，再由DetectionsToRectsCalculator旋转对齐，其旋转向量改用关键点33（左眼外侧）到 263（右眼外侧），随后同样经RectTransformationCalculator以scale_x/y: 1.5、square_long: true外扩——扩大后的矩形保证即使人脸有轻微运动，下一帧的人脸仍在 ROI 内。

循环结束后，EndLoopNormalizedLandmarkListVectorCalculator把每个 ROI 的关键点汇成multi_face_landmarks输出，同时EndLoopNormalizedRectCalculator汇出face_rects_from_landmarks供回环缓存。

至此，一条完整的多脸跟踪管线闭环形成：上一帧关键点 ROI →（够数则跳过检测）→ ROI 融合 → 单脸回归 → 新关键点 ROI → 缓存供下一帧。

五、资源依赖与运行前提

运行这套子图需要满足以下资源前提（主图文件注释中均有明确声明）：

• 单脸回归必选：mediapipe/modules/face_landmark/face_landmark.tflite（with_attention=false时）；
• 注意力增强可选：mediapipe/modules/face_landmark/face_landmark_with_attention.tflite（with_attention=true时）；
• 前端多脸图额外必选：mediapipe/modules/face_detection/face_detection_short_range.tflite（短距离人脸检测模型）。

两个模型文件路径由FaceLandmarksModelLoader中的ConstantSidePacketCalculator硬编码（见 face_landmarks_model_loader.pbtxt 第 27、37 行），因此部署时资源名必须与之一致。MediaPipe 的资源加载机制（ResourceProviderCalculator）会按项目构建的 resource 目录解析这些相对路径，若缺失会直接导致图运行失败。

六、在宿主图中组合使用的完整示例

仓库内现成的组合范例是 face_mesh_desktop.pbtxt（桌面端 CPU 人脸网格示例，同类移动端/其他示例 也基于本模块）。它展示了前端子图的典型装配方式：

input_side_packet: "input_video_path" input_side_packet: "output_video_path" max_queue_size: 1 # 通过限流保证图一次只处理一帧 # 通过常量边包注入 num_faces 与 with_attention node { calculator: "ConstantSidePacketCalculator" output_side_packet: "PACKET:0:num_faces" output_side_packet: "PACKET:1:with_attention" node_options: { [type.googleapis.com/mediapipe.ConstantSidePacketCalculatorOptions]: { packet { int_value: 1 } packet { bool_value: true } } } } # 组合 FaceLandmarkFrontCpu 进行人脸检测与关键点回归 node { calculator: "FaceLandmarkFrontCpu" input_stream: "IMAGE:input_video" input_side_packet: "NUM_FACES:num_faces" input_side_packet: "WITH_ATTENTION:with_attention" output_stream: "LANDMARKS:multi_face_landmarks" output_stream: "ROIS_FROM_LANDMARKS:face_rects_from_landmarks" output_stream: "DETECTIONS:face_detections" output_stream: "ROIS_FROM_DETECTIONS:face_rects_from_detections" } # 渲染关键点标注 node { calculator: "FaceRendererCpu" input_stream: "IMAGE:input_video" input_stream: "LANDMARKS:multi_face_landmarks" input_stream: "NORM_RECTS:face_rects_from_landmarks" input_stream: "DETECTIONS:face_detections" output_stream: "IMAGE:output_video" }

该示例同时把num_faces=1、with_attention=true通过ConstantSidePacketCalculator注入，验证了"边包驱动"的调用风格。读者可以据此把FaceLandmarkFrontCpu/Gpu换成对应后端，或改用FaceLandmarkCpu/Gpu自行提供检测 ROI；仓库中 mediapipe/graphs/iris_tracking/iris_tracking_cpu.pbtxt、mediapipe/graphs/holistic_tracking 等图还对FaceLandmarkFrontCpu做了复用以提取眼部/面部区域，可继续参考。

七、小结：读懂 face_landmark 的一张图

把本模块的全部 pbtxt 串联起来，可以得到如下心智模型：

• 四个公开子图 = 两套能力 × 两个后端：单脸 ROI 回归（Cpu/Gpu）是计算核心；前端多脸（FrontCpu/FrontGpu）是在其之上叠加了"短距人脸检测 + 跨帧 ROI 反馈 + ROI 关联去重"的完整解决方案；
• 同一个with_attention贯穿三层：模型文件选择 → 输出张量切分 → 关键点解码，三处联动决定了最终输出 468 还是 478 个点；
• 所有关键点坐标都归一化且会回投到输入图：解码时按 192×192 模型输入归一化，输出前经LandmarkProjectionCalculator用 ROI 逆变换还原；
• "无脸即缺包"是显式协议：子图通过帧级空输出表达检测失败，下游必须正确处理时间戳边界。

对于需要在自有 MediaPipe 图中接入人脸网格能力的开发者，最直接的做法就是复用本模块的四个已注册子图并遵循上述边包与流契约；如需深度定制（例如替换模型、调整 ROI 外扩系数、改变关键点数量），则可从 face_landmark_cpu.pbtxt 这份最小管线出发进行修改。

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe