The open source OpenXR runtime
1/* Copyright 2021 Jan Schmidt
2 * SPDX-License-Identifier: BSL-1.0
3 */
4/*!
5 * @file
6 * @brief WMR and MS HoloLens configuration structures
7 * @author Jan Schmidt <jan@centricular.com>
8 * @ingroup drv_wmr
9 */
10
11#pragma once
12
13#include "math/m_vec2.h"
14#include "math/m_vec3.h"
15
16#include "util/u_logging.h"
17#include "util/u_distortion_mesh.h"
18
19/* Increase this number if anyone releases a headset with
20 * more cameras */
21#define WMR_MAX_CAMERAS 4
22
23/* Increase this number if anyone releases a controller with
24 * more tracking LEDs */
25#define WMR_MAX_LEDS 40
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31enum wmr_distortion_model
32{
33 WMR_DISTORTION_MODEL_UNKNOWN = 0,
34 WMR_DISTORTION_MODEL_POLYNOMIAL_3K,
35 WMR_DISTORTION_MODEL_POLYNOMIAL_6KT,
36};
37
38/* Location is used as camera_id for setting gain */
39enum wmr_camera_location
40{
41 WMR_CAMERA_LOCATION_HT0 = 0,
42 WMR_CAMERA_LOCATION_HT1 = 1,
43 WMR_CAMERA_LOCATION_DO0 = 2,
44 WMR_CAMERA_LOCATION_DO1 = 3,
45 WMR_CAMERA_LOCATION_HT2 = 4,
46 WMR_CAMERA_LOCATION_HT3 = 5,
47};
48
49enum wmr_camera_purpose
50{
51 WMR_CAMERA_PURPOSE_HEAD_TRACKING,
52 WMR_CAMERA_PURPOSE_DISPLAY_OBSERVER,
53};
54
55struct wmr_distortion_6KT
56{
57 enum wmr_distortion_model model;
58
59 /* The config provides 15 float values: */
60 union {
61 struct
62 {
63 float cx, cy; /* Principal point */
64 float fx, fy; /* Focal length */
65 float k[6]; /* Radial distortion coefficients */
66 float dist_x, dist_y; /* Center of distortion */
67 float p2, p1; /* Tangential distortion parameters */
68 float metric_radius; /* Metric radius */
69 } params;
70 float v[15];
71 };
72};
73
74struct wmr_distortion_eye_config
75{
76 struct xrt_vec3 translation; //!< Raw translation (to HT0)
77 struct xrt_matrix_3x3 rotation; //!< Raw rotation (to HT0), row major
78 struct xrt_pose pose; //!< Pose from `translation` and `rotation`
79
80 /* Radius of the (undistorted) visible area from the center (pixels) (I think) */
81 double visible_radius;
82
83 /* Width, Height (pixels) of the full display */
84 struct xrt_vec2 display_size;
85 /* Center for the eye viewport visibility (pixels) */
86 struct xrt_vec2 visible_center;
87
88 struct u_poly_3k_eye_values poly_3k; //!< Distortion parameters for each channel
89};
90
91struct wmr_camera_config
92{
93 enum wmr_camera_location location;
94 enum wmr_camera_purpose purpose;
95
96 struct xrt_rect roi;
97
98 struct xrt_vec3 translation; //!< Raw translation (to HT0)
99 struct xrt_matrix_3x3 rotation; //!< Raw rotation (to HT0), row major
100 struct xrt_pose pose; //!< Pose from `translation` and `rotation`
101
102 struct wmr_distortion_6KT distortion6KT;
103};
104
105/* Configuration for a single inertial sensor */
106struct wmr_inertial_sensor_config
107{
108 struct xrt_vec3 translation; //!< Raw translation (to HT0). Usually non-zero only on accelerometers.
109 struct xrt_matrix_3x3 rotation; //!< Raw rotation (to HT0), row major
110 struct xrt_pose pose; //!< Pose from `translation` and `rotation`
111
112 /* Current bias and mix matrix extracted from
113 * the configuration, which provides coefficients
114 * for temperature adjustments - but they're always 0,
115 * so we just take the constant coefficient */
116 struct xrt_vec3 bias_offsets;
117 struct xrt_matrix_3x3 mix_matrix;
118
119 //! Bias random walk variance. @see slam_tracker::inertial_calibration.
120 struct xrt_vec3 bias_var;
121
122 //! Measurement noise standard deviation. @see slam_tracker::inertial_calibration.
123 struct xrt_vec3 noise_std;
124};
125
126/* Precomputed transforms to convert between OpenXR and WMR coordinate systems */
127struct wmr_sensor_transforms_config
128{
129 struct xrt_pose P_oxr_acc; //!< Converts accel samples into OpenXR coordinates
130 struct xrt_pose P_oxr_gyr; //!< Converts gyro samples into OpenXR coordinates
131 struct xrt_pose P_ht0_me; //!< ME="middle of the eyes". HT0-to-ME transform but in OpenXR coordinates
132 struct xrt_pose P_imu_me; //!< IMU=accel. IMU-to-ME transform but in OpenXR coordinates
133};
134
135/* Configuration for the set of inertial sensors */
136struct wmr_inertial_sensors_config
137{
138 struct wmr_inertial_sensor_config accel;
139 struct wmr_inertial_sensor_config gyro;
140 struct wmr_inertial_sensor_config mag;
141
142 struct wmr_sensor_transforms_config transforms;
143};
144
145struct wmr_led_config
146{
147 struct xrt_vec3 pos;
148 struct xrt_vec3 norm;
149};
150
151struct wmr_hmd_config
152{
153 /* Left and Right eye mapping and distortion params */
154 struct wmr_distortion_eye_config eye_params[2];
155
156 struct wmr_inertial_sensors_config sensors;
157
158 int cam_count;
159 struct wmr_camera_config cams[WMR_MAX_CAMERAS];
160
161 struct wmr_camera_config *tcams[WMR_MAX_CAMERAS]; //!< Pointers to tracking cameras in `cameras`
162 int tcam_count; //!< Number of tracking cameras
163 int slam_cam_count; //!< Number of tracking cameras to use for SLAM
164};
165
166bool
167wmr_hmd_config_parse(struct wmr_hmd_config *c, char *json_string, enum u_logging_level log_level);
168
169
170struct wmr_controller_config
171{
172 struct wmr_inertial_sensors_config sensors;
173
174 int led_count;
175 struct wmr_led_config leds[WMR_MAX_LEDS];
176};
177
178bool
179wmr_controller_config_parse(struct wmr_controller_config *c, char *json_string, enum u_logging_level log_level);
180
181void
182wmr_config_precompute_transforms(struct wmr_inertial_sensors_config *sensors,
183 struct wmr_distortion_eye_config *eye_params);
184
185#ifdef __cplusplus
186}
187#endif