gait_analysis.analysisRun.computeGait

Description

Analyzes named two-dimensional pose coordinates without opening the app. The function maps five anatomical roles to source points, smooths their coordinates, calculates joint angles and segment lengths, detects repeated active swings, evaluates each swing against quality thresholds, and returns the same four tables used by app preview and CSV export.

Inputs

pose

Scalar normalized pose structure, normally returned by gait_analysis.sourceFiles.readPoseFile. Required fields are coords, an F-by-P-by-2 numeric array of [x y] image coordinates, and pointNames, a P-element text vector. Optional frameIndex and time vectors must have F elements. unitName labels coordinates that are already physical. sourceFormat is copied into the summary table.

opts

Scalar option structure. Start with gait_analysis.analysisRun.defaultOptions; missing fields use those defaults.

Options

iliacPoint

Case-insensitive point name assigned to the iliac role. Default: "iliac".

hipPoint

Point name assigned to the hip role. Default: "hip".

kneePoint

Point name assigned to the knee role. Default: "knee".

anklePoint

Point name assigned to the ankle role. Default: "ankle".

footPoint

Point name used for event detection and step length. Default: "foot".

frameRate

Frames per second used only when pose.time has no finite values. Current Video Marker projects supply this value from embedded video metadata. Zero leaves time_s as NaN. Default: 0.

pixelsPerUnit

Positive pixel density for physical output. Distances and scaled coordinates are divided by this value. When invalid, pose.unitName is retained at scale 1 when present; otherwise output uses pixels. Default: 1.

unitName

Label used with a valid pixelsPerUnit. Default: "px".

originAtFirstFrameFirstPoint

When true, coordinateTable subtracts the first point's first-frame coordinate from every scaled point. Raw pixel columns are unchanged. Default: false.

smoothWindow

Requested centered smoothing span in frames, rounded to an integer of at least one. The effective odd span is 2*floor((smoothWindow-1)/2)+1. Finite values are averaged separately for each point and axis. Default: 5.

detectionProminence

Minimum foot-X peak prominence in source coordinate units. Default: 20, preserving the legacy treadmill workflow threshold.

detectionMinHeightSigma

A lift-off peak must be at least mean(foot X)-value*std(foot X). Default: 2, preserving the legacy treadmill peak-height floor.

minLiftOffIntervalSeconds

Minimum separation between lift-off peaks. It is converted to frames from source time/frame rate. Default: 0.2 seconds.

minSwingFrames

Minimum accepted lift-off-to-landing span. It is also the event separation fallback when source timing is unavailable. Default: 3.

maxSwingFrames

Maximum accepted inclusive lift-off-to-landing span. Default: 300.

minStepLength

Minimum accepted two-dimensional foot endpoint displacement. Default: 1.

maxHipTranslation

Maximum accepted hip endpoint displacement in output units. Default: 1000000, which normally leaves this check inactive.

Event Detection

The detection trace is smoothed foot X. A lift-off candidate is a local maximum meeting detectionProminence; nearby candidates retain the higher peak. Each lift-off is independently paired with the following foot-X minimum before the next lift-off, or before the recording ends. Therefore a completed final swing is retained even without a later lift-off. These are kinematic treadmill events, not force-plate contact measurements.

Measurements

Hip, knee, and ankle angles are the unsigned angles from 0 to 180 degrees between the two adjacent segment vectors. A zero-length or nonfinite segment produces NaN. Segment lengths are Euclidean distances. For each cycle, Step length and each point translation are Euclidean endpoint displacements from lift-off to landing. Range of motion is the finite maximum-minus-minimum joint angle within that swing. When a next lift-off exists, cycle time, stance time, cadence, and duty factor are also reported; the final complete swing may legitimately lack them.

Outputs

result

Scalar structure containing status, normalized options, events, and four tables.

Result Fields

ok, message - true and "Analysis complete" after successful calculation.

options

Effective options after defaults, scalar cleanup, and rounding.

events

Structure with paired liftOffFrames and landingFrames, peak prominence, the foot-X detectionSignal, and footRelativeX diagnostic.

frameTable

One row per frame. It contains frame/time/step membership, landing and lift-off flags, coordinate unit, three joint angles, four segment lengths, and scaled <point>_x/<point>_y columns.

coordinateTable

One row per frame with frame/time and origin metadata, raw <point>__x_px/<point>__y_px columns, and scaled, optionally shifted <point>__x/<point>__y columns. The unshifted origin is [0 0] in pixel coordinates rather than the center of pixel [1 1].

stepTable

One row per paired lift-off-to-landing swing. It contains validity and reason, event frames, swing/cycle/stance timing, cadence, duty factor, two-dimensional step length and point translations, three joint extrema/ranges of motion, and recording-wide joint extrema. invalid_reason is "ok", "duration_out_of_range", "step_length_too_small", or "hip_translation_too_large".

summaryTable

Metric/value text table reporting source geometry, detected and valid step counts, mean valid-swing time and step length, and global finite joint-angle extrema.

Errors

labkit_GaitAnalysis_app:NoPoseData

pose has no nonempty coords field.

labkit_GaitAnalysis_app:MissingRolePoint

A configured role name is absent from pose.pointNames.

Example

frame = (1:12).';
footX = [-2; -3; -1; 2; 4; -3; -1; 2; 4; -3; -1; 1];
pose = struct("coords", NaN(12, 5, 2), ...
"pointNames", ["iliac"; "hip"; "knee"; "ankle"; "foot"], ...
"frameIndex", frame, "time", (frame-1)/30, ...
"unitName", "px", "sourceFormat", "synthetic");
pose.coords(:, :, 1) = [-2*ones(12,1), zeros(12,1), ...
ones(12,1), 2*ones(12,1), footX];
pose.coords(:, :, 2) = repmat([8 6 4 2 0], 12, 1);
opts = gait_analysis.analysisRun.defaultOptions();
opts.smoothWindow = 1;
opts.detectionProminence = 2;
opts.minLiftOffIntervalSeconds = 0.1;
result = gait_analysis.analysisRun.computeGait(pose, opts);
assert(result.ok && height(result.stepTable) == 2)