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.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.c
20 * @brief Bounded, north-up acoustic evidence rendering and JPEG georeference sidecars.
21 * @details Deposit measured linear power into a height-dependent Gaussian grid,
22 * normalize by deposited weight, then display the loud end of the dB range.
23 * Smoothing is a visualization heuristic, not a measured microphone beam model.
24 * The decorated image explains the track; the undecorated field supports overlays.
25 */
26#include "ear_heatmap.h"
27
28#include <ctype.h>
29#include <errno.h>
30#include <float.h>
31#include <math.h>
32#include <pthread.h>
33#include <setjmp.h>
34#include <stdint.h>
35#include <stdio.h>
36#include <stdlib.h>
37#include <string.h>
38
39#include <jpeglib.h>
40
41#define HEATMAP_MIN_CELL_M 1.0
42#define HEATMAP_MAX_CELLS 96U
43#define HEATMAP_MAX_OUTPUT_PX 768U
44#define HEATMAP_QUALITY 90
45#define HEATMAP_MIN_SAMPLES 3U
46#define EARTH_RADIUS_M 6378137.0
47#define DEG_TO_RAD 0.017453292519943295
48
49/** Policy values below retain existing output geometry, colors and byte values. */
50#define HEATMAP_RGB_CHANNELS 3
51#define HEATMAP_RGB_CHANNELS_U 3U
52#define HEATMAP_RGB_MAX 255
53#define HEATMAP_RGB_MAX_F 255.0
54#define HEATMAP_PATH_CAPACITY 512
55#define HEATMAP_SUFFIX_LENGTH 4
56#define HEATMAP_SUFFIX_STORAGE 5
57#define HEATMAP_BOUND_INITIALIZER 1e9
58#define HEATMAP_POSE_LATITUDE_EPSILON_DEG 1e-6
59#define HEATMAP_MIN_USABLE_AGL_M 0.5
60#define HEATMAP_FALLBACK_AGL_M 10.0
61#define HEATMAP_CELLS_PER_AGL 4.0
62#define HEATMAP_FOOTPRINT_SIGMA_DIVISOR 2.0
63#define HEATMAP_MIN_HALF_EXTENT_CELLS 3.0
64#define HEATMAP_GAUSSIAN_REACH_SIGMAS 3.0
65#define HEATMAP_MIN_DEPOSIT_WEIGHT 1e-3
66#define HEATMAP_MIN_INTERPOLATION_WEIGHT 1e-6
67#define HEATMAP_DB_LOG_BASE 10.0
68#define HEATMAP_POWER_DB_PER_DECADE 10.0
69#define HEATMAP_FLAT_RANGE_DB 1.0
70#define HEATMAP_DISPLAY_RANGE_DB 20.0
71/** Piecewise palette: dark blue -> cyan -> yellow -> red; channels are normalized. */
72#define HEATMAP_PALETTE_FIRST_END 0.33
73#define HEATMAP_PALETTE_SECOND_END 0.66
74#define HEATMAP_PALETTE_FIRST_WIDTH 0.33
75#define HEATMAP_PALETTE_SECOND_WIDTH 0.33
76#define HEATMAP_PALETTE_LAST_WIDTH 0.34
77#define HEATMAP_PALETTE_CHANNEL_LOW 0.05
78#define HEATMAP_PALETTE_CHANNEL_HIGH 0.95
79#define HEATMAP_PALETTE_BLUE_START 0.35
80#define HEATMAP_PALETTE_GREEN_START 0.10
81#define HEATMAP_PALETTE_GREEN_FIRST_RISE 0.70
82#define HEATMAP_PALETTE_BLUE_FIRST_RISE 0.55
83#define HEATMAP_PALETTE_RED_SECOND_RISE 0.90
84#define HEATMAP_PALETTE_GREEN_MIDDLE 0.80
85#define HEATMAP_PALETTE_GREEN_SECOND_RISE 0.15
86#define HEATMAP_PALETTE_BLUE_MIDDLE 0.90
87#define HEATMAP_PALETTE_BLUE_SECOND_FALL 0.85
88#define HEATMAP_PALETTE_GREEN_LAST_FALL 0.80
89/** Marker and bar dimensions are output pixels, not localization error bounds. */
90#define HEATMAP_RING_STROKE_PX 2.0
91#define HEATMAP_DOT_REACH_PX 2.5
92#define HEATMAP_DOT_OUTER_RADIUS_PX 2.0
93#define HEATMAP_SPOT_GREEN 40
94#define HEATMAP_SPOT_RING_RADIUS_PX 9.0
95#define HEATMAP_SPOT_ARM_LENGTH_PX 22.0
96#define HEATMAP_SPOT_ARM_GAP_PX 4.0
97#define HEATMAP_SPOT_OUTLINE_RADIUS_PX 2.4
98#define HEATMAP_SPOT_ARM_RADIUS_PX 1.2
99#define HEATMAP_SPOT_CENTER_RADIUS_PX 1.5
100#define HEATMAP_SCALE_LENGTH_M 50.0
101#define HEATMAP_SCALE_MAX_WIDTH_FRACTION 0.6
102#define HEATMAP_SCALE_LEFT_FRACTION 0.04
103#define HEATMAP_SCALE_BOTTOM_FRACTION 0.06
104#define HEATMAP_SCALE_OUTLINE_RADIUS_PX 2.5
105#define HEATMAP_SCALE_STROKE_RADIUS_PX 1.2
106#define HEATMAP_SCALE_TICK_HALF_HEIGHT_PX 6
107
108/* Serialize the shared grids and RGB workspace through encoding. A second
109 * caller must not overwrite pixels while libjpeg still reads the first image. */
110static pthread_mutex_t heatmap_mutex = PTHREAD_MUTEX_INITIALIZER;
114
115/**
116 * @brief Per-encode libjpeg callback state and recovery point.
117 * @details Kept on the active stack frame so one failed JPEG cannot poison a
118 * subsequent render or escape into the host service.
119 */
121 struct jpeg_error_mgr manager;
122 jmp_buf recovery;
123};
124
125/**
126 * @brief Turn a fatal libjpeg callback into a local encoder failure.
127 * @param info Codec state whose error manager stores the recovery target.
128 * @details Default libjpeg handling terminates the process; USHER must instead
129 * report a failed visualization and remain available for camera/UART work.
130 */
131static void heatmap_jpeg_error_exit(j_common_ptr info)
132{
133 struct heatmap_jpeg_error *error = (struct heatmap_jpeg_error *)info->err;
134 longjmp(error->recovery, 1);
135}
136
137/**
138 * @brief Map a normalized relative level to the preserved three-color ramp.
139 * @param t Display position; out-of-range values are clamped to [0, 1].
140 * @param rgb Receives red, green and blue 8-bit channels.
141 * @details The palette represents relative levels within this image; it is not
142 * a calibrated sound-pressure scale and its breakpoints remain fixed for compatibility.
143 */
144static void colormap(double t, uint8_t *rgb)
145{
146 if (t < 0.0) { t = 0.0; }
147 if (t > 1.0) { t = 1.0; }
148 double r, g, b;
150 double u = t / HEATMAP_PALETTE_FIRST_WIDTH;
154 } else if (t < HEATMAP_PALETTE_SECOND_END) {
159 } else {
164 }
165 rgb[0] = (uint8_t)(r * HEATMAP_RGB_MAX_F + 0.5);
166 rgb[1] = (uint8_t)(g * HEATMAP_RGB_MAX_F + 0.5);
167 rgb[2] = (uint8_t)(b * HEATMAP_RGB_MAX_F + 0.5);
168}
169
170/**
171 * @brief Rasterize a clipped filled disc or annular stroke.
172 * @param pixels Interleaved RGB destination.
173 * @param width Destination width in pixels.
174 * @param height Destination height in pixels.
175 * @param cx Marker center X, including fractional-pixel position.
176 * @param cy Marker center Y, including fractional-pixel position.
177 * @param radius Outer marker radius.
178 * @param rgb Opaque marker color.
179 * @param ring Draw a ring instead of a filled disc when true.
180 * @details Pixel-center distances keep fractional marker placement symmetric;
181 * explicit clipping prevents edge markers from indexing outside the fixed raster.
182 */
183static void draw_disc(uint8_t *pixels, unsigned int width, unsigned int height,
184 double cx, double cy, double radius, const uint8_t *rgb, bool ring)
185{
186 if (!isfinite(cx) || !isfinite(cy) || !isfinite(radius) || radius < 0 ||
187 cx < -radius - 1 || cy < -radius - 1 || cx > width + radius + 1 || cy > height + radius + 1) return;
188 int x0 = (int)floor(cx - radius - 1.0);
189 int x1 = (int)ceil(cx + radius + 1.0);
190 int y0 = (int)floor(cy - radius - 1.0);
191 int y1 = (int)ceil(cy + radius + 1.0);
192 for (int y = y0; y <= y1; y++) {
193 if (y < 0 || (unsigned int)y >= height) { continue; }
194 for (int x = x0; x <= x1; x++) {
195 if (x < 0 || (unsigned int)x >= width) { continue; }
196 double d = hypot(x + 0.5 - cx, y + 0.5 - cy);
197 bool inside = ring ? (d <= radius && d >= radius - HEATMAP_RING_STROKE_PX) : d <= radius;
198 if (inside) {
199 uint8_t *p = &pixels[((size_t)y * width + x) * HEATMAP_RGB_CHANNELS];
200 p[0] = rgb[0]; p[1] = rgb[1]; p[2] = rgb[2];
201 }
202 }
203 }
204}
205
206/**
207 * @brief Clamp a normalized coverage/intensity value to its legal blend interval.
208 * @param v Candidate weight or palette position.
209 * @return `v` constrained to [0, 1].
210 */
211static double clamp01(double v)
212{
213 return v < 0.0 ? 0.0 : (v > 1.0 ? 1.0 : v);
214}
215
216/**
217 * @brief Draw one observation as a white subpixel core with a dark outline.
218 * @param pixels Interleaved RGB destination.
219 * @param width Destination width in pixels.
220 * @param height Destination height in pixels.
221 * @param cx Observation center X in fractional output pixels.
222 * @param cy Observation center Y in fractional output pixels.
223 * @details Fractional coverage preserves the measured pose's subpixel placement;
224 * the outline separates a location mark from the relative heat palette.
225 */
226static void draw_dot(uint8_t *pixels, unsigned int width, unsigned int height, double cx, double cy)
227{
228 if (!isfinite(cx) || !isfinite(cy) || cx < -HEATMAP_DOT_REACH_PX || cy < -HEATMAP_DOT_REACH_PX ||
229 cx > width + HEATMAP_DOT_REACH_PX || cy > height + HEATMAP_DOT_REACH_PX) return;
230 int x0 = (int)floor(cx - HEATMAP_DOT_REACH_PX), x1 = (int)ceil(cx + HEATMAP_DOT_REACH_PX);
231 int y0 = (int)floor(cy - HEATMAP_DOT_REACH_PX), y1 = (int)ceil(cy + HEATMAP_DOT_REACH_PX);
232 for (int y = y0; y <= y1; y++) {
233 if (y < 0 || (unsigned int)y >= height) { continue; }
234 for (int x = x0; x <= x1; x++) {
235 if (x < 0 || (unsigned int)x >= width) { continue; }
236 double d = hypot(x + 0.5 - cx, y + 0.5 - cy);
237 double white = clamp01(1.0 - d); // core: radius 0.5 px, soft edge
238 double black = clamp01(HEATMAP_DOT_OUTER_RADIUS_PX - d) - white; // ring: 1 px wide around the core
239 if (white + black <= 0.0) { continue; }
240 uint8_t *p = &pixels[((size_t)y * width + x) * HEATMAP_RGB_CHANNELS];
241 for (int c = 0; c < HEATMAP_RGB_CHANNELS; c++) {
242 double v = p[c] * (1.0 - white - black) + HEATMAP_RGB_MAX_F * white;
243 p[c] = (uint8_t)(v + 0.5);
244 }
245 }
246 }
247}
248
249/**
250 * @brief Write the georeference sidecar for a successful north-up JPEG.
251 * @param filename JPEG path whose `.jpg` suffix becomes `.geo`.
252 * @param width Encoded output width in pixels.
253 * @param height Encoded output height in pixels.
254 * @param lat_c Local projection center latitude, degrees.
255 * @param lon_c Local projection center longitude, degrees.
256 * @param cos_lat Longitude-to-metre scale at the center latitude.
257 * @param half_e East half-extent of the raster, metres.
258 * @param half_n North half-extent of the raster, metres.
259 * @param m_per_px Local metres per encoded output pixel.
260 * @param spot Optional solved spot metadata; null/invalid estimates add no spot keys.
261 * @details The sidecar uses the same local equirectangular frame as rasterization.
262 * Its write is best-effort so a valid JPEG is retained if metadata storage fails;
263 * map consumers requiring both artifacts validate the sidecar separately.
264 */
265static void write_georef(const char *filename, unsigned int width, unsigned int height,
266 double lat_c, double lon_c, double cos_lat, double half_e, double half_n,
267 double m_per_px, const struct ear_loudest_spot *spot)
268{
269 char path[HEATMAP_PATH_CAPACITY];
270 size_t n = strlen(filename);
271 if (n + HEATMAP_SUFFIX_STORAGE > sizeof(path)) {
272 return;
273 }
274 size_t stem = (n > HEATMAP_SUFFIX_LENGTH && strcmp(filename + n - HEATMAP_SUFFIX_LENGTH, ".jpg") == 0)
275 ? n - HEATMAP_SUFFIX_LENGTH : n;
276 for (size_t i = 0; i < stem; i++) {
277 path[i] = filename[i];
278 }
279 path[stem] = '\0';
280 strcat(path, ".geo");
281 FILE *f = fopen(path, "w");
282 if (f == NULL) {
283 return;
284 }
285 double m_per_deg_lat = DEG_TO_RAD * EARTH_RADIUS_M;
286 double m_per_deg_lon = m_per_deg_lat * cos_lat;
287 fprintf(f, "# ear heatmap georeference: equirectangular about the centre, north up\n");
288 fprintf(f, "width_px=%u\nheight_px=%u\nm_per_px=%.6f\n", width, height, m_per_px);
289 fprintf(f, "lat_center=%.8f\nlon_center=%.8f\n", lat_c, lon_c);
290 fprintf(f, "lat_north=%.8f\nlon_west=%.8f\n", lat_c + half_n / m_per_deg_lat, lon_c - half_e / m_per_deg_lon);
291 fprintf(f, "lat_south=%.8f\nlon_east=%.8f\n", lat_c + (half_n - height * m_per_px) / m_per_deg_lat,
292 lon_c + (width * m_per_px - half_e) / m_per_deg_lon);
293 if (spot != NULL && spot->valid) {
294 fprintf(f, "spot_lat=%.8f\nspot_lon=%.8f\nspot_level_db=%.2f\nspot_confidence=%.3f\n",
295 spot->lat_deg, spot->lon_deg, spot->level_db, spot->confidence);
296 }
297 fclose(f);
298}
299
300/**
301 * @brief Encode caller-owned RGB pixels as a JPEG.
302 * @param filename Output path.
303 * @param pixels Borrowed row-major interleaved RGB raster.
304 * @param width Raster width in pixels.
305 * @param height Raster height in pixels.
306 * @return 0 after encoding and close succeed; -1 for open/codec/close failures.
307 * @details Scanlines are passed directly to libjpeg, so the bounded renderer
308 * does not need another image-sized copy.
309 */
310static int encode_jpeg(const char *filename, const uint8_t *pixels,
311 unsigned int width, unsigned int height)
312{
313 FILE *output = fopen(filename, "wb");
314 if (output == NULL) {
315 return -1;
316 }
317 struct jpeg_compress_struct encoder;
319 encoder.err = jpeg_std_error(&error.manager);
320 error.manager.error_exit = heatmap_jpeg_error_exit;
321 if (setjmp(error.recovery) != 0) {
322 jpeg_destroy_compress(&encoder);
323 fclose(output);
324 return -1;
325 }
326 jpeg_create_compress(&encoder);
327 jpeg_stdio_dest(&encoder, output);
328 encoder.image_width = width;
329 encoder.image_height = height;
330 encoder.input_components = HEATMAP_RGB_CHANNELS;
331 encoder.in_color_space = JCS_RGB;
332 jpeg_set_defaults(&encoder);
333 jpeg_set_quality(&encoder, HEATMAP_QUALITY, TRUE);
334 jpeg_start_compress(&encoder, TRUE);
335 while (encoder.next_scanline < encoder.image_height) {
336 JSAMPROW row[1] = {(JSAMPROW)&pixels[(size_t)encoder.next_scanline * width * HEATMAP_RGB_CHANNELS]};
337 jpeg_write_scanlines(&encoder, row, 1);
338 }
339 jpeg_finish_compress(&encoder);
340 jpeg_destroy_compress(&encoder);
341 return fclose(output) == 0 ? 0 : -1;
342}
343
344/**
345 * @brief Render the shared measured field with optional human-facing markers.
346 * @param filename Destination JPEG.
347 * @param samples Borrowed, immutable geotagged EAR windows.
348 * @param count Supplied window count.
349 * @param spot Optional fused loudest-spot estimate.
350 * @param decorate Draw observation dots, estimate crosshair and scale bar when true.
351 * @return 0 on successful JPEG encode; -1 for insufficient usable samples or I/O failure.
352 * @details One mutex protects the shared grids and pixels until libjpeg finishes reading
353 * them. The AGL-derived grid is bounded; bilinear upsampling smooths display pixels but
354 * does not increase the microphone's spatial resolution.
355 */
356static int heatmap_write(const char *filename, const struct ear_sample *samples, size_t count,
357 const struct ear_loudest_spot *spot, bool decorate)
358{
359 if (filename == NULL || samples == NULL || count < HEATMAP_MIN_SAMPLES || count > EAR_MAX_SAMPLES) {
360 return -1;
361 }
362
363 // Bounding box and typical AGL over the usable samples.
364 double lat_min = HEATMAP_BOUND_INITIALIZER, lat_max = -HEATMAP_BOUND_INITIALIZER,
366 double agl_sum = 0.0;
367 size_t usable = 0;
368 for (size_t index = 0; index < count; index++) {
369 const struct ear_sample *s = &samples[index];
370 if ((isfinite(s->lat_deg) && fabs(s->lat_deg) > 90) ||
371 (isfinite(s->lon_deg) && fabs(s->lon_deg) > 180) ||
372 (isfinite(s->agl_m) && s->agl_m > INT32_MAX)) return -1;
373 if (s->clipped || !isfinite(s->lat_deg) || !isfinite(s->lon_deg)
374 || !isfinite(s->level_db) || fabs(s->lat_deg) <= HEATMAP_POSE_LATITUDE_EPSILON_DEG) {
375 continue;
376 }
377 const double power = pow(HEATMAP_DB_LOG_BASE, s->level_db / HEATMAP_POWER_DB_PER_DECADE);
378 if (!isfinite(power) || power < DBL_MIN || power > DBL_MAX / EAR_MAX_SAMPLES) return -1;
379 if (s->lat_deg < lat_min) { lat_min = s->lat_deg; }
380 if (s->lat_deg > lat_max) { lat_max = s->lat_deg; }
381 if (s->lon_deg < lon_min) { lon_min = s->lon_deg; }
382 if (s->lon_deg > lon_max) { lon_max = s->lon_deg; }
383 agl_sum += (isfinite(s->agl_m) && s->agl_m > HEATMAP_MIN_USABLE_AGL_M)
385 usable++;
386 }
387 if (usable < HEATMAP_MIN_SAMPLES) {
388 return -1;
389 }
390 double agl = agl_sum / (double)usable;
391 double cell_m = fmax(HEATMAP_MIN_CELL_M, agl / HEATMAP_CELLS_PER_AGL);
392 double sigma_m = fmax(cell_m, agl / HEATMAP_FOOTPRINT_SIGMA_DIVISOR);
393
394 // Local ENU about the box centre, with one footprint of margin.
395 double lat_c = 0.5 * (lat_min + lat_max);
396 double lon_c = 0.5 * (lon_min + lon_max);
397 double cos_lat = cos(lat_c * DEG_TO_RAD);
398 if (!isfinite(cos_lat) || cos_lat <= 0) return -1;
399 double half_e = (lon_max - lon_min) * 0.5 * DEG_TO_RAD * EARTH_RADIUS_M * cos_lat + agl;
400 double half_n = (lat_max - lat_min) * 0.5 * DEG_TO_RAD * EARTH_RADIUS_M + agl;
401 if (half_e < HEATMAP_MIN_HALF_EXTENT_CELLS * cell_m) { half_e = HEATMAP_MIN_HALF_EXTENT_CELLS * cell_m; }
402 if (half_n < HEATMAP_MIN_HALF_EXTENT_CELLS * cell_m) { half_n = HEATMAP_MIN_HALF_EXTENT_CELLS * cell_m; }
403 double grid_x = ceil(2.0 * half_e / cell_m), grid_y = ceil(2.0 * half_n / cell_m);
404 if (!isfinite(grid_x) || !isfinite(grid_y) || grid_x < 1 || grid_y < 1) return -1;
405 if (grid_x > HEATMAP_MAX_CELLS || grid_y > HEATMAP_MAX_CELLS) {
406 double scale = fmax(grid_x, grid_y) / HEATMAP_MAX_CELLS;
407 cell_m *= scale;
408 grid_x = ceil(2.0 * half_e / cell_m);
409 grid_y = ceil(2.0 * half_n / cell_m);
410 }
411 if (!isfinite(grid_x) || !isfinite(grid_y) || grid_x < 1 || grid_y < 1 ||
412 grid_x > HEATMAP_MAX_CELLS || grid_y > HEATMAP_MAX_CELLS) return -1;
413 const unsigned int cells_x = (unsigned int)grid_x, cells_y = (unsigned int)grid_y;
414
415 pthread_mutex_lock(&heatmap_mutex);
416 double *field = heatmap_field;
417 double *weight = heatmap_weight;
418 memset(field, 0, sizeof(heatmap_field));
419 memset(weight, 0, sizeof(heatmap_weight));
420
421 // Gaussian footprint deposit of each sample's level (in linear power).
422 double level_min = HEATMAP_BOUND_INITIALIZER, level_max = -HEATMAP_BOUND_INITIALIZER;
423 double inv_two_sigma2 = 1.0 / (2.0 * sigma_m * sigma_m);
424 int reach = (int)ceil(HEATMAP_GAUSSIAN_REACH_SIGMAS * sigma_m / cell_m);
425 for (size_t index = 0; index < count; index++) {
426 const struct ear_sample *s = &samples[index];
427 if (s->clipped || !isfinite(s->lat_deg) || !isfinite(s->lon_deg)
428 || !isfinite(s->level_db) || fabs(s->lat_deg) <= HEATMAP_POSE_LATITUDE_EPSILON_DEG) {
429 continue;
430 }
431 double e = (s->lon_deg - lon_c) * DEG_TO_RAD * EARTH_RADIUS_M * cos_lat;
432 double n = (s->lat_deg - lat_c) * DEG_TO_RAD * EARTH_RADIUS_M;
433 double gx = (e + half_e) / cell_m;
434 double gy = (half_n - n) / cell_m; // north up
436 int cx0 = (int)floor(gx), cy0 = (int)floor(gy);
437 for (int y = cy0 - reach; y <= cy0 + reach; y++) {
438 if (y < 0 || (unsigned int)y >= cells_y) { continue; }
439 for (int x = cx0 - reach; x <= cx0 + reach; x++) {
440 if (x < 0 || (unsigned int)x >= cells_x) { continue; }
441 double dx = (x + 0.5 - gx) * cell_m;
442 double dy = (y + 0.5 - gy) * cell_m;
443 double w = exp(-(dx * dx + dy * dy) * inv_two_sigma2);
444 size_t k = (size_t)y * cells_x + x;
445 field[k] += w * power;
446 weight[k] += w;
447 }
448 }
449 }
450 for (size_t k = 0; k < (size_t)cells_x * cells_y; k++) {
451 if (weight[k] > HEATMAP_MIN_DEPOSIT_WEIGHT) {
452 field[k] = HEATMAP_POWER_DB_PER_DECADE * log10(field[k] / weight[k]);
453 if (field[k] < level_min) { level_min = field[k]; }
454 if (field[k] > level_max) { level_max = field[k]; }
455 } else {
456 field[k] = NAN;
457 }
458 }
459 if (!(level_max > level_min)) {
460 level_max = level_min + HEATMAP_FLAT_RANGE_DB;
461 }
462 // Emphasize the top of the dynamic range; the quiet floor is not informative.
463 double span = fmin(level_max - level_min, HEATMAP_DISPLAY_RANGE_DB);
464 double floor_db = level_max - span;
465
466 // Output image: upsample cells bilinearly so the viewer sees smooth blobs.
467 // The grid (not the pixel count) carries the microphone's resolution limit.
468 unsigned int cells_max = cells_x > cells_y ? cells_x : cells_y;
469 double scale = (double)HEATMAP_MAX_OUTPUT_PX / (double)cells_max;
470 unsigned int width = (unsigned int)ceil(cells_x * scale);
471 unsigned int height = (unsigned int)ceil(cells_y * scale);
472 if (width < 1U) { width = 1U; }
473 if (height < 1U) { height = 1U; }
474 // The long side is HEATMAP_MAX_OUTPUT_PX by construction; bound both anyway.
475 if (width > HEATMAP_MAX_OUTPUT_PX) { width = HEATMAP_MAX_OUTPUT_PX; }
476 if (height > HEATMAP_MAX_OUTPUT_PX) { height = HEATMAP_MAX_OUTPUT_PX; }
477 uint8_t *pixels = heatmap_pixels;
478 for (unsigned int y = 0; y < height; y++) {
479 double fy = (y + 0.5) / scale - 0.5;
480 int y0 = (int)floor(fy); double ty = fy - y0;
481 for (unsigned int x = 0; x < width; x++) {
482 double fx = (x + 0.5) / scale - 0.5;
483 int x0 = (int)floor(fx); double tx = fx - x0;
484 double sum = 0.0, wsum = 0.0;
485 for (int j = 0; j < 2; j++) {
486 int yy = y0 + j;
487 if (yy < 0 || (unsigned int)yy >= cells_y) { continue; }
488 for (int i = 0; i < 2; i++) {
489 int xx = x0 + i;
490 if (xx < 0 || (unsigned int)xx >= cells_x) { continue; }
491 double v = field[(size_t)yy * cells_x + xx];
492 if (isnan(v)) { continue; }
493 double w = (i ? tx : 1.0 - tx) * (j ? ty : 1.0 - ty);
494 sum += w * v;
495 wsum += w;
496 }
497 }
498 uint8_t *p = &pixels[((size_t)y * width + x) * HEATMAP_RGB_CHANNELS];
500 colormap((sum / wsum - floor_db) / span, p);
501 } else {
503 }
504 }
505 }
506
507 // Track dots and the fused loudest-spot marker.
508 for (size_t index = 0; decorate && index < count; index++) {
509 const struct ear_sample *s = &samples[index];
510 if (!isfinite(s->lat_deg) || !isfinite(s->lon_deg) || fabs(s->lat_deg) <= HEATMAP_POSE_LATITUDE_EPSILON_DEG) {
511 continue;
512 }
513 double e = (s->lon_deg - lon_c) * DEG_TO_RAD * EARTH_RADIUS_M * cos_lat;
514 double n = (s->lat_deg - lat_c) * DEG_TO_RAD * EARTH_RADIUS_M;
515 double px = (e + half_e) / cell_m * scale;
516 double py = (half_n - n) / cell_m * scale;
517 draw_dot(pixels, width, height, px, py);
518 }
519 if (decorate && spot != NULL && spot->valid) {
520 // Loudest spot: magenta crosshair with a small ring, black casing.
522 const uint8_t black[HEATMAP_RGB_CHANNELS] = {0, 0, 0};
523 double e = (spot->lon_deg - lon_c) * DEG_TO_RAD * EARTH_RADIUS_M * cos_lat;
524 double n = (spot->lat_deg - lat_c) * DEG_TO_RAD * EARTH_RADIUS_M;
525 double px = (e + half_e) / cell_m * scale;
526 double py = (half_n - n) / cell_m * scale;
527 const double ring = HEATMAP_SPOT_RING_RADIUS_PX,
529 for (int pass = 0; pass < 2; pass++) {
530 const uint8_t *rgb = pass == 0 ? black : magenta;
532 for (int t = (int)gap; t <= (int)arm; t++) {
533 draw_disc(pixels, width, height, px + t, py, r, rgb, false);
534 draw_disc(pixels, width, height, px - t, py, r, rgb, false);
535 draw_disc(pixels, width, height, px, py + t, r, rgb, false);
536 draw_disc(pixels, width, height, px, py - t, r, rgb, false);
537 }
538 }
539 draw_disc(pixels, width, height, px, py, ring + HEATMAP_RING_STROKE_PX, black, true);
540 draw_disc(pixels, width, height, px, py, ring, magenta, true);
541 draw_disc(pixels, width, height, px, py, HEATMAP_SPOT_CENTER_RADIUS_PX, magenta, false);
542 }
543
544 /* The nominal bar is capped to fit small maps. When capped it is shorter
545 * than the nominal length; .geo m_per_px is the authoritative map scale. */
546 if (decorate) {
548 const uint8_t black[HEATMAP_RGB_CHANNELS] = {0, 0, 0};
549 double bar_px = HEATMAP_SCALE_LENGTH_M / cell_m * scale;
550 if (bar_px > HEATMAP_SCALE_MAX_WIDTH_FRACTION * width) { bar_px = HEATMAP_SCALE_MAX_WIDTH_FRACTION * width; }
551 int bar_steps = (int)floor(bar_px);
552 double x0 = HEATMAP_SCALE_LEFT_FRACTION * width;
553 double y0 = height - HEATMAP_SCALE_BOTTOM_FRACTION * height;
554 for (int t = 0; t <= bar_steps; t++) {
555 draw_disc(pixels, width, height, x0 + t, y0, HEATMAP_SCALE_OUTLINE_RADIUS_PX, black, false);
556 }
557 for (int t = 0; t <= bar_steps; t++) {
558 draw_disc(pixels, width, height, x0 + t, y0, HEATMAP_SCALE_STROKE_RADIUS_PX, white, false);
559 }
561 draw_disc(pixels, width, height, x0, y0 + dy, HEATMAP_SCALE_STROKE_RADIUS_PX, white, false);
562 draw_disc(pixels, width, height, x0 + bar_px, y0 + dy, HEATMAP_SCALE_STROKE_RADIUS_PX, white, false);
563 }
564 }
565
566 int status = encode_jpeg(filename, pixels, width, height);
567 if (status == 0) {
568 write_georef(filename, width, height, lat_c, lon_c, cos_lat, half_e, half_n, cell_m / scale, spot);
569 }
570 pthread_mutex_unlock(&heatmap_mutex);
571 return status;
572}
573
574int ear_heatmap_write(const char *filename, const struct ear_sample *samples, size_t count,
575 const struct ear_loudest_spot *spot)
576{
577 return heatmap_write(filename, samples, count, spot, true);
578}
579
580int ear_heatmap_write_field(const char *filename, const struct ear_sample *samples, size_t count,
581 const struct ear_loudest_spot *spot)
582{
583 return heatmap_write(filename, samples, count, spot, false);
584}
585
586/**
587 * @brief Trim leading/trailing whitespace in a mutable sidecar token.
588 * @param text NUL-terminated buffer; trailing whitespace is replaced by NUL.
589 * @return Pointer to the first non-whitespace character in the same storage.
590 * @details In-place trimming keeps the sidecar reader bounded and validates the
591 * unconsumed suffix left by numeric conversion.
592 */
593static char *trim_whitespace(char *text)
594{
595 while (isspace((unsigned char)*text)) { text++; }
596 char *end = text + strlen(text);
597 while (end > text && isspace((unsigned char)end[-1])) { *--end = '\0'; }
598 return text;
599}
600
601/**
602 * @brief Parse one finite number from a bounded sidecar value token.
603 * @param text Token after key/value splitting.
604 * @param value Receives the value only if the complete trimmed token is valid.
605 * @return false for empty, non-finite, range-error or partially consumed input.
606 * @details Rejecting trailing text prevents plausible prefixes such as `48junk`
607 * from silently changing the overlay's geographic placement.
608 */
609static bool parse_geo_double(const char *text, double *value)
610{
611 errno = 0;
612 char *end = NULL;
613 double parsed = strtod(text, &end);
614 if (end == text || errno == ERANGE || !isfinite(parsed) || *trim_whitespace(end) != '\0') {
615 return false;
616 }
617 *value = parsed;
618 return true;
619}
620
621/**
622 * @brief Parse a strictly positive image dimension from a sidecar field.
623 * @param text Decimal token.
624 * @param value Receives the dimension on complete conversion.
625 * @return true when nonzero and representable as unsigned int; false otherwise.
626 * @details Rejecting zero/overflow dimensions before indexing protects consumers
627 * that use the sidecar to size geographic pixel transforms.
628 */
629static bool parse_geo_dimension(const char *text, unsigned int *value)
630{
631 errno = 0;
632 char *end = NULL;
633 unsigned long parsed = strtoul(text, &end, 10);
634 if (end == text || errno == ERANGE || parsed == 0 || parsed > UINT32_MAX
635 || *trim_whitespace(end) != '\0') {
636 return false;
637 }
638 *value = (unsigned int)parsed;
639 return true;
640}
641
642int ear_heatmap_read_georef(const char *filename, struct ear_heatmap_georef *georef)
643{
644 if (filename == NULL || georef == NULL) { return -1; }
645 FILE *input = fopen(filename, "r");
646 if (input == NULL) { return -1; }
647
648 struct ear_heatmap_georef parsed = {0};
649 unsigned int seen = 0;
650 bool spot_lat_seen = false;
651 bool spot_lon_seen = false;
652 /* Bound each input line independently of the size of the sidecar. */
653 char line[256];
654 bool valid = true;
655 while (fgets(line, sizeof(line), input) != NULL) {
656 size_t length = strlen(line);
657 if (length > 0 && line[length - 1] != '\n' && !feof(input)) {
658 valid = false;
659 break;
660 }
661 char *entry = trim_whitespace(line);
662 if (*entry == '\0' || *entry == '#') { continue; }
663 char *separator = strchr(entry, '=');
664 if (separator == NULL) { valid = false; break; }
665 *separator = '\0';
666 char *key = trim_whitespace(entry);
667 char *value = trim_whitespace(separator + 1);
668 unsigned int bit = 0;
669 bool field_valid = true;
670 if (strcmp(key, "width_px") == 0) {
671 bit = 1U << 0;
672 field_valid = parse_geo_dimension(value, &parsed.width_px);
673 } else if (strcmp(key, "height_px") == 0) {
674 bit = 1U << 1;
675 field_valid = parse_geo_dimension(value, &parsed.height_px);
676 } else if (strcmp(key, "m_per_px") == 0) {
677 bit = 1U << 2;
678 field_valid = parse_geo_double(value, &parsed.m_per_px) && parsed.m_per_px > 0.0;
679 } else if (strcmp(key, "lat_center") == 0) {
680 bit = 1U << 3;
681 field_valid = parse_geo_double(value, &parsed.lat_center);
682 } else if (strcmp(key, "lon_center") == 0) {
683 bit = 1U << 4;
684 field_valid = parse_geo_double(value, &parsed.lon_center);
685 } else if (strcmp(key, "lat_north") == 0) {
686 bit = 1U << 5;
687 field_valid = parse_geo_double(value, &parsed.lat_north);
688 } else if (strcmp(key, "lon_west") == 0) {
689 bit = 1U << 6;
690 field_valid = parse_geo_double(value, &parsed.lon_west);
691 } else if (strcmp(key, "spot_lat") == 0) {
692 field_valid = !spot_lat_seen && parse_geo_double(value, &parsed.spot_lat);
693 if (field_valid) { spot_lat_seen = true; }
694 } else if (strcmp(key, "spot_lon") == 0) {
695 field_valid = !spot_lon_seen && parse_geo_double(value, &parsed.spot_lon);
696 if (field_valid) { spot_lon_seen = true; }
697 } else if (strcmp(key, "spot_level_db") == 0 || strcmp(key, "spot_confidence") == 0) {
698 double ignored = 0.0;
699 field_valid = parse_geo_double(value, &ignored);
700 }
701 if (!field_valid || (bit != 0 && (seen & bit) != 0)) {
702 valid = false;
703 break;
704 }
705 seen |= bit;
706 }
707 if (ferror(input) != 0) { valid = false; }
708 if (fclose(input) != 0) { valid = false; }
709 const unsigned int required = (1U << 7) - 1U;
710 if (!valid || seen != required || spot_lat_seen != spot_lon_seen
711 || fabs(parsed.lat_center) > 90.0 || fabs(parsed.lat_north) > 90.0
712 || fabs(parsed.lon_center) > 180.0 || fabs(parsed.lon_west) > 180.0
713 || (spot_lat_seen && (fabs(parsed.spot_lat) > 90.0 || fabs(parsed.spot_lon) > 180.0))) {
714 return -1;
715 }
716 parsed.has_spot = spot_lat_seen;
717 *georef = parsed;
718 return 0;
719}
#define DEG_TO_RAD
Definition ear_fusion.c:34
#define EARTH_RADIUS_M
Definition ear_fusion.c:33
#define HEATMAP_SCALE_STROKE_RADIUS_PX
#define HEATMAP_DB_LOG_BASE
Definition ear_heatmap.c:67
static void draw_disc(uint8_t *pixels, unsigned int width, unsigned int height, double cx, double cy, double radius, const uint8_t *rgb, bool ring)
Rasterize a clipped filled disc or annular stroke.
static char * trim_whitespace(char *text)
Trim leading/trailing whitespace in a mutable sidecar token.
#define HEATMAP_PALETTE_FIRST_WIDTH
Definition ear_heatmap.c:74
#define HEATMAP_MIN_INTERPOLATION_WEIGHT
Definition ear_heatmap.c:66
#define HEATMAP_PATH_CAPACITY
Definition ear_heatmap.c:54
static uint8_t heatmap_pixels[HEATMAP_MAX_OUTPUT_PX *HEATMAP_MAX_OUTPUT_PX *HEATMAP_RGB_CHANNELS_U]
static void heatmap_jpeg_error_exit(j_common_ptr info)
Turn a fatal libjpeg callback into a local encoder failure.
#define HEATMAP_RING_STROKE_PX
Definition ear_heatmap.c:90
#define HEATMAP_PALETTE_BLUE_FIRST_RISE
Definition ear_heatmap.c:82
#define HEATMAP_BOUND_INITIALIZER
Definition ear_heatmap.c:57
#define HEATMAP_MIN_CELL_M
Definition ear_heatmap.c:41
#define HEATMAP_PALETTE_CHANNEL_HIGH
Definition ear_heatmap.c:78
#define HEATMAP_POWER_DB_PER_DECADE
Definition ear_heatmap.c:68
#define HEATMAP_PALETTE_BLUE_SECOND_FALL
Definition ear_heatmap.c:87
#define HEATMAP_PALETTE_GREEN_LAST_FALL
Definition ear_heatmap.c:88
static void draw_dot(uint8_t *pixels, unsigned int width, unsigned int height, double cx, double cy)
Draw one observation as a white subpixel core with a dark outline.
#define HEATMAP_DOT_OUTER_RADIUS_PX
Definition ear_heatmap.c:92
#define HEATMAP_PALETTE_SECOND_WIDTH
Definition ear_heatmap.c:75
#define HEATMAP_SCALE_MAX_WIDTH_FRACTION
#define HEATMAP_CELLS_PER_AGL
Definition ear_heatmap.c:61
#define HEATMAP_PALETTE_GREEN_SECOND_RISE
Definition ear_heatmap.c:85
#define HEATMAP_POSE_LATITUDE_EPSILON_DEG
Definition ear_heatmap.c:58
#define HEATMAP_FLAT_RANGE_DB
Definition ear_heatmap.c:69
int ear_heatmap_read_georef(const char *filename, struct ear_heatmap_georef *georef)
Read the georeference sidecar emitted by the heatmap renderer.
#define HEATMAP_RGB_MAX_F
Definition ear_heatmap.c:53
static double heatmap_field[HEATMAP_MAX_CELLS *HEATMAP_MAX_CELLS]
static void colormap(double t, uint8_t *rgb)
Map a normalized relative level to the preserved three-color ramp.
#define HEATMAP_PALETTE_CHANNEL_LOW
Definition ear_heatmap.c:77
#define HEATMAP_SCALE_OUTLINE_RADIUS_PX
static pthread_mutex_t heatmap_mutex
#define HEATMAP_MAX_CELLS
Definition ear_heatmap.c:42
static double clamp01(double v)
Clamp a normalized coverage/intensity value to its legal blend interval.
#define HEATMAP_SUFFIX_LENGTH
Definition ear_heatmap.c:55
#define HEATMAP_SPOT_ARM_GAP_PX
Definition ear_heatmap.c:96
#define HEATMAP_DISPLAY_RANGE_DB
Definition ear_heatmap.c:70
#define HEATMAP_FOOTPRINT_SIGMA_DIVISOR
Definition ear_heatmap.c:62
#define HEATMAP_PALETTE_BLUE_MIDDLE
Definition ear_heatmap.c:86
#define HEATMAP_RGB_CHANNELS
Definition ear_heatmap.c:50
#define HEATMAP_MIN_USABLE_AGL_M
Definition ear_heatmap.c:59
static void write_georef(const char *filename, unsigned int width, unsigned int height, double lat_c, double lon_c, double cos_lat, double half_e, double half_n, double m_per_px, const struct ear_loudest_spot *spot)
Write the georeference sidecar for a successful north-up JPEG.
#define HEATMAP_MIN_SAMPLES
Definition ear_heatmap.c:45
#define HEATMAP_RGB_MAX
Definition ear_heatmap.c:52
#define HEATMAP_PALETTE_FIRST_END
Definition ear_heatmap.c:72
static int encode_jpeg(const char *filename, const uint8_t *pixels, unsigned int width, unsigned int height)
Encode caller-owned RGB pixels as a JPEG.
#define HEATMAP_SPOT_ARM_RADIUS_PX
Definition ear_heatmap.c:98
#define HEATMAP_MAX_OUTPUT_PX
Definition ear_heatmap.c:43
#define HEATMAP_DOT_REACH_PX
Definition ear_heatmap.c:91
static int heatmap_write(const char *filename, const struct ear_sample *samples, size_t count, const struct ear_loudest_spot *spot, bool decorate)
Render the shared measured field with optional human-facing markers.
#define HEATMAP_PALETTE_SECOND_END
Definition ear_heatmap.c:73
#define HEATMAP_SPOT_OUTLINE_RADIUS_PX
Definition ear_heatmap.c:97
#define HEATMAP_SPOT_CENTER_RADIUS_PX
Definition ear_heatmap.c:99
#define HEATMAP_SPOT_GREEN
Definition ear_heatmap.c:93
#define HEATMAP_MIN_DEPOSIT_WEIGHT
Definition ear_heatmap.c:65
#define HEATMAP_SPOT_RING_RADIUS_PX
Definition ear_heatmap.c:94
#define HEATMAP_MIN_HALF_EXTENT_CELLS
Definition ear_heatmap.c:63
#define HEATMAP_QUALITY
Definition ear_heatmap.c:44
#define HEATMAP_SCALE_TICK_HALF_HEIGHT_PX
static bool parse_geo_double(const char *text, double *value)
Parse one finite number from a bounded sidecar value token.
#define HEATMAP_PALETTE_LAST_WIDTH
Definition ear_heatmap.c:76
#define HEATMAP_SCALE_BOTTOM_FRACTION
#define HEATMAP_FALLBACK_AGL_M
Definition ear_heatmap.c:60
#define HEATMAP_PALETTE_GREEN_FIRST_RISE
Definition ear_heatmap.c:81
static double heatmap_weight[HEATMAP_MAX_CELLS *HEATMAP_MAX_CELLS]
#define HEATMAP_PALETTE_GREEN_MIDDLE
Definition ear_heatmap.c:84
static bool parse_geo_dimension(const char *text, unsigned int *value)
Parse a strictly positive image dimension from a sidecar field.
#define HEATMAP_RGB_CHANNELS_U
Definition ear_heatmap.c:51
#define HEATMAP_PALETTE_RED_SECOND_RISE
Definition ear_heatmap.c:83
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.
#define HEATMAP_SCALE_LENGTH_M
#define HEATMAP_SCALE_LEFT_FRACTION
#define HEATMAP_GAUSSIAN_REACH_SIGMAS
Definition ear_heatmap.c:64
#define HEATMAP_SPOT_ARM_LENGTH_PX
Definition ear_heatmap.c:95
#define HEATMAP_PALETTE_BLUE_START
Definition ear_heatmap.c:79
#define HEATMAP_SUFFIX_STORAGE
Definition ear_heatmap.c:56
#define HEATMAP_PALETTE_GREEN_START
Definition ear_heatmap.c:80
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.
#define EAR_HEATMAP_NO_DATA_GREEN
Definition ear_heatmap.h:30
#define EAR_HEATMAP_NO_DATA_RED
Definition ear_heatmap.h:29
#define EAR_HEATMAP_NO_DATA_BLUE
Definition ear_heatmap.h:31
static struct ear_sample samples[EAR_MAX_SAMPLES]
#define EAR_MAX_SAMPLES
Definition earcam_core.h:34
struct jpeg_compress_struct encoder
Definition lwir_image.c:59
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
struct jpeg_error_mgr error
Definition lwir_image.c:60
static size_t count
Definition pose_log.c:79
static FILE * output
Definition pose_log.c:77
Validated geographic placement metadata shared by heatmap consumers.
Definition ear_heatmap.h:38
unsigned int width_px
Definition ear_heatmap.h:39
unsigned int height_px
Definition ear_heatmap.h:40
Estimated ground source, not a surveyed target or guaranteed alarm detection.
Definition earcam_core.h:37
One audio window associated with microphone position and provenance.
Definition earcam_core.h:55
double lat_deg
Definition earcam_core.h:58
double agl_m
Definition earcam_core.h:60
double lon_deg
Definition earcam_core.h:59
double level_db
Definition earcam_core.h:62
Per-encode libjpeg callback state and recovery point.
struct jpeg_error_mgr manager
bool valid
Definition usher.c:537