PanoramaAlignment.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
// Content-based alignment of 360 panoramas to the scan.
//
// A panorama is imported and placed on the trajectory purely by nearest EXIF
// timestamp (`rux import 360`), inheriting the matched sensor frame's pose.
// That is only as good as the clock sync and gives the panorama no independent
// orientation. This module refines the panorama's 6-DoF pose from image
// content:
//
//   1. render virtual pinhole slices of the equirect
//   (geometry/EquirectProjection)
//   2. ORB-match each slice against nearby sensor frames — the SAME
//   license-clean
//      OpenCV ORB + Lowe-ratio front-end used by LoopClosure
//   3. lift frame matches to metric 3D via the frame's stored depth + pose
//   4. resect the panorama pose per slice with solvePnPRansac (each slice is a
//      true pinhole with known K and known slice->panorama rotation), then
//      refine over all slices' inliers in panorama-bearing space
//
// The refined pose is a panorama-optical->world transform in the SAME
// convention as sensor_frame_pose, so it drops straight into the viewer /
// exporters and (as a follow-up, issue #236) into the pose graph as loop
// constraints.
 
#pragma once
 
#include <Eigen/Core>
#include <Eigen/Geometry>
 
#include <array>
#include <string>
 
namespace reusex {
class ProjectDB;
}
 
namespace reusex::geometry {

struct PanoramaAlignmentOptions {
  // --- candidate sensor frames -------------------------------------------
  int candidate_window = 25;
  int max_candidates = 20;
 
  // --- panorama slicing (geometry/EquirectProjection) --------------------
  int n_yaw = 8;         
  double fov_deg = 90.0; 
  int slice = 1008;      
 
  // --- ORB front-end (mirrors LoopClosureOptions) ------------------------
  int max_features = 3000;  
  float ratio_test = 0.85f; 
  float min_depth = 0.3f;   
  float max_depth = 6.0f;
 
  // --- PnP resection -----------------------------------------------------
  int min_slice_correspondences = 6; 
  int min_inliers = 25;              
  float ransac_reproj_px = 5.0f;     
  int ransac_iterations = 500;
  int refine_iterations = 10; 

  double max_correction_m = 5.0;
  unsigned seed = 42;

  std::string debug_dir;
  std::string debug_name;
};

struct PanoramaAlignmentResult {
  int pano_id = -1;
  int seed_node = -1;
  bool aligned = false;
  int inliers = 0;       
  double rms_deg = -1.0; 
  std::array<double, 16> pose = {1, 0, 0, 0, 0, 1, 0, 0,
                                 0, 0, 1, 0, 0, 0, 0, 1};

  double delta_from_seed_m = -1.0;
};

PanoramaAlignmentResult align_panorama(ProjectDB &db, int pano_id,
                                       int seed_node_id,
                                       const PanoramaAlignmentOptions &opt);
 
} // namespace reusex::geometry