Implementation of the Reduced Heteroscedastic Errors In Variables surface fitting algorithm [2]. More...

#include <rheiv.h>

Public Types
using	x_t = Eigen::Matrix< double, k, 1 >
	Input vector type $k \times 1$ .

using	xs_t = Eigen::Matrix< double, k, -1 >
	Container type for the input data array.

using	u_t = Eigen::Matrix< double, l, 1 >
	Transformed input vector type $l \times 1$ .

using	P_t = Eigen::Matrix< double, k, k >
	Covariance type of the input vector $k \times k$ .

using	Ps_t = std::vector< P_t >
	Container type for covariances `P` of the input data array.

using	z_t = Eigen::Matrix< double, lr, 1 >
	Type of a reduced transformed input vector $l_r \times 1$ .

using	zs_t = Eigen::Matrix< double, lr, -1 >
	Container type for an array of the reduced transformed input vectors `z`.

using	f_z_t = typename std::function< zs_t(const xs_t &)>
	Function signature of the $\mathbf{z}\left( \mathbf{x} \right)$ mapping function.

using	dzdx_t = Eigen::Matrix< double, lr, k >
	Type of the jacobian matrix $\mathbf{J} \mathbf{z}\left( \mathbf{x} \right)$ , evaluated at $\mathbf{x}$ .

using	dzdxs_t = std::vector< dzdx_t >
	Contained type for an array of the jacobian matrices.

using	f_dzdx_t = typename std::function< dzdx_t(const xs_t &)>
	Function signature of the jacobian $\mathbf{J} \mathbf{z}\left( \mathbf{x} \right)$ .

using	theta_t = Eigen::Matrix< double, l, 1 >
	Parameter vector type $l \times 1$ .

using	eta_t = z_t
	Reduced parameter vector type $l_r \times 1$ .

Public Member Functions
	RHEIV ()
	Convenience default constructor. More...

	RHEIV (const f_z_t &f_z, const f_dzdx_t &f_dzdx, const double min_dtheta=1e-15, const unsigned max_its=100)
	The main constructor. More...

template<typename time_t >
	RHEIV (const f_z_t &f_z, const f_dzdx_t &f_dzdx, const double min_dtheta=1e-15, const unsigned max_its=100, const time_t &timeout=std::chrono::duration_cast< time_t >(ms_t::zero()), const int debug_nth_it=-1)
	The main constructor. More...

	RHEIV (const f_z_t &f_z, const dzdx_t &dzdx, const double min_dtheta=1e-15, const unsigned max_its=100)
	A convenience constructor constructor. More...

template<typename time_t >
	RHEIV (const f_z_t &f_z, const dzdx_t &dzdx, const double min_dtheta=1e-15, const unsigned max_its=100, const time_t &timeout=std::chrono::duration_cast< time_t >(ms_t::zero()), const int debug_nth_it=-1)
	A convenience constructor constructor. More...

theta_t	fit (const xs_t &xs, const Ps_t &Ps)
	Fit the defined model to the provided data. More...

template<class T_it1 , class T_it2 >
theta_t	fit (const T_it1 &xs_begin, const T_it1 &xs_end, const T_it2 &Ps_begin, const T_it2 &Ps_end)
	Fit the defined model to the provided data. More...

theta_t	fit_ALS (const xs_t &xs)
	Fit the defined model to the provided data using Algebraic Least Squares (not RHEIV). More...

theta_t	get_last_estimate () const
	Returns the last valid estimate of $\mathbf{\theta}$ . More...

theta_t	get_ALS_estimate () const
	Returns the Algebraic Least Squares estimate of $\mathbf{\theta}$ . More...

Static Public Attributes
static const int	k = n_states
	Length of the state vector `x`.

static const int	l = n_params
	Length of the parameter vector $\mathbf{\theta}$ .

static const int	lr = l - 1
	Length of the reduced parameter vector $\mathbf{\eta}$ .

