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

Render EARcam acoustic fields over cached or downloaded map tiles. More...

#include "version.h"
#include "modules/ear_cam/ear_heatmap.h"
#include <ctype.h>
#include <errno.h>
#include <math.h>
#include <setjmp.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <jpeglib.h>
#include <sys/stat.h>
#include <sys/wait.h>
#include <unistd.h>
Include dependency graph for ear_heatmap_overlay.c:

Go to the source code of this file.

Data Structures

struct  rgb_image
 Non-owning view of a bounded interleaved RGB workspace. More...
struct  point
 One timestamped geographic position for a replay annotation. More...
struct  point_list
 Fixed-capacity, non-owning view over parsed session/track points. More...
struct  obstacle
 One optional terrain-height cell supplied for visual context. More...
struct  obstacle_list
 Bounded view over LiDAR cells and their inferred regular spacing. More...
struct  options
 Validated capture and reporting policy, fixed before the sample loop. More...
struct  jpeg_failure

Macros

#define _POSIX_C_SOURCE   200809L
#define TILE_SIZE   256U
#define PI   3.14159265358979323846
#define EARTH_RADIUS_M   6378137.0
#define DEG_TO_RAD   0.017453292519943295
#define MAX_PATH_LENGTH   4096U
#define MAX_TILE_COUNT   4096U
#define MAX_OUTPUT_PIXELS   16000000U
#define MAX_INPUT_PIXELS   1048576U
#define MAX_CSV_POINTS   200000U
#define MAX_CSV_LINE   8192U
#define DEFAULT_MAX_ZOOM   20U
#define DEFAULT_MARGIN_M   15.0
#define DEFAULT_ALPHA   0.55
#define DEFAULT_TRACK_GAP_S   1.5
#define JPEG_QUALITY   92

Functions

static void jpeg_error_exit (j_common_ptr info)
 Convert libjpeg's fatal callback into a jump to the active operation.
static void image_free (struct rgb_image *image)
 Invalidate an RGB view before its shared workspace is reused.
static int image_read_jpeg (const char *path, struct rgb_image *image)
 Decode one JPEG into the caller's bounded RGB workspace.
static int image_write_jpeg (const char *path, const struct rgb_image *image)
 Encode a bounded RGB view to a JPEG file.
static bool parse_double (const char *text, double *value)
 Parse a finite floating-point token in full.
static bool parse_unsigned (const char *text, unsigned int *value)
 Parse an unsigned integer option without accepting suffix characters.
static void print_help (const char *program)
 Print command synopsis and defaults from the same option vocabulary parsed below.
static bool parse_options (int argc, char **argv, struct options *options)
 Parse one positional heatmap and the supported optional controls.
static void mercator_xy (double lat, double lon, unsigned int zoom, double *x, double *y)
 Project latitude/longitude into fractional Web Mercator tile coordinates.
static double mercator_m_per_pixel (double lat, unsigned int zoom)
 Estimate ground metres per tile pixel at a latitude.
static unsigned int choose_zoom (const struct ear_heatmap_georef *geo, unsigned int max_zoom)
 Select the first basemap zoom at least as detailed as the heatmap.
static bool parse_location (const char *text, bool with_radius, double *lat, double *lon, double *radius)
 Parse LAT,LON or LAT,LON,RADIUS_M into bounded geographic values.
static int make_stem_path (const char *path, const char *suffix, char *output, size_t capacity)
 Derive a sibling .geo, _field.jpg or _sat.jpg path from an image.
static int default_cache_path (char *path, size_t capacity)
 Resolve the Paparazzi GCS map-cache root from XDG environment settings.
static int make_directories (const char *path)
 Create parent directories for a tile file without treating the file as a directory.
static void gcs_key (unsigned int x, unsigned int y, unsigned int zoom, char *key, size_t capacity)
 Encode an XYZ address using Paparazzi's legacy Google quadkey alphabet.
static int tile_path (const struct options *options, unsigned int x, unsigned int y, unsigned int zoom, char *path, size_t capacity)
 Select the first known local filename for an XYZ source tile.
static int download_tile (const struct options *options, unsigned int x, unsigned int y, unsigned int zoom, const char *path)
 Download one cache miss with the existing curl executable.
static int fetch_tile (const struct options *options, unsigned int x, unsigned int y, unsigned int zoom, struct rgb_image *tile)
 Read a local hit, fetch a miss if permitted, and decode one 256x256 tile.
static int copy_tile_to_output (const struct rgb_image *tile, struct rgb_image *output, int tile_x, int tile_y, int crop_x, int crop_y)
 Copy only the part of a source tile intersecting the cropped output.
static double mercator_latitude (double tile_y, unsigned int zoom)
 Invert fractional Web Mercator tile Y into a geographic latitude.
