Native USHER adapter for on-sensor IMX500 object detection. More...
#include <errno.h>#include <fcntl.h>#include <limits.h>#include <math.h>#include <poll.h>#include <signal.h>#include <spawn.h>#include <stdint.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <sys/stat.h>#include <sys/socket.h>#include <sys/types.h>#include <sys/wait.h>#include <time.h>#include <unistd.h>#include "spotter_cam_pipe.h"#include "camera_backend.h"#include "imx500_pipe.h"#include "path_utils.h"#include "bounded_ini.h"#include "sha256fst.h"#include "exifite.h"
Go to the source code of this file.
Data Structures | |
| struct | object_detection_result |
| struct | detection_fields |
Macros | |
| #define | USHER_SPOTTERCAM_PHOTO_DIR USHER_AI_CAM_PHOTO_DIR |
| #define | OBJECT_METADATA_LIMIT 32768 |
| #define | OBJECT_MAX_DETECTIONS 64 |
| #define | OBJECT_LABEL_SIZE 64 |
| #define | OBJECT_COPY_BUFFER_SIZE (64U * 1024U) |
| #define | USHER_SPOTTERCAM_COMMAND "./bin/spottercam" |
| Standalone object-worker executable, never the LOOM entry point. | |
| #define | USHER_SPOTTERCAM_MODEL "models/ai_cam/nn_vehicles.rpk" |
| Native detector RPK path borrowed for the worker's lifetime. | |
Functions | |
| 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_set_photo_only (bool enabled) |
| Select or inspect the model-free capture mode before worker startup. | |
| bool | spotter_cam_pipe_photo_only (void) |
| Report whether capture was configured without analysis. | |
| static int | metadata_path (const char *filename, char *path, size_t path_size) |
| static bool | detection_field (void *context, const char *key, const char *value) |
| Parse one bounded detector sidecar field. | |
| static bool | read_detection_sidecar (const char *filename, struct object_detection_result *result, struct spotter_detections *detections) |
| Read a stable bounded sidecar and validate schema, dimensions, and every box. | |
| static bool | parse_detection_sidecar (const char *filename, struct object_detection_result *result) |
| Read only the capture-facing detector summary. | |
| bool | spotter_cam_pipe_read_detections (const char *filename, struct spotter_detections *detections) |
| Read the full detector result associated with a JPEG. | |
| 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. | |
| void | spotter_cam_pipe_set_photo_directory (const char *directory) |
| Set the borrowed output directory before backend initialization. | |
| void | spotter_cam_pipe_last_detection_summary (char *buffer, size_t buffer_size) |
| Format the most recent shot's detection result for EXIF writing. | |
| static int | copy_file (const char *source_path, const char *dest_path) |
| Stream a review copy without allocating another image-sized buffer. | |
| 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_shoot() call found an object. | |
| int | spotter_cam_pipe_init (const char *unused) |
| Start and qualify native persistent capture with the selected analysis policy. | |
| 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. | |
| void | spotter_cam_pipe_deinit (void) |
| Stop the native camera process and clear detector-specific configuration. | |
| int | spotter_cam_pipe_set_settings (const char *settings) |
| Select the detector assignment before either capture or saved-picture analysis starts. | |
| 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. | |
Variables | |
| static struct imx500_pipe | spotter_capture = IMX500_PIPE_INITIALIZER |
| static struct imx500_pipe | spotter_analysis = IMX500_PIPE_INITIALIZER |
| static const char * | spotter_settings |
| static bool | spotter_photo_only |
| static const char * | photo_directory = USHER_SPOTTERCAM_PHOTO_DIR |
| static struct object_detection_result | last_detection |
Detailed Description
Native USHER adapter for on-sensor IMX500 object detection.
The native Spottercam worker owns capture. This adapter checks its bounded object sidecar and retains the highest-confidence box for EXIF/SODA. Missing analysis does not delete a useful photograph, and a valid empty result is not a hit. Review copies happen only after USHER has tagged the original. Shared process supervision and frame timing deliberately remain separate from detector interpretation; LOOM does not use this adapter's result semantics.
Definition in file spotter_cam_pipe.c.
Macro Definition Documentation
◆ OBJECT_COPY_BUFFER_SIZE
| #define OBJECT_COPY_BUFFER_SIZE (64U * 1024U) |
Stream large photo copies in fixed chunks instead of allocating image-sized RAM.
Definition at line 70 of file spotter_cam_pipe.c.
◆ OBJECT_LABEL_SIZE
| #define OBJECT_LABEL_SIZE 64 |
Bound labels copied from model metadata into the fixed EXIF summary.
Definition at line 68 of file spotter_cam_pipe.c.
◆ OBJECT_MAX_DETECTIONS
| #define OBJECT_MAX_DETECTIONS 64 |
Bound candidate records even when a producer sends a syntactically valid oversized array.
Definition at line 66 of file spotter_cam_pipe.c.
◆ OBJECT_METADATA_LIMIT
| #define OBJECT_METADATA_LIMIT 32768 |
A sidecar is generated locally; 32 KiB bounds 64 boxes with precise centres.
Definition at line 64 of file spotter_cam_pipe.c.
◆ USHER_SPOTTERCAM_COMMAND
| #define USHER_SPOTTERCAM_COMMAND "./bin/spottercam" |
Standalone object-worker executable, never the LOOM entry point.
Definition at line 74 of file spotter_cam_pipe.c.
◆ USHER_SPOTTERCAM_MODEL
| #define USHER_SPOTTERCAM_MODEL "models/ai_cam/nn_vehicles.rpk" |
Native detector RPK path borrowed for the worker's lifetime.
Definition at line 78 of file spotter_cam_pipe.c.
◆ USHER_SPOTTERCAM_PHOTO_DIR
| #define USHER_SPOTTERCAM_PHOTO_DIR USHER_AI_CAM_PHOTO_DIR |
Defaults to the same directory as plain AICam (USHER_AI_CAM_PHOTO_DIR, already defined globally via the build's CFLAGS): –spottercam is still conceptually "the AI camera", just with detection added, so it belongs in the same photo directory.
Definition at line 60 of file spotter_cam_pipe.c.
Function Documentation
◆ copy_file()
|
static |
Stream a review copy without allocating another image-sized buffer.
- Parameters
-
source_path Readable original photograph, which is never modified. dest_path New review destination; existing files and links are never replaced.
- Returns
- Zero after writes/close succeed, otherwise -1; opened partial output is removed.
This is a convenience copy, not the exclusive flight-image publication path. It neither fsyncs the destination nor guarantees power-loss durability.
Definition at line 395 of file spotter_cam_pipe.c.
◆ detection_field()
|
static |
Parse one bounded detector sidecar field.
- Parameters
-
[in,out] context Pointer to the parser's detection_fields accumulator. key Current key from the INI reader. value Associated text value.
- Returns
- True when the field is accepted.
Track field presence independently of values so duplicate metadata or box fields cannot replace the first reading silently.
Definition at line 165 of file spotter_cam_pipe.c.
◆ metadata_path()
|
static |
Build the sidecar name by replacing the final .jpg suffix.
- Parameters
-
filename Completed JPEG filename. path Caller-owned output buffer. path_size Output capacity.
- Returns
- Zero on a bounded JPEG path, otherwise -1.
Definition at line 136 of file spotter_cam_pipe.c.
◆ parse_detection_sidecar()
|
static |
Read only the capture-facing detector summary.
- Parameters
-
filename JPEG paired with the sidecar. [out] result Summary; cleared on read or validation failure.
- Returns
- True for valid evidence, including zero detections.
Reuse the full parser so requesting only the summary never skips box or provenance validation.
Definition at line 334 of file spotter_cam_pipe.c.
◆ read_detection_sidecar()
|
static |
Read a stable bounded sidecar and validate schema, dimensions, and every box.
- Parameters
-
filename Matching JPEG path. [out] result Cleared on any I/O, parse, or schema failure. [out] detections Optional expanded detection list and provenance.
- Returns
- True for valid metadata, including a valid zero-detection frame.
Size/mtime checks reject ordinary changes during the read, while caller-owned buffers bound parser storage. Exposure association is a later exact sequence/timestamp check, not a property of INI syntax alone.
Definition at line 235 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_analyze()
| 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.
- Parameters
-
filename Saved JPEG, still owned by the producer during analysis. number Positive increasing correlation number.
- Returns
- Zero when disabled or a matching result is accepted, minus one with retained detections cleared.
A valid empty result remains distinct from failed or mismatched analysis.
Definition at line 546 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_bind_frame()
| 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.
- Parameters
-
sequence Camera sequence obtained from that image's validated frame evidence. sensor_timestamp_ns Matching sensor timestamp, not the FC shot time.
- Returns
- True for matching detector identity; false clears the retained analysis.
INI parsing alone does not bind detections to pixels. Compare both fields after shared frame/file validation and before EXIF replacement changes the inode.
Definition at line 351 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_configure()
| void spotter_cam_pipe_configure | ( | const struct camera_backend_host * | host | ) |
Borrow USHER's shutdown flag for both serialized native worker owners.
Definition at line 110 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_deinit()
| void spotter_cam_pipe_deinit | ( | void | ) |
Stop the native camera process and clear detector-specific configuration.
Stop the selected camera owner and release detector-specific configuration.
Definition at line 532 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_init()
| int spotter_cam_pipe_init | ( | const char * | unused | ) |
Start and qualify native persistent capture with the selected analysis policy.
- Parameters
-
unused Reserved common backend argument.
- Returns
- 0 after the selected producer qualifies readiness, otherwise -1.
Process startup alone is insufficient: the capture owner must report its initial frame and, when enabled, inference contract before accepting photographs.
Definition at line 496 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_last_detection_summary()
| void spotter_cam_pipe_last_detection_summary | ( | char * | buffer, |
| size_t | buffer_size ) |
Format the most recent shot's detection result for EXIF writing.
- Parameters
-
buffer Caller-owned destination for a short human-readable summary. buffer_size Capacity of buffer.
Reflects the last spotter_cam_pipe_shoot() call only; safe to call even when that call failed (reports status=analysis_failed) or no server ever ran.
Definition at line 374 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_photo_only()
| bool spotter_cam_pipe_photo_only | ( | void | ) |
Report whether capture was configured without analysis.
- Returns
- True in photo-only mode.
This is a configuration check, not a camera readiness check.
Definition at line 126 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_read_detections()
| bool spotter_cam_pipe_read_detections | ( | const char * | filename, |
| struct spotter_detections * | detections ) |
Read the full detector result associated with a JPEG.
- Parameters
-
filename JPEG paired with the sidecar. [out] detections Required destination for boxes and provenance.
- Returns
- True for a valid sidecar, including an empty detector result.
Use the same validation as the capture summary so downstream projection cannot admit results the capture pipeline rejects.
Definition at line 345 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_save_detection_copy()
| 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_shoot() call found an object.
- Parameters
-
filename Path to the just-finished image (ideally already EXIF-tagged by the caller, so the copy carries the same metadata as the original).
No-op when the last shot found nothing, never completed, or filename is NULL/empty; safe to call unconditionally, mirroring spotter_cam_pipe_last_detection_summary().
Definition at line 459 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_set_photo_directory()
| void spotter_cam_pipe_set_photo_directory | ( | const char * | directory | ) |
Set the borrowed output directory before backend initialization.
- Parameters
-
directory Caller-owned path retained until configuration changes; NULL restores the build-time default.
- Precondition
- No capture is using the previous configuration.
Definition at line 367 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_set_photo_only()
| int spotter_cam_pipe_set_photo_only | ( | bool | enabled | ) |
Select or inspect the model-free capture mode before worker startup.
Definition at line 116 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_set_settings()
| int spotter_cam_pipe_set_settings | ( | const char * | settings | ) |
Select the detector assignment before either capture or saved-picture analysis starts.
- Parameters
-
settings Nonempty borrowed application settings path, alive until both workers stop.
- Returns
- Zero if accepted; minus one for invalid input or an already active worker.
Definition at line 539 of file spotter_cam_pipe.c.
◆ spotter_cam_pipe_shoot()
| 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.
- Parameters
-
filename Output path buffer, cleared on failure. filename_size Output path capacity. image_number USHER shot sequence.
- Returns
- 0 only for a qualified saved image, otherwise -1.
Missing or malformed analysis leaves the photograph usable and makes the summary report analysis_failed. Clearing the old result prevents a previous hit being attached to the next exposure.
Definition at line 510 of file spotter_cam_pipe.c.
Variable Documentation
◆ last_detection
|
static |
Current shot only; cleared on capture/binding failure.
Definition at line 108 of file spotter_cam_pipe.c.
◆ photo_directory
|
static |
Borrowed configured photo directory.
Definition at line 86 of file spotter_cam_pipe.c.
◆ spotter_analysis
|
static |
Definition at line 82 of file spotter_cam_pipe.c.
◆ spotter_capture
|
static |
Exclusive native-detector process state.
Definition at line 81 of file spotter_cam_pipe.c.
◆ spotter_photo_only
|
static |
Definition at line 84 of file spotter_cam_pipe.c.
◆ spotter_settings
|
static |
Definition at line 83 of file spotter_cam_pipe.c.