Holistic Tracking数据导出格式转换：CSV/JSON互转实战教程

1. 引言

1.1 学习目标

本文将带你掌握如何对Holistic Tracking模型输出的人体关键点数据进行结构化处理，重点实现CSV 与 JSON 格式之间的高效互转。通过本教程，你将能够：

理解 MediaPipe Holistic 输出的关键点数据结构
将原始检测结果导出为标准 CSV 和 JSON 文件
实现两种格式之间的双向转换
构建可复用的数据预处理模块，便于后续动作分析、动画驱动或机器学习建模

完成本教程后，你可以轻松将全息感知系统集成到自动化流水线中，支持数据归档、跨平台传输和可视化分析。

1.2 前置知识

建议具备以下基础： - Python 编程经验（熟悉字典、列表操作） - 了解基本的文件读写操作（json,csv模块） - 对 MediaPipe 或计算机视觉有一定认知

无需深度学习背景，所有代码均可直接运行。

1.3 教程价值

在虚拟人、动作捕捉、行为识别等场景中，结构化存储人体姿态数据是工程落地的关键一步。然而，MediaPipe 默认输出的是嵌套的 Protobuf 结构，难以直接用于数据分析或模型训练。

本教程提供一套完整的“检测 → 提取 → 转换 → 导出”流程，特别聚焦于CSV 与 JSON 的标准化互转逻辑，帮助开发者快速构建数据管道，提升项目迭代效率。

2. 环境准备与数据结构解析

2.1 运行环境配置

确保已安装以下依赖库：

pip install mediapipe opencv-python pandas numpy

推荐使用 Python 3.8+ 版本以保证兼容性。

2.2 Holistic 关键点结构概览

MediaPipe Holistic 模型输出包含三大子模块，共543 个 3D 关键点：

模块	关键点数量	坐标维度	示例用途
Pose（姿态）	33 点	(x, y, z, visibility)	动作分类、步态分析
Face Mesh（面部）	468 点	(x, y, z)	表情识别、唇形同步
Hands（手势）	左右手各 21 点	(x, y, z)	手势控制、交互操作

📌 注意：Pose 输出包含visibility字段表示置信度，而 Face 和 Hands 不提供该字段，需自行插值补全。

2.3 原始输出示例（简化版）

results.pose_landmarks.landmark[0] # 第一个姿态点 # -> x: 0.45, y: 0.67, z: -0.12, visibility: 0.98 results.face_landmarks.landmark[10] # 鼻尖位置 # -> x: 0.51, y: 0.32, z: 0.05

这些数据为landmark_pb2.Landmark类型对象，不能直接序列化为 JSON 或写入 CSV，必须先转换为原生 Python 数据类型。

3. 数据提取与标准化封装

3.1 提取函数设计原则

我们定义统一接口，将results对象中的关键点提取为标准字典结构，便于后续格式转换。

3.2 完整提取代码实现

import json import csv import pandas as pd from collections import OrderedDict def extract_holistic_data(results): """ 从 MediaPipe Holistic 结果中提取结构化数据 Args: results: mediapipe.solutions.holistic.HolisticResults Returns: dict: 包含 pose, face, left_hand, right_hand 的有序字典 """ data = OrderedDict() # 提取姿态关键点 (带 visibility) if results.pose_landmarks: data['pose'] = [ { 'x': lm.x, 'y': lm.y, 'z': lm.z, 'visibility': lm.visibility } for lm in results.pose_landmarks.landmark ] else: data['pose'] = [None] * 33 # 提取面部关键点 if results.face_landmarks: data['face'] = [ {'x': lm.x, 'y': lm.y, 'z': lm.z} for lm in results.face_landmarks.landmark ] else: data['face'] = [None] * 468 # 提取左右手 def extract_hand(landmarks): return [{'x': lm.x, 'y': lm.y, 'z': lm.z} for lm in landmarks.landmark] if landmarks else [None]*21 data['left_hand'] = extract_hand(results.left_hand_landmarks) data['right_hand'] = extract_hand(results.right_hand_landmarks) return data

💡 使用说明：此函数返回一个OrderedDict，保证字段顺序一致，适合批量处理视频帧序列。

4. JSON 导出与加载

4.1 导出为 JSON 文件

def save_to_json(data, filepath): """ 将提取的数据保存为 JSON 文件 """ with open(filepath, 'w', encoding='utf-8') as f: json.dump(data, f, indent=2, ensure_ascii=False) print(f"✅ JSON 数据已保存至: {filepath}") # 示例调用 # save_to_json(extracted_data, "output.json")

输出示例 (`output.json`)：