static void composite_heatmap (struct rgb_image *base, const struct rgb_image *field, const struct ear_heatmap_georef *geo, unsigned int zoom, int crop_x, int crop_y, double alpha)
 Resample the local equirectangular heat field onto the Mercator tile mosaic.
static void put_blended_pixel (struct rgb_image *image, int x, int y, uint8_t red, uint8_t green, uint8_t blue, double alpha)
 Blend one annotation pixel while clipping out-of-image coordinates.
static void draw_brush (struct rgb_image *image, int x, int y, int width, uint8_t red, uint8_t green, uint8_t blue, double alpha)
 Stamp a square brush centered at an integer pixel.
static void draw_line (struct rgb_image *image, int x0, int y0, int x1, int y1, int width, uint8_t red, uint8_t green, uint8_t blue, double alpha)
 Draw a raster line with an integer Bresenham walk.
static void draw_circle (struct rgb_image *image, int cx, int cy, int radius, int width, uint8_t red, uint8_t green, uint8_t blue, double alpha)
 Draw a filled disc or clipped ring with a fixed-width stroke.
static void draw_crosshair (struct rgb_image *image, int x, int y, uint8_t red, uint8_t green, uint8_t blue)
 Draw a distinct, high-contrast marker for the estimated loudest spot.
static void draw_diamond (struct rgb_image *image, int x, int y, int radius, uint8_t red, uint8_t green, uint8_t blue)
 Draw the known simulation source as a shape distinct from the estimate.
static const uint8_t * glyph_rows (char character)
 Return one embedded 5x7 uppercase bitmap glyph.
static void draw_text_pass (struct rgb_image *image, int x, int y, const char *text, unsigned int scale, uint8_t red, uint8_t green, uint8_t blue)
 Paint one foreground or outline pass of bitmap text.
static void draw_text (struct rgb_image *image, int x, int y, const char *text, uint8_t red, uint8_t green, uint8_t blue)
 Draw a small outlined label over arbitrary imagery.
static void pixel_location (double lat, double lon, double origin_x, double origin_y, unsigned int zoom, int *x, int *y)
 Convert a geographic annotation to pixels in the cropped tile mosaic.
static int append_point (struct point_list *list, const struct point *point)
 Append a point into caller-owned bounded storage.
static bool csv_number (const char *line, unsigned int column, double *value)
 Parse one complete numeric field from a bounded CSV row.
static int read_points (const char *path, bool session_log, struct point_list *points)
 Read geographic points from an EAR session or aircraft-track CSV.
static int header_column (const char *header, const char *name)
 Locate an exact field name in a CSV header without mutating the source.
static bool csv_column (const char *line, unsigned int column, double *value)
 Read one required numeric column from a LiDAR CSV row.
static int append_obstacle (struct obstacle_list *list, const struct obstacle *obstacle)
 Append one obstacle cell when fixed storage has room.
static int compare_double (const void *left, const void *right)
 Order projected eastings so adjacent positive deltas reveal cell pitch.
static int read_obstacles (const char *path, struct obstacle_list *obstacles, double *cell_size)
 Read the optional regular LiDAR height grid and infer its cell width.
static double haversine_m (double lat_a, double lon_a, double lat_b, double lon_b)
 Compute great-circle distance between two latitude/longitude points.
static void draw_log_points (struct rgb_image *image, const struct point_list *points, double origin_x, double origin_y, unsigned int zoom)
 Redraw sample locations as crisp dots over the blended sound field.
static void draw_track (struct rgb_image *image, const struct point_list *points, double origin_x, double origin_y, unsigned int zoom, double gap_s)
 Draw aircraft-track segments, breaking where fixes are too far apart.
static void draw_obstacles (struct rgb_image *image, const struct obstacle_list *obstacles, double cell_size, double m_per_deg_lat, double m_per_deg_lon, double origin_x, double origin_y, unsigned int zoom)
 Paint optional height-above-terrain cells over the output map.
static int build_output (const struct options *options, const struct ear_heatmap_georef *geo, const struct rgb_image *heat, struct rgb_image *output)
 Assemble basemap tiles, heatfield and optional annotations into one output raster.
int main (int argc, char **argv)
 Validate replay artifacts, compose the map context and write a JPEG.

Variables

static uint8_t input_pixels [(size_t) MAX_INPUT_PIXELS *3U]
 Reused input, tile and final RGB workspaces; avoid per-image allocator churn.
static uint8_t tile_pixels [(size_t) TILE_SIZE *TILE_SIZE *3U]
static uint8_t output_pixels [(size_t) MAX_OUTPUT_PIXELS *3U]
static struct point session_points [MAX_CSV_POINTS]
static struct point track_points [MAX_CSV_POINTS]
static struct obstacle obstacle_cells [MAX_CSV_POINTS]
static double obstacle_eastings [MAX_CSV_POINTS]

