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_cam_pipe.h
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#ifndef USHER_SPOTTERCAM_PIPE_H
19#define USHER_SPOTTERCAM_PIPE_H
20
21/**
22 * @file spotter_cam_pipe.h
23 * @brief Native USHER adapter for on-sensor detection or photo-only capture.
24 * @details Uses the neutral native-worker supervisor,
25 * then interprets only the matching detector sidecar. Capture success and usable
26 * analysis are separate outcomes; the last result is retrieved separately for EXIF.
27 * @pre Configuration, capture, binding and result retrieval are serialized by
28 * the owning backend. This adapter has one parser workspace and one last result.
29 */
30
31#include <stddef.h>
32#include <stdbool.h>
33#include <stdint.h>
34
36
37#define SPOTTER_MAX_DETECTIONS 64U
38#define SPOTTER_LABEL_CAPACITY 64U
39
47
55
56bool spotter_cam_pipe_read_detections(const char *filename, struct spotter_detections *detections);
57
58/** @brief Borrow USHER's shutdown flag for both serialized native worker owners. */
59void spotter_cam_pipe_configure(const struct camera_backend_host *host);
60
61/** @brief Select or inspect the model-free capture mode before worker startup. */
64
65/** @brief Start and qualify native persistent capture with the selected analysis policy.
66 * @param unused Reserved common backend argument.
67 * @return 0 after the selected producer qualifies readiness, otherwise -1.
68 * @details Process startup alone is insufficient: the capture owner must report
69 * its initial frame and, when enabled, inference contract before accepting photographs. */
70int spotter_cam_pipe_init(const char *unused);
71/** @brief Set the borrowed output directory before backend initialization.
72 * @param directory Caller-owned path retained until configuration changes; NULL
73 * restores the build-time default.
74 * @pre No capture is using the previous configuration. */
75void spotter_cam_pipe_set_photo_directory(const char *directory);
76/** @brief Request one JPEG and, when enabled, parse its matching detection sidecar.
77 * @param filename Output path buffer, cleared on failure.
78 * @param filename_size Output path capacity.
79 * @param image_number USHER shot sequence.
80 * @return 0 only for a qualified saved image, otherwise -1.
81 * @details Missing or malformed analysis leaves the photograph usable and makes
82 * the summary report analysis_failed. Clearing the old result prevents a previous
83 * hit being attached to the next exposure. */
84int spotter_cam_pipe_shoot(char *filename, size_t filename_size, int image_number);
85/** @brief Stop the native camera process and clear detector-specific configuration. */
87/** @brief Format the most recent shot's detection result for EXIF writing.
88 * @param buffer Caller-owned destination for a short human-readable summary.
89 * @param buffer_size Capacity of @p buffer.
90 * @details Reflects the last spotter_cam_pipe_shoot() call only; safe to call even
91 * when that call failed (reports status=analysis_failed) or no server ever ran. */
92void spotter_cam_pipe_last_detection_summary(char *buffer, size_t buffer_size);
93/** @brief Reject a detection result whose identity differs from the validated saved frame.
94 * @param sequence Camera sequence obtained from that image's validated frame evidence.
95 * @param sensor_timestamp_ns Matching sensor timestamp, not the FC shot time.
96 * @return True for matching detector identity; false clears the retained analysis.
97 * @details INI parsing alone does not bind detections to pixels. Compare both
98 * fields after shared frame/file validation and before EXIF replacement changes the inode. */
99bool spotter_cam_pipe_bind_frame(uint64_t sequence, uint64_t sensor_timestamp_ns);
100/** @brief Copy @p filename into a "detections" subdirectory of the photo directory
101 * if the last spotter_cam_pipe_shoot() call found an object.
102 * @param filename Path to the just-finished image (ideally already EXIF-tagged by the
103 * caller, so the copy carries the same metadata as the original).
104 * @details No-op when the last shot found nothing, never completed, or @p filename is
105 * NULL/empty; safe to call unconditionally, mirroring spotter_cam_pipe_last_detection_summary(). */
106void spotter_cam_pipe_save_detection_copy(const char *filename);
107/** @brief Select the detector assignment before either capture or saved-picture analysis starts.
108 * @param settings Nonempty borrowed application settings path, alive until both workers stop.
109 * @return Zero if accepted; minus one for invalid input or an already active worker. */
110int spotter_cam_pipe_set_settings(const char *settings);
111/** @brief Analyze a saved simulation/private picture and bind results to its source hash and request.
112 * @param filename Saved JPEG, still owned by the producer during analysis.
113 * @param number Positive increasing correlation number.
114 * @return Zero when disabled or a matching result is accepted, minus one with retained detections cleared.
115 * @details A valid empty result remains distinct from failed or mismatched analysis. */
116int spotter_cam_pipe_analyze(const char *filename, unsigned number);
117
118#endif
static bool enabled(void)
Report explicit opt-in independently of process or model readiness.
static struct spotter_detections detections
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...
int spotter_cam_pipe_set_settings(const char *settings)
Select the detector assignment before either capture or saved-picture analysis starts.
void spotter_cam_pipe_configure(const struct camera_backend_host *host)
Borrow USHER's shutdown flag for both serialized native worker owners.
#define SPOTTER_MAX_DETECTIONS
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_analyze(const char *filename, unsigned number)
Analyze a saved simulation/private picture and bind results to its source hash and request.
int spotter_cam_pipe_init(const char *unused)
Start and qualify native persistent capture with the selected analysis policy.
void spotter_cam_pipe_set_photo_directory(const char *directory)
Set the borrowed output directory before backend initialization.
#define SPOTTER_LABEL_CAPACITY
int spotter_cam_pipe_set_photo_only(bool enabled)
Select or inspect the model-free capture mode before worker startup.
char label[SPOTTER_LABEL_CAPACITY]
struct spotter_detection objects[SPOTTER_MAX_DETECTIONS]