{ "pose": [ {"x": 0.45, "y": 0.67, "z": -0.12, "visibility": 0.98}, ... ], "face": [ {"x": 0.51, "y": 0.32, "z": 0.05}, ... ], "left_hand": [...], "right_hand": [...] }

4.2 加载 JSON 数据

def load_from_json(filepath): """ 从 JSON 文件加载数据 """ with open(filepath, 'r', encoding='utf-8') as f: return json.load(f)

📌 优势：JSON 保留完整层级结构，适合长期存档和 Web 接口通信。

5. CSV 导出策略与实现

5.1 CSV 存储挑战

由于数据具有多层级结构（pose/face/hands），无法直接扁平化为二维表。我们采用以下两种方案：

方案	描述	适用场景
单文件分 sheet	使用 Excel 多工作表	本地查看、人工分析
多文件拆分	分别生成 pose.csv, face.csv 等	自动化流水线、数据库导入

本文采用多文件拆分 + 统一前缀命名的方式，兼顾灵活性与可维护性。

5.2 CSV 导出核心代码

def save_to_csv(data, prefix="holistic"): """ 将各模块分别导出为 CSV 文件 """ def write_module(df, name): filename = f"{prefix}_{name}.csv" df.to_csv(filename, index=False) print(f"✅ {name.upper()} 数据已保存至: {filename}") # Pose to DataFrame df_pose = pd.DataFrame(data['pose']) write_module(df_pose, "pose") # Face df_face = pd.DataFrame(data['face']) write_module(df_face, "face") # Left Hand df_lh = pd.DataFrame(data['left_hand']) write_module(df_lh, "left_hand") # Right Hand df_rh = pd.DataFrame(data['right_hand']) write_module(df_rh, "right_hand")

输出文件结构：

holistic_pose.csv # 33 行 × 4 列 holistic_face.csv # 468 行 × 3 列 holistic_left_hand.csv # 21 行 × 3 列 holistic_right_hand.csv# 21 行 × 3 列

📌 提示：若需合并为单个宽表，可用pandas.concat()按索引对齐拼接。

6. CSV 与 JSON 互转工具链

6.1 JSON → CSV 转换器

def json_to_csv(json_path, output_prefix): """ 将 JSON 文件转换为多个 CSV 文件 """ data = load_from_json(json_path) save_to_csv(data, prefix=output_prefix)

6.2 CSV → JSON 转换器

def csv_to_json(prefix, output_path): """ 将多个 CSV 文件合并回 JSON 结构 """ def read_csv_safe(filename): try: return pd.read_csv(filename).to_dict('records') except FileNotFoundError: print(f"⚠️ 文件未找到: {filename}") return [None] * { 'pose': 33, 'face': 468, 'left_hand': 21, 'right_hand': 21 }.get(filename.split('_')[1], 21) data = OrderedDict() data['pose'] = read_csv_safe(f"{prefix}_pose.csv") data['face'] = read_csv_safe(f"{prefix}_face.csv") data['left_hand'] = read_csv_safe(f"{prefix}_left_hand.csv") data['right_hand'] = read_csv_safe(f"{prefix}_right_hand.csv") with open(output_path, 'w', encoding='utf-8') as f: json.dump(data, f, indent=2, ensure_ascii=False) print(f"✅ 已从 CSV 重建并保存为 JSON: {output_path}")

6.3 使用示例

# 全流程演示 extracted_data = extract_holistic_data(results) # 导出为 JSON save_to_json(extracted_data, "frame_001.json") # 转为 CSV json_to_csv("frame_001.json", "frame_001") # 再转回 JSON csv_to_json("frame_001", "recovered.json")

✅ 验证方法：可用jsondiff库比对原始与恢复后的数据一致性。

7. 实战技巧与常见问题

7.1 批量处理视频帧

import os def batch_export_frames(results_list, output_dir="frames"): os.makedirs(output_dir, exist_ok=True) for i, results in enumerate(results_list): data = extract_holistic_data(results) save_to_json(data, f"{output_dir}/frame_{i:04d}.json") json_to_csv(f"{output_dir}/frame_{i:04d}.json", f"{output_dir}/frame_{i:04d}")

适用于动作捕捉序列导出。

7.2 时间戳添加（增强实用性）

修改extract_holistic_data函数，在顶层添加时间信息：

data['timestamp'] = time.time() data['frame_id'] = frame_counter

便于后期做时序分析。

7.3 常见问题解答

问题	解决方案
CSV 中出现`NaN`	使用`df.fillna(0)`填充缺失值
JSON 文件过大	启用压缩：`json.dump(..., separators=(',', ':'))`
手部点错位	检查是否左右手混淆，可通过手腕位置判断
导出速度慢	改用`orjson`或`ujson`加速序列化