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
ortho_map.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 ortho_map.h
20 * @brief Describe the validated photo set and render projected map windows.
21 * @details Rendering retains source provenance and a per-pixel confidence class
22 * alongside colour so publication can distinguish observed colour from
23 * completion. The API keeps rendering separate from JPEG/XYZ publication,
24 * allowing both output formats to share the same map engine.
25 */
26#ifndef PANGEA_ORTHO_MAP_H
27#define PANGEA_ORTHO_MAP_H
28
29#include "map_config.h"
30#include "map_projection.h"
31#include "camera_projection.h"
32#include <functional>
33#include <memory>
34#include <vector>
35
36namespace pangea_survey {
37/** @brief UTM-aligned extent and tile count for one requested map area. */
39 double west = 0, north = 0, east = 0, south = 0;
40 std::size_t columns = 0, rows = 0;
41 int epsg = 0;
42};
43/**
44 * @brief Compute a north-up, non-overlapping image grid for the requested bounds.
45 * @param[in] config Validated geographic bounds, pixel size, and tile dimensions.
46 * @return Projected bounds, EPSG code, and whole-tile row/column counts.
47 */
48OrthoLayout orthoLayout(const MapConfig& config);
49/**
50 * @brief One fixed-session source image and its camera/pose evidence.
51 * @details Coordinates are WGS-84 degrees; elevations are AMSL metres; camera
52 * intrinsics are pixels; timestamps are 100 ns monotonic counts. The optional
53 * capture cell lets Great use the planned flight grid without inventing pose data.
54 */
56 std::filesystem::path path;
57 std::optional<CameraPlane> camera;
58 double latitude = 0, longitude = 0, altitude = 0;
59 double focal = 0, cx = 0, cy = 0;
60 double focalY = 0, poseUncertainty = 0;
61 double pitch = 0, bank = 0, heading = 0, fov = 0;
62 long long poseTime = 0, frameTime = 0;
63 int width = 0, height = 0;
64 std::optional<UtcDateTime> captureUtc;
66 long long utcRead100ns = 0;
67 double referencePlane = std::numeric_limits<double>::quiet_NaN();
68 bool distorted = false;
70 std::optional<std::pair<int, int>> captureCell;
71};
72/**
73 * @brief Rendered BGRA map plus coverage, source list, and method provenance.
74 * @details Confidence is independent of colour: zero means no supported colour,
75 * and Great's reconstruction classes must not be reported as observed camera
76 * geometry. `validFraction` is image colour coverage, not map accuracy.
77 */
78struct OrthoImage {
80 int width = 0, height = 0;
81 std::vector<unsigned char> bgra, confidence;
82 std::vector<OrthoSource> sources;
83 double validFraction = 0;
85 std::string mode = "simple";
86 double referencePlane = std::numeric_limits<double>::quiet_NaN();
87 int seamScale = 0, blendBands = 0;
88 std::string seamMethod;
89 bool exposureCompensated = false;
91};
92/**
93 * @brief Load a fixed-session source set and render its projected tiles/windows.
94 * @details The implementation owns bounded decoded-photo and rendered-block
95 * caches. Returned images own their pixel/provenance vectors; cancellation is
96 * cooperative and throws before an incomplete render can be treated as complete.
97 */
99 struct Impl;
100 std::unique_ptr<Impl> impl_;
101public:
102 /**
103 * @brief Validate source CSV rows and derive the requested output grid.
104 * @param[in] config Validated mapping configuration.
105 * @param[in] csv Source manifest with one consistent fixed-session camera setup.
106 * @throws std::runtime_error If any source, calibration, pose, or session contract fails.
107 */
108 Orthorectifier(const MapConfig& config, const std::filesystem::path& csv);
109 /** @brief Release the render state and its caches.
110 * @details Defined out of line where the private implementation is complete. */
112 /** @brief Disallow copying the owned render state. */
114 /** @brief Disallow copy assignment of the owned render state. */
116 /** @brief Return output tile columns. */
117 std::size_t columns() const;
118 /** @brief Return output tile rows. */
119 std::size_t rows() const;
120 /** @brief Return total requested map tiles. */
121 std::size_t size() const;
122 /** @brief Return the validated common capture UTC target, when present. */
123 std::optional<UtcDateTime> captureUtc() const;
124 /** @brief Return the validated source count without decoding pixels. */
125 std::size_t sourceCount() const;
126 /**
127 * @brief Hash canonical source paths and current JPEG contents in source order.
128 * @param[in] stopped Cooperative cancellation predicate.
129 * @return Content fingerprint used to detect changes to admitted photographs.
130 */
131 std::string sourceFingerprint(const std::function<bool()>& stopped) const;
132 /**
133 * @brief Prepare shared source rasters/mosaic state before repeated rendering.
134 * @param[in] stopped Cooperative cancellation predicate.
135 */
136 void prepareSources(const std::function<bool()>& stopped);
137 /**
138 * @brief Render one configured output tile.
139 * @param[in] index Row-major tile index in `[0, size())`.
140 * @param[in] stopped Cooperative cancellation predicate.
141 * @param[in] progress Optional render fraction callback in `[0, 1]`.
142 * @return Owned image pixels, confidence classes, and source provenance.
143 * @throws std::runtime_error If index is invalid, rendering fails, or canceled.
144 */
145 OrthoImage render(std::size_t index, const std::function<bool()>& stopped,
146 const std::function<void(double)>& progress = {});
147 /**
148 * @brief Render an arbitrary bounded window of the configured map grid.
149 * @param[in] originX Leftmost map-grid pixel.
150 * @param[in] originY Topmost map-grid pixel.
151 * @param[in] width Window width in pixels.
152 * @param[in] height Window height in pixels.
153 * @param[in] stopped Cooperative cancellation predicate.
154 * @param[in] progress Optional render fraction callback in `[0, 1]`.
155 * @return Owned image and coverage metadata for the requested window.
156 * @throws std::runtime_error If bounds exceed the configured area or rendering fails.
157 */
158 OrthoImage renderWindow(std::size_t originX, std::size_t originY, int width, int height,
159 const std::function<bool()>& stopped,
160 const std::function<void(double)>& progress = {});
161 static void selfTest();
162 /**
163 * @brief Rectify JPEG sources into working JPEGs and write a new CSV.
164 * @param[in] csv Original source CSV.
165 * @param[in] directory New directory for normalized JPEGs and CSV.
166 * @param[in] stopped Cooperative cancellation predicate.
167 * @param[in] workers Upper bound on independent source-preparation workers.
168 * @param[in] memoryMiB Working-memory budget used to reduce the worker count.
169 * @return Path to the normalized source CSV.
170 * @throws std::runtime_error If source decoding, rectification, or publication fails.
171 */
172 static std::filesystem::path normalizeSources(const std::filesystem::path& csv,
173 const std::filesystem::path& directory, const std::function<bool()>& stopped,
174 unsigned workers = 1, unsigned memoryMiB = 128);
175};
176}
177#endif
Map calibrated camera pixels to a local flat ground plane.
std::size_t size() const
Return total requested map tiles.
~Orthorectifier()
Release the render state and its caches.
std::optional< UtcDateTime > captureUtc() const
Return the validated common capture UTC target, when present.
void prepareSources(const std::function< bool()> &stopped)
Prepare shared source rasters/mosaic state before repeated rendering.
std::size_t rows() const
Return output tile rows.
Orthorectifier(const MapConfig &config, const std::filesystem::path &csv)
Validate source CSV rows and derive the requested output grid.
Orthorectifier & operator=(const Orthorectifier &)=delete
Disallow copy assignment of the owned render state.
std::unique_ptr< Impl > impl_
Definition ortho_map.h:100
OrthoImage renderWindow(std::size_t originX, std::size_t originY, int width, int height, const std::function< bool()> &stopped, const std::function< void(double)> &progress={})
Render an arbitrary bounded window of the configured map grid.
static std::filesystem::path normalizeSources(const std::filesystem::path &csv, const std::filesystem::path &directory, const std::function< bool()> &stopped, unsigned workers=1, unsigned memoryMiB=128)
Rectify JPEG sources into working JPEGs and write a new CSV.
std::size_t sourceCount() const
Return the validated source count without decoding pixels.
static void selfTest()
Run synthetic orthorectification regression cases.
OrthoImage render(std::size_t index, const std::function< bool()> &stopped, const std::function< void(double)> &progress={})
Render one configured output tile.
std::size_t columns() const
Return output tile columns.
std::string sourceFingerprint(const std::function< bool()> &stopped) const
Hash canonical source paths and current JPEG contents in source order.
Orthorectifier(const Orthorectifier &)=delete
Disallow copying the owned render state.
Own the survey mapper's validated configuration and mode defaults.
Convert between WGS-84 coordinates and one local UTM grid.
OrthoLayout orthoLayout(const MapConfig &config)
Compute a north-up, non-overlapping image grid for the requested bounds.
Engineering lens-distortion and lateral colour-scale parameters.
Fully parsed settings shared by orthomap and XYZ export.
Definition map_config.h:41
Centre and pixel geometry for a projected image tile.
Rendered BGRA map plus coverage, source list, and method provenance.
Definition ortho_map.h:78
std::vector< OrthoSource > sources
Definition ortho_map.h:82
std::vector< unsigned char > bgra
Definition ortho_map.h:81
std::vector< unsigned char > confidence
Definition ortho_map.h:81
UTM-aligned extent and tile count for one requested map area.
Definition ortho_map.h:38
One fixed-session source image and its camera/pose evidence.
Definition ortho_map.h:55
std::filesystem::path path
Definition ortho_map.h:56
std::optional< CameraPlane > camera
Definition ortho_map.h:57
std::optional< std::pair< int, int > > captureCell
Definition ortho_map.h:70
std::optional< UtcDateTime > captureUtc
Definition ortho_map.h:64