Detailed Description

Render EARcam acoustic fields over cached or downloaded map tiles.

Host-side review utility. It does not run in the MORA service or change acoustic samples, source estimates or flight-control decisions.

Definition in file ear_heatmap_overlay.c.

Macro Definition Documentation

◆ _POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Definition at line 18 of file ear_heatmap_overlay.c.

◆ DEFAULT_ALPHA

#define DEFAULT_ALPHA   0.55

Definition at line 58 of file ear_heatmap_overlay.c.

◆ DEFAULT_MARGIN_M

#define DEFAULT_MARGIN_M   15.0

Definition at line 57 of file ear_heatmap_overlay.c.

◆ DEFAULT_MAX_ZOOM

#define DEFAULT_MAX_ZOOM   20U

Review defaults: visual framing only; none of these imply spatial accuracy.

Definition at line 56 of file ear_heatmap_overlay.c.

◆ DEFAULT_TRACK_GAP_S

#define DEFAULT_TRACK_GAP_S   1.5

Definition at line 59 of file ear_heatmap_overlay.c.

◆ DEG_TO_RAD

#define DEG_TO_RAD   0.017453292519943295

Definition at line 47 of file ear_heatmap_overlay.c.

◆ EARTH_RADIUS_M

#define EARTH_RADIUS_M   6378137.0

Definition at line 46 of file ear_heatmap_overlay.c.

◆ JPEG_QUALITY

#define JPEG_QUALITY   92

Definition at line 60 of file ear_heatmap_overlay.c.

◆ MAX_CSV_LINE

#define MAX_CSV_LINE   8192U

Definition at line 54 of file ear_heatmap_overlay.c.

◆ MAX_CSV_POINTS

#define MAX_CSV_POINTS   200000U

Definition at line 53 of file ear_heatmap_overlay.c.

◆ MAX_INPUT_PIXELS

#define MAX_INPUT_PIXELS   1048576U

Definition at line 52 of file ear_heatmap_overlay.c.

◆ MAX_OUTPUT_PIXELS

#define MAX_OUTPUT_PIXELS   16000000U

Definition at line 51 of file ear_heatmap_overlay.c.

◆ MAX_PATH_LENGTH

#define MAX_PATH_LENGTH   4096U

Explicit I/O/image/CSV ceilings keep malformed inputs from growing memory unboundedly.

Definition at line 49 of file ear_heatmap_overlay.c.

◆ MAX_TILE_COUNT

#define MAX_TILE_COUNT   4096U

Definition at line 50 of file ear_heatmap_overlay.c.

◆ PI

#define PI   3.14159265358979323846

Definition at line 45 of file ear_heatmap_overlay.c.

◆ TILE_SIZE

#define TILE_SIZE   256U

Web Mercator XYZ tile geometry and local projection constants.

Definition at line 44 of file ear_heatmap_overlay.c.

Function Documentation

◆ append_obstacle()

int append_obstacle ( struct obstacle_list * list,
const struct obstacle * obstacle )
static

Append one obstacle cell when fixed storage has room.

Parameters
listBounded obstacle list view.
obstacleValidated cell to copy.
Returns
0 on append, -1 when the configured cell cap is reached.

Definition at line 1164 of file ear_heatmap_overlay.c.

◆ append_point()

int append_point ( struct point_list * list,
const struct point * point )
static

Append a point into caller-owned bounded storage.

Parameters
listPoint list view.
pointValidated point to copy.
Returns
0 on append, -1 when its fixed capacity is exhausted.

Definition at line 1065 of file ear_heatmap_overlay.c.

◆ build_output()

int build_output ( const struct options * options,
const struct ear_heatmap_georef * geo,
const struct rgb_image * heat,
struct rgb_image * output )
static

Assemble basemap tiles, heatfield and optional annotations into one output raster.

Parameters
optionsParsed cache, projection and annotation policy.
geoValidated local-projection footprint from the .geo sidecar.
heatUndecorated _field.jpg when present, otherwise the input JPEG.
outputReceives the final cropped raster in fixed output storage.
Returns
0 after composition, or -1 for malformed annotations, unsupported bounds, cache failures or capacity limits.

Bounds are computed before tile access; only intersecting tiles are assembled, heat pixels are projected individually, then crisp evidence layers are drawn on top. No step feeds back into acoustic measurements or navigation.

Definition at line 1352 of file ear_heatmap_overlay.c.

◆ choose_zoom()

unsigned int choose_zoom ( const struct ear_heatmap_georef * geo,
unsigned int max_zoom )
static

Select the first basemap zoom at least as detailed as the heatmap.

Parameters
geoHeatmap pixel scale and center latitude.
max_zoomHighest permitted map zoom.
Returns
Selected zoom, capped at max_zoom when the map remains coarser.

