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.h
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.h
20 * @brief Render geotagged acoustic measurements into north-up JPEG heatmaps. */
21#ifndef EARCAM_HEATMAP_H
22#define EARCAM_HEATMAP_H
23
24#include <stdbool.h>
25#include <stddef.h>
26
27#include "earcam_core.h"
28
29#define EAR_HEATMAP_NO_DATA_RED 18U /**< Red channel identifying uncovered field pixels. */
30#define EAR_HEATMAP_NO_DATA_GREEN 18U /**< Green channel identifying uncovered field pixels. */
31#define EAR_HEATMAP_NO_DATA_BLUE 24U /**< Blue channel identifying uncovered field pixels. */
32
33/**
34 * @brief Validated geographic placement metadata shared by heatmap consumers.
35 * @details The renderer uses a local equirectangular frame about the center; overlay
36 * code must transform to its map projection rather than stretch the JPEG by size.
37 */
39 unsigned int width_px; /**< Encoded heatmap width; must match the JPEG consumer reads. */
40 unsigned int height_px; /**< Encoded heatmap height. */
41 double m_per_px; /**< Ground spacing represented by each heatmap pixel. */
42 double lat_center; /**< Latitude origin for the local projection, degrees. */
43 double lon_center; /**< Longitude origin for the local projection, degrees. */
44 double lat_north; /**< Latitude at the upper image edge, degrees. */
45 double lon_west; /**< Longitude at the left image edge, degrees. */
46 bool has_spot; /**< True only when the sidecar contains a complete spot pair. */
47 double spot_lat; /**< Estimated spot latitude, degrees, when `has_spot`. */
48 double spot_lon; /**< Estimated spot longitude, degrees, when `has_spot`. */
49};
50
51/**
52 * @brief Read the georeference sidecar emitted by the heatmap renderer.
53 * @param filename Path to the `.geo` sidecar.
54 * @param georef Receives validated dimensions, projection and optional spot.
55 * @return 0 on success; -1 for invalid arguments, malformed data or I/O error.
56 * @details Required dimensions, scale and edge/origin coordinates are validated
57 * before publication to the caller; partial parses never replace its struct.
58 * Duplicate fields, oversized lines and incomplete optional spot pairs fail.
59 */
60int ear_heatmap_read_georef(const char *filename, struct ear_heatmap_georef *georef);
61
62/**
63 * @brief Write a decorated north-up JPEG of relative measured acoustic intensity.
64 * @param filename Output path; an adjacent .geo sidecar is attempted after JPEG success.
65 * @param samples Borrowed, immutable geotagged windows; not retained after the call.
66 * @param count Window count; at least three usable finite, unclipped windows are required.
67 * @param spot Optional borrowed estimate; only valid estimates receive a marker.
68 * @return 0 for a successfully written JPEG, -1 for insufficient data or file/codec failure.
69 * @details Track dots, an estimated-source marker and a scale bar aid interpretation.
70 * Calls serialize on bounded shared scratch storage. Grid cells are roughly AGL/4;
71 * bilinear upsampling adds visual smoothness, not measurement resolution.
72 * @warning Sidecar write failure does not change the return status. Neither the
73 * smoothed field nor the marker demonstrates localization accuracy or alarm presence.
74 */
75int ear_heatmap_write(const char *filename, const struct ear_sample *samples, size_t count,
76 const struct ear_loudest_spot *spot);
77
78/**
79 * @brief Write the same field without track dots, source marker or scale bar.
80 * @param filename JPEG path; a best-effort .geo sidecar supplies overlay placement.
81 * @param samples Borrowed immutable acoustic windows.
82 * @param count Number of supplied windows, with the same usable-data gate as ear_heatmap_write().
83 * @param spot Optional estimate retained in sidecar metadata, not drawn into pixels.
84 * @return 0 for JPEG success, -1 for insufficient usable data or file/codec failure.
85 * @details Use the same interpolation and shared workspace as the decorated
86 * renderer, keeping annotation pixels out of the field used for overlays.
87 * @see ear_heatmap_write for locking, resolution and sidecar-status caveats.
88 */
89int ear_heatmap_write_field(const char *filename, const struct ear_sample *samples, size_t count,
90 const struct ear_loudest_spot *spot);
91
92#endif
int ear_heatmap_read_georef(const char *filename, struct ear_heatmap_georef *georef)
Read the georeference sidecar emitted by the heatmap renderer.
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 struct ear_sample samples[EAR_MAX_SAMPLES]
Sensor-independent acoustic samples and ground-source estimates.
static size_t count
Definition pose_log.c:79
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