The open source OpenXR runtime
a/math: Improve comments for one euro filter
authored by
Ryan Pavlik
and committed by
Jakob Bornecrantz
534d2e9f
8f02541c
+130
-10
+130
-10
src/xrt/auxiliary/math/m_filter_one_euro.h
+130
-10
src/xrt/auxiliary/math/m_filter_one_euro.h
···
1
-
// Copyright 2021, Collabora, Ltd.
1
+
// Copyright 2021-2023, Collabora, Ltd.
2
2
// Copyright 2021, Jan Schmidt
3
3
// SPDX-License-Identifier: BSL-1.0
4
4
/*!
···
32
32
extern "C" {
33
33
#endif
34
34
35
-
/**
35
+
/*!
36
36
* @brief Base data type for One Euro filter instances.
37
+
*
38
+
* @ingroup aux_math
37
39
*/
38
40
struct m_filter_one_euro_base
39
41
{
···
53
55
uint64_t prev_ts;
54
56
};
55
57
58
+
/*!
59
+
* @brief One Euro filter for a single float measurement.
60
+
*
61
+
* @ingroup aux_math
62
+
*/
56
63
struct m_filter_euro_f32
57
64
{
58
65
/** Base/common data */
59
66
struct m_filter_one_euro_base base;
60
67
61
-
/** The previous sample */
68
+
/** The most recent measurement, after filtering. */
62
69
double prev_y;
63
70
64
-
/** The previous sample derivative */
71
+
/** The most recent sample derivative, after filtering. */
65
72
double prev_dy;
66
73
};
67
74
75
+
/*!
76
+
* @brief One Euro filter for a 2D float measurement.
77
+
*
78
+
* @ingroup aux_math
79
+
*/
68
80
struct m_filter_euro_vec2
69
81
{
70
82
/** Base/common data */
71
83
struct m_filter_one_euro_base base;
72
84
73
-
/** The previous sample */
85
+
/** The most recent measurement, after filtering. */
74
86
struct xrt_vec2 prev_y;
75
87
76
-
/** The previous sample derivative */
88
+
/** The most recent sample derivative, after filtering. */
77
89
struct xrt_vec2 prev_dy;
78
90
};
79
91
92
+
/*!
93
+
* @brief One Euro filter for a 3D float measurement.
94
+
*
95
+
* @ingroup aux_math
96
+
*/
80
97
struct m_filter_euro_vec3
81
98
{
82
99
/** Base/common data */
83
100
struct m_filter_one_euro_base base;
84
101
85
-
/** The previous sample */
102
+
/** The most recent measurement, after filtering. */
86
103
struct xrt_vec3 prev_y;
87
104
88
-
/** The previous sample derivative */
105
+
/** The most recent sample derivative, after filtering. */
89
106
struct xrt_vec3 prev_dy;
90
107
};
91
108
109
+
110
+
/*!
111
+
* @brief One Euro filter for a unit quaternion (used as 3D rotation).
112
+
*
113
+
* @ingroup aux_math
114
+
*/
92
115
struct m_filter_euro_quat
93
116
{
94
117
/** Base/common data */
95
118
struct m_filter_one_euro_base base;
96
119
97
-
/** The previous sample */
120
+
/** The most recent measurement, after filtering. */
98
121
struct xrt_quat prev_y;
99
122
100
-
/** The previous sample derivative */
123
+
/** The most recent sample derivative, after filtering. */
101
124
struct xrt_quat prev_dy;
102
125
};
103
126
127
+
/**
128
+
* @brief Initialize a 1D filter
129
+
*
130
+
* @param f self pointer
131
+
* @param fc_min Minimum frequency cutoff for filter
132
+
* @param fc_min_d Minimum frequency cutoff for derivative filter
133
+
* @param beta Beta value for "responsiveness" of filter
134
+
*
135
+
* @public @memberof m_filter_euro_f32
136
+
*/
104
137
void
105
138
m_filter_euro_f32_init(struct m_filter_euro_f32 *f, double fc_min, double fc_min_d, double beta);
139
+
140
+
/**
141
+
* @brief Filter a measurement and commit changes to filter state
142
+
*
143
+
* @param[in,out] f self pointer
144
+
* @param ts measurement timestamp
145
+
* @param in_y raw measurement
146
+
* @param[out] out_y filtered measurement
147
+
*
148
+
* @public @memberof m_filter_euro_f32
149
+
*/
106
150
void
107
151
m_filter_euro_f32_run(struct m_filter_euro_f32 *f, uint64_t ts, const float *in_y, float *out_y);
108
152
153
+
/**
154
+
* @brief Initialize a 2D filter
155
+
*
156
+
* @param f self pointer
157
+
* @param fc_min Minimum frequency cutoff for filter
158
+
* @param beta Beta value for "responsiveness" of filter
159
+
* @param fc_min_d Minimum frequency cutoff for derivative filter
160
+
*
161
+
* @public @memberof m_filter_euro_vec2
162
+
*/
109
163
void
110
164
m_filter_euro_vec2_init(struct m_filter_euro_vec2 *f, double fc_min, double fc_min_d, double beta);
165
+
166
+
/**
167
+
* @brief Filter a measurement and commit changes to filter state
168
+
*
169
+
* @param[in,out] f self pointer
170
+
* @param ts measurement timestamp
171
+
* @param in_y raw measurement
172
+
* @param[out] out_y filtered measurement
173
+
*
174
+
* @public @memberof m_filter_euro_vec2
175
+
*/
111
176
void
112
177
m_filter_euro_vec2_run(struct m_filter_euro_vec2 *f, uint64_t ts, const struct xrt_vec2 *in_y, struct xrt_vec2 *out_y);
178
+
179
+
/**
180
+
* @brief Filter a measurement **without** committing changes to filter state
181
+
*
182
+
* Similar to @ref m_filter_euro_vec2_run but @p f is not modified.
183
+
*
184
+
* @param[in] f self pointer
185
+
* @param ts measurement timestamp
186
+
* @param in_y raw measurement
187
+
* @param[out] out_y filtered measurement
188
+
*
189
+
* @public @memberof m_filter_euro_vec2
190
+
*/
113
191
void
114
192
m_filter_euro_vec2_run_no_commit(struct m_filter_euro_vec2 *f,
115
193
uint64_t ts,
116
194
const struct xrt_vec2 *in_y,
117
195
struct xrt_vec2 *out_y);
118
196
197
+
/**
198
+
* @brief Initialize a 3D filter
199
+
*
200
+
* @param f self pointer
201
+
* @param fc_min Minimum frequency cutoff for filter
202
+
* @param fc_min_d Minimum frequency cutoff for derivative filter
203
+
* @param beta Beta value for "responsiveness" of filter
204
+
*
205
+
* @public @memberof m_filter_euro_vec3
206
+
*/
119
207
void
120
208
m_filter_euro_vec3_init(struct m_filter_euro_vec3 *f, double fc_min, double fc_min_d, double beta);
209
+
210
+
/**
211
+
* @brief Filter a measurement and commit changes to filter state
212
+
*
213
+
* @param[in,out] f self pointer
214
+
* @param ts measurement timestamp
215
+
* @param in_y raw measurement
216
+
* @param[out] out_y filtered measurement
217
+
*
218
+
* @public @memberof m_filter_euro_vec3
219
+
*/
121
220
void
122
221
m_filter_euro_vec3_run(struct m_filter_euro_vec3 *f, uint64_t ts, const struct xrt_vec3 *in_y, struct xrt_vec3 *out_y);
123
222
223
+
/**
224
+
* @brief Initialize a unit quaternion (3D rotation) filter
225
+
*
226
+
* @param f self pointer
227
+
* @param fc_min Minimum frequency cutoff for filter
228
+
* @param fc_min_d Minimum frequency cutoff for derivative filter
229
+
* @param beta Beta value for "responsiveness" of filter
230
+
*
231
+
* @public @memberof m_filter_euro_quat
232
+
*/
124
233
void
125
234
m_filter_euro_quat_init(struct m_filter_euro_quat *f, double fc_min, double fc_min_d, double beta);
235
+
236
+
/**
237
+
* @brief Filter a measurement and commit changes to filter state
238
+
*
239
+
* @param[in,out] f self pointer
240
+
* @param ts measurement timestamp
241
+
* @param in_y raw measurement
242
+
* @param[out] out_y filtered measurement
243
+
*
244
+
* @public @memberof m_filter_euro_quat
245
+
*/
126
246
void
127
247
m_filter_euro_quat_run(struct m_filter_euro_quat *f, uint64_t ts, const struct xrt_quat *in_y, struct xrt_quat *out_y);
128
248