Skip to content

Class inertialsim::sensors::INS

ClassList > inertialsim > sensors > INS

INS sensor simulation.More...

  • #include <ins.h>

Public Functions

Type Name
INS (const INSModel & model, const INSSpecification & specification, std::optional< uint64_t > seed=0, INSSimulationMode mode=INSSimulationMode::BATCH)
Construct an INS .
std::optional< INSData > Initialize (const std::optional< geodesy::GlobalPose > & pose=std::nullopt, const std::optional< geometry::Vector > & angular_rate=std::nullopt, const std::optional< geometry::Vector > & specific_force=std::nullopt)
Initialize the INS sensor.
void Reset (const std::optional< geometry::Rotation > & attitude=std::nullopt, const std::optional< geodesy::Coordinates > & position=std::nullopt, const std::optional< geometry::Vector > & velocity=std::nullopt)
Reset the INS state.
INSData Simulate (const geometry::Vector & angular_rate, const geometry::Vector & specific_force)
Simulate INS measurements fromIMU inputs.
INSData Simulate (const Measurement & angular_rate, const Measurement & specific_force)
Simulate INS measurements fromMeasurement inputs.
bool initialized () const
Check if the INS is initialized.
INSSimulationMode mode () const
Get the simulation mode.
const INSModel & model () const
Get the INS model.
const std::mt19937_64 & rng () const
Get the random number generator.
const INSSpecification & specification () const
Get the INS specification.
const INSState & state () const
Get the simulation state.

Detailed Description

An INS integrates data from a gyro and an accelerometer to produce attitude (orientation), position, and velocity outputs. The class supports both batch and real-time simulation modes.

Before calling Simulate(), the INS must be initialized via the Initialize() method. This provides the initial attitude (orientation), position, and velocity of the INS. The INS also inherits the navigation coordinate frame from the initial condition inputs, along with any geodetic datums and models.

Public Functions Documentation

function INS

Construct an INS . 

inertialsim::sensors::INS::INS (
    const  INSModel & model,
    const  INSSpecification & specification,
    std::optional< uint64_t > seed=0,
    INSSimulationMode mode=INSSimulationMode::BATCH
)

INS sensors require a model which specifies which sources of error to simulate; a specification which includes the parameters necessary to model deterministic and random errors; and optionally a random number generator seed to control determinism and repeatability of the simulation.

Two modes are supported: BATCH (default) and REALTIME. In BATCH mode, the Simulate() method should be called once with all inputs to return all simulated measurement outputs. In REALTIME mode, the Simulate() method can be called repeatedly to incrementally simulate measurements.

Before calling Simulate(), the INS must be initialized via the Initialize() method. This provides the initial attitude (orientation), position, and velocity of the INS. The INS also inherits the navigation coordinate frame from the initial condition inputs, along with any geodetic datums and models.

Parameters:

  • model INS model options specifying error sources.
  • specification INS specification with error parameters.
  • seed Random number generator seed (nullopt for random, 0 for deterministic default).
  • mode Simulation mode: BATCH (default) or REALTIME.

function Initialize

Initialize the INS sensor. 

std::optional< INSData > inertialsim::sensors::INS::Initialize (
    const std::optional< geodesy::GlobalPose > & pose=std::nullopt,
    const std::optional< geometry::Vector > & angular_rate=std::nullopt,
    const std::optional< geometry::Vector > & specific_force=std::nullopt
)

Set the initial attitude, position, and velocity of the INS sensor. If using REALTIME mode for incremental simulation, users must also supply the initial angular rate and specific force inputs.

Initial pose should be specified as a GlobalPose object. The navigation frame, gravity, and earth rotation rate models will be inherited from the initial conditions.

If the pose input is nullopt, a local frame with identity initial pose, zero position, zero velocity, and standard gravity will be used.

All inputs must be a single sample representing the initial conditions at the start of navigation.

Parameters:

  • pose Initial attitude, position, and velocity of the INS relative to Earth. Must have velocity data and contain exactly one pose.
  • angular_rate Initial angular rate of the INS. Only required in REALTIME mode.
  • specific_force Initial specific force experienced by the INS. Only required in REALTIME mode.

Returns:

INSData with initial pose. Only returned in REALTIME mode.