Detailed Description

template<int n_states, int n_params>
class mrs_lib::RHEIV< n_states, n_params >

Implementation of the Reduced Heteroscedastic Errors In Variables surface fitting algorithm [2].

This class estimates a vector of parameters $\mathbf{\theta}$ of a model, which is defined by an equation $\mathbf{\theta}^T \mathbf{u}\left( \mathbf{x} \right) = 0$ , where $\mathbf{x}$ is a data sample vector and $\mathbf{u}\left( \mathbf{x} \right)$ is a vector, obtained by transforming $\mathbf{x}$ in a problem-dependent manner.

Note that $\mathbf{u}\left( \mathbf{x} \right)$ must fulfill two conditions:

each element of $\mathbf{u}\left( \mathbf{x} \right)$ is a quadratic form of a vector $\left[ \mathbf{x}, 1 \right]$ , and
the last element of $\mathbf{u}\left( \mathbf{x} \right)$ is equal to one.

Such model can be used to describe e.g. various surfaces, such as planes or conics, which makes this class a useful tool for computer vision. The model is described in the context of the RHEIV class by the length of the vector $\mathbf{x}$ , the length of the vector $\mathbf{\theta}$ , and the Jacobian matrix of $\partial_{\mathbf{x}} \mathbf{z}\left( \mathbf{x} \right)$ , where $\mathbf{z}\left( \mathbf{x} \right)$ is defined by the formula $\mathbf{u}\left( \mathbf{x} \right) = \left[ \mathbf{z}\left( \mathbf{x} \right), 1 \right]$ .

For more information, see [2].

Examples: rheiv/example.cpp.

Constructor & Destructor Documentation

◆ RHEIV() [1/5]

template<int n_states, int n_params>

mrs_lib::RHEIV< n_states, n_params >::RHEIV ( )

inline

Convenience default constructor.

Warning: This constructor should not be used if applicable. If used, the main constructor has to be called afterwards, before using this class, otherwise the RHEIV object is invalid (not initialized).

◆ RHEIV() [2/5]

template<int n_states, int n_params>

mrs_lib::RHEIV< n_states, n_params >::RHEIV	(	const f_z_t &	f_z,
		const f_dzdx_t &	f_dzdx,
		const double	min_dtheta = `1e-15`,
		const unsigned	max_its = `100`
	)

inline

The main constructor.

The dzdx parameter gives the relation between $\mathbf{z}\left( \mathbf{x} \right)$ and $\mathbf{x}$ . It is the full jacobian matrix $\partial_{\mathbf{x}} \mathbf{z}\left( \mathbf{x} \right)$ .

The optimization algorithm is iterative with two possible stopping conditions:

if change of the estimate of $\mathbf{\theta}$ between two iterations is smaller than a defined threshold, or
if a maximal number of iterations was reached.

Parameters

f_z	the mapping function $\mathbf{z}\left( \mathbf{x} \right)$ .
f_dzdx	a function, returning the jacobian matrix of partial derivations of $\mathbf{z}\left( \mathbf{x} \right)$ by $\mathbf{x}$ , evaluated at $\mathbf{x}$ .
min_dtheta	if the difference of $\mathbf{\theta}_{k}$ and $\mathbf{\theta}_{k-1}$ is smaller than this number, the iteration is stopped.
max_its	if the iteration is stopped after this number of iterations.

◆ RHEIV() [3/5]

template<int n_states, int n_params>

template<typename time_t >

mrs_lib::RHEIV< n_states, n_params >::RHEIV	(	const f_z_t &	f_z,
		const f_dzdx_t &	f_dzdx,
		const double	min_dtheta = `1e-15`,
		const unsigned	max_its = `100`,
		const time_t &	timeout = `std::chrono::duration_cast<time_t>(ms_t::zero())`,
		const int	debug_nth_it = `-1`
	)

inline

The main constructor.

