Analyze your data in Python
Each recording's output_data/freemocap_data_by_frame.parquet file (see
find and read your output) holds all the data in one table: one row per keypoint per frame, with frame, keypoint, x,
y, z, model, trajectory, and reprojection_error columns. See
the output data model for what each of those
means; this page is about actually working with it.
Loading your data
import pandas as pd
df = pd.read_parquet("path/to/recording/output_data/freemocap_data_by_frame.parquet")
df.head()
Pulling out a single joint
right_wrist = df[df["keypoint"] == "right_wrist"]
right_wrist = right_wrist.sort_values("frame")
That gives you the x, y, and z position of one keypoint in every frame, in order.
Checking tracking quality
The reprojection_error column is there for a per-point quality score, but it's empty (all NaN)
in current recordings. For now, check tracking quality by eye in the annotated videos. See
the output data model.
A quick trajectory plot
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.plot(right_wrist["frame"], right_wrist["z"])
ax.set_xlabel("Frame")
ax.set_ylabel("Z position (mm)")
plt.show()
Remember the coordinate system. Data is in millimetres, with +Z as up, if your ground-plane calibration set a Z-up frame in the first place.
If you need array-shaped data instead
The tidy parquet is usually the easier starting point, but the same data
is also available as .npy arrays shaped (num_frames, num_markers, 3)
per tracker and body region, if that's a better fit for your existing
tooling:
import numpy as np
# file names start with the tracker used, for example rtmpose_ or mediapipe_
body_3d = np.load("path/to/recording/output_data/mediapipe_body_3d_xyz.npy")
print(body_3d.shape) # (num_frames, num_markers, 3)
See array shapes and units and skeleton models and keypoints for exactly which index maps to which keypoint, that mapping is tracker-specific.