More detailed imagery cannot increase acoustic measurement resolution; this default avoids needless tile downloads at higher-than-useful zoom.

Definition at line 431 of file ear_heatmap_overlay.c.

◆ compare_double()

int compare_double ( const void * left,
const void * right )
static

Order projected eastings so adjacent positive deltas reveal cell pitch.

Definition at line 1172 of file ear_heatmap_overlay.c.

◆ composite_heatmap()

void composite_heatmap ( struct rgb_image * base,
const struct rgb_image * field,
const struct ear_heatmap_georef * geo,
unsigned int zoom,
int crop_x,
int crop_y,
double alpha )
static

Resample the local equirectangular heat field onto the Mercator tile mosaic.

Parameters
baseIn/out satellite RGB image.
fieldUndecorated EAR heatmap raster.
geoValidated sidecar footprint and scale.
zoomBasemap XYZ zoom shared by tile placement and output projection.
crop_xCropped image origin within the tile grid, pixels.
crop_yCropped image origin within the tile grid, pixels.
alphaOpacity for covered heatmap pixels.

Every basemap pixel is transformed back into the heatmap's local frame. This avoids stretching the field to fit a differently projected map and preserves the renderer's no-data color as transparent coverage rather than false evidence.

Definition at line 740 of file ear_heatmap_overlay.c.

◆ copy_tile_to_output()

int copy_tile_to_output ( const struct rgb_image * tile,
struct rgb_image * output,
int tile_x,
int tile_y,
int crop_x,
int crop_y )
static

Copy only the part of a source tile intersecting the cropped output.

Parameters
tileDecoded fixed-size map tile.
outputBounded destination mosaic.
tile_xAbsolute XYZ column.
tile_yAbsolute XYZ row.
crop_xCrop origin in the assembled tile-grid pixels.
crop_yCrop origin in the assembled tile-grid pixels.
Returns
0 after a clipped copy; nonintersecting edges need no work.

Direct clipped copies avoid constructing a larger full-tile mosaic that would immediately be cropped and discarded.

Definition at line 696 of file ear_heatmap_overlay.c.

◆ csv_column()

bool csv_column ( const char * line,
unsigned int column,
double * value )
static

Read one required numeric column from a LiDAR CSV row.

Definition at line 1153 of file ear_heatmap_overlay.c.

◆ csv_number()

bool csv_number ( const char * line,
unsigned int column,
double * value )
static

Parse one complete numeric field from a bounded CSV row.

Parameters
lineCSV record buffer.
columnZero-based field index.
valueReceives the finite number on success.
Returns
true only when the selected field exists and contains a complete number.

A short stack token buffer rejects overlong cells rather than sizing memory from untrusted file contents.

Definition at line 1081 of file ear_heatmap_overlay.c.

◆ default_cache_path()

int default_cache_path ( char * path,
size_t capacity )
static

Resolve the Paparazzi GCS map-cache root from XDG environment settings.

Parameters
pathReceives $XDG_DATA_HOME/paparazzi/pprzgcs/map or the HOME fallback.
capacityDestination capacity in bytes.
Returns
0 for a usable environment/path, -1 if HOME is absent or the result cannot fit.

GCS imagery belongs to its user-data cache, not the source checkout; using this shared location is what makes local tiles the fast/default path.

Definition at line 503 of file ear_heatmap_overlay.c.

◆ download_tile()

int download_tile ( const struct options * options,
unsigned int x,
unsigned int y,
unsigned int zoom,
const char * path )
static

Download one cache miss with the existing curl executable.

Parameters
optionsSource/cache policy.
xTile column.
yTile row.
zoomTile zoom level.
pathFinal cache filename.
Returns
0 after an atomic install, otherwise -1 on process, network or file failure.

Called only after every local cache spelling misses. execvp avoids shell interpretation; the temporary file is renamed only after curl exits cleanly.

Definition at line 609 of file ear_heatmap_overlay.c.

◆ draw_brush()

void draw_brush ( struct rgb_image * image,
int x,
int y,
int width,
uint8_t red,
uint8_t green,
uint8_t blue,
double alpha )
static

Stamp a square brush centered at an integer pixel.

Parameters
imageDestination RGB image.
xCenter X.
yCenter Y.
widthNominal stroke width.
redStroke red channel.
greenStroke green channel.
blueStroke blue channel.
alphaStroke opacity.

Definition at line 811 of file ear_heatmap_overlay.c.

◆ draw_circle()

void draw_circle ( struct rgb_image * image,
int cx,
int cy,
int radius,
int width,
uint8_t red,
uint8_t green,
uint8_t blue,
double alpha )
static

Draw a filled disc or clipped ring with a fixed-width stroke.

