RidgeRun Video Stabilization Library/API Reference/Adding Algorithms: Difference between revisions

From RidgeRun Developer Wiki
No edit summary
Line 18: Line 18:
* Apply: applies the integrator algorithm to the entry orientation data.
* Apply: applies the integrator algorithm to the entry orientation data.
* Reset: sets the initial orientation and its initial time to a desired value.
* Reset: sets the initial orientation and its initial time to a desired value.


==== Defining the Apply method ====
==== Defining the Apply method ====
This method receives two parameters:  
This method receives two parameters:  
* softgyro: This is the input data containing a vector of orientation values (Quaternions) along with their corresponding timestamps. It is used by the interpolation algorithm.
* softengyro: This contains the result of integrating the initial orientation data, it contains a vector of orientation values represented as a Quaternion with their corresponding timestamps.
* interpolated: This contains a vector of interpolated orientation values with their corresponding interpolation timestamps.
* rawgyro: This parameter contains the data from sensors, could have data from gyroscope, accelerometer and magnetometer.
The user must take into account that the method uses the IInterpolator start time member to perform the interpolation and that the time must be set on microseconds.


<syntaxhighlight lang=c++>
<syntaxhighlight lang=c++>
RuntimeError ExampleInterpolator::Apply(
RuntimeError ExampleIntegrator::Apply(
     std::vector<std::pair<Quaternion<double>, uint64_t>>&interpolated,
     std::vector<std::pair<Quaternion<double>, uint64_t>>& softengyro,
     std::vector<std::pair<Quaternion<double>, uint64_t>>& softgyro) {
     const std::vector<SensorPayload> rawgyro) {
   RuntimeError ret{};
   RuntimeError ret{};


   /* Interpolation algorithm logic */
   /* Integrator algorithm logic */


   return ret;
   return ret;
Line 38: Line 38:


==== Defining the Reset method ====
==== Defining the Reset method ====
This method receives an start time value as parameter and sets the IInterpolator start time member to the inserted value.
This method receives an orientation value as parameter and a time value (in microseconds) as parameter and sets the IIntegrator initial orientation member and the initial time member.


<syntaxhighlight lang=c++>
<syntaxhighlight lang=c++>
RuntimeError ExampleInterpolator::Reset(const uint64_t start_time) {
RuntimeError SimpleComplementaryIntegrator::Reset(
    const Quaternion<double> initial_orient, const uint64_t initial_time) {
   RuntimeError ret{};
   RuntimeError ret{};


   /* Reset start time logic */
   /* Reset initial orientation and initial time logic */  
 
  this->initial_orient_ = /* logic result */;
  this->initial_time_ = /* logic result */;


   return ret;
   return ret;
Line 103: Line 107:
}
}
</syntaxhighlight>
</syntaxhighlight>


== Interpolator ==
== Interpolator ==

Revision as of 01:16, 2 July 2024









Introduction

Integrator

The integrator algorithms work with orientation data captured by the IMU sensor, defined as Quaternions. These algorithms estimate an object's orientation using gyroscope and accelerometer measurements for improved accuracy. An initial orientation is necessary to begin the estimation process.To add a new integrator algorithm, follow these steps:

  • Define the Integrator Algorithm class, inheriting from the IIntegrator class.
  • Add the new Integrator Algorithm to the Integrator Interface.

Define the Integrator Algorithm

The RidgeRun Integrator Interface, known as IIntegrator, is an extensible class design to support various types of integrators. To add a new integrator to it, the user must implement a new integrator class that derives from the IIntegrator class. This class must implement the following methods:

  • Apply: applies the integrator algorithm to the entry orientation data.
  • Reset: sets the initial orientation and its initial time to a desired value.


Defining the Apply method

This method receives two parameters:

  • softengyro: This contains the result of integrating the initial orientation data, it contains a vector of orientation values represented as a Quaternion with their corresponding timestamps.
  • rawgyro: This parameter contains the data from sensors, could have data from gyroscope, accelerometer and magnetometer.
RuntimeError ExampleIntegrator::Apply(
    std::vector<std::pair<Quaternion<double>, uint64_t>>& softengyro,
    const std::vector<SensorPayload> rawgyro) {
  RuntimeError ret{};

  /* Integrator algorithm logic */

  return ret;


Defining the Reset method

This method receives an orientation value as parameter and a time value (in microseconds) as parameter and sets the IIntegrator initial orientation member and the initial time member.

RuntimeError SimpleComplementaryIntegrator::Reset(
    const Quaternion<double> initial_orient, const uint64_t initial_time) {
  RuntimeError ret{};

  /* Reset initial orientation and initial time logic */ 

  this->initial_orient_ = /* logic result */;
  this->initial_time_ = /* logic result */;

  return ret;
}

Add the Interpolator Algorithm to IInterpolator

In order to add the new interpolator algorithm class to the interpolator interface follow these steps:

  • Add the constructor method to the interpolator algorithm header file.
  • Extend the Interpolator Algorithms enumeration with the new interpolation algorithm.
  • Add the interpolator algorithm to the IInterpolator Build method.

Add the constructor method

The constructor method receives the interpolator settings parameter. These settings include the interpolation interval, which is a constant time (in microseconds) that updates the initial time after each interpolation.

class ExampleInterpolator : public IInterpolator {
 public:
  explicit ExampleInterpolator(
      const std::shared_ptr<InterpolatorSettings> settings);

  /* Rest of class */

}


Extend the Interpolator Algorithms enumeration

To enable the IInterpolator interface to create an instance of the new sensor, it must be added to the InterpolatorAlgorithms enumeration.

enum class InterpolatorAlgorithms {
  kSlerp = 0,

  /* Add new interpolator algorithm */
  kExampleInterpolator
};

Add Interpolation Algorithm to IInterpolator Build method

Finally, the new interpolator case must be added to the IInterpolator build method to allow the interface to instantiate the interpolator algorithm.

std::shared_ptr<IInterpolator> IInterpolator::Build(
    const InterpolatorAlgorithms impl,
    const std::shared_ptr<InterpolatorSettings> settings) {
  switch (impl) {
    case InterpolatorAlgorithms::kSlerp:
      return std::make_shared<SlerpInterpolator>(settings);

    /* Add new interpolation algorithm case */
    case InterpolatorAlgorithms::kExampleInterpolator:
      return std::make_shared<ExampleInterpolator>(settings);

    default:
      return nullptr;
  }
}

Interpolator

The interpolator algorithms adjust the timestamps of the IMU sensor measurements to align with the timestamps of the captured frames. This alignment is necessary because the IMU sensor time and the camera sensor time (or system internal time) may not match. Therefore, the system needs to adjust the measurements based on the frame capture time. To add a new interpolator algorithm, follow these steps:

  • Define the Interpolator Algorithm class, inheriting from the IInterpolator class.
  • Add the new Interpolator Algorithm to the Interpolator Interface.

Define the Interpolator Algorithm

The RidgeRun Interpolator Interface, known as IInterpolator, is an extensible class design to support various types of interpolators. To add a new interpolator to it, the user must implement a new interpolator class that derives from the IInterpolator class. This class must implement the following methods:

  • Apply: applies the interpolator algorithm to the desired data based on a initial time.
  • Reset: sets the initial time of the interpolator to the desired value.

Defining the Apply method

This method receives two parameters:

  • softgyro: This is the input data containing a vector of orientation values (Quaternions) along with their corresponding timestamps. It is used by the interpolation algorithm.
  • interpolated: This contains a vector of interpolated orientation values with their corresponding interpolation timestamps.

The user must take into account that the method uses the IInterpolator start time member to perform the interpolation and that the time must be set on microseconds.

RuntimeError ExampleInterpolator::Apply(
    std::vector<std::pair<Quaternion<double>, uint64_t>>&interpolated,
    std::vector<std::pair<Quaternion<double>, uint64_t>>& softgyro) {
  RuntimeError ret{};

  /* Interpolation algorithm logic */

  return ret;


Defining the Reset method

This method receives an start time value as parameter and sets the IInterpolator start time member to the inserted value.

RuntimeError ExampleInterpolator::Reset(const uint64_t start_time) {
  RuntimeError ret{};

  /* Reset start time logic */

  return ret;
}

Add the Interpolator Algorithm to IInterpolator

In order to add the new interpolator algorithm class to the interpolator interface follow these steps:

  • Add the constructor method to the interpolator algorithm header file.
  • Extend the Interpolator Algorithms enumeration with the new interpolation algorithm.
  • Add the interpolator algorithm to the IInterpolator Build method.

Add the constructor method

The constructor method receives the interpolator settings parameter. These settings include the interpolation interval, which is a constant time (in microseconds) that updates the initial time after each interpolation.

class ExampleInterpolator : public IInterpolator {
 public:
  explicit ExampleInterpolator(
      const std::shared_ptr<InterpolatorSettings> settings);

  /* Rest of class */

}


Extend the Interpolator Algorithms enumeration

To enable the IInterpolator interface to create an instance of the new sensor, it must be added to the InterpolatorAlgorithms enumeration.

enum class InterpolatorAlgorithms {
  kSlerp = 0,

  /* Add new interpolator algorithm */
  kExampleInterpolator
};

Add Interpolation Algorithm to IInterpolator Build method

Finally, the new interpolator case must be added to the IInterpolator build method to allow the interface to instantiate the interpolator algorithm.

std::shared_ptr<IInterpolator> IInterpolator::Build(
    const InterpolatorAlgorithms impl,
    const std::shared_ptr<InterpolatorSettings> settings) {
  switch (impl) {
    case InterpolatorAlgorithms::kSlerp:
      return std::make_shared<SlerpInterpolator>(settings);

    /* Add new interpolation algorithm case */
    case InterpolatorAlgorithms::kExampleInterpolator:
      return std::make_shared<ExampleInterpolator>(settings);

    default:
      return nullptr;
  }
}