Monado OpenXR Runtime
Files | Data Structures | Macros | Enumerations | Functions

Trackers, filters and associated helper code. More...

Collaboration diagram for Tracking:

Files

file  t_calibration.cpp
 Calibration code.
 
file  t_calibration_opencv.hpp
 OpenCV calibration helpers.
 
file  t_convert.cpp
 Code to build conversion tables and convert images.
 
file  t_data_utils.c
 Small data helpers for calibration.
 
file  t_debug_hsv_filter.cpp
 HSV filter debug code.
 
file  t_debug_hsv_picker.cpp
 HSV Picker Debugging code.
 
file  t_debug_hsv_viewer.cpp
 HSV debug viewer code.
 
file  t_documentation.h
 Documentation-only header.
 
file  t_file.cpp
 Handling of files and calibration data.
 
file  t_fusion.hpp
 C++ sensor fusion/filtering code that uses flexkalman.
 
file  t_helper_debug_sink.hpp
 Small helper struct that for debugging views.
 
file  t_hsv_filter.c
 A simple HSV filter.
 
file  t_imu.cpp
 IMU fusion implementation - for inclusion into the single kalman-incuding translation unit.
 
file  t_imu.h
 C interface to basic IMU fusion.
 
file  t_imu_fusion.hpp
 C++ sensor fusion/filtering code that uses flexkalman.
 
file  t_kalman.cpp
 Single compiled file for all kalman filter using source.
 
file  t_lowpass.hpp
 Low-pass IIR filter.
 
file  t_lowpass_vector.hpp
 Low-pass IIR filter on vectors.
 
file  t_tracker_hand.cpp
 Hand tracker code.
 
file  t_tracker_psmv.cpp
 PS Move tracker code.
 
file  t_tracker_psmv_fusion.cpp
 PS Move tracker code that is expensive to compile.
 
file  t_tracker_psmv_fusion.hpp
 PS Move tracker code.
 
file  t_tracker_psvr.cpp
 PSVR tracker code.
 
file  t_tracking.h
 Tracking API interface.
 
file  u_hand_tracking.c
 Hand Tracking API interface.
 

Data Structures

struct  t_camera_calibration
 Essential calibration data for a single camera, or single lens/sensor of a stereo camera. More...
 
struct  t_stereo_camera_calibration
 Stereo camera calibration data to be given to trackers. More...
 
struct  t_convert_table
 
struct  t_hsv_filter_color
 
struct  t_hsv_filter_params
 Parameters for constructing an HSV filter. More...
 
struct  t_hsv_filter_large_table
 
struct  t_hsv_filter_optimized_table
 
struct  t_calibration_status
 
struct  t_calibration_params
 

Macros

#define XRT_DISTORTION_MAX_DIM   (5)
 Maximum size of rectilinear distortion coefficient array. More...
 
#define T_HSV_SIZE   32
 
#define T_HSV_STEP   (256 / T_HSV_SIZE)
 
#define T_HSV_DEFAULT_PARAMS()
 

Enumerations

enum  t_board_pattern { T_BOARD_CHECKERS, T_BOARD_CIRCLES, T_BOARD_ASYMMETRIC_CIRCLES }
 Board pattern type. More...
 

Functions

bool t_stereo_camera_calibration_load_v1 (FILE *calib_file, struct t_stereo_camera_calibration **out_data)
 Load stereo calibration data from a given file. More...
 
bool t_stereo_camera_calibration_save_v1 (FILE *calib_file, struct t_stereo_camera_calibration *data)
 Save the given stereo calibration data to the given file. More...
 
void t_convert_fill_table (struct t_convert_table *t)
 
void t_convert_make_y8u8v8_to_r8g8b8 (struct t_convert_table *t)
 
void t_convert_make_y8u8v8_to_h8s8v8 (struct t_convert_table *t)
 
void t_convert_make_h8s8v8_to_r8g8b8 (struct t_convert_table *t)
 
void t_convert_in_place_y8u8v8_to_r8g8b8 (uint32_t width, uint32_t height, size_t stride, void *data_ptr)
 
