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_config.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_config.h
20 * @brief Own the survey mapper's validated configuration and mode defaults.
21 * @details CLI overrides are applied before mode-specific defaults so the
22 * resulting configuration has one explicit owner and one validation path.
23 * The low-memory profile further narrows that configuration to a supported
24 * bounded workflow instead of pretending every option fits on a small board.
25 */
26#ifndef PANGEA_MAP_CONFIG_H
27#define PANGEA_MAP_CONFIG_H
28
29#include "ini_file.h"
30#include <limits>
31#include <thread>
32#include <unistd.h>
33
34namespace pangea_survey {
35/**
36 * @brief Fully parsed settings shared by orthomap and XYZ export.
37 * @details Distances are metres, coordinates are WGS-84 degrees, and image
38 * dimensions are pixels. `lowMemory` describes a process policy, not measured
39 * whole-board headroom or a hard resident-memory limit.
40 */
41struct MapConfig {
43 int jpegWidth = 700, jpegHeight = 1100;
44 unsigned long quality = 95;
45 double mapPixelSize = .1;
46 double minCoverage = .999, referencePlane = std::numeric_limits<double>::quiet_NaN();
47 double mosaicReferencePlane = std::numeric_limits<double>::quiet_NaN();
49 bool mosaicExposure = true;
50 std::string mosaicSeamMethod = "graphcut";
51 int mosaicOverviewPixels = 4000000;
54 bool mosaicFillGaps = false;
55 bool lowMemory = false;
56 int memoryMiB = 192, reserveMiB = 192, blockCacheMiB = 8;
57 std::filesystem::path workingDirectory;
58 std::filesystem::path preparedSourceDirectory;
59 std::filesystem::path sourceDirectory;
60 std::filesystem::path photoDirectory, cameraProfile;
62 bool allowRecordedPose = false;
63 bool incrementalPreview = false;
65 std::filesystem::path livePauseFile, liveFinalFile;
66 unsigned mosaicThreads = std::max(1u, std::min(32u, std::thread::hardware_concurrency()));
67 std::string outputFormat = "orthomap";
68 int xyzZoom = 19, xyzMinZoom = 19;
69 bool xyzCompleteOnly = false;
70 std::string mode = "simple", orthoEngine = "simple", blend = "seam";
72 std::optional<std::size_t> expectedSaved;
73 bool allowIncomplete = false;
74 std::optional<UtcDateTime> startupUtc;
75 std::string weatherPreset = "unchanged";
76 std::filesystem::path weatherReadback;
77};
78
79/** @brief Return whether a supported processing mode uses the Great mosaic. */
80inline bool mosaicMode(const std::string& mode) {
81 return mode == "great";
82}
83
84/**
85 * @brief Select one of the two supported processing modes and apply its defaults.
86 * @param[in,out] config Settings to update.
87 * @param[in] mode Exact supported name: `simple` or `great`.
88 * @throws std::runtime_error If @p mode is not supported.
89 * @note Explicit INI values are loaded afterward and may override mode defaults.
90 */
91inline void mapMode(MapConfig& config, const std::string& mode) {
92 if (mode != "simple" && mode != "great")
93 throw std::runtime_error("processing.mode must be simple or great");
94 config.mode = mode;
95 config.orthoEngine = mosaicMode(mode) ? "mosaic" : "simple";
96 if (mode == "great") {
97 config.mosaicSeamMethod = "graphcut";
98 config.mosaicOverviewPixels = 8000000;
99 config.mosaicPhotoCacheMiB = 1024;
100 config.mosaicOverviewSourceMaxSide = 512;
101 config.mosaicFillGaps = true;
102 config.mosaicSeamScale = 4;
103 config.mosaicBlendBands = 4;
104 }
105}
106
107/** @brief Give a stable descriptive name to a Great seam-and-blend renderer. */
108inline std::string mosaicRenderMethod(const std::string& method) {
109 return "overview_" + (method == "graphcut" ? std::string("graph_cut") : method) + "_multiband";
110}
111
112/** @brief Normalize INI paths to the host filesystem's UTF-8 path parser. */
113inline std::filesystem::path configPath(std::string text) {
114 for (char& ch : text) {
115 if (ch == '\\') ch = '/';
116 }
117 return std::filesystem::u8path(text);
118}
119
120/**
121 * @brief Load and validate a survey INI plus its capture manifest or source CSV.
122 * @param[in] path Configuration file path; relative inputs resolve beside it.
123 * @param[in] modeOverride Optional exact CLI mode override, applied before defaults.
124 * @return A complete configuration whose source CSV exists and matches its contract.
125 * @throws std::runtime_error For unknown settings, invalid values, inconsistent
126 * capture metadata, unsupported profile combinations, or missing inputs.
127 */
128inline MapConfig loadMapConfig(const std::filesystem::path& path, const std::string& modeOverride = {}) {
129 const IniFile ini(path);
130 ini.validate({"input.capture_manifest", "input.source_csv", "input.allow_incomplete",
131 "input.photo_directory", "input.camera_profile", "input.max_pose_uncertainty_m", "input.pose_policy",
132 "start.lat", "start.lon", "end.lat", "end.lon", "processing.mode",
133 "map.pixel_size_m", "map.tile_width", "map.tile_height",
134 "simple.reference_plane_amsl_m", "simple.blend",
135 "mosaic.seam_method", "mosaic.seam_scale", "mosaic.blend_bands", "mosaic.exposure_compensation",
136 "mosaic.overview_pixels",
137 "mosaic.photo_cache_mib", "mosaic.threads", "mosaic.reference_plane_amsl_m",
138 "mosaic.overview_source_max_side",
139 "mosaic.fill_gaps",
140 "live.update_seconds", "live.batch_photos", "live.cpu_percent", "live.pause_file", "live.final_file",
141 "runtime.profile", "runtime.memory_mib", "runtime.reserve_mib",
142 "output.directory", "output.jpeg_quality", "output.format", "tiles.zoom", "tiles.min_zoom", "tiles.complete_only",
143 "quality.min_colour_coverage"});
144 const auto base = std::filesystem::absolute(path).parent_path();
145 MapConfig config;
146 mapMode(config, modeOverride.empty() ? ini.text("processing.mode", "simple") : modeOverride);
147 const auto profile = ini.text("runtime.profile", "auto");
148 if (profile != "auto" && profile != "desktop" && profile != "low_memory")
149 throw std::runtime_error("runtime.profile must be auto, desktop or low_memory");
150 const long pages = sysconf(_SC_PHYS_PAGES), pageSize = sysconf(_SC_PAGESIZE);
151 config.lowMemory = profile == "low_memory" || (profile == "auto" && pages > 0 && pageSize > 0 &&
152 static_cast<unsigned long long>(pages) * pageSize <= 1024ull * 1024 * 1024);
153 if (config.lowMemory) {
154 config.mosaicOverviewPixels = 250000;
155 config.mosaicPhotoCacheMiB = 8;
156 config.mosaicThreads = 1;
157 }
158 config.outputFormat = ini.text("output.format", "orthomap");
159 if (config.outputFormat != "orthomap" && config.outputFormat != "xyz")
160 throw std::runtime_error("output.format must be orthomap or xyz");
161 if (config.outputFormat != "xyz" && (ini.has("tiles.zoom") || ini.has("tiles.min_zoom") ||
162 ini.has("tiles.complete_only")))
163 throw std::runtime_error("tiles settings require output.format=xyz");
164 if (config.outputFormat == "xyz" && (ini.has("map.pixel_size_m") || ini.has("map.tile_width") ||
165 ini.has("map.tile_height")))
166 throw std::runtime_error("XYZ grid uses tiles.zoom and fixed 256-pixel tiles; remove map grid settings");
167 config.allowIncomplete = ini.boolean("input.allow_incomplete");
168 if (int(ini.has("input.capture_manifest")) + int(ini.has("input.source_csv")) +
169 int(ini.has("input.photo_directory")) != 1)
170 throw std::runtime_error("Specify exactly one input.capture_manifest, input.source_csv or input.photo_directory");
171 if (ini.has("input.capture_manifest")) {
172 config.captureManifest = base / configPath(ini.text("input.capture_manifest"));
173 const IniFile manifest(config.captureManifest);
174 manifest.validate({"capture.schema", "capture.status", "capture.source_csv", "capture.planned", "capture.saved",
175 "start.lat", "start.lon", "start.agl", "end.lat", "end.lon", "end.agl",
176 "camera.lens_profile", "camera.lock_start_altitude", "camera.tile_overlap",
177 "acquisition.start_lat", "acquisition.start_lon", "acquisition.end_lat", "acquisition.end_lon",
178 "simulation.weather_preset", "simulation.utc_datetime"});
179 if (manifest.text("capture.schema") != "tessavia_capture_v1")
180 throw std::runtime_error("Unsupported capture manifest schema");
181 const auto status = manifest.text("capture.status");
182 if (status == "in_progress" || (status != "complete" && status != "interrupted"))
183 throw std::runtime_error("Capture is unfinished or its status is invalid");
184 if (status != "complete" && !config.allowIncomplete)
185 throw std::runtime_error("Interrupted capture requires input.allow_incomplete=1");
186 const auto count = [&](const char* key) {
187 const double value = manifest.required(key);
188 range(value, 0, 1e9, key);
189 if (value != std::floor(value))
190 throw std::runtime_error(std::string(key) + " must be integer");
191 return static_cast<std::size_t>(value);
192 };
193 const auto planned = count("capture.planned"), saved = count("capture.saved");
194 if (saved == 0 || (planned != 0 && (saved > planned || (status == "complete" && saved != planned))))
195 throw std::runtime_error("Capture manifest saved/planned counts disagree with its status");
196 config.expectedSaved = saved;
197 const auto csv = configPath(manifest.text("capture.source_csv"));
198 if (csv.empty() || csv.has_parent_path()) throw std::runtime_error("Manifest CSV must be a local filename");
199 config.sourceCsv = config.captureManifest.parent_path() / csv;
200 config.start = {manifest.required("start.lat"), manifest.required("start.lon"), manifest.required("start.agl")};
201 config.end = {manifest.required("end.lat"), manifest.required("end.lon"), manifest.required("end.agl")};
202 } else if (ini.has("input.photo_directory")) {
203 config.photoDirectory = base / configPath(ini.text("input.photo_directory"));
204 config.cameraProfile = base / configPath(ini.text("input.camera_profile"));
205 config.maxPoseUncertainty = ini.numeric("input.max_pose_uncertainty_m", 5);
206 range(config.maxPoseUncertainty, 0, 100, "input.max_pose_uncertainty_m");
207 const auto policy = ini.text("input.pose_policy", "exposure");
208 if (policy != "exposure" && policy != "recorded")
209 throw std::runtime_error("input.pose_policy must be exposure or recorded");
210 config.allowRecordedPose = policy == "recorded";
211 if (config.allowRecordedPose && ini.has("input.max_pose_uncertainty_m"))
212 throw std::runtime_error("Recorded-pose input cannot certify max_pose_uncertainty_m; use exposure policy for that gate");
213 if (!std::filesystem::is_directory(config.photoDirectory) || !std::filesystem::is_regular_file(config.cameraProfile))
214 throw std::runtime_error("AI Camera input requires an existing photo_directory and camera_profile");
215 } else {
216 config.sourceCsv = base / configPath(ini.text("input.source_csv"));
217 }
218 const bool bounds = ini.has("start.lat") || ini.has("start.lon") || ini.has("end.lat") || ini.has("end.lon");
219 if (bounds || config.captureManifest.empty()) {
220 config.start.lat = ini.required("start.lat"); config.start.lon = ini.required("start.lon");
221 config.end.lat = ini.required("end.lat"); config.end.lon = ini.required("end.lon");
222 }
223 for (const auto& point : {config.start, config.end}) {
224 range(point.lat, -80, 84, "map latitude"); range(point.lon, -180, 180, "map longitude");
225 }
226 if (config.start.lat == config.end.lat || config.start.lon == config.end.lon ||
227 std::abs(config.start.lon - config.end.lon) >= 180)
228 throw std::runtime_error("Map needs nonzero bounds in one supported UTM region");
229 config.mapPixelSize = ini.numeric("map.pixel_size_m", .1);
230 range(config.mapPixelSize, .05, 2, "map.pixel_size_m");
231 const auto integer = [&](const char* key, int fallback, int low, int high) {
232 const auto value = ini.numeric(key, fallback);
233 range(value, low, high, key);
234 if (value != std::floor(value)) throw std::runtime_error(std::string(key) + " must be integer");
235 return static_cast<int>(value);
236 };
237 config.jpegWidth = integer("map.tile_width", 700, 1, 4096);
238 config.jpegHeight = integer("map.tile_height", 1100, 1, 4096);
239 config.xyzZoom = integer("tiles.zoom", 19, 0, 22);
240 config.xyzMinZoom = integer("tiles.min_zoom", config.xyzZoom, std::max(0, config.xyzZoom - 2), config.xyzZoom);
241 config.xyzCompleteOnly = ini.boolean("tiles.complete_only");
242 config.quality = static_cast<unsigned long>(integer("output.jpeg_quality", 95, 1, 100));
243 if (ini.has("simple.reference_plane_amsl_m"))
244 config.referencePlane = ini.required("simple.reference_plane_amsl_m");
245 if (ini.has("mosaic.reference_plane_amsl_m")) {
246 config.mosaicReferencePlane = ini.required("mosaic.reference_plane_amsl_m");
247 }
248 config.mosaicSeamScale = integer("mosaic.seam_scale", config.mosaicSeamScale, 4, 64);
249 config.mosaicBlendBands = integer("mosaic.blend_bands", config.mosaicBlendBands, 1, 4);
250 config.mosaicExposure = ini.boolean("mosaic.exposure_compensation", config.mosaicExposure);
251 config.mosaicOverviewPixels = integer("mosaic.overview_pixels", config.mosaicOverviewPixels, 250000, 8000000);
252 config.mosaicPhotoCacheMiB = integer("mosaic.photo_cache_mib", config.mosaicPhotoCacheMiB,
253 config.lowMemory ? 1 : 128, config.lowMemory ? 16 : 8192);
254 config.mosaicOverviewSourceMaxSide = integer("mosaic.overview_source_max_side", config.mosaicOverviewSourceMaxSide, 64, 2048);
255 config.mosaicFillGaps = ini.boolean("mosaic.fill_gaps", config.mosaicFillGaps);
256 if (config.mosaicFillGaps && !mosaicMode(config.mode))
257 throw std::runtime_error("mosaic.fill_gaps requires Great processing");
258 config.mosaicSeamMethod = ini.text("mosaic.seam_method", config.mosaicSeamMethod);
259 if (config.mosaicSeamMethod != "graphcut" && config.mosaicSeamMethod != "dp" && config.mosaicSeamMethod != "voronoi")
260 throw std::runtime_error("mosaic.seam_method must be graphcut, dp or voronoi");
261 config.mosaicThreads = static_cast<unsigned>(integer("mosaic.threads", static_cast<int>(config.mosaicThreads), 1, 32));
262 config.blend = ini.text("simple.blend", "seam");
263 if (config.blend != "seam" && config.blend != "feather")
264 throw std::runtime_error("simple.blend must be seam or feather");
265 config.minCoverage = ini.numeric("quality.min_colour_coverage", config.outputFormat == "xyz" ? 1 : .999);
266 range(config.minCoverage, .001, 1, "quality.min_colour_coverage");
267 if (config.outputFormat == "xyz" && config.minCoverage != 1)
268 throw std::runtime_error("Opaque XYZ JPEG tiles require quality.min_colour_coverage=1");
269 config.output = base / configPath(ini.text("output.directory",
270 config.outputFormat == "xyz" ? "Pictures/XYZ" : "maps"));
271 config.memoryMiB = integer("runtime.memory_mib", 192, 128, 192);
272 config.reserveMiB = integer("runtime.reserve_mib", 192, 192, 4096);
273 config.liveUpdateSeconds = integer("live.update_seconds", 30, 1, 3600);
274 config.liveBatchPhotos = integer("live.batch_photos", 4, 1, 4096);
275 config.liveCpuPercent = integer("live.cpu_percent", 20, 1, 100);
276 if (ini.has("live.pause_file")) config.livePauseFile = base / configPath(ini.text("live.pause_file"));
277 if (ini.has("live.final_file")) config.liveFinalFile = base / configPath(ini.text("live.final_file"));
278 if (config.lowMemory && (config.mode != "great" || config.outputFormat != "xyz" ||
279 config.mosaicSeamMethod != "graphcut" ||
280 !config.mosaicFillGaps || config.xyzCompleteOnly || config.mosaicThreads != 1 ||
281 config.mosaicOverviewPixels > 250000 || config.mosaicBlendBands > 4))
282 throw std::runtime_error("Low-memory profile requires Great XYZ with graphcut seams, gap filling, "
283 "one worker and at most 250000 overview pixels; no omitted tiles");
284 if (!config.photoDirectory.empty() && (!config.lowMemory || config.mode != "great" || config.outputFormat != "xyz" ||
285 !std::isfinite(config.mosaicReferencePlane)))
286 throw std::runtime_error("AI Camera photos require low_memory GREAT XYZ and mosaic.reference_plane_amsl_m in FC navigation datum");
287 if (config.photoDirectory.empty() && (ini.has("input.camera_profile") || ini.has("input.max_pose_uncertainty_m") || ini.has("input.pose_policy")))
288 throw std::runtime_error("AI Camera settings require input.photo_directory");
289 if (config.photoDirectory.empty() && !std::filesystem::is_regular_file(config.sourceCsv))
290 throw std::runtime_error("Missing source CSV: " + config.sourceCsv.u8string());
291 return config;
292}
293}
294#endif
Read scalar values from a bounded, section-based INI file.
Definition ini_file.h:38
static bool bounds(const struct coverage_state *state, const struct coverage_candidate *candidate, struct coverage_bounds *box)
Reject unusable polygons before converting coordinates or scanning cells.
Parse strict section-qualified INI settings for the survey mapper.
static struct usher_camera_profile profile
MapConfig loadMapConfig(const std::filesystem::path &path, const std::string &modeOverride={})
Load and validate a survey INI plus its capture manifest or source CSV.
Definition map_config.h:128
std::filesystem::path configPath(std::string text)
Normalize INI paths to the host filesystem's UTF-8 path parser.
Definition map_config.h:113
void range(double value, double minimum, double maximum, const std::string &name)
Enforce the inclusive policy bounds for a parsed setting.
Definition route.h:160
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
void mapMode(MapConfig &config, const std::string &mode)
Select one of the two supported processing modes and apply its defaults.
Definition map_config.h:91
static size_t count
Definition pose_log.c:79
Fully parsed settings shared by orthomap and XYZ export.
Definition map_config.h:41
std::filesystem::path workingDirectory
Definition map_config.h:57
std::string weatherPreset
Definition map_config.h:75
std::filesystem::path preparedSourceDirectory
Definition map_config.h:58
std::filesystem::path livePauseFile
Definition map_config.h:65
std::filesystem::path originalSourceCsv
Definition map_config.h:71
std::filesystem::path cameraProfile
Definition map_config.h:60
std::filesystem::path sourceCsv
Definition map_config.h:71
unsigned long quality
Definition map_config.h:44
std::filesystem::path sourceDirectory
Definition map_config.h:59
std::optional< std::size_t > expectedSaved
Definition map_config.h:72
std::filesystem::path weatherReadback
Definition map_config.h:76
std::optional< UtcDateTime > startupUtc
Definition map_config.h:74
std::filesystem::path liveFinalFile
Definition map_config.h:65
std::filesystem::path output
Definition map_config.h:71
std::filesystem::path photoDirectory
Definition map_config.h:60
std::filesystem::path captureManifest
Definition map_config.h:71
std::string mosaicSeamMethod
Definition map_config.h:50
Geographic route point; latitude/longitude are degrees and AGL is metres.
Definition route.h:48