jumpZeroVelocityDetection.m

Go to the documentation of this file.

%> @brief this function performs a zero velocity detection on the provided data.
%>
%> @param data - data structured as defined in @ref jumpReadData
%> @param options.plot - boolean to enable plotting (default: false)
%> @param options.method - method to use for zero velocity detection (default: "movstd_acc_gyr")
%> @param options.windowSize - window size for the moving standard deviation (default: 100)
%> @param options.threshold_acc - threshold for the acceleration (default: 0.15 m/s^2)
%> @param options.threshold_gyr - threshold for the angular velocity (default: 0.15 deg/s)
%>
%> @retval zv - logical vector indicating zero velocity (1) and movement (0)
%>
%> @details The methods works as follows:
%> - movstd_acc_gyr: calculates the moving standard deviation of the acceleration
%> and angular velocity. If the standard deviation is below the threshold for both
%> acceleration and angular velocity, the data is considered zero velocity.
%>
%> @file jumpZeroVelocityDetection.m
%>
%> @copyright see the file @ref LICENSE in the root directory of the repository
 
function zv = jumpZeroVelocityDetection(data, options)
% input validation
arguments
    data (1,1) struct;
    options.plot (1,1) logical = false;
    options.method (1,1) string = "movstd_acc_gyr";
    options.windowSize (1,1) double = 100;
    options.threshold_acc (1,1) double = 0.15;
    options.threshold_gyr (1,1) double = 0.15;
end
 
% check data structure
assert(jumpCheckData(data), "Data structure is not valid.");
 
switch options.method
    case "movstd_acc_gyr"
        try
            std_acc = max(abs(movstd(data.tt.acc, options.windowSize)),[],2);
            std_gyr = max(abs(movstd(data.tt.gyr, options.windowSize)),[],2);
            
            zv = std_acc < options.threshold_acc & std_gyr < options.threshold_gyr;
        catch e
            error("Zero velocity detection failed. Check if the data is correctly structured and the parameters are set correctly.");
        end
    otherwise
        error("Unknown method: %s", method);
end
 
if options.plot
    figure;
    plt1 = subplot(2,1,1);
    yyaxis left;
    plot(data.tt.t, data.tt.acc, "DisplayName", "acceleration");
    ylabel("acc [m/s^2]");
    yyaxis right;
    plot(data.tt.t, zv, '.', "DisplayName", "zv");
    ylim([-0.1, 1.1]);
    yticks([0, 1]);
    yticklabels(["movement", "zero velocity"]);
    ylabel("zv");
    title("Zero velocity detection");
    legend("Location", "best");
    
    plt2 = subplot(2,1,2);
    yyaxis left;
    plot(data.tt.t, data.tt.gyr, "DisplayName", "angular velocity");
    ylabel("gyr [deg/s]");
    yyaxis right;
    plot(data.tt.t, zv, '.', "DisplayName", "zv");
    ylim([-0.1, 1.1]);
    yticks([0, 1]);
    yticklabels(["movement", "zero velocity"]);
    ylabel("zv");
    xlabel("time [s]");
    legend("Location", "best");
    
    linkaxes([plt1, plt2], "x");
    
end