void t_convert_in_place_y8u8v8_to_h8s8v8 (uint32_t width, uint32_t height, size_t stride, void *data_ptr)
 
void t_convert_in_place_h8s8v8_to_r8g8b8 (uint32_t width, uint32_t height, size_t stride, void *data_ptr)
 
void t_hsv_build_convert_table (struct t_hsv_filter_params *params, struct t_convert_table *t)
 
void t_hsv_build_large_table (struct t_hsv_filter_params *params, struct t_hsv_filter_large_table *t)
 
void t_hsv_build_optimized_table (struct t_hsv_filter_params *params, struct t_hsv_filter_optimized_table *t)
 
static uint8_t t_hsv_filter_sample (struct t_hsv_filter_optimized_table *t, uint32_t y, uint32_t u, uint32_t v)
 
int t_calibration_stereo_create (struct xrt_frame_context *xfctx, const struct t_calibration_params *params, struct t_calibration_status *status, struct xrt_frame_sink *gui, struct xrt_frame_sink **out_sink)
 Create the camera calibration frame sink. More...
 
int t_convert_yuv_or_yuyv_create (struct xrt_frame_sink *next, struct xrt_frame_sink **out_sink)
 
int t_debug_hsv_picker_create (struct xrt_frame_context *xfctx, struct xrt_frame_sink *passthrough, struct xrt_frame_sink **out_sink)
 
int t_debug_hsv_viewer_create (struct xrt_frame_context *xfctx, struct xrt_frame_sink *passthrough, struct xrt_frame_sink **out_sink)
 
int t_debug_hsv_filter_create (struct xrt_frame_context *xfctx, struct xrt_frame_sink *passthrough, struct xrt_frame_sink **out_sink)
 
struct imu_fusionimu_fusion::imu_fusion_create ()
 Create a struct imu_fusion. More...
 
void imu_fusion::imu_fusion_destroy (struct imu_fusion *fusion)
 Destroy a struct imu_fusion. More...
 
int imu_fusion::imu_fusion_incorporate_gyros (struct imu_fusion *fusion, uint64_t timestamp_ns, struct xrt_vec3 const *ang_vel, struct xrt_vec3 const *ang_vel_variance)
 Predict and correct fusion with a gyroscope reading. More...
 
int imu_fusion::imu_fusion_incorporate_accelerometer (struct imu_fusion *fusion, uint64_t timestamp_ns, struct xrt_vec3 const *accel, struct xrt_vec3 const *accel_variance, struct xrt_vec3 *out_world_accel)
 Predict and correct fusion with an accelerometer reading. More...
 
int imu_fusion::imu_fusion_incorporate_gyros_and_accelerometer (struct imu_fusion *fusion, uint64_t timestamp_ns, struct xrt_vec3 const *ang_vel, struct xrt_vec3 const *ang_vel_variance, struct xrt_vec3 const *accel, struct xrt_vec3 const *accel_variance, struct xrt_vec3 *out_world_accel)
 Predict and correct fusion with a simultaneous accelerometer and gyroscope reading. More...
 
int imu_fusion::imu_fusion_get_prediction (struct imu_fusion const *fusion, uint64_t timestamp_ns, struct xrt_quat *out_quat, struct xrt_vec3 *out_ang_vel)
 Get the predicted state. More...
 
int imu_fusion::imu_fusion_get_prediction_rotation_vec (struct imu_fusion const *fusion, uint64_t timestamp_ns, struct xrt_vec3 *out_rotation_vec)
 Get the predicted state as a rotation vector. More...
 
void t_stereo_camera_calibration::t_stereo_camera_calibration_alloc (struct t_stereo_camera_calibration **calib)
 Allocates a new stereo calibration data, unreferences the old calib. More...
 
static void t_stereo_camera_calibration_reference (struct t_stereo_camera_calibration **dst, struct t_stereo_camera_calibration *src)
 Update the reference counts on a stereo calibration data(s). More...
 
