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_pipeline.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_pipeline.h
20 * @brief Orchestrate orthophoto rendering, evidence, and final publication.
21 * @details Each output directory begins with an incomplete marker and is marked
22 * complete only after all required images and manifests have been finalized.
23 * Diagnostic runs intentionally retain incomplete status because they inspect
24 * imagery/coverage but do not pass the production publication gate.
25 */
26#ifndef PANGEA_MAP_PIPELINE_H
27#define PANGEA_MAP_PIPELINE_H
28
29#include "binary_output.h"
30/**
31 * @brief Render orthophoto tiles and publish their coverage/provenance manifest.
32 * @param[in] config Validated map settings and colour-coverage threshold.
33 * @param[in] csv Source CSV, normalized by the caller when required.
34 * @param[in] diagnostic Render inspectable evidence without publishing a complete dataset.
35 * @param[in] progress Optional caller-owned progress reporter.
36 * @param[in] first Starting progress percentage for a larger pipeline.
37 * @return Zero after successful rendering and finalization.
38 * @throws std::runtime_error If rendering, coverage policy, or publication fails.
39 * @note Coverage acceptance is not surveyed-accuracy certification.
40 */
41static int orthorectify(const pangea_survey::MapConfig& config, const fs::path& csv, bool diagnostic = false,
42 pangea_survey::MapProgress* progress = nullptr, double first = 0) {
43 std::unique_ptr<pangea_survey::MapProgress> ownedProgress;
44 if (!progress) {
45 ownedProgress = std::make_unique<pangea_survey::MapProgress>(diagnostic ? "Diagnostic progress" : "Map progress");
46 progress = ownedProgress.get();
47 }
48 const double renderStart = first + (99 - first) * .02;
49 progress->stage("Loading sources and surface", first, renderStart);
50 pangea_survey::Orthorectifier processor(config, csv);
51 const auto directory = config.output / ("orthomap_" + sessionName());
52 fs::create_directories(directory);
53 std::cout << "Pangea " << config.mode << ": " << processor.columns() << " x " << processor.rows()
54 << " final tiles, zero tile overlap, " << config.mapPixelSize
55 << " m/projected pixel. Output: " << directory.u8string() << '\n';
58 const pangea_survey::MapProjection projection((config.start.lat + config.end.lat) / 2,
59 (config.start.lon + config.end.lon) / 2);
60 std::ofstream manifest(directory / "orthophotos.csv");
61 manifest << "filename,row,column,epsg,center_easting_m,center_northing_m,pixel_size_m,width,height,"
62 "valid_fraction,projection,source_csv\n";
63 if (!manifest) throw std::runtime_error("Cannot create orthophoto manifest");
64 const auto incomplete = "{\"complete\":false,\"mode\":" + pangea_survey::PhotoExif::jsonString(config.mode) + "}";
65 // Keep the incomplete marker until every required tile and final manifest exist.
66 saveBinary(directory / "dataset.incomplete.json", incomplete.data(), incomplete.size());
67 progress->stage(diagnostic ? "Rendering diagnostic evidence" : "Creating and saving map tiles", renderStart, 99);
68 int effectiveSeamScale = 0;
69 double effectiveReferencePlane = std::numeric_limits<double>::quiet_NaN();
70 for (std::size_t i = 0; i < processor.size(); ++i) {
71 const auto detail = "tile " + std::to_string(i + 1) + "/" + std::to_string(processor.size());
72 progress->detail(detail);
73 auto image = processor.render(i, isStopping, [&](double fraction) {
74 progress->update((i + .95 * fraction) / processor.size(), detail);
75 });
76 effectiveSeamScale = image.seamScale;
77 effectiveReferencePlane = image.referencePlane;
78 std::ostringstream basename;
79 basename << "ortho_r" << std::setfill('0') << std::setw(5) << i / processor.columns()
80 << "_c" << std::setw(5) << i % processor.columns();
81 const auto base = directory / basename.str();
82 std::ostringstream geometry;
83 geometry.imbue(std::locale::classic());
84 geometry << std::setprecision(15) << "{\"epsg\":" << image.map.epsg
85 << ",\"center_easting_m\":" << image.map.east << ",\"center_northing_m\":" << image.map.north
86 << ",\"pixel_size_m\":" << image.map.pixelSize << ",\"width\":" << image.width
87 << ",\"height\":" << image.height << ",\"valid_fraction\":" << image.validFraction
88 << ",\"mode\":" << pangea_survey::PhotoExif::jsonString(config.mode)
89 << ",\"height_encoding\":null"
90 << ",\"relief_corrected\":false,\"reference_plane_amsl_m\":" << image.referencePlane
91 << ",\"confidence_classes\":{\"0\":\"no_colour\",\"16\":\"source_derived_reconstruction\","
92 "\"48\":\"observed_reconstruction_transition\",\"64\":\"flat_plane_colour_only\"}";
94 geometry << ",\"render_method\":" << pangea_survey::PhotoExif::jsonString(pangea_survey::mosaicRenderMethod(image.seamMethod))
95 << ",\"seam_scale\":" << image.seamScale
96 << ",\"blend_bands\":" << image.blendBands
97 << ",\"reconstructed_fraction\":" << image.reconstructedFraction
98 << ",\"reconstruction_blend_fraction\":" << image.reconstructionBlendFraction
99 << ",\"observed_colour_fraction\":" << image.validFraction - image.reconstructedFraction
100 << ",\"exposure_compensation\":" << (image.exposureCompensated ? "true" : "false")
101 << ",\"geometry_fraction\":0,\"corroborated_fraction\":0";
102 geometry << '}';
103 const auto geometryText = geometry.str();
104 saveBinary(base.string() + ".geometry.json", geometryText.data(), geometryText.size());
105 const fs::path sourceCompanion = base.string() + ".sources.json";
106 const auto sourcesText = "{\"source_csv\":" + pangea_survey::PhotoExif::jsonString(csv.u8string()) +
107 ",\"sources\":" + pangea_survey::MapExif::sourceMetadata(image.sources) + "}";
108 saveBinary(sourceCompanion, sourcesText.data(), sourcesText.size());
109 if (diagnostic) {
110 const fs::path preview = base.string() + ".diagnostic.jpg";
111 const auto jpeg = encoder.encode(image.bgra.data(), image.width, image.height,
112 image.width * 4, static_cast<int>(config.quality));
113 if (pangea_survey::mosaicMode(config.mode)) {
114 const auto metadata = exif.buildOrtho(image, projection, sourceCompanion.filename().u8string());
115 pangea_survey::MapWriter::writeMap(preview, image.map, image.width, image.height, false);
116 JpegEncoder::save(jpeg, preview, metadata.data, metadata.size);
117 } else JpegEncoder::save(jpeg, preview);
118 // Diagnostic artifacts help inspect coverage but are never a completed publication.
119 std::cout << "Diagnostic only: unapproved image/coverage evidence saved; no final tile published.\n";
120 progress->update(static_cast<double>(i + 1) / processor.size(), detail);
121 continue;
122 }
123 // Refuse a plausible-looking output tile when unsupported pixels exceed policy.
124 if (image.validFraction < config.minCoverage)
125 throw std::runtime_error("Map colour coverage is below quality.min_colour_coverage; final JPEG not published. "
126 "Inspect saved coverage evidence; acquire additional source photos or reduce the requested bounds.");
127 const fs::path path = base.string() + ".jpg";
128 auto world = path; world.replace_extension(".jgw");
129 const fs::path aux = path.string() + ".aux.xml";
130 try {
131 pangea_survey::MapWriter::writeMap(path, image.map, image.width, image.height, false);
132 const auto metadata = exif.buildOrtho(image, projection, sourceCompanion.filename().u8string());
133 const auto jpeg = encoder.encode(image.bgra.data(), image.width, image.height,
134 image.width * 4, static_cast<int>(config.quality));
135 JpegEncoder::save(jpeg, path, metadata.data, metadata.size);
136 } catch (...) {
137 for (const auto& file : {world, aux}) {
138 std::error_code error;
139 fs::remove(file, error);
140 if (error) std::cerr << "WARNING: Cannot clean unpublished orthophoto metadata: " << error.message() << '\n';
141 }
142 throw;
143 }
144 manifest << path.filename().u8string() << ',' << i / processor.columns() << ',' << i % processor.columns()
145 << ',' << image.map.epsg << ',' << std::setprecision(15) << image.map.east
146 << ',' << image.map.north << ',' << image.map.pixelSize << ',' << image.width
147 << ',' << image.height << ',' << image.validFraction << ','
148 << (config.mode == "simple" ? "flat_plane_mosaic" : "fast_seam_multiband_mosaic") << ",\"";
149 for (const char ch : csv.u8string()) { if (ch == '"') manifest << '"'; manifest << ch; }
150 manifest << "\"\n";
151 manifest.flush();
152 if (!manifest) throw std::runtime_error("Cannot write orthophoto manifest");
153 std::cout << "Saved " << config.mode << " map tile " << path.filename().u8string() << '\n';
154 progress->update(static_cast<double>(i + 1) / processor.size(), detail);
155 }
156 progress->stage("Finalizing dataset metadata", 99, 99.9);
157 manifest.close();
158 if (!manifest) throw std::runtime_error("Cannot finalize orthophoto manifest");
159 std::ostringstream dataset;
160 dataset.imbue(std::locale::classic());
161 dataset << std::setprecision(15) << "{\"complete\":" << (diagnostic ? "false" : "true")
162 << ",\"application\":\"pangea\",\"mode\":" << pangea_survey::PhotoExif::jsonString(config.mode)
163 << ",\"blend\":" << pangea_survey::PhotoExif::jsonString(pangea_survey::mosaicMode(config.mode) ? "multiband" : config.blend)
164 << ",\"min_colour_coverage\":" << config.minCoverage
165 << ",\"relief_corrected\":false"
166 << ",\"reference_plane_amsl_m\":" << effectiveReferencePlane;
167 dataset << ",\"mosaic_seam_scale\":" << effectiveSeamScale
168 << ",\"mosaic_blend_bands\":" << (pangea_survey::mosaicMode(config.mode) ? config.mosaicBlendBands : 0)
169 << ",\"mosaic_exposure_compensation\":" << (pangea_survey::mosaicMode(config.mode) && config.mosaicExposure ? "true" : "false")
170 << ",\"mosaic_seam_method\":" << pangea_survey::PhotoExif::jsonString(config.mosaicSeamMethod)
171 << ",\"mosaic_overview_pixels\":" << config.mosaicOverviewPixels
172 << ",\"mosaic_photo_cache_mib\":" << config.mosaicPhotoCacheMiB
173 << ",\"mosaic_overview_source_max_side\":" << config.mosaicOverviewSourceMaxSide
174 << ",\"mosaic_fill_gaps\":" << (config.mosaicFillGaps ? "true" : "false")
175 << ",\"gap_fill_method\":" << pangea_survey::PhotoExif::jsonString(config.mosaicFillGaps ? "global_source_push_pull" : "none")
176 << ",\"mosaic_threads\":" << config.mosaicThreads
177 << ",\"render_method\":" << pangea_survey::PhotoExif::jsonString(pangea_survey::mosaicMode(config.mode) ?
178 pangea_survey::mosaicRenderMethod(config.mosaicSeamMethod) : "flat_plane_mosaic")
179 << ",\"original_source_csv\":" << pangea_survey::PhotoExif::jsonString(config.originalSourceCsv.u8string())
180 << ",\"diagnostic\":" << (diagnostic ? "true" : "false")
181 << ",\"accuracy_certified\":false,\"columns\":" << processor.columns()
182 << ",\"rows\":" << processor.rows() << ",\"pixel_size_m\":" << config.mapPixelSize
183 << ",\"tile_width\":" << config.jpegWidth << ",\"tile_height\":" << config.jpegHeight
184 << ",\"output_overlap_pixels\":0,\"source_csv\":" << pangea_survey::PhotoExif::jsonString(csv.u8string())
185 << ",\"requested_startup_utc\":"
186 << (config.startupUtc ? pangea_survey::PhotoExif::jsonString(config.startupUtc->text) : "null")
187 << ",\"requested_weather_preset\":" << pangea_survey::PhotoExif::jsonString(config.weatherPreset)
188 << ",\"weather_verification\":"
189 << (config.weatherReadback.empty() ? "null" : "\"SDK_FlightSave_readback_before_capture\"")
190 << ",\"weather_readback_file\":"
191 << (config.weatherReadback.empty() ? "null" : pangea_survey::PhotoExif::jsonString(config.weatherReadback.u8string()))
192 << ",\"capture_utc\":"
193 << (processor.captureUtc() ? pangea_survey::PhotoExif::jsonString(processor.captureUtc()->text) : "null")
194 << ",\"simulation_time_continues\":" << (processor.captureUtc() ? "false" : "null")
195 << ",\"utc_hold_method\":"
196 << (processor.captureUtc() ? "\"repeated_simconnect_clock_resets\"" : "null") << "}";
197 const auto datasetText = dataset.str();
198 saveBinary(directory / "dataset.json", datasetText.data(), datasetText.size());
199 if (!fs::remove(directory / "dataset.incomplete.json"))
200 throw std::runtime_error("Cannot remove incomplete dataset marker");
201 std::cout << (diagnostic ? "Diagnostic render completed; not a completed map dataset.\n" :
202 "Map dataset completed; coverage is not surveyed accuracy certification.\n");
203 progress->finish();
204 return 0;
205}
206#endif
Publish immutable result files without exposing partial contents.
void saveBinary(const fs::path &path, const void *data, std::size_t size)
Write bytes to a new path and publish them by same-directory rename.
Reusable IJG compressor and JPEG publisher.
static void save(const Image &image, const std::filesystem::path &path, const unsigned char *exif=nullptr, std::size_t exifSize=0, bool durable=false)
Publish encoded JPEG bytes, optionally adding one EXIF APP1 segment.
Serialize source-camera provenance and map-grid metadata for orthophotos.
Definition map_exif.h:36
static std::string sourceMetadata(const std::vector< OrthoSource > &sources)
Encode each source image's optical, geographic, and timing provenance.
Definition map_exif.h:43
Thread-safe progress reporter for staged map work.
Forward and inverse WGS-84 Transverse Mercator conversion for one UTM zone.
static void writeMap(const fs::path &path, const pangea_survey::MapTile &map, int width, int height, bool orthorectified=false)
Publish a world file and GIS projection metadata for one map image.
Definition map_writer.h:96
Load a fixed-session source set and render its projected tiles/windows.
Definition ortho_map.h:98
std::size_t size() const
Return total requested map tiles.
std::optional< UtcDateTime > captureUtc() const
Return the validated common capture UTC target, when present.
std::size_t rows() const
Return output tile rows.
OrthoImage render(std::size_t index, const std::function< bool()> &stopped, const std::function< void(double)> &progress={})
Render one configured output tile.
std::size_t columns() const
Return output tile columns.
static std::string jsonString(const std::string &text)
Escape a string as a JSON string literal.
Definition photo_exif.h:456
struct exif_document exif
Definition lwir_image.c:64
struct jpeg_compress_struct encoder
Definition lwir_image.c:59
struct jpeg_error_mgr error
Definition lwir_image.c:60
static int orthorectify(const pangea_survey::MapConfig &config, const fs::path &csv, bool diagnostic=false, pangea_survey::MapProgress *progress=nullptr, double first=0)
Render orthophoto tiles and publish their coverage/provenance manifest.
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
Fully parsed settings shared by orthomap and XYZ export.
Definition map_config.h:41
std::string weatherPreset
Definition map_config.h:75
std::filesystem::path originalSourceCsv
Definition map_config.h:71
unsigned long quality
Definition map_config.h:44
std::filesystem::path weatherReadback
Definition map_config.h:76
std::optional< UtcDateTime > startupUtc
Definition map_config.h:74
std::filesystem::path output
Definition map_config.h:71
std::string mosaicSeamMethod
Definition map_config.h:50
static bool isStopping()
Check cancellation at a cooperative mapping boundary.
Definition survey.cpp:68
static std::string sessionName()
Create a readable, millisecond-resolution session label.
Definition survey.cpp:103
struct captured_image image
Definition usher.c:371