@spec configure_time_sync(Sidereon.GNSS.Fusion.Filter.t(), keyword() | map()) ::
  {:ok, map()} | {:error, term()}

Configure retained IMU samples and GNSS checkpoints for time synchronization.

@spec encode_state(Sidereon.GNSS.Fusion.Filter.t()) ::
  {:ok, binary()} | {:error, term()}

Encode the current filter state and retained time-sync history as bytes.

@spec filter_config(imu_spec(), keyword() | map()) :: filter_config()

Build a fusion filter config from an IMU spec and options.

Options include :filter_kind (:ekf or :ukf), :mechanization, :loose, :tight, :imu_model, :imu_to_body_dcm, and :ukf_update_options. Loose config may include :fix_status_weighting, :measurement_reweighting, :prediction_adaptation, :stationary_updates, and :non_holonomic.

@spec from_state_bytes(binary(), filter_config()) ::
  {:ok, Sidereon.GNSS.Fusion.Filter.t()} | {:error, term()}

Restore a new stateful filter from versioned fusion state bytes.

@spec gnss_fix_status_weighting(keyword() | map()) :: map()

Return per-fix-status sigma multipliers for loose GNSS updates.

@spec igg_iii_measurement_reweighting(keyword() | map()) :: map()

Return standard IGG-III measurement reweighting settings for loose updates.

@spec imu_spec(imu_spec()) :: map()

Return an IMU stochastic specification.

Presets are :mems, :tactical, and :navigation. A map is passed through after numeric normalization.

@spec new(filter_state(), filter_config()) ::
  {:ok, Sidereon.GNSS.Fusion.Filter.t()} | {:error, term()}

Build a new stateful filter.

@spec non_holonomic_constraint_config(keyword() | map()) :: map()

Return wheeled-vehicle lateral and vertical velocity constraint settings.

@spec propagate(Sidereon.GNSS.Fusion.Filter.t(), imu_sample()) ::
  {:ok, map()} | {:error, term()}

Propagate the filter by one IMU sample.

@spec propagate_recorded(
  Sidereon.GNSS.Fusion.Filter.t(),
  imu_sample(),
  Sidereon.GNSS.Fusion.FusionRtsHistoryBuilder.t()
) :: {:ok, map()} | {:error, term()}

Propagate the filter by one IMU sample and record the transition for RTS smoothing.

@spec restore_state(Sidereon.GNSS.Fusion.Filter.t(), binary()) ::
  {:ok, map()} | {:error, term()}

Restore an existing filter from bytes produced by encode_state/1.

@spec smooth_fusion_rts(Sidereon.GNSS.Fusion.FusionRtsHistory.t()) ::
  {:ok, Sidereon.GNSS.Fusion.SmoothedFusionTrajectory.t()} | {:error, term()}

Apply fixed-interval RTS smoothing to recorded GNSS/INS fusion history.

@spec state(Sidereon.GNSS.Fusion.Filter.t()) :: {:ok, map()} | {:error, term()}

Return the current closed-loop filter state.

@spec stationary_detector_config(keyword() | map()) :: map()

Return windowed IMU thresholds for stationary update detection.

@spec stationary_update_config(keyword() | map()) :: map()

Return zero-velocity and zero-angular-rate stationary update settings.

@spec strapdown_config(keyword() | map()) :: map()

Return a strapdown mechanization config.

The current core surface exposes :off coning correction.

@spec tight_clock_state(Sidereon.GNSS.Fusion.Filter.t()) ::
  {:ok, map()} | {:error, term()}

Return the tight receiver-clock state.

@spec time_sync_status(Sidereon.GNSS.Fusion.Filter.t()) ::
  {:ok, map()} | {:error, term()}

Return retained-history occupancy for time synchronization.

@spec update_loose(Sidereon.GNSS.Fusion.Filter.t(), loose_measurement()) ::
  {:ok, map()} | {:error, term()}

Apply a loose GNSS position or position-velocity fix at the current filter epoch.

@spec update_loose_recorded(
  Sidereon.GNSS.Fusion.Filter.t(),
  loose_measurement(),
  Sidereon.GNSS.Fusion.FusionRtsHistoryBuilder.t()
) :: {:ok, map()} | {:error, term()}

Apply a loose GNSS fix and record before/after checkpoints for RTS smoothing.

@spec update_loose_time_sync(Sidereon.GNSS.Fusion.Filter.t(), loose_measurement()) ::
  {:ok, map()} | {:error, term()}

Apply a time-synchronized loose GNSS fix, replaying retained history if needed.

@spec update_non_holonomic(Sidereon.GNSS.Fusion.Filter.t()) ::
  {:ok, map() | nil} | {:error, term()}

Apply configured non-holonomic vehicle constraints.

@spec update_non_holonomic_recorded(
  Sidereon.GNSS.Fusion.Filter.t(),
  Sidereon.GNSS.Fusion.FusionRtsHistoryBuilder.t()
) :: {:ok, map() | nil} | {:error, term()}

Apply configured non-holonomic constraints and record checkpoints when applied.

@spec update_stationary(Sidereon.GNSS.Fusion.Filter.t()) ::
  {:ok, map() | nil} | {:error, term()}

Apply configured stationary zero-velocity and zero-angular-rate constraints.

@spec update_stationary_recorded(
  Sidereon.GNSS.Fusion.Filter.t(),
  Sidereon.GNSS.Fusion.FusionRtsHistoryBuilder.t()
) :: {:ok, map() | nil} | {:error, term()}

Apply configured stationary constraints and record checkpoints when applied.

@spec update_tight(
  Sidereon.GNSS.Fusion.Filter.t(),
  Sidereon.GNSS.SP3.t() | Sidereon.GNSS.Broadcast.t(),
  tight_epoch()
) :: {:ok, map()} | {:error, term()}

Apply a tight raw GNSS epoch at the current filter epoch.

The ephemeris source must be an existing SP3 or broadcast resource.

@spec update_tight_recorded(
  Sidereon.GNSS.Fusion.Filter.t(),
  Sidereon.GNSS.SP3.t() | Sidereon.GNSS.Broadcast.t(),
  tight_epoch(),
  Sidereon.GNSS.Fusion.FusionRtsHistoryBuilder.t()
) :: {:ok, map()} | {:error, term()}

Apply a tight raw GNSS epoch and record before/after checkpoints for RTS smoothing.

@spec update_tight_time_sync(
  Sidereon.GNSS.Fusion.Filter.t(),
  Sidereon.GNSS.SP3.t() | Sidereon.GNSS.Broadcast.t(),
  tight_epoch()
) :: {:ok, map()} | {:error, term()}

Apply a time-synchronized tight raw GNSS epoch.

@spec velocity_match_outage(
  [velocity_match_state()],
  loose_measurement(),
  keyword() | map()
) ::
  {:ok, map()} | {:error, term()}

Blend a first good post-outage position/velocity fix back over an outage span.

@spec velocity_matching_config(keyword() | map()) :: map()

Return endpoint velocity matching settings for one GNSS outage.

@spec yang_prediction_adaptive_factor(keyword() | map()) :: map()

Return standard Yang predicted-covariance adaptation settings for loose updates.