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_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 camera_projection.h
20 * @brief Map calibrated camera pixels to a local flat ground plane.
21 * @details Body and mount rotations are composed before the pinhole ray model.
22 * The cached inverse is reused across output pixels; invalid or horizon-facing
23 * rays are rejected rather than extrapolated into plausible-looking map points.
24 */
25#ifndef PANGEA_CAMERA_PROJECTION_H
26#define PANGEA_CAMERA_PROJECTION_H
27
28#include <opencv2/core.hpp>
29#include <cmath>
30#include <stdexcept>
31
32namespace pangea_survey {
33/**
34 * @brief Compose body attitude into the local camera-ray coordinate frame.
35 * @param[in] roll Body roll in degrees.
36 * @param[in] pitch Body pitch in degrees.
37 * @param[in] yaw Body yaw in degrees.
38 * @return Rotation matrix for the supplied Euler angles.
39 */
40inline cv::Matx33d cameraRotation(double roll, double pitch, double yaw) {
41 constexpr double radians = 3.14159265358979323846 / 180;
42 roll *= radians; pitch *= radians; yaw *= radians;
43 const cv::Matx33d aroundRoll(1, 0, 0, 0, std::cos(roll), -std::sin(roll), 0, std::sin(roll), std::cos(roll));
44 const cv::Matx33d aroundPitch(std::cos(pitch), 0, std::sin(pitch), 0, 1, 0, -std::sin(pitch), 0, std::cos(pitch));
45 const cv::Matx33d aroundYaw(std::cos(yaw), -std::sin(yaw), 0, std::sin(yaw), std::cos(yaw), 0, 0, 0, 1);
46 return aroundYaw * aroundPitch * aroundRoll;
47}
48
50 cv::Matx33d rays_, inverseRays_;
51public:
52 /**
53 * @brief Cache forward and inverse pinhole transforms for one camera pose.
54 * @param[in] fx Horizontal focal length in pixels.
55 * @param[in] fy Vertical focal length in pixels.
56 * @param[in] cx Principal-point x coordinate in pixels.
57 * @param[in] cy Principal-point y coordinate in pixels.
58 * @param[in] roll Body roll in degrees.
59 * @param[in] pitch Body pitch in degrees.
60 * @param[in] yaw Body yaw in degrees.
61 * @param[in] mountRoll Camera mount roll in degrees.
62 * @param[in] mountPitch Camera mount pitch in degrees.
63 * @param[in] mountYaw Camera mount yaw in degrees.
64 * @throws std::runtime_error If intrinsics or angles are nonfinite, or focal length is invalid.
65 */
66 CameraPlane(double fx, double fy, double cx, double cy, double roll, double pitch, double yaw,
67 double mountRoll = 0, double mountPitch = 0, double mountYaw = 0) {
68 for (const double value : {fx, fy, cx, cy, roll, pitch, yaw, mountRoll, mountPitch, mountYaw})
69 if (!std::isfinite(value)) throw std::runtime_error("Nonfinite camera geometry");
70 if (fx <= 0 || fy <= 0) throw std::runtime_error("Invalid camera focal length");
71 rays_ = cameraRotation(roll, pitch, yaw) * cameraRotation(mountRoll, mountPitch, mountYaw) *
72 cv::Matx33d(0, -1 / fy, cy / fy, 1 / fx, 0, -cx / fx, 0, 0, 1);
73 inverseRays_ = rays_.inv();
74 }
75
76 /**
77 * @brief Intersect one delivered-image pixel ray with a horizontal ground plane.
78 * @param[in] column Image column in pixels.
79 * @param[in] row Image row in pixels.
80 * @param[in] height Camera-to-plane distance in metres.
81 * @return Local ground point in metres.
82 * @throws std::runtime_error If the ray is invalid or too close to the horizon.
83 */
84 cv::Point2d ground(double column, double row, double height) const {
85 const auto ray = rays_ * cv::Vec3d(column, row, 1);
86 const double length = cv::norm(ray);
87 if (!std::isfinite(height) || height <= 5 || !std::isfinite(length) || length <= 0 || ray[2] / length < .2)
88 throw std::runtime_error("Camera footprint reaches horizon or invalid ground plane");
89 return {height * ray[1] / ray[2], height * ray[0] / ray[2]};
90 }
91
92 /**
93 * @brief Return a homography from local ground coordinates to image pixels.
94 * @param[in] height Camera-to-plane distance in metres.
95 * @return 3x3 ground-to-pixel projective transform.
96 * @throws std::runtime_error If the plane height is invalid.
97 */
98 cv::Matx33d groundToPixel(double height) const {
99 if (!std::isfinite(height) || height <= 5) throw std::runtime_error("Invalid camera ground distance");
100 return inverseRays_ * cv::Matx33d(0, 1, 0, 1, 0, 0, 0, 0, height);
101 }
102
103 /**
104 * @brief Shift the principal point after removing equal borders from the image.
105 * @param[in] inset Number of pixels removed from each edge.
106 */
107 void crop(int inset) {
108 rays_ = rays_ * cv::Matx33d(1, 0, inset, 0, 1, inset, 0, 0, 1);
109 inverseRays_ = cv::Matx33d(1, 0, -inset, 0, 1, -inset, 0, 0, 1) * inverseRays_;
110 }
111};
112}
113#endif
void crop(int inset)
Shift the principal point after removing equal borders from the image.
cv::Matx33d groundToPixel(double height) const
Return a homography from local ground coordinates to image pixels.
CameraPlane(double fx, double fy, double cx, double cy, double roll, double pitch, double yaw, double mountRoll=0, double mountPitch=0, double mountYaw=0)
Cache forward and inverse pinhole transforms for one camera pose.
cv::Point2d ground(double column, double row, double height) const
Intersect one delivered-image pixel ray with a horizontal ground plane.
uint8_t row[LWIR_MAX_WIDTH *3U]
Definition lwir_image.c:63
cv::Matx33d cameraRotation(double roll, double pitch, double yaw)
Compose body attitude into the local camera-ray coordinate frame.