Exception:

  • std::invalid_argument if pose navigation frame is not supported (must be ECEF, GEODETIC, TOPOCENTRIC, or LOCAL).
  • std::invalid_argument if pose does not contain exactly one sample.
  • std::invalid_argument if pose does not have velocity data.
  • std::invalid_argument if in REALTIME mode and angular_rate or specific_force are not provided.

function Reset

Reset the INS state. 

void inertialsim::sensors::INS::Reset (
    const std::optional< geometry::Rotation > & attitude=std::nullopt,
    const std::optional< geodesy::Coordinates > & position=std::nullopt,
    const std::optional< geometry::Vector > & velocity=std::nullopt
)

Resets the internal INS attitude (orientation), position, and/or velocity from an external reference. Reset can be used to simulate the behavior of an aided INS sensor. For example, resetting the entire state can simulate the behavior of a sensor where GNSS measurements correct attitude, position, and velocity errors through correlations in a state estimation filter.

All inputs are optional and must be supplied relative to the navigation coordinate system established at initialization.

Parameters:

  • attitude Reference attitude to reset to (nullopt to keep current).
  • position Reference position to reset to (nullopt to keep current).
  • velocity Reference velocity to reset to (nullopt to keep current).

Exception:

  • std::runtime_error if INS is not initialized.

function Simulate [1/2]

Simulate INS measurements fromIMU inputs. 

INSData inertialsim::sensors::INS::Simulate (
    const  geometry::Vector & angular_rate,
    const  geometry::Vector & specific_force
)

An INS integrates data from a gyro and an accelerometer to produce attitude (orientation), position, and velocity outputs. Initial conditions must be specified using the Initialize() method before calling this method.

Inputs must have compatible shape and time. The angular rate input must be the angular rate of the gyro relative to inertial space as measured in gyro coordinates. The specific force input must be the specific force (non-gravitational acceleration) relative to inertial space acting on the accelerometer as measured in accelerometer coordinates.

The effect of Earth's rotation and gravity will be modeled based on the coordinates and datums specified in the initial conditions.

In REALTIME mode with the RK4 integrator, consecutive pairwise inputs must be supplied, e.g., two angular rates and two specific forces at times (1-2, 3-4, 5-6, ...). The first of the two samples is used as the mid-point of the integration interval and the output is given coincident with the second sample.

If the input data is itself simulated, see Gyro::Simulate(), Accelerometer::Simulate(), and IMU::Simulate().

Parameters:

  • angular_rate Angular rate of the INS relative to inertial space, measured in gyro coordinates. Must include time data.
  • specific_force Specific force experienced by the INS relative to inertial space, measured in accelerometer coordinates. Must include time data.

Returns:

INSData containing simulated measurements.

Exception:

  • std::runtime_error if INS is not initialized.
  • std::invalid_argument if inputs have incompatible times.
  • std::invalid_argument if insufficient samples provided (minimum 2 for BATCH mode with Euler/Trapezoid integrators, minimum 3 for RK4 integrator).

function Simulate [2/2]

Simulate INS measurements fromMeasurement inputs. 

INSData inertialsim::sensors::INS::Simulate (
    const  Measurement & angular_rate,
    const  Measurement & specific_force
)

Convenience overload that accepts Measurement objects instead of Vector objects. See the primary Simulate() method for detailed documentation.

Parameters:

  • angular_rate Angular rate measurement.
  • specific_force Specific force measurement.

Returns:

INSData containing simulated measurements.

function initialized

Check if the INS is initialized. 

inline bool inertialsim::sensors::INS::initialized () const

Returns:

True if initialized.

function mode

Get the simulation mode. 

inline INSSimulationMode inertialsim::sensors::INS::mode () const

Returns:

Simulation mode.

function model

Get the INS model. 

inline const  INSModel & inertialsim::sensors::INS::model () const

Returns:

Reference to the model.

function rng

Get the random number generator. 

inline const std::mt19937_64 & inertialsim::sensors::INS::rng () const

Returns:

Reference to the RNG.

function specification

Get the INS specification. 

inline const  INSSpecification & inertialsim::sensors::INS::specification () const

Returns:

Reference to the specification.

function state

Get the simulation state. 

const  INSState & inertialsim::sensors::INS::state () const

Returns the simulation state including all internal sensor parameters required to replicate the simulated measurement outputs.

Returns:

Reference to the INS state.

Exception:

  • std::runtime_error if INS is not initialized.

The documentation for this class was generated from the following file cpp/include/inertialsim/sensors/ins.h