Function predictAim

tracker/src/pointing/predict.ts:131–201

(
  ac: Aircraft,
  site: GeoPoint,
  now: number,
  history: TrackHistory,
  params: PredictParams,
  mount: MountModel,
  limits: CameraLimits,
  currentPanTilt: PanTilt | null,
)

 * recompute slew from the resulting move, predict again.
 */
export function predictAim(
  ac: Aircraft,
  site: GeoPoint,
  now: number,
  history: TrackHistory,
  params: PredictParams,
  mount: MountModel,
  limits: CameraLimits,
  currentPanTilt: PanTilt | null,
): Prediction | null {
  // Denoised position when smoothing is on (kills ~1 Hz aim jitter from
  // ADS-B position noise); raw fix otherwise.
  const geo =
    params.posSmoothing && params.posSmoothing > 0
      ? history.smoothGeo(ac, now, 1 - params.posSmoothing * 0.85) ?? aircraftGeoPoint(ac)
      : aircraftGeoPoint(ac);
  if (!geo) return null;

  const fixAgeSec = Math.max(0, (now - (ac.ts ?? now)) / 1000) + (ac.seen ?? 0);
  const turnRateDps = history.turnRateDps(ac.hex);
  const kin = {
    lat: geo.lat,
    lon: geo.lon,
    altM: geo.altM,
    gsKt: ac.gs,
    trackDeg: ac.track,
    vRateFpm: ac.baroRate,
    turnRateDps,
  };

  const predictAt = (leadSec: number): AzEl =>
    azElFromSite(site, predictGeo(kin, leadSec));

  // The camera doesn't move the instant we command it — aim where the plane
  // will be when the command BITES, not when it's sent. While continuously
  // tracking, this is the term that converts a steady trailing error into a
  // centered lock (the rate feedforward picks up the matching value because
  // the analytic rate is evaluated at the same shifted epoch).
  const motorLag = params.motorLatencySec ?? 0;

  // Pass 1: assume a small slew.
  let lead = fixAgeSec + params.adsbLatencySec + motorLag + 0.3;
  let clamped = lead > params.maxLeadSec + fixAgeSec;
  lead = Math.min(lead, params.maxLeadSec + fixAgeSec);
  let azEl = predictAt(lead);

  // Pass 2: refine with the actual slew time to the pass-1 aim point.
  if (currentPanTilt) {
    const goal = mountFromWorld(azEl.azDeg, azEl.elDeg, mount);
    const slew = slewSeconds(currentPanTilt, goal, limits);
    let refined = fixAgeSec + params.adsbLatencySec + motorLag + slew;
    if (refined > params.maxLeadSec + fixAgeSec) {
      refined = params.maxLeadSec + fixAgeSec;
      clamped = true;
    }
    azEl = predictAt(refined);
    lead = refined;
  }