add clarification to research methodology by including a step for solution comparison and user consultation

_docs/00_research/camera_tilt_gsd_research.md

@@ -0,0 +1,189 @@
+# Camera Tilt Impact on GSD Estimation for UAV Aerial Photography (Without IMU)
+
+**Context**: GPS-denied visual navigation system processes photos from a fixed-wing UAV. Camera points downward but is NOT autostabilized. GSD computed as `GSD = (effective_altitude × sensor_width) / (focal_length × original_width)` assuming nadir. Flight altitude up to 1 km. No IMU data.
+
+---
+
+## 1. GSD Error from Uncorrected Camera Tilt
+
+### Formula
+
+At the principal point (image center, φ = 0), the GSD correction factor is:
+
+```
+GSD_rate = 1 / cos(θ)
+GSD_actual = GSD_nadir × GSD_rate = GSD_nadir / cos(θ)
+```
+
+Where θ = tilt angle from nadir (angle between optical axis and vertical).
+
+**Error percentage** (nadir assumption vs. actual):
+
+```
+Error (%) = (GSD_actual - GSD_nadir) / GSD_nadir × 100 = (1/cos(θ) - 1) × 100
+```
+
+### GSD Error at Typical Tilt Angles
+
+| Tilt θ | 1/cos(θ) | GSD Error (%) |
+|--------|----------|---------------|
+| 1°     | 1.00015  | 0.015%        |
+| 2°     | 1.00061  | 0.06%         |
+| 3°     | 1.00137  | 0.14%         |
+| 5°     | 1.00382  | 0.38%         |
+| 10°    | 1.01538  | 1.54%         |
+| 15°    | 1.03528  | 3.53%         |
+| 18°    | 1.05146  | 5.15%         |
+| 20°    | 1.06418  | 6.42%         |
+| 25°    | 1.10338  | 10.34%        |
+| 30°    | 1.15470  | 15.47%        |
+
+**Straight flight (1–5° tilt)**: Error 0.015%–0.38% — negligible for most applications.
+
+**During turns (10–30° bank)**: Error 1.5%–15.5% — significant and should be corrected.
+
+---
+
+## 2. When Does GSD Error Become Significant (>5%)?
+
+**Threshold**: ~18° tilt.
+
+- Below 15°: Error < 3.5%
+- 15°–18°: Error 3.5%–5%
+- Above 18°: Error > 5%
+
+Fixed-wing UAVs commonly bank 10–30° in turns; photogrammetry specs often limit tilt to ±2° for straight flight and roll to ±5°.
+
+---
+
+## 3. Per-Pixel GSD (Full Formula)
+
+For non-nadir views, GSD varies across the image:
+
+```
+GSD_rate(x, y) = 1 / cos(θ + φ)
+```
+
+Where:
+- **θ** = camera tilt from nadir
+- **φ** = angular offset of pixel from optical axis (0 at principal point)
+
+**Computing φ** from pixel (x, y) and intrinsics (fx, fy, cx, cy):
+
+```
+world_vector = K⁻¹ × [x, y, 1]ᵀ
+φ = angle between world_vector and optical axis (0, 0, 1)
+```
+
+Using focal length f and principal point (c₁, c₂):
+
+```
+tan(φ) = px × √[(x_px - c₁)² + (y_px - c₂)²] / f
+```
+
+For two-axis rotation (tilt + pan), the spherical law of cosines applies; see Math Stack Exchange derivation.
+
+---
+
+## 4. Tilt Estimation Without IMU
+
+### 4.1 Horizon Detection
+
+**Feasibility**: Not suitable for nadir-down imagery at 1 km.
+
+- Horizon is ~0.9° below horizontal at 1 km altitude.
+- A downward camera (e.g. 80–90° from horizontal) does not see the horizon.
+- Horizon detection is used for front-facing or oblique cameras, not nadir mapping.
+
+**Sources**: Fixed-wing attitude via horizon tracking; horizon detection for front-facing UAV cameras.
+
+### 4.2 Vanishing Point Analysis
+
+**Feasibility**: Limited for nadir ground imagery.
+
+- Vanishing points come from parallel lines (roads, buildings).
+- Nadir views often lack clear converging lines.
+- More useful for oblique/urban views.
+- Reported accuracy: ~0.15° roll, ~0.12° pitch on structured road scenes.
+
+**Sources**: ISPRS vanishing point exterior orientation; real-time joint estimation of camera orientation and vanishing points.
+
+### 4.3 Feature Matching Between Consecutive Frames
+
+**Feasibility**: Yes — standard approach.
+
+- Feature matching (e.g. SuperPoint+LightGlue) yields point correspondences.
+- Homography or essential matrix relates consecutive views.
+- Homography decomposition gives rotation R (and translation t).
+- R encodes roll, pitch, yaw; pitch/roll relative to nadir give tilt.
+
+### 4.4 Homography Decomposition (Already in Pipeline)
+
+**Feasibility**: Best fit for this system.
+
+- Homography: `H = K(R - tnᵀ/d)K⁻¹` for planar scene.
+- R = rotation (roll, pitch, yaw); t = translation; n = plane normal; d = plane distance.
+- For ground plane at known altitude, R can be decomposed to extract tilt.
+- Planar motion (constant height, fixed tilt) reduces DOF; specialized solvers exist.
+
+**Lund University work**:
+- Ego-motion and tilt from multiple homographies under planar motion.
+- Iterative methods for robust tilt across sequences.
+- Minimal solvers (e.g. 2.5 point correspondences) for RANSAC.
+
+**Sources**: Homography decomposition (Springer); Lund planar motion and tilt estimation.
+
+---
+
+## 5. Recommended Approach for Tilt-Compensated GSD
+
+### Option A: Homography Decomposition (Recommended)
+
+1. Use existing VO homography between consecutive frames.
+2. Decompose H to obtain R (and t).
+3. Extract tilt (pitch/roll from nadir) from R.
+4. Apply correction: `GSD_corrected = GSD_nadir / cos(θ)` at principal point, or per-pixel with `1/cos(θ + φ)`.
+
+**Pros**: Reuses current pipeline, no extra sensors, consistent with VO.  
+**Cons**: Depends on homography quality; planar assumption; possible 4-way decomposition ambiguity (resolved with known altitude/scale).
+
+### Option B: Simplified Center-Only Correction
+
+If per-pixel correction is unnecessary:
+- Estimate tilt θ from homography decomposition.
+- Use `GSD_corrected = GSD_nadir / cos(θ)` for the whole image.
+
+### Option C: Vanishing Points (If Applicable)
+
+For urban/structured scenes with visible parallel lines:
+- Detect vanishing points.
+- Estimate pitch/roll from vanishing point positions.
+- Use for GSD correction when horizon/homography are unreliable.
+
+---
+
+## 6. Implementation Notes
+
+1. **Straight flight (1–5°)**: Correction optional; error < 0.4%.
+2. **Turns (10–30°)**: Correction recommended; error can exceed 5% above ~18°.
+3. **Homography decomposition**: Use `cv2.decomposeHomographyMat` or planar-motion solvers (e.g. Lund-style).
+4. **Scale**: Known altitude fixes scale from homography decomposition.
+5. **Roll vs. pitch**: For GSD, the effective tilt from nadir matters; combine roll and pitch into a single tilt angle for the correction.
+
+---
+
+## 7. Source URLs
+
+| Topic | URL |
+|-------|-----|
+| GSD oblique correction formula | https://math.stackexchange.com/questions/4221152/correct-non-nadir-view-for-calculation-of-the-ground-sampling-distance-gsd |
+| Stack Overflow GSD correction | https://stackoverflow.com/questions/68710337/correct-non-nadir-view-for-gsd-calculation-uav |
+| Camera orientation variation (Extrica) | https://www.extrica.com/article/15116 |
+| Oblique GSD calculator | https://www.aerial-survey-base.com/gsd-calculator/gsd-calculator-help-oblique-images-calculation/ |
+| Homography decomposition | https://link.springer.com/article/10.1007/s11263-025-02680-4 |
+| Lund homography planar motion + tilt | https://www.lu.se/lup/publication/72c8b14d-3913-4111-a334-3ea7646bd7ea |
+| Horizon detection attitude | https://ouci.dntb.gov.ua/en/works/98XdWoq9/ |
+| Fixed-wing horizon + optical flow | https://onlinelibrary.wiley.com/doi/10.1002/rob.20387 |
+| Vanishing point camera orientation | https://isprs-archives.copernicus.org/articles/XLVIII-2-W9-2025/143/2025/ |
+| UAV nadir/oblique influence | https://www.mdpi.com/2504-446X/8/11/662 |
+| Horizon angle at altitude | https://gis.stackexchange.com/questions/4690/determining-angle-down-to-horizon-from-different-flight-altitudes |