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
image_framing.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 image_framing.h
20 * @brief Crop, resample, and rotate BGRA images into the requested camera frame.
21 * @details Framing is shared by rendering and metadata generation: returning
22 * the exact crop geometry lets callers derive matching intrinsics. A single
23 * scale on both axes preserves aspect ratio, while reusable buffers avoid a
24 * second full image allocation when the input can be viewed directly.
25 */
26#ifndef PANGEA_IMAGE_FRAMING_H
27#define PANGEA_IMAGE_FRAMING_H
28
29#include <algorithm>
30#include <cmath>
31#include <cstdint>
32#include <cstring>
33#if defined(__SSE2__)
34#include <emmintrin.h>
35#elif defined(__aarch64__)
36#include <arm_neon.h>
37#endif
38#include <array>
39#include <stdexcept>
40#include <vector>
41
42namespace pangea_survey {
43/**
44 * @brief Validate encoded-image dimensions before allocating pixel buffers.
45 * @param[in] width Image width in pixels.
46 * @param[in] height Image height in pixels.
47 * @throws std::runtime_error If dimensions exceed per-axis or total-pixel bounds.
48 */
49inline void validateJpegSize(int width, int height) {
50 if (width < 1 || height < 1 || width > 16384 || height > 16384 ||
51 static_cast<std::int64_t>(width) * height > 64 * 1024 * 1024)
52 throw std::runtime_error("JPEG width/height must be integers 1-16384, with at most 64 megapixels");
53}
54
55
56/**
57 * @brief Produce a bounded crop/resample view over a source BGRA image.
58 * @details The view may borrow the source pixels for an exact crop or point to
59 * this object's reusable output buffer after resampling/rotation. In the latter
60 * case, the bytes remain valid only until the next call to @ref apply.
61 */
63 struct Sample {
65 float weight;
66 };
67 int sourceWidth_ = 0, sourceHeight_ = 0, width_ = 0, height_ = 0, inset_ = 0;
68 double rotationBound_ = 0;
69 std::vector<Sample> columns_, rows_;
70 std::vector<unsigned char> buffer_;
71 std::vector<float> horizontal_[2];
72
73#if defined(__SSE2__)
74 using Channels = __m128;
75 static Channels splat(float value) { return _mm_set1_ps(value); }
76 static Channels sum(Channels first, Channels second) { return _mm_add_ps(first, second); }
77 static Channels difference(Channels first, Channels second) { return _mm_sub_ps(first, second); }
78 static Channels product(Channels first, Channels second) { return _mm_mul_ps(first, second); }
79 static Channels load(const float* values) { return _mm_loadu_ps(values); }
80 static void store(float* target, Channels values) { _mm_storeu_ps(target, values); }
81 static Channels channels(const unsigned char* pixel) {
82 std::uint32_t packed = 0;
83 for (std::size_t channel = 0; channel < sizeof(packed); ++channel)
84 packed |= static_cast<std::uint32_t>(pixel[channel]) << (channel * 8);
85 const auto bytes = _mm_cvtsi32_si128(static_cast<int>(packed));
86 const auto zero = _mm_setzero_si128();
87 return _mm_cvtepi32_ps(_mm_unpacklo_epi16(_mm_unpacklo_epi8(bytes, zero), zero));
88 }
89 template<typename SamplePixel>
90 static void writeRow(unsigned char* destination, int width, SamplePixel&& sample) {
91 const auto rounding = _mm_set1_ps(0.5f);
92 int x = 0;
93 for (; x + 1 < width; x += 2) {
94 const auto first = _mm_cvttps_epi32(_mm_add_ps(sample(x), rounding));
95 const auto second = _mm_cvttps_epi32(_mm_add_ps(sample(x + 1), rounding));
96 const auto words = _mm_packs_epi32(first, second);
97 const auto bytes = _mm_packus_epi16(words, words);
98 const auto packed = static_cast<std::uint64_t>(_mm_cvtsi128_si64(bytes));
99 for (std::size_t channel = 0; channel < sizeof(packed); ++channel)
100 destination[x * 4 + channel] = static_cast<unsigned char>(packed >> (channel * 8));
101 }
102 if (x < width) {
103 const auto value = _mm_cvttps_epi32(_mm_add_ps(sample(x), rounding));
104 const auto words = _mm_packs_epi32(value, value);
105 const auto packed = static_cast<std::uint32_t>(_mm_cvtsi128_si32(_mm_packus_epi16(words, words)));
106 for (std::size_t channel = 0; channel < sizeof(packed); ++channel)
107 destination[x * 4 + channel] = static_cast<unsigned char>(packed >> (channel * 8));
108 }
109 }
110#else
111#if defined(__aarch64__)
112 using Channels = float32x4_t;
113 /** @brief Broadcast a scalar interpolation weight to all BGRA lanes.
114 * @param value Weight to broadcast.
115 * @return Four identical lanes. */
116 static Channels splat(float value) { return vdupq_n_f32(value); }
117 /** @brief Add independent BGRA lanes without mixing channels.
118 * @param first Left operand.
119 * @param second Right operand.
120 * @return Lane-wise sum. */
121 static Channels sum(Channels first, Channels second) { return vaddq_f32(first, second); }
122 /** @brief Form independent BGRA deltas for interpolation.
123 * @param first Reference value in each lane.
124 * @param second Value subtracted from each lane.
125 * @return Lane-wise difference. */
126 static Channels difference(Channels first, Channels second) { return vsubq_f32(first, second); }
127 /** @brief Multiply each BGRA lane by its corresponding weight.
128 * @param first Channel values or weights.
129 * @param second Matching weights or channel values.
130 * @return Lane-wise product. */
131 static Channels product(Channels first, Channels second) { return vmulq_f32(first, second); }
132 /** @brief Load interpolation values in BGRA order.
133 * @param values Four readable floats.
134 * @return Loaded channels. */
135 static Channels load(const float* values) { return vld1q_f32(values); }
136 /** @brief Store floating-point channels before narrowing to bytes.
137 * @param[out] target Four writable floats.
138 * @param values Channel vector in BGRA order. */
139 static void store(float* target, Channels values) { vst1q_f32(target, values); }
140#else
141 using Channels = std::array<float, 4>;
142 /** @brief Broadcast a scalar to all four portable BGRA lanes.
143 * @param value Weight to broadcast.
144 * @return Four identical lanes. */
145 static Channels splat(float value) { return {value, value, value, value}; }
146 /** @brief Accumulate channel values without mixing color and alpha.
147 * @param first Left operand.
148 * @param second Right operand.
149 * @return Lane-wise sum. */
150 static Channels sum(Channels first, Channels second) {
151 for (int channel = 0; channel < 4; ++channel) first[channel] += second[channel];
152 return first;
153 }
154 /** @brief Form independent channel deltas for interpolation.
155 * @param first Reference values.
156 * @param second Values to subtract.
157 * @return Lane-wise difference. */
158 static Channels difference(Channels first, Channels second) {
159 for (int channel = 0; channel < 4; ++channel) first[channel] -= second[channel];
160 return first;
161 }
162 /** @brief Multiply each channel by its corresponding weight.
163 * @param first First lane vector.
164 * @param second Second lane vector.
165 * @return Lane-wise product. */
166 static Channels product(Channels first, Channels second) {
167 for (int channel = 0; channel < 4; ++channel) first[channel] *= second[channel];
168 return first;
169 }
170 /** @brief Load four floating-point channel values in BGRA order.
171 * @param values Four readable floats.
172 * @return Loaded channels. */
173 static Channels load(const float* values) { return {values[0], values[1], values[2], values[3]}; }
174 /** @brief Store channels in the order expected by byte conversion.
175 * @param[out] target Four writable floats.
176 * @param values Channel values in BGRA order. */
177 static void store(float* target, Channels values) {
178 for (int channel = 0; channel < 4; ++channel) target[channel] = values[channel];
179 }
180#endif
181 /** @brief Widen a packed BGRA pixel for floating-point interpolation.
182 * @param pixel Four readable bytes in BGRA order.
183 * @return The same channel values without byte-range arithmetic. */
184 static Channels channels(const unsigned char* pixel) {
185 const float values[] = {float(pixel[0]), float(pixel[1]), float(pixel[2]), float(pixel[3])};
186 return load(values);
187 }
188 /** @brief Write one sampled row to the byte raster.
189 * @tparam SamplePixel Callable yielding four lanes for an output column.
190 * @param[out] destination Row storage of at least four bytes per pixel.
191 * @param width Output column count.
192 * @param sample Interpolating sampler.
193 * @details Round and clamp at the byte boundary, not during interpolation. */
194 template<typename SamplePixel>
195 static void writeRow(unsigned char* destination, int width, SamplePixel&& sample) {
196 for (int column = 0; column < width; ++column) {
197 float values[4]; store(values, sample(column));
198 for (int channel = 0; channel < 4; ++channel)
199 destination[column * 4 + channel] = static_cast<unsigned char>(
200 std::clamp(static_cast<int>(values[channel] + .5f), 0, 255));
201 }
202 }
203#endif
204 /** @brief Precompute bilinear indices and fractions along one output axis.
205 * @param[out] result One entry per output sample.
206 * @param count Output samples on the axis.
207 * @param sourceSize Positive source extent in pixels.
208 * @param offset Crop offset in source pixels.
209 * @param scale Source pixels per output sample.
210 * @details Map pixel centers and clamp before computing neighbors.
211 * Reusing these entries avoids repeated coordinate arithmetic in each row. */
212 static void samples(std::vector<Sample>& result, int count, int sourceSize,
213 double offset, double scale) {
214 result.resize(count);
215 for (int i = 0; i < count; ++i) {
216 const double position = std::clamp(offset + (i + 0.5) * scale - 0.5,
217 0.0, static_cast<double>(sourceSize - 1));
218 const int first = static_cast<int>(position);
219 result[i] = {first, std::min(first + 1, sourceSize - 1),
220 static_cast<float>(position - first)};
221 }
222 }
223public:
224 /** @brief Source-space crop and uniform scale needed for an output frame. */
225 struct Crop {
226 double x, y, width, height, scale;
227 };
228 /**
229 * @brief Fit an output aspect ratio inside source bounds and rotation margin.
230 * @param[in] sourceWidth Source image width in pixels.
231 * @param[in] sourceHeight Source image height in pixels.
232 * @param[in] width Requested output width in pixels.
233 * @param[in] height Requested output height in pixels.
234 * @param[in] inset Minimum source-edge margin in pixels.
235 * @param[in] rotationBoundDegrees Maximum absolute rotation to accommodate.
236 * @return Centered crop rectangle and the common scale for both axes.
237 * @throws std::runtime_error If dimensions, margin, or rotation are invalid.
238 */
239 static Crop crop(int sourceWidth, int sourceHeight, int width, int height, int inset = 0,
240 double rotationBoundDegrees = 0) {
241 validateJpegSize(width, height);
242 if (sourceWidth < 1 || sourceHeight < 1 || sourceWidth > 16384 || sourceHeight > 16384)
243 throw std::runtime_error("Invalid source dimensions for JPEG framing");
244 if (inset < 0 || sourceWidth <= 2 * inset || sourceHeight <= 2 * inset)
245 throw std::runtime_error("Capture inset leaves no usable image");
246 if (!std::isfinite(rotationBoundDegrees) || std::abs(rotationBoundDegrees) > 45)
247 throw std::runtime_error("Image framing rotation must be within +/-45 degrees");
248 const double angle = std::abs(rotationBoundDegrees) * 0.01745329251994329577;
249 const double c = std::cos(angle), s = std::sin(angle);
250 const double scale = std::min((sourceWidth - 2.0 * inset) / (width * c + height * s),
251 (sourceHeight - 2.0 * inset) / (height * c + width * s));
252 const double cropWidth = width * scale, cropHeight = height * scale;
253 return {(sourceWidth - cropWidth) / 2, (sourceHeight - cropHeight) / 2,
254 cropWidth, cropHeight, scale};
255 }
256 struct View {
257 const unsigned char* bgra;
260 };
261
262 /**
263 * @brief Frame BGRA pixels into a crop, resampled image, or rotated image.
264 * @param[in] bgra Borrowed source pixel buffer.
265 * @param[in] sourceWidth Source width in pixels.
266 * @param[in] sourceHeight Source height in pixels.
267 * @param[in] stride Source row stride in bytes.
268 * @param[in] width Requested output width in pixels.
269 * @param[in] height Requested output height in pixels.
270 * @param[in] inset Excluded border in source pixels.
271 * @param[in] rotationDegrees Applied rotation in the renderer's image coordinates.
272 * @param[in] rotationBoundDegrees Maximum rotation used when selecting a safe crop.
273 * @return BGRA view and the source crop represented by its pixels.
274 * @throws std::runtime_error If input bounds or the rotated footprint are invalid.
275 * @note A returned pointer to internal storage is invalidated by the next call.
276 */
277 View apply(const unsigned char* bgra, int sourceWidth, int sourceHeight, int stride,
278 int width, int height, int inset = 0, double rotationDegrees = 0,
279 double rotationBoundDegrees = 0) {
280 if (!std::isfinite(rotationDegrees))
281 throw std::runtime_error("Nonfinite image framing rotation");
282 const auto bounds = crop(sourceWidth, sourceHeight, width, height, inset,
283 std::max(std::abs(rotationDegrees), std::abs(rotationBoundDegrees)));
284 if (!bgra || sourceWidth < 1 || sourceHeight < 1 ||
285 sourceWidth > 16384 || sourceHeight > 16384 || stride < sourceWidth * 4)
286 throw std::runtime_error("Invalid source BGRA dimensions/stride for JPEG framing");
287 // A single sampling scale on both axes prevents distortion, even for fractional crop edges.
288 const double scale = bounds.scale, cropWidth = bounds.width, cropHeight = bounds.height;
289 const double cropX = bounds.x, cropY = bounds.y;
290 if (rotationDegrees != 0) {
291 buffer_.resize(static_cast<std::size_t>(width) * height * 4);
292 const double angle = rotationDegrees * 0.01745329251994329577;
293 const double c = std::cos(angle), s = std::sin(angle);
294 for (int y = 0; y < height; ++y) {
295 const double dy = (y + 0.5 - height / 2.0) * scale;
296 writeRow(buffer_.data() + static_cast<std::size_t>(y) * width * 4, width, [&](int x) {
297 const double dx = (x + 0.5 - width / 2.0) * scale;
298 const double px = sourceWidth / 2.0 - 0.5 + c * dx - s * dy;
299 const double py = sourceHeight / 2.0 - 0.5 + s * dx + c * dy;
300 const int ix = static_cast<int>(std::floor(px)), iy = static_cast<int>(std::floor(py));
301 if (ix < 0 || iy < 0 || ix + 1 >= sourceWidth || iy + 1 >= sourceHeight)
302 throw std::runtime_error("Rotated image footprint lies outside capture pixels");
303 const auto* top = bgra + static_cast<std::size_t>(iy) * stride + ix * 4;
304 const auto* bottom = top + stride;
305 const auto hx = splat(static_cast<float>(px - ix));
306 const auto vy = splat(static_cast<float>(py - iy));
307 const auto ta = channels(top), tb = channels(top + 4);
308 const auto ba = channels(bottom), bb = channels(bottom + 4);
309 const auto upper = sum(ta, product(difference(tb, ta), hx));
310 const auto lower = sum(ba, product(difference(bb, ba), hx));
311 return sum(upper, product(difference(lower, upper), vy));
312 });
313 }
314 return {buffer_.data(), width, height, width * 4, cropX, cropY, cropWidth, cropHeight};
315 }
316 if (scale == 1 && std::floor(cropX) == cropX && std::floor(cropY) == cropY)
317 return {bgra + static_cast<std::size_t>(cropY) * stride + static_cast<std::size_t>(cropX) * 4,
318 width, height, stride, cropX, cropY, cropWidth, cropHeight};
319 if (sourceWidth_ != sourceWidth || sourceHeight_ != sourceHeight ||
320 width_ != width || height_ != height || inset_ != inset || rotationBound_ != rotationBoundDegrees) {
321 samples(columns_, width, sourceWidth, cropX, scale);
322 samples(rows_, height, sourceHeight, cropY, scale);
323 buffer_.resize(static_cast<std::size_t>(width) * height * 4);
324 sourceWidth_ = sourceWidth;
325 sourceHeight_ = sourceHeight;
326 width_ = width;
327 height_ = height;
328 inset_ = inset;
329 rotationBound_ = rotationBoundDegrees;
330 }
331 if (scale < 1) {
332 horizontal_[0].resize(static_cast<std::size_t>(width) * 4);
333 horizontal_[1].resize(static_cast<std::size_t>(width) * 4);
334 // Cache only within this image; neighboring output rows reuse source rows when upscaling.
335 int cached[2] = {-1, -1};
336 const auto horizontalRow = [&](int row, int protectedSlot) {
337 for (int slot = 0; slot < 2; ++slot)
338 if (cached[slot] == row) return slot;
339 const int slot = protectedSlot == 0 ? 1 : 0;
340 const auto* source = bgra + static_cast<std::size_t>(row) * stride;
341 auto* destination = horizontal_[slot].data();
342 for (int x = 0; x < width; ++x) {
343 const auto& column = columns_[x];
344 const auto a = channels(source + column.first * 4);
345 const auto b = channels(source + column.second * 4);
346 store(destination + x * 4,
347 sum(a, product(difference(b, a), splat(column.weight))));
348 }
349 cached[slot] = row;
350 return slot;
351 };
352 for (int y = 0; y < height; ++y) {
353 const auto& row = rows_[y];
354 const int first = horizontalRow(row.first, -1);
355 const int second = horizontalRow(row.second, first);
356 const auto* top = horizontal_[first].data();
357 const auto* bottom = horizontal_[second].data();
358 auto* destination = buffer_.data() + static_cast<std::size_t>(y) * width * 4;
359 const auto vertical = splat(row.weight);
360 writeRow(destination, width, [&](int x) {
361 const auto upper = load(top + x * 4), lower = load(bottom + x * 4);
362 return sum(upper, product(difference(lower, upper), vertical));
363 });
364 }
365 return {buffer_.data(), width, height, width * 4, cropX, cropY, cropWidth, cropHeight};
366 }
367 for (int y = 0; y < height; ++y) {
368 const auto& row = rows_[y];
369 const auto* top = bgra + static_cast<std::size_t>(row.first) * stride;
370 const auto* bottom = bgra + static_cast<std::size_t>(row.second) * stride;
371 auto* destination = buffer_.data() + static_cast<std::size_t>(y) * width * 4;
372 const auto vertical = splat(row.weight);
373 writeRow(destination, width, [&](int x) {
374 const auto& column = columns_[x];
375 const auto horizontal = splat(column.weight);
376 const auto a = channels(top + column.first * 4);
377 const auto b = channels(top + column.second * 4);
378 const auto d = channels(bottom + column.first * 4);
379 const auto e = channels(bottom + column.second * 4);
380 const auto upper = sum(a, product(difference(b, a), horizontal));
381 const auto lower = sum(d, product(difference(e, d), horizontal));
382 return sum(upper, product(difference(lower, upper), vertical));
383 });
384 }
385 return {buffer_.data(), width, height, width * 4, cropX, cropY, cropWidth, cropHeight};
386 }
387};
388}
389#endif
uint8_t bytes[CHDK_CONTROL_REPLY_SIZE]
Definition chdk_pipe.c:144
Produce a bounded crop/resample view over a source BGRA image.
std::vector< Sample > rows_
static Channels load(const float *values)
Load four floating-point channel values in BGRA order.
static Channels sum(Channels first, Channels second)
Accumulate channel values without mixing color and alpha.
View apply(const unsigned char *bgra, int sourceWidth, int sourceHeight, int stride, int width, int height, int inset=0, double rotationDegrees=0, double rotationBoundDegrees=0)
Frame BGRA pixels into a crop, resampled image, or rotated image.
static Channels product(Channels first, Channels second)
Multiply each channel by its corresponding weight.
std::vector< Sample > columns_
static void writeRow(unsigned char *destination, int width, SamplePixel &&sample)
Write one sampled row to the byte raster.
std::array< float, 4 > Channels
std::vector< unsigned char > buffer_
static Channels splat(float value)
Broadcast a scalar to all four portable BGRA lanes.
static Channels difference(Channels first, Channels second)
Form independent channel deltas for interpolation.
static Channels channels(const unsigned char *pixel)
Widen a packed BGRA pixel for floating-point interpolation.
static void samples(std::vector< Sample > &result, int count, int sourceSize, double offset, double scale)
Precompute bilinear indices and fractions along one output axis.
std::vector< float > horizontal_[2]
static Crop crop(int sourceWidth, int sourceHeight, int width, int height, int inset=0, double rotationBoundDegrees=0)
Fit an output aspect ratio inside source bounds and rotation margin.
static void store(float *target, Channels values)
Store channels in the order expected by byte conversion.
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 struct ear_sample samples[EAR_MAX_SAMPLES]
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
void validateJpegSize(int width, int height)
Validate encoded-image dimensions before allocating pixel buffers.
static size_t count
Definition pose_log.c:79
Source-space crop and uniform scale needed for an output frame.
struct usher_control_result result
Definition usher.c:377