The dzdx parameter gives the relation between $\mathbf{z}\left( \mathbf{x} \right)$ and $\mathbf{x}$ . It is the full jacobian matrix $\partial_{\mathbf{x}} \mathbf{z}\left( \mathbf{x} \right)$ .

The optimization algorithm is iterative with two possible stopping conditions:

if change of the estimate of $\mathbf{\theta}$ between two iterations is smaller than a defined threshold, or
if a maximal number of iterations was reached.

Parameters

f_z	the mapping function $\mathbf{z}\left( \mathbf{x} \right)$ .
f_dzdx	a function, returning the jacobian matrix of partial derivations of $\mathbf{z}\left( \mathbf{x} \right)$ by $\mathbf{x}$ , evaluated at $\mathbf{x}$ .
min_dtheta	if the difference of $\mathbf{\theta}_{k}$ and $\mathbf{\theta}_{k-1}$ is smaller than this number, the iteration is stopped.
max_its	if the iteration is stopped after this number of iterations.
timeout	if the calculation takes longer than this time, the iteration is stopped.
debug_nth_it	a debug message will be printed every `debug_nth_it` th iteration (negative number disables debug).

◆ RHEIV() [4/5]

template<int n_states, int n_params>

mrs_lib::RHEIV< n_states, n_params >::RHEIV	(	const f_z_t &	f_z,
		const dzdx_t &	dzdx,
		const double	min_dtheta = `1e-15`,
		const unsigned	max_its = `100`
	)

inline

A convenience constructor constructor.

This constructor differs from the main one only in the parameters it takes. Instead of the function f_dzdx, it takes directly the dzdx matrix. This variant is meant to be used for systems where the jacobian matrix $\mathbf{z}\left( \mathbf{x} \right)$ by $\mathbf{x}$ does not depend on $\mathbf{x}$ .

Parameters

f_z	the mapping function $\mathbf{z}\left( \mathbf{x} \right)$ .
dzdx	the jacobian matrix of partial derivations of $\mathbf{z}\left( \mathbf{x} \right)$ by $\mathbf{x}$ .
min_dtheta	if the difference of $\mathbf{\theta}_{k}$ and $\mathbf{\theta}_{k-1}$ is smaller than this number, the iteration is stopped.

◆ RHEIV() [5/5]

template<int n_states, int n_params>

template<typename time_t >

mrs_lib::RHEIV< n_states, n_params >::RHEIV	(	const f_z_t &	f_z,
		const dzdx_t &	dzdx,
		const double	min_dtheta = `1e-15`,
		const unsigned	max_its = `100`,
		const time_t &	timeout = `std::chrono::duration_cast<time_t>(ms_t::zero())`,
		const int	debug_nth_it = `-1`
	)

inline

A convenience constructor constructor.

This constructor differs from the main one only in the parameters it takes. Instead of the function f_dzdx, it takes directly the dzdx matrix. This variant is meant to be used for systems where the jacobian matrix $\mathbf{z}\left( \mathbf{x} \right)$ by $\mathbf{x}$ does not depend on $\mathbf{x}$ .

Parameters

f_z	the mapping function $\mathbf{z}\left( \mathbf{x} \right)$ .
dzdx	the jacobian matrix of partial derivations of $\mathbf{z}\left( \mathbf{x} \right)$ by $\mathbf{x}$ .
min_dtheta	if the difference of $\mathbf{\theta}_{k}$ and $\mathbf{\theta}_{k-1}$ is smaller than this number, the iteration is stopped.
timeout	if the calculation takes longer than this time, the iteration is stopped.
max_its	if the iteration is stopped after this number of iterations.
debug_nth_it	a debug message will be printed every `debug_nth_it` th iteration (negative number disables debug).

Member Function Documentation

◆ fit() [1/2]

template<int n_states, int n_params>

template<class T_it1 , class T_it2 >

