Function mosaic::compute_dyadic_kinematics#

Function Documentation#

DyadicKinematicsSeries mosaic::compute_dyadic_kinematics(const Skeleton3DResult &result, int trackIdA, int trackIdB, int congruentMotionWindow = 30)#

Derives interpersonal distance/approach-rate/facingness/congruent-motion between two already-reconstructed people (by trackId) from an already-loaded Skeleton3DResult (the 3D Pose Reconstruction plugin’s own session-level result).

Requires the result’s keypoint_names() to contain “nose”, “left_shoulder”, “right_shoulder”, “left_hip”, and “right_hip” (resolved once by name, not a hardcoded COCO index) — facingCosine stays permanently NaN for every sample (distanceMm/approachRateMmPerS still compute normally) if any of the five is missing, rather than crashing or silently reading the wrong index on a non-COCO skeleton.

Distance/approach-rate use each person’s hip midpoint (average of their left_hip/right_hip positionRoom). Facingness needs the same hip midpoint plus the shoulder midpoint and nose, per person — see the .cpp’s facing_vector() for the full derivation: a “chest-forward” unit vector from cross(spine, shoulders), with its inherent front/back sign ambiguity resolved by checking which sign points toward that person’s own nose. facingCosine is the dot product of the two people’s forward vectors: near -1 when oriented in opposite directions (commonly — but not provably, since this is a position-independent orientation comparison — face-to-face in a two-person interaction; also consistent with standing back-to-back facing directly away from each other), near +1 when oriented the same way (e.g. side-by-side), near 0 when perpendicular. This limitation is documented, not a bug: the metric is a pure torso-heading correlation, not a “looking at each other” detector.

Approach rate and each person’s own speed (used internally for congruent motion) both follow pose_kinematics.hpp’s established discipline exactly: skip missing samples rather than interpolate, and derive using the REAL elapsed time between the two nearest valid samples, so a tracking gap yields an honest average rather than a fabricated spike.

Parameters:

congruentMotionWindow – Trailing window size (in paired valid speed samples, not ticks) for the rolling Pearson correlation of A’s and B’s instantaneous speed. A tick’s congruentMotionCorr stays NaN until at least 3 paired samples exist in its trailing window, and also if either signal has zero variance in that window (e.g. one person standing still — not an error, just undefined correlation).