gaitmap.preprocessing.sensor_alignment.ForwardDirectionSignAlignment

class gaitmap.preprocessing.sensor_alignment.ForwardDirectionSignAlignment(forward_direction: str = 'x', rotation_axis: str = 'z', baseline_velocity_threshold: float = 0.2, ori_method: BaseOrientationMethod = cf(MadgwickAHRS(beta=0.1, initial_orientation=array([0., 0., 0., 1.]), memory=None, use_magnetometer=False)), zupt_detector_orientation_init: BaseZuptDetector = cf(NormZuptDetector(inactive_signal_threshold=0.01, metric='variance', sensor='acc', window_length_s=0.15, window_overlap=0.5, window_overlap_samples=None)), pos_method: BasePositionMethod = cf(PieceWiseLinearDedriftedIntegration(gravity=array([0., 0., 9.81]), level_assumption=False, zupt_detector=NormZuptDetector(inactive_signal_threshold=15.0, metric='mean', sensor='gyr', window_length_s=0.15, window_overlap=0.5, window_overlap_samples=None))))

Flip sensor target axis by 0deg or 180deg to align with the sensor frame with the expected forward direction.

Note

This algorithm is only available via the gaitmap_mad package and distributed under a AGPL3 licence. To use it, you need to explicitly install the gaitmap_mad package. Learn more about that here.

This method applies a fixed 0deg or 180deg flip of the coordinate system to match the sensor frame with the expected forward direction. This step is necessary as a subsequent step of other alignment methods which are sign invariant like for example an alignment via PCA. Such methods can only align the sensor frame with a given target plane but cannot ensure the correct “direction” of the coordinate frame. Therefore, an additional 180deg rotation might be necessary. The forward direction is estimated by a strapdown integration of the given IMU data and evaluation of the sign of the primary velocity component of the expected forward direction. To ensure only the forward component within the sensor frame is considered rotations around the yaw axis within the global frame are ignored. The sign (aka 0deg or 180deg flip) is finally estimated by the sign of the mean velocity within the expected forward direction.

Parameters:

forward_direction

axis which corresponds to the expected forward direction e.g. “x”

rotation_axis

axis around which the sensor will be flipped, which must be perpendicular to the forward_direction e.g. “z”

baseline_velocity_threshold

threshold in m/s^2 around which valocity values are ignored for mean calculation. This is necessary to avoid influence of long near zero velocity periods which contain no information about the actual forward direction

ori_method

An instance of any available orientation method with the desired parameters set. This method is called on the input data to actually calculate the orientation and compensate for gravity. Note, the the initial_orientation parameter of this method will be overwritten, as this class estimates the initial orientation automatically on its own.

zupt_detector_orientation_init

An instance of a valid Zupt detector that will be used to estimate the initial orientation for the ori_method.

pos_method

An instance of any available position method with the desired parameters set. This method is called after the orientation estimation to actually calculate the velocity (and position). The provided data is already transformed into the global frame using the orientations calculated by the ori_method.

Other Parameters:

data

The data passed to the align method.

sampling_rate_hz

The sampling rate of this data

Attributes:

aligned_data_

The rotated sensor data after alignment

rotation_

The Rotation object tranforming the original data to the aligned data. For this class the rotation corresponds either to a 0deg or 180deg rotation.

is_flipped_

Boolean indicating if the data is flipped (aka 180 deg rotation required)

ori_method_

Reference to the orientation method object after alignment. This contains the calculated orientations. This is mostly useful for debugging.

pos_method_

Reference to the position method object after alignment This contains the calculated velocities and positions. Note, that these will equivalent to the full sensor trajectory in the world frame. This is mostly useful for debugging.

See also

gaitmap.preprocessing.sensor_alignment.PcaAlignment

Details on the PCA based alignment method.

Notes

This method is usually used as a subsequent step after a sign invariant alignment step like PCA alignment and will only apply either a 0deg (aka no rotation) or a 180deg flip on the input data.

Examples

Estimate the sign of the forward direction velocity and apply a 0deg or 180deg flip on the data accordingly. This step is usually a subsequent step of a previous sign invariant alignment step like the PCA alignment.

>>> fdsa = ForwardDirectionSignAlignment(forward_direction="x", rotation_axis="z", baseline_velocity_threshold=0.2)
>>> fdsa = fdsa.align(data, 204.8)
>>> fdsa.aligned_data_["left_sensor"]
<copy of dataset with axis aligned to the medio-lateral plane>
...
>>> fdsa.is_flipped_  # True when the data was rotated by 180 deg, False afterwise
True

Methods

align(data, *, sampling_rate_hz, **_)	Align sensor data.
clone()	Create a new instance of the class with all parameters copied over.
from_json(json_str)	Import an gaitmap object from its json representation.
get_params([deep])	Get parameters for this algorithm.
set_params(**params)	Set the parameters of this Algorithm.
to_json()	Export the current object parameters as json.

__init__(forward_direction: str = 'x', rotation_axis: str = 'z', baseline_velocity_threshold: float = 0.2, ori_method: BaseOrientationMethod = cf(MadgwickAHRS(beta=0.1, initial_orientation=array([0., 0., 0., 1.]), memory=None, use_magnetometer=False)), zupt_detector_orientation_init: BaseZuptDetector = cf(NormZuptDetector(inactive_signal_threshold=0.01, metric='variance', sensor='acc', window_length_s=0.15, window_overlap=0.5, window_overlap_samples=None)), pos_method: BasePositionMethod = cf(PieceWiseLinearDedriftedIntegration(gravity=array([0., 0., 9.81]), level_assumption=False, zupt_detector=NormZuptDetector(inactive_signal_threshold=15.0, metric='mean', sensor='gyr', window_length_s=0.15, window_overlap=0.5, window_overlap_samples=None)))) → None

align(data: DataFrame | dict[Union[collections.abc.Hashable, str], pandas.core.frame.DataFrame], *, sampling_rate_hz: float, **_) → Self

Align sensor data.

clone() → Self

Create a new instance of the class with all parameters copied over.

This will create a new instance of the class itself and all nested objects

classmethod from_json(json_str: str) → Self

Import an gaitmap object from its json representation.

For details have a look at the this example.

You can use the to_json method of a class to export it as a compatible json string.

Parameters:

json_str

json formatted string

get_params(deep: bool = True) → dict[str, Any]

Get parameters for this algorithm.

Parameters:

deep

Only relevant if object contains nested algorithm objects. If this is the case and deep is True, the params of these nested objects are included in the output using a prefix like nested_object_name__ (Note the two “_” at the end)

Returns:

params

Parameter names mapped to their values.

set_params(**params: Any) → Self

Set the parameters of this Algorithm.

To set parameters of nested objects use nested_object_name__para_name=.

to_json() → str

Export the current object parameters as json.

For details have a look at the this example.

You can use the from_json method of any gaitmap algorithm to load the object again.

Warning

This will only export the Parameters of the instance, but not any results!

Examples using gaitmap.preprocessing.sensor_alignment.ForwardDirectionSignAlignment

Automatic sensor alignment

Automatic sensor alignment

Automatic sensor alignment (detailed)

Automatic sensor alignment (detailed)