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
camera_optics.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 camera_optics.h
20 * @brief Optical profiles and EXIF settings for simulated survey cameras.
21 * @details The Pi AI profile is a deterministic rendering model, not a
22 * measured calibration. Its crop, field of view, distortion, and channel scales
23 * must stay coupled so the saved image and intrinsics describe the same pixels.
24 */
25#ifndef PANGEA_CAMERA_OPTICS_H
26#define PANGEA_CAMERA_OPTICS_H
27
28#include "image_framing.h"
29#include <cstdint>
30#include <string>
31
32namespace pangea_survey {
33/**
34 * @brief User-supplied exposure labels written to simulated-photo EXIF.
35 * @details These values describe the configured emulation only; they are not
36 * sensor readback or evidence of a physical exposure.
37 */
39 double shutterSeconds = 0.001;
40 std::uint16_t iso = 100;
41 std::string hardwareIdentifier;
42
43 /** @brief Reject values that cannot be represented as bounded EXIF metadata. */
44 void validate() const {
46 throw std::runtime_error("camera.shutter_speed_seconds must be between 0.000001 and 30");
47 if (iso == 0)
48 throw std::runtime_error("camera.iso must be an integer between 1 and 65535");
49 if (hardwareIdentifier.size() > 64 || hardwareIdentifier.find_first_not_of(
50 "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._:-") != std::string::npos)
51 throw std::runtime_error("camera.hardware_identifier must contain 1-64 letters, digits, '.', '_', ':' or '-'");
52 }
53};
54
55/** @brief Engineering lens-distortion and lateral colour-scale parameters. */
57 double k1 = -.03, k2 = .005;
58 double blueScale = .9996, redScale = 1.0004;
59};
60/**
61 * @brief Nominal Pi AI Camera geometry used by the simulator rendering profile.
62 * @details Fixed dimensions and focal model define the intrinsic matrix;
63 * overscan keeps rotated/distorted output inside the final frame without
64 * changing those nominal intrinsics.
65 */
66struct PiAiOptics {
67 static constexpr int width = 2028, height = 1520;
68 static constexpr double focalMm = 4.74, aperture = 1.79;
69 static constexpr double clearDayShutterSeconds = 0.0001;
70 static constexpr double sensorWidthMm = 4056 * 0.00155;
71 static constexpr double sensorHeightMm = 3040 * 0.00155;
72 static constexpr double radiansToDegrees = 57.295779513082320877;
73 static constexpr double focalPixels = focalMm / (2 * 0.00155);
74 static constexpr double k1 = -0.03, k2 = 0.005;
75 static constexpr double blueScale = 0.9996, greenScale = 1, redScale = 1.0004;
76 static constexpr double overscan = 1.04;
77 /**
78 * @brief Compute a centered source crop matching the nominal sensor frame.
79 * @param[in] sourceWidth Rendered source width in pixels.
80 * @param[in] sourceHeight Rendered source height in pixels.
81 * @param[in] inset Pixels excluded at each source edge.
82 * @return Crop geometry and its shared horizontal/vertical sampling scale.
83 */
84 static ImageFraming::Crop crop(int sourceWidth, int sourceHeight, int inset) {
85 auto result = ImageFraming::crop(sourceWidth, sourceHeight, width, height, inset);
86 result.scale /= overscan;
87 result.width = width * result.scale;
88 result.height = height * result.scale;
89 result.x = (sourceWidth - result.width) / 2;
90 result.y = (sourceHeight - result.height) / 2;
91 return result;
92 }
93 /** @brief Return nominal vertical field of view in degrees. */
94 static double verticalFov() {
95 return 2 * std::atan(height / (2 * focalPixels)) * radiansToDegrees;
96 }
97 /** @brief Return nominal horizontal field of view in degrees. */
98 static double horizontalFov() {
99 return 2 * std::atan(width / (2 * focalPixels)) * radiansToDegrees;
100 }
101 /**
102 * @brief Find the simulator vertical FOV that yields this captured viewport.
103 * @param[in] sourceWidth Rendered viewport width in pixels.
104 * @param[in] sourceHeight Rendered viewport height in pixels.
105 * @param[in] inset Excluded source-edge pixels used by the crop.
106 * @return Vertical field of view in degrees.
107 * @throws std::runtime_error If the viewport needs an unsupported FOV.
108 */
109 static double viewportFov(int sourceWidth, int sourceHeight, int inset) {
110 const auto framing = crop(sourceWidth, sourceHeight, inset);
111 const double result = 2 * std::atan(sourceHeight / (2 * focalPixels * framing.scale)) * radiansToDegrees;
113 throw std::runtime_error("Viewport/inset cannot represent the Pi AI lens within SDK FOV limits");
114 return result;
115 }
116};
117}
118
119#endif
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.
Crop, resample, and rotate BGRA images into the requested camera frame.
User-supplied exposure labels written to simulated-photo EXIF.
void validate() const
Reject values that cannot be represented as bounded EXIF metadata.
Source-space crop and uniform scale needed for an output frame.
Engineering lens-distortion and lateral colour-scale parameters.
Nominal Pi AI Camera geometry used by the simulator rendering profile.
static ImageFraming::Crop crop(int sourceWidth, int sourceHeight, int inset)
Compute a centered source crop matching the nominal sensor frame.
static constexpr double radiansToDegrees
static constexpr double overscan
static constexpr double k2
static constexpr double k1
static double horizontalFov()
Return nominal horizontal field of view in degrees.
static constexpr double focalPixels
static double viewportFov(int sourceWidth, int sourceHeight, int inset)
Find the simulator vertical FOV that yields this captured viewport.
static double verticalFov()
Return nominal vertical field of view in degrees.
static constexpr double redScale
static constexpr double clearDayShutterSeconds
static constexpr double blueScale
static constexpr double aperture
static constexpr int height
static constexpr double sensorHeightMm
static constexpr double greenScale
static constexpr double focalMm
static constexpr int width
static constexpr double sensorWidthMm
struct usher_control_result result
Definition usher.c:377