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
pangea.cpp
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 pangea.cpp
20 * @brief Resumable, resource-bounded USHER photo-map assembler.
21 * @details Consumes clean USHER JPEGs, validates pose/geometry provenance, and
22 * incrementally blends them into checksummed map tiles. Atomic state/checkpoint
23 * files allow interrupted runs to resume. MIMIC and explicit real-camera
24 * profiles are separate input modes; this flat-ground renderer does not certify
25 * map accuracy.
26 */
27
28// clang-format off
29#include <stddef.h>
30#include <stdio.h>
31#include <jpeglib.h>
32// clang-format on
33#include "exifite.h"
34extern "C" {
35#include "sha256fst.h"
36}
37
38#include <opencv2/core/persistence.hpp>
39#include <opencv2/calib3d.hpp>
40#include <opencv2/features2d.hpp>
41#include <opencv2/imgproc.hpp>
42#include <dirent.h>
43#include <fcntl.h>
44#include <linux/ioprio.h>
45#include <poll.h>
46#include <pthread.h>
47#include <sched.h>
48#include <sys/file.h>
49#include <sys/prctl.h>
50#include <sys/resource.h>
51#include <sys/stat.h>
52#include <sys/statvfs.h>
53#include <sys/syscall.h>
54#include <unistd.h>
55
56#include <algorithm>
57#include <array>
58#include <atomic>
59#include <cerrno>
60#include <chrono>
61#include <cmath>
62#include <condition_variable>
63#include <csetjmp>
64#include <csignal>
65#include <cstdint>
66#include <cstdio>
67#include <filesystem>
68#include <fstream>
69#include <functional>
70#include <iomanip>
71#include <iostream>
72#include <map>
73#include <memory>
74#include <mutex>
75#include <sstream>
76#include <stdexcept>
77#include <string>
78#include <thread>
79#include <vector>
80
81#include "version.h"
82#include "map_storage.h"
83#include "camera_profile.h"
84#include "opencv_json.hpp"
85#include "opencv_parallel.hpp"
86#include "jpeg_stream.h"
87
88/** Internal worker implementation; keeping the pipeline in one namespace aids
89 * code navigation. */
90namespace pangea_detail {
92namespace fs = std::filesystem;
93/** Binary-size unit for explicit resident-memory and disk-reserve accounting.
94 */
95constexpr uint64_t mib = 1024 * 1024;
96/** Hard virtual-address ceiling prevents OpenCV allocations exceeding the
97 * worker budget. */
98constexpr uint64_t memory_limit = 128 * mib;
99/** Radians per degree conversion used by pose and camera rotations. */
100constexpr double pi = 3.14159265358979323846;
101/** Slippy-map world width at zoom 18: 256 pixels per tile times 2^18 tiles. */
102constexpr double world_pixels = 256.0 * (1 << 18);
103/** Web-Mercator ground resolution scale at the equator for this zoom level. */
104constexpr double projected_pixel_m = 2 * pi * 6378137.0 / world_pixels;
105/** Slippy-map tile side length in pixels. */
106constexpr int tile_size = 256;
107/** Bound total accepted source photos and the on-disk checkpoint sequence. */
108constexpr int max_photos = 10000;
109std::atomic<sig_atomic_t> stopping{0};
110static_assert(decltype(stopping)::is_always_lock_free,
111 "Signal cancellation requires lock-free atomic access");
112pid_t parent_pid = 0;
113
114/** Signal handler records cancellation; normal code performs checkpoint-safe
115 * shutdown. */
116void stop(int) { stopping = 1; }
117
118/** Throw a worker-level error that reaches the single CLI diagnostic handler.
119 */
120void check(bool condition, const char* message) {
121 if (!condition) throw std::runtime_error(message);
122}
123
124/** Read one clock as fractional seconds for CPU-duty accounting and deadlines.
125 * @param clock Clock identifier.
126 * @return Seconds with nanosecond fraction. */
127double seconds(clockid_t clock) {
128 timespec value{};
129 check(clock_gettime(clock, &value) == 0, "clock unavailable");
130 return value.tv_sec + value.tv_nsec * 1e-9;
131}
132
133/** Read one named kB counter from Linux procfs and return bytes.
134 * @param path procfs status file.
135 * @param wanted Counter name including trailing colon.
136 * @return Counter in bytes, or zero when unavailable. */
137uint64_t proc_kib(const char* path, const char* wanted) {
138 std::ifstream input(path);
139 std::string line;
140 while (std::getline(input, line)) {
141 std::istringstream values(line);
142 std::string key, unit;
143 uint64_t amount = 0;
144 if (values >> key >> amount >> unit && key == wanted && unit == "kB")
145 return amount * 1024;
146 }
147 return 0;
148}
149
151 std::vector<std::thread> workers;
152 std::mutex mutex;
153 std::condition_variable ready, completed;
154 std::function<void(size_t)> task;
155 size_t next_job = 0, job_count = 0, active = 0;
156 size_t peak_active = 0;
157 bool shutdown = false;
158 std::exception_ptr failure;
159 std::atomic<bool> cancel{false};
160
161 /** @brief Claim and execute jobs until the coordinator shuts down the pool.
162 * @details Execute callbacks outside the mutex. On failure, stop assigning
163 * jobs but let in-flight callbacks drain before the batch returns. */
164 void work() {
165 std::unique_lock<std::mutex> lock(mutex);
166 for (;;) {
167 ready.wait(lock, [this] { return shutdown || next_job < job_count; });
168 if (shutdown) return;
169 const size_t job = next_job++;
170 ++active;
171 peak_active = std::max(peak_active, active);
172 lock.unlock();
173 try {
174 task(job);
175 } catch (...) {
176 lock.lock();
177 if (!failure) failure = std::current_exception();
178 cancel = true;
180 lock.unlock();
181 }
182 lock.lock();
183 --active;
184 if (active == 0 && next_job == job_count) completed.notify_one();
185 }
186 }
187
188 public:
189 /** @brief Start the desktop worker pool.
190 * @param count Number of worker threads.
191 * @details Block termination signals while spawning so workers inherit
192 * the mask and shutdown remains the coordinator's responsibility. */
193 explicit DesktopPool(size_t count) {
194 sigset_t blocked, previous;
195 sigemptyset(&blocked);
196 sigaddset(&blocked, SIGINT);
197 sigaddset(&blocked, SIGTERM);
198 check(pthread_sigmask(SIG_BLOCK, &blocked, &previous) == 0,
199 "cannot mask desktop worker signals");
200 try {
201 for (size_t index = 0; index < count; ++index)
202 workers.emplace_back([this] { work(); });
203 check(pthread_sigmask(SIG_SETMASK, &previous, nullptr) == 0,
204 "cannot restore coordinator signals");
205 } catch (...) {
206 {
207 std::lock_guard<std::mutex> lock(mutex);
208 shutdown = true;
209 }
210 ready.notify_all();
211 for (auto& worker : workers) worker.join();
212 pthread_sigmask(SIG_SETMASK, &previous, nullptr);
213 throw;
214 }
215 }
216 /** @brief Wake and join the workers before destroying shared batch state.
217 * @pre No coordinator call to @ref run is in progress. */
219 {
220 std::lock_guard<std::mutex> lock(mutex);
221 shutdown = true;
222 }
223 ready.notify_all();
224 for (auto& worker : workers) worker.join();
225 }
226 /** @brief Report the fixed worker capacity.
227 * @return Number of threads, whether idle or active. */
228 size_t size() const { return workers.size(); }
229 /** @brief Read the lifetime concurrency high-water mark.
230 * @return Greatest number of simultaneously active jobs. */
231 size_t peak_workers() {
232 std::lock_guard<std::mutex> lock(mutex);
233 return peak_active;
234 }
235 /** @brief Check whether the current batch has failed or been interrupted.
236 * @return True when workers should stop at their next checkpoint. */
237 bool cancelled() const { return cancel.load(); }
238
239 /** @brief Run indexed work and wait for every active callback to finish.
240 * @param count Number of jobs.
241 * @param operation Worker callback; invocations may overlap.
242 * @param checkpoint Coordinator callback for resource and stop checks.
243 * @details Poll the checkpoint while waiting. Preserve the first failure
244 * and rethrow it only after callbacks no longer borrow batch state.
245 * @pre One coordinator calls this method; it is not reentrant. */
246 void run(size_t count, std::function<void(size_t)> operation,
247 const std::function<void()>& checkpoint) {
248 std::unique_lock<std::mutex> lock(mutex);
249 task = std::move(operation);
251 next_job = 0;
252 failure = nullptr;
253 cancel = false;
254 ready.notify_all();
255 while (active != 0 || next_job != job_count) {
256 completed.wait_for(lock, std::chrono::milliseconds(20));
257 lock.unlock();
258 try {
259 checkpoint();
260 } catch (...) {
261 lock.lock();
262 if (!failure) failure = std::current_exception();
263 cancel = true;
265 lock.unlock();
266 }
267 lock.lock();
268 }
269 task = {};
270 if (failure) std::rethrow_exception(failure);
271 }
272};
273
274/** Apply idle-priority scheduling and cooperative memory/CPU/pause checks. */
276 double last_cpu = seconds(CLOCK_PROCESS_CPUTIME_ID);
277 double last_wall = seconds(CLOCK_MONOTONIC);
278 const double started_cpu = last_cpu;
279 const double started_wall = last_wall;
280 uint64_t previous_total = 0, previous_idle = 0;
281 double idle_fraction = 0;
282 double sampled_at = 0;
283 uint64_t reserve; /**< RAM left for Linux, camera buffers and concurrent
284 services. */
285 double duty; /**< Maximum fraction of one CPU core used over each checkpoint
286 interval. */
287 fs::path pause_file; /**< Operator-controlled file whose existence suspends
288 processing. */
289 bool desktop_mode = false;
291 std::unique_ptr<DesktopPool> pool;
292 public:
293 /** @brief Establish mapping limits for onboard or desktop execution.
294 * @param reserve_mb Required available memory reserve in MiB.
295 * @param cpu_percent Onboard CPU budget as a percentage of one core.
296 * @param pause Optional path whose existence pauses work.
297 * @param desktop Whether to provision desktop workers.
298 * @details Keep the onboard policy conservative; desktop concurrency is
299 * capped by both available memory and CPU affinity. */
300 Resources(uint64_t reserve_mb, int cpu_percent, fs::path pause = {},
301 bool desktop = false)
302 : reserve(reserve_mb * mib),
303 duty(cpu_percent / 100.0),
304 pause_file(std::move(pause)), desktop_mode(desktop) {
305 check(reserve_mb >= 192 && reserve_mb <= 4096 && cpu_percent >= 1 &&
306 cpu_percent <= 20,
307 "reserve must be 192..4096 MiB; CPU duty must be 1..20 percent of "
308 "one core");
309 rlimit address{memory_limit, memory_limit}, core{0, 0}, files{64, 64};
310 if (desktop_mode) {
311 check(proc_kib("/proc/meminfo", "MemTotal:") >= 2 * 1024 * mib,
312 "--desktop requires at least 2 GiB RAM; MORA must use default mode");
313 check(getrlimit(RLIMIT_AS, &address) == 0,
314 "cannot read inherited address-space limit");
315 address_limit = address.rlim_cur == RLIM_INFINITY ? 0 : address.rlim_cur;
316 duty = 1;
317 files = {256, 256};
318 } else {
319 check(setrlimit(RLIMIT_AS, &address) == 0,
320 "cannot install resource limits");
321 }
322 check(setrlimit(RLIMIT_CORE, &core) == 0 &&
323 setrlimit(RLIMIT_NOFILE, &files) == 0,
324 "cannot install resource limits");
325 sched_param parameters{};
326 if (!desktop_mode) {
327 check(setpriority(PRIO_PROCESS, 0, 19) == 0 &&
328 sched_setscheduler(0, SCHED_IDLE, &parameters) == 0,
329 "cannot enable idle CPU scheduling");
330 check(syscall(SYS_ioprio_set, IOPRIO_WHO_PROCESS, 0,
331 IOPRIO_PRIO_VALUE(IOPRIO_CLASS_IDLE, 0)) == 0,
332 "cannot enable idle I/O scheduling");
333 }
334 check(prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) == 0,
335 "cannot disable privilege escalation");
336 cv::setNumThreads(1);
337 if (desktop_mode) {
338 cpu_set_t affinity;
339 CPU_ZERO(&affinity);
340 check(sched_getaffinity(0, sizeof(affinity), &affinity) == 0,
341 "desktop CPU affinity unavailable");
342 const uint64_t available_memory =
343 proc_kib("/proc/meminfo", "MemAvailable:");
344 check(available_memory > reserve + memory_limit + 16 * mib,
345 "insufficient RAM headroom for desktop workers");
346 const uint64_t memory_workers =
347 (available_memory - reserve - memory_limit) / (16 * mib);
348 const size_t count = std::min<uint64_t>(
349 std::min(CPU_COUNT(&affinity), 64), memory_workers);
350 check(count > 0, "no desktop worker capacity");
351 pool = std::make_unique<DesktopPool>(count);
352 }
353 }
354
355 /** @brief Check which execution policy was selected.
356 * @return True for desktop execution. */
357 bool desktop() const { return desktop_mode; }
358 /** @brief Check whether tile processing may continue.
359 * @details In desktop mode the coordinator samples resources; workers only
360 * observe batch cancellation. Serial execution runs the full checkpoint. */
362 if (pool) check(!pool->cancelled(), "desktop tile work cancelled");
363 else checkpoint();
364 }
365 /** @brief Run a desktop batch under the coordinator's resource policy.
366 * @param count Number of indexed jobs.
367 * @param task Thread-safe job callback.
368 * @details Check headroom before dispatch and continue sampling while waiting. */
369 void parallel_tiles(size_t count, std::function<void(size_t)> task) {
370 check(bool(pool), "desktop worker pool unavailable");
371 checkpoint();
372 pool->run(count, std::move(task), [this] { checkpoint(); });
373 }
374 /** @brief Estimate how many photos can be prepared in one desktop batch.
375 * @param photo_budget_mib Nonzero estimated peak memory per photo in MiB.
376 * @return Batch size from one photo through the worker count.
377 * @details Preserve reserve and worker overhead before dividing the remaining
378 * headroom. The minimum allows serial preparation, not a memory guarantee.
379 * @pre Desktop worker pool is initialized. */
380 size_t photo_batch_capacity(uint64_t photo_budget_mib = 128) const {
381 const uint64_t available_memory =
382 proc_kib("/proc/meminfo", "MemAvailable:");
383 const uint64_t overhead = reserve + memory_limit + pool->size() * 16 * mib;
384 if (available_memory <= overhead) return 1;
385 return std::max<size_t>(1, std::min<uint64_t>(
386 pool->size(), (available_memory - overhead) / (photo_budget_mib * mib)));
387 }
388
389 /** Report whether system headroom currently meets the configured reserve and
390 * duty budget. */
391 bool available() {
392 if (!pause_file.empty()) {
393 struct stat status{};
394 if (lstat(pause_file.c_str(), &status) == 0 || errno != ENOENT)
395 return false;
396 }
397 const double now = seconds(CLOCK_MONOTONIC);
398 if (desktop_mode)
399 return proc_kib("/proc/meminfo", "MemAvailable:") >= reserve;
400 // Sample procfs every quarter-second rather than once per pixel, row, or
401 // tile.
402 if (now - sampled_at >= 0.25) {
403 std::ifstream input("/proc/stat");
404 std::string label;
405 std::array<uint64_t, 8> ticks{};
406 input >> label;
407 uint64_t total = 0;
408 for (auto& value : ticks) {
409 input >> value;
410 total += value;
411 }
412 check(input.good() && label == "cpu", "CPU headroom unavailable");
413 if (previous_total && total > previous_total &&
414 ticks[3] >= previous_idle) {
415 idle_fraction = static_cast<double>(ticks[3] - previous_idle) /
416 (total - previous_total);
417 }
418 previous_total = total;
419 previous_idle = ticks[3];
420 sampled_at = now;
421 }
422 const uint64_t resident = proc_kib("/proc/self/status", "VmRSS:");
423 const uint64_t available_memory =
424 proc_kib("/proc/meminfo", "MemAvailable:");
425 // Require one quarter of system CPU to appear idle before this best-effort
426 // worker proceeds.
427 return resident > 0 &&
428 available_memory >=
429 reserve + memory_limit - std::min(resident, memory_limit) &&
430 idle_fraction >= 0.25;
431 }
432
433 /** Bound CPU duty by sleeping and stop work when memory, CPU or pause gates
434 * close.
435 * @throws std::runtime_error on cancellation or unavailable required system
436 * telemetry. */
437 /** Sleep to enforce CPU duty and wait while system headroom or operator pause
438 * is closed.
439 * @throws std::runtime_error on process cancellation or unavailable
440 * telemetry. */
441 void checkpoint() {
442 if (parent_pid && getppid() != parent_pid) stopping = 1;
443 check(!stopping, "interrupted; disk checkpoint retained");
444 const double now_cpu = seconds(CLOCK_PROCESS_CPUTIME_ID);
445 const double now_wall = seconds(CLOCK_MONOTONIC);
446 const double rest = desktop_mode ? 0 :
447 (now_cpu - last_cpu) / duty - (now_wall - last_wall);
448 const double deadline = now_wall + std::max(0.0, rest);
449 while (!stopping && seconds(CLOCK_MONOTONIC) < deadline) {
450 poll(nullptr, 0,
451 static_cast<int>(std::clamp(
452 std::ceil((deadline - seconds(CLOCK_MONOTONIC)) * 1000), 1.0,
453 1000.0)));
454 if (parent_pid && getppid() != parent_pid) stopping = 1;
455 }
456 while (!stopping && !available()) {
457 poll(nullptr, 0, 1000);
458 if (parent_pid && getppid() != parent_pid) stopping = 1;
459 }
460 check(!stopping, "interrupted; disk checkpoint retained");
461 last_cpu = now_cpu;
462 last_wall = seconds(CLOCK_MONOTONIC);
463 }
464
465 /** Summarize active limits and measured process peak in the run report. */
467 Json result = Json::object({{"schema", "PANGEA_RESOURCES_V1"},
468 {"address_space_limit_bytes", address_limit},
469 {"reserve_bytes", reserve},
470 {"cpu_duty_percent", duty * 100 * (pool ? pool->size() : 1)},
471 {"scheduler", desktop_mode ? "inherited" : "SCHED_IDLE"},
472 {"threads", pool ? static_cast<int>(pool->size()) : cv::getNumThreads()},
473 {"available", available()},
474 {"peak_rss_bytes", proc_kib("/proc/self/status", "VmHWM:")}});
475 if (desktop_mode) {
476 result.set("mode", "desktop");
477 result.set("cpu_throttled", false);
478 const double elapsed = seconds(CLOCK_MONOTONIC) - started_wall;
479 const double cpu = seconds(CLOCK_PROCESS_CPUTIME_ID) - started_cpu;
480 result.set("elapsed_wall_seconds", elapsed);
481 result.set("process_cpu_seconds", cpu);
482 result.set("average_cpu_percent", elapsed > 0 ? cpu / elapsed * 100 : 0);
483 result.set("peak_active_workers", static_cast<int>(pool->peak_workers()));
484 }
485 return result;
486 }
487};
488
489/** RAII closer keeps regular-file descriptors bounded on exception paths. */
491 /** @brief Release an owned, non-null file stream.
492 * @param file Stream transferred to the deleter.
493 * @note Callers that need to detect flush/close failures must close explicitly. */
494 void operator()(FILE* file) const { fclose(file); }
495};
496using File = std::unique_ptr<FILE, FileCloser>;
497/** RAII closer for directory scans that may exit through validation errors. */
499 /** @brief Release an owned, non-null directory stream.
500 * @param directory Stream transferred to the deleter. */
501 void operator()(DIR* directory) const { closedir(directory); }
502};
503using Directory = std::unique_ptr<DIR, DirectoryCloser>;
504/** Distinguish invalid source photos (record and continue) from failed map
505 * operations. */
506struct InvalidPhoto : std::runtime_error {
507 using std::runtime_error::runtime_error;
508};
509
510/** Reject an unusable photo without treating the whole batch as an
511 * infrastructure error. */
512void photo_check(bool condition, const char* message) {
513 if (!condition) throw InvalidPhoto(message);
514}
515
516/** Open a no-follow regular file and enforce its byte ceiling before decoding.
517 * @param path Input path.
518 * @param maximum Maximum file size in bytes.
519 * @return Owning stream, or throws InvalidPhoto for unsafe/unusable input. */
520File regular_file(const fs::path& path, uint64_t maximum) {
521 int descriptor =
522 open(path.c_str(), O_RDONLY | O_NONBLOCK | O_NOFOLLOW | O_CLOEXEC);
523 check(descriptor >= 0, "cannot open regular input");
524 struct stat status{};
525 if (fstat(descriptor, &status) != 0 || !S_ISREG(status.st_mode) ||
526 status.st_size < 0 || static_cast<uint64_t>(status.st_size) > maximum) {
528 throw InvalidPhoto("input exceeds regular-file limits");
529 }
530 File result(fdopen(descriptor, "rb"));
531 if (!result) close(descriptor);
532 check(bool(result), "cannot create input stream");
533 return result;
534}
535
536/** Persist directory-entry changes after atomic checkpoint publication.
537 * @param path Directory to synchronize. */
538void sync_directory(const fs::path& path) {
539 const int descriptor = open(path.c_str(), O_RDONLY | O_DIRECTORY | O_CLOEXEC);
540 check(descriptor >= 0, "cannot open checkpoint directory");
541 const int result = fsync(descriptor);
543 check(result == 0, "cannot synchronize checkpoint directory");
544}
545
546/** Same-directory temporary file committed with fsync+rename for crash-safe
547 * checkpoints. */
548/** Same-directory temporary output committed with flush, fsync, rename, and
549 * directory fsync. */
551 fs::path target, temporary;
553 /** @param destination Final path; its parent directory must already exist. */
554 explicit AtomicFile(const fs::path& destination) : target(destination) {
555 std::string pattern = destination.string() + ".tmp-XXXXXX";
556 const int descriptor = mkstemp(pattern.data());
557 check(descriptor >= 0, "cannot create checkpoint temporary");
558 temporary = pattern;
559 file.reset(fdopen(descriptor, "wb"));
560 if (!file) {
562 unlink(temporary.c_str());
563 }
564 check(bool(file), "cannot open checkpoint stream");
565 }
566 /** @brief Remove abandoned staging data without removing committed output. */
568 if (!temporary.empty()) unlink(temporary.c_str());
569 }
570 /** Append exact bytes to the temporary output. */
571 void write(const void* data, size_t length) {
572 check(fwrite(data, 1, length, file.get()) == length,
573 "checkpoint write failed");
574 }
575 /** @brief Append serialized text without adding a terminator or newline.
576 * @param value Exact bytes to append. */
577 void text(const std::string& value) { write(value.data(), value.size()); }
578 /** Durably publish the complete temporary file at target. */
579 void commit() {
580 check(fflush(file.get()) == 0 && fsync(fileno(file.get())) == 0,
581 "checkpoint flush failed");
582 check(fclose(file.release()) == 0, "checkpoint close failed");
583 check(rename(temporary.c_str(), target.c_str()) == 0,
584 "checkpoint publish failed");
585 temporary.clear();
586 sync_directory(target.parent_path());
587 }
588};
589
590/** Serialize one JSON checkpoint through AtomicFile rather than truncating live
591 * state. */
592/** Serialize a small state/profile record through atomic, durable file
593 * publication. */
594void write_json(const fs::path& path, const Json& value) {
595 AtomicFile output(path);
596 output.text(value.dump(2) + "\n");
597 output.commit();
598}
599
600/** Read a bounded regular JSON checkpoint. */
601/** Read a regular JSON state file subject to the 16 KiB input ceiling. */
602Json read_json(const fs::path& path) {
603 File input = regular_file(path, 16384);
604 std::array<char, 16385> bytes{};
605 size_t count = fread(bytes.data(), 1, bytes.size(), input.get());
606 check(!ferror(input.get()) && count <= 16384, "invalid checkpoint length");
607 try {
608 return Json::parse(bytes.begin(), bytes.begin() + count);
609 } catch (const Json::exception& error) {
610 throw std::runtime_error("invalid JSON file " + path.string() + ": " + error.what());
611 }
612}
613
614/** Return lowercase SHA-256 hex for tile payload and source-identity checks. */
615std::string digest(const void* data, size_t size) {
616 std::array<uint8_t, 32> hash{};
617 sha256_bytes(data, size, hash.data());
618 std::ostringstream result;
619 for (uint8_t byte : hash)
620 result << std::hex << std::setw(2) << std::setfill('0') << unsigned(byte);
621 return result.str();
622}
623
624/** Fingerprint a source from stable filesystem identity/metadata for resume
625 * validation.
626 * @param path Candidate photo.
627 * @param allow_missing Return empty for a source already removed by its
628 * producer.
629 * @return SHA-256 identity; content itself is not re-read for every directory
630 * scan. */
631std::string identity(const fs::path& path, bool allow_missing = false) {
632 struct stat status{};
633 const int result = lstat(path.c_str(), &status);
634 if (allow_missing && ((result != 0 && (errno == ENOENT || errno == ESTALE)) ||
635 (result == 0 && !S_ISREG(status.st_mode))))
636 return {};
637 check(result == 0 && S_ISREG(status.st_mode),
638 "source disappeared or is not regular");
639 std::ostringstream value;
640 value << path.filename().string() << ':' << status.st_dev << ':'
641 << status.st_ino << ':' << status.st_size << ':'
642 << status.st_mtim.tv_sec << ':' << status.st_mtim.tv_nsec << ':'
643 << status.st_ctim.tv_sec << ':' << status.st_ctim.tv_nsec;
644 const std::string text = value.str();
645 return digest(text.data(), text.size());
646}
647
648/** Read one bounded EXIF text entry without using NUL termination as its
649 * length. */
650std::string exif_text(const exif_view* metadata, exif_directory directory, uint16_t tag) {
651 exif_value entry{};
652 if (!exif_get(metadata, directory, tag, &entry)) return {};
654 (entry.format == EXIF_ASCII || entry.format == EXIF_UNDEFINED), "invalid EXIF field");
655 std::string text(reinterpret_cast<const char*>(entry.data), entry.size);
656 if (directory == EXIF_CAMERA && tag == EXIF_USER_COMMENT &&
657 text.compare(0, 8, std::string("ASCII\0\0\0", 8)) == 0)
658 text.erase(0, 8);
659 while (!text.empty() && text.back() == '\0') text.pop_back();
660 return text;
661}
662
663/** Require a finite JSON number within the field's physical or geometric range.
664 */
665double numeric(const Json& values, const char* key, double minimum,
666 double maximum) {
667 photo_check(values.contains(key) && values[key].is_number(),
668 (std::string("missing numeric geometry: ") + key).c_str());
669 const double result = values[key].get<double>();
670 photo_check(std::isfinite(result) && result >= minimum && result <= maximum,
671 "geometry out of range");
672 return result;
673}
674
675/** Compose roll, pitch, and yaw matrices in the aircraft frame's declared
676 * order. */
677cv::Matx33d rotation(double roll, double pitch, double yaw) {
678 const cv::Matx33d roll_matrix(1, 0, 0, 0, cos(roll), -sin(roll), 0, sin(roll),
679 cos(roll));
680 const cv::Matx33d pitch_matrix(cos(pitch), 0, sin(pitch), 0, 1, 0,
681 -sin(pitch), 0, cos(pitch));
682 const cv::Matx33d yaw_matrix(cos(yaw), -sin(yaw), 0, sin(yaw), cos(yaw), 0, 0,
683 0, 1);
684 return yaw_matrix * pitch_matrix * roll_matrix;
685}
686
687/** Load explicit real-camera intrinsics and mount geometry; reject unknown
688 * fields.
689 * @param path Empty for MIMIC, otherwise a PANGEA_CAMERA_V1 key=value file.
690 * @return Null for MIMIC, validated camera profile for real JPEGs. */
691Json camera_profile(const fs::path& path) {
692 if (path.empty()) return nullptr;
693 struct usher_camera_profile parsed{};
694 check(usher_camera_profile_read(path.c_str(), &parsed),
695 "invalid flat real-camera profile");
696 const struct coverage_camera& camera = parsed.calibration;
697 const std::string prefix(parsed.filename_prefix);
698 return Json::object({{"schema", "PANGEA_CAMERA_V1"},
699 {"width", camera.width},
700 {"height", camera.height},
701 {"fx", camera.fx},
702 {"fy", camera.fy},
703 {"cx", camera.cx},
704 {"cy", camera.cy},
705 {"mount_roll_deg", camera.mount_roll_deg},
706 {"mount_pitch_deg", camera.mount_pitch_deg},
707 {"mount_yaw_deg", camera.mount_yaw_deg},
708 {"filename_prefix", prefix}});
709}
710
711/** Inclusive slippy-map tile rectangle for accumulated mosaic coverage. */
712struct Bounds {
713 int left = 0, top = 0, right = -1, bottom = -1;
714 /** Empty until an accepted source photo contributes map coverage. */
715 bool empty() const { return right < left; }
716 /** Serialize the inclusive tile rectangle into checkpoint JSON. */
717 Json json() const { return Json::array({left, top, right, bottom}); }
718 /** Parse bounds and enforce zoom-18 world and maximum map-side constraints.
719 */
720 static Bounds from(const Json& value, int max_map_side = 8192) {
721 check(value.is_array() && value.size() == 4, "invalid map bounds");
722 Bounds result{value[0].get<int>(), value[1].get<int>(), value[2].get<int>(),
723 value[3].get<int>()};
724 check(
725 result.empty() ||
726 (result.left >= 0 && result.top >= 0 && result.right < (1 << 18) &&
727 result.bottom < (1 << 18) &&
728 result.right - result.left < max_map_side / tile_size &&
729 result.bottom - result.top < max_map_side / tile_size),
730 "map exceeds configured pixel side or Mercator limits");
731 return result;
732 }
733 /** @brief Extend the committed tile envelope without changing either input.
734 * @param other New footprint in tile coordinates.
735 * @param max_map_side Maximum allowed map side in pixels.
736 * @return Bounding rectangle, not a claim that all enclosed tiles have coverage.
737 * @details Reapply map limits to the union; individually acceptable
738 * footprints can breach the limit when combined. */
739 Bounds include(const Bounds& other, int max_map_side = 8192) const {
740 if (empty()) return other;
741 return from(Json::array({std::min(left, other.left), std::min(top, other.top),
742 std::max(right, other.right),
743 std::max(bottom, other.bottom)}), max_map_side);
744 }
745};
746
747/** Decoded source frame, pixel-to-world homography, and intersected tile
748 * bounds. */
749struct Photo {
750 cv::Mat image;
751 cv::Matx33d to_world;
753 /** Transform the four source-image corners into another image/tile plane. */
754 std::array<cv::Point2f, 4> corners(const cv::Matx33d& transform) const {
755 std::array<cv::Point2f, 4> result{};
756 const std::array<cv::Point, 4> pixels{{{0, 0},
757 {image.cols - 1, 0},
758 {image.cols - 1, image.rows - 1},
759 {0, image.rows - 1}}};
760 for (size_t index = 0; index < pixels.size(); ++index) {
761 const cv::Vec3d point =
762 transform * cv::Vec3d(pixels[index].x, pixels[index].y, 1);
763 result[index] = {float(point[0] / point[2]), float(point[1] / point[2])};
764 }
765 return result;
766 }
767 /** Convert source corners back to longitude/latitude for per-photo
768 * provenance. */
771 for (const cv::Point& pixel :
772 std::array<cv::Point, 4>{{{0, 0},
773 {image.cols - 1, 0},
774 {image.cols - 1, image.rows - 1},
775 {0, image.rows - 1}}}) {
776 const cv::Vec3d point = to_world * cv::Vec3d(pixel.x, pixel.y, 1);
777 const double world_x = point[0] / point[2], world_y = point[1] / point[2];
778 result.push_back(Json::array({world_x / world_pixels * 360 - 180,
779 atan(sinh(pi * (1 - 2 * world_y / world_pixels))) * 180 / pi}));
780 }
781 return result;
782 }
783 /** Validate source EXIF and derive a flat-ground source-pixel-to-world
784 * transform. MIMIC uses embedded geometry; real JPEGs require explicit
785 * intrinsics and mount angles so the worker never guesses a sensor model. */
786 void geometry(const exif_view* metadata, int width, int height, const Json& camera,
787 bool standard_profile) {
788 Json provenance;
789 const std::string document =
791 standard_profile = standard_profile &&
792 document.find("USHER_MOCK_MAP_V1") == std::string::npos;
793 if (camera.is_null() && !standard_profile) {
794 try {
795 provenance = Json::parse(document);
796 } catch (const Json::exception&) {
797 throw InvalidPhoto(
798 "missing MIMIC geometry; real JPEGs require --camera-profile");
799 }
800 const bool xyz_geometry = provenance.value("tile_scheme", "") == "XYZ";
801 // Older MIMIC EXIF used GOOGLE as a cache-layout token, not imagery provenance.
802 const bool legacy_cache_geometry = provenance.value("provider", "") == "GOOGLE";
804 provenance.is_object() &&
805 provenance.value("schema", "") == "USHER_MOCK_MAP_V1" &&
806 provenance.value("projection", "") == "pinhole_flat_ground" &&
807 (xyz_geometry || legacy_cache_geometry) &&
808 provenance.value("zoom", 0) == 18,
809 "only clean USHER MIMIC pinhole photos are supported");
810 } else if (!camera.is_null()) {
811 photo_check(document.find("USHER_MOCK_MAP_V1") == std::string::npos,
812 "mock photo in real-camera input");
813 photo_check(width == camera.at("width") && height == camera.at("height"),
814 "JPEG dimensions differ from real-camera profile");
815 }
817 .find("USHER_LENS_V1") == std::string::npos,
818 "lens derivative cannot be inverted without its shutter/lens "
819 "model; use clean photo");
820 exif_value orientation{};
821 uint32_t orientation_value = 0;
822 photo_check(!exif_get(metadata, EXIF_PRIMARY, EXIF_ORIENTATION, &orientation) ||
823 (orientation.format == EXIF_SHORT && orientation.count == 1 &&
824 exif_value_unsigned(&orientation, 0, &orientation_value) && orientation_value == 1),
825 "unsupported EXIF orientation");
826 std::istringstream description(
828 std::string field;
829 std::getline(description, field, ';');
831 const bool flyeye = (standard_profile || !camera.is_null()) &&
832 field.find("FlyEye simulated camera") == 0;
833 if (flyeye) {
834 const Json pose = Json::parse(
836 photo_check(pose.value("source", "") == "FlyEye/MSFS2024" &&
837 pose.value("datum", "") == "WGS-84",
838 "unsupported FlyEye position metadata");
839 shot.set("lat_deg", pose.at("latitude_deg"));
840 shot.set("lon_deg", pose.at("longitude_deg"));
841 shot.set("groundalt_m", pose.at("agl_m"));
842 shot.set("roll_deg", 0);
843 shot.set("pitch_deg", 0);
844 shot.set("yaw_deg", 0);
845 } else {
846 photo_check(field.find("Paparazzi USHER ") == 0,
847 "missing USHER shot metadata");
848 std::map<std::string, std::string> fields;
849 while (std::getline(description, field, ';')) {
850 const size_t start = field.find_first_not_of(" \t\r\n"),
851 end = field.find_last_not_of(" \t\r\n");
852 photo_check(start != std::string::npos, "empty metadata field");
853 field = field.substr(start, end - start + 1);
854 const size_t separator = field.find('=');
855 photo_check(separator != std::string::npos &&
856 fields
857 .emplace(field.substr(0, separator),
858 field.substr(separator + 1))
859 .second,
860 "duplicate or invalid metadata field");
861 }
862 for (const char* key : {"lat_deg", "lon_deg", "roll_deg", "pitch_deg",
863 "yaw_deg", "groundalt_m"}) {
864 std::string selected = key;
865 if (camera.is_null() &&
866 (selected == "lat_deg" || selected == "lon_deg") &&
867 fields.count("original_" + selected))
868 selected = "original_" + selected;
869 photo_check(fields.count(selected), "missing shot field");
870 try {
871 size_t consumed = 0;
872 shot.set(key, std::stod(fields.at(selected), &consumed));
873 photo_check(consumed == fields.at(selected).size(),
874 "invalid shot number");
875 } catch (const std::logic_error&) {
876 throw InvalidPhoto("invalid shot number");
877 }
878 }
879 }
880 const double latitude = numeric(shot, "lat_deg", -85, 85) * pi / 180;
881 const double longitude = numeric(shot, "lon_deg", -180, 180);
882 const double altitude = numeric(shot, "groundalt_m", 0.1, 10000) /
884 const double roll = numeric(shot, "roll_deg", -180, 180) * pi / 180;
885 const double pitch = numeric(shot, "pitch_deg", -180, 180) * pi / 180;
886 const double yaw = numeric(shot, "yaw_deg", -360, 360) * pi / 180;
887 cv::Matx33d rays, mount = cv::Matx33d::eye();
888 if (camera.is_null()) {
889 const double horizontal =
890 standard_profile ? tan(60 * pi / 360) :
891 tan(numeric(provenance, "horizontal_fov_deg", 1, 170) * pi / 360);
892 const double vertical =
893 standard_profile ? horizontal * (height - 1) / (width - 1) :
894 tan(numeric(provenance, "vertical_fov_deg", 1, 170) * pi / 360);
895 rays = cv::Matx33d(0, -2 * vertical / (height - 1), vertical,
896 2 * horizontal / (width - 1), 0, -horizontal, 0, 0, 1);
897 } else {
898 const double fx = camera.at("fx").get<double>(), fy = camera.at("fy").get<double>(),
899 cx = camera.at("cx").get<double>(), cy = camera.at("cy").get<double>();
900 rays = cv::Matx33d(0, -1 / fy, cy / fy, 1 / fx, 0, -cx / fx, 0, 0, 1);
901 mount = rotation(camera.at("mount_roll_deg").get<double>() * pi / 180,
902 camera.at("mount_pitch_deg").get<double>() * pi / 180,
903 camera.at("mount_yaw_deg").get<double>() * pi / 180);
904 }
905 const cv::Matx33d ground = rotation(roll, pitch, yaw) * mount * rays;
906 const double center_x = (longitude + 180) / 360 * world_pixels;
907 const double center_y =
908 (1 - asinh(tan(latitude)) / pi) * 0.5 * world_pixels;
909 to_world =
910 cv::Matx33d(0, altitude, center_x, -altitude, 0, center_y, 0, 0, 1) *
911 ground;
912 update_bounds(width, height);
913 }
914
915 /** @brief Recompute the tile footprint after setting the image homography.
916 * @param width Source columns in pixels.
917 * @param height Source rows in pixels.
918 * @details Check homogeneous depth before dividing. Reject horizon,
919 * dateline and oversized footprints instead of creating unbounded tile work.
920 * @throws InvalidPhoto If the candidate footprint violates a mapping limit. */
921 void update_bounds(int width, int height) {
922 double minimum_x = INFINITY, minimum_y = INFINITY, maximum_x = -INFINITY,
923 maximum_y = -INFINITY;
924 for (int row : {0, height - 1})
925 for (int column : {0, width - 1}) {
926 const cv::Vec3d point = to_world * cv::Vec3d(column, row, 1);
927 photo_check(point[2] > 0.01, "footprint reaches the horizon");
928 const double world_x = point[0] / point[2],
929 world_y = point[1] / point[2];
930 photo_check(std::isfinite(world_x) && std::isfinite(world_y) &&
931 world_x >= 0 && world_y >= 0 &&
932 world_x < world_pixels && world_y < world_pixels,
933 "footprint crosses Mercator/dateline boundary");
934 minimum_x = std::min(minimum_x, world_x);
935 maximum_x = std::max(maximum_x, world_x);
936 minimum_y = std::min(minimum_y, world_y);
937 maximum_y = std::max(maximum_y, world_y);
938 }
939 bounds = {
940 int(floor(minimum_x / tile_size)), int(floor(minimum_y / tile_size)),
941 int(floor(maximum_x / tile_size)), int(floor(maximum_y / tile_size))};
942 photo_check(bounds.right - bounds.left < 16 &&
943 bounds.bottom - bounds.top < 16 &&
944 (bounds.right - bounds.left + 1) *
945 (bounds.bottom - bounds.top + 1) <=
946 64,
947 "photo footprint exceeds 64-tile work limit");
948 }
949};
950
951struct JpegError {
952 jpeg_error_mgr manager{};
953 jmp_buf recovery;
954 void (*emit)(j_common_ptr, int) = nullptr;
955};
956/** @brief Route a libjpeg fatal callback to the active recovery point.
957 * @param state JPEG state whose error manager owns the jump buffer.
958 * @warning Does not return; recovery must be established before codec calls. */
959void jpeg_failure(j_common_ptr state) {
960 longjmp(reinterpret_cast<JpegError*>(state->err)->recovery, 1);
961}
962/** @brief Screen scan diagnostics before dispatching to libjpeg's usual handler.
963 * @param state JPEG state with the installed mapper error manager.
964 * @param level libjpeg message level. */
965void jpeg_message(j_common_ptr state, int level) {
967 reinterpret_cast<JpegError*>(state->err)->emit(state, level);
968}
969struct Decoder {
970 jpeg_decompress_struct state{};
972 bool created = false;
975 /** @brief Release codec allocations only if creation succeeded. */
977 if (created) jpeg_destroy_decompress(&state);
978 }
979};
980
981/** @brief Admit and decode one source JPEG into a projection-ready photo.
982 * @param path Source JPEG path.
983 * @param resources Resource and cancellation policy.
984 * @param camera Camera calibration/profile fields.
985 * @param standard_profile Whether the standard camera profile is active.
986 * @param parallel_decode Whether to use reusable per-worker decode state.
987 * @return Decoded image with its transform and tile footprint.
988 * @details Reuse decoder storage only within a worker thread; discard that
989 * state after fatal libjpeg recovery rather than reusing a failed codec. */
990Photo read_photo(const fs::path& path, Resources& resources,
991 const Json& camera, bool standard_profile = false,
992 bool parallel_decode = false) {
993 File input = regular_file(path, 32 * mib);
994 static thread_local std::unique_ptr<Decoder> cached_decoder;
995 std::unique_ptr<Decoder> local_decoder;
996 if (parallel_decode) {
997 if (!cached_decoder) cached_decoder = std::make_unique<Decoder>();
998 } else local_decoder = std::make_unique<Decoder>();
999 Decoder* const volatile decoder = parallel_decode ? cached_decoder.get() : local_decoder.get();
1000 decoder->state.err = jpeg_std_error(&decoder->error.manager);
1001 decoder->error.manager.error_exit = jpeg_failure;
1002 decoder->error.emit = decoder->error.manager.emit_message;
1003 decoder->error.manager.emit_message = jpeg_message;
1004 if (setjmp(decoder->error.recovery)) {
1005 if (parallel_decode) cached_decoder.reset();
1006 throw InvalidPhoto("invalid JPEG stream");
1007 }
1008 if (decoder->created) {
1009 jpeg_abort_decompress(&decoder->state);
1010 decoder->metadata = {};
1011 decoder->photo = {};
1012 } else {
1013 decoder->created = true;
1014 jpeg_create_decompress(&decoder->state);
1015 }
1016 jpeg_stdio_src(&decoder->state, input.get());
1017 jpeg_save_markers(&decoder->state, JPEG_APP0 + 1, 65533);
1018 photo_check(jpeg_read_header(&decoder->state, TRUE) == JPEG_HEADER_OK,
1019 "invalid JPEG header");
1020 const unsigned width = decoder->state.image_width,
1021 height = decoder->state.image_height;
1022 photo_check(width >= 2 && height >= 2 && width <= 4096 && height <= 4096 &&
1023 uint64_t(width) * height <=
1024 (camera.is_null() ? 8388608u : 16777216u) &&
1025 !decoder->state.progressive_mode,
1026 "unsupported JPEG size or progressive encoding");
1027 for (jpeg_saved_marker_ptr marker = decoder->state.marker_list; marker;
1028 marker = marker->next) {
1029 if (marker->marker != JPEG_APP0 + 1 || marker->data_length < 6 ||
1030 std::string(reinterpret_cast<const char*>(marker->data), 6) !=
1031 std::string("Exif\0\0", 6))
1032 continue;
1033 photo_check(!decoder->metadata.tiff, "multiple EXIF records");
1034 photo_check(exif_parse(&decoder->metadata, marker->data, marker->data_length) == 0,
1035 "malformed EXIF");
1036 }
1037 photo_check(decoder->metadata.tiff != nullptr, "missing EXIF");
1038 try {
1039 decoder->photo.geometry(&decoder->metadata, width, height, camera,
1040 standard_profile);
1041 } catch (const Json::exception&) {
1042 throw InvalidPhoto("malformed EXIF geometry");
1043 }
1044 if (parallel_decode) resources.tile_checkpoint();
1045 else resources.checkpoint();
1046 decoder->state.out_color_space = JCS_RGB;
1047 jpeg_start_decompress(&decoder->state);
1048 decoder->photo.image.create(height, width, CV_8UC3);
1049 while (decoder->state.output_scanline < height) {
1050 if (decoder->state.output_scanline % 32 == 0) {
1051 if (parallel_decode) resources.tile_checkpoint();
1052 else resources.checkpoint();
1053 }
1054 JSAMPROW row = decoder->photo.image.ptr(decoder->state.output_scanline);
1055 photo_check(jpeg_read_scanlines(&decoder->state, &row, 1) == 1,
1056 "incomplete JPEG scanline");
1057 }
1058 jpeg_finish_decompress(&decoder->state);
1059 photo_check(decoder->error.manager.num_warnings == 0, "damaged JPEG");
1060 return std::move(decoder->photo);
1061}
1062
1063/** Per-tile four-channel sums (RGB weighted totals and accumulated feather
1064 * weight). */
1065/** Per-tile RGB weighted sums plus total feather weight, stored for resumable
1066 * blending. */
1067struct Tile {
1068 uint64_t sequence = 0;
1069 cv::Mat sums{tile_size, tile_size, CV_32FC4, cv::Scalar::all(0)};
1070 /** Load and verify an existing tile; absent files represent zero coverage. */
1071 void load(const fs::path& path) {
1072 if (!fs::exists(path)) return;
1073 File input = regular_file(path, sums.total() * sums.elemSize() + 512);
1074 std::array<char, 512> header{};
1075 check(fgets(header.data(), header.size(), input.get()) != nullptr,
1076 "tile header missing");
1077 Json record;
1078 try {
1079 record = Json::parse(header.data());
1080 } catch (const Json::exception& error) {
1081 throw std::runtime_error("invalid tile header " + path.string() + ": " + error.what());
1082 }
1083 check(record.value("schema", "") == "PANGEA_TILE_V1",
1084 "invalid tile format");
1085 sequence = record.at("sequence").get<uint64_t>();
1086 check(sequence <= max_photos, "invalid tile sequence");
1087 const size_t length = sums.total() * sums.elemSize();
1088 check(fread(sums.data, 1, length, input.get()) == length &&
1089 fgetc(input.get()) == EOF && !ferror(input.get()),
1090 "invalid tile data length");
1091 check(record.at("sha256") == digest(sums.data, length),
1092 "tile checksum mismatch");
1093 check(cv::checkRange(sums, true, nullptr, 0, 255.0 * max_photos + 1),
1094 "invalid tile accumulation");
1095 }
1096 /** Atomically persist tile data and sequence so a pending photo can be
1097 * replayed safely. */
1098 void save(const fs::path& path) {
1099 const size_t length = sums.total() * sums.elemSize();
1100 AtomicFile output(path);
1101 output.text(Json::object({{"schema", "PANGEA_TILE_V1"},
1102 {"sequence", sequence},
1103 {"sha256", digest(sums.data, length)}})
1104 .dump() +
1105 "\n");
1106 output.write(sums.data, length);
1107 output.commit();
1108 }
1109};
1110
1111/** Return the deterministic checkpoint path for one zoom-18 tile coordinate. */
1112fs::path tile_path(const fs::path& root, int column, int row) {
1113 return root / "tiles" /
1114 (std::to_string(column) + "-" + std::to_string(row) + ".tile");
1115}
1116
1117/** Retain a 512 MiB filesystem reserve in addition to the next operation
1118 * estimate.
1119 * @param root Output/checkpoint filesystem path.
1120 * @param required Estimated additional bytes for the pending operation. */
1121void disk_headroom(const fs::path& root, uint64_t required) {
1122 struct statvfs status{};
1123 check(statvfs(root.c_str(), &status) == 0, "disk headroom unavailable");
1124 // Retain 512 MiB free for the OS, camera services and recovery beyond this
1125 // operation's estimate.
1126 check(uint64_t(status.f_bavail) * status.f_frsize >= 512 * mib + required,
1127 "disk reserve reached; checkpoint retained, free space and resume");
1128}
1129
1130/** Blend one validated photo into intersecting tiles, checkpointing each tile
1131 * atomically.
1132 * @param photo Source pixels, projection, and affected tile bounds.
1133 * @param root Tile/state directory.
1134 * @param sequence Unique accepted-photo sequence used to prevent duplicate
1135 * contribution.
1136 * @param resources Cooperative CPU/RAM/pause policy.
1137 * @param tile_column Independent destination tile column.
1138 * @param tile_row Independent destination tile row. */
1139void blend_tile(const Photo& photo, const fs::path& root, uint64_t sequence,
1140 Resources& resources, int tile_column, int tile_row) {
1141 resources.tile_checkpoint();
1142 disk_headroom(root, 2 * mib);
1143 const cv::Matx33d local = cv::Matx33d(1, 0, -tile_column * tile_size, 0,
1144 1, -tile_row * tile_size, 0, 0, 1) *
1145 photo.to_world;
1146 const auto footprint = photo.corners(local);
1147 const std::array<cv::Point2f, 4> rectangle{
1148 {{0, 0},
1149 {tile_size - 1, 0},
1150 {tile_size - 1, tile_size - 1},
1151 {0, tile_size - 1}}};
1152 std::vector<cv::Point2f> intersection;
1153 if (cv::intersectConvexConvex(footprint, rectangle, intersection) <= 0)
1154 return;
1155 const fs::path path = tile_path(root, tile_column, tile_row);
1156 Tile tile;
1157 tile.load(path);
1158 check(tile.sequence <= sequence, "tile newer than pending photo");
1159 if (tile.sequence == sequence) return;
1160 bool contributed = false;
1161 // Process 16-row strips so warp temporaries stay small on the 512 MiB
1162 // board.
1163 for (int start_row = 0; start_row < tile_size; start_row += 16) {
1164 resources.tile_checkpoint();
1165 const cv::Matx33d transform =
1166 cv::Matx33d(1, 0, -tile_column * tile_size, 0, 1,
1167 -tile_row * tile_size - start_row, 0, 0, 1) *
1168 photo.to_world;
1169 const cv::Matx33d inverse = transform.inv();
1170 cv::Mat warped;
1171 cv::warpPerspective(photo.image, warped, transform,
1172 cv::Size(tile_size, 16), cv::INTER_LINEAR,
1173 cv::BORDER_CONSTANT);
1174 for (int row = 0; row < warped.rows; ++row) {
1175 auto* sums = tile.sums.ptr<cv::Vec4f>(start_row + row);
1176 const auto* colors = warped.ptr<cv::Vec3b>(row);
1177 for (int column = 0; column < tile_size; ++column) {
1178 const cv::Vec3d source = inverse * cv::Vec3d(column, row, 1);
1179 if (source[2] <= 0) continue;
1180 const double source_x = source[0] / source[2],
1181 source_y = source[1] / source[2];
1182 const double edge =
1183 std::min({source_x, source_y, photo.image.cols - 1 - source_x,
1184 photo.image.rows - 1 - source_y});
1185 if (edge < 1) continue;
1186 // Feather the source edge over 12.5% of its smaller dimension to
1187 // soften seams.
1188 const float weight = std::min(
1189 1.0,
1190 edge / (0.125 * std::min(photo.image.cols, photo.image.rows)));
1191 contributed = true;
1192 for (int channel = 0; channel < 3; ++channel)
1193 sums[column][channel] += colors[column][channel] * weight;
1194 sums[column][3] += weight;
1195 }
1196 }
1197 }
1198 if (contributed) {
1199 tile.sequence = sequence;
1200 tile.save(path);
1201 }
1202}
1203
1204/** @brief Apply one photo to the tiles enclosed by its footprint.
1205 * @param photo Validated source image and projection.
1206 * @param root Output map directory.
1207 * @param sequence Pending photo sequence used for replay protection.
1208 * @param resources Serial or desktop execution policy.
1209 * @details Desktop jobs operate on distinct tile files; onboard processing
1210 * walks the same tile envelope serially to limit resource use. */
1211void blend(const Photo& photo, const fs::path& root, uint64_t sequence,
1213 if (resources.desktop()) {
1214 const int columns = photo.bounds.right - photo.bounds.left + 1;
1215 const int rows = photo.bounds.bottom - photo.bounds.top + 1;
1216 resources.parallel_tiles(static_cast<size_t>(columns) * rows,
1217 [&](size_t index) {
1218 blend_tile(photo, root, sequence, resources,
1219 photo.bounds.left + static_cast<int>(index % columns),
1220 photo.bounds.top + static_cast<int>(index / columns));
1221 });
1222 return;
1223 }
1224 for (int tile_row = photo.bounds.top; tile_row <= photo.bounds.bottom;
1225 ++tile_row) {
1226 for (int tile_column = photo.bounds.left; tile_column <= photo.bounds.right;
1227 ++tile_column) {
1228 blend_tile(photo, root, sequence, resources, tile_column, tile_row);
1229 }
1230 }
1231}
1232
1234 int column = 0, row = 0;
1235 cv::Mat colors, weights;
1236};
1237
1240 std::vector<cv::KeyPoint> keypoints;
1241 cv::Matx33d to_world;
1242 cv::Matx33d position_prior;
1243 int width = 0, height = 0;
1244 std::string name;
1245};
1246
1249 std::vector<ProjectedTile> tiles;
1250 std::unique_ptr<ImageFeatures> features;
1251};
1252
1253/** @brief Stage projected colour and weights without modifying durable tiles.
1254 * @param[in,out] prepared Decoded photo and destination for its contributions.
1255 * @param resources Resource and cancellation policy.
1256 * @details Reject tiles outside the actual quadrilateral before allocating
1257 * buffers. Separate projection from commit so photos can be prepared in parallel. */
1259 const Photo& photo = prepared.photo;
1260 static thread_local std::vector<cv::Point2f> intersection;
1261 for (int tile_row = photo.bounds.top; tile_row <= photo.bounds.bottom; ++tile_row) {
1262 for (int tile_column = photo.bounds.left; tile_column <= photo.bounds.right;
1263 ++tile_column) {
1264 resources.tile_checkpoint();
1265 const cv::Matx33d local =
1266 cv::Matx33d(1, 0, -tile_column * tile_size, 0, 1,
1267 -tile_row * tile_size, 0, 0, 1) * photo.to_world;
1268 const auto footprint = photo.corners(local);
1269 const std::array<cv::Point2f, 4> rectangle{{{0, 0}, {tile_size - 1, 0},
1270 {tile_size - 1, tile_size - 1}, {0, tile_size - 1}}};
1271 intersection.clear();
1272 if (cv::intersectConvexConvex(footprint, rectangle, intersection) <= 0)
1273 continue;
1274 ProjectedTile tile;
1275 tile.column = tile_column;
1276 tile.row = tile_row;
1277 tile.colors.create(tile_size, tile_size, CV_8UC3);
1278 tile.weights = cv::Mat(tile_size, tile_size, CV_32FC1, cv::Scalar::all(0));
1279 bool contributed = false;
1280 for (int start_row = 0; start_row < tile_size; start_row += 16) {
1281 resources.tile_checkpoint();
1282 const cv::Matx33d transform =
1283 cv::Matx33d(1, 0, -tile_column * tile_size, 0, 1,
1284 -tile_row * tile_size - start_row, 0, 0, 1) * photo.to_world;
1285 const cv::Matx33d inverse = transform.inv();
1286 cv::Mat colors = tile.colors.rowRange(start_row, start_row + 16);
1287 cv::warpPerspective(photo.image, colors, transform, cv::Size(tile_size, 16),
1288 cv::INTER_LINEAR, cv::BORDER_CONSTANT);
1289 for (int row = 0; row < 16; ++row) {
1290 auto* weights = tile.weights.ptr<float>(start_row + row);
1291 for (int column = 0; column < tile_size; ++column) {
1292 const cv::Vec3d source = inverse * cv::Vec3d(column, row, 1);
1293 if (source[2] <= 0) continue;
1294 const double source_x = source[0] / source[2];
1295 const double source_y = source[1] / source[2];
1296 const double edge = std::min({source_x, source_y,
1297 photo.image.cols - 1 - source_x, photo.image.rows - 1 - source_y});
1298 if (edge < 1) continue;
1299 weights[column] = std::min(1.0,
1300 edge / (0.125 * std::min(photo.image.cols, photo.image.rows)));
1301 contributed = true;
1302 }
1303 }
1304 }
1305 if (contributed) prepared.tiles.push_back(std::move(tile));
1306 }
1307 }
1308}
1309
1310/** @brief Commit a prepared photo's contributions to independent tile files.
1311 * @param prepared Precomputed colour and weight data for this photo.
1312 * @param root Output map directory.
1313 * @param sequence Pending photo sequence.
1314 * @param resources Desktop execution policy.
1315 * @details Skip tiles already at this sequence to resume a partially
1316 * committed photo without double-counting its weights. */
1317void blend_prepared(const PreparedPhoto& prepared, const fs::path& root,
1318 uint64_t sequence, Resources& resources) {
1319 resources.parallel_tiles(prepared.tiles.size(), [&](size_t index) {
1320 resources.tile_checkpoint();
1321 disk_headroom(root, 2 * mib);
1322 const ProjectedTile& projected = prepared.tiles[index];
1323 const fs::path path = tile_path(root, projected.column, projected.row);
1324 Tile tile;
1325 tile.load(path);
1326 check(tile.sequence <= sequence, "tile newer than pending photo");
1327 if (tile.sequence == sequence) return;
1328 for (int row = 0; row < tile_size; ++row) {
1329 if (row % 16 == 0) resources.tile_checkpoint();
1330 auto* sums = tile.sums.ptr<cv::Vec4f>(row);
1331 const auto* colors = projected.colors.ptr<cv::Vec3b>(row);
1332 const auto* weights = projected.weights.ptr<float>(row);
1333 for (int column = 0; column < tile_size; ++column) {
1334 if (weights[column] <= 0) continue;
1335 for (int channel = 0; channel < 3; ++channel)
1336 sums[column][channel] += colors[column][channel] * weights[column];
1337 sums[column][3] += weights[column];
1338 }
1339 }
1340 tile.sequence = sequence;
1341 tile.save(path);
1342 });
1343}
1344
1345struct Encoder {
1346 jpeg_compress_struct state{};
1348 bool created = false;
1349 cv::Mat stripe, covered;
1350 /** @brief Release initialized compressor state on success or recovery. */
1352 if (created) jpeg_destroy_compress(&state);
1353 }
1354};
1355
1356/** Stream the committed tile bounds into a snapshot JPEG, mask, world file, and
1357 * VRT.
1358 * @param root Map output directory.
1359 * @param state Durable sequence/bounds checkpoint.
1360 * @param resources Cooperative resource policy.
1361 * @param max_map_side Explicit pixel-side ceiling for this invocation. */
1362void export_map(const fs::path& root, const Json& state, Resources& resources,
1363 int max_map_side) {
1364 const Bounds bounds = Bounds::from(state.at("bounds"), max_map_side);
1365 if (bounds.empty()) return;
1366 const int width = (bounds.right - bounds.left + 1) * tile_size;
1367 const int height = (bounds.bottom - bounds.top + 1) * tile_size;
1368 disk_headroom(root, uint64_t(width) * height * 4 + 8 * mib);
1369 const std::string name =
1370 "snapshot-" + std::to_string(state.at("sequence").get<uint64_t>());
1371 const fs::path destination = root / name;
1372 if (fs::is_symlink(root / "latest") &&
1373 fs::read_symlink(root / "latest") == name) {
1374 const Json published = read_json(destination / "map.json");
1375 check(published.at("sequence") == state.at("sequence") &&
1376 published.at("bounds") == state.at("bounds"),
1377 "published snapshot disagrees with checkpoint");
1378 return;
1379 }
1380 fs::create_directory(destination);
1381 AtomicFile output(destination / "map.jpg"),
1382 mask(destination / "map-mask.pgm");
1383 mask.text("P5\n" + std::to_string(width) + " " + std::to_string(height) +
1384 "\n255\n");
1385 auto encoder = std::make_unique<Encoder>();
1386 encoder->state.err = jpeg_std_error(&encoder->error.manager);
1387 encoder->error.manager.error_exit = jpeg_failure;
1388 if (setjmp(encoder->error.recovery))
1389 throw std::runtime_error("map JPEG encoding failed");
1390 jpeg_create_compress(&encoder->state);
1391 encoder->created = true;
1392 jpeg_stdio_dest(&encoder->state, output.file.get());
1393 encoder->state.image_width = width;
1394 encoder->state.image_height = height;
1395 encoder->state.input_components = 3;
1396 encoder->state.in_color_space = JCS_RGB;
1397 jpeg_set_defaults(&encoder->state);
1398 jpeg_set_quality(&encoder->state, 95, TRUE);
1399 jpeg_start_compress(&encoder->state, TRUE);
1400 const int stripe_rows = width > 8192 && !resources.desktop() ? 16 : tile_size;
1401 for (int stripe_top = bounds.top * tile_size;
1402 stripe_top < (bounds.bottom + 1) * tile_size; stripe_top += stripe_rows) {
1403 const int tile_row = stripe_top / tile_size;
1404 const int start_row = stripe_top % tile_size;
1405 resources.checkpoint();
1406 encoder->stripe = cv::Mat(stripe_rows, width, CV_8UC3, cv::Scalar::all(0));
1407 encoder->covered = cv::Mat(stripe_rows, width, CV_8UC1, cv::Scalar::all(0));
1408 const auto fill_tile = [&](int tile_column) {
1409 resources.tile_checkpoint();
1410 Tile tile;
1411 tile.load(tile_path(root, tile_column, tile_row));
1412 for (int row = 0; row < stripe_rows; ++row) {
1413 if (resources.desktop() && row % 16 == 0) resources.tile_checkpoint();
1414 auto* colors = encoder->stripe.ptr<cv::Vec3b>(row) +
1415 (tile_column - bounds.left) * tile_size;
1416 auto* valid = encoder->covered.ptr<uint8_t>(row) +
1417 (tile_column - bounds.left) * tile_size;
1418 const auto* sums = tile.sums.ptr<cv::Vec4f>(start_row + row);
1419 for (int column = 0; column < tile_size; ++column)
1420 if (sums[column][3] > 0) {
1421 for (int channel = 0; channel < 3; ++channel)
1422 colors[column][channel] = cv::saturate_cast<uint8_t>(
1423 sums[column][channel] / sums[column][3]);
1424 valid[column] = 255;
1425 }
1426 }
1427 };
1428 if (resources.desktop()) {
1429 resources.parallel_tiles(bounds.right - bounds.left + 1,
1430 [&](size_t index) {
1431 fill_tile(bounds.left + static_cast<int>(index));
1432 });
1433 } else {
1434 for (int tile_column = bounds.left; tile_column <= bounds.right;
1435 ++tile_column)
1436 fill_tile(tile_column);
1437 }
1438 for (int row = 0; row < stripe_rows; ++row) {
1439 if (row % 16 == 0) resources.checkpoint();
1440 JSAMPROW pixels = encoder->stripe.ptr(row);
1441 check(jpeg_write_scanlines(&encoder->state, &pixels, 1) == 1,
1442 "map scanline write failed");
1443 mask.write(encoder->covered.ptr(row), width);
1444 }
1445 }
1446 jpeg_finish_compress(&encoder->state);
1447 output.commit();
1448 mask.commit();
1449 const double origin_x =
1451 const double origin_y =
1453 std::ostringstream world;
1454 world << std::setprecision(17) << projected_pixel_m << "\n0\n0\n"
1455 << -projected_pixel_m << '\n'
1456 << origin_x << '\n'
1457 << origin_y << '\n';
1458 AtomicFile world_file(destination / "map.jgw");
1459 world_file.text(world.str());
1460 world_file.commit();
1461 std::ostringstream vrt;
1462 vrt << std::setprecision(17) << "<VRTDataset rasterXSize=\"" << width
1463 << "\" rasterYSize=\"" << height
1464 << "\"><SRS>EPSG:3857</SRS><GeoTransform>"
1465 << origin_x - projected_pixel_m / 2 << ',' << projected_pixel_m << ",0,"
1466 << origin_y + projected_pixel_m / 2 << ",0," << -projected_pixel_m
1467 << "</GeoTransform>";
1468 for (int band = 1; band <= 4; ++band) {
1469 vrt << "<VRTRasterBand dataType=\"Byte\" band=\"" << band
1470 << "\"><ColorInterp>"
1471 << std::array<const char*, 4>{"Red", "Green", "Blue", "Alpha"}[band - 1]
1472 << "</ColorInterp><SimpleSource><SourceFilename relativeToVRT=\"1\">"
1473 << (band == 4 ? "map-mask.pgm" : "map.jpg")
1474 << "</SourceFilename><SourceBand>" << (band == 4 ? 1 : band)
1475 << "</SourceBand></SimpleSource></VRTRasterBand>";
1476 }
1477 vrt << "</VRTDataset>\n";
1478 AtomicFile vrt_file(destination / "map.vrt");
1479 vrt_file.text(vrt.str());
1480 vrt_file.commit();
1481 Json metadata = state;
1482 metadata.set("resources", resources.report());
1483 metadata.set("crs", "EPSG:3857");
1484 metadata.set("projected_pixel_m", projected_pixel_m);
1485 metadata.set("width", width);
1486 metadata.set("height", height);
1487 metadata.set("model", "pose_pinhole_flat_ground_feather_v1");
1488 metadata.set("source_mode",
1489 state.value("standard_profile", false) ? "assumed_camera" :
1490 state.value("camera", Json()).is_null() ? "mimic" : "real_camera");
1491 metadata.set("limitations",
1492 "Flat-ground pinhole projection of input JPEGs; no terrain/3D "
1493 "reconstruction, lens correction, added effects or accuracy "
1494 "certification");
1495 if (state.value("align_images", false)) {
1496 metadata.set("model", "neighbor_similarity_registered_visual_map_v1");
1497 metadata.set("limitations",
1498 "Visual neighbor registration with pose-selected candidates and pose "
1499 "fallbacks; first-anchor scale/position and accumulated drift are not "
1500 "surveyed accuracy. Source overlays, parallax and renderer artifacts "
1501 "remain; no GPS correction or terrain reconstruction.");
1502 }
1503 write_json(destination / "map.json", metadata);
1504 const fs::path temporary = root / ".latest-next";
1505 unlink(temporary.c_str());
1506 check(symlink(name.c_str(), temporary.c_str()) == 0 &&
1507 rename(temporary.c_str(), (root / "latest").c_str()) == 0,
1508 "cannot publish completed map snapshot");
1509 sync_directory(root);
1510 for (const auto& entry : fs::directory_iterator(root)) {
1511 if (!entry.is_directory() || entry.is_symlink() ||
1512 entry.path().filename().string().rfind("snapshot-", 0) != 0 ||
1513 entry.path().filename() == name)
1514 continue;
1515 for (const char* file :
1516 {"map.jpg", "map-mask.pgm", "map.jgw", "map.vrt", "map.json"})
1517 fs::remove(entry.path() / file);
1518 std::error_code error;
1519 fs::remove(entry.path(), error);
1520 }
1521 std::cout << "PANGEA: map published " << (root / "latest/map.jpg") << '\n';
1522}
1523
1524/** Coordinate discovery, validation, resumable blending, and snapshot
1525 * publication. */
1526class Worker {
1527 fs::path input, root;
1531 bool allow_prompt = false;
1532 bool profile_asked = false;
1533 int max_map_side = 8192;
1534 bool align_images = false;
1536 std::vector<AlignmentReference> references;
1537
1538 /** @brief Extract bounded SIFT features for a possible alignment reference.
1539 * @param photo Source image and initial world transform.
1540 * @param name Source name for the alignment record.
1541 * @return Descriptors and keypoints expressed in original image pixels.
1542 * @details Detect on reduced, border-masked imagery to limit feature work;
1543 * restore original coordinates before fitting geometry. */
1544 AlignmentReference features(const Photo& photo, const std::string& name) {
1545 struct Workspace {
1546 cv::Mat resized, gray, mask;
1547 cv::Ptr<cv::SIFT> detector = cv::SIFT::create(4000);
1548 };
1549 static thread_local Workspace workspace;
1550 const double scale = std::min(1.0, 1024.0 / std::max(photo.image.cols, photo.image.rows));
1551 cv::resize(photo.image, workspace.resized, cv::Size(), scale, scale, cv::INTER_AREA);
1552 cv::cvtColor(workspace.resized, workspace.gray, cv::COLOR_RGB2GRAY);
1553 workspace.mask.create(workspace.gray.size(), CV_8UC1);
1554 workspace.mask.setTo(0);
1555 const int margin = std::max(1, int(40 * scale));
1556 workspace.mask(cv::Rect(margin, 2 * margin, workspace.gray.cols - 2 * margin,
1557 workspace.gray.rows - 3 * margin)).setTo(255);
1558 AlignmentReference current;
1559 current.width = photo.image.cols;
1560 current.height = photo.image.rows;
1561 current.name = name;
1562 current.to_world = photo.to_world;
1563 current.position_prior = photo.to_world;
1564 workspace.detector->detectAndCompute(workspace.gray, workspace.mask,
1565 current.keypoints, current.descriptors);
1566 for (auto& point : current.keypoints) point.pt *= float(1 / scale);
1567 return current;
1568 }
1569
1570 /** @brief Try to refine a photo's georeferenced transform using recent photos.
1571 * @param[in,out] photo Source whose transform may be updated.
1572 * @param name Source name for evidence and reference tracking.
1573 * @param[in,out] cached Optional precomputed features, moved from when used.
1574 * @return Alignment decision and available supporting evidence.
1575 * @details Use position priors to screen candidate references; keep the
1576 * original projection if no feature match passes the geometric checks. */
1577 Json align(Photo& photo, const std::string& name, ImageFeatures* cached = nullptr) {
1578 Json result = Json::object({{"status", "gps_fallback"}});
1579 const int margin = 40;
1580 if (photo.image.cols <= 2 * margin || photo.image.rows <= 3 * margin)
1581 return Json::object({{"status", "image_too_small"}});
1582 AlignmentReference current = cached ? std::move(*cached) : features(photo, name);
1583 size_t best_inliers = 0;
1584 cv::Matx33d selected = photo.to_world;
1585 const cv::Vec3d center_pixel((photo.image.cols - 1) / 2.0,
1586 (photo.image.rows - 1) / 2.0, 1);
1587 const cv::Vec3d predicted_center = photo.to_world * center_pixel;
1588 struct Candidate {
1589 size_t inliers = 0;
1590 cv::Matx33d to_world;
1591 Json evidence;
1592 };
1593 std::vector<Candidate> candidates(references.size());
1594 resources.parallel_tiles(references.size(), [&](size_t candidate_index) {
1595 const auto* reference = &references[references.size() - 1 - candidate_index];
1596 if (current.descriptors.empty() || reference->descriptors.empty()) return;
1597 const cv::Vec3d relative = reference->position_prior.inv() * predicted_center;
1598 if (relative[2] <= 0 || relative[0] / relative[2] < -reference->width * 0.25 ||
1599 relative[0] / relative[2] > reference->width * 1.25 ||
1600 relative[1] / relative[2] < -reference->height * 0.25 ||
1601 relative[1] / relative[2] > reference->height * 1.25) return;
1602 resources.tile_checkpoint();
1603 struct Workspace {
1604 cv::BFMatcher matcher{cv::NORM_L2};
1605 std::vector<std::vector<cv::DMatch>> matches;
1606 std::vector<cv::Point2f> source, target, supported;
1607 std::vector<double> errors;
1608 cv::Mat inliers;
1609 };
1610 static thread_local Workspace workspace;
1611 auto& matches = workspace.matches;
1612 auto& source = workspace.source;
1613 auto& target = workspace.target;
1614 auto& supported = workspace.supported;
1615 auto& errors = workspace.errors;
1616 matches.clear(); source.clear(); target.clear();
1617 supported.clear(); errors.clear();
1618 workspace.matcher.knnMatch(current.descriptors, reference->descriptors, matches, 2);
1619 for (const auto& pair : matches) {
1620 if (pair.size() != 2 || pair[0].distance >= 0.7f * pair[1].distance) continue;
1621 source.push_back(current.keypoints[pair[0].queryIdx].pt);
1622 target.push_back(reference->keypoints[pair[0].trainIdx].pt);
1623 }
1624 if (source.size() < 30) return;
1625 cv::Mat& inliers = workspace.inliers;
1626 const cv::Mat affine = cv::estimateAffinePartial2D(
1627 source, target, inliers, cv::RANSAC, 3, 2000, 0.995, 10);
1628 const int count = cv::countNonZero(inliers);
1629 if (affine.empty() || count < 30 || count < source.size() * 0.25 ||
1630 count <= 0) return;
1631 const double scale = std::hypot(affine.at<double>(0, 0), affine.at<double>(1, 0));
1632 const double angle = std::atan2(affine.at<double>(1, 0),
1633 affine.at<double>(0, 0)) * 180 / pi;
1634 if (!std::isfinite(scale) || scale < 0.9 || scale > 1.1 || std::abs(angle) > 5) return;
1635 const cv::Matx33d transform(
1636 affine.at<double>(0, 0), affine.at<double>(0, 1), affine.at<double>(0, 2),
1637 affine.at<double>(1, 0), affine.at<double>(1, 1), affine.at<double>(1, 2),
1638 0, 0, 1);
1639 for (size_t index = 0; index < source.size(); ++index) {
1640 if (!inliers.at<uint8_t>(static_cast<int>(index))) continue;
1641 const cv::Vec3d point = transform * cv::Vec3d(source[index].x, source[index].y, 1);
1642 supported.push_back(source[index]);
1643 errors.push_back(std::hypot(point[0] - target[index].x, point[1] - target[index].y));
1644 }
1645 const cv::Rect support = cv::boundingRect(supported);
1646 if (support.width < photo.image.cols * 0.15 ||
1647 support.height < photo.image.rows * 0.15) return;
1648 std::sort(errors.begin(), errors.end());
1649 if (errors[errors.size() / 2] > 2) return;
1650 const cv::Matx33d candidate = reference->to_world * transform;
1651 const cv::Vec3d candidate_center = candidate * center_pixel;
1652 const double correction = std::hypot(candidate_center[0] - predicted_center[0],
1653 candidate_center[1] - predicted_center[1]);
1654 const cv::Vec3d matched_center = transform * center_pixel;
1655 const double local_distance = std::hypot(
1656 matched_center[0] - (reference->width - 1) / 2.0,
1657 matched_center[1] - (reference->height - 1) / 2.0);
1658 if (!std::isfinite(correction) ||
1659 local_distance > std::hypot(reference->width, reference->height) * 1.25)
1660 return;
1661 Candidate& match = candidates[candidate_index];
1662 match.inliers = count;
1663 match.to_world = candidate;
1664 match.evidence = Json::object({{"status", "registered"}, {"reference", reference->name},
1665 {"inliers", count}, {"median_error_px", errors[errors.size() / 2]},
1666 {"center_correction_map_px", correction}, {"relative_scale", scale}});
1667 });
1668 for (const auto& candidate : candidates) {
1669 if (candidate.inliers <= best_inliers) continue;
1670 best_inliers = candidate.inliers;
1671 selected = candidate.to_world;
1672 result = candidate.evidence;
1673 }
1674 photo.to_world = selected;
1675 photo.update_bounds(photo.image.cols, photo.image.rows);
1676 current.to_world = photo.to_world;
1677 if (references.size() == 8) references.erase(references.begin());
1678 references.push_back(std::move(current));
1679 return result;
1680 }
1681
1682 /** @brief Publish the current resume checkpoint through the atomic JSON writer. */
1683 void save() { write_json(root / "state.json", state); }
1684
1685 /** @brief Recheck source identity before modifying map state.
1686 * @param source Current source path.
1687 * @param job Discovery record containing the expected identity.
1688 * @return True on a match; false when a changing input can be deferred.
1689 * @details Reject an identity change while resuming a pending photo: some
1690 * tiles may already incorporate the original input. */
1691 bool unchanged(const fs::path& source, const Json& job) {
1692 if (identity(source, true) == job.at("identity")) return true;
1693 check(state.at("pending").is_null(),
1694 "pending source changed; retain original photos to resume this map");
1695 std::cout << "PANGEA: deferred changing photo " << source.filename()
1696 << '\n';
1697 return false;
1698 }
1699
1700 /** Validate one discovered source and checkpoint its blend as an idempotent
1701 * job. */
1702 void process(const Json& job, PreparedPhoto* prepared = nullptr,
1703 std::exception_ptr prepared_error = nullptr) {
1704 const fs::path source = input / job.at("name").get<std::string>();
1705 check(source.parent_path() == input, "invalid source path");
1706 if (!unchanged(source, job)) return;
1707 Photo photo;
1708 try {
1709 try {
1710 if (prepared) photo = std::move(prepared->photo);
1711 else if (prepared_error) std::rethrow_exception(prepared_error);
1712 else photo = read_photo(source, resources, state.value("camera", Json()),
1713 state.value("standard_profile", false));
1714 } catch (const InvalidPhoto& error) {
1715 if (!allow_prompt || profile_asked ||
1716 std::string(error.what()) !=
1717 "missing MIMIC geometry; real JPEGs require --camera-profile")
1718 throw;
1719 profile_asked = true;
1720 std::cerr << "PANGEA: " << error.what() << '\n'
1721 << "Standard profile assumes 60-degree horizontal FOV, "
1722 "centered square pixels and nadir mounting; FlyEye "
1723 "images assume north-up, zero roll/pitch. "
1724 "Map geometry is approximate, not calibrated.\n"
1725 << "use standard profile Y/n: " << std::flush;
1726 std::string answer;
1727 if (!std::getline(std::cin, answer) ||
1728 !(answer.empty() || answer == "Y" || answer == "y"))
1729 throw;
1730 state.set("standard_profile", true);
1731 state.set("assumed_geometry", Json::object({
1732 {"horizontal_fov_deg", 60}, {"mount", "nadir"},
1733 {"flyeye_roll_deg", 0}, {"flyeye_pitch_deg", 0},
1734 {"flyeye_yaw_deg", 0}, {"accuracy", "uncalibrated"}}));
1735 save();
1736 photo = read_photo(source, resources, Json(), true);
1737 }
1738 } catch (const std::exception& error) {
1739 if (!unchanged(source, job)) return;
1740 if (dynamic_cast<const InvalidPhoto*>(&error) == nullptr) throw;
1741 check(state.at("pending").is_null(),
1742 "pending photo no longer decodes; checkpoint retained");
1743 write_json(
1744 root / "done" / (job.at("identity").get<std::string>() + ".json"),
1745 Json::object({{"status", "rejected"}, {"source", job}, {"reason", error.what()}}));
1746 state.set("rejected", state.at("rejected").get<unsigned>() + 1);
1747 save();
1748 std::cerr << "PANGEA: skipped " << source.filename() << ": "
1749 << error.what() << '\n';
1750 return;
1751 }
1752 if (!unchanged(source, job)) return;
1753 Json alignment;
1754 if (align_images) {
1755 if (!state.at("pending").is_null() &&
1756 state.at("pending").contains("registered_to_world")) {
1757 const Json saved = state.at("pending").at("registered_to_world");
1758 const cv::Matx33d position_prior = photo.to_world;
1759 check(saved.is_array() && saved.size() == 9, "invalid saved alignment");
1760 for (int index = 0; index < 9; ++index) {
1761 photo.to_world.val[index] = saved[index].get<double>();
1762 check(std::isfinite(photo.to_world.val[index]), "nonfinite saved alignment");
1763 }
1764 photo.update_bounds(photo.image.cols, photo.image.rows);
1765 alignment = state.at("pending").at("alignment");
1766 if (photo.image.cols > 80 && photo.image.rows > 120) {
1767 if (references.size() == 8) references.erase(references.begin());
1768 auto reference = features(photo, job.at("name").get<std::string>());
1769 reference.position_prior = position_prior;
1770 references.push_back(std::move(reference));
1771 }
1772 } else alignment = align(photo, job.at("name").get<std::string>(),
1773 prepared ? prepared->features.get() : nullptr);
1774 if (prepared) {
1775 prepared->photo = photo;
1776 prepared->tiles.clear();
1777 prepare_projection(*prepared, resources);
1778 }
1779 }
1781 try {
1782 combined = Bounds::from(state.at("bounds"), max_map_side)
1783 .include(photo.bounds, max_map_side);
1784 } catch (const std::exception&) {
1785 throw std::runtime_error(
1786 "map extent limit reached; resume with a larger --max-map-side "
1787 "for standalone stitching, or use a new output for another area");
1788 }
1789 const uint64_t sequence = state.at("sequence").get<uint64_t>() + 1;
1790 check(sequence <= max_photos, "10000-photo limit reached; start a new map");
1791 disk_headroom(root, 64 * mib);
1792 // Persist intent before touching tiles so a restart can replay partial tile
1793 // updates.
1794 if (state.at("pending").is_null()) {
1795 state.set("pending", job);
1796 if (align_images) {
1797 Json transform = Json::array();
1798 for (double value : photo.to_world.val) transform.push_back(value);
1799 Json pending = state.at("pending");
1800 pending.set("registered_to_world", transform);
1801 pending.set("alignment", alignment);
1802 state.set("pending", pending);
1803 }
1804 save();
1805 }
1806 if (prepared) blend_prepared(*prepared, root, sequence, resources);
1807 else blend(photo, root, sequence, resources);
1808 Json completed = Json::object({{"status", "assembled"},
1809 {"source", job},
1810 {"sequence", sequence},
1811 {"corners_lon_lat", photo.geographic_corners()}});
1812 if (align_images) completed.set("alignment", alignment);
1813 write_json(root / "done" / (job.at("identity").get<std::string>() + ".json"), completed);
1814 state.set("bounds", combined.json());
1815 state.set("sequence", sequence);
1816 state.set("pending", nullptr);
1817 if (align_images) {
1818 Json saved = Json::array();
1819 for (const auto& reference : references) {
1820 Json transform = Json::array();
1821 for (double value : reference.to_world.val) transform.push_back(value);
1822 saved.push_back(Json::object({{"name", reference.name},
1823 {"identity", identity(input / reference.name)}, {"to_world", transform}}));
1824 }
1825 state.set("alignment_references", saved);
1826 }
1827 save();
1828 std::cout << "PANGEA: assembled " << source.filename() << " (#" << sequence
1829 << ")\n";
1830 }
1831
1832 public:
1833 /** Acquire per-user/output locks and load or initialize the resumable state
1834 * file. */
1835 Worker(fs::path source, fs::path output, Resources& budget, uint64_t since,
1836 const Json& camera, bool interactive, int side_limit, bool image_alignment)
1837 : resources(budget), allow_prompt(interactive), max_map_side(side_limit),
1838 align_images(image_alignment) {
1839 input = fs::canonical(source);
1840 check(fs::is_directory(input), "input must be a photo directory");
1841 fs::create_directories(output);
1842 root = fs::canonical(output);
1843 check(root != input, "output must differ from input");
1844 // Serialize this user's workers before taking the output-specific
1845 // checkpoint lock.
1846 const std::string lock_path =
1847 "/tmp/usher-pangea-" + std::to_string(getuid()) + ".lock";
1848 process_lock.reset(open(lock_path.c_str(),
1849 O_CREAT | O_RDWR | O_NOFOLLOW | O_CLOEXEC, 0600));
1850 check(process_lock.get() >= 0 && flock(process_lock.get(), LOCK_EX | LOCK_NB) == 0,
1851 "another PANGEA worker is active for this user");
1852 output_lock.reset(open((root / ".lock").c_str(),
1853 O_CREAT | O_RDWR | O_NOFOLLOW | O_CLOEXEC, 0600));
1854 check(output_lock.get() >= 0 && flock(output_lock.get(), LOCK_EX | LOCK_NB) == 0,
1855 "output already has a PANGEA worker");
1856 if (fs::exists(root / "state.json")) {
1857 state = read_json(root / "state.json");
1858 check(state.value("schema", "") == "PANGEA_STATE_V1" &&
1859 state.at("input") == input.string(),
1860 "checkpoint belongs to another input or format");
1861 check(state.value("camera", Json()) == camera,
1862 "camera profile differs from checkpoint; use original profile or a "
1863 "new output");
1864 Bounds::from(state.at("bounds"), max_map_side);
1865 check(state.value("align_images", false) == align_images,
1866 "alignment mode differs from checkpoint; use a new output directory");
1867 check(state.at("sequence").get<uint64_t>() <= max_photos &&
1868 state.at("rejected").get<unsigned>() <= max_photos,
1869 "invalid checkpoint counts");
1870 } else {
1871 for (const auto& entry : fs::directory_iterator(root))
1872 check(entry.path().filename() == ".lock",
1873 "output must be empty or a PANGEA checkpoint");
1874 state = Json::object({{"schema", "PANGEA_STATE_V1"},
1875 {"input", input.string()},
1876 {"since", since},
1877 {"camera", camera},
1878 {"sequence", 0},
1879 {"rejected", 0},
1880 {"exported", 0},
1881 {"bounds", Bounds{}.json()},
1882 {"pending", nullptr}});
1883 if (align_images) state.set("align_images", true);
1884 save();
1885 }
1886 fs::create_directory(root / "tiles");
1887 fs::create_directory(root / "done");
1888 if (align_images && state.contains("alignment_references")) {
1889 const Json saved = state.at("alignment_references");
1890 check(saved.is_array() && saved.size() <= 8, "invalid alignment references");
1891 for (size_t saved_index = 0; saved_index < saved.size(); ++saved_index) {
1892 const Json record = saved[saved_index];
1893 const std::string name = record.at("name").get<std::string>();
1894 const fs::path source = input / name;
1895 check(source.parent_path() == input &&
1896 identity(source) == record.at("identity"),
1897 "alignment reference changed; retain original photos");
1898 Photo photo = read_photo(source, resources, camera,
1899 state.value("standard_profile", false));
1900 const cv::Matx33d position_prior = photo.to_world;
1901 const Json transform = record.at("to_world");
1902 check(transform.is_array() && transform.size() == 9, "invalid reference transform");
1903 for (int index = 0; index < 9; ++index) {
1904 photo.to_world.val[index] = transform[index].get<double>();
1905 check(std::isfinite(photo.to_world.val[index]), "nonfinite reference transform");
1906 }
1907 photo.update_bounds(photo.image.cols, photo.image.rows);
1908 auto reference = features(photo, name);
1909 reference.position_prior = position_prior;
1910 references.push_back(std::move(reference));
1911 }
1912 }
1913 }
1914 /** Process stable jobs; in watch mode, defer changing files and export
1915 * periodically. */
1916 void run(bool watch) {
1917 double exported_at = seconds(CLOCK_MONOTONIC);
1918 const auto export_due = [&](bool force) {
1919 if (state.at("exported") != state.at("sequence") &&
1920 (force || (watch && seconds(CLOCK_MONOTONIC) - exported_at >= 10))) {
1922 state.set("exported", state.at("sequence"));
1923 save();
1924 exported_at = seconds(CLOCK_MONOTONIC);
1925 }
1926 };
1927 std::map<std::string, std::pair<std::string, double>> observed;
1928 while (!stopping) {
1929 resources.checkpoint();
1930 if (!state.at("pending").is_null()) {
1931 process(state.at("pending"));
1932 export_due(false);
1933 continue;
1934 }
1935 Directory directory(opendir(input.c_str()));
1936 check(bool(directory), "input directory unavailable");
1937 std::vector<Json> jobs;
1938 jobs.reserve(64);
1939 std::map<std::string, std::pair<std::string, double>> next_observed;
1940 size_t entries = 0;
1941 while (dirent* entry = readdir(directory.get())) {
1942 // Check cancellation/headroom during very large directory scans without
1943 // a syscall per entry.
1944 if (++entries % 64 == 0) resources.checkpoint();
1945 check(entries <= 100000, "input directory entry limit reached");
1946 const std::string name = entry->d_name;
1947 if (fs::path(name).extension() != ".jpg" ||
1948 name.find(".lens.") != std::string::npos)
1949 continue;
1950 if (!state.value("camera", Json()).is_null() &&
1951 name.rfind(
1952 state.at("camera").at("filename_prefix").get<std::string>(),
1953 0) != 0)
1954 continue;
1955 struct stat status{};
1956 if (lstat((input / name).c_str(), &status) != 0 ||
1957 !S_ISREG(status.st_mode) ||
1958 status.st_mtim.tv_sec <
1959 static_cast<time_t>(state.at("since").get<uint64_t>()))
1960 continue;
1961 const std::string key = identity(input / name, true);
1962 if (key.empty()) continue;
1963 if (fs::exists(root / "done" / (key + ".json"))) continue;
1964 if (watch) {
1965 const auto previous = observed.find(name);
1966 const double now = seconds(CLOCK_MONOTONIC);
1967 const double stable_since =
1968 previous != observed.end() && previous->second.first == key
1969 ? previous->second.second
1970 : now;
1971 next_observed.emplace(name, std::make_pair(key, stable_since));
1972 // Require two stable seconds so a producer cannot expose a
1973 // half-written JPEG.
1974 if (now - stable_since < 2) {
1975 if (next_observed.size() == 64) break;
1976 continue;
1977 }
1978 }
1979 jobs.push_back(Json::object({{"name", name}, {"identity", key}}));
1980 if (jobs.size() == 64 || next_observed.size() == 64) break;
1981 }
1982 observed = std::move(next_observed);
1983 if (!jobs.empty()) {
1984 std::sort(jobs.begin(), jobs.end(),
1985 [](const Json& first, const Json& second) {
1986 return first.at("name") < second.at("name");
1987 });
1988 if (!resources.desktop()) {
1989 for (const Json& job : jobs) {
1990 check(state.at("sequence").get<unsigned>() +
1991 state.at("rejected").get<unsigned>() < max_photos,
1992 "photo record limit reached; start a new output");
1993 process(job);
1994 export_due(false);
1995 }
1996 } else {
1997 for (size_t batch_start = 0; batch_start < jobs.size();) {
1998 const size_t batch_size =
1999 std::min(resources.photo_batch_capacity(align_images ? 256 : 128),
2000 jobs.size() - batch_start);
2001 bool standard_profile = state.value("standard_profile", false);
2002 std::vector<std::unique_ptr<PreparedPhoto>> prepared(batch_size);
2003 std::vector<std::exception_ptr> errors(batch_size);
2004 const Json camera = state.value("camera", Json());
2005 const auto prepare_one = [&](size_t index) {
2006 prepared[index].reset();
2007 errors[index] = nullptr;
2008 try {
2009 auto decoded = std::make_unique<PreparedPhoto>();
2010 decoded->photo = read_photo(
2011 input / jobs[batch_start + index].at("name").get<std::string>(),
2012 resources, camera, standard_profile, true);
2013 if (!align_images) prepare_projection(*decoded, resources);
2014 else if (decoded->photo.image.cols > 80 && decoded->photo.image.rows > 120)
2015 decoded->features = std::make_unique<ImageFeatures>(features(
2016 decoded->photo, jobs[batch_start + index].at("name").get<std::string>()));
2017 prepared[index] = std::move(decoded);
2018 } catch (...) {
2019 errors[index] = std::current_exception();
2020 }
2021 };
2022 resources.parallel_tiles(batch_size, prepare_one);
2023 for (size_t index = 0; index < batch_size; ++index) {
2024 const Json& job = jobs[batch_start + index];
2025 check(state.at("sequence").get<unsigned>() +
2026 state.at("rejected").get<unsigned>() <
2027 max_photos,
2028 "photo record limit reached; start a new output");
2029 if (standard_profile != state.value("standard_profile", false)) {
2030 standard_profile = state.value("standard_profile", false);
2031 resources.parallel_tiles(batch_size - index, [&](size_t remaining) {
2032 prepare_one(index + remaining);
2033 });
2034 }
2035 process(job, prepared[index].get(), errors[index]);
2036 }
2037 batch_start += batch_size;
2038 }
2039 }
2040 export_due(false);
2041 continue;
2042 }
2043 export_due(!watch);
2044 if (!watch) break;
2045 poll(nullptr, 0, 1000);
2046 }
2047 }
2048};
2049} // namespace pangea_detail
2050
2051using namespace pangea_detail;
2052
2053/** Parse worker options, install signal/resource policy, and run one map
2054 * session.
2055 * @param argc Argument count.
2056 * @param argv Input/output paths and optional watch, camera, and resource
2057 * settings.
2058 * @return Zero on successful completion, otherwise one with a diagnostic. */
2059int pangeaSurveyMain(int argc, char** argv);
2060
2061/** @brief Dispatch PANGEA survey commands or run incremental photo mapping.
2062 * @param argc Command-line argument count.
2063 * @param argv Command-line arguments, including the executable name.
2064 * @return Exit status for the selected operation.
2065 * @details Establish restrictive output permissions and the OpenCV backend
2066 * before dispatching work; the direct mapper installs cooperative stop handlers. */
2067int main(int argc, char** argv) {
2068 umask(0077);
2069 try {
2070 if (argc == 2 && (std::string(argv[1]) == "--version" || std::string(argv[1]) == "-v")) {
2071 std::cout << PANGEA_BUILD_VERSION << '\n';
2072 return 0;
2073 }
2074 const usher_cv_parallel::ScopedBackend opencv_parallel_backend;
2075 if (argc > 1) {
2076 const std::string command = argv[1];
2077 if (command == "--run" || command == "--check" || command == "--diagnostic" ||
2078 command == "--update-great" || command == "--follow-great" || command == "--finalize-great" ||
2079 command == "--stop" || command == "--self-test")
2080 return pangeaSurveyMain(argc, argv);
2081 }
2082 signal(SIGINT, stop);
2083 signal(SIGTERM, stop);
2084 umask(0077);
2085 std::cout.setf(std::ios::unitbuf);
2086 if (argc == 2 && std::string(argv[1]) == "--check-resources") {
2087 Resources resources(192, 20);
2088 std::cout << resources.report().dump() << '\n';
2089 return 0;
2090 }
2091 fs::path input, output, profile_path, pause_file;
2092 uint64_t reserve = 192, since = 0;
2093 int cpu_percent = 20, max_map_side = 8192;
2094 bool watch = false, desktop = false, cpu_option = false, align_images = false;
2095 for (int index = 1; index < argc; ++index) {
2096 const std::string option = argv[index];
2097 if (option == "--help" || option == "-h") {
2098 std::cout
2099 << "PANGEA: Photo-Assisted Neighboring Geographic Edge Assembly\n"
2100 "Usage: pangea --input PHOTOS --output MAP [--watch] "
2101 "[--reserve-mb 192] [--cpu-percent 20]\n"
2102 " Incremental GREAT XYZ: --update-great INI, --follow-great INI, --finalize-great INI.\n"
2103 " Add --camera-profile FILE for real USHER JPEGs; no "
2104 "synthetic images or effects.\n"
2105 " --pause-file FILE defers work while FILE exists; remove "
2106 "it to resume.\n"
2107 " --max-map-side N permits larger standalone maps; "
2108 "default 8192, multiples of 256 up to 65280.\n"
2109 " --desktop enables parallel, unthrottled replay on "
2110 "hosts with at least 2 GiB RAM; never for MORA.\n"
2111 " --align-images registers overlapping photos in desktop "
2112 "mode; requires a new output directory.\n"
2113 " pangea --check-resources\n"
2114 " pangea --check SURVEY.ini\n"
2115 " pangea --run SURVEY.ini [--mode simple|great]\n"
2116 " pangea --diagnostic SURVEY.ini [--mode MODE]\n"
2117 " pangea --stop\n"
2118#if SENSORAIA_BUILD_TESTING
2119 " pangea --self-test\n"
2120#endif
2121 " pangea --version\n"
2122 "Default: clean MIMIC input. Real mode requires explicit "
2123 "camera geometry. Standalone replay offers an approximate "
2124 "standard profile when MIMIC geometry is missing. "
2125 "No realtime deadline.\n";
2126 return 0;
2127 }
2128 if (option == "--watch") {
2129 watch = true;
2130 continue;
2131 }
2132 if (option == "--desktop") {
2133 desktop = true;
2134 continue;
2135 }
2136 if (option == "--align-images") {
2137 align_images = true;
2138 continue;
2139 }
2140 check(index + 1 < argc, "option needs a value");
2141 const std::string value = argv[++index];
2142 if (option == "--input")
2143 input = value;
2144 else if (option == "--output")
2145 output = value;
2146 else if (option == "--camera-profile")
2147 profile_path = value;
2148 else if (option == "--pause-file") {
2149 check(!value.empty(), "pause file must not be empty");
2150 pause_file = value;
2151 } else {
2152 check(!value.empty() &&
2153 value.find_first_not_of("0123456789") == std::string::npos,
2154 "numeric option must be unsigned");
2155 const uint64_t parsed = std::stoull(value);
2156 if (option == "--reserve-mb")
2157 reserve = parsed;
2158 else if (option == "--max-map-side") {
2159 check(parsed >= 8192 && parsed <= 65280 && parsed % tile_size == 0,
2160 "max-map-side must be a multiple of 256 in 8192..65280");
2161 max_map_side = static_cast<int>(parsed);
2162 }
2163 else if (option == "--cpu-percent") {
2164 check(parsed <= 20, "CPU duty exceeds limit");
2165 cpu_percent = parsed;
2166 cpu_option = true;
2167 } else if (option == "--since")
2168 since = parsed;
2169 else if (option == "--parent-pid") {
2170 check(parsed > 1 && parsed <= INT32_MAX, "invalid parent PID");
2171 parent_pid = parsed;
2172 } else
2173 throw std::runtime_error("unknown option");
2174 }
2175 }
2176 check(!input.empty() && !output.empty(),
2177 "--input PHOTOS and --output MAP are required");
2178 check(!desktop || (!watch && !parent_pid && !cpu_option),
2179 "--desktop is standalone replay only; incompatible with --watch, "
2180 "--parent-pid and --cpu-percent");
2181 check(!align_images || desktop, "--align-images requires --desktop");
2182 Resources resources(reserve, cpu_percent, pause_file, desktop);
2183 resources.checkpoint();
2184 const Json camera = camera_profile(profile_path);
2185 while (watch && !fs::exists(input)) {
2186 resources.checkpoint();
2187 poll(nullptr, 0, 1000);
2188 }
2189 Worker worker(input, output, resources, since, camera,
2190 !watch && !parent_pid && camera.is_null(), max_map_side, align_images);
2191 worker.run(watch);
2192 std::cout << resources.report().dump() << '\n';
2193 return 0;
2194 } catch (const std::exception& error) {
2195 std::cerr << "PANGEA: " << error.what() << '\n';
2196 return 1;
2197 }
2198}
bool usher_camera_profile_read(const char *filename, struct usher_camera_profile *profile)
Read a bounded PANGEA_CAMERA_V1 key=value calibration file.
Public C API for reading PANGEA camera calibration profiles.
static double latitude
static double longitude
size_t size
Definition chdk_pipe.c:143
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
int descriptor
Definition chdk_pipe.c:142
void(* close)(struct usbfs_handle *)
Definition chdkbridge.c:57
int(* open)(const struct usbfs_device *, struct usbfs_handle *)
Definition chdkbridge.c:56
size_t peak_workers()
Read the lifetime concurrency high-water mark.
Definition pangea.cpp:231
~DesktopPool()
Wake and join the workers before destroying shared batch state.
Definition pangea.cpp:218
DesktopPool(size_t count)
Start the desktop worker pool.
Definition pangea.cpp:193
std::condition_variable ready
Definition pangea.cpp:153
std::exception_ptr failure
Definition pangea.cpp:158
void work()
Claim and execute jobs until the coordinator shuts down the pool.
Definition pangea.cpp:164
std::condition_variable completed
Definition pangea.cpp:153
bool cancelled() const
Check whether the current batch has failed or been interrupted.
Definition pangea.cpp:237
std::vector< std::thread > workers
Definition pangea.cpp:151
size_t size() const
Report the fixed worker capacity.
Definition pangea.cpp:228
void run(size_t count, std::function< void(size_t)> operation, const std::function< void()> &checkpoint)
Run indexed work and wait for every active callback to finish.
Definition pangea.cpp:246
std::atomic< bool > cancel
Definition pangea.cpp:159
std::function< void(size_t)> task
Definition pangea.cpp:154
const double started_cpu
Definition pangea.cpp:278
size_t photo_batch_capacity(uint64_t photo_budget_mib=128) const
Estimate how many photos can be prepared in one desktop batch.
Definition pangea.cpp:380
bool desktop() const
Check which execution policy was selected.
Definition pangea.cpp:357
std::unique_ptr< DesktopPool > pool
Definition pangea.cpp:291
void tile_checkpoint()
Check whether tile processing may continue.
Definition pangea.cpp:361
void parallel_tiles(size_t count, std::function< void(size_t)> task)
Run a desktop batch under the coordinator's resource policy.
Definition pangea.cpp:369
Resources(uint64_t reserve_mb, int cpu_percent, fs::path pause={}, bool desktop=false)
Establish mapping limits for onboard or desktop execution.
Definition pangea.cpp:300
const double started_wall
Definition pangea.cpp:279
bool unchanged(const fs::path &source, const Json &job)
Recheck source identity before modifying map state.
Definition pangea.cpp:1691
pangea_survey::StorageDescriptor process_lock
Definition pangea.cpp:1530
Worker(fs::path source, fs::path output, Resources &budget, uint64_t since, const Json &camera, bool interactive, int side_limit, bool image_alignment)
Definition pangea.cpp:1835
void process(const Json &job, PreparedPhoto *prepared=nullptr, std::exception_ptr prepared_error=nullptr)
Definition pangea.cpp:1702
void save()
Publish the current resume checkpoint through the atomic JSON writer.
Definition pangea.cpp:1683
Json align(Photo &photo, const std::string &name, ImageFeatures *cached=nullptr)
Try to refine a photo's georeferenced transform using recent photos.
Definition pangea.cpp:1577
Resources & resources
Definition pangea.cpp:1528
ImageFeatures AlignmentReference
Definition pangea.cpp:1535
pangea_survey::StorageDescriptor output_lock
Definition pangea.cpp:1530
std::vector< AlignmentReference > references
Definition pangea.cpp:1536
void run(bool watch)
Definition pangea.cpp:1916
AlignmentReference features(const Photo &photo, const std::string &name)
Extract bounded SIFT features for a possible alignment reference.
Definition pangea.cpp:1544
Own a working-file descriptor through success and exception paths.
Definition map_storage.h:45
Adapter errors exposed independently of OpenCV's exception type.
C++ value interface with explicit conversions and OpenCV JSON I/O.
static Value parse(Iterator first, Iterator last)
Copy a byte range and delegate parsing to the string overload.
Type get() const
Convert explicitly while preserving the distinction between types.
Value at(const char *key) const
Require an object member instead of substituting null.
void push_back(const Value &value)
Clone an element, append it in order and select array kind.
bool is_array() const
Inspect the array tag.
void set(const std::string &key, const Value &value)
Clone a member value, replace any matching key and select object kind.
size_t size() const
Count container entries, not string bytes or scalar payload size.
bool is_number() const
Test all three numeric categories without treating bool as numeric.
std::string dump(int indent=-1, char=' ', bool=false) const
Serialize with OpenCV and restore native JSON scalar tokens.
Type value(const char *key, Type fallback) const
Use a default only for absence, never to hide an invalid present value.
static Value array()
Make an empty array.
static Value object()
Make an empty object.
bool is_null() const
Inspect the null tag.
bool contains(const char *key) const
Check member presence without interpreting a null value as missing.
bool is_object() const
Inspect the object tag.
RAII guard installing the backend at startup and joining workers before main() exits.
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.
static bool start(uint32_t session)
Admit a nonzero session and discard correlation from the previous one.
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
static bool stopping
static bool pending
static struct ear_inference_result queued_evidence completed
static bool supported(enum exif_directory directory, uint16_t tag)
Select standard fields retained by the default import policy.
Definition exifite.c:595
Bounded C11 EXIF metadata and JPEG streaming interfaces.
bool exif_value_unsigned(const struct exif_value *value, size_t index, uint32_t *result)
Decode one BYTE, SHORT or LONG component without an unaligned load.
Definition exifite.c:339
int exif_parse(struct exif_view *view, const unsigned char *payload, size_t size)
Validate an EXIF APP1 payload and create a borrowed view.
Definition exifite.c:257
exif_directory
Directory identities, not on-disk tag numbers or offsets.
Definition exifite.h:59
bool exif_get(const struct exif_view *view, enum exif_directory directory, uint16_t tag, struct exif_value *value)
Look up a directory-local tag without copying its bytes.
Definition exifite.c:310
#define EXIF_MAX_PAYLOAD
APP1 payload ceiling: the JPEG length includes its own two bytes.
Definition exifite.h:51
@ EXIF_ASCII
Definition exifite.h:66
@ EXIF_SHORT
Definition exifite.h:67
@ EXIF_UNDEFINED
Definition exifite.h:70
@ EXIF_CAMERA
Definition exifite.h:59
@ EXIF_PRIMARY
Definition exifite.h:59
@ EXIF_DOCUMENT_NAME
Definition exifite.h:79
@ EXIF_IMAGE_DESCRIPTION
Definition exifite.h:80
@ EXIF_USER_COMMENT
Definition exifite.h:93
@ EXIF_ORIENTATION
Definition exifite.h:81
static struct image_mock_workspace workspace
Decode JPEGs with IJG scanlines into BGRA previews or disk-backed rasters.
char evidence[8192]
Definition lwir_image.c:66
struct jpeg_compress_struct encoder
Definition lwir_image.c:59
uint8_t marker[LWIR_THERMAL_HEADER_BYTES+LWIR_THERMAL_CHUNK_CAPACITY]
Definition lwir_image.c:62
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
struct jpeg_error_mgr error
Definition lwir_image.c:60
struct jpeg_decompress_struct decoder
Definition lwir_mock.c:55
static uint8_t combined[256U *192U *4U]
Integrity checks and bounded disk-backed intermediates for surveys.
cv::Matx33d rotation(double roll, double pitch, double yaw)
Definition pangea.cpp:677
Json camera_profile(const fs::path &path)
Definition pangea.cpp:691
constexpr int tile_size
Definition pangea.cpp:106
constexpr uint64_t memory_limit
Definition pangea.cpp:98
void blend_tile(const Photo &photo, const fs::path &root, uint64_t sequence, Resources &resources, int tile_column, int tile_row)
Definition pangea.cpp:1139
Photo read_photo(const fs::path &path, Resources &resources, const Json &camera, bool standard_profile=false, bool parallel_decode=false)
Admit and decode one source JPEG into a projection-ready photo.
Definition pangea.cpp:990
void stop(int)
Definition pangea.cpp:116
constexpr uint64_t mib
Definition pangea.cpp:95
usher_cv_json::Value Json
Definition pangea.cpp:91
void photo_check(bool condition, const char *message)
Definition pangea.cpp:512
void write_json(const fs::path &path, const Json &value)
Definition pangea.cpp:594
std::atomic< sig_atomic_t > stopping
Definition pangea.cpp:109
constexpr double projected_pixel_m
Definition pangea.cpp:104
std::unique_ptr< FILE, FileCloser > File
Definition pangea.cpp:496
fs::path tile_path(const fs::path &root, int column, int row)
Definition pangea.cpp:1112
void jpeg_message(j_common_ptr state, int level)
Screen scan diagnostics before dispatching to libjpeg's usual handler.
Definition pangea.cpp:965
void blend(const Photo &photo, const fs::path &root, uint64_t sequence, Resources &resources)
Apply one photo to the tiles enclosed by its footprint.
Definition pangea.cpp:1211
void blend_prepared(const PreparedPhoto &prepared, const fs::path &root, uint64_t sequence, Resources &resources)
Commit a prepared photo's contributions to independent tile files.
Definition pangea.cpp:1317
double seconds(clockid_t clock)
Definition pangea.cpp:127
uint64_t proc_kib(const char *path, const char *wanted)
Definition pangea.cpp:137
std::unique_ptr< DIR, DirectoryCloser > Directory
Definition pangea.cpp:503
std::string digest(const void *data, size_t size)
Definition pangea.cpp:615
void jpeg_failure(j_common_ptr state)
Route a libjpeg fatal callback to the active recovery point.
Definition pangea.cpp:959
std::string identity(const fs::path &path, bool allow_missing=false)
Definition pangea.cpp:631
void prepare_projection(PreparedPhoto &prepared, Resources &resources)
Stage projected colour and weights without modifying durable tiles.
Definition pangea.cpp:1258
void export_map(const fs::path &root, const Json &state, Resources &resources, int max_map_side)
Definition pangea.cpp:1362
pid_t parent_pid
Definition pangea.cpp:112
void sync_directory(const fs::path &path)
Definition pangea.cpp:538
constexpr double pi
Definition pangea.cpp:100
void disk_headroom(const fs::path &root, uint64_t required)
Definition pangea.cpp:1121
Json read_json(const fs::path &path)
Definition pangea.cpp:602
constexpr double world_pixels
Definition pangea.cpp:102
void check(bool condition, const char *message)
Definition pangea.cpp:120
double numeric(const Json &values, const char *key, double minimum, double maximum)
Definition pangea.cpp:665
std::string exif_text(const exif_view *metadata, exif_directory directory, uint16_t tag)
Definition pangea.cpp:650
File regular_file(const fs::path &path, uint64_t maximum)
Definition pangea.cpp:520
constexpr int max_photos
Definition pangea.cpp:108
void validateJpegScanMessage(j_common_ptr state)
Apply the shared JPEG marker bounds to the current decoder state.
Definition jpeg_stream.h:44
Header-only C++17 value adapter around OpenCV's JSON persistence layer.
Header-only C++17 cv::parallel::ParallelForAPI backend for Sensoraia.
int main(int argc, char **argv)
Dispatch PANGEA survey commands or run incremental photo mapping.
Definition pangea.cpp:2067
int pangeaSurveyMain(int argc, char **argv)
Definition survey.cpp:204
static const char header[]
Definition pose_log.c:87
static size_t count
Definition pose_log.c:79
static FILE * output
Definition pose_log.c:77
void sha256_bytes(const void *data, size_t length, void *output)
Hash one memory region to its standard 32-byte binary digest.
Definition sha256fst.c:279
Allocation-free, portable SHA-256 checksums for memory and streams.
#define PANGEA_BUILD_VERSION
Definition version.h:76
Measured pinhole calibration for the delivered image, including its mount.
Borrowed bytes plus enough type information for safe interpretation.
Definition exifite.h:119
const unsigned char * data
Definition exifite.h:120
size_t size
Definition exifite.h:121
uint32_t count
Definition exifite.h:122
uint16_t format
Definition exifite.h:123
Borrowed view of a validated APP1 payload.
Definition exifite.h:131
AtomicFile(const fs::path &destination)
Definition pangea.cpp:554
void write(const void *data, size_t length)
Definition pangea.cpp:571
void text(const std::string &value)
Append serialized text without adding a terminator or newline.
Definition pangea.cpp:577
~AtomicFile()
Remove abandoned staging data without removing committed output.
Definition pangea.cpp:567
Json json() const
Definition pangea.cpp:717
static Bounds from(const Json &value, int max_map_side=8192)
Definition pangea.cpp:720
bool empty() const
Definition pangea.cpp:715
Bounds include(const Bounds &other, int max_map_side=8192) const
Extend the committed tile envelope without changing either input.
Definition pangea.cpp:739
~Decoder()
Release codec allocations only if creation succeeded.
Definition pangea.cpp:976
jpeg_decompress_struct state
Definition pangea.cpp:970
void operator()(DIR *directory) const
Release an owned, non-null directory stream.
Definition pangea.cpp:501
jpeg_compress_struct state
Definition pangea.cpp:1346
~Encoder()
Release initialized compressor state on success or recovery.
Definition pangea.cpp:1351
void operator()(FILE *file) const
Release an owned, non-null file stream.
Definition pangea.cpp:494
std::vector< cv::KeyPoint > keypoints
Definition pangea.cpp:1240
void(* emit)(j_common_ptr, int)
Definition pangea.cpp:954
jpeg_error_mgr manager
Definition pangea.cpp:952
Json geographic_corners() const
Definition pangea.cpp:769
void geometry(const exif_view *metadata, int width, int height, const Json &camera, bool standard_profile)
Definition pangea.cpp:786
std::array< cv::Point2f, 4 > corners(const cv::Matx33d &transform) const
Definition pangea.cpp:754
void update_bounds(int width, int height)
Recompute the tile footprint after setting the image homography.
Definition pangea.cpp:921
cv::Matx33d to_world
Definition pangea.cpp:751
std::unique_ptr< ImageFeatures > features
Definition pangea.cpp:1250
std::vector< ProjectedTile > tiles
Definition pangea.cpp:1249
void save(const fs::path &path)
Definition pangea.cpp:1098
void load(const fs::path &path)
Definition pangea.cpp:1071
One timestamped geographic position for a replay annotation.
One measured camera calibration loaded from the flat PANGEA profile format.
struct coverage_camera calibration
static std::unique_ptr< pangea_survey::MapResources > resources
Definition survey.cpp:50
static struct camera_backend camera
Definition usher.c:521
bool valid
Definition usher.c:537
struct usher_control_result result
Definition usher.c:377
struct capture_job job
Definition usher.c:370
union dc_shot_union shot
Definition usher.c:534