Math

C interface to some transform-related math functions. More...

Collaboration diagram for Math:

Files
file	m_api.h
	C interface to math library.
file	m_base.cpp
	Base implementations for math library.
file	m_eigen_interop.hpp
	Interoperability helpers connecting internal math types and Eigen.
file	m_filter_fifo.c
	A fifo that also allows you to dynamically filter.
file	m_filter_fifo.h
	A fifo that also allows you to dynamically filter.
file	m_hash.cpp
	Hashing function.
file	m_imu_3dof.c
	A IMU fusion specially made for 3dof devices.
file	m_imu_3dof.h
	A IMU fusion specially made for 3dof devices.
file	m_imu_pre.c
	IMU pre filter struct.
file	m_imu_pre.h
	IMU pre filter struct.
file	m_optics.c
	Functions related to field-of-view.
file	m_quatexpmap.cpp
	Base implementations for math library.
file	m_vec2.h
	C vec2 math library.
file	m_vec3.h
	C vec3 math library.

Macros
#define	MATH_GRAVITY_M_S2   (9.8066)
	Standard gravity acceleration constant. More...

Functions
size_t	math_hash_string (const char *str_c, size_t length)
	Generate a hash value from the given string, trailing zero not included. More...
void	math_quat_rotate_vec3 (const struct xrt_quat *left, const struct xrt_vec3 *right, struct xrt_vec3 *result)
	Rotate a vector. More...
void	math_quat_integrate_velocity (const struct xrt_quat *quat, const struct xrt_vec3 *ang_vel, float dt, struct xrt_quat *result)
	Integrate an angular velocity vector (exponential map) and apply to a quaternion. More...
void	math_quat_finite_difference (const struct xrt_quat *quat0, const struct xrt_quat *quat1, float dt, struct xrt_vec3 *out_ang_vel)
	Compute an angular velocity vector (exponential map format) by taking the finite difference of two quaternions. More...
bool	math_compute_fovs (double w_total, double w_1, double horizfov_total, double h_total, double h_1, double vertfov_total, struct xrt_fov *fov)
	Perform the computations from "Computing Half-Fields-Of-View from Simpler Display Models", to get half-FOVs from things we can retrieve from other APIs. More...
bool	math_vec3_validate (const struct xrt_vec3 *vec3)
	Check if this vec3 is valid for math operations. More...
void	math_vec3_accum (const struct xrt_vec3 *additional, struct xrt_vec3 *inAndOut)
	Accumulate a vector by adding in-place. More...
void	math_vec3_cross (const struct xrt_vec3 *l, const struct xrt_vec3 *r, struct xrt_vec3 *result)
	Cross product of a vector. More...
void	math_quat_from_angle_vector (float angle_rads, const struct xrt_vec3 *vector, struct xrt_quat *result)
	Create a rotation from a angle in radians and a vector. More...
void	math_quat_from_matrix_3x3 (const struct xrt_matrix_3x3 *mat, struct xrt_quat *result)
	Create a rotation from a 3x3 rotation matrix. More...
void	math_quat_from_plus_x_z (const struct xrt_vec3 *plus_x, const struct xrt_vec3 *plus_z, struct xrt_quat *result)
	Create a rotation from two vectors plus x and z, by creating a rotation matrix by crossing z and x to get the y axis. More...
bool	math_quat_validate (const struct xrt_quat *quat)
	Check if this quat can be used in transformation operations. More...
void	math_quat_normalize (struct xrt_quat *inout)
	Normalize a quaternion. More...
void	math_quat_rotate_vec3 (const struct xrt_quat *left, const struct xrt_vec3 *right, struct xrt_vec3 *result)
	Rotate a vector. More...
void	math_quat_rotate (const struct xrt_quat *left, const struct xrt_quat *right, struct xrt_quat *result)
	Rotate a quaternion (compose rotations). More...
