MediaPipe Box Tracking 深度解析基于经典运动分析的目标框跟踪架构与检测跟踪流水线实战【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipeMediaPipe Box Tracking 是一套完全基于经典计算机视觉运动分析而非每帧神经网络推理实现的多目标区域跟踪解决方案。它由运动分析Motion Analysis、流打包Flow Packager、框跟踪Box Tracker三个可复用的 MediaPipe 计算器组成并以一个统一的子图subgraph形式对外提供输入视频 起始框位置、输出每帧框位置的接口。本文将以 box_tracking.md 为骨架结合本仓库中真实存在的子图定义与计算器源码完整解析其组件原理、图配置、启动框语义以及如何将其与 ML 目标检测组合为移动端可实时运行的对象检测与跟踪流水线读完你既能读懂tracking目录下所有.pbtxt的结构也能直接编译运行 CPU/GPU 示例目标。重要说明文档明确标注MediaPipe Box Tracking 属于MediaPipe Legacy Solution官方已于2023 年 3 月 1 日停止对其支持详见文档顶部的 Attention 声明与 MediaPipe Solutions 指南 中关于 legacy 的说明。下文内容用于理解该经典方案的架构思路与源码实现若用于新项目请评估官方当前推荐的 MediaPipe Tasks 方案。一、方案总览解决什么问题输入输出是什么从功能上看Box Tracking 解决的是给出一组带时间戳的 2D 矩形起始框感兴趣区域在后续每一帧视频中持续跟踪它们的位置。它的输入有两路来自视频或摄像头流的图像帧序列带有时间戳的起始框集合每个框对应一个需要跟踪的 2D 区域。输出则是每个时间点上这些框的最新跟踪位置。起始框的来源不固定——在经典用法中来自目标检测器但同样可以由用户手动标注或由其他上游系统提供。正是这种起始框来源解耦的设计让 Box Tracking 成为可复用的基础跟踪模块。在真实产品历史上该方案长期支撑着 Motion Stills 的实时特效跟踪、YouTube 的移动物体隐私模糊privacy blur以及 Google Lens 等功能的实时跟踪能力文档 Overview 中明确提到这几个使用方此处作为背景事实引用。它不依赖深度模型而是利用高梯度角点、光流与相机运动估计等传统视觉手段完成跟踪这也是它能长时间稳定运行于移动端的原因。二、三大核心组件一条完整的数据流水线文档明确指出整套解决方案由三个主要组件构成每个组件都被封装为一个 MediaPipe 计算器而 Box Tracking 方案整体被表示为一个 MediaPipe 子图。在 GPU 版子图 box_tracking_gpu.pbtxt 中一条完整的数据流如下CPU 版 box_tracking_cpu.pbtxt 结构一致仅输入输出图像载体与降采样尺寸不同input_stream: VIDEO:input_video input_stream: BOXES:start_pos input_stream: CANCEL_ID:cancel_object_id output_stream: BOXES:boxesVIDEO待跟踪的视频帧流BOXES起始框输入TimedBoxProtoList每个框携带时间戳与唯一 idCANCEL_ID请求移除某个正在跟踪的框的 idBOXES输出逐帧跟踪后的框位置列表。图内部还先做了一步降采样GPU 版用ImageTransformationCalculator把输入缩放到 240×320竖屏尺寸CPU 版缩放到 320×240横屏尺寸显著降低后续运动分析的算力开销GPU 版随后通过GpuBufferToImageFrameCalculator把 GPU 缓冲转成 CPU 上的ImageFrame因为跟踪运动分析本身跑在 CPU上。三大组件依次如下1. MotionAnalysisCalculator运动分析MotionAnalysisCalculator负责在整幅图像上提取特征点例如高梯度角点随时间跟踪这些特征点将特征点分类为前景/背景特征同时估计局部运动矢量与全局运动模型相机运动。这一点在 motion_analysis_calculator.cc 的源码注释中也能印证它接收VIDEO流ImageFramesRGB/sRGBA/GRAY8输出FLOW稀疏特征轨迹RegionFlowFeatureListproto与CAMERACameraMotionproto。GPU 子图中对该计算器的配置box_tracking_gpu.pbtxt#L29-L60如下这些参数直接决定了跟踪的鲁棒性与计算量node: { calculator: MotionAnalysisCalculator input_stream: VIDEO:downscaled_input_video_cpu output_stream: CAMERA:camera_motion output_stream: FLOW:region_flow node_options: { [type.googleapis.com/mediapipe.MotionAnalysisCalculatorOptions]: { analysis_options { analysis_policy: ANALYSIS_POLICY_CAMERA_MOBILE # 面向手持移动相机的分析策略 flow_options { fast_estimation_min_block_size: 100 top_inlier_sets: 1 frac_inlier_error_threshold: 3e-3 downsample_mode: DOWNSAMPLE_TO_INPUT_SIZE verification_distance: 5.0 verify_long_feature_acceleration: true verify_long_feature_trigger_ratio: 0.1 tracking_options { max_features: 500 # 最多跟踪的特征点数 adaptive_extraction_levels: 2 # 自适应特征提取的层级数 min_eig_val_settings { adaptive_lowest_quality_level: 2e-4 } klt_tracker_implementation: KLT_OPENCV # KLT 跟踪实现 } } } } } }从配置可以看出运动分析在整幅图上做特征跟踪max_features: 500并采用ANALYSIS_POLICY_CAMERA_MOBILE策略来适配手机拍摄的抖动/平移场景通过verify_long_feature_acceleration等校验抑制错误特征。2. FlowPackagerCalculator打包运动元数据FlowPackagerCalculator把运动分析产出的稀疏光流与相机运动打包成紧凑、高效的TrackingData格式供后续框跟踪使用。GPU 子图内该节点的注释box_tracking_gpu.pbtxt#L62-L79解释了其内部表示读取optical_flow_field.h定义的光流场输出一个双通道v_x、v_yVideoFrame每个通道量化到 0–255以此实现紧凑存储。其源码 flow_packager_calculator.cc 表明它接收FLOWRegionFlowFeatureList与可选的CAMERA输出每帧TRACKINGTrackingDataproto若提供CACHE_DIR输入边包还可把跟踪块TrackingDataChunk写入磁盘缓存为批处理 / 随机访问模式提供数据源。node: { calculator: FlowPackagerCalculator input_stream: FLOW:region_flow input_stream: CAMERA:camera_motion output_stream: TRACKING:tracking_data node_options: { [type.googleapis.com/mediapipe.FlowPackagerCalculatorOptions]: { flow_packager_options: { binary_tracking_data_support: false } } } }3. BoxTrackerCalculator框跟踪BoxTrackerCalculator接收 FlowPackager 的运动元数据与起始框位置**仅凭运动数据不需要 RGB 原图**对每个框进行持续跟踪并能同时跟踪多个对象/区域、将它们彼此区分。GPU 子图中该节点还配套了关键的同步与反馈语义box_tracking_gpu.pbtxt#L81-L125node: { calculator: BoxTrackerCalculator input_stream: TRACKING:tracking_data input_stream: TRACK_TIME:input_video input_stream: START_POS:start_pos input_stream: CANCEL_OBJECT_ID:cancel_object_id input_stream_info: { tag_index: CANCEL_OBJECT_ID back_edge: true # 反馈边取消 id 的输出会回流到本节点 } output_stream: BOXES:boxes input_stream_handler { input_stream_handler: SyncSetInputStreamHandler options { [mediapipe.SyncSetInputStreamHandlerOptions.ext] { sync_set { tag_index: TRACKING tag_index: TRACK_TIME } sync_set { tag_index: START_POS } sync_set { tag_index: CANCEL_OBJECT_ID } } } } node_options: { [type.googleapis.com/mediapipe.BoxTrackerCalculatorOptions]: { tracker_options: { track_step_options { track_object_and_camera: true # 同时考虑对象运动与相机运动 tracking_degrees: TRACKING_DEGREE_OBJECT_SCALE # 跟踪自由度对象尺度 inlier_spring_force: 0.0 static_motion_temporal_ratio: 3e-2 } } visualize_tracking_data: false streaming_track_data_cache_size: 100 # 缓存 100 帧跟踪数据用于快速前推 } } }值得注意的工程细节有两点back_edge: true反馈边CANCEL_OBJECT_ID让跟踪器可以从下游例如对象管理模块收到删除某框的信号形成闭环SyncSetInputStreamHandler将TRACKING/TRACK_TIME分为一组同步、START_POS与CANCEL_OBJECT_ID各自成组——这保证了运动数据与新的起始框请求可以以不同频率异步到达而不错配。BoxTrackerCalculator 的两种工作模式阅读 box_tracker_calculator.cc 的头部注释可以获得更完整的接口语义该计算器支持两种模式流式模式Streaming仅使用逐帧TRACKING数据向前跟踪。可额外提供TRACK_TIME请求输出时间戳以便在高于TRACKING帧率的频率上查询跟踪结果批处理模式Batch通过CACHE_DIR边包从跟踪块文件读取数据支持多关键帧的前向与后向跟踪批处理模式下需自行管理缓存目录的清理避免陈旧块文件被复用。BoxTrackerCalculator的输入流非常丰富全部可选、按需启用输入流语义TRACKING运动分析产生的逐帧TrackingDataTRACK_TIME请求跟踪结果的输出时间戳START_POSTimedBoxProtoList起始框框的时间戳不必单调新起始框会被快进到当前跟踪头部START_POS_PROTO_STRINGSTART_POS的序列化 proto 字符串形式两者并存时优先START_POSRESTART_POS专用于接收重捕获reacquisition检测结果的起始框CANCEL_OBJECT_ID需要移除的框 idRA_TRACK随机访问跟踪请求输入为 [start0, stop0, start1, stop1, …] 的成对TimedBoxProtoList数量必须为偶数位置与 id 用于起点、时间用于终点可在任意时间顺序上执行RA_TRACK_PROTO_STRINGRA_TRACK的序列化 proto 字符串形式输出流包括VIZ叠加框的可视化视频需提供VIDEO、BOXES常规跟踪结果、RA_BOXES随机访问请求的结果与请求同时间戳。与之对应的配置项见 box_tracker_calculator.protoinitial_position通过选项直接给定起始框visualize_tracking_data/visualize_state/visualize_internal_state三档可视化开关默认均为 false用于把跟踪数据、框状态或内部状态渲染到VIZ流streaming_track_data_cache_size流式模式下的跟踪数据缓存大小以帧为单位默认 0。缓存允许把任意时刻到达的START_POS起始框快进到当前跟踪头部。GPU 子图将其设为 100start_pos_transition_frames当收到新的 reset 起始位置时加入 N 帧过渡以平滑原始跟踪到新位置的跳变线性衰减0 表示无过渡。框跟踪的核心状态机MotionBox/PathSegment见同文件MotionBoxPath结构会在流式模式下按缓存大小裁剪前向/后向的状态与路径队列从而在长时间流上维持有界的内存占用。三、架构优势恒定开销、跨帧缓存与随机访问文档特别强调了这套分离式架构的三个关键收益与跟踪数量无关的恒定计算量运动分析被独立为一个计算器、在整幅图上跟踪特征因此无论同时跟踪 1 个还是多个区域运动分析的计算开销保持不变新增跟踪区域几乎不增加成本跟踪阶段不依赖 RGB 原图BoxTracker 只消费运动元数据这使我们可以把打包后的元数据按批量跨帧缓存缓存带来时间维度的自由支持向前和向后双向跟踪甚至可以直接同步到指定时间戳做随机访问跟踪——这正是上一节RA_TRACK输入流在源码层的落地。这套分析与跟踪解耦 运动数据可缓存的思想是 Box Tracking 能长期部署在 Motion Stills、YouTube 隐私模糊等真实产品中的根本原因历史使用场景以文档说明为准。四、与 ML 组合对象检测 跟踪流水线纯跟踪只能维持已有框无法发现新对象。MediaPipe 给出的经典做法是把 Box Tracking 与ML 目标检测配对构成检测驱动 跟踪维持的流水线。相比每帧都跑检测例如纯 object_detection.md 方案文档列出了三个显著优势实例级跟踪跨帧保持对象 ID 一致而非每帧各自独立的检测结果检测不必逐帧执行可以在较低频率上运行更重但更准的检测模型同时让整体流水线在移动端保持轻量、实时时间一致性更好借助跟踪对象定位在时间上连续帧间抖动jitter明显减少。顶层图的真实结构仓库中完整的移动端示例图是 object_detection_tracking_mobile_gpu.pbtxt其结构为# 1) 抽帧降频把输入视频从原帧率抽稀到 0.5 fps作为检测的输入 node { calculator: PacketResamplerCalculator input_stream: DATA:input_video output_stream: DATA:throttled_input_video node_options: { [type.googleapis.com/mediapipe.PacketResamplerCalculatorOptions] { frame_rate: 0.5 } } } # 2) 检测子图内部执行 TFLite GPU 推理 node { calculator: ObjectDetectionSubgraphGpu input_stream: IMAGE:throttled_input_video output_stream: DETECTIONS:output_detections } # 3) 对象跟踪子图每帧实时运行 node { calculator: ObjectTrackingSubgraphGpu input_stream: VIDEO:input_video input_stream: DETECTIONS:output_detections output_stream: DETECTIONS:tracked_detections } # 4) 渲染子图 node { calculator: RendererSubgraphGpu input_stream: IMAGE:input_video input_stream: DETECTIONS:tracked_detections output_stream: IMAGE:output_video }该顶层图在内部引用四个子图检测子图 object_detection_gpu.pbtxt、对象跟踪子图 object_tracking_gpu.pbtxt、框跟踪子图 box_tracking_gpu.pbtxt 以及渲染子图 renderer_gpu.pbtxt。注意上图中PacketResamplerCalculator把进入检测的帧抽稀到 0.5 fps——文档明确指出该帧率只是此图的配置示例可通过PacketResamplerCalculatorOptions.frame_rate自由调整桌面端示例 object_detection_tracking_desktop_live.pbtxt 就使用了frame_rate: 3。这样一来检测子图仅在请求时运行例如按任意低帧率或被特定信号触发承担发现新对象/重新定位的职责对象跟踪子图在每个输入帧上实时运行负责把已检测对象稳定跟住。在移动端 GPU 示例中检测使用 TensorFlow Lite 跑在 GPU 上而跟踪部分跑在 CPUbox tracking 子图内部的降采样与运动分析均为 CPU 操作详见子图内GpuBufferToImageFrameCalculator。对象跟踪子图内部从检测到跟踪再到管理对象跟踪子图 object_tracking_gpu.pbtxt 在 box tracking 之上扩展了四步逻辑DetectionUniqueIdCalculator为每个新检测结果分配全局唯一 id这是实例级跟踪、ID 跨帧稳定的前提DetectionsToTimedBoxListCalculator把Detectionproto 转成跟踪用的TimedBoxProtoList。其源码 detections_to_timed_box_list_calculator.cc 注释明确仅支持RELATIVE_BOUNDING_BOX类型的 LocationData 格式BoxTrackingSubgraphGpu即前面分析的框跟踪子图用最新检测框初始化/维持框跟踪TrackedDetectionManagerCalculator管理新检测对象与在跟踪对象。文档指出当新的检测结果到来时它使用IoUIntersection over Union把当前在跟踪的框与新的检测框做关联从而剔除已过时或重复的框并输出CANCEL_OBJECT_ID反馈给 box tracking 子图让其停止对应跟踪。该节点的实际实现位于 tracked_detection_manager.cc。因此整个检测跟踪闭环可概括为低频检测发现对象 → 转为带 id 的起始框 → 高频运动跟踪维持框 → IoU 关联去重并管理对象生命周期。五、编译运行示例开始之前建议先阅读各平台构建指引Android、iOS、桌面端 C。要可视化这些.pbtxt图可以把图内容复制粘贴到 MediaPipe Visualizer或参考本仓库的 visualizer 文档查看节点与子图结构。移动端Android注意该示例中目标检测使用 TensorFlow Lite 跑在 GPU跟踪在 CPU 上。顶层图object_detection_tracking_mobile_gpu.pbtxtAndroid Bazel 目标mediapipe/examples/android/src/java/com/google/mediapipe/apps/objecttrackinggpu:objecttrackinggpu示例源码位于 objecttrackinggpu文档还提供了预编译 ARM64 APK 的下载入口此处不转载外部链接。iOS 目标不可用。桌面端Linux/macOSCPU桌面示例只提供 CPU 版本GPU 版不可用构建与运行命令记录在 examples/desktop/object_tracking/BUILD 头部# 构建禁用 GPU bazel build -c opt --define MEDIAPIPE_DISABLE_GPU1 \ //mediapipe/examples/desktop/object_tracking:object_tracking_cpu # 运行喂入视频输出带跟踪框的视频 bazel-bin/mediapipe/examples/desktop/object_tracking/object_tracking_cpu \ --calculator_graph_config_file.../object_detection_tracking_desktop_live.pbtxt \ --input_video_pathinput video path \ --output_video_pathoutput video path该目标依赖的顶层图为 object_detection_tracking_desktop_live.pbtxtCPU 变体内部使用ObjectDetectionSubgraphCpu/ObjectTrackingSubgraphCpu/RendererSubgraphCpuPacketResampler抽帧到 3 fps并且从 BUILD 的data可以看到它运行时加载ssdlite_object_detection.tflite与对应的 labelmap位于 mediapipe/modelslabelmap 文件为 ssdlite_object_detection_labelmap.txt。六、仓库中的可延伸阅读入口如果你想从用起来深入到改起来推荐按下列路径继续阅读本仓库子图全部文件集中在 mediapipe/graphs/tracking/subgraphsbox_tracking_*.pbtxt、object_tracking_*.pbtxt、object_detection_*.pbtxt、renderer_*.pbtxt顶层示例图在 mediapipe/graphs/tracking移动端 GPU 与桌面端 live 两个版本可直接对照框跟踪的底层状态机实现在 box_tracker.cc含同名头文件与 proto box_tracker.proto并有 box_tracker_test.cc 提供行为测试参考运动分析与打包的底层算法分别位于 motion_analysis.cc 与 flow_packager.cc框架层概念计算器、图、时间戳、子图可查阅 calculators.md、graphs.md 等文档。七、小结MediaPipe Box Tracking 是理解如何把经典视觉算法工程化为可组合的图模块的绝佳案例它用三个职责单一的计算器整图运动分析、运动元数据打包、纯运动驱动的框跟踪实现了计算量与跟踪对象数解耦、跟踪阶段不依赖 RGB 帧、支持跨帧缓存与随机访问等特性并在上层通过与低频 ML 检测子图、IoU 对象管理子图的组合形成一套移动端可实时运行的检测跟踪流水线。仓库中从box_tracking_gpu.pbtxt到object_detection_tracking_mobile_gpu.pbtxt再到 Android/桌面示例目标的完整链路可作为复刻与改造该方案的第一手参考。【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MediaPipe Box Tracking 深度解析：基于经典运动分析的目标框跟踪架构与“检测+跟踪“流水线实战
MediaPipe Box Tracking 深度解析基于经典运动分析的目标框跟踪架构与检测跟踪流水线实战【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipeMediaPipe Box Tracking 是一套完全基于经典计算机视觉运动分析而非每帧神经网络推理实现的多目标区域跟踪解决方案。它由运动分析Motion Analysis、流打包Flow Packager、框跟踪Box Tracker三个可复用的 MediaPipe 计算器组成并以一个统一的子图subgraph形式对外提供输入视频 起始框位置、输出每帧框位置的接口。本文将以 box_tracking.md 为骨架结合本仓库中真实存在的子图定义与计算器源码完整解析其组件原理、图配置、启动框语义以及如何将其与 ML 目标检测组合为移动端可实时运行的对象检测与跟踪流水线读完你既能读懂tracking目录下所有.pbtxt的结构也能直接编译运行 CPU/GPU 示例目标。重要说明文档明确标注MediaPipe Box Tracking 属于MediaPipe Legacy Solution官方已于2023 年 3 月 1 日停止对其支持详见文档顶部的 Attention 声明与 MediaPipe Solutions 指南 中关于 legacy 的说明。下文内容用于理解该经典方案的架构思路与源码实现若用于新项目请评估官方当前推荐的 MediaPipe Tasks 方案。一、方案总览解决什么问题输入输出是什么从功能上看Box Tracking 解决的是给出一组带时间戳的 2D 矩形起始框感兴趣区域在后续每一帧视频中持续跟踪它们的位置。它的输入有两路来自视频或摄像头流的图像帧序列带有时间戳的起始框集合每个框对应一个需要跟踪的 2D 区域。输出则是每个时间点上这些框的最新跟踪位置。起始框的来源不固定——在经典用法中来自目标检测器但同样可以由用户手动标注或由其他上游系统提供。正是这种起始框来源解耦的设计让 Box Tracking 成为可复用的基础跟踪模块。在真实产品历史上该方案长期支撑着 Motion Stills 的实时特效跟踪、YouTube 的移动物体隐私模糊privacy blur以及 Google Lens 等功能的实时跟踪能力文档 Overview 中明确提到这几个使用方此处作为背景事实引用。它不依赖深度模型而是利用高梯度角点、光流与相机运动估计等传统视觉手段完成跟踪这也是它能长时间稳定运行于移动端的原因。二、三大核心组件一条完整的数据流水线文档明确指出整套解决方案由三个主要组件构成每个组件都被封装为一个 MediaPipe 计算器而 Box Tracking 方案整体被表示为一个 MediaPipe 子图。在 GPU 版子图 box_tracking_gpu.pbtxt 中一条完整的数据流如下CPU 版 box_tracking_cpu.pbtxt 结构一致仅输入输出图像载体与降采样尺寸不同input_stream: VIDEO:input_video input_stream: BOXES:start_pos input_stream: CANCEL_ID:cancel_object_id output_stream: BOXES:boxesVIDEO待跟踪的视频帧流BOXES起始框输入TimedBoxProtoList每个框携带时间戳与唯一 idCANCEL_ID请求移除某个正在跟踪的框的 idBOXES输出逐帧跟踪后的框位置列表。图内部还先做了一步降采样GPU 版用ImageTransformationCalculator把输入缩放到 240×320竖屏尺寸CPU 版缩放到 320×240横屏尺寸显著降低后续运动分析的算力开销GPU 版随后通过GpuBufferToImageFrameCalculator把 GPU 缓冲转成 CPU 上的ImageFrame因为跟踪运动分析本身跑在 CPU上。三大组件依次如下1. MotionAnalysisCalculator运动分析MotionAnalysisCalculator负责在整幅图像上提取特征点例如高梯度角点随时间跟踪这些特征点将特征点分类为前景/背景特征同时估计局部运动矢量与全局运动模型相机运动。这一点在 motion_analysis_calculator.cc 的源码注释中也能印证它接收VIDEO流ImageFramesRGB/sRGBA/GRAY8输出FLOW稀疏特征轨迹RegionFlowFeatureListproto与CAMERACameraMotionproto。GPU 子图中对该计算器的配置box_tracking_gpu.pbtxt#L29-L60如下这些参数直接决定了跟踪的鲁棒性与计算量node: { calculator: MotionAnalysisCalculator input_stream: VIDEO:downscaled_input_video_cpu output_stream: CAMERA:camera_motion output_stream: FLOW:region_flow node_options: { [type.googleapis.com/mediapipe.MotionAnalysisCalculatorOptions]: { analysis_options { analysis_policy: ANALYSIS_POLICY_CAMERA_MOBILE # 面向手持移动相机的分析策略 flow_options { fast_estimation_min_block_size: 100 top_inlier_sets: 1 frac_inlier_error_threshold: 3e-3 downsample_mode: DOWNSAMPLE_TO_INPUT_SIZE verification_distance: 5.0 verify_long_feature_acceleration: true verify_long_feature_trigger_ratio: 0.1 tracking_options { max_features: 500 # 最多跟踪的特征点数 adaptive_extraction_levels: 2 # 自适应特征提取的层级数 min_eig_val_settings { adaptive_lowest_quality_level: 2e-4 } klt_tracker_implementation: KLT_OPENCV # KLT 跟踪实现 } } } } } }从配置可以看出运动分析在整幅图上做特征跟踪max_features: 500并采用ANALYSIS_POLICY_CAMERA_MOBILE策略来适配手机拍摄的抖动/平移场景通过verify_long_feature_acceleration等校验抑制错误特征。2. FlowPackagerCalculator打包运动元数据FlowPackagerCalculator把运动分析产出的稀疏光流与相机运动打包成紧凑、高效的TrackingData格式供后续框跟踪使用。GPU 子图内该节点的注释box_tracking_gpu.pbtxt#L62-L79解释了其内部表示读取optical_flow_field.h定义的光流场输出一个双通道v_x、v_yVideoFrame每个通道量化到 0–255以此实现紧凑存储。其源码 flow_packager_calculator.cc 表明它接收FLOWRegionFlowFeatureList与可选的CAMERA输出每帧TRACKINGTrackingDataproto若提供CACHE_DIR输入边包还可把跟踪块TrackingDataChunk写入磁盘缓存为批处理 / 随机访问模式提供数据源。node: { calculator: FlowPackagerCalculator input_stream: FLOW:region_flow input_stream: CAMERA:camera_motion output_stream: TRACKING:tracking_data node_options: { [type.googleapis.com/mediapipe.FlowPackagerCalculatorOptions]: { flow_packager_options: { binary_tracking_data_support: false } } } }3. BoxTrackerCalculator框跟踪BoxTrackerCalculator接收 FlowPackager 的运动元数据与起始框位置**仅凭运动数据不需要 RGB 原图**对每个框进行持续跟踪并能同时跟踪多个对象/区域、将它们彼此区分。GPU 子图中该节点还配套了关键的同步与反馈语义box_tracking_gpu.pbtxt#L81-L125node: { calculator: BoxTrackerCalculator input_stream: TRACKING:tracking_data input_stream: TRACK_TIME:input_video input_stream: START_POS:start_pos input_stream: CANCEL_OBJECT_ID:cancel_object_id input_stream_info: { tag_index: CANCEL_OBJECT_ID back_edge: true # 反馈边取消 id 的输出会回流到本节点 } output_stream: BOXES:boxes input_stream_handler { input_stream_handler: SyncSetInputStreamHandler options { [mediapipe.SyncSetInputStreamHandlerOptions.ext] { sync_set { tag_index: TRACKING tag_index: TRACK_TIME } sync_set { tag_index: START_POS } sync_set { tag_index: CANCEL_OBJECT_ID } } } } node_options: { [type.googleapis.com/mediapipe.BoxTrackerCalculatorOptions]: { tracker_options: { track_step_options { track_object_and_camera: true # 同时考虑对象运动与相机运动 tracking_degrees: TRACKING_DEGREE_OBJECT_SCALE # 跟踪自由度对象尺度 inlier_spring_force: 0.0 static_motion_temporal_ratio: 3e-2 } } visualize_tracking_data: false streaming_track_data_cache_size: 100 # 缓存 100 帧跟踪数据用于快速前推 } } }值得注意的工程细节有两点back_edge: true反馈边CANCEL_OBJECT_ID让跟踪器可以从下游例如对象管理模块收到删除某框的信号形成闭环SyncSetInputStreamHandler将TRACKING/TRACK_TIME分为一组同步、START_POS与CANCEL_OBJECT_ID各自成组——这保证了运动数据与新的起始框请求可以以不同频率异步到达而不错配。BoxTrackerCalculator 的两种工作模式阅读 box_tracker_calculator.cc 的头部注释可以获得更完整的接口语义该计算器支持两种模式流式模式Streaming仅使用逐帧TRACKING数据向前跟踪。可额外提供TRACK_TIME请求输出时间戳以便在高于TRACKING帧率的频率上查询跟踪结果批处理模式Batch通过CACHE_DIR边包从跟踪块文件读取数据支持多关键帧的前向与后向跟踪批处理模式下需自行管理缓存目录的清理避免陈旧块文件被复用。BoxTrackerCalculator的输入流非常丰富全部可选、按需启用输入流语义TRACKING运动分析产生的逐帧TrackingDataTRACK_TIME请求跟踪结果的输出时间戳START_POSTimedBoxProtoList起始框框的时间戳不必单调新起始框会被快进到当前跟踪头部START_POS_PROTO_STRINGSTART_POS的序列化 proto 字符串形式两者并存时优先START_POSRESTART_POS专用于接收重捕获reacquisition检测结果的起始框CANCEL_OBJECT_ID需要移除的框 idRA_TRACK随机访问跟踪请求输入为 [start0, stop0, start1, stop1, …] 的成对TimedBoxProtoList数量必须为偶数位置与 id 用于起点、时间用于终点可在任意时间顺序上执行RA_TRACK_PROTO_STRINGRA_TRACK的序列化 proto 字符串形式输出流包括VIZ叠加框的可视化视频需提供VIDEO、BOXES常规跟踪结果、RA_BOXES随机访问请求的结果与请求同时间戳。与之对应的配置项见 box_tracker_calculator.protoinitial_position通过选项直接给定起始框visualize_tracking_data/visualize_state/visualize_internal_state三档可视化开关默认均为 false用于把跟踪数据、框状态或内部状态渲染到VIZ流streaming_track_data_cache_size流式模式下的跟踪数据缓存大小以帧为单位默认 0。缓存允许把任意时刻到达的START_POS起始框快进到当前跟踪头部。GPU 子图将其设为 100start_pos_transition_frames当收到新的 reset 起始位置时加入 N 帧过渡以平滑原始跟踪到新位置的跳变线性衰减0 表示无过渡。框跟踪的核心状态机MotionBox/PathSegment见同文件MotionBoxPath结构会在流式模式下按缓存大小裁剪前向/后向的状态与路径队列从而在长时间流上维持有界的内存占用。三、架构优势恒定开销、跨帧缓存与随机访问文档特别强调了这套分离式架构的三个关键收益与跟踪数量无关的恒定计算量运动分析被独立为一个计算器、在整幅图上跟踪特征因此无论同时跟踪 1 个还是多个区域运动分析的计算开销保持不变新增跟踪区域几乎不增加成本跟踪阶段不依赖 RGB 原图BoxTracker 只消费运动元数据这使我们可以把打包后的元数据按批量跨帧缓存缓存带来时间维度的自由支持向前和向后双向跟踪甚至可以直接同步到指定时间戳做随机访问跟踪——这正是上一节RA_TRACK输入流在源码层的落地。这套分析与跟踪解耦 运动数据可缓存的思想是 Box Tracking 能长期部署在 Motion Stills、YouTube 隐私模糊等真实产品中的根本原因历史使用场景以文档说明为准。四、与 ML 组合对象检测 跟踪流水线纯跟踪只能维持已有框无法发现新对象。MediaPipe 给出的经典做法是把 Box Tracking 与ML 目标检测配对构成检测驱动 跟踪维持的流水线。相比每帧都跑检测例如纯 object_detection.md 方案文档列出了三个显著优势实例级跟踪跨帧保持对象 ID 一致而非每帧各自独立的检测结果检测不必逐帧执行可以在较低频率上运行更重但更准的检测模型同时让整体流水线在移动端保持轻量、实时时间一致性更好借助跟踪对象定位在时间上连续帧间抖动jitter明显减少。顶层图的真实结构仓库中完整的移动端示例图是 object_detection_tracking_mobile_gpu.pbtxt其结构为# 1) 抽帧降频把输入视频从原帧率抽稀到 0.5 fps作为检测的输入 node { calculator: PacketResamplerCalculator input_stream: DATA:input_video output_stream: DATA:throttled_input_video node_options: { [type.googleapis.com/mediapipe.PacketResamplerCalculatorOptions] { frame_rate: 0.5 } } } # 2) 检测子图内部执行 TFLite GPU 推理 node { calculator: ObjectDetectionSubgraphGpu input_stream: IMAGE:throttled_input_video output_stream: DETECTIONS:output_detections } # 3) 对象跟踪子图每帧实时运行 node { calculator: ObjectTrackingSubgraphGpu input_stream: VIDEO:input_video input_stream: DETECTIONS:output_detections output_stream: DETECTIONS:tracked_detections } # 4) 渲染子图 node { calculator: RendererSubgraphGpu input_stream: IMAGE:input_video input_stream: DETECTIONS:tracked_detections output_stream: IMAGE:output_video }该顶层图在内部引用四个子图检测子图 object_detection_gpu.pbtxt、对象跟踪子图 object_tracking_gpu.pbtxt、框跟踪子图 box_tracking_gpu.pbtxt 以及渲染子图 renderer_gpu.pbtxt。注意上图中PacketResamplerCalculator把进入检测的帧抽稀到 0.5 fps——文档明确指出该帧率只是此图的配置示例可通过PacketResamplerCalculatorOptions.frame_rate自由调整桌面端示例 object_detection_tracking_desktop_live.pbtxt 就使用了frame_rate: 3。这样一来检测子图仅在请求时运行例如按任意低帧率或被特定信号触发承担发现新对象/重新定位的职责对象跟踪子图在每个输入帧上实时运行负责把已检测对象稳定跟住。在移动端 GPU 示例中检测使用 TensorFlow Lite 跑在 GPU 上而跟踪部分跑在 CPUbox tracking 子图内部的降采样与运动分析均为 CPU 操作详见子图内GpuBufferToImageFrameCalculator。对象跟踪子图内部从检测到跟踪再到管理对象跟踪子图 object_tracking_gpu.pbtxt 在 box tracking 之上扩展了四步逻辑DetectionUniqueIdCalculator为每个新检测结果分配全局唯一 id这是实例级跟踪、ID 跨帧稳定的前提DetectionsToTimedBoxListCalculator把Detectionproto 转成跟踪用的TimedBoxProtoList。其源码 detections_to_timed_box_list_calculator.cc 注释明确仅支持RELATIVE_BOUNDING_BOX类型的 LocationData 格式BoxTrackingSubgraphGpu即前面分析的框跟踪子图用最新检测框初始化/维持框跟踪TrackedDetectionManagerCalculator管理新检测对象与在跟踪对象。文档指出当新的检测结果到来时它使用IoUIntersection over Union把当前在跟踪的框与新的检测框做关联从而剔除已过时或重复的框并输出CANCEL_OBJECT_ID反馈给 box tracking 子图让其停止对应跟踪。该节点的实际实现位于 tracked_detection_manager.cc。因此整个检测跟踪闭环可概括为低频检测发现对象 → 转为带 id 的起始框 → 高频运动跟踪维持框 → IoU 关联去重并管理对象生命周期。五、编译运行示例开始之前建议先阅读各平台构建指引Android、iOS、桌面端 C。要可视化这些.pbtxt图可以把图内容复制粘贴到 MediaPipe Visualizer或参考本仓库的 visualizer 文档查看节点与子图结构。移动端Android注意该示例中目标检测使用 TensorFlow Lite 跑在 GPU跟踪在 CPU 上。顶层图object_detection_tracking_mobile_gpu.pbtxtAndroid Bazel 目标mediapipe/examples/android/src/java/com/google/mediapipe/apps/objecttrackinggpu:objecttrackinggpu示例源码位于 objecttrackinggpu文档还提供了预编译 ARM64 APK 的下载入口此处不转载外部链接。iOS 目标不可用。桌面端Linux/macOSCPU桌面示例只提供 CPU 版本GPU 版不可用构建与运行命令记录在 examples/desktop/object_tracking/BUILD 头部# 构建禁用 GPU bazel build -c opt --define MEDIAPIPE_DISABLE_GPU1 \ //mediapipe/examples/desktop/object_tracking:object_tracking_cpu # 运行喂入视频输出带跟踪框的视频 bazel-bin/mediapipe/examples/desktop/object_tracking/object_tracking_cpu \ --calculator_graph_config_file.../object_detection_tracking_desktop_live.pbtxt \ --input_video_pathinput video path \ --output_video_pathoutput video path该目标依赖的顶层图为 object_detection_tracking_desktop_live.pbtxtCPU 变体内部使用ObjectDetectionSubgraphCpu/ObjectTrackingSubgraphCpu/RendererSubgraphCpuPacketResampler抽帧到 3 fps并且从 BUILD 的data可以看到它运行时加载ssdlite_object_detection.tflite与对应的 labelmap位于 mediapipe/modelslabelmap 文件为 ssdlite_object_detection_labelmap.txt。六、仓库中的可延伸阅读入口如果你想从用起来深入到改起来推荐按下列路径继续阅读本仓库子图全部文件集中在 mediapipe/graphs/tracking/subgraphsbox_tracking_*.pbtxt、object_tracking_*.pbtxt、object_detection_*.pbtxt、renderer_*.pbtxt顶层示例图在 mediapipe/graphs/tracking移动端 GPU 与桌面端 live 两个版本可直接对照框跟踪的底层状态机实现在 box_tracker.cc含同名头文件与 proto box_tracker.proto并有 box_tracker_test.cc 提供行为测试参考运动分析与打包的底层算法分别位于 motion_analysis.cc 与 flow_packager.cc框架层概念计算器、图、时间戳、子图可查阅 calculators.md、graphs.md 等文档。七、小结MediaPipe Box Tracking 是理解如何把经典视觉算法工程化为可组合的图模块的绝佳案例它用三个职责单一的计算器整图运动分析、运动元数据打包、纯运动驱动的框跟踪实现了计算量与跟踪对象数解耦、跟踪阶段不依赖 RGB 帧、支持跨帧缓存与随机访问等特性并在上层通过与低频 ML 检测子图、IoU 对象管理子图的组合形成一套移动端可实时运行的检测跟踪流水线。仓库中从box_tracking_gpu.pbtxt到object_detection_tracking_mobile_gpu.pbtxt再到 Android/桌面示例目标的完整链路可作为复刻与改造该方案的第一手参考。【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考