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_writer.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_writer.h
20 * @brief Write georeferencing sidecars for rendered Pangea map images.
21 * @details The world file and PAM metadata use different origin conventions:
22 * the world file identifies the centre of the upper-left pixel, while the
23 * GeoTransform identifies its outer corner. Keeping both values derived from
24 * the same map grid prevents GIS readers from shifting the image by half a
25 * pixel. Sidecars are published without overwriting prior work so a failed run
26 * cannot silently replace metadata belonging to another map.
27 */
28#ifndef PANGEA_MAP_WRITER_H
29#define PANGEA_MAP_WRITER_H
30
31#include "map_projection.h"
32#include "application_runtime.h"
33
34namespace pangea_survey {
35/**
36 * @brief Create the georeferencing files paired with a rendered map image.
37 * @details This writer owns only the .jgw and .aux.xml sidecars; JPEG encoding
38 * and publication are handled separately. The sidecars describe the requested
39 * grid, not surveyed ground truth, and are not a claim of orthorectified relief.
40 */
41class MapWriter {
42 /** @brief Write and publish one complete georeferencing sidecar.
43 * @param path Final sidecar path in the caller's working directory.
44 * @param text Serialized world-file or XML content.
45 * @throws std::runtime_error On an existing path or write/publication failure.
46 * @details Stage under a sibling name before renaming. The caller
47 * coordinates exclusive access and any cleanup of the sidecar pair. */
48 static void writeMetadata(const fs::path& path, const std::string& text) {
49 const fs::path temporary = path.string() + ".partial";
50 if (fs::exists(path) || fs::exists(temporary))
51 throw std::runtime_error("Refusing to overwrite map metadata: " + path.u8string());
52 try {
53 // Rename exposes only a complete sidecar; the caller still owns pair-level cleanup.
54 std::ofstream output(temporary, std::ios::binary);
55 output << text;
56 output.close();
57 if (!output) throw std::runtime_error("Cannot write map metadata: " + path.u8string());
58 std::error_code ec;
59 fs::rename(temporary, path, ec);
60 if (ec) throw std::runtime_error("Finalize map metadata failed: " + ec.message());
61 } catch (...) {
62 std::error_code error;
63 fs::remove(temporary, error);
64 if (error) std::cerr << "WARNING: Cannot remove partial map metadata: " << error.message() << '\n';
65 throw;
66 }
67 }
68public:
69 /**
70 * @brief Return the two sidecar paths associated with a map image.
71 * @param[in] path Image path whose extension is replaced for the world file.
72 * @return World-file path followed by the PAM XML path.
73 */
74 static std::array<fs::path, 2> mapFiles(const fs::path& path) {
75 auto world = path;
76 world.replace_extension(".jgw");
77 return {world, fs::path(path.string() + ".aux.xml")};
78 }
79
80 /**
81 * @brief Publish a world file and GIS projection metadata for one map image.
82 * @param[in] path Destination image path used to derive both sidecar names.
83 * @param[in] map Projected map centre, pixel size, heading, and EPSG code.
84 * @param[in] width Image width in pixels; used to place the grid origin.
85 * @param[in] height Image height in pixels; used to place the grid origin.
86 * @param[in] orthorectified Whether the PAM metadata may describe surface
87 * correction; false deliberately labels the output as reference-plane only.
88 * @throws std::runtime_error If either sidecar already exists or cannot be
89 * written. If the second file fails, the first is removed to avoid leaving
90 * a misleading half-pair.
91 *
92 * The world-file origin is the upper-left pixel centre. The PAM
93 * GeoTransform starts at the upper-left pixel corner, as required by GDAL;
94 * these values differ by half a pixel by design.
95 */
96 static void writeMap(const fs::path& path, const pangea_survey::MapTile& map, int width, int height,
97 bool orthorectified = false) {
98 const auto paths = mapFiles(path);
99 std::ostringstream world, xml;
100 world.imbue(std::locale::classic());
101 xml.imbue(std::locale::classic());
102 world << std::setprecision(15) << map.pixelSize << "\n0\n0\n" << -map.pixelSize << '\n'
103 << map.east - (width - 1) * map.pixelSize / 2 << '\n'
104 << map.north + (height - 1) * map.pixelSize / 2 << '\n';
105 const int zone = map.epsg % 100;
106 xml << std::setprecision(15)
107 << "<PAMDataset><SRS>PROJCS[&quot;WGS 84 / UTM zone " << zone
108 << (map.epsg < 32700 ? "N" : "S")
109 << "&quot;,GEOGCS[&quot;WGS 84&quot;,DATUM[&quot;WGS_1984&quot;,SPHEROID[&quot;WGS 84&quot;,6378137,298.257223563]],"
110 "PRIMEM[&quot;Greenwich&quot;,0],UNIT[&quot;degree&quot;,0.0174532925199433]],"
111 "PROJECTION[&quot;Transverse_Mercator&quot;],PARAMETER[&quot;latitude_of_origin&quot;,0],"
112 "PARAMETER[&quot;central_meridian&quot;," << zone * 6 - 183
113 << "],PARAMETER[&quot;scale_factor&quot;,0.9996],PARAMETER[&quot;false_easting&quot;,500000],"
114 "PARAMETER[&quot;false_northing&quot;," << (map.epsg < 32700 ? 0 : 10000000)
115 << "],UNIT[&quot;metre&quot;,1],AUTHORITY[&quot;EPSG&quot;,&quot;" << map.epsg
116 << "&quot;]]</SRS><GeoTransform>"
117 << map.east - width * map.pixelSize / 2 << ',' << map.pixelSize << ",0,"
118 << map.north + height * map.pixelSize / 2 << ",0," << -map.pixelSize
119 << "</GeoTransform><Metadata><MDI key=\"GEOREFERENCING_MODEL\">"
120 << (orthorectified ? "Multi-view surface orthorectification; see geometry metadata for coverage classes" :
121 "Reference-plane georeferencing; not a true orthophoto")
122 << "</MDI></Metadata></PAMDataset>\n";
123 writeMetadata(paths[0], world.str());
124 try { writeMetadata(paths[1], xml.str()); }
125 catch (...) {
126 std::error_code error;
127 fs::remove(paths[0], error);
128 if (error) std::cerr << "WARNING: Cannot remove incomplete map metadata: " << error.message() << '\n';
129 throw;
130 }
131 }
132};
133}
134#endif
Shared logging and operating-system checks for the survey executable.
Create the georeferencing files paired with a rendered map image.
Definition map_writer.h:41
static std::array< fs::path, 2 > mapFiles(const fs::path &path)
Return the two sidecar paths associated with a map image.
Definition map_writer.h:74
static void writeMetadata(const fs::path &path, const std::string &text)
Write and publish one complete georeferencing sidecar.
Definition map_writer.h:48
static void writeMap(const fs::path &path, const pangea_survey::MapTile &map, int width, int height, bool orthorectified=false)
Publish a world file and GIS projection metadata for one map image.
Definition map_writer.h:96
struct jpeg_error_mgr error
Definition lwir_image.c:60
Convert between WGS-84 coordinates and one local UTM grid.
static FILE * output
Definition pose_log.c:77
Centre and pixel geometry for a projected image tile.