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
map_exif.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 map_exif.h
20 * @brief Add projection, coverage, and source provenance to map EXIF.
21 * @details Large source lists move to a companion JSON file rather than
22 * overflowing the bounded EXIF payload. Metadata also labels the output's
23 * reference-plane model and simulator-coordinate accuracy limits explicitly.
24 */
25#ifndef PANGEA_MAP_EXIF_H
26#define PANGEA_MAP_EXIF_H
27
28#include "photo_exif.h"
29#include "ortho_map.h"
30namespace pangea_survey {
31/**
32 * @brief Serialize source-camera provenance and map-grid metadata for orthophotos.
33 * @details This is derived-map metadata: it does not claim exposure-time pose
34 * synchronization, a measured lens calibration, or relief-corrected geometry.
35 */
36class MapExif : public PhotoExif {
37public:
38 /**
39 * @brief Encode each source image's optical, geographic, and timing provenance.
40 * @param[in] sources Sources contributing to one rendered map.
41 * @return JSON array suitable for an EXIF comment or companion file.
42 */
43 static std::string sourceMetadata(const std::vector<OrthoSource>& sources) {
44 std::ostringstream json;
45 json.imbue(std::locale::classic()); json << std::setprecision(15) << '[';
46 bool first = true;
47 for (const auto& source : sources) {
48 if (!first) json << ',';
49 first = false;
50 json << "{\"filename\":" << jsonString(source.path.filename().u8string())
51 << ",\"lens_model\":\"SimConnect rectilinear virtual lens\","
52 "\"projection\":\"perspective\",\"sdk_vertical_fov_deg\":" << source.fov
53 << ",\"fx_px\":" << source.focal << ",\"fy_px\":" << source.focal
54 << ",\"cx_px\":" << source.cx << ",\"cy_px\":" << source.cy
55 << ",\"physical_sensor_mm\":null,\"latitude_deg\":" << source.latitude
56 << ",\"longitude_deg\":" << source.longitude << ",\"amsl_m\":" << source.altitude
57 << ",\"commanded_pitch_deg\":90,\"commanded_bank_deg\":0,\"commanded_heading_deg\":0,"
58 "\"observed_pitch_deg\":" << source.pitch << ",\"observed_bank_deg\":" << source.bank
59 << ",\"observed_heading_deg\":" << source.heading << ",\"pose_qpc_100ns\":" << source.poseTime
60 << ",\"frame_qpc_100ns\":" << source.frameTime << ",\"pose_frame_synchronized\":false";
61 if (source.captureUtc)
62 json << ",\"capture_utc\":" << jsonString(source.captureUtc->text)
63 << ",\"utc_absolute_seconds\":" << std::setprecision(17) << source.utcAbsoluteSeconds
64 << ",\"utc_read_qpc_100ns\":" << source.utcRead100ns
65 << ",\"utc_frame_synchronized\":false" << std::setprecision(15);
66 json << '}';
67 }
68 return json.str() + ']';
69 }
70 /**
71 * @brief Build EXIF for an orthophoto and reference any external source list.
72 * @param[in] image Rendered pixels, map grid, coverage classes, and sources.
73 * @param[in] projection UTM projection used to derive the map-centre location.
74 * @param[in] sourceCompanion Optional companion JSON filename for large provenance.
75 * @return Serialized EXIF payload borrowed from the inherited workspace.
76 * @throws std::runtime_error If provenance cannot fit or map metadata is invalid.
77 */
78 Payload buildOrtho(const OrthoImage& image, const MapProjection& projection,
79 const std::string& sourceCompanion = {}) {
80 const auto coordinate = projection.inverse(image.map.east, image.map.north);
81 build({coordinate.first, coordinate.second, 0, 0}, image.width, image.height);
82 check(exif_document_ascii(&document_, EXIF_PRIMARY, EXIF_SOFTWARE, "Pangea / Sensoraia"), "Set map software");
83 check(exif_document_ascii(&document_, EXIF_PRIMARY, 0x0110, "Pangea derived map"),
84 "Set orthophoto model");
86 "Reference-plane mosaic; relief displacement remains; see coverage metadata"),
87 "Set orthophoto description");
88 std::ostringstream json;
89 json.imbue(std::locale::classic());
90 json << std::setprecision(15)
91 << "{\"source\":\"pangea/survey\",\"pose\":\"derived_map_center\",\"mode\":" << jsonString(image.mode)
92 << ",\"projection\":" << jsonString(image.mode == "simple" ? "flat_plane_mosaic" : "fast_seam_multiband_mosaic")
93 << ",\"datum\":\"WGS-84\","
94 "\"gps_altitude_meaning\":\"zero_reference_datum_not_camera_or_surface\","
95 "\"crs\":\"EPSG:" << image.map.epsg << "\",\"pixel_size_m\":" << image.map.pixelSize
96 << ",\"center_easting_m\":" << image.map.east << ",\"center_northing_m\":" << image.map.north
97 << ",\"width\":" << image.width << ",\"height\":" << image.height
98 << ",\"grid_up_heading_deg\":0,\"valid_fraction\":" << image.validFraction
99 << ",\"confidence_mask\":null,\"surface_heights\":null,"
100 "\"absolute_accuracy\":\"simulator_coordinates_not_surveyed\",";
101 json << "\"relief_corrected\":false,\"reference_plane_amsl_m\":" << image.referencePlane << ',';
102 if (mosaicMode(image.mode))
103 json << "\"render_method\":" << jsonString(mosaicRenderMethod(image.seamMethod.empty() ? "graphcut" : image.seamMethod)) << ','
104 << "\"seam_scale\":" << image.seamScale << ",\"blend_bands\":" << image.blendBands
105 << ",\"exposure_compensation\":" << (image.exposureCompensated ? "true" : "false")
106 << ",\"geometry_fraction\":0,\"corroborated_fraction\":0"
107 << ",\"reconstructed_fraction\":" << image.reconstructedFraction
108 << ",\"reconstruction_blend_fraction\":" << image.reconstructionBlendFraction
109 << ",\"observed_colour_fraction\":" << image.validFraction - image.reconstructedFraction
110 << ",\"confidence_classes\":{\"0\":\"unfilled\",\"16\":\"source_derived_reconstruction\","
111 "\"48\":\"observed_reconstruction_transition\",\"64\":\"reference_plane_colour_only\"},";
112 const auto sources = sourceMetadata(image.sources);
113 if (sources.size() <= 40000) {
114 json << "\"sources\":" << sources;
115 if (!sourceCompanion.empty()) json << ",\"source_metadata_file\":" << jsonString(sourceCompanion);
116 } else {
117 if (sourceCompanion.empty()) throw std::runtime_error("Large map source provenance requires a companion JSON");
118 json << "\"sources_embedded\":false,\"source_count\":" << image.sources.size()
119 << ",\"source_metadata_file\":" << jsonString(sourceCompanion);
120 }
121 json << '}';
122 const auto text = json.str();
123 const unsigned char prefix[] = {'A', 'S', 'C', 'I', 'I', 0, 0, 0};
124 if (text.size() > EXIF_MAX_PAYLOAD - sizeof(prefix) - 1)
125 throw std::runtime_error("Map provenance exceeds EXIF capacity");
127 static_cast<std::uint32_t>(text.size() + 9));
128 for (std::size_t offset = 0; offset < sizeof(prefix); ++offset) comment[offset] = prefix[offset];
129 for (std::size_t offset = 0; offset < text.size(); ++offset)
130 comment[sizeof(prefix) + offset] = static_cast<unsigned char>(text[offset]);
131 comment[sizeof(prefix) + text.size()] = 0;
132 std::size_t size = 0;
133 check(exif_serialize(&document_, payload_.data(), payload_.size(), &size), "Serialize orthophoto EXIF");
134 return {payload_.data(), size};
135 }
136};
137}
138#endif
size_t size
Definition chdk_pipe.c:143
Serialize source-camera provenance and map-grid metadata for orthophotos.
Definition map_exif.h:36
Payload buildOrtho(const OrthoImage &image, const MapProjection &projection, const std::string &sourceCompanion={})
Build EXIF for an orthophoto and reference any external source list.
Definition map_exif.h:78
static std::string sourceMetadata(const std::vector< OrthoSource > &sources)
Encode each source image's optical, geographic, and timing provenance.
Definition map_exif.h:43
Forward and inverse WGS-84 Transverse Mercator conversion for one UTM zone.
std::pair< double, double > inverse(double east, double north) const
Convert UTM easting/northing back to WGS-84 latitude/longitude.
Build bounded EXIF payloads for simulator-generated source photos.
Definition photo_exif.h:91
Payload build(const PhotoPosition &position, int width, int height, const std::optional< PhotoCamera > &camera={})
Construct EXIF from validated photo position and optional camera evidence.
Definition photo_exif.h:194
std::array< unsigned char, EXIF_MAX_PAYLOAD > payload_
Definition photo_exif.h:94
exif_document document_
Definition photo_exif.h:93
static std::string jsonString(const std::string &text)
Escape a string as a JSON string literal.
Definition photo_exif.h:456
void coordinate(double degrees, std::uint16_t referenceTag, std::uint16_t valueTag, char positive, char negative)
Encode a validated geographic coordinate as EXIF GPS rationals.
Definition photo_exif.h:127
unsigned char * reserve(exif_directory directory, std::uint16_t tag, exif_format format, std::uint32_t count)
Allocate one field in the bounded EXIF document.
Definition photo_exif.h:112
static void check(int result, const char *operation)
Convert a C EXIF status into the mapper's error path.
Definition photo_exif.h:100
int exif_serialize(const struct exif_document *document, unsigned char *payload, size_t capacity, size_t *size)
Serialize a document into one complete EXIF APP1 payload.
Definition exifite.c:736
#define EXIF_MAX_PAYLOAD
APP1 payload ceiling: the JPEG length includes its own two bytes.
Definition exifite.h:51
int exif_document_ascii(struct exif_document *document, enum exif_directory directory, uint16_t tag, const char *text)
Replace an ASCII field, including its terminating NUL byte.
Definition exifite.c:543
@ EXIF_UNDEFINED
Definition exifite.h:70
@ EXIF_CAMERA
Definition exifite.h:59
@ EXIF_PRIMARY
Definition exifite.h:59
@ EXIF_IMAGE_DESCRIPTION
Definition exifite.h:80
@ EXIF_SOFTWARE
Definition exifite.h:85
@ EXIF_USER_COMMENT
Definition exifite.h:93
bool mosaicMode(const std::string &mode)
Return whether a supported processing mode uses the Great mosaic.
Definition map_config.h:80
std::string mosaicRenderMethod(const std::string &method)
Give a stable descriptive name to a Great seam-and-blend renderer.
Definition map_config.h:108
Describe the validated photo set and render projected map windows.
Encode simulated-camera pose, optics, and uncertainty into EXIF.
Rendered BGRA map plus coverage, source list, and method provenance.
Definition ortho_map.h:78
Borrowed serialized EXIF bytes held in this object's workspace.
Definition photo_exif.h:180
struct captured_image image
Definition usher.c:371