Bounded, north-up acoustic evidence rendering and JPEG georeference sidecars. More...
#include "ear_heatmap.h"#include <ctype.h>#include <errno.h>#include <float.h>#include <math.h>#include <pthread.h>#include <setjmp.h>#include <stdint.h>#include <stdio.h>#include <stdlib.h>#include <string.h>#include <jpeglib.h>
Go to the source code of this file.
Data Structures | |
| struct | heatmap_jpeg_error |
| Per-encode libjpeg callback state and recovery point. More... | |
Functions | |
| static void | heatmap_jpeg_error_exit (j_common_ptr info) |
| Turn a fatal libjpeg callback into a local encoder failure. | |
| static void | colormap (double t, uint8_t *rgb) |
| Map a normalized relative level to the preserved three-color ramp. | |
| 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 double | clamp01 (double v) |
| Clamp a normalized coverage/intensity value to its legal blend interval. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| static char * | trim_whitespace (char *text) |
| Trim leading/trailing whitespace in a mutable sidecar token. | |
| static bool | parse_geo_double (const char *text, double *value) |
| Parse one finite number from a bounded sidecar value token. | |
| static bool | parse_geo_dimension (const char *text, unsigned int *value) |
| Parse a strictly positive image dimension from a sidecar field. | |
| int | ear_heatmap_read_georef (const char *filename, struct ear_heatmap_georef *georef) |
| Read the georeference sidecar emitted by the heatmap renderer. | |
Variables | |
| static pthread_mutex_t | heatmap_mutex = PTHREAD_MUTEX_INITIALIZER |
| static double | heatmap_field [HEATMAP_MAX_CELLS *HEATMAP_MAX_CELLS] |
| static double | heatmap_weight [HEATMAP_MAX_CELLS *HEATMAP_MAX_CELLS] |
| static uint8_t | heatmap_pixels [HEATMAP_MAX_OUTPUT_PX *HEATMAP_MAX_OUTPUT_PX *HEATMAP_RGB_CHANNELS_U] |
Detailed Description
Bounded, north-up acoustic evidence rendering and JPEG georeference sidecars.
Deposit measured linear power into a height-dependent Gaussian grid, normalize by deposited weight, then display the loud end of the dB range. Smoothing is a visualization heuristic, not a measured microphone beam model. The decorated image explains the track; the undecorated field supports overlays.
Definition in file ear_heatmap.c.
Macro Definition Documentation
◆ DEG_TO_RAD
| #define DEG_TO_RAD 0.017453292519943295 |
Definition at line 47 of file ear_heatmap.c.
◆ EARTH_RADIUS_M
| #define EARTH_RADIUS_M 6378137.0 |
Definition at line 46 of file ear_heatmap.c.
◆ HEATMAP_BOUND_INITIALIZER
| #define HEATMAP_BOUND_INITIALIZER 1e9 |
Definition at line 57 of file ear_heatmap.c.
◆ HEATMAP_CELLS_PER_AGL
| #define HEATMAP_CELLS_PER_AGL 4.0 |
Definition at line 61 of file ear_heatmap.c.
◆ HEATMAP_DB_LOG_BASE
| #define HEATMAP_DB_LOG_BASE 10.0 |
Definition at line 67 of file ear_heatmap.c.
◆ HEATMAP_DISPLAY_RANGE_DB
| #define HEATMAP_DISPLAY_RANGE_DB 20.0 |
Definition at line 70 of file ear_heatmap.c.
◆ HEATMAP_DOT_OUTER_RADIUS_PX
| #define HEATMAP_DOT_OUTER_RADIUS_PX 2.0 |
Definition at line 92 of file ear_heatmap.c.
◆ HEATMAP_DOT_REACH_PX
| #define HEATMAP_DOT_REACH_PX 2.5 |
Definition at line 91 of file ear_heatmap.c.
◆ HEATMAP_FALLBACK_AGL_M
| #define HEATMAP_FALLBACK_AGL_M 10.0 |
Definition at line 60 of file ear_heatmap.c.
◆ HEATMAP_FLAT_RANGE_DB
| #define HEATMAP_FLAT_RANGE_DB 1.0 |
Definition at line 69 of file ear_heatmap.c.
◆ HEATMAP_FOOTPRINT_SIGMA_DIVISOR
| #define HEATMAP_FOOTPRINT_SIGMA_DIVISOR 2.0 |
Definition at line 62 of file ear_heatmap.c.
◆ HEATMAP_GAUSSIAN_REACH_SIGMAS
| #define HEATMAP_GAUSSIAN_REACH_SIGMAS 3.0 |
Definition at line 64 of file ear_heatmap.c.
◆ HEATMAP_MAX_CELLS
| #define HEATMAP_MAX_CELLS 96U |
Definition at line 42 of file ear_heatmap.c.
◆ HEATMAP_MAX_OUTPUT_PX
| #define HEATMAP_MAX_OUTPUT_PX 768U |
Definition at line 43 of file ear_heatmap.c.
◆ HEATMAP_MIN_CELL_M
| #define HEATMAP_MIN_CELL_M 1.0 |
Definition at line 41 of file ear_heatmap.c.
◆ HEATMAP_MIN_DEPOSIT_WEIGHT
| #define HEATMAP_MIN_DEPOSIT_WEIGHT 1e-3 |
Definition at line 65 of file ear_heatmap.c.
◆ HEATMAP_MIN_HALF_EXTENT_CELLS
| #define HEATMAP_MIN_HALF_EXTENT_CELLS 3.0 |
Definition at line 63 of file ear_heatmap.c.
◆ HEATMAP_MIN_INTERPOLATION_WEIGHT
| #define HEATMAP_MIN_INTERPOLATION_WEIGHT 1e-6 |
Definition at line 66 of file ear_heatmap.c.
◆ HEATMAP_MIN_SAMPLES
| #define HEATMAP_MIN_SAMPLES 3U |
Definition at line 45 of file ear_heatmap.c.
◆ HEATMAP_MIN_USABLE_AGL_M
| #define HEATMAP_MIN_USABLE_AGL_M 0.5 |
Definition at line 59 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_BLUE_FIRST_RISE
| #define HEATMAP_PALETTE_BLUE_FIRST_RISE 0.55 |
Definition at line 82 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_BLUE_MIDDLE
| #define HEATMAP_PALETTE_BLUE_MIDDLE 0.90 |
Definition at line 86 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_BLUE_SECOND_FALL
| #define HEATMAP_PALETTE_BLUE_SECOND_FALL 0.85 |
Definition at line 87 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_BLUE_START
| #define HEATMAP_PALETTE_BLUE_START 0.35 |
Definition at line 79 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_CHANNEL_HIGH
| #define HEATMAP_PALETTE_CHANNEL_HIGH 0.95 |
Definition at line 78 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_CHANNEL_LOW
| #define HEATMAP_PALETTE_CHANNEL_LOW 0.05 |
Definition at line 77 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_FIRST_END
| #define HEATMAP_PALETTE_FIRST_END 0.33 |
Piecewise palette: dark blue -> cyan -> yellow -> red; channels are normalized.
Definition at line 72 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_FIRST_WIDTH
| #define HEATMAP_PALETTE_FIRST_WIDTH 0.33 |
Definition at line 74 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_GREEN_FIRST_RISE
| #define HEATMAP_PALETTE_GREEN_FIRST_RISE 0.70 |
Definition at line 81 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_GREEN_LAST_FALL
| #define HEATMAP_PALETTE_GREEN_LAST_FALL 0.80 |
Definition at line 88 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_GREEN_MIDDLE
| #define HEATMAP_PALETTE_GREEN_MIDDLE 0.80 |
Definition at line 84 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_GREEN_SECOND_RISE
| #define HEATMAP_PALETTE_GREEN_SECOND_RISE 0.15 |
Definition at line 85 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_GREEN_START
| #define HEATMAP_PALETTE_GREEN_START 0.10 |
Definition at line 80 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_LAST_WIDTH
| #define HEATMAP_PALETTE_LAST_WIDTH 0.34 |
Definition at line 76 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_RED_SECOND_RISE
| #define HEATMAP_PALETTE_RED_SECOND_RISE 0.90 |
Definition at line 83 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_SECOND_END
| #define HEATMAP_PALETTE_SECOND_END 0.66 |
Definition at line 73 of file ear_heatmap.c.
◆ HEATMAP_PALETTE_SECOND_WIDTH
| #define HEATMAP_PALETTE_SECOND_WIDTH 0.33 |
Definition at line 75 of file ear_heatmap.c.
◆ HEATMAP_PATH_CAPACITY
| #define HEATMAP_PATH_CAPACITY 512 |
Definition at line 54 of file ear_heatmap.c.
◆ HEATMAP_POSE_LATITUDE_EPSILON_DEG
| #define HEATMAP_POSE_LATITUDE_EPSILON_DEG 1e-6 |
Definition at line 58 of file ear_heatmap.c.
◆ HEATMAP_POWER_DB_PER_DECADE
| #define HEATMAP_POWER_DB_PER_DECADE 10.0 |
Definition at line 68 of file ear_heatmap.c.
◆ HEATMAP_QUALITY
| #define HEATMAP_QUALITY 90 |
Definition at line 44 of file ear_heatmap.c.
◆ HEATMAP_RGB_CHANNELS
| #define HEATMAP_RGB_CHANNELS 3 |
Policy values below retain existing output geometry, colors and byte values.
Definition at line 50 of file ear_heatmap.c.
◆ HEATMAP_RGB_CHANNELS_U
| #define HEATMAP_RGB_CHANNELS_U 3U |
Definition at line 51 of file ear_heatmap.c.
◆ HEATMAP_RGB_MAX
| #define HEATMAP_RGB_MAX 255 |
Definition at line 52 of file ear_heatmap.c.
◆ HEATMAP_RGB_MAX_F
| #define HEATMAP_RGB_MAX_F 255.0 |
Definition at line 53 of file ear_heatmap.c.
◆ HEATMAP_RING_STROKE_PX
| #define HEATMAP_RING_STROKE_PX 2.0 |
Marker and bar dimensions are output pixels, not localization error bounds.
Definition at line 90 of file ear_heatmap.c.
◆ HEATMAP_SCALE_BOTTOM_FRACTION
| #define HEATMAP_SCALE_BOTTOM_FRACTION 0.06 |
Definition at line 103 of file ear_heatmap.c.
◆ HEATMAP_SCALE_LEFT_FRACTION
| #define HEATMAP_SCALE_LEFT_FRACTION 0.04 |
Definition at line 102 of file ear_heatmap.c.
◆ HEATMAP_SCALE_LENGTH_M
| #define HEATMAP_SCALE_LENGTH_M 50.0 |
Definition at line 100 of file ear_heatmap.c.
◆ HEATMAP_SCALE_MAX_WIDTH_FRACTION
| #define HEATMAP_SCALE_MAX_WIDTH_FRACTION 0.6 |
Definition at line 101 of file ear_heatmap.c.
◆ HEATMAP_SCALE_OUTLINE_RADIUS_PX
| #define HEATMAP_SCALE_OUTLINE_RADIUS_PX 2.5 |
Definition at line 104 of file ear_heatmap.c.
◆ HEATMAP_SCALE_STROKE_RADIUS_PX
| #define HEATMAP_SCALE_STROKE_RADIUS_PX 1.2 |
Definition at line 105 of file ear_heatmap.c.
◆ HEATMAP_SCALE_TICK_HALF_HEIGHT_PX
| #define HEATMAP_SCALE_TICK_HALF_HEIGHT_PX 6 |
Definition at line 106 of file ear_heatmap.c.
◆ HEATMAP_SPOT_ARM_GAP_PX
| #define HEATMAP_SPOT_ARM_GAP_PX 4.0 |
Definition at line 96 of file ear_heatmap.c.
◆ HEATMAP_SPOT_ARM_LENGTH_PX
| #define HEATMAP_SPOT_ARM_LENGTH_PX 22.0 |
Definition at line 95 of file ear_heatmap.c.
◆ HEATMAP_SPOT_ARM_RADIUS_PX
| #define HEATMAP_SPOT_ARM_RADIUS_PX 1.2 |
Definition at line 98 of file ear_heatmap.c.
◆ HEATMAP_SPOT_CENTER_RADIUS_PX
| #define HEATMAP_SPOT_CENTER_RADIUS_PX 1.5 |
Definition at line 99 of file ear_heatmap.c.
◆ HEATMAP_SPOT_GREEN
| #define HEATMAP_SPOT_GREEN 40 |
Definition at line 93 of file ear_heatmap.c.
◆ HEATMAP_SPOT_OUTLINE_RADIUS_PX
| #define HEATMAP_SPOT_OUTLINE_RADIUS_PX 2.4 |
Definition at line 97 of file ear_heatmap.c.
◆ HEATMAP_SPOT_RING_RADIUS_PX
| #define HEATMAP_SPOT_RING_RADIUS_PX 9.0 |
Definition at line 94 of file ear_heatmap.c.
◆ HEATMAP_SUFFIX_LENGTH
| #define HEATMAP_SUFFIX_LENGTH 4 |
Definition at line 55 of file ear_heatmap.c.
◆ HEATMAP_SUFFIX_STORAGE
| #define HEATMAP_SUFFIX_STORAGE 5 |
Definition at line 56 of file ear_heatmap.c.
Function Documentation
◆ clamp01()
|
static |
Clamp a normalized coverage/intensity value to its legal blend interval.
- Parameters
-
v Candidate weight or palette position.
- Returns
- v constrained to [0, 1].
Definition at line 211 of file ear_heatmap.c.
◆ colormap()
|
static |
Map a normalized relative level to the preserved three-color ramp.
- Parameters
-
t Display position; out-of-range values are clamped to [0, 1]. rgb Receives red, green and blue 8-bit channels.
The palette represents relative levels within this image; it is not a calibrated sound-pressure scale and its breakpoints remain fixed for compatibility.
Definition at line 144 of file ear_heatmap.c.
◆ draw_disc()
|
static |
Rasterize a clipped filled disc or annular stroke.
- Parameters
-
pixels Interleaved RGB destination. width Destination width in pixels. height Destination height in pixels. cx Marker center X, including fractional-pixel position. cy Marker center Y, including fractional-pixel position. radius Outer marker radius. rgb Opaque marker color. ring Draw a ring instead of a filled disc when true.
Pixel-center distances keep fractional marker placement symmetric; explicit clipping prevents edge markers from indexing outside the fixed raster.
Definition at line 183 of file ear_heatmap.c.
◆ draw_dot()
|
static |
Draw one observation as a white subpixel core with a dark outline.
- Parameters
-
pixels Interleaved RGB destination. width Destination width in pixels. height Destination height in pixels. cx Observation center X in fractional output pixels. cy Observation center Y in fractional output pixels.
Fractional coverage preserves the measured pose's subpixel placement; the outline separates a location mark from the relative heat palette.
Definition at line 226 of file ear_heatmap.c.
◆ ear_heatmap_read_georef()
| int ear_heatmap_read_georef | ( | const char * | filename, |
| struct ear_heatmap_georef * | georef ) |
Read the georeference sidecar emitted by the heatmap renderer.
- Parameters
-
filename Path to the .geo sidecar. georef Receives validated dimensions, projection and optional spot.
- Returns
- 0 on success; -1 for invalid arguments, malformed data or I/O error.
Required dimensions, scale and edge/origin coordinates are validated before publication to the caller; partial parses never replace its struct. Duplicate fields, oversized lines and incomplete optional spot pairs fail.
Definition at line 642 of file ear_heatmap.c.
◆ ear_heatmap_write()
| 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.
- Parameters
-
filename Output path; an adjacent .geo sidecar is attempted after JPEG success. samples Borrowed, immutable geotagged windows; not retained after the call. count Window count; at least three usable finite, unclipped windows are required. spot Optional borrowed estimate; only valid estimates receive a marker.
- Returns
- 0 for a successfully written JPEG, -1 for insufficient data or file/codec failure.
Track dots, an estimated-source marker and a scale bar aid interpretation. Calls serialize on bounded shared scratch storage. Grid cells are roughly AGL/4; bilinear upsampling adds visual smoothness, not measurement resolution.
- Warning
- Sidecar write failure does not change the return status. Neither the smoothed field nor the marker demonstrates localization accuracy or alarm presence.
Definition at line 574 of file ear_heatmap.c.
◆ ear_heatmap_write_field()
| 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.
- Parameters
-
filename JPEG path; a best-effort .geo sidecar supplies overlay placement. samples Borrowed immutable acoustic windows. count Number of supplied windows, with the same usable-data gate as ear_heatmap_write(). spot Optional estimate retained in sidecar metadata, not drawn into pixels.
- Returns
- 0 for JPEG success, -1 for insufficient usable data or file/codec failure.
Use the same interpolation and shared workspace as the decorated renderer, keeping annotation pixels out of the field used for overlays.
- See also
- ear_heatmap_write for locking, resolution and sidecar-status caveats.
Definition at line 580 of file ear_heatmap.c.
◆ encode_jpeg()
|
static |
Encode caller-owned RGB pixels as a JPEG.
- Parameters
-
filename Output path. pixels Borrowed row-major interleaved RGB raster. width Raster width in pixels. height Raster height in pixels.
- Returns
- 0 after encoding and close succeed; -1 for open/codec/close failures.
Scanlines are passed directly to libjpeg, so the bounded renderer does not need another image-sized copy.
Definition at line 310 of file ear_heatmap.c.
◆ heatmap_jpeg_error_exit()
|
static |
Turn a fatal libjpeg callback into a local encoder failure.
- Parameters
-
info Codec state whose error manager stores the recovery target.
Default libjpeg handling terminates the process; USHER must instead report a failed visualization and remain available for camera/UART work.
Definition at line 131 of file ear_heatmap.c.
◆ heatmap_write()
|
static |
Render the shared measured field with optional human-facing markers.
- Parameters
-
filename Destination JPEG. samples Borrowed, immutable geotagged EAR windows. count Supplied window count. spot Optional fused loudest-spot estimate. decorate Draw observation dots, estimate crosshair and scale bar when true.
- Returns
- 0 on successful JPEG encode; -1 for insufficient usable samples or I/O failure.
One mutex protects the shared grids and pixels until libjpeg finishes reading them. The AGL-derived grid is bounded; bilinear upsampling smooths display pixels but does not increase the microphone's spatial resolution.
Definition at line 356 of file ear_heatmap.c.
◆ parse_geo_dimension()
|
static |
Parse a strictly positive image dimension from a sidecar field.
- Parameters
-
text Decimal token. value Receives the dimension on complete conversion.
- Returns
- true when nonzero and representable as unsigned int; false otherwise.
Rejecting zero/overflow dimensions before indexing protects consumers that use the sidecar to size geographic pixel transforms.
Definition at line 629 of file ear_heatmap.c.
◆ parse_geo_double()
|
static |
Parse one finite number from a bounded sidecar value token.
- Parameters
-
text Token after key/value splitting. value Receives the value only if the complete trimmed token is valid.
- Returns
- false for empty, non-finite, range-error or partially consumed input.
Rejecting trailing text prevents plausible prefixes such as 48junk from silently changing the overlay's geographic placement.
Definition at line 609 of file ear_heatmap.c.
◆ trim_whitespace()
|
static |
Trim leading/trailing whitespace in a mutable sidecar token.
- Parameters
-
text NUL-terminated buffer; trailing whitespace is replaced by NUL.
- Returns
- Pointer to the first non-whitespace character in the same storage.
In-place trimming keeps the sidecar reader bounded and validates the unconsumed suffix left by numeric conversion.
Definition at line 593 of file ear_heatmap.c.
◆ write_georef()
|
static |
Write the georeference sidecar for a successful north-up JPEG.
- Parameters
-
filename JPEG path whose .jpg suffix becomes .geo. width Encoded output width in pixels. height Encoded output height in pixels. lat_c Local projection center latitude, degrees. lon_c Local projection center longitude, degrees. cos_lat Longitude-to-metre scale at the center latitude. half_e East half-extent of the raster, metres. half_n North half-extent of the raster, metres. m_per_px Local metres per encoded output pixel. spot Optional solved spot metadata; null/invalid estimates add no spot keys.
The sidecar uses the same local equirectangular frame as rasterization. Its write is best-effort so a valid JPEG is retained if metadata storage fails; map consumers requiring both artifacts validate the sidecar separately.
Definition at line 265 of file ear_heatmap.c.
Variable Documentation
◆ heatmap_field
|
static |
Definition at line 111 of file ear_heatmap.c.
◆ heatmap_mutex
|
static |
Definition at line 110 of file ear_heatmap.c.
◆ heatmap_pixels
|
static |
Definition at line 113 of file ear_heatmap.c.
◆ heatmap_weight
|
static |
Definition at line 112 of file ear_heatmap.c.