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
ear_heatmap_replay.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 ear_heatmap_replay.c
20 * @brief Offline CSV replay utility for validating EARcam heatmaps and fusion. */
21// C11 + POSIX.1-2008.
22#define _POSIX_C_SOURCE 200809L
23
24// Re-render an EAR session log (earlogs/ear_*.csv) into the loudest-spot heatmap
25// exactly as USHER does in flight: fuse the samples, write the JPEG and its .geo
26// georeference sidecar. The host-only ear_heatmap_overlay application can place
27// the field over local or online satellite tiles.
28//
29// ear_heatmap_replay earlogs/ear_20260908_103533.csv photos/e000686.jpg
30// -> photos/e000686.jpg, e000686.geo, e000686_field.jpg (undecorated overlay input)
32#include "version.h"
33
34#include <stdio.h>
35#include <stdlib.h>
36#include <string.h>
37
38/** Bounded workspace matches EARcam's runtime sample ceiling; replay never grows with log size. */
40
41/**
42 * @brief Decode one EAR session row into the shared fusion sample structure.
43 * @param line Comma-separated log row in the order documented by the session header.
44 * @param s Receives the parsed measurement; the caller owns this sample slot.
45 * @return 0 for all twelve required fields, or -1 for an incomplete/malformed row.
46 * @details Keeping replay on `ear_sample` makes the same solver and renderer handle
47 * recorded evidence and live USHER snapshots.
48 */
49static int parse_line(const char *line, struct ear_sample *s)
50{
51 unsigned long long t_ms;
52 int shot, alarm, clip;
53 double freq;
54 int fields = sscanf(line, "%llu,%d,%lf,%lf,%lf,%lf,%lf,%lf,%lf,%lf,%d,%d",
55 &t_ms, &shot, &s->lat_deg, &s->lon_deg, &s->agl_m, &s->alt_m,
56 &s->level_db, &s->trend_db, &s->contrast_db, &freq, &alarm, &clip);
57 if (fields != 12) {
58 return -1;
59 }
60 s->timestamp_ms = t_ms;
61 s->shot_nr = shot;
62 s->frequency_hz = freq;
63 s->alarm = alarm != 0;
64 s->clipped = clip != 0;
65 return 0;
66}
67
68/**
69 * @brief Recompute an EAR loudest-spot result and emit decorated/field JPEGs.
70 * @param argc Command-line argument count.
71 * @param argv Expects a session CSV and destination JPEG, or a help/version switch.
72 * @return 0 on completed output, 2 for usage errors, or 1 when the log has no valid solve.
73 * @details The undecorated sibling preserves clean heat colors for later map overlay;
74 * the decorated JPEG remains the human-readable result and both share one `.geo` frame.
75 */
76int main(int argc, char **argv)
77{
78 if (argc == 2 && (!strcmp(argv[1], "--version") || !strcmp(argv[1], "-V"))) {
80 return 0;
81 }
82 if (argc == 2 && (!strcmp(argv[1], "--help") || !strcmp(argv[1], "-h"))) {
83 printf("%s\nUsage: %s SESSION.csv OUT.jpg\n", EAR_HEATMAP_REPLAY_BUILD_VERSION, argv[0]);
84 return 0;
85 }
86 if (argc != 3) {
87 fprintf(stderr, "usage: %s SESSION.csv OUT.jpg\n", argv[0]);
88 return 2;
89 }
90 FILE *input = fopen(argv[1], "r");
91 if (input == NULL) {
92 perror(argv[1]);
93 return 1;
94 }
95 size_t count = 0;
96 char line[512];
97 // Stop at the runtime sample bound so hostile/oversized logs cannot grow replay state.
98 while (fgets(line, sizeof(line), input) != NULL && count < EAR_MAX_SAMPLES) {
99 if (line[0] == '#' || line[0] == 't' || line[0] == '\n') {
100 continue; // comment, header or blank
101 }
102 if (parse_line(line, &samples[count]) == 0) {
103 count++;
104 }
105 }
106 fclose(input);
107
108 struct ear_loudest_spot spot;
109 memset(&spot, 0, sizeof(spot));
110 if (calculated_loudestspot(samples, count, &spot) != 0 || !spot.valid) {
111 fprintf(stderr, "%s: no valid loudest spot from %zu samples\n", argv[1], count);
112 return 1;
113 }
114 printf("samples=%zu used=%u spot lat=%.7f lon=%.7f level=%.2f dB conf=%.3f\n",
115 count, spot.used_count, spot.lat_deg, spot.lon_deg, spot.level_db, spot.confidence);
116 int status = ear_heatmap_write(argv[2], samples, count, &spot);
117 if (status == 0) {
118 // Keep the overlay input clean; blending the decorated markers twice obscures the field.
119 char field[512];
120 size_t n = strlen(argv[2]);
121 size_t stem = (n > 4 && strcmp(argv[2] + n - 4, ".jpg") == 0) ? n - 4 : n;
122 if (stem + 11 < sizeof(field)) {
123 for (size_t i = 0; i < stem; i++) {
124 field[i] = argv[2][i];
125 }
126 field[stem] = '\0';
127 strcat(field, "_field.jpg");
128 if (ear_heatmap_write_field(field, samples, count, &spot) == 0) {
129 printf("wrote %s\n", field);
130 }
131 }
132 }
133 if (status != 0) {
134 fprintf(stderr, "failed to write %s\n", argv[2]);
135 return 1;
136 }
137 printf("wrote %s (+ .geo sidecar)\n", argv[2]);
138 return 0;
139}
int calculated_loudestspot(const struct ear_sample *samples, size_t count, struct ear_loudest_spot *result)
Estimate a ground source from relative loudness along a survey track.
Definition ear_fusion.c:129
int ear_heatmap_write(const char *filename, const struct ear_sample *samples, size_t count, const struct ear_loudest_spot *spot)
Write a decorated north-up JPEG of relative measured acoustic intensity.
int ear_heatmap_write_field(const char *filename, const struct ear_sample *samples, size_t count, const struct ear_loudest_spot *spot)
Write the same field without track dots, source marker or scale bar.
Render geotagged acoustic measurements into north-up JPEG heatmaps.
int main(int argc, char **argv)
Recompute an EAR loudest-spot result and emit decorated/field JPEGs.
static struct ear_sample samples[EAR_MAX_SAMPLES]
static int parse_line(const char *line, struct ear_sample *s)
Decode one EAR session row into the shared fusion sample structure.
#define EAR_MAX_SAMPLES
Definition earcam_core.h:34
static size_t count
Definition pose_log.c:79
Compile-time build identity strings for USHER executables.
#define EAR_HEATMAP_REPLAY_BUILD_VERSION
Definition version.h:81
Estimated ground source, not a surveyed target or guaranteed alarm detection.
Definition earcam_core.h:37
uint32_t used_count
Definition earcam_core.h:46
One audio window associated with microphone position and provenance.
Definition earcam_core.h:55
int32_t shot_nr
Definition earcam_core.h:57
double lat_deg
Definition earcam_core.h:58
double trend_db
Definition earcam_core.h:63
double frequency_hz
Definition earcam_core.h:65
double agl_m
Definition earcam_core.h:60
double lon_deg
Definition earcam_core.h:59
double contrast_db
Definition earcam_core.h:64
double alt_m
Definition earcam_core.h:61
double level_db
Definition earcam_core.h:62
uint64_t timestamp_ms
Definition earcam_core.h:56
union dc_shot_union shot
Definition usher.c:534