PanoramaLoopEdges.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
//
// Issue #236: wide-baseline pose-graph loop edges derived from 360 panoramas.
//
// WHY A PANORAMA IS THE RIGHT SENSOR FOR THIS
// -------------------------------------------
// The plane-landmark back-end (PlaneGraphOptimizer) makes frames that
// co-observe the same wall mutually consistent, but two temporally distant
// views of the same place that share no plane-landmark chain are left
// unconstrained — the "basin problem" of
// docs/research/registration-improvements.md. The ORB front-end in
// LoopClosure.hpp attacks that by matching frame PAIRS, which requires the two
// narrow-FOV frames to overlap each other.
//
// A 360 panorama sees every direction at once, so a SINGLE panorama routinely
// matches frames that do not overlap each other at all — including frames from
// opposite ends of the capture. Each such panorama is therefore a hub that ties
// a whole group of temporally distant frames together.
//
// WHAT MAKES THE EDGE INFORMATIVE (the one thing to get right)
// ------------------------------------------------------------
// `PanoramaAlignment` resects ONE panorama pose in WORLD coordinates, from
// frame keypoints already transformed to world by their (drifted) seed poses.
// An edge built from that pose would be circular: `T_pano_A^-1 · T_pano_B`
// would reproduce `seed(A)^-1 · seed(B)` and carry exactly ZERO
// drift-correction information — it would restate the drift rather than measure
// it.
//
// This module therefore resects the panorama INDEPENDENTLY against each matched
// frame, using that frame's keypoints in the frame's OWN optical coordinates:
//
//   T_pano_A  :  pano-from-A, from A's correspondences alone
//   T_pano_B  :  pano-from-B, from B's correspondences alone
//   T_AB = T_pano_A^-1 · T_pano_B          (== pose(A)^-1 · pose(B))
//
// Neither resection reads `sensor_frame_pose`, so `T_AB` is a genuine metric
// measurement of where B sits relative to A. The panorama is a shared, rigid
// intermediate coordinate frame — it never has to be correctly placed in world.
// (A useful consequence: `rux align 360` is NOT a prerequisite. Panorama poses
// are neither read nor written here.)
//
// GUARDRAILS: nothing new is invented. The emitted LoopEdges are the SAME type
// the ORB front-end emits, are gated by the SAME LoopClosureOptions knobs
// (`min_frame_gap`, `min_seed_disagreement`, `max_seed_disagreement`), are
// PCM-filtered as part of the UNION with the other edge sources, and enter the
// SAME GncOptimizer graph — so a wrong panorama edge is down-weighted rather
// than corrupting the solution.
//
// This header carries no GTSAM and no OpenCV include (docs/STANDARDS.md §2).
 
#pragma once
 
#include "reusex/slam/LoopClosure.hpp"
 
#include <Eigen/Core>
 
#include <vector>
 
namespace reusex {
class ProjectDB;
}
 
namespace reusex::geometry {

struct PanoramaLoopOptions {
  bool enable = false;
 
  // --- candidate frames ----------------------------------------------------
  int max_frames = 240;
  int min_candidate_frames = 8;
 
  // --- panorama slicing (geometry/EquirectProjection) ----------------------
  int n_yaw = 8;         
  double fov_deg = 90.0; 
  int slice = 1008;      
 
  // --- ORB front-end -------------------------------------------------------
  int max_features = 3000;  
  float ratio_test = 0.85f; 
  float min_depth = 0.3f;   
  float max_depth = 6.0f;
 
  // --- per-frame resection -------------------------------------------------
  int min_frame_correspondences = 10;
  int min_slice_correspondences = 6;
  int min_frame_inliers = 20;
  float ransac_reproj_px = 5.0f; 
  int ransac_iterations = 500;
  int refine_iterations = 10; 
  double max_pano_distance = 8.0;
 
  // --- edge emission -------------------------------------------------------
  int max_edges_per_panorama = 24;
  float base_sigma_trans = 0.15f; 
  float base_sigma_rot = 0.06f;   
  float min_sigma_trans = 0.05f;  
  float min_sigma_rot = 0.025f;   
 
  unsigned seed = 42; 
};

struct PanoramaLoopResult {
  int panoramas = 0;         
  int panoramas_matched = 0; 
  int frames_resected = 0;   
  int proposed = 0;          
  int dropped_gap = 0;       
  int dropped_seed_gate = 0; 
  int dropped_cap = 0;       
  int edges = 0;             
  int total_inliers = 0;     
};

std::vector<LoopEdge>
detect_panorama_loop_edges(ProjectDB &db, const std::vector<int> &node_ids,
                           const std::vector<Eigen::Matrix4d> &seed_poses,
                           const PanoramaLoopOptions &options,
                           const LoopClosureOptions &gates,
                           PanoramaLoopResult *out_result = nullptr);

namespace detail {

struct PanoResection {
  int frame = -1; 
  Eigen::Matrix4d T_pano_frame = Eigen::Matrix4d::Identity();
  int inliers = 0; 
};

std::vector<LoopEdge>
edges_from_resections(std::vector<PanoResection> resections,
                      const std::vector<Eigen::Matrix4d> &seed_poses,
                      const PanoramaLoopOptions &opt,
                      const LoopClosureOptions &gates,
                      PanoramaLoopResult *stats = nullptr);
 
} // namespace detail
 
} // namespace reusex::geometry