void	math_quat_integrate_velocity (const struct xrt_quat *quat, const struct xrt_vec3 *ang_vel, float dt, struct xrt_quat *result)
	Integrate an angular velocity vector (exponential map) and apply to a quaternion. More...
void	math_quat_finite_difference (const struct xrt_quat *quat0, const struct xrt_quat *quat1, float dt, struct xrt_vec3 *out_ang_vel)
	Compute an angular velocity vector (exponential map format) by taking the finite difference of two quaternions. More...
bool	math_pose_validate (const struct xrt_pose *pose)
	Check if this pose can be used in transformation operations. More...
void	math_pose_invert (const struct xrt_pose *pose, struct xrt_pose *outPose)
	Invert pose. More...
void	math_pose_transform (const struct xrt_pose *transform, const struct xrt_pose *pose, struct xrt_pose *outPose)
	Apply a rigid-body transformation to a pose. More...
void	math_pose_transform_point (const struct xrt_pose *transform, const struct xrt_vec3 *point, struct xrt_vec3 *out_point)
	Apply a rigid-body transformation to a point. More...
void	math_pose_openxr_locate (const struct xrt_pose *space_pose, const struct xrt_pose *relative_pose, const struct xrt_pose *base_space_pose, struct xrt_pose *result)
	Combine the poses of the target and base space with the relative pose of those spaces. More...
void	math_relation_reset (struct xrt_space_relation *out)
	Reset a relation to zero velocity, located at origin, and all validity flags. More...
void	math_relation_apply_offset (const struct xrt_pose *offset, struct xrt_space_relation *in_out_relation)
	Apply a static pose on top of an existing relation. More...
void	math_relation_accumulate_relation (const struct xrt_space_relation *additional_relation, struct xrt_space_relation *in_out_relation)
	Apply another step of space relation on top of an existing relation. More...
void	math_relation_openxr_locate (const struct xrt_pose *space_pose, const struct xrt_space_relation *relative_relation, const struct xrt_pose *base_space_pose, struct xrt_space_relation *result)
	Combine the poses of the target and base space with the relative relation of those spaces. More...

Detailed Description

C interface to some transform-related math functions.

Macro Definition Documentation

MATH_GRAVITY_M_S2

#define MATH_GRAVITY_M_S2   (9.8066)

#include <auxiliary/math/m_api.h>

Standard gravity acceleration constant.

Referenced by xrt_fusion::SimpleIMUFusion::getCorrectedWorldAccel(), and xrt_fusion::SimpleIMUFusion::postCorrect().

Function Documentation

math_compute_fovs()

bool math_compute_fovs	(	double	w_total,
		double	w_1,
		double	horizfov_total,
		double	h_total,
		double	h_1,
		double	vertfov_total,
		struct xrt_fov *	fov
	)

#include <auxiliary/math/m_api.h>

Perform the computations from "Computing Half-Fields-Of-View from Simpler Display Models", to get half-FOVs from things we can retrieve from other APIs.

The origin is in the lower-left corner of the display, so w_1 is the width to the left of CoP, and h_1 is the height below CoP.

If vertfov_total is set to 0, it will be computed from h_total.

Distances are in arbitrary but consistent units. Angles are in radians.

In the diagram below, treating it like a FOV for horizontal, the top angle is horizfov_total, the length of the bottom is w_total, and the distance between the vertical line and the left corner is w_1. Vertical is similar - h_1 is above the center line. The triangle need not be symmetrical, despite how the diagram looks.

              horizfov_total
                      *
angle_left (neg) -> / |  \ <- angle_right
                   /  |   \
                  /   |    \
                 /    |     \
                -------------
                [ w_1 ]
                [ --- w  --- ]

-------     --- |\
                |   \
            h_1 |      \ angle_up
h_total     ___ |-------* vertfov_total
                |      / angle_down (neg)
                |    /
                |  /
-------         |/

Returns

true if successful.

math_hash_string()