theta_t mrs_lib::RHEIV< n_states, n_params >::fit	(	const T_it1 &	xs_begin,
		const T_it1 &	xs_end,
		const T_it2 &	Ps_begin,
		const T_it2 &	Ps_end
	)

inline

Fit the defined model to the provided data.

The RHEIV iterative optimization algorithm will be applied to estimate optimal parameters of the model based on the provided data. This is a conveinence overload, which takes the data points and covariances in a general container, supporting std::begin() and std::end().

Parameters

xs_begin	begin iterator of a container, containing the data points $\mathbf{x}_i$ .
xs_end	end iterator of a container, containing the data points $\mathbf{x}_i$ .
Ps_begin	begin iterator of a container, containing the corresponding covariance matrices $\mathbf{P}_i$ .
Ps_end	end iterator of a container, containing the corresponding covariance matrices $\mathbf{P}_i$ .

Returns: estimate of the parameter vector $\mathbf{\theta}$ .

Warning: Note that length of xs and Ps must be the same!

◆ fit() [2/2]

template<int n_states, int n_params>

theta_t mrs_lib::RHEIV< n_states, n_params >::fit	(	const xs_t &	xs,
		const Ps_t &	Ps
	)

inline

Fit the defined model to the provided data.

The RHEIV iterative optimization algorithm will be applied to estimate optimal parameters of the model based on the provided data.

Parameters

xs	the data points $\mathbf{x}_i$ .
Ps	the corresponding covariance matrices $\mathbf{P}_i$ .

Returns: estimate of the parameter vector $\mathbf{\theta}$ .

Warning: Note that length of xs and Ps must be the same!

◆ fit_ALS()

template<int n_states, int n_params>

theta_t mrs_lib::RHEIV< n_states, n_params >::fit_ALS ( const xs_t & xs )

inline

Fit the defined model to the provided data using Algebraic Least Squares (not RHEIV).

Instead of using the iterative RHEIV algorithm to fit the data, just use the simple ALS (which basically does eigenvector decomposition). This can be useful in cases of degenerate data where the RHEIV algorithm fails or when covariances of the data are not available.

Parameters

xs	the data points $\mathbf{x}_i$ .

Returns: estimate of the parameter vector $\mathbf{\theta}$ .

◆ get_ALS_estimate()

template<int n_states, int n_params>

theta_t mrs_lib::RHEIV< n_states, n_params >::get_ALS_estimate ( ) const

inline

Returns the Algebraic Least Squares estimate of $\mathbf{\theta}$ .

You can use this method in case of an exception to retreive the Algebraic Least Squares estimate of the parameter vector, which is more stable than the RHEIV algorithm, and can be used as a more rough estimate of the parameters.

Returns: the ALS estimate of the parameter vector $\mathbf{\theta}$ .

Warning: The fit() method must be called prior to attempting to get the last ALS estimate!

◆ get_last_estimate()

template<int n_states, int n_params>

theta_t mrs_lib::RHEIV< n_states, n_params >::get_last_estimate ( ) const

inline

Returns the last valid estimate of $\mathbf{\theta}$ .

You can use this method in case of an exception to retreive the last valid estimate of the parameter vector before the crash, which is sometimes useful.

Returns: the last valid estimate of the parameter vector $\mathbf{\theta}$ .

Warning: The fit() method must be called prior to attempting to get the last valid estimate!

The documentation for this class was generated from the following file:

include/mrs_lib/rheiv.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

template<int n_states, int n_params> class mrs_lib::RHEIV< n_states, n_params >

Constructor & Destructor Documentation

◆ RHEIV() [1/5]

◆ RHEIV() [2/5]

◆ RHEIV() [3/5]

◆ RHEIV() [4/5]

◆ RHEIV() [5/5]

Member Function Documentation

◆ fit() [1/2]

◆ fit() [2/2]

◆ fit_ALS()

◆ get_ALS_estimate()

◆ get_last_estimate()

template<int n_states, int n_params>
class mrs_lib::RHEIV< n_states, n_params >