Parameters
imageDestination RGB image.
cxCenter X in output pixels.
cyCenter Y in output pixels.
radiusOuter radius in pixels.
widthRing thickness, ignored for a filled disc.
redAnnotation red channel.
greenAnnotation green channel.
blueAnnotation blue channel.
alphaAnnotation opacity.

Reject circles vastly larger than the image before squaring radii; clipping the remaining scan bounds avoids visiting pixels outside the output.

Definition at line 866 of file ear_heatmap_overlay.c.

◆ draw_crosshair()

void draw_crosshair ( struct rgb_image * image,
int x,
int y,
uint8_t red,
uint8_t green,
uint8_t blue )
static

Draw a distinct, high-contrast marker for the estimated loudest spot.

Parameters
imageDestination image.
xMarker center X.
yMarker center Y.
redForeground red channel.
greenForeground green channel.
blueForeground blue channel.

A dark casing pass precedes the colored stroke so the estimate remains visible over both bright and dark map/heat pixels.

Definition at line 899 of file ear_heatmap_overlay.c.

◆ draw_diamond()

void draw_diamond ( struct rgb_image * image,
int x,
int y,
int radius,
uint8_t red,
uint8_t green,
uint8_t blue )
static

Draw the known simulation source as a shape distinct from the estimate.

Parameters
imageDestination image.
xDiamond center X.
yDiamond center Y.
radiusDiamond half-width and half-height.
redForeground red channel.
greenForeground green channel.
blueForeground blue channel.

Truth is a separate simulation reference, not another sensor reading; the black outline keeps that distinction visible on any background.

Definition at line 930 of file ear_heatmap_overlay.c.

◆ draw_line()

void draw_line ( struct rgb_image * image,
int x0,
int y0,
int x1,
int y1,
int width,
uint8_t red,
uint8_t green,
uint8_t blue,
double alpha )
static

Draw a raster line with an integer Bresenham walk.

Parameters
imageDestination RGB image.
x0Start X.
y0Start Y.
x1End X.
y1End Y.
widthBrush width.
redStroke red channel.
greenStroke green channel.
blueStroke blue channel.
alphaStroke opacity.

A compact local rasterizer avoids a drawing library for a few crisp lines; per-pixel clipping remains centralized in put_blended_pixel.

Definition at line 837 of file ear_heatmap_overlay.c.

◆ draw_log_points()

void draw_log_points ( struct rgb_image * image,
const struct point_list * points,
double origin_x,
double origin_y,
unsigned int zoom )
static

Redraw sample locations as crisp dots over the blended sound field.

Parameters
imageOutput map.
pointsParsed EAR session observations.
origin_xFractional XYZ X coordinate of output origin.
origin_yFractional XYZ Y coordinate of output origin.
zoomMap tile zoom.

A black edge and white core keep individual observations visible on both satellite imagery and the heat palette.

Definition at line 1266 of file ear_heatmap_overlay.c.

◆ draw_obstacles()

void draw_obstacles ( struct rgb_image * image,
const struct obstacle_list * obstacles,
double cell_size,
double m_per_deg_lat,
double m_per_deg_lon,
double origin_x,
double origin_y,
unsigned int zoom )
static

Paint optional height-above-terrain cells over the output map.

Parameters
imageOutput map.
obstaclesParsed regular LiDAR cells.
cell_sizeProjected cell pitch in metres.
m_per_deg_latLocal metres per latitude degree.
m_per_deg_lonLocal metres per longitude degree.
origin_xFractional XYZ X coordinate of output origin.
origin_yFractional XYZ Y coordinate of output origin.
zoomMap tile zoom.

Cell bounds are clipped before painting, and color bands are only qualitative review aids; no collision or flight-control logic consumes them.

Definition at line 1314 of file ear_heatmap_overlay.c.

◆ draw_text()

void draw_text ( struct rgb_image * image,
int x,
int y,
const char * text,
uint8_t red,
uint8_t green,
uint8_t blue )
static

Draw a small outlined label over arbitrary imagery.

Parameters
imageDestination image.
xLeft coordinate.
yTop coordinate.
textNUL-terminated label.
redForeground red channel.
greenForeground green channel.
blueForeground blue channel.

The eight-neighbor dark casing is a lightweight contrast aid; no external font or graphics library is needed for these short map labels.

Definition at line 1028 of file ear_heatmap_overlay.c.

◆ draw_text_pass()

void draw_text_pass ( struct rgb_image * image,
int x,
int y,
const char * text,
unsigned int scale,
uint8_t red,
uint8_t green,
uint8_t blue )
static

Paint one foreground or outline pass of bitmap text.

Parameters
imageDestination image.
xLeft coordinate.
yTop coordinate.
textNUL-terminated label.
scaleInteger expansion per glyph pixel.
redText red channel.
greenText green channel.
blueText blue channel.

Definition at line 996 of file ear_heatmap_overlay.c.