size_t math_hash_string	(	const char *	str_c,
		size_t	length
	)

#include <auxiliary/math/m_api.h>

Generate a hash value from the given string, trailing zero not included.

Hashing function used is not specified so no guarantee of staying the same between different versions of the software, or even when the same version is compiled on different platforms/libc++ as it might use std::hash.

math_pose_invert()

void math_pose_invert ( const struct xrt_pose *  pose, struct xrt_pose *  outPose  )

related

Invert pose.

OK if input and output are the same addresses.

Referenced by xrt_pose::math_pose_openxr_locate().

math_pose_openxr_locate()

void math_pose_openxr_locate ( const struct xrt_pose *  space_pose, const struct xrt_pose *  relative_pose, const struct xrt_pose *  base_space_pose, struct xrt_pose *  result  )

related

Combine the poses of the target and base space with the relative pose of those spaces.

In a way that OpenXR specifies in the function xrLocateSpace.

Performs roughly outPose = spacePose * relativePose * baseSpacePose^-1

OK if input and output are the same addresses.

References xrt_pose::math_pose_invert(), and xrt_pose::math_pose_transform().

math_pose_transform()

void math_pose_transform ( const struct xrt_pose *  transform, const struct xrt_pose *  pose, struct xrt_pose *  outPose  )

related

Apply a rigid-body transformation to a pose.

OK if input and output are the same addresses.

Referenced by xrt_pose::math_pose_openxr_locate().

math_pose_transform_point()

void math_pose_transform_point ( const struct xrt_pose *  transform, const struct xrt_vec3 *  point, struct xrt_vec3 *  out_point  )

related

Apply a rigid-body transformation to a point.

The input point and output may be the same pointer.

math_pose_validate()

bool math_pose_validate ( const struct xrt_pose *  pose )

related

Check if this pose can be used in transformation operations.

References xrt_quat::math_quat_validate(), and xrt_vec3::math_vec3_validate().

math_quat_finite_difference() [1/2]

void math_quat_finite_difference ( const struct xrt_quat *  quat0, const struct xrt_quat *  quat1, float  dt, struct xrt_vec3 *  out_ang_vel  )

related

Compute an angular velocity vector (exponential map format) by taking the finite difference of two quaternions.

quat1 is the orientation dt time after the orientation was quat0

out_ang_vel and dt share the same units of time, and out_ang_vel is be in radians per unit of time.

math_quat_finite_difference() [2/2]

void math_quat_finite_difference	(	const struct xrt_quat *	quat0,
		const struct xrt_quat *	quat1,
		float	dt,
		struct xrt_vec3 *	out_ang_vel
	)

#include <auxiliary/math/m_api.h>

Compute an angular velocity vector (exponential map format) by taking the finite difference of two quaternions.

quat1 is the orientation dt time after the orientation was quat0

out_ang_vel and dt share the same units of time, and out_ang_vel is be in radians per unit of time.

math_quat_from_angle_vector()

void math_quat_from_angle_vector ( float  angle_rads, const struct xrt_vec3 *  vector, struct xrt_quat *  result  )

related

Create a rotation from a angle in radians and a vector.

math_quat_from_matrix_3x3()

void math_quat_from_matrix_3x3 ( const struct xrt_matrix_3x3 *  mat, struct xrt_quat *  result  )

related

Create a rotation from a 3x3 rotation matrix.

Referenced by xrt_vec3::math_quat_from_plus_x_z().

math_quat_from_plus_x_z()

void math_quat_from_plus_x_z ( const struct xrt_vec3 *  plus_x, const struct xrt_vec3 *  plus_z, struct xrt_quat *  result  )

related

Create a rotation from two vectors plus x and z, by creating a rotation matrix by crossing z and x to get the y axis.

References xrt_matrix_3x3::math_quat_from_matrix_3x3(), and xrt_vec3::math_vec3_cross().

math_quat_integrate_velocity() [1/2]

