Linear Algebra Operations

Utility functions for vector and signal-level linear algebra operations.

biomechzoo.linear_algebra_ops.compute_magnitude_data.compute_magnitude_data(data, ch_x, ch_y, ch_z, ch_new_name=None)[source]

Compute Euclidean magnitude from IMU channels stored in a BiomechZoo-style data dict.

Parameters:

  • data (dict) – BiomechZoo data structure where each channel is stored as: data[channel][‘line’] -> np.ndarray

  • ch_x, ch_y, ch_z (str or None) – Channel names for X, Y, Z components. Any channel can be None (treated as missing / ignored).

    Rules: - At least 2 channels must be provided - Missing channels are treated as zero contribution

  • ch_new_name (str or None) – Name of output magnitude channel. If None, a name is automatically generated.

Returns:

data (dict) – Updated data dictionary with added magnitude channel.

Parameters:

  • data (Dict)

  • ch_x (str | None)

  • ch_y (str | None)

  • ch_z (str | None)

  • ch_new_name (str | None)

Return type:

Dict

biomechzoo.linear_algebra_ops.compute_magnitude_data.compute_magnitude_line(x, y, z)[source]

Compute Euclidean magnitude (supports 2D by allowing y or z to be None).

Parameters:

x, y, z (array_like or None) – Signal components. Any component can be None. If a component is None, it is treated as zero (i.e., 2D or 1D data is supported).

Returns:

magnitude (ndarray) – Vector magnitude sqrt(x^2 + y^2 + z^2)

Parameters:
Return type:

ndarray

biomechzoo.linear_algebra_ops.rectify.compute_magnitude_line(x, y, z)[source]

Compute the Euclidean magnitude of a 3-component signal.

Parameters:

  • x (array_like) – X component.

  • y (array_like) – Y component.

  • z (array_like) – Z component.

Returns:

magnitude (ndarray) – Vector magnitude sqrt(x**2 + y**2 + z**2).

Parameters:
Return type:

ndarray

biomechzoo.linear_algebra_ops.rectify.rectify_data(data, chs)[source]

Take the absolute value of one or more channels and store the result as new channels.

Parameters:

  • data (dict) – Zoo data dictionary.

  • chs (str or list of str) – Channel name(s) to rectify.

Returns:

data (dict) – The input data dictionary updated with one new '<ch>_rectified' channel per entry in chs.

Parameters:
Return type:

Dict

biomechzoo.linear_algebra_ops.rectify.rectify_line(yd)[source]

Take the absolute value of a signal.

Parameters:

yd (array_like) – Input signal.

Returns:

yd_abs (ndarray) – Absolute value of yd.

Parameters:

yd (_SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes])

Return type:

ndarray

biomechzoo.linear_algebra_ops.kinematics.rotate_dcm_data(data, ch, axis, degrees)[source]

Apply a rotation about a principal axis to one segment’s DCM.

Parameters:

  • data (dict) – Zoo data dictionary containing DCM channels for the segment to be rotated.

  • ch (list[str]) – List of 3 channel names identifying the DCM to rotate, ordered i, j, k (e.g., ['i_LSh', 'j_LSh', 'k_LSh']).

  • axis ({‘X’, ‘Y’, ‘Z’}) – Principal axis to rotate about (case-insensitive).

  • degrees (float) – Rotation angle in degrees.

Returns:

data (dict) – The input data dictionary with the DCM channels updated in place to reflect the applied rotation.

Raises:

ValueError – If ch does not have exactly 3 elements, if all channels do not belong to the same segment, or if axis is not 'X', 'Y', or 'Z'.

Parameters:
Return type:

dict

biomechzoo.linear_algebra_ops.kinematics.quats2euler_data(data, ch_prox, ch_dist, sequence)[source]

Compute Euler angles of the distal segment relative to the proximal segment from quaternion data stored in a zoo data dictionary.

Parameters:

  • data (dict) – Zoo data dictionary containing quaternion channels for the proximal and distal segments.

  • ch_prox (list[str]) – List of 4 channel names for the proximal segment’s quaternion components, ordered W, X, Y, Z (e.g., ['Quat_W_LSh', 'Quat_X_LSh', 'Quat_Y_LSh', 'Quat_Z_LSh']).

  • ch_dist (list[str]) – List of 4 channel names for the distal segment’s quaternion components, ordered W, X, Y, Z (e.g., ['Quat_W_LH', 'Quat_X_LH', 'Quat_Y_LH', 'Quat_Z_LH']).

  • sequence (str) – Euler angle rotation sequence passed to scipy.spatial.transform.Rotation.as_euler(). Case determines intrinsic (uppercase) vs extrinsic (lowercase) rotations (e.g., 'ZXY' for intrinsic, 'zxy' for extrinsic).

Returns:

data (dict) – The input data dictionary updated with three new channels: '<prox>_<dist>_alpha', '<prox>_<dist>_beta', and '<prox>_<dist>_gamma', containing the first, second, and third Euler angles (in degrees) respectively, where <prox> and <dist> are the segment labels extracted from prox_ch and dist_ch.

Raises:

ValueError – If prox_ch or dist_ch do not have exactly 4 elements.

Parameters:
Return type:

dict

References

https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html

biomechzoo.linear_algebra_ops.kinematics.dcms2euler_data(data, ch_prox, ch_dist, sequence)[source]

Compute Euler angles of the distal segment relative to the proximal segment from direction cosine matrices (DCMs) stored in a zoo data dictionary.

Parameters:

  • data (dict) – Zoo data dictionary containing DCM channels for the proximal and distal segments.

  • ch_prox (list[str]) – List of 3 channel names for the proximal segment’s DCM column vectors, ordered i, j, k (e.g., ['i_LSh', 'j_LSh', 'k_LSh']).

  • ch_dist (list[str]) – List of 3 channel names for the distal segment’s DCM column vectors, ordered i, j, k (e.g., ['i_LH', 'j_LH', 'k_LH']).

  • sequence (str) – Euler angle rotation sequence passed to scipy.spatial.transform.Rotation.as_euler(). Case determines intrinsic (uppercase) vs extrinsic (lowercase) rotations (e.g., 'ZXY' for intrinsic, 'zxy' for extrinsic).

Returns:

data (dict) – The input data dictionary updated with three new channels: '<prox>_<dist>_alpha', '<prox>_<dist>_beta', and '<prox>_<dist>_gamma', containing the first, second, and third Euler angles (in degrees) respectively, where <prox> and <dist> are the segment labels extracted from prox_ch and dist_ch.

Raises:

ValueError – If prox_ch or dist_ch do not have exactly 3 elements.

Parameters:
Return type:

dict

References

https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html

biomechzoo.linear_algebra_ops.kinematics.marker2dcm_data(data, seg, origin, marker_1, marker_2)[source]

Compute a right-handed local coordinate system (LCS) from motion capture marker positions and store it as a direction cosine matrix (DCM) in the zoo data dictionary.

Parameters:

  • data (dict) – Zoo data dictionary containing motion capture marker channels.

  • seg (str) – Segment label used to name the output DCM channels (e.g., 'LSh' produces 'i_LSh', 'j_LSh', 'k_LSh').

  • origin (str) – Label of the marker defining the origin of the local coordinate system. Supports both full (e.g., 'LeftShank1') and abbreviated (e.g., 'LShank1') naming conventions.

  • marker_1 (str) – Label of the marker defining the primary axis (i). Same naming conventions as origin.

  • marker_2 (str) – Label of the marker used to define the temporary vector for computing the orthogonal axes via cross product. Same naming conventions as origin.

Returns:

data (dict) – The input data dictionary updated with three new channels: 'i_<seg>', 'j_<seg>', and 'k_<seg>', containing the first, second, and third column vectors of the DCM respectively.

Raises:

ValueError – If the resulting DCM is not orthonormal.

Parameters:
Return type:

dict

Notes

The LCS is constructed as follows:

  • i = unit vector from origin to marker_1

  • j_temp = unit vector from origin to marker_2

  • k = unit vector of i × j_temp

  • j = k × i

Orthonormality is verified before storing.

biomechzoo.linear_algebra_ops.kinematics.quats2dcm_data(data, seg, ch)[source]

Compute a direction cosine matrix (DCM) from quaternion data and store it in the zoo data dictionary.

Parameters:

  • data (dict) – Zoo data dictionary containing quaternion channels for the segment.

  • seg (str) – Segment label used to name the output DCM channels (e.g., 'LSh' produces 'i_LSh', 'j_LSh', 'k_LSh').

  • ch (list[str]) – List of 4 quaternion channel names ordered W, X, Y, Z (e.g., ['Quat_W_LSh', 'Quat_X_LSh', 'Quat_Y_LSh', 'Quat_Z_LSh']).

Returns:

data (dict) – The input data dictionary updated with three new channels: 'i_<seg>', 'j_<seg>', and 'k_<seg>', containing the first, second, and third column vectors of the DCM respectively.

Raises:

ValueError – If ch does not have exactly 4 elements.

Parameters:
Return type:

dict

References

https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html

biomechzoo.linear_algebra_ops.make_unit.make_unit(v)[source]

Normalise a vector or array of vectors to unit length.

Parameters:

v (ndarray) – Input vector or array of vectors. The last axis is treated as the vector dimension.

Returns:

ndarray – Array of the same shape as v where each vector has been divided by its L2 norm, resulting in unit length along the last axis.

Parameters:

v (ndarray)

Return type:

ndarray