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
great_session.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file great_session.h
20 * @brief Coordinate append-only, restartable GREAT XYZ survey sessions.
21 * @details The session lease excludes both another offline mapper and the live
22 * capture mapper. Each revision is fingerprinted and prepared before `latest`
23 * moves, so interruption cannot replace the last usable revision.
24 */
25#ifndef PANGEA_GREAT_SESSION_H
26#define PANGEA_GREAT_SESSION_H
27
28#include <sys/stat.h>
29
30namespace pangea_survey {
31/**
32 * @brief Hold the per-user GREAT and live-PANGEA locks for one session update.
33 * @details Both locks are necessary because offline remapping and the live
34 * watcher compete for the same camera-compute memory and output resources.
35 */
37 std::array<int, 2> descriptors_{{-1, -1}};
38public:
39 /** @brief Acquire both nonblocking locks or fail without disturbing the owner. */
41 const std::array<std::string, 2> paths{{
42 "/tmp/pangea-survey-" + std::to_string(getuid()) + ".lock",
43 "/tmp/usher-pangea-" + std::to_string(getuid()) + ".lock"}};
44 for (std::size_t index = 0; index < paths.size(); ++index) {
45 const int descriptor = open(paths[index].c_str(), O_CREAT | O_RDWR | O_NOFOLLOW | O_CLOEXEC, 0600);
46 if (descriptor < 0 || flock(descriptor, LOCK_EX | LOCK_NB) != 0) {
47 if (descriptor >= 0) close(descriptor);
48 for (const auto held : descriptors_) if (held >= 0) close(held);
49 throw std::runtime_error("Another Pangea mapper is active; capture remains independent");
50 }
51 descriptors_[index] = descriptor;
52 }
53 const auto pid = std::to_string(getpid()) + "\n";
54 if (ftruncate(descriptors_[0], 0) != 0 ||
55 write(descriptors_[0], pid.data(), pid.size()) != static_cast<ssize_t>(pid.size()) ||
56 fsync(descriptors_[0]) != 0) {
57 for (const auto held : descriptors_) close(held);
58 throw std::runtime_error("Cannot record GREAT session owner");
59 }
60 }
61 /** @brief Release both locks without removing the lock paths.
62 * @details Other callers must continue locking the same files. */
63 ~GreatSessionLease() { for (const auto held : descriptors_) if (held >= 0) close(held); }
64 /** @brief Noncopyable: both descriptors have a single lifetime owner. */
66 /** @brief Nonassignable: an active lease cannot be replaced by copying. */
68};
69
70/**
71 * @brief Read a bounded regular session file without following symlinks.
72 * @param[in] path Session input, identity, or admission record.
73 * @return Complete file contents, up to 4 MiB.
74 * @throws std::runtime_error If the path is not a regular bounded file or reading fails.
75 */
76inline std::string sessionText(const fs::path& path) {
77 const int descriptor = open(path.c_str(), O_RDONLY | O_CLOEXEC | O_NOFOLLOW | O_NONBLOCK);
78 if (descriptor < 0) throw std::runtime_error("Cannot open session input: " + path.string());
79 struct stat status{};
80 if (fstat(descriptor, &status) != 0 || !S_ISREG(status.st_mode) || status.st_size > 4 * 1024 * 1024) {
82 throw std::runtime_error("Session input must be a regular file of at most 4 MiB");
83 }
84 std::string text;
85 std::array<char, 65536> buffer{};
86 for (;;) {
87 const auto count = read(descriptor, buffer.data(), buffer.size());
88 if (count < 0 && errno == EINTR) continue;
89 if (count < 0 || text.size() + static_cast<std::size_t>(count) > 4 * 1024 * 1024) {
91 throw std::runtime_error("Cannot read bounded session input");
92 }
93 if (!count) break;
94 text.append(buffer.data(), static_cast<std::size_t>(count));
95 }
97 return text;
98}
99
100/**
101 * @brief Snapshot the current accepted photo list for one GREAT revision.
102 * @param[in] config Session settings and either a source CSV or photo directory.
103 * @return The accepted list plus newly arrived, sorted AI Camera basenames.
104 * @throws std::runtime_error If the admission record, photo names, or row limit is invalid.
105 * @details Existing rows remain a prefix; preserving their order is required
106 * for stable revision identity and deterministic checkpoint reuse.
107 */
108inline std::string greatInputText(const MapConfig& config) {
109 if (config.photoDirectory.empty()) return sessionText(config.sourceCsv);
110 std::string text = "USHER_AICAM_V1\n";
111 std::map<std::string, bool> admitted;
112 if (fs::exists(config.output / "accepted")) {
113 const auto record = sessionText(config.output / "accepted");
114 if (record.size() < 65 || record[64] != '\n') throw std::runtime_error("Invalid AI Camera admission record");
115 text = record.substr(65);
116 std::istringstream lines(text);
117 std::string name;
118 if (!std::getline(lines, name) || name != "USHER_AICAM_V1") throw std::runtime_error("Invalid AI Camera snapshot schema");
119 while (std::getline(lines, name)) admitted.emplace(name, true);
120 }
121 std::vector<std::string> arrivals;
122 for (const auto& entry : fs::directory_iterator(config.photoDirectory)) {
123 const auto name = entry.path().filename().string();
124 if (name.empty() || name.front() != 'a' || entry.path().extension() != ".jpg" || admitted.count(name)) continue;
125 if (admitted.size() + arrivals.size() >= 4096) throw std::runtime_error("AI Camera session exceeds 4096 photos");
126 arrivals.push_back(name);
127 }
128 std::sort(arrivals.begin(), arrivals.end());
129 for (const auto& name : arrivals) text += name + '\n';
130 return text;
131}
132
133/**
134 * @brief Atomically point `latest` at a completed, owned revision.
135 * @param[in] root Session output root.
136 * @param[in] revision Validated revision name beneath `revisions/`.
137 * @throws std::runtime_error If staging, ownership checks, rename, or directory sync fails.
138 */
139inline void publishGreatLatest(const fs::path& root, const std::string& revision) {
140 const auto pending = root / "latest.partial";
141 if (fs::is_symlink(pending)) fs::remove(pending);
142 if (fs::exists(pending)) throw std::runtime_error("Unexpected latest revision staging path");
143 fs::create_directory_symlink(fs::path("revisions") / revision, pending);
144 if (fs::exists(root / "latest") && !fs::is_symlink(root / "latest"))
145 throw std::runtime_error("Latest revision path is not an owned symlink");
146 fs::rename(pending, root / "latest");
147 const int directory = open(root.c_str(), O_RDONLY | O_DIRECTORY | O_CLOEXEC);
148 if (directory < 0) throw std::runtime_error("Cannot open session publication directory");
149 const int status = fsync(directory);
150 close(directory);
151 if (status != 0) throw std::runtime_error("Cannot synchronize latest revision");
152}
153
154/** @brief Validate a digest-based revision name and its preview/final suffix. */
155inline bool greatRevisionName(const std::string& name) {
156 if (name.size() < 64 || (name.substr(64) != "-preview" && name.substr(64) != "-final")) return false;
157 return std::all_of(name.begin(), name.begin() + 64, [](char value) {
158 return (value >= '0' && value <= '9') || (value >= 'a' && value <= 'f');
159 });
160}
161
162/**
163 * @brief Admit new photos and optionally publish a GREAT preview/final revision.
164 * @param[in] settings Validated low-memory GREAT XYZ configuration.
165 * @param[in] ini Configuration whose content participates in session identity.
166 * @param[in] final True to require a closed photo list and finalize the session.
167 * @param[in] render False to prepare source/checkpoint state without rendering.
168 * @return True when input was admitted or a revision was processed; false when
169 * no complete input row is available yet.
170 * @throws std::runtime_error If session identity, append order, source contents,
171 * checkpoints, output coverage, or publication checks fail.
172 */
173static bool updateGreatSession(const MapConfig& settings, const fs::path& ini, bool final, bool render = true) {
174 if (!settings.lowMemory || settings.mode != "great" || settings.outputFormat != "xyz" ||
175 !settings.captureManifest.empty())
176 throw std::runtime_error("Incremental GREAT requires low_memory GREAT XYZ and CSV or AI Camera photos");
177 const auto root = fs::weakly_canonical(fs::absolute(settings.output));
178 const auto sourceDirectory = settings.photoDirectory.empty() ? fs::canonical(settings.sourceCsv).parent_path() :
179 fs::canonical(settings.photoDirectory);
180 if (root == sourceDirectory)
181 throw std::runtime_error("Session output must be separate from the photo directory");
182 const auto profileIdentity = settings.photoDirectory.empty() ? std::string() : fileDigest(settings.cameraProfile);
183 const auto identity = "PANGEA_GREAT_SESSION_V1\n" + fileDigest(ini) + "\n" +
184 (settings.photoDirectory.empty() ? fs::canonical(settings.sourceCsv) : sourceDirectory).generic_string() + "\n" +
185 root.generic_string() + "\n" + (profileIdentity.empty() ? "" : profileIdentity + "\n");
186 if (fs::exists(root)) {
187 if (!fs::exists(root / "identity") || sessionText(root / "identity") != identity)
188 throw std::runtime_error("Session identity changed or output is unowned; choose a new output");
189 } else {
190 fs::create_directories(root);
191 saveWorkingText(root / "identity", identity);
192 }
193 auto text = greatInputText(settings);
194 if (text.find('\0') != std::string::npos) throw std::runtime_error("NUL in growing photo CSV");
195 const auto newline = text.rfind('\n');
196 if (final && (text.empty() || newline != text.size() - 1))
197 throw std::runtime_error("Final photo CSV has an unfinished row");
198 if (newline == std::string::npos) return false;
199 text.resize(newline + 1);
200 if (text.size() > 4 * 1024 * 1024 - 65)
201 throw std::runtime_error("Growing photo CSV exceeds admission record budget");
202 if (std::count(text.begin(), text.end(), '\n') > 4097)
203 throw std::runtime_error("Growing photo CSV exceeds 4096 rows");
204 std::string accepted, acceptedIdentity;
205 if (fs::exists(root / "accepted")) {
206 const auto record = sessionText(root / "accepted");
207 const auto separator = record.find('\n');
208 if (separator != 64) throw std::runtime_error("Invalid session admission record");
209 acceptedIdentity = record.substr(0, separator);
210 accepted = record.substr(separator + 1);
211 if (text.compare(0, accepted.size(), accepted) != 0)
212 throw std::runtime_error("Committed photo CSV changed; only append is allowed");
213 }
214 if (std::count(text.begin(), text.end(), '\n') < 2) return false;
215 const auto snapshot = root / "snapshot.csv";
216 saveWorkingText(snapshot, text);
217 auto config = settings;
218 config.sourceDirectory = sourceDirectory;
219 config.sourceCsv = snapshot;
220 config.originalSourceCsv = settings.sourceCsv;
221 const XyzPlan plan(config);
222 Orthorectifier input(plan.workingConfig(config), snapshot);
223 const auto photoIdentity = input.sourceFingerprint(isStopping);
224 if (!profileIdentity.empty() && fileDigest(settings.cameraProfile) != profileIdentity)
225 throw std::runtime_error("AI Camera profile changed during admission");
226 const auto fingerprint = dataDigest(text.data(), text.size());
227 const auto revisionName = fingerprint + (final ? "-final" : "-preview");
228 const auto revision = root / "revisions" / revisionName;
229 const auto revisionIdentity = "PANGEA_GREAT_REVISION_V1\n" + identity + fingerprint + "\n" + photoIdentity + "\n";
230 std::string latest;
231 if (fs::is_symlink(root / "latest")) {
232 const auto target = fs::read_symlink(root / "latest");
233 if (target.parent_path() != fs::path("revisions") || !greatRevisionName(target.filename().string()))
234 throw std::runtime_error("Invalid session latest target");
235 latest = target.filename().string();
236 const auto prefix = "PANGEA_GREAT_REVISION_V1\n" + identity;
237 if (sessionText(root / "latest" / "identity").compare(0, prefix.size(), prefix) != 0)
238 throw std::runtime_error("Published revision belongs to another session");
239 const cv::FileStorage status((root / "latest" / "status.json").string(), cv::FileStorage::READ);
240 if (!status.isOpened()) throw std::runtime_error("Cannot verify latest revision status");
241 if (static_cast<int>(status["finalized"]) && (!final || text != accepted))
242 throw std::runtime_error("GREAT session is finalized; start a new output for another flight");
243 }
244 if (fs::exists(revision / "identity") && sessionText(revision / "identity") != revisionIdentity)
245 throw std::runtime_error("Committed source photo changed; originals and previous revision retained");
246 if (!accepted.empty()) {
247 saveWorkingText(root / "previous.csv", accepted);
248 Orthorectifier previous(plan.workingConfig(config), root / "previous.csv");
249 if (previous.sourceFingerprint(isStopping) != acceptedIdentity)
250 throw std::runtime_error("Previously committed source photo changed");
251 }
252 if (fs::exists(root / "revisions")) {
253 const auto prefix = "PANGEA_GREAT_REVISION_V1\n" + identity;
254 for (const auto& entry : fs::directory_iterator(root / "revisions")) {
255 if (entry.path() == revision || entry.path().filename().string() == latest) continue;
256 if (entry.is_symlink() || !entry.is_directory() || !greatRevisionName(entry.path().filename().string()) ||
257 sessionText(entry.path() / "identity").compare(0, prefix.size(), prefix) != 0)
258 throw std::runtime_error("Unowned revision prevents session cleanup");
259 fs::remove_all(entry.path());
260 }
261 }
262 fs::create_directories(revision);
263 if (!fs::exists(revision / "identity")) saveWorkingText(revision / "identity", revisionIdentity);
264 saveWorkingText(revision / "photos.csv", text);
265 config.sourceCsv = revision / "photos.csv";
266 config.workingDirectory = revision / "work";
267 config.preparedSourceDirectory = root / "prepared";
268 config.output = revision / "xyz";
269 config.incrementalPreview = !final;
270 if (!final) {
271 config.mosaicFillGaps = false;
272 config.xyzCompleteOnly = true;
273 }
274 fs::create_directories(config.workingDirectory);
275 {
276 Orthorectifier preparation(plan.workingConfig(config), config.sourceCsv);
277 preparation.prepareSources(isStopping);
278 }
279 saveWorkingText(root / "accepted", photoIdentity + "\n" + text);
280 if (!render) {
281 saveWorkingText(root / "status.json", "{\"schema\":\"pangea_great_session_v1\",\"state\":\"prepared\","
282 "\"finalized\":false,\"source_count\":" + std::to_string(input.sourceCount()) + "}");
283 return true;
284 }
285 exportXyzTiles(config, config.sourceCsv, config.workingDirectory);
286 if (input.sourceFingerprint(isStopping) != photoIdentity ||
287 (!profileIdentity.empty() && fileDigest(settings.cameraProfile) != profileIdentity))
288 throw std::runtime_error("Source changed during GREAT rendering; latest revision retained");
289 const cv::FileStorage report((config.workingDirectory / "dataset.json").string(), cv::FileStorage::READ);
290 if (!report.isOpened()) throw std::runtime_error("Cannot verify revision report");
291 const int tiles = static_cast<int>(report["tile_count"]);
292 std::ostringstream status;
293 status << "{\"schema\":\"pangea_great_session_v1\",\"provisional\":" << (final ? "false" : "true")
294 << ",\"finalized\":" << (final ? "true" : "false") << ",\"source_count\":" << input.sourceCount()
295 << ",\"tile_count\":" << tiles << ",\"revision\":" << PhotoExif::jsonString(revisionName) << "}";
296 saveWorkingText(revision / "status.json", status.str());
297 if (tiles) publishGreatLatest(root, revisionName);
298 saveWorkingText(root / "status.json", status.str());
299 std::cout << "GREAT " << (final ? "final" : "provisional") << " revision: " << input.sourceCount()
300 << " prepared photos, " << tiles << " published tiles; " << root.string() << '\n';
301 return true;
302}
303}
304#endif
static void report(const struct capture_intent *intent, unsigned camera_id, uint32_t outcome)
Record a terminal outcome without allowing telemetry backlog to block camera release.
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
~GreatSessionLease()
Release both locks without removing the lock paths.
GreatSessionLease(const GreatSessionLease &)=delete
Noncopyable: both descriptors have a single lifetime owner.
GreatSessionLease()
Acquire both nonblocking locks or fail without disturbing the owner.
GreatSessionLease & operator=(const GreatSessionLease &)=delete
Nonassignable: an active lease cannot be replaced by copying.
std::array< int, 2 > descriptors_
Load a fixed-session source set and render its projected tiles/windows.
Definition ortho_map.h:98
void prepareSources(const std::function< bool()> &stopped)
Prepare shared source rasters/mosaic state before repeated rendering.
std::size_t sourceCount() const
Return the validated source count without decoding pixels.
std::string sourceFingerprint(const std::function< bool()> &stopped) const
Hash canonical source paths and current JPEG contents in source order.
static std::string jsonString(const std::string &text)
Escape a string as a JSON string literal.
Definition photo_exif.h:456
static int record(const union dc_shot_union *shot)
Retrieve a point and admit a new observation only when its credit is free.
static struct latest_measurement latest
static bool pending
static bool updateGreatSession(const MapConfig &settings, const fs::path &ini, bool final, bool render=true)
Admit new photos and optionally publish a GREAT preview/final revision.
bool greatRevisionName(const std::string &name)
Validate a digest-based revision name and its preview/final suffix.
std::string sessionText(const fs::path &path)
Read a bounded regular session file without following symlinks.
std::string fileDigest(const std::filesystem::path &path, const std::function< bool()> &stopped={})
Hash a file in bounded chunks, optionally honoring cancellation.
Definition map_storage.h:89
std::string greatInputText(const MapConfig &config)
Snapshot the current accepted photo list for one GREAT revision.
std::string dataDigest(const void *data, std::size_t size)
Compute a lowercase SHA-256 digest for an in-memory byte range.
Definition map_storage.h:77
void publishGreatLatest(const fs::path &root, const std::string &revision)
Atomically point latest at a completed, owned revision.
void saveWorkingText(const std::filesystem::path &target, const std::string &text)
Save checkpoint text through the durable working-file publisher.
static size_t count
Definition pose_log.c:79
static uint64_t accepted
Definition pose_log.c:81
Fully parsed settings shared by orthomap and XYZ export.
Definition map_config.h:41
std::filesystem::path cameraProfile
Definition map_config.h:60
std::filesystem::path sourceCsv
Definition map_config.h:71
std::filesystem::path sourceDirectory
Definition map_config.h:59
std::filesystem::path output
Definition map_config.h:71
std::filesystem::path photoDirectory
Definition map_config.h:60
std::filesystem::path captureManifest
Definition map_config.h:71
Derive requested XYZ bounds, map grid, and per-zoom tile ranges.
Definition xyz_tiles.h:119
static bool isStopping()
Check cancellation at a cooperative mapping boundary.
Definition survey.cpp:68
static int exportXyzTiles(const pangea_survey::MapConfig &config, const fs::path &csv, const fs::path &workDirectory, bool diagnostic=false)
Render and publish the planned XYZ pyramid, optionally as diagnostics.
Definition xyz_export.h:230