void math_quat_integrate_velocity ( const struct xrt_quat *  quat, const struct xrt_vec3 *  ang_vel, float  dt, struct xrt_quat *  result  )

related

Integrate an angular velocity vector (exponential map) and apply to a quaternion.

ang_vel and dt should share the same units of time, and the ang_vel vector should be in radians per unit of time.

math_quat_integrate_velocity() [2/2]

void math_quat_integrate_velocity	(	const struct xrt_quat *	quat,
		const struct xrt_vec3 *	ang_vel,
		float	dt,
		struct xrt_quat *	result
	)

#include <auxiliary/math/m_api.h>

Integrate an angular velocity vector (exponential map) and apply to a quaternion.

ang_vel and dt should share the same units of time, and the ang_vel vector should be in radians per unit of time.

math_quat_normalize()

void math_quat_normalize ( struct xrt_quat *  inout )

related

Normalize a quaternion.

math_quat_rotate()

void math_quat_rotate ( const struct xrt_quat *  left, const struct xrt_quat *  right, struct xrt_quat *  result  )

related

Rotate a quaternion (compose rotations).

math_quat_rotate_vec3() [1/2]

void math_quat_rotate_vec3	(	const struct xrt_quat *	left,
		const struct xrt_vec3 *	right,
		struct xrt_vec3 *	result
	)

#include <auxiliary/math/m_api.h>

Rotate a vector.

math_quat_rotate_vec3() [2/2]

void math_quat_rotate_vec3 ( const struct xrt_quat *  left, const struct xrt_vec3 *  right, struct xrt_vec3 *  result  )

related

Rotate a vector.

math_quat_validate()

bool math_quat_validate ( const struct xrt_quat *  quat )

related

Check if this quat can be used in transformation operations.

Referenced by xrt_pose::math_pose_validate().

math_relation_accumulate_relation()

void math_relation_accumulate_relation ( const struct xrt_space_relation *  additional_relation, struct xrt_space_relation *  in_out_relation  )

related

Apply another step of space relation on top of an existing relation.

Updates all valid pose and derivative fields, as well as the validity mask.

math_relation_apply_offset()

void math_relation_apply_offset ( const struct xrt_pose *  offset, struct xrt_space_relation *  in_out_relation  )

related

Apply a static pose on top of an existing relation.

Updates all valid pose and derivative fields. Does not modify the validity mask. Treats both position and orientation of transform as valid.

See also

xrt_pose

math_relation_openxr_locate()

void math_relation_openxr_locate ( const struct xrt_pose *  space_pose, const struct xrt_space_relation *  relative_relation, const struct xrt_pose *  base_space_pose, struct xrt_space_relation *  result  )

related

Combine the poses of the target and base space with the relative relation of those spaces.

In a way that OpenXR specifies in the function xrLocateSpace.

Performs roughly out_relation->pose = space_pose * relative_relation->pose * base_space_pose^-1 for the poses, and appropriate rotation

OK if input and output are the same addresses.

See also

xrt_pose

math_relation_reset()

void math_relation_reset ( struct xrt_space_relation *  out )

related

Reset a relation to zero velocity, located at origin, and all validity flags.

math_vec3_accum()

void math_vec3_accum ( const struct xrt_vec3 *  additional, struct xrt_vec3 *  inAndOut  )

related

Accumulate a vector by adding in-place.

Logically, *inAndOut += *additional OK if the two arguments are the same addresses.

math_vec3_cross()

void math_vec3_cross ( const struct xrt_vec3 *  l, const struct xrt_vec3 *  r, struct xrt_vec3 *  result  )

related

Cross product of a vector.

Referenced by xrt_vec3::math_quat_from_plus_x_z().

math_vec3_validate()

bool math_vec3_validate ( const struct xrt_vec3 *  vec3 )

related

Check if this vec3 is valid for math operations.

Referenced by xrt_pose::math_pose_validate().