int t_hsv_filter::t_hsv_filter_create (struct xrt_frame_context *xfctx, struct t_hsv_filter_params *params, struct xrt_frame_sink *sinks[4], struct xrt_frame_sink **out_sink)
 Construct an HSV filter sink. More...
 
int xrt_tracked_psmv::t_psmv_start (struct xrt_tracked_psmv *xtmv)
 
int xrt_tracked_psmv::t_psmv_create (struct xrt_frame_context *xfctx, struct xrt_colour_rgb_f32 *rgb, struct t_stereo_camera_calibration *data, struct xrt_tracked_psmv **out_xtmv, struct xrt_frame_sink **out_sink)
 
int xrt_tracked_psvr::t_psvr_start (struct xrt_tracked_psvr *xtvr)
 
int xrt_tracked_psvr::t_psvr_create (struct xrt_frame_context *xfctx, struct t_stereo_camera_calibration *data, struct xrt_tracked_psvr **out_xtvr, struct xrt_frame_sink **out_sink)
 
int xrt_tracked_hand::t_hand_create (struct xrt_frame_context *xfctx, struct t_stereo_camera_calibration *data, struct xrt_tracked_hand **out_xth, struct xrt_frame_sink **out_sink)
 
int xrt_tracked_hand::t_hand_start (struct xrt_tracked_hand *xth)
 
static void t_calibration_params::t_calibration_params_default (struct t_calibration_params *p)
 Sets the calibration parameters to the their default values. More...
 

Detailed Description

Trackers, filters and associated helper code.

Coordinate system

Right now there is no specific convention on where a tracking systems coordinate system is centered, and is something we probably need to figure out. Right now the stereo based tracking system used by the PSVR and PSMV tracking system is centered on the camera that OpenCV decided is origin.

To go a bit further on the PSVR/PSMV case. Think about a idealized start up case, the user is wearing the HMD headset and holding two PSMV controllers. The HMD's coordinate system axis are perfectly parallel with the user coordinate with the user's coordinate system. Where -Z is forward. The user holds the controllers with the ball pointing up and the buttons on the back pointing forward. Which if you read the documentation of psmv_device will that the axis of the PSMV are also perfectly aligned with the users coordinate system. So everything "attached" to the user have it's coordinate system parallel to the user's.

The camera on the other hand is looking directly at the user, it's Z-axis and X-axis is flipped in relation to the user's. So to compare what is sees to what the user sees, everything is rotated 180° around the Y-axis.

Macro Definition Documentation

◆ T_HSV_DEFAULT_PARAMS

#define T_HSV_DEFAULT_PARAMS ( )

#include <auxiliary/tracking/t_tracking.h>

Value:
{ \
{ \
{165, 30, 160, 100}, \
{135, 30, 160, 100}, \
{95, 30, 160, 100}, \
}, \
{128, 80}, \
}

Referenced by p_factory_ensure_frameserver(), t_debug_hsv_filter_create(), and t_debug_hsv_viewer_create().

◆ T_HSV_SIZE

#define T_HSV_SIZE   32

◆ T_HSV_STEP

#define T_HSV_STEP   (256 / T_HSV_SIZE)

◆ XRT_DISTORTION_MAX_DIM

#define XRT_DISTORTION_MAX_DIM   (5)

#include <auxiliary/tracking/t_tracking.h>

Maximum size of rectilinear distortion coefficient array.

Referenced by xrt::auxiliary::tracking::CameraCalibrationWrapper::isDataStorageValid().

Enumeration Type Documentation

◆ t_board_pattern

#include <auxiliary/tracking/t_tracking.h>

Board pattern type.

Enumerator
T_BOARD_CHECKERS 
T_BOARD_CIRCLES 
T_BOARD_ASYMMETRIC_CIRCLES 

Function Documentation

◆ imu_fusion_create()

struct imu_fusion * imu_fusion_create ( )

Create a struct imu_fusion.

◆ imu_fusion_destroy()

void imu_fusion_destroy ( struct imu_fusion fusion)

Destroy a struct imu_fusion.

Should not be called simultaneously with any other imu_fusion function.

Parameters
fusionThe IMU Fusion object

◆ imu_fusion_get_prediction()