◆ draw_track()

void draw_track ( struct rgb_image * image,
const struct point_list * points,
double origin_x,
double origin_y,
unsigned int zoom,
double gap_s )
static

Draw aircraft-track segments, breaking where fixes are too far apart.

Parameters
imageOutput map.
pointsOrdered fixes with normalized second timestamps.
origin_xFractional XYZ X coordinate of output origin.
origin_yFractional XYZ Y coordinate of output origin.
zoomMap tile zoom.
gap_sLargest allowed timestamp gap within a connected segment.

Breaking stale intervals avoids drawing a fabricated straight path through periods where no aircraft positions were recorded.

Definition at line 1288 of file ear_heatmap_overlay.c.

◆ fetch_tile()

int fetch_tile ( const struct options * options,
unsigned int x,
unsigned int y,
unsigned int zoom,
struct rgb_image * tile )
static

Read a local hit, fetch a miss if permitted, and decode one 256x256 tile.

Parameters
optionsSource/cache/offline policy.
xTile column.
yTile row.
zoomTile zoom level.
tileReceives RGB pixels in the fixed tile workspace.
Returns
0 for a readable tile/placeholder; -1 for offline misses or invalid cached JPEGs.

Offline mode is deliberately strict: replacing missing terrain with blank pixels would make incomplete geographic context look like a successful map review.

Definition at line 655 of file ear_heatmap_overlay.c.

◆ gcs_key()

void gcs_key ( unsigned int x,
unsigned int y,
unsigned int zoom,
char * key,
size_t capacity )
static

Encode an XYZ address using Paparazzi's legacy Google quadkey alphabet.

Parameters
xTile column.
yTile row, increasing southward.
zoomNumber of quadkey digits.
keyCaller-owned string buffer.
capacityBuffer capacity including the terminator.

This is a compatibility fallback; current Paparazzi cache entries are searched in the uppercase XYZ layout first.

Definition at line 554 of file ear_heatmap_overlay.c.

◆ glyph_rows()

const uint8_t * glyph_rows ( char character)
static

Return one embedded 5x7 uppercase bitmap glyph.

Parameters
characterASCII label character; unsupported characters become blank.
Returns
Seven row bitmasks with five meaningful bits each.

This tiny font keeps annotation text independent of system font files and avoids adding a font-rendering library to the host utility.

Definition at line 955 of file ear_heatmap_overlay.c.

◆ haversine_m()

double haversine_m ( double lat_a,
double lon_a,
double lat_b,
double lon_b )
static

Compute great-circle distance between two latitude/longitude points.

Parameters
lat_aFirst latitude in degrees.
lon_aFirst longitude in degrees.
lat_bSecond latitude in degrees.
lon_bSecond longitude in degrees.
Returns
Spherical-Earth separation in metres.

Used to annotate known simulation truth versus the estimate; it does not correct the estimate or certify field accuracy.

Definition at line 1246 of file ear_heatmap_overlay.c.

◆ header_column()

int header_column ( const char * header,
const char * name )
static

Locate an exact field name in a CSV header without mutating the source.

Parameters
headerBounded header row.
nameRequired column name.
Returns
Zero-based field index, or -1 when absent or overlong.

Each lookup tokenizes a stack copy so querying several required fields does not consume or corrupt the shared header.

Definition at line 1138 of file ear_heatmap_overlay.c.

◆ image_free()

void image_free ( struct rgb_image * image)
static

Invalidate an RGB view before its shared workspace is reused.

Parameters
imageDescriptor to clear; its backing pixels are caller-owned static storage.

Definition at line 170 of file ear_heatmap_overlay.c.

◆ image_read_jpeg()

int image_read_jpeg ( const char * path,
struct rgb_image * image )
static

Decode one JPEG into the caller's bounded RGB workspace.

Parameters
pathJPEG file path.
imageSupplies pixel pointer/capacity and receives decoded dimensions.
Returns
0 after complete decode, or -1 for I/O, codec, size or capacity failure.

The pixel cap is checked before scanlines are decoded; image dimensions from a file header never trigger allocation or out-of-bounds writes.

Definition at line 186 of file ear_heatmap_overlay.c.

◆ image_write_jpeg()

int image_write_jpeg ( const char * path,
const struct rgb_image * image )
static

Encode a bounded RGB view to a JPEG file.

Parameters
pathOutput JPEG path.
imageImage dimensions and borrowed RGB pixels.
Returns
0 on successful encode/close, or -1 on open, codec or close failure.

Scanlines are passed directly from the single output workspace so no image-sized staging copy is required.

Definition at line 238 of file ear_heatmap_overlay.c.

◆ jpeg_error_exit()

void jpeg_error_exit ( j_common_ptr info)
static

Convert libjpeg's fatal callback into a jump to the active operation.

