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.c File Reference

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"
Include dependency graph for spotter_cam_pipe.c:

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()

int copy_file ( const char * source_path,
const char * dest_path )
static

Stream a review copy without allocating another image-sized buffer.

Parameters
source_pathReadable original photograph, which is never modified.
dest_pathNew 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()

bool detection_field ( void * context,
const char * key,
const char * value )
static

Parse one bounded detector sidecar field.

Parameters
[in,out]contextPointer to the parser's detection_fields accumulator.
keyCurrent key from the INI reader.
valueAssociated 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()

int metadata_path ( const char * filename,
char * path,
size_t path_size )
static

Build the sidecar name by replacing the final .jpg suffix.

Parameters
filenameCompleted JPEG filename.
pathCaller-owned output buffer.
path_sizeOutput capacity.
Returns
Zero on a bounded JPEG path, otherwise -1.

Definition at line 136 of file spotter_cam_pipe.c.

◆ parse_detection_sidecar()

bool parse_detection_sidecar ( const char * filename,
struct object_detection_result * result )
static

Read only the capture-facing detector summary.

Parameters
filenameJPEG paired with the sidecar.
[out]resultSummary; 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()

bool read_detection_sidecar ( const char * filename,
struct object_detection_result * result,
struct spotter_detections * detections )
static

Read a stable bounded sidecar and validate schema, dimensions, and every box.

Parameters
filenameMatching JPEG path.
[out]resultCleared on any I/O, parse, or schema failure.
[out]detectionsOptional 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
filenameSaved JPEG, still owned by the producer during analysis.
numberPositive 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
sequenceCamera sequence obtained from that image's validated frame evidence.
sensor_timestamp_nsMatching 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
unusedReserved 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
bufferCaller-owned destination for a short human-readable summary.
buffer_sizeCapacity 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
filenameJPEG paired with the sidecar.
[out]detectionsRequired 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
filenamePath 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
directoryCaller-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
settingsNonempty 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
filenameOutput path buffer, cleared on failure.
filename_sizeOutput path capacity.
image_numberUSHER 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

struct object_detection_result last_detection
static

Current shot only; cleared on capture/binding failure.

Definition at line 108 of file spotter_cam_pipe.c.

◆ photo_directory

const char* photo_directory = USHER_SPOTTERCAM_PHOTO_DIR
static

Borrowed configured photo directory.

Definition at line 86 of file spotter_cam_pipe.c.

◆ spotter_analysis

struct imx500_pipe spotter_analysis = IMX500_PIPE_INITIALIZER
static

Definition at line 82 of file spotter_cam_pipe.c.

◆ spotter_capture

struct imx500_pipe spotter_capture = IMX500_PIPE_INITIALIZER
static

Exclusive native-detector process state.

Definition at line 81 of file spotter_cam_pipe.c.

◆ spotter_photo_only

bool spotter_photo_only
static

Definition at line 84 of file spotter_cam_pipe.c.

◆ spotter_settings

const char* spotter_settings
static

Definition at line 83 of file spotter_cam_pipe.c.