int imu_fusion_get_prediction ( struct imu_fusion const *  fusion,
uint64_t  timestamp_ns,
struct xrt_quat out_quat,
struct xrt_vec3 out_ang_vel 
)

Get the predicted state.

Does not advance the internal state clock.

Non-zero return means error.

Parameters
fusionThe IMU Fusion object
timestamp_nsThe timestamp corresponding to the predicted state you want.
out_quatThe quaternion to populate with the predicted orientation.
out_ang_velThe vector to poluate with the predicted angular velocity.

◆ imu_fusion_get_prediction_rotation_vec()

int imu_fusion_get_prediction_rotation_vec ( struct imu_fusion const *  fusion,
uint64_t  timestamp_ns,
struct xrt_vec3 out_rotation_vec 
)

Get the predicted state as a rotation vector.

Does not advance the internal state clock.

This is mostly for debugging: a rotation vector can be easier to visualize or understand intuitively.

Non-zero return means error.

Parameters
fusionThe IMU Fusion object
timestamp_nsThe timestamp corresponding to the predicted state you want.
out_rotation_vecThe vector to poluate with the predicted orientation rotation vector.

◆ imu_fusion_incorporate_accelerometer()

int imu_fusion_incorporate_accelerometer ( struct imu_fusion fusion,
uint64_t  timestamp_ns,
struct xrt_vec3 const *  accel,
struct xrt_vec3 const *  accel_variance,
struct xrt_vec3 out_world_accel 
)

Predict and correct fusion with an accelerometer reading.

If you're receiving accel and gyro data at the same time, call imu_fusion_incorporate_gyros_and_accelerometer() instead.

Should not be called simultaneously with any other imu_fusion function.

Non-zero return means error.

Parameters
fusionThe IMU Fusion object
timestamp_nsThe timestamp corresponding to the information being processed with this call.
accelAccelerometer data (in m/s/s) including the effect of gravity - assumed to be +y when aligned with the world.
accel_varianceThe variance of the accelerometer measurements: part of the characteristics of the IMU being used.
out_world_accelOptional output parameter: will contain the non-gravity acceleration in the world frame.

◆ imu_fusion_incorporate_gyros()

int imu_fusion_incorporate_gyros ( struct imu_fusion fusion,
uint64_t  timestamp_ns,
struct xrt_vec3 const *  ang_vel,
struct xrt_vec3 const *  ang_vel_variance 
)

Predict and correct fusion with a gyroscope reading.

dt should not be zero: If you're receiving accel and gyro data at the same time, call imu_fusion_incorporate_gyros_and_accelerometer() instead.

Should not be called simultaneously with any other imu_fusion function.

Non-zero return means error.

Parameters
fusionThe IMU Fusion object
timestamp_nsThe timestamp corresponding to the information being processed with this call.
ang_velAngular velocity vector from gyroscope: in radians per second.
ang_vel_varianceThe variance of the angular velocity measurements: part of the characteristics of the IMU being used.

◆ imu_fusion_incorporate_gyros_and_accelerometer()

int imu_fusion_incorporate_gyros_and_accelerometer ( struct imu_fusion fusion,
uint64_t  timestamp_ns,
struct xrt_vec3 const *  ang_vel,
struct xrt_vec3 const *  ang_vel_variance,
struct xrt_vec3 const *  accel,
struct xrt_vec3 const *  accel_variance,
struct xrt_vec3 out_world_accel 
)

Predict and correct fusion with a simultaneous accelerometer and gyroscope reading.

Should not be called simultaneously with any other imu_fusion function.

Non-zero return means error.

Parameters
fusionThe IMU Fusion object
timestamp_nsThe timestamp corresponding to the information being processed with this call.
ang_velAngular velocity vector from gyroscope: radians/s
ang_vel_varianceThe variance of the angular velocity measurements: part of the characteristics of the IMU being used.
accelAccelerometer data (in m/s/s) including the effect of gravity - assumed to be +y when aligned with the world.
accel_varianceThe variance of the accelerometer measurements: part of the characteristics of the IMU being used.
out_world_accelOptional output parameter: will contain the non-gravity acceleration in the world frame.

