altitude, camera, annotation err

README.md

@@ -532,9 +532,19 @@ obs.plot()                                  # Show results with uncertainty
 ## Limitations & Best Practices
 
 ### **Accuracy Expectations**
-- **Typical accuracy**: ~20%
-- **Best case**: ~15% with optimal conditions and camera calibration (so far!)
-- **Factors affecting precision**: Image quality, horizon clarity, altitude, camera specs
+
+For Earth photographed from an aircraft, **altitude is the dominant error source**. The inferred
+radius amplifies altitude uncertainty by roughly R/h (~637× at 10 km cruise altitude):
+
+| Altitude source | Typical precision | Radius error |
+| --- | --- | --- |
+| GPS (phone or aircraft) | ~30 m | < 0.5% |
+| Aircraft display / app | ~300–600 m | ~3–6% |
+| Estimated from flight info | ~600–2000 m | ~6–20% |
+
+Annotation quality and camera parameter accuracy are secondary contributors (~1–5% each with
+careful technique). The benchmark examples in this README use images without GPS telemetry; their
+errors reflect estimated-altitude quality, not the limits of the method.
 
 ### **Technical Limitations**
 - **Optimization challenges**: Complex parameter space → potential local minima (mitigated by multi-resolution optimization)

docs/science/geometry_basics.rst

@@ -49,7 +49,42 @@ This sagitta scales as :math:`s \propto \sqrt{h}` for a fixed field of view—do
 increases the sagitta by only :math:`\sqrt{2} \approx 1.4\times`. This square-root scaling means 
 that high altitude provides only modest improvements in measurement precision compared to moderate altitude.
 
-The key insight is that the limb arc's shape encodes the observer's altitude :math:`h` through the 
-relationship between :math:`R`, :math:`h`, and the observed angular geometry. By measuring the arc's 
-curvature in an image with known camera parameters, we can infer :math:`h` (if :math:`R` is known) 
-or :math:`R` (if :math:`h` is known).
+The key insight is that the limb arc's shape encodes the observer's altitude :math:`h` through the
+relationship between :math:`R`, :math:`h`, and the observed angular geometry. By measuring the arc's
+curvature in an image with known camera parameters, we can infer :math:`h` (if :math:`R` is known)
+or :math:`R` (if :math:`h` is known).
+
+Parameter Identifiability and the R–h Degeneracy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The arc curvature constrains the ratio :math:`R/(R+h)`, not :math:`R` and :math:`h` independently.
+Any pair :math:`(R', h')` satisfying the same ratio produces an identical limb arc in the image.
+Freeing both parameters simultaneously therefore creates a degenerate ridge in the optimization
+landscape: the optimizer can trade off radius against altitude without changing the predicted arc
+shape. This is why altitude must be supplied from an external source—GPS, barometric sensor, or
+flight telemetry—rather than inferred from the image alongside radius.
+
+When altitude :math:`h` is known, the sensitivity of the inferred radius to altitude uncertainty
+follows directly from differentiating :math:`R = \rho h\,/\,(1 - \rho)` where
+:math:`\rho = R/(R+h)`:
+
+.. math::
+
+   \frac{dR}{dh} = \frac{R}{h}
+
+The amplification factor :math:`R/h` is large at aircraft altitudes. At :math:`h = 10` km, a 1 km
+error in altitude propagates to a ~637 km (~10%) error in the inferred radius. However, civilian GPS
+altitude is accurate to roughly 10–30 m, which propagates to only 6–19 km (~0.1–0.3%)—well within
+useful measurement bounds.
+
+Three independent sources contribute to overall radius uncertainty:
+
+- **Altitude** (:math:`\sigma_h`): :math:`\sigma_R \approx (R/h)\,\sigma_h`. Reduced by better GPS
+  or barometric sensing. Typically dominates with good annotations.
+
+- **Annotation noise** (:math:`\sigma_\alpha`): uncertainty in the fitted arc position, driven by
+  the number and precision of horizon points. Reduced by denser or automated annotation.
+
+- **Camera parameters** (:math:`\sigma_{f/w}`): errors in focal length or sensor width shift the
+  pixel-to-angle mapping, biasing the inferred curvature. Reduced by camera calibration;
+  usually 1–2% for smartphones with accurate EXIF metadata.

docs/science/methodology.rst

@@ -70,13 +70,18 @@ resolution, helping avoid local minima in the cost landscape.
 Uncertainty Quantification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Measurement uncertainty arises from pixel discretization, camera parameter uncertainty, and 
-atmospheric effects. Bootstrap resampling provides empirical confidence intervals: we repeatedly 
-resample the observed horizon points with replacement, refit the model to each bootstrap sample, 
-and examine the distribution of fitted parameters. The standard deviation of this distribution 
-estimates parameter uncertainty.
-
-Alternatively, the Hessian matrix (second derivatives of the cost function at the solution) provides 
-an approximate covariance matrix for the parameters, yielding uncertainty estimates from the optimization 
-geometry itself. Both methods typically agree within a factor of two and provide order-of-magnitude 
-uncertainty characterization.
+For Earth measurements from aircraft, **altitude uncertainty dominates**. Because the arc curvature
+constrains the ratio :math:`R/(R+h)` rather than :math:`R` directly, altitude error is amplified
+by :math:`R/h` when converting to radius (see :doc:`geometry_basics`). At 10 km cruise altitude
+this factor is ~637: a 600 m altitude uncertainty adds ~6% radius error, while GPS precision
+of ~30 m contributes under 0.5%. Secondary contributors are annotation quality and camera parameter
+accuracy, typically 1–5% each.
+
+Algorithmic uncertainty—arising from local minima, pixel discretization, and numerical precision—is
+estimated by two complementary methods. Bootstrap resampling repeatedly resamples the observed
+horizon points with replacement, refits the model to each sample, and reports the standard deviation
+of the resulting parameter distribution. Alternatively, the Hessian matrix (second derivatives of
+the cost function at the solution) yields an approximate parameter covariance matrix directly from
+the optimization geometry. Both methods typically agree within a factor of two and capture
+optimizer-level uncertainty, but they do not account for the altitude or camera-parameter terms
+above, which must be propagated separately.

docs/tutorial_airplane.rst

@@ -150,7 +150,10 @@ If you can't get exact altitude, use these typical values:
      - 11,278 - 12,497
 
 .. warning::
-   Altitude uncertainty of ±2,000 feet typically adds 5-10% error to your final radius measurement. Try to be as accurate as possible, but don't worry if you can only estimate.
+   **Altitude is the dominant error source.** At cruise altitude (~10 km), the inferred radius
+   amplifies altitude uncertainty by roughly R/h ≈ 637×. A ±2,000 ft (±610 m) uncertainty adds
+   ~6% to your radius measurement; GPS altitude (~30 m) reduces this below 0.5%. Altitude
+   accuracy matters more than image quality or annotation precision—get it as precisely as you can.
 
 Part 4: Analysis with Planet Ruler
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~