Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
spotter_camera_backend.c
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file spotter_camera_backend.c
20 * @brief Native Spottercam backend and optional C11 UART target-slot projection.
21 * @details Projects validated vehicle detections through a measured PANGEA_CAMERA_V1
22 * pinhole profile onto the five ranked geographic target slots (0..4 -> T1..T5)
23 * and publishes correlated USHER_CAM_POINT_UPDATE frames without Python helpers.
24 */
26#include "camera_profile.h"
27#include "coverage_scheduler.h"
28#include "spotter_cam_pipe.h"
30
31#include <errno.h>
32#include <math.h>
33#include <pthread.h>
34#include <stdio.h>
35#include <sys/eventfd.h>
36#include <unistd.h>
37
38#ifndef USHER_SODA
39 #define USHER_SODA "./bin/soda"
40#endif
41#ifndef USHER_AI_CAM_PHOTO_DIR
42 #define USHER_AI_CAM_PHOTO_DIR "~/Pictures/sensoraia"
43#endif
44#ifndef USHER_SPOTTERCAM_PHOTO_DIR
45 #define USHER_SPOTTERCAM_PHOTO_DIR USHER_AI_CAM_PHOTO_DIR
46#endif
47
48#define SPOTTER_POINT_QUEUE_CAPACITY 16U
49
50static pthread_mutex_t target_mutex = PTHREAD_MUTEX_INITIALIZER;
56static size_t pending_head;
57static size_t pending_count;
58static uint32_t last_admitted_shot;
59static int notification_fd = -1;
60
61/** @brief Clear the event hint while holding @c target_mutex.
62 * @details The result queue, not the event counter, owns pending work. Clear
63 * the counter only while producers are excluded and the queue is empty. */
65{
66 if (notification_fd < 0) return;
67 eventfd_t value;
68 int status;
69 do {
70 status = eventfd_read(notification_fd, &value);
71 } while (status < 0 && errno == EINTR);
72}
73
74/** @brief Wake the event loop after queuing a result under @c target_mutex.
75 * @details An eventfd wake is a readability hint, not a second result queue;
76 * a saturated counter already has the desired readable state. */
77static void notify_locked(void)
78{
79 if (notification_fd < 0) return;
80 const uint64_t increment = 1U;
81 ssize_t written;
82 do {
83 written = write(notification_fd, &increment, sizeof(increment));
84 } while (written < 0 && errno == EINTR);
85}
86
88{
89 struct usher_camera_profile candidate;
90 if (!filename || !filename[0] || !usher_camera_profile_read(filename, &candidate)
91 || candidate.camera_id != USHER_CAMERA_AICAM
92 || candidate.calibration.width < 2U || candidate.calibration.height < 2U) {
93 return false;
94 }
95 pthread_mutex_lock(&target_mutex);
96 target_profile = candidate;
98 pthread_mutex_unlock(&target_mutex);
99 return true;
100}
101
106
107/** @brief Reset target accumulation and prepare completion notification.
108 * @return Zero with a usable event descriptor, or -1 on eventfd failure.
109 * @details Reset shot ordering with the result ring so a prior stream's
110 * observations cannot be mistaken for this stream's output. */
111static int spotter_stream_init(void)
112{
113 pthread_mutex_lock(&target_mutex);
115 pending_head = 0U;
116 pending_count = 0U;
118 if (notification_fd < 0) {
119 notification_fd = eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC);
120 }
121 const int result = notification_fd >= 0 ? 0 : -1;
122 pthread_mutex_unlock(&target_mutex);
123 return result;
124}
125
126/** @brief Discard pending target results and close their notification channel.
127 * @details Serialize descriptor lifetime with producers so they cannot write
128 * to a closed or subsequently reused descriptor. */
129static void spotter_stream_drain(void)
130{
131 pthread_mutex_lock(&target_mutex);
132 pending_head = 0U;
133 pending_count = 0U;
134 if (notification_fd >= 0) {
136 notification_fd = -1;
137 }
138 pthread_mutex_unlock(&target_mutex);
139}
140
141/** @brief Get the stream's borrowed poll descriptor.
142 * @return Event descriptor, or -1 if the stream has none.
143 * @details The lock protects lookup, not the lifetime after return; the
144 * event-loop owner coordinates polling with teardown. */
146{
147 pthread_mutex_lock(&target_mutex);
148 const int fd = notification_fd;
149 pthread_mutex_unlock(&target_mutex);
150 return fd;
151}
152
153/** @brief Pop one queued Spottercam point.
154 * @param[out] result Destination, unchanged if no point is available.
155 * @return True when a point was copied.
156 * @details Keep the event descriptor readable while more points remain, and
157 * clear it under the producer lock once the last point is removed. */
159{
160 if (!result) return false;
161 bool available = false;
162 pthread_mutex_lock(&target_mutex);
163 if (pending_count > 0U) {
167 available = true;
168 }
169 if (pending_count == 0U) {
171 }
172 pthread_mutex_unlock(&target_mutex);
173 return available;
174}
175
176/** @brief Convert a saved image's detections into stream observations.
177 * @param filename Published JPEG used to locate matching detector evidence.
178 * @param shot Pose and photo number associated with that image.
179 * @details Reject non-increasing shot IDs and invalid evidence before
180 * updating the target store. Rescale intrinsics to the detection raster
181 * before projecting; these are flat-ground estimates, not surveyed positions. */
182static void spotter_image_saved(const char *filename, const union dc_shot_union *shot)
183{
184 if (!spotter_camera_backend_targets_enabled() || !filename || !shot || shot->data.nr <= 0) {
185 return;
186 }
187 const uint32_t frame_number = (uint32_t)shot->data.nr;
188 pthread_mutex_lock(&target_mutex);
189 if (frame_number <= last_admitted_shot
191 || parsed_detections.count == 0U
192 || parsed_detections.width < 2U || parsed_detections.width > 4096U
193 || parsed_detections.height < 2U || parsed_detections.height > 4096U) {
194 pthread_mutex_unlock(&target_mutex);
195 return;
196 }
197 struct coverage_camera camera = target_profile.calibration;
198 const double scale_x = (double)parsed_detections.width / (double)camera.width;
199 const double scale_y = (double)parsed_detections.height / (double)camera.height;
200 camera.fx *= scale_x;
201 camera.fy *= scale_y;
202 /* Preserve the principal point's pixel-center convention during resize. */
203 camera.cx = (camera.cx + 0.5) * scale_x - 0.5;
204 camera.cy = (camera.cy + 0.5) * scale_y - 0.5;
205 camera.width = parsed_detections.width;
206 camera.height = parsed_detections.height;
207
208 const double deg_per_rad = 57.29577951308232;
209 const double rad_per_deg = 0.017453292519943295;
210 const double earth_radius_m = 6378137.0;
211 const double agl_m = shot->data.groundalt > 0 ? shot->data.groundalt / 256.0 : shot->data.alt / 1000.0;
212 const struct coverage_pose pose = {
213 .latitude_deg = shot->data.lat / 1e7,
214 .longitude_deg = shot->data.lon / 1e7,
215 .agl_m = agl_m,
216 .roll_deg = shot->data.phi / 4096.0 * deg_per_rad,
217 .pitch_deg = shot->data.theta / 4096.0 * deg_per_rad,
218 .yaw_deg = shot->data.psi / 4096.0 * deg_per_rad,
219 .uncertainty_m = 0.0
220 };
221 const double cos_lat = cos(pose.latitude_deg * rad_per_deg);
222 if (!isfinite(cos_lat) || cos_lat <= 1e-6) {
223 pthread_mutex_unlock(&target_mutex);
224 return;
225 }
226
227 for (unsigned index = 0U; index < parsed_detections.count; ++index) {
228 const struct spotter_detection *box = &parsed_detections.objects[index];
229 const double cx = box->precise_center ? box->center_x : box->x + 0.5 * box->width;
230 const double cy = box->precise_center ? box->center_y : box->y + 0.5 * box->height;
231 struct coverage_point offset;
232 if (!coverage_project_pixel(&camera, &pose, cx, cy, &offset)) {
233 continue;
234 }
235 const double target_lat = pose.latitude_deg + (offset.north / earth_radius_m) * deg_per_rad;
236 const double target_lon = remainder(
237 pose.longitude_deg + (offset.east / (earth_radius_m * cos_lat)) * deg_per_rad, 360.0);
238 if (!isfinite(target_lat) || !isfinite(target_lon)
239 || fabs(target_lat) > 90.0 || fabs(target_lon) > 180.0) {
240 continue;
241 }
242 const long long lat_e7 = llround(target_lat * 1e7);
243 const long long lon_e7 = llround(target_lon * 1e7);
244 const long long ground_alt_mm = (long long)shot->data.alt - llround(agl_m * 1000.0);
245 const long long score = llround(box->confidence * 1000.0);
246 if ((lat_e7 == 0 && lon_e7 == 0) || score < 0 || score > 1000
247 || ground_alt_mm < INT32_MIN || ground_alt_mm > INT32_MAX) {
248 continue;
249 }
250 const struct spotter_target observation = {
251 .latitude = (int32_t)lat_e7,
252 .longitude = (int32_t)lon_e7,
253 .altitude_mm = (int32_t)ground_alt_mm,
254 .score = (uint16_t)score,
255 .valid = true
256 };
257 const int slot = spotter_targets_offer(&target_store, &observation, NULL, NULL);
258 if (slot < 0) {
259 continue;
260 }
261 last_admitted_shot = frame_number;
262 const struct camera_point_result update = {
263 .session_id = frame_number,
264 .valid = true,
265 .lat = observation.latitude,
266 .lon = observation.longitude,
267 .alt_mm = observation.altitude_mm,
268 .agl_mm = 0,
269 .quality = observation.score,
270 .metric = slot
271 };
274 pending_points[tail] = update;
276 } else {
279 }
281 printf("SPOTTER_TARGETS:\tshot %u assigned T%d lat=%.7f lon=%.7f score=%u\n",
282 frame_number, slot + 1, observation.latitude / 1e7, observation.longitude / 1e7,
283 (unsigned)observation.score);
284 break;
285 }
286 pthread_mutex_unlock(&target_mutex);
287}
288
290{
291 static const struct camera_point_stream_ops stream = {
292 .init = spotter_stream_init,
293 .poll_result = spotter_stream_poll_result,
294 .drain = spotter_stream_drain,
296 .completion_fd = spotter_stream_completion_fd
297 };
298 struct camera_backend backend = {
299 .name = "spottercam",
300 .init = spotter_cam_pipe_init,
301 .shoot = spotter_cam_pipe_shoot,
302 .deinit = spotter_cam_pipe_deinit,
303 .soda_application = USHER_SODA,
304 .configure = spotter_cam_pipe_configure,
305 .camera_id = USHER_CAMERA_AICAM,
306 .prefix = 'a',
307 .mock = {.width = 2028, .height = 1520, .filename_marker = "m"},
309 .soda_option = "--aicam",
310 .bind_frame = spotter_cam_pipe_bind_frame,
311 .detection_summary = spotter_cam_pipe_last_detection_summary,
312 .save_detection_copy = spotter_cam_pipe_save_detection_copy,
313 .photo_directory = USHER_SPOTTERCAM_PHOTO_DIR
314 };
316 backend.capabilities &= ~(CAMERA_CAP_DETECTION | CAMERA_CAP_FINISH_OWNED);
317 backend.soda_application = NULL;
318 backend.bind_frame = NULL;
319 backend.detection_summary = NULL;
320 backend.save_detection_copy = NULL;
321 } else if (target_profile_loaded) {
322 backend.image_saved = spotter_image_saved;
323 backend.point_stream = &stream;
324 }
325 return backend;
326}
@ CAMERA_CAP_FINISH_OWNED
@ CAMERA_CAP_IMAGE
@ CAMERA_CAP_PRIVATE_IMAGE
@ CAMERA_CAP_DETECTION
#define USHER_SODA
#define USHER_SPOTTERCAM_PHOTO_DIR
bool usher_camera_profile_read(const char *filename, struct usher_camera_profile *profile)
Read a bounded PANGEA_CAMERA_V1 key=value calibration file.
Public C API for reading PANGEA camera calibration profiles.
static double longitude
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
bool coverage_project_pixel(const struct coverage_camera *camera, const struct coverage_pose *pose, double column, double row, struct coverage_point *offset)
Project an image pixel onto the same ground plane as the coverage footprint.
Fixed-memory geometric coverage accounting, independent of camera I/O.
static size_t pending_head
static size_t pending_count
static pthread_cond_t available
Definition pose_log.c:73
int fd
Definition serial.c:39
void spotter_cam_pipe_deinit(void)
Stop the native camera process and clear detector-specific configuration.
bool spotter_cam_pipe_photo_only(void)
Report whether capture was configured without analysis.
void spotter_cam_pipe_last_detection_summary(char *buffer, size_t buffer_size)
Format the most recent shot's detection result for EXIF writing.
void spotter_cam_pipe_save_detection_copy(const char *filename)
Copy filename into a "detections" subdirectory of the photo directory if the last spotter_cam_pipe_sh...
void spotter_cam_pipe_configure(const struct camera_backend_host *host)
Borrow USHER's shutdown flag for both serialized native worker owners.
int spotter_cam_pipe_shoot(char *filename, size_t filename_size, int image_number)
Request one JPEG and, when enabled, parse its matching detection sidecar.
bool spotter_cam_pipe_bind_frame(uint64_t sequence, uint64_t sensor_timestamp_ns)
Reject a detection result whose identity differs from the validated saved frame.
bool spotter_cam_pipe_read_detections(const char *filename, struct spotter_detections *detections)
Read the full detector result associated with a JPEG.
int spotter_cam_pipe_init(const char *unused)
Start and qualify native persistent capture with the selected analysis policy.
Native USHER adapter for on-sensor detection or photo-only capture.
static int notification_fd
static void spotter_stream_drain(void)
Discard pending target results and close their notification channel.
static void notify_locked(void)
Wake the event loop after queuing a result under target_mutex.
static struct usher_camera_profile target_profile
static bool spotter_stream_poll_result(struct camera_point_result *result)
Pop one queued Spottercam point.
static void spotter_image_saved(const char *filename, const union dc_shot_union *shot)
Convert a saved image's detections into stream observations.
static struct spotter_detections parsed_detections
static void drain_notification_locked(void)
Clear the event hint while holding target_mutex.
static pthread_mutex_t target_mutex
static int spotter_stream_init(void)
Reset target accumulation and prepare completion notification.
static int spotter_stream_completion_fd(void)
Get the stream's borrowed poll descriptor.
static struct spotter_targets target_store
struct camera_backend spotter_camera_backend_get(void)
Build the Spottercam backend descriptor for the registry.
bool spotter_camera_backend_targets_enabled(void)
True when native Spottercam UART target projection is configured and active.
static bool target_profile_loaded
bool spotter_camera_backend_set_targets_profile(const char *filename)
Configure pinhole camera calibration for projecting Spottercam boxes to UART points.
#define SPOTTER_POINT_QUEUE_CAPACITY
static struct camera_point_result pending_points[SPOTTER_POINT_QUEUE_CAPACITY]
static uint32_t last_admitted_shot
Spottercam backend descriptor and optional native UART target projection.
void spotter_targets_reset(struct spotter_targets *targets)
Forget all prior assignments without manufacturing target coordinates.
int spotter_targets_offer(struct spotter_targets *targets, const struct spotter_target *observation, bool(*apply)(void *, unsigned, const struct spotter_target *), void *context)
Admit a target only after its owner's coordinate application succeeds.
Five ranked geographic targets, independent of navigation and camera transport.
Function table describing one backend's owned camera operations.
Repeated correlated point updates from saved photos or non-image work.
Measured pinhole calibration for the delivered image, including its mount.
unsigned width
Delivered width in pixels; must agree with the saved image, not the sensor mode alone.
Local ground coordinates in metres, east and north of the projection origin.
double north
Metres north of the shared local geographic reference.
double east
Metres east of the shared local geographic reference.
Pose estimate and its positional margin for a single observation.
double latitude_deg
Observation latitude in geographic degrees, not FC fixed-point units.
double longitude_deg
Observation longitude in geographic degrees.
Geographic observation in the shared USHER point units.
Caller-owned fixed storage; slot indices stay stable while scores improve.
One measured camera calibration loaded from the flat PANGEA profile format.
struct coverage_camera calibration
static struct camera_backend camera
Definition usher.c:521
struct usher_control_result result
Definition usher.c:377
union dc_shot_union shot
Definition usher.c:534
#define USHER_CAMERA_AICAM