Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
map_projection.h
Go to the documentation of this file.
1/*
2 * Copyright 2026 OpenUAS
3 * SPDX-License-Identifier: Apache-2.0
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/**
19 * @file map_projection.h
20 * @brief Convert between WGS-84 coordinates and one local UTM grid.
21 * @details Map pixels are laid out in metres in a single zone so resampling
22 * and world-file spacing stay linear across a small survey. Inputs outside
23 * the supported UTM latitude, hemisphere, or zone span are rejected rather
24 * than silently producing a plausible-looking but invalid grid.
25 */
26#ifndef PANGEA_MAP_PROJECTION_H
27#define PANGEA_MAP_PROJECTION_H
28
29#include <algorithm>
30#include <cmath>
31#include <stdexcept>
32#include <utility>
33
34namespace pangea_survey {
35/** @brief Centre and pixel geometry for a projected image tile. */
36struct MapTile {
38 int epsg;
39};
40
41/**
42 * @brief Forward and inverse WGS-84 Transverse Mercator conversion for one UTM zone.
43 * @details This projection locates simulator imagery; it does not establish
44 * camera calibration, relief correction, or surveyed positional accuracy.
45 */
47 int zone_;
48 bool north_;
49 static constexpr double a = 6378137, e2 = 0.0066943799901413165, k = 0.9996;
50 static constexpr double radians = 0.01745329251994329577;
51 /** @brief Select a standard six-degree UTM zone.
52 * @param latitude WGS-84 latitude in degrees.
53 * @param longitude WGS-84 longitude in degrees.
54 * @return Zone number from 1 to 60.
55 * @throws std::runtime_error For nonfinite or unsupported coordinates.
56 * @details Clamp the positive antimeridian endpoint to zone 60 and
57 * use regular longitudinal bands rather than regional exceptions. */
58 static int zone(double latitude, double longitude) {
59 if (!std::isfinite(latitude) || !std::isfinite(longitude) || latitude < -80 || latitude > 84 ||
61 throw std::runtime_error("Mapping grid requires WGS-84 latitude -80..84 and longitude -180..180");
62 return std::clamp(static_cast<int>(std::floor((longitude + 180) / 6)) + 1, 1, 60);
63 }
64public:
65 /**
66 * @brief Choose the UTM zone and hemisphere from a representative coordinate.
67 * @param[in] latitude WGS-84 latitude in degrees.
68 * @param[in] longitude WGS-84 longitude in degrees.
69 * @throws std::runtime_error If the coordinate is outside supported UTM limits.
70 */
73 /** @brief Get the CRS identifier for this WGS-84 UTM zone.
74 * @return EPSG code in the northern 326xx or southern 327xx family.
75 * @details Include the hemisphere so consumers can interpret false northing. */
76 int epsg() const { return (north_ ? 32600 : 32700) + zone_; }
77 /** @brief Return the selected zone's central meridian in radians. */
78 double centralMeridian() const { return (zone_ * 6 - 183) * radians; }
79 /** @brief Estimate grid convergence in degrees at a geographic position. */
80 double convergence(double latitude, double longitude) const {
81 return std::atan(std::tan(longitude * radians - centralMeridian()) *
82 std::sin(latitude * radians)) / radians;
83 }
84 /** @brief Estimate local UTM point scale at a geographic position. */
85 double scale(double latitude, double longitude) const {
86 const double p = latitude * radians;
87 const double A = std::cos(p) * (longitude * radians - centralMeridian());
88 const double C = e2 / (1 - e2) * std::pow(std::cos(p), 2);
89 const double T = std::pow(std::tan(p), 2);
90 return k * (1 + (1 + C) * A * A / 2 +
91 (5 - 4 * T + 42 * C + 13 * C * C - 28 * e2 / (1 - e2)) * std::pow(A, 4) / 24);
92 }
93 /**
94 * @brief Project a geographic position into UTM easting and northing.
95 * @param[in] latitude WGS-84 latitude in degrees.
96 * @param[in] longitude WGS-84 longitude in degrees.
97 * @return Easting and northing in metres, including standard UTM false origins.
98 * @throws std::runtime_error If the coordinate crosses the selected hemisphere
99 * or lies too far from the selected zone's central meridian.
100 */
101 std::pair<double, double> forward(double latitude, double longitude) const {
102 if (!std::isfinite(latitude) || !std::isfinite(longitude) || latitude < -80 || latitude > 84 ||
103 (latitude >= 0) != north_ || std::abs(longitude * radians - centralMeridian()) > 0.105)
104 throw std::runtime_error("Area crosses a hemisphere or extends too far from its UTM zone");
105 const double p = latitude * radians, l = longitude * radians;
106 const double s = std::sin(p), c = std::cos(p), t = std::tan(p);
107 const double ep = e2 / (1 - e2), n = a / std::sqrt(1 - e2 * s * s);
108 const double T = t * t, C = ep * c * c, A = c * (l - centralMeridian());
109 const double e4 = e2 * e2, e6 = e4 * e2;
110 const double M = a * ((1 - e2 / 4 - 3 * e4 / 64 - 5 * e6 / 256) * p -
111 (3 * e2 / 8 + 3 * e4 / 32 + 45 * e6 / 1024) * std::sin(2 * p) +
112 (15 * e4 / 256 + 45 * e6 / 1024) * std::sin(4 * p) -
113 35 * e6 / 3072 * std::sin(6 * p));
114 return {500000 + k * n * (A + (1 - T + C) * std::pow(A, 3) / 6 +
115 (5 - 18 * T + T * T + 72 * C - 58 * ep) * std::pow(A, 5) / 120),
116 (north_ ? 0 : 10000000) + k * (M + n * t * (A * A / 2 +
117 (5 - T + 9 * C + 4 * C * C) * std::pow(A, 4) / 24 +
118 (61 - 58 * T + T * T + 600 * C - 330 * ep) * std::pow(A, 6) / 720))};
119 }
120 /**
121 * @brief Convert UTM easting/northing back to WGS-84 latitude/longitude.
122 * @param[in] east UTM easting in metres.
123 * @param[in] north UTM northing in metres.
124 * @return Latitude and longitude in degrees.
125 * @throws std::runtime_error If either projected coordinate is nonfinite.
126 */
127 std::pair<double, double> inverse(double east, double north) const {
128 if (!std::isfinite(east) || !std::isfinite(north))
129 throw std::runtime_error("Nonfinite mapping-grid coordinates");
130 const double e4 = e2 * e2, e6 = e4 * e2;
131 const double mu = (north - (north_ ? 0 : 10000000)) /
132 (k * a * (1 - e2 / 4 - 3 * e4 / 64 - 5 * e6 / 256));
133 const double e1 = (1 - std::sqrt(1 - e2)) / (1 + std::sqrt(1 - e2));
134 const double p = mu + (3 * e1 / 2 - 27 * std::pow(e1, 3) / 32) * std::sin(2 * mu) +
135 (21 * e1 * e1 / 16 - 55 * std::pow(e1, 4) / 32) * std::sin(4 * mu) +
136 151 * std::pow(e1, 3) / 96 * std::sin(6 * mu) +
137 1097 * std::pow(e1, 4) / 512 * std::sin(8 * mu);
138 const double s = std::sin(p), c = std::cos(p), t = std::tan(p);
139 const double ep = e2 / (1 - e2), C = ep * c * c, T = t * t;
140 const double n = a / std::sqrt(1 - e2 * s * s);
141 const double r = a * (1 - e2) / std::pow(1 - e2 * s * s, 1.5);
142 const double D = (east - 500000) / (n * k);
143 return {(p - n * t / r * (D * D / 2 -
144 (5 + 3 * T + 10 * C - 4 * C * C - 9 * ep) * std::pow(D, 4) / 24 +
145 (61 + 90 * T + 298 * C + 45 * T * T - 252 * ep - 3 * C * C) *
146 std::pow(D, 6) / 720)) / radians,
147 (centralMeridian() + (D - (1 + 2 * T + C) * std::pow(D, 3) / 6 +
148 (5 - 2 * C + 28 * T - 3 * C * C + 8 * ep + 24 * T * T) *
149 std::pow(D, 5) / 120) / c) / radians};
150 }
151};
152}
153#endif
static double latitude
static double longitude
double convergence(double latitude, double longitude) const
Estimate grid convergence in degrees at a geographic position.
MapProjection(double latitude, double longitude)
Choose the UTM zone and hemisphere from a representative coordinate.
double centralMeridian() const
Return the selected zone's central meridian in radians.
static constexpr double e2
static constexpr double a
static constexpr double k
double scale(double latitude, double longitude) const
Estimate local UTM point scale at a geographic position.
static constexpr double radians
int epsg() const
Get the CRS identifier for this WGS-84 UTM zone.
std::pair< double, double > inverse(double east, double north) const
Convert UTM easting/northing back to WGS-84 latitude/longitude.
static int zone(double latitude, double longitude)
Select a standard six-degree UTM zone.
std::pair< double, double > forward(double latitude, double longitude) const
Project a geographic position into UTM easting and northing.
Centre and pixel geometry for a projected image tile.