◆ t_calibration_params_default()

static void t_calibration_params_default ( struct t_calibration_params p)
inline

◆ t_calibration_stereo_create()

int t_calibration_stereo_create ( struct xrt_frame_context xfctx,
const struct t_calibration_params params,
struct t_calibration_status status,
struct xrt_frame_sink gui,
struct xrt_frame_sink **  out_sink 
)

#include <auxiliary/tracking/t_tracking.h>

Create the camera calibration frame sink.

Parameters
xfctxContext for frame transport.
paramsParameters to use during calibration. Values copied, pointer not retained.
statusOptional pointer to structure for status information. Pointer retained, and pointed-to struct modified.
guiFrame sink
out_sinkOutput: created frame sink.
See also
xrt_frame_context

References t_calibration_params::asymmetric_circles, xrt::auxiliary::tracking::build_board_position(), t_calibration_params::checkers, t_calibration_params::circles, t_calibration_params::cols, t_calibration_params::diagonal_distance_meters, t_calibration_params::distance_meters, t_calibration_params::enabled, t_calibration_params::load, xrt::auxiliary::tracking::make_gui_str(), t_calibration_params::mirror_rgb_image, t_calibration_params::num_collect_restart, t_calibration_params::num_collect_total, t_calibration_params::num_cooldown_frames, t_calibration_params::num_images, t_calibration_params::num_wait_for, P, t_calibration_params::pattern, xrt_frame_sink::push_frame, xrt::auxiliary::tracking::push_model(), t_calibration_params::rows, t_calibration_params::save_images, t_calibration_params::size_meters, t_calibration_params::stereo_sbs, t_calibration_params::subpixel_enable, t_calibration_params::subpixel_size, T_BOARD_ASYMMETRIC_CIRCLES, T_BOARD_CHECKERS, T_BOARD_CIRCLES, xrt::auxiliary::tracking::t_calibration_frame(), t_debug_hsv_filter_create(), t_debug_hsv_picker_create(), t_debug_hsv_viewer_create(), u_sink_create_to_yuv_yuyv_uyvy_or_l8(), and t_calibration_params::use_fisheye.

Referenced by scene_render_select(), and t_calibration_params::t_calibration_params_default().

◆ t_convert_fill_table()

void t_convert_fill_table ( struct t_convert_table t)

◆ t_convert_in_place_h8s8v8_to_r8g8b8()

void t_convert_in_place_h8s8v8_to_r8g8b8 ( uint32_t  width,
uint32_t  height,
size_t  stride,
void *  data_ptr 
)

◆ t_convert_in_place_y8u8v8_to_h8s8v8()

void t_convert_in_place_y8u8v8_to_h8s8v8 ( uint32_t  width,
uint32_t  height,
size_t  stride,
void *  data_ptr 
)

◆ t_convert_in_place_y8u8v8_to_r8g8b8()

void t_convert_in_place_y8u8v8_to_r8g8b8 ( uint32_t  width,
uint32_t  height,
size_t  stride,
void *  data_ptr 
)

◆ t_convert_make_h8s8v8_to_r8g8b8()

void t_convert_make_h8s8v8_to_r8g8b8 ( struct t_convert_table t)

◆ t_convert_make_y8u8v8_to_h8s8v8()

void t_convert_make_y8u8v8_to_h8s8v8 ( struct t_convert_table t)

◆ t_convert_make_y8u8v8_to_r8g8b8()

void t_convert_make_y8u8v8_to_r8g8b8 ( struct t_convert_table t)

◆ t_convert_yuv_or_yuyv_create()

int t_convert_yuv_or_yuyv_create ( struct xrt_frame_sink next,
struct xrt_frame_sink **  out_sink 
)

◆ t_debug_hsv_filter_create()

int t_debug_hsv_filter_create ( struct xrt_frame_context xfctx,
struct xrt_frame_sink passthrough,
struct xrt_frame_sink **  out_sink 
)

◆ t_debug_hsv_picker_create()

