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>
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()
|
static |
Append one obstacle cell when fixed storage has room.
- Parameters
-
list Bounded obstacle list view. obstacle Validated 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()
|
static |
Append a point into caller-owned bounded storage.
- Parameters
-
list Point list view. point Validated 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()
|
static |
Assemble basemap tiles, heatfield and optional annotations into one output raster.
- Parameters
-
options Parsed cache, projection and annotation policy. geo Validated local-projection footprint from the .geo sidecar. heat Undecorated _field.jpg when present, otherwise the input JPEG. output Receives 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()
|
static |
Select the first basemap zoom at least as detailed as the heatmap.
- Parameters
-
geo Heatmap pixel scale and center latitude. max_zoom Highest 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()
|
static |
Order projected eastings so adjacent positive deltas reveal cell pitch.
Definition at line 1172 of file ear_heatmap_overlay.c.
◆ composite_heatmap()
|
static |
Resample the local equirectangular heat field onto the Mercator tile mosaic.
- Parameters
-
base In/out satellite RGB image. field Undecorated EAR heatmap raster. geo Validated sidecar footprint and scale. zoom Basemap XYZ zoom shared by tile placement and output projection. crop_x Cropped image origin within the tile grid, pixels. crop_y Cropped image origin within the tile grid, pixels. alpha Opacity 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()
|
static |
Copy only the part of a source tile intersecting the cropped output.
- Parameters
-
tile Decoded fixed-size map tile. output Bounded destination mosaic. tile_x Absolute XYZ column. tile_y Absolute XYZ row. crop_x Crop origin in the assembled tile-grid pixels. crop_y Crop 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()
|
static |
Read one required numeric column from a LiDAR CSV row.
Definition at line 1153 of file ear_heatmap_overlay.c.
◆ csv_number()
|
static |
Parse one complete numeric field from a bounded CSV row.
- Parameters
-
line CSV record buffer. column Zero-based field index. value Receives 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()
|
static |
Resolve the Paparazzi GCS map-cache root from XDG environment settings.
- Parameters
-
path Receives $XDG_DATA_HOME/paparazzi/pprzgcs/map or the HOME fallback. capacity Destination 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()
|
static |
Download one cache miss with the existing curl executable.
- Parameters
-
options Source/cache policy. x Tile column. y Tile row. zoom Tile zoom level. path Final 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()
|
static |
Stamp a square brush centered at an integer pixel.
- Parameters
-
image Destination RGB image. x Center X. y Center Y. width Nominal stroke width. red Stroke red channel. green Stroke green channel. blue Stroke blue channel. alpha Stroke opacity.
Definition at line 811 of file ear_heatmap_overlay.c.
◆ draw_circle()
|
static |
Draw a filled disc or clipped ring with a fixed-width stroke.
- Parameters
-
image Destination RGB image. cx Center X in output pixels. cy Center Y in output pixels. radius Outer radius in pixels. width Ring thickness, ignored for a filled disc. red Annotation red channel. green Annotation green channel. blue Annotation blue channel. alpha Annotation 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()
|
static |
Draw a distinct, high-contrast marker for the estimated loudest spot.
- Parameters
-
image Destination image. x Marker center X. y Marker center Y. red Foreground red channel. green Foreground green channel. blue Foreground 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()
|
static |
Draw the known simulation source as a shape distinct from the estimate.
- Parameters
-
image Destination image. x Diamond center X. y Diamond center Y. radius Diamond half-width and half-height. red Foreground red channel. green Foreground green channel. blue Foreground 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()
|
static |
Draw a raster line with an integer Bresenham walk.
- Parameters
-
image Destination RGB image. x0 Start X. y0 Start Y. x1 End X. y1 End Y. width Brush width. red Stroke red channel. green Stroke green channel. blue Stroke blue channel. alpha Stroke 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()
|
static |
Redraw sample locations as crisp dots over the blended sound field.
- Parameters
-
image Output map. points Parsed EAR session observations. origin_x Fractional XYZ X coordinate of output origin. origin_y Fractional XYZ Y coordinate of output origin. zoom Map 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()
|
static |
Paint optional height-above-terrain cells over the output map.
- Parameters
-
image Output map. obstacles Parsed regular LiDAR cells. cell_size Projected cell pitch in metres. m_per_deg_lat Local metres per latitude degree. m_per_deg_lon Local metres per longitude degree. origin_x Fractional XYZ X coordinate of output origin. origin_y Fractional XYZ Y coordinate of output origin. zoom Map 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()
|
static |
Draw a small outlined label over arbitrary imagery.
- Parameters
-
image Destination image. x Left coordinate. y Top coordinate. text NUL-terminated label. red Foreground red channel. green Foreground green channel. blue Foreground 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()
|
static |
Paint one foreground or outline pass of bitmap text.
- Parameters
-
image Destination image. x Left coordinate. y Top coordinate. text NUL-terminated label. scale Integer expansion per glyph pixel. red Text red channel. green Text green channel. blue Text blue channel.
Definition at line 996 of file ear_heatmap_overlay.c.
◆ draw_track()
|
static |
Draw aircraft-track segments, breaking where fixes are too far apart.
- Parameters
-
image Output map. points Ordered fixes with normalized second timestamps. origin_x Fractional XYZ X coordinate of output origin. origin_y Fractional XYZ Y coordinate of output origin. zoom Map tile zoom. gap_s Largest 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()
|
static |
Read a local hit, fetch a miss if permitted, and decode one 256x256 tile.
- Parameters
-
options Source/cache/offline policy. x Tile column. y Tile row. zoom Tile zoom level. tile Receives 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()
|
static |
Encode an XYZ address using Paparazzi's legacy Google quadkey alphabet.
- Parameters
-
x Tile column. y Tile row, increasing southward. zoom Number of quadkey digits. key Caller-owned string buffer. capacity Buffer 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()
|
static |
Return one embedded 5x7 uppercase bitmap glyph.
- Parameters
-
character ASCII 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()
|
static |
Compute great-circle distance between two latitude/longitude points.
- Parameters
-
lat_a First latitude in degrees. lon_a First longitude in degrees. lat_b Second latitude in degrees. lon_b Second 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()
|
static |
Locate an exact field name in a CSV header without mutating the source.
- Parameters
-
header Bounded header row. name Required 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()
|
static |
Invalidate an RGB view before its shared workspace is reused.
- Parameters
-
image Descriptor to clear; its backing pixels are caller-owned static storage.
Definition at line 170 of file ear_heatmap_overlay.c.
◆ image_read_jpeg()
|
static |
Decode one JPEG into the caller's bounded RGB workspace.
- Parameters
-
path JPEG file path. image Supplies 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()
|
static |
Encode a bounded RGB view to a JPEG file.
- Parameters
-
path Output JPEG path. image Image 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()
|
static |
Convert libjpeg's fatal callback into a jump to the active operation.
- Parameters
-
info Codec 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
-
argc Command-line argument count. argv Process 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()
|
static |
Create parent directories for a tile file without treating the file as a directory.
- Parameters
-
path Full 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()
|
static |
Derive a sibling .geo, _field.jpg or _sat.jpg path from an image.
- Parameters
-
path Input JPEG path. suffix Replacement suffix. output Destination path buffer. capacity Capacity 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()
|
static |
Invert fractional Web Mercator tile Y into a geographic latitude.
- Parameters
-
tile_y Fractional tile row, increasing southward. zoom XYZ zoom level.
- Returns
- Latitude in degrees.
Definition at line 721 of file ear_heatmap_overlay.c.
◆ mercator_m_per_pixel()
|
static |
Estimate ground metres per tile pixel at a latitude.
- Parameters
-
lat Latitude in degrees. zoom XYZ 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()
|
static |
Project latitude/longitude into fractional Web Mercator tile coordinates.
- Parameters
-
lat Latitude in degrees. lon Longitude in degrees. zoom XYZ zoom level. x Receives fractional tile X, increasing eastward. y Receives 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()
|
static |
Parse a finite floating-point token in full.
- Parameters
-
text NUL-terminated command-line value. value Receives 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()
|
static |
Parse LAT,LON or LAT,LON,RADIUS_M into bounded geographic values.
- Parameters
-
text Comma-separated command-line token. with_radius Allow/require interpretation of a third optional field. lat Receives latitude in degrees. lon Receives longitude in degrees. radius Receives 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()
|
static |
Parse one positional heatmap and the supported optional controls.
- Parameters
-
argc Argument count. argv Process argument vector. options Receives 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()
|
static |
Parse an unsigned integer option without accepting suffix characters.
- Parameters
-
text NUL-terminated decimal token. value Receives 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()
|
static |
Convert a geographic annotation to pixels in the cropped tile mosaic.
- Parameters
-
lat Latitude in degrees. lon Longitude in degrees. origin_x Fractional XYZ X coordinate of output origin. origin_y Fractional XYZ Y coordinate of output origin. zoom Shared Web Mercator zoom. x Receives image-space X. y Receives image-space Y.
Definition at line 1050 of file ear_heatmap_overlay.c.
◆ print_help()
|
static |
Print command synopsis and defaults from the same option vocabulary parsed below.
- Parameters
-
program Invocation name displayed to the user.
Definition at line 307 of file ear_heatmap_overlay.c.
◆ put_blended_pixel()
|
static |
Blend one annotation pixel while clipping out-of-image coordinates.
- Parameters
-
image Destination RGB image. x Image-space X. y Image-space Y. red Annotation red channel. green Annotation green channel. blue Annotation blue channel. alpha Blend 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()
|
static |
Read the optional regular LiDAR height grid and infer its cell width.
- Parameters
-
path CSV with x_east_m, lat, lon, and mnh_m header columns. obstacles Receives validated cells in fixed-capacity storage. cell_size Receives 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()
|
static |
Read geographic points from an EAR session or aircraft-track CSV.
- Parameters
-
path CSV path. session_log Select session columns/timestamps instead of track schema. points Bounded 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()
|
static |
Select the first known local filename for an XYZ source tile.
- Parameters
-
options Source namespace and cache root. x Tile column. y Tile row. zoom Tile zoom. path Receives an existing tile path when found, otherwise preferred download path. capacity Destination 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
|
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
|
static |
Definition at line 122 of file ear_heatmap_overlay.c.
◆ obstacle_eastings
|
static |
Definition at line 123 of file ear_heatmap_overlay.c.
◆ output_pixels
|
static |
Definition at line 119 of file ear_heatmap_overlay.c.
◆ session_points
|
static |
Definition at line 120 of file ear_heatmap_overlay.c.
◆ tile_pixels
Definition at line 118 of file ear_heatmap_overlay.c.
◆ track_points
|
static |
Definition at line 121 of file ear_heatmap_overlay.c.