@spec attitude_dcm_from_quaternion(attitude_quaternion()) ::
  {:ok, mat3()} | {:error, inertial_error()}

Convert a scalar-first quaternion to its body-to-ECEF direction cosine matrix.

@spec attitude_quaternion_from_dcm(mat3()) ::
  {:ok, Sidereon.GNSS.Fusion.AttitudeQuaternion.t()}
  | {:error, inertial_error()}

Convert a body-to-ECEF direction cosine matrix to a normalized quaternion.

@spec attitude_yaw_pitch_roll_rad(mat3()) :: {:ok, vec3()} | {:error, term()}

Return yaw, pitch, and roll in radians for a body-to-ECEF matrix.

@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 configure_time_sync_history(
  Sidereon.GNSS.Fusion.Filter.t(),
  Sidereon.GNSS.Fusion.TimeSyncHistoryConfig.t() | keyword() | map()
) :: {:ok, map()} | {:error, term()}

Alias for configure_time_sync/2 matching Python's retained-history name.

@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_encoded_state(binary(), filter_config()) ::
  {:ok, Sidereon.GNSS.Fusion.Filter.t()} | {:error, term()}

Alias for from_state_bytes/2 matching Python's encoded-state constructor.

@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 gauss_markov_bias_decay(number(), number() | :infinity | nil) ::
  {:ok, float()} | {:error, inertial_error()}

Return a first-order Gauss-Markov bias decay factor.

@spec gauss_markov_bias_variance_increment(
  number(),
  number(),
  number() | :infinity | nil
) ::
  {:ok, float()} | {:error, inertial_error()}

Return the Gauss-Markov bias variance increment over a time interval.

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

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

@spec gravity_ecef_mps2(vec3()) :: {:ok, vec3()} | {:error, inertial_error()}

Return the WGS84 normal-gravity vector at an ECEF position.

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

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

@spec imu_simulator_bias(reference()) :: {:ok, map()} | {:error, term()}

Return the simulator's current Gauss-Markov bias state.

@spec imu_simulator_rate_random_walk(reference()) :: {:ok, map()} | {:error, term()}

Return the simulator's current rate-random-walk state.

@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 nav_state_attitude_quaternion(Sidereon.GNSS.Fusion.NavState.t() | map()) ::
  {:ok, Sidereon.GNSS.Fusion.AttitudeQuaternion.t()}
  | {:error, inertial_error()}

Read a navigation state's body-to-ECEF attitude as a normalized quaternion.

@spec nav_state_attitude_yaw_pitch_roll_rad(Sidereon.GNSS.Fusion.NavState.t() | map()) ::
  {:ok, vec3()} | {:error, inertial_error()}

Read a navigation state's attitude as yaw, pitch, and roll in radians.

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

Build a new stateful filter.

@spec new_imu_simulator(imu_spec(), keyword() | map()) ::
  {:ok, Sidereon.GNSS.Fusion.ImuSimulator.t()} | {:error, term()}

Create a deterministic stateful IMU simulator.

@spec new_strapdown_mechanizer(
  Sidereon.GNSS.Fusion.NavState.t() | map(),
  keyword() | map()
) ::
  {:ok, Sidereon.GNSS.Fusion.StrapdownMechanizer.t()} | {:error, term()}

Create a standalone ECEF strapdown mechanizer from a navigation state.

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

Return wheeled-vehicle lateral and vertical velocity constraint settings.

@spec normal_gravity_mps2(number(), number()) ::
  {:ok, float()} | {:error, inertial_error()}

Return WGS84 normal-gravity magnitude at geodetic latitude and height.

@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_encoded_state(Sidereon.GNSS.Fusion.Filter.t(), binary()) ::
  {:ok, map()} | {:error, term()}

Alias for restore_state/2 matching Python's encoded-state restore method.

@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 simulate_imu_increment(reference(), map()) ::
  {:ok, Sidereon.GNSS.Fusion.ImuSample.t()} | {:error, term()}

Generate one simulated sample from a truth IMU increment.

@spec simulate_imu_samples(
  [Sidereon.GNSS.Fusion.NavState.t() | map()],
  imu_spec(),
  keyword() | map()
) ::
  {:ok, Sidereon.GNSS.Fusion.SimulatedImuSequence.t()} | {:error, term()}

Generate a batch of samples from a navigation-state truth trajectory.

@spec simulate_imu_samples_from_increments(
  [Sidereon.GNSS.Fusion.CorrectedImuIncrement.t() | map()],
  imu_spec(),
  keyword() | map()
) :: {:ok, Sidereon.GNSS.Fusion.SimulatedImuSequence.t()} | {:error, term()}

Generate a batch of samples from explicit corrected truth increments.

@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 strapdown_propagate(reference(), Sidereon.GNSS.Fusion.ImuSample.t() | map()) ::
  {:ok, Sidereon.GNSS.Fusion.NavState.t()} | {:error, term()}

Propagate a standalone mechanizer by one IMU sample.

@spec strapdown_state(reference()) ::
  {:ok, Sidereon.GNSS.Fusion.NavState.t()} | {:error, term()}

Return the current standalone mechanizer navigation state.

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

Return the tight receiver-clock state.

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

Alias for time_sync_status/1 matching Python's retained-history name.

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

Return retained-history occupancy for time synchronization.

@spec true_imu_increment_between(
  Sidereon.GNSS.Fusion.NavState.t() | map(),
  Sidereon.GNSS.Fusion.NavState.t() | map()
) :: {:ok, Sidereon.GNSS.Fusion.CorrectedImuIncrement.t()} | {:error, term()}

Reconstruct the mechanization-consistent truth increment between two navigation states.

@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. The single-frequency code model subtracts the broadcast group delay of the record a broadcast clock came from, and takes the relativistic clock term RTKLIB peph2pos applies to a precise clock. A satellite state the source refuses because it reads UT1 outside the UT1 table fails the update with {:error, {:ut1_outside_coverage, :before_coverage | :after_coverage}} and leaves the filter unchanged; every update map carries :ut1_degraded, nil or the side of the table a state was read outside under a permissive UT1 policy.

@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 with_config(filter_state(), filter_config()) ::
  {:ok, Sidereon.GNSS.Fusion.Filter.t()} | {:error, term()}

Alias for new/2 matching the Python InertialFilter.with_config constructor.

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

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