EquirectProjection.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
// Equirectangular (360 panorama) <-> perspective (pinhole) reprojection.
//
// The codebase has no spherical-image geometry outside the VTK viewer, which
// only *samples* an equirect texture onto a sphere for display
// (apps/rux/src/view/panorama_handler.cpp). This utility provides the CPU
// geometry shared by two features:
//   * SAM3-on-360  : slice an equirect into pinhole tiles the segmenter can
//                    consume at its native resolution, then stitch the per-tile
//                    label maps back into one equirect label image.
//   * 360 alignment: render a virtual pinhole view of the panorama toward a
//                    nearby sensor frame so it can be ORB-matched, and map
//                    slice pixels back to panorama bearings for pose resection.
//
// Panorama frame convention (right-handed, camera-style y-down):
//   longitude theta in [-pi, pi]  -> column u in [0, W)
//   latitude  phi   in [-pi/2,pi/2] -> row    v in [0, H)   (v=0 = north pole)
//   bearing d(theta,phi) = ( sin(theta) cos(phi),
//                           -sin(phi),
//                            cos(theta) cos(phi) )
// so d(0,0) = +Z (forward), +X points right (theta>0), +Y points down. This is
// the same optical convention (x right, y down, z forward) the rest of the
// pipeline uses for sensor-frame cameras, so a resected panorama pose composes
// directly with sensor-frame poses.
 
#pragma once
 
#include <Eigen/Core>
#include <opencv2/core.hpp>
 
#include <vector>
 
namespace reusex::geometry {

struct PerspectiveView {
  cv::Mat image;     
  Eigen::Matrix3d K; 
  Eigen::Matrix3d
      R_pano_from_view;   
  double fov_deg = 90.0;  
  double yaw_deg = 0.0;   
  double pitch_deg = 0.0; 
};

Eigen::Vector3d pixel_to_bearing(const cv::Size &equirect, double u, double v);

Eigen::Vector2d bearing_to_pixel(const cv::Size &equirect,
                                 const Eigen::Vector3d &bearing);

PerspectiveView extract_perspective(const cv::Mat &equirect, double yaw_deg,
                                    double pitch_deg, double fov_deg, int out_w,
                                    int out_h, int interp = 1 /*INTER_LINEAR*/);

PerspectiveView extract_perspective(const cv::Mat &equirect,
                                    const Eigen::Matrix3d &R_pano_from_view,
                                    const Eigen::Matrix3d &K, int out_w,
                                    int out_h, int interp = 1);

std::vector<PerspectiveView> cube_faces(const cv::Mat &equirect, int face_size,
                                        int interp = 1);

std::vector<PerspectiveView> overlapping_views(const cv::Mat &equirect,
                                               int n_yaw, double fov_deg,
                                               int tile, int interp = 1);

cv::Mat stitch_labels_to_equirect(const cv::Size &out,
                                  const std::vector<PerspectiveView> &views,
                                  const std::vector<cv::Mat> &tile_labels);
 
} // namespace reusex::geometry