int t_debug_hsv_picker_create ( struct xrt_frame_context xfctx,
struct xrt_frame_sink passthrough,
struct xrt_frame_sink **  out_sink 
)

◆ t_debug_hsv_viewer_create()

int t_debug_hsv_viewer_create ( struct xrt_frame_context xfctx,
struct xrt_frame_sink passthrough,
struct xrt_frame_sink **  out_sink 
)

◆ t_hand_create()

int t_hand_create ( struct xrt_frame_context xfctx,
struct t_stereo_camera_calibration data,
struct xrt_tracked_hand **  out_xth,
struct xrt_frame_sink **  out_sink 
)

◆ t_hand_start()

int t_hand_start ( struct xrt_tracked_hand xth)

◆ t_hsv_build_convert_table()

void t_hsv_build_convert_table ( struct t_hsv_filter_params params,
struct t_convert_table t 
)

◆ t_hsv_build_large_table()

void t_hsv_build_large_table ( struct t_hsv_filter_params params,
struct t_hsv_filter_large_table t 
)

◆ t_hsv_build_optimized_table()

void t_hsv_build_optimized_table ( struct t_hsv_filter_params params,
struct t_hsv_filter_optimized_table t 
)

◆ t_hsv_filter_create()

int t_hsv_filter_create ( struct xrt_frame_context xfctx,
struct t_hsv_filter_params params,
struct xrt_frame_sink sinks[4],
struct xrt_frame_sink **  out_sink 
)

Construct an HSV filter sink.

See also
xrt_frame_context

◆ t_hsv_filter_sample()

static uint8_t t_hsv_filter_sample ( struct t_hsv_filter_optimized_table t,
uint32_t  y,
uint32_t  u,
uint32_t  v 
)
inlinestatic

◆ t_psmv_create()

int t_psmv_create ( struct xrt_frame_context xfctx,
struct xrt_colour_rgb_f32 rgb,
struct t_stereo_camera_calibration data,
struct xrt_tracked_psmv **  out_xtmv,
struct xrt_frame_sink **  out_sink 
)

◆ t_psmv_start()

int t_psmv_start ( struct xrt_tracked_psmv xtmv)

◆ t_psvr_create()

int t_psvr_create ( struct xrt_frame_context xfctx,
struct t_stereo_camera_calibration data,
struct xrt_tracked_psvr **  out_xtvr,
struct xrt_frame_sink **  out_sink 
)

◆ t_psvr_start()

int t_psvr_start ( struct xrt_tracked_psvr xtvr)

◆ t_stereo_camera_calibration_alloc()

void t_stereo_camera_calibration_alloc ( struct t_stereo_camera_calibration **  calib)

Allocates a new stereo calibration data, unreferences the old calib.

◆ t_stereo_camera_calibration_load_v1()

bool t_stereo_camera_calibration_load_v1 ( FILE *  calib_file,
struct t_stereo_camera_calibration **  out_data 
)

◆ t_stereo_camera_calibration_reference()

static void t_stereo_camera_calibration_reference ( struct t_stereo_camera_calibration **  dst,
struct t_stereo_camera_calibration src 
)
related

Update the reference counts on a stereo calibration data(s).

Parameters
dstPointer to a object reference, if the object reference is non-null will decrement it's counter. The reference that dst points to will be set to src.
[in]srcObject to be have it's refcount increased dst is set to this.

References data, t_stereo_camera_calibration::reference, t_stereo_camera_calibration_destroy(), t_stereo_camera_calibration_load_v1(), t_stereo_camera_calibration_save_v1(), xrt_reference_dec(), and xrt_reference_inc().

Referenced by t_stereo_camera_calibration_alloc().

◆ t_stereo_camera_calibration_save_v1()

bool t_stereo_camera_calibration_save_v1 ( FILE *  calib_file,
struct t_stereo_camera_calibration data 
)

#include <auxiliary/tracking/t_tracking.h>

Save the given stereo calibration data to the given file.

References write_cv_mat().

Referenced by save_calibration(), and t_stereo_camera_calibration::t_stereo_camera_calibration_reference().