Parameters
infoCodec state carrying the recovery record in its error manager.

Default libjpeg behavior exits the process; keeping recovery local lets corrupt cached tiles fail this overlay without terminating other host tools.

Definition at line 160 of file ear_heatmap_overlay.c.

◆ main()

int main ( int argc,
char ** argv )

Validate replay artifacts, compose the map context and write a JPEG.

Parameters
argcCommand-line argument count.
argvProcess arguments; option strings are borrowed for this invocation.
Returns
0 on success, 2 for usage/policy errors, or 1 for I/O/data failure.

Prefer the matching undecorated field because reusing the decorated heatmap would blend its original dots/marker into the basemap a second time. The sidecar dimensions are checked before any map data is read.

Definition at line 1510 of file ear_heatmap_overlay.c.

◆ make_directories()

int make_directories ( const char * path)
static

Create parent directories for a tile file without treating the file as a directory.

Parameters
pathFull destination filename.
Returns
0 if all parents exist or are created, otherwise -1.

Downloads go to a sibling temporary path and are renamed on success; partial transfers therefore cannot masquerade as cache hits.

Definition at line 523 of file ear_heatmap_overlay.c.

◆ make_stem_path()

int make_stem_path ( const char * path,
const char * suffix,
char * output,
size_t capacity )
static

Derive a sibling .geo, _field.jpg or _sat.jpg path from an image.

Parameters
pathInput JPEG path.
suffixReplacement suffix.
outputDestination path buffer.
capacityCapacity in bytes.
Returns
0 when the path fits, -1 rather than returning a truncated filename.

Stem-derived names keep replay artifacts paired without asking users to type a second path that can silently refer to another session.

Definition at line 480 of file ear_heatmap_overlay.c.

◆ mercator_latitude()

double mercator_latitude ( double tile_y,
unsigned int zoom )
static

Invert fractional Web Mercator tile Y into a geographic latitude.

Parameters
tile_yFractional tile row, increasing southward.
zoomXYZ zoom level.
Returns
Latitude in degrees.

Definition at line 721 of file ear_heatmap_overlay.c.

◆ mercator_m_per_pixel()

double mercator_m_per_pixel ( double lat,
unsigned int zoom )
static

Estimate ground metres per tile pixel at a latitude.

Parameters
latLatitude in degrees.
zoomXYZ zoom level.
Returns
Local ground resolution in metres per 256-pixel tile pixel.

Mercator scale varies by latitude, so zoom selection and the scale annotation consistently use the heatmap's center latitude.

Definition at line 418 of file ear_heatmap_overlay.c.

◆ mercator_xy()

void mercator_xy ( double lat,
double lon,
unsigned int zoom,
double * x,
double * y )
static

Project latitude/longitude into fractional Web Mercator tile coordinates.

Parameters
latLatitude in degrees.
lonLongitude in degrees.
zoomXYZ zoom level.
xReceives fractional tile X, increasing eastward.
yReceives fractional tile Y, increasing southward.

Clamp to the finite square-tile Mercator latitude limit; callers separately reject overlays whose geographic bounds are not supported by this projection.

Definition at line 401 of file ear_heatmap_overlay.c.

◆ parse_double()

bool parse_double ( const char * text,
double * value )
static

Parse a finite floating-point token in full.

Parameters
textNUL-terminated command-line value.
valueReceives the result only on success.
Returns
false for empty, non-finite, out-of-range or partially numeric strings.

Rejecting trailing characters prevents a typo like 0.5junk from silently changing image opacity or another numeric option.

Definition at line 277 of file ear_heatmap_overlay.c.

◆ parse_location()

bool parse_location ( const char * text,
bool with_radius,
double * lat,
double * lon,
double * radius )
static

Parse LAT,LON or LAT,LON,RADIUS_M into bounded geographic values.

Parameters
textComma-separated command-line token.
with_radiusAllow/require interpretation of a third optional field.
latReceives latitude in degrees.
lonReceives longitude in degrees.
radiusReceives the parsed radius or the 25 m default when enabled.
Returns
true only when every field is consumed and within its geographic/radius range.

Definition at line 448 of file ear_heatmap_overlay.c.

◆ parse_options()

bool parse_options ( int argc,
char ** argv,
struct options * options )
static

Parse one positional heatmap and the supported optional controls.

Parameters
argcArgument count.
argvProcess argument vector.
optionsReceives validated values; strings borrow argv storage.
Returns
true when exactly one positional input and all recognized values are present.

Options are accepted before or after the image to avoid shell-order surprises; unknown switches and duplicate positional images are rejected.

Definition at line 340 of file ear_heatmap_overlay.c.

◆ parse_unsigned()

bool parse_unsigned ( const char * text,
unsigned int * value )
static

Parse an unsigned integer option without accepting suffix characters.

