acc_detector_presence_processing.h
Go to the documentation of this file.
1 // Copyright (c) Acconeer AB, 2022-2025
2 // All rights reserved
3
4 #ifndef ACC_DETECTOR_PRESENCE_PROCESSING_H_
5 #define ACC_DETECTOR_PRESENCE_PROCESSING_H_
6
7 #include <stdbool.h>
8 #include <stdint.h>
9
10 #include "acc_config.h"
11 #include "acc_definitions_common.h"
12
13 /**
14 * @brief Presence detector handle container
15 */
16 struct acc_detector_presence_processing_handle;
17
18 typedef struct acc_detector_presence_processing_handle acc_detector_presence_processing_handle_t;
19
20 /**
21 * @brief Presence processing configuration container
22 */
23 struct acc_detector_presence_processing_config;
24
25 typedef struct acc_detector_presence_processing_config acc_detector_presence_processing_config_t;
26
27 /**
28 * @brief Presence detector results container
29 */
30 typedef struct
31 {
32 bool presence_detected;
33 float intra_presence_score;
34 float inter_presence_score;
35 float presence_distance;
36 float *depthwise_intra_presence_scores;
37 float *depthwise_inter_presence_scores;
38 uint32_t depthwise_presence_scores_length;
39 } acc_detector_presence_processing_result_t;
40
41 /**
42 * @brief Get the buffer size needed for presence processing
43 *
44 * @param[in] sensor_config Sensor config to get size for
45 * @return The buffer size
46 */
47 uint32_t acc_detector_presence_processing_get_buffer_size(const acc_config_t *sensor_config);
48
49 /**
50 * @brief Create a configuration for a presence processor
51 *
52 * @return Presence processor configuration, NULL if creation was not possible
53 */
54 acc_detector_presence_processing_config_t *acc_detector_presence_processing_config_create(void);
55
56 /**
57 * @brief Destroy a presence processor configuration
58 *
59 * @param[in] processor_config The configuration to destroy
60 */
61 void acc_detector_presence_processing_config_destroy(acc_detector_presence_processing_config_t *processor_config);
62
63 /**
64 * @brief Create a processing handle with the provided base configuration
65 *
66 * @param[in] processing_config The presence processing configuration to create a processing handle with
67 * @param[in] sensor_config The sensor config to create a processing handle with
68 * @return processing handle, NULL if creation was not possible
69 */
70 acc_detector_presence_processing_handle_t *acc_detector_presence_processing_create(const acc_detector_presence_processing_config_t *processing_config,
71 const acc_config_t *sensor_config);
72
73 /**
74 * @brief Destroy a processing handle
75 *
76 * @param[in] processing_handle A reference to the processing handle to destroy
77 */
78 void acc_detector_presence_processing_destroy(acc_detector_presence_processing_handle_t *processing_handle);
79
80 /**
81 * @brief Reset existing processing buffers
82 *
83 * @param[in] processing_handle A reference to the processing handle to reset existing processing buffers for
84 * @return true if successful, false otherwise
85 */
86
87 bool acc_detector_presence_processing_reset(acc_detector_presence_processing_handle_t *processing_handle);
88
89 /**
90 * @brief Process sensor data
91 *
92 * This function process the sensor data and tries to find presence.
93 *
94 * @param[in] processing_handle The presence detector processing handle to get the next result for
95 * @param[in] buffer Working memory for process, must be at least 32-bit aligned
96 * @param[in] frame The radar data to be processed, must be of the length provided at processing creation
97 * @param[out] presence_result The result container with presence information for the user
98 * @return true if successful, false otherwise
99 */
100 bool acc_detector_presence_processing_process(acc_detector_presence_processing_handle_t *processing_handle,
101 void *buffer,
102 const acc_int16_complex_t *frame,
103 acc_detector_presence_processing_result_t *presence_result);
104
105 /**
106 * @brief Set the frame rate
107 *
108 * See @ref acc_config_frame_rate_set for details
109 *
110 * @param[in] processing_config The configuration
111 * @param[in] frame_rate Frame rate in Hz. Must be > 0
112 */
113 void acc_detector_presence_processing_config_frame_rate_set(acc_detector_presence_processing_config_t *processing_config, float frame_rate);
114
115 /**
116 * @brief Get the frame rate
117 *
118 * See @ref acc_detector_presence_config_frame_rate_set
119 *
120 * @param[in] processing_config The configuration
121 * @return Frame rate in Hz
122 */
123 float acc_detector_presence_processing_config_frame_rate_get(const acc_detector_presence_processing_config_t *processing_config);
124
125 /**
126 * @brief Set the inter-frame presence timeout in seconds
127 *
128 * Number of seconds the inter-frame presence score needs to decrease before exponential
129 * scaling starts for faster decline. Should be between 0 and 30 where 0 means no timeout
130 *
131 * @param[in] processing_config The configuration
132 * @param[in] inter_frame_presence_timeout Timeout in seconds between 0 and 30
133 */
134 void acc_detector_presence_processing_config_inter_frame_presence_timeout_set(acc_detector_presence_processing_config_t *processing_config,
135 uint16_t inter_frame_presence_timeout);
136
137 /**
138 * @brief Get the inter-frame presence timeout in seconds
139 *
140 * See @ref acc_detector_presence_processing_config_inter_frame_presence_timeout_set
141 *
142 * @param[in] processing_config The configuration
143 * @return Inter-frame presence timeout in s
144 */
145 uint16_t acc_detector_presence_processing_config_inter_frame_presence_timeout_get(const acc_detector_presence_processing_config_t *processing_config);
146
147 /**
148 * @brief Set intra-frame presence detection
149 *
150 * This is used for detecting faster movements inside frames
151 *
152 * @param[in] processing_config The configuration to set intra-frame detection for
153 * @param[in] enable true if intra-frame detection should be enabled
154 */
155 void acc_detector_presence_processing_config_intra_detection_set(acc_detector_presence_processing_config_t *processing_config, bool enable);
156
157 /**
158 * @brief Get if frame intra-frame presence detection is enabled
159 *
160 * See @ref acc_detector_presence_processing_config_intra_detection_set
161 *
162 * @param[in] processing_config The configuration to get intra detection for
163 * @return true if intra-frame detection is enabled, false otherwise
164 */
165 bool acc_detector_presence_processing_config_intra_detection_get(const acc_detector_presence_processing_config_t *processing_config);
166
167 /**
168 * @brief Set the detection threshold for the intra-frame presence detection
169 *
170 * This is the threshold for detecting faster movements inside frames
171 *
172 * @param[in] processing_config The configuration to set the detection threshold for
173 * @param[in] intra_detection_threshold The intra-frame detection threshold to set
174 */
175 void acc_detector_presence_processing_config_intra_detection_threshold_set(acc_detector_presence_processing_config_t *processing_config,
176 float intra_detection_threshold);
177
178 /**
179 * @brief Get the detection threshold for the intra-frame presence detection
180 *
181 * See @ref acc_detector_presence_processing_config_intra_detection_threshold_set
182 *
183 * @param[in] processing_config The configuration to get the detection threshold for
184 * @return The intra-frame detection threshold
185 */
186 float acc_detector_presence_processing_config_intra_detection_threshold_get(const acc_detector_presence_processing_config_t *processing_config);
187
188 /**
189 * @brief Set inter-frame presence detection
190 *
191 * This is used for detecting slower movements between frames
192 *
193 * @param[in] processing_config The configuration to set inter-frame detection for
194 * @param[in] enable true if inter-frame presence detection should be enabled
195 */
196 void acc_detector_presence_processing_config_inter_detection_set(acc_detector_presence_processing_config_t *processing_config, bool enable);
197
198 /**
199 * @brief Get if inter-frame presence detection is enabled
200 *
201 * See @ref acc_detector_presence_processing_config_inter_detection_set
202 *
203 * @param[in] processing_config The configuration to get inter-frame presence detection for
204 * @return true if inter-frame presence detection is enabled, false otherwise
205 */
206 bool acc_detector_presence_processing_config_inter_detection_get(const acc_detector_presence_processing_config_t *processing_config);
207
208 /**
209 * @brief Set the detection threshold for the inter-frame presence detection
210 *
211 * This is the threshold for detecting slower movements between frames
212 *
213 * @param[in] processing_config The configuration to set the detection threshold for
214 * @param[in] inter_detection_threshold The threshold
215 */
216 void acc_detector_presence_processing_config_inter_detection_threshold_set(acc_detector_presence_processing_config_t *processing_config,
217 float inter_detection_threshold);
218
219 /**
220 * @brief Get the detection threshold for the inter-frame presence detection
221 *
222 * See @ref acc_detector_presence_processing_config_inter_detection_threshold_set
223 *
224 * @param[in] processing_config The configuration to get the detection threshold for
225 * @return detection threshold
226 */
227 float acc_detector_presence_processing_config_inter_detection_threshold_get(const acc_detector_presence_processing_config_t *processing_config);
228
229 /**
230 * @brief Set the time constant of the low pass filter for the inter-frame deviation between fast and slow
231 *
232 * @param[in] processing_config The configuration
233 * @param[in] inter_frame_deviation_time_const Time constant to set
234 */
235 void acc_detector_presence_processing_config_inter_frame_deviation_time_const_set(acc_detector_presence_processing_config_t *processing_config,
236 float inter_frame_deviation_time_const);
237
238 /**
239 * @brief Get the time constant of the low pass filter for the inter-frame deviation between fast and slow
240 *
241 * @param[in] processing_config The configuration to get the time constant for
242 * @return time constant in s
243 */
244 float acc_detector_presence_processing_config_inter_frame_deviation_time_const_get(
245 const acc_detector_presence_processing_config_t *processing_config);
246
247 /**
248 * @brief Set the cutoff frequency of the low pass filter for the fast filtered absolute sweep mean
249 *
250 * No filtering is applied if the cutoff is set over half the frame rate (Nyquist limit).
251 *
252 * @param[in] processing_config The configuration
253 * @param[in] inter_frame_fast_cutoff Cutoff frequency to set
254 */
255 void acc_detector_presence_processing_config_inter_frame_fast_cutoff_set(acc_detector_presence_processing_config_t *processing_config,
256 float inter_frame_fast_cutoff);
257
258 /**
259 * @brief Get the cutoff frequency of the low pass filter for the fast filtered absolute sweep mean
260 *
261 * @param[in] processing_config The configuration to get the cutoff frequency for
262 * @return the cutoff frequency in Hz
263 */
264 float acc_detector_presence_processing_config_inter_frame_fast_cutoff_get(const acc_detector_presence_processing_config_t *processing_config);
265
266 /**
267 * @brief Set the cutoff frequency of the low pass filter for the slow filtered absolute sweep mean
268 *
269 * @param[in] processing_config The configuration
270 * @param[in] inter_frame_slow_cutoff Cutoff frequency to set
271 */
272 void acc_detector_presence_processing_config_inter_frame_slow_cutoff_set(acc_detector_presence_processing_config_t *processing_config,
273 float inter_frame_slow_cutoff);
274
275 /**
276 * @brief Get the cutoff frequency of the low pass filter for the slow filtered absolute sweep mean
277 *
278 * @param[in] processing_config The configuration to get the cutoff frequency for
279 * @return the cutoff frequency in Hz
280 */
281 float acc_detector_presence_processing_config_inter_frame_slow_cutoff_get(const acc_detector_presence_processing_config_t *processing_config);
282
283 /**
284 * @brief Set the time constant for the depthwise filtering in the intra-frame part
285 *
286 * @param[in] processing_config The configuration
287 * @param[in] intra_frame_time_const Time constant to set
288 */
289 void acc_detector_presence_processing_config_intra_frame_time_const_set(acc_detector_presence_processing_config_t *processing_config,
290 float intra_frame_time_const);
291
292 /**
293 * @brief Get the time constant for the depthwise filtering in the intra-frame part
294 *
295 * @param[in] processing_config The configuration to get the time constant for
296 * @return time constant in s
297 */
298 float acc_detector_presence_processing_config_intra_frame_time_const_get(const acc_detector_presence_processing_config_t *processing_config);
299
300 /**
301 * @brief Set the time constant for the output in the intra-frame part
302 *
303 * @param[in] processing_config The configuration
304 * @param[in] intra_output_time_const Time constant to set
305 */
306 void acc_detector_presence_processing_config_intra_output_time_const_set(acc_detector_presence_processing_config_t *processing_config,
307 float intra_output_time_const);
308
309 /**
310 * @brief Get the time constant for the output in the intra-frame part
311 *
312 * @param[in] processing_config The configuration to get the time constant for
313 * @return time constant in s
314 */
315 float acc_detector_presence_processing_config_intra_output_time_const_get(const acc_detector_presence_processing_config_t *processing_config);
316
317 /**
318 * @brief Set the time constant for the output in the inter-frame part
319 *
320 * @param[in] processing_config The configuration
321 * @param[in] inter_output_time_const Time constant to set
322 */
323 void acc_detector_presence_processing_config_inter_output_time_const_set(acc_detector_presence_processing_config_t *processing_config,
324 float inter_output_time_const);
325
326 /**
327 * @brief Get the time constant for the output in the inter-frame part
328 *
329 * @param[in] processing_config The configuration to get the time constant for
330 * @return time constant in s
331 */
332 float acc_detector_presence_processing_config_inter_output_time_const_get(const acc_detector_presence_processing_config_t *processing_config);
333
334 #endif
acc_detector_presence_processing_create
acc_detector_presence_processing_handle_t * acc_detector_presence_processing_create(const acc_detector_presence_processing_config_t *processing_config, const acc_config_t *sensor_config)
Create a processing handle with the provided base configuration.
acc_detector_presence_processing_config_destroy
void acc_detector_presence_processing_config_destroy(acc_detector_presence_processing_config_t *processor_config)
Destroy a presence processor configuration.
acc_detector_presence_processing_config_frame_rate_get
float acc_detector_presence_processing_config_frame_rate_get(const acc_detector_presence_processing_config_t *processing_config)
Get the frame rate.
acc_detector_presence_processing_config_t
struct acc_detector_presence_processing_config acc_detector_presence_processing_config_t
Definition: acc_detector_presence_processing.h:25
acc_detector_presence_processing_config_inter_frame_fast_cutoff_set
void acc_detector_presence_processing_config_inter_frame_fast_cutoff_set(acc_detector_presence_processing_config_t *processing_config, float inter_frame_fast_cutoff)
Set the cutoff frequency of the low pass filter for the fast filtered absolute sweep mean.
buffer
void * buffer
Definition: i2c_example_cargo.c:40
acc_detector_presence_processing_result_t::depthwise_intra_presence_scores
float * depthwise_intra_presence_scores
Definition: acc_detector_presence_processing.h:36
acc_detector_presence_processing_config_intra_detection_get
bool acc_detector_presence_processing_config_intra_detection_get(const acc_detector_presence_processing_config_t *processing_config)
Get if frame intra-frame presence detection is enabled.
acc_int16_complex_t
Data type for interger-based representation of complex numbers.
Definition: acc_definitions_common.h:40
acc_detector_presence_processing_config_inter_frame_slow_cutoff_get
float acc_detector_presence_processing_config_inter_frame_slow_cutoff_get(const acc_detector_presence_processing_config_t *processing_config)
Get the cutoff frequency of the low pass filter for the slow filtered absolute sweep mean.
acc_detector_presence_processing_config_inter_frame_presence_timeout_set
void acc_detector_presence_processing_config_inter_frame_presence_timeout_set(acc_detector_presence_processing_config_t *processing_config, uint16_t inter_frame_presence_timeout)
Set the inter-frame presence timeout in seconds.
acc_detector_presence_processing_result_t::depthwise_inter_presence_scores
float * depthwise_inter_presence_scores
Definition: acc_detector_presence_processing.h:37
acc_detector_presence_processing_reset
bool acc_detector_presence_processing_reset(acc_detector_presence_processing_handle_t *processing_handle)
Reset existing processing buffers.
acc_detector_presence_processing_handle_t
struct acc_detector_presence_processing_handle acc_detector_presence_processing_handle_t
Definition: acc_detector_presence_processing.h:18
acc_detector_presence_processing_result_t::presence_distance
float presence_distance
Definition: acc_detector_presence_processing.h:35
acc_detector_presence_processing_config_inter_output_time_const_set
void acc_detector_presence_processing_config_inter_output_time_const_set(acc_detector_presence_processing_config_t *processing_config, float inter_output_time_const)
Set the time constant for the output in the inter-frame part.
acc_detector_presence_processing_config_inter_frame_deviation_time_const_get
float acc_detector_presence_processing_config_inter_frame_deviation_time_const_get(const acc_detector_presence_processing_config_t *processing_config)
Get the time constant of the low pass filter for the inter-frame deviation between fast and slow.
acc_detector_presence_processing_config_inter_detection_get
bool acc_detector_presence_processing_config_inter_detection_get(const acc_detector_presence_processing_config_t *processing_config)
Get if inter-frame presence detection is enabled.
acc_detector_presence_processing_config_inter_detection_set
void acc_detector_presence_processing_config_inter_detection_set(acc_detector_presence_processing_config_t *processing_config, bool enable)
Set inter-frame presence detection.
acc_detector_presence_processing_config_frame_rate_set
void acc_detector_presence_processing_config_frame_rate_set(acc_detector_presence_processing_config_t *processing_config, float frame_rate)
Set the frame rate.
acc_detector_presence_processing_destroy
void acc_detector_presence_processing_destroy(acc_detector_presence_processing_handle_t *processing_handle)
Destroy a processing handle.
acc_config_t
struct acc_config acc_config_t
Definition: acc_config.h:24
acc_detector_presence_processing_config_intra_output_time_const_get
float acc_detector_presence_processing_config_intra_output_time_const_get(const acc_detector_presence_processing_config_t *processing_config)
Get the time constant for the output in the intra-frame part.
acc_detector_presence_processing_config_inter_output_time_const_get
float acc_detector_presence_processing_config_inter_output_time_const_get(const acc_detector_presence_processing_config_t *processing_config)
Get the time constant for the output in the inter-frame part.
acc_detector_presence_processing_config_create
acc_detector_presence_processing_config_t * acc_detector_presence_processing_config_create(void)
Create a configuration for a presence processor.
acc_detector_presence_processing_config_inter_frame_fast_cutoff_get
float acc_detector_presence_processing_config_inter_frame_fast_cutoff_get(const acc_detector_presence_processing_config_t *processing_config)
Get the cutoff frequency of the low pass filter for the fast filtered absolute sweep mean.
acc_detector_presence_processing_config_intra_detection_set
void acc_detector_presence_processing_config_intra_detection_set(acc_detector_presence_processing_config_t *processing_config, bool enable)
Set intra-frame presence detection.
acc_detector_presence_processing_config_intra_detection_threshold_set
void acc_detector_presence_processing_config_intra_detection_threshold_set(acc_detector_presence_processing_config_t *processing_config, float intra_detection_threshold)
Set the detection threshold for the intra-frame presence detection.
acc_detector_presence_processing_process
bool acc_detector_presence_processing_process(acc_detector_presence_processing_handle_t *processing_handle, void *buffer, const acc_int16_complex_t *frame, acc_detector_presence_processing_result_t *presence_result)
Process sensor data.
acc_detector_presence_processing_config_inter_frame_presence_timeout_get
uint16_t acc_detector_presence_processing_config_inter_frame_presence_timeout_get(const acc_detector_presence_processing_config_t *processing_config)
Get the inter-frame presence timeout in seconds.
acc_detector_presence_processing_config_intra_frame_time_const_get
float acc_detector_presence_processing_config_intra_frame_time_const_get(const acc_detector_presence_processing_config_t *processing_config)
Get the time constant for the depthwise filtering in the intra-frame part.
acc_detector_presence_processing_result_t::presence_detected
bool presence_detected
Definition: acc_detector_presence_processing.h:32
acc_detector_presence_processing_result_t::intra_presence_score
float intra_presence_score
Definition: acc_detector_presence_processing.h:33
acc_detector_presence_processing_result_t
Presence detector results container.
Definition: acc_detector_presence_processing.h:30
acc_definitions_common.h
acc_detector_presence_processing_result_t::inter_presence_score
float inter_presence_score
Definition: acc_detector_presence_processing.h:34
acc_config.h
acc_detector_presence_processing_config_inter_detection_threshold_get
float acc_detector_presence_processing_config_inter_detection_threshold_get(const acc_detector_presence_processing_config_t *processing_config)
Get the detection threshold for the inter-frame presence detection.
acc_detector_presence_processing_config_intra_frame_time_const_set
void acc_detector_presence_processing_config_intra_frame_time_const_set(acc_detector_presence_processing_config_t *processing_config, float intra_frame_time_const)
Set the time constant for the depthwise filtering in the intra-frame part.
acc_detector_presence_processing_config_intra_output_time_const_set
void acc_detector_presence_processing_config_intra_output_time_const_set(acc_detector_presence_processing_config_t *processing_config, float intra_output_time_const)
Set the time constant for the output in the intra-frame part.
acc_detector_presence_processing_config_inter_frame_deviation_time_const_set
void acc_detector_presence_processing_config_inter_frame_deviation_time_const_set(acc_detector_presence_processing_config_t *processing_config, float inter_frame_deviation_time_const)
Set the time constant of the low pass filter for the inter-frame deviation between fast and slow.
acc_detector_presence_processing_config_inter_frame_slow_cutoff_set
void acc_detector_presence_processing_config_inter_frame_slow_cutoff_set(acc_detector_presence_processing_config_t *processing_config, float inter_frame_slow_cutoff)
Set the cutoff frequency of the low pass filter for the slow filtered absolute sweep mean.
acc_detector_presence_processing_config_intra_detection_threshold_get
float acc_detector_presence_processing_config_intra_detection_threshold_get(const acc_detector_presence_processing_config_t *processing_config)
Get the detection threshold for the intra-frame presence detection.
acc_detector_presence_processing_result_t::depthwise_presence_scores_length
uint32_t depthwise_presence_scores_length
Definition: acc_detector_presence_processing.h:38
acc_detector_presence_processing_get_buffer_size
uint32_t acc_detector_presence_processing_get_buffer_size(const acc_config_t *sensor_config)
Get the buffer size needed for presence processing.
acc_detector_presence_processing_config_inter_detection_threshold_set
void acc_detector_presence_processing_config_inter_detection_threshold_set(acc_detector_presence_processing_config_t *processing_config, float inter_detection_threshold)
Set the detection threshold for the inter-frame presence detection.