Parameters
textNUL-terminated decimal token.
valueReceives the value only when it fits unsigned int.
Returns
true for a complete conversion within the destination range.

Definition at line 293 of file ear_heatmap_overlay.c.

◆ pixel_location()

void pixel_location ( double lat,
double lon,
double origin_x,
double origin_y,
unsigned int zoom,
int * x,
int * y )
static

Convert a geographic annotation to pixels in the cropped tile mosaic.

Parameters
latLatitude in degrees.
lonLongitude in degrees.
origin_xFractional XYZ X coordinate of output origin.
origin_yFractional XYZ Y coordinate of output origin.
zoomShared Web Mercator zoom.
xReceives image-space X.
yReceives image-space Y.

Definition at line 1050 of file ear_heatmap_overlay.c.

◆ print_help()

void print_help ( const char * program)
static

Print command synopsis and defaults from the same option vocabulary parsed below.

Parameters
programInvocation name displayed to the user.

Definition at line 307 of file ear_heatmap_overlay.c.

◆ put_blended_pixel()

void put_blended_pixel ( struct rgb_image * image,
int x,
int y,
uint8_t red,
uint8_t green,
uint8_t blue,
double alpha )
static

Blend one annotation pixel while clipping out-of-image coordinates.

Parameters
imageDestination RGB image.
xImage-space X.
yImage-space Y.
redAnnotation red channel.
greenAnnotation green channel.
blueAnnotation blue channel.
alphaBlend amount from transparent to opaque.

Central clipping lets each simple raster primitive draw across map boundaries without a separate bounds check for every caller.

Definition at line 788 of file ear_heatmap_overlay.c.

◆ read_obstacles()

int read_obstacles ( const char * path,
struct obstacle_list * obstacles,
double * cell_size )
static

Read the optional regular LiDAR height grid and infer its cell width.

Parameters
pathCSV with x_east_m, lat, lon, and mnh_m header columns.
obstaclesReceives validated cells in fixed-capacity storage.
cell_sizeReceives the smallest positive spacing between eastings.
Returns
0 for a usable grid, -1 for I/O, schema, capacity or spacing failures.

Sorting the projected eastings distinguishes grid pitch from geographic map scale; height colors remain visual context, not a clearance/navigation result.

Definition at line 1188 of file ear_heatmap_overlay.c.

◆ read_points()

int read_points ( const char * path,
bool session_log,
struct point_list * points )
static

Read geographic points from an EAR session or aircraft-track CSV.

Parameters
pathCSV path.
session_logSelect session columns/timestamps instead of track schema.
pointsBounded destination list view.
Returns
0 after a complete read, -1 for I/O errors or record-cap overflow.

Session time is milliseconds and positions are columns 2/3; track time is seconds and positions are columns 1/2. Invalid poses are skipped, not plotted.

Definition at line 1106 of file ear_heatmap_overlay.c.

◆ tile_path()

int tile_path ( const struct options * options,
unsigned int x,
unsigned int y,
unsigned int zoom,
char * path,
size_t capacity )
static

Select the first known local filename for an XYZ source tile.

Parameters
optionsSource namespace and cache root.
xTile column.
yTile row.
zoomTile zoom.
pathReceives an existing tile path when found, otherwise preferred download path.
capacityDestination buffer size.
Returns
0 when a candidate fits the buffer; -1 if path formatting would truncate.

Current GOOGLE/{z}/{x}/{y}.jpeg and Esri layouts are checked before historical spellings so existing locally cached imagery is reused without network.

Definition at line 577 of file ear_heatmap_overlay.c.

Variable Documentation

◆ input_pixels

uint8_t input_pixels[(size_t) MAX_INPUT_PIXELS *3U]
static

Reused input, tile and final RGB workspaces; avoid per-image allocator churn.

Definition at line 117 of file ear_heatmap_overlay.c.

◆ obstacle_cells

struct obstacle obstacle_cells[MAX_CSV_POINTS]
static

Definition at line 122 of file ear_heatmap_overlay.c.

◆ obstacle_eastings

double obstacle_eastings[MAX_CSV_POINTS]
static

Definition at line 123 of file ear_heatmap_overlay.c.

◆ output_pixels

uint8_t output_pixels[(size_t) MAX_OUTPUT_PIXELS *3U]
static

Definition at line 119 of file ear_heatmap_overlay.c.

◆ session_points

struct point session_points[MAX_CSV_POINTS]
static

Definition at line 120 of file ear_heatmap_overlay.c.

◆ tile_pixels

uint8_t tile_pixels[(size_t) TILE_SIZE *TILE_SIZE *3U]
static

Definition at line 118 of file ear_heatmap_overlay.c.

◆ track_points

struct point track_points[MAX_CSV_POINTS]
static

Definition at line 121 of file ear_heatmap_overlay.c.