#include <superviseddescent.hpp>

Public Member Functions
	SupervisedDescentOptimiser ()=default

	SupervisedDescentOptimiser (std::vector< RegressorType > regressors, NormalisationStrategy normalisation=NoNormalisation())

template<class ProjectionFunction >
void	train (cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection)

template<class ProjectionFunction , class OnTrainingEpochCallback >
void	train (cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection, OnTrainingEpochCallback on_training_epoch_callback)

template<class ProjectionFunction >
cv::Mat	test (cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection)

template<class ProjectionFunction , class OnRegressorIterationCallback >
cv::Mat	test (cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection, OnRegressorIterationCallback on_regressor_iteration_callback)

template<class ProjectionFunction >
cv::Mat	predict (cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection)

Friends
class	cereal::access

Detailed Description

template<class RegressorType, class NormalisationStrategy = NoNormalisation>
class superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >

The heart of the library: The main class that performs learning of the gradient, testing and predicting of values.

The class takes a RegressorType as template parameter to specify a learning algorithm to use. As an example, use a LinearRegressor from regressors.hpp. To use your own learning algorithm, implement the functions of the abstract class Regressor.

Constructor & Destructor Documentation

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::SupervisedDescentOptimiser ( )

default

Construct an empty optimiser, with no regressors.

We allow to create an empty SupervisedDescentOptimiser to facilitate serialisation.

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::SupervisedDescentOptimiser	(	std::vector< RegressorType >	regressors,
		NormalisationStrategy	normalisation = `NoNormalisation()`
	)

inline

Construct an optimiser with one or several regressors in series.

Parameters

[in]	regressors	One or several regressors.
[in]	normalisation	Normalisation strategy for the data during optimisation.

Member Function Documentation

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

template<class ProjectionFunction >

cv::Mat superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::predict	(	cv::Mat	initialisations,
		cv::Mat	templates,
		ProjectionFunction	projection
	)

inline

Predicts the result value for a single example, using the learned regressors.

The input matrices should only contain one row (i.e. one training example).

y can either be given or set to empty (=cv::Mat()), according to what was learned during training.

For a detailed explanation of the parameters, see train(cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection).

Parameters

[in]	initialisations	Initialisation values for the parameters. Constant in case 1) and variable in case 2).
[in]	templates	An optional matrix of template values. See description above.
[in]	projection	The projection function that projects the given parameter values to the space of the template values. Could be a simple function like sin(x), a projection from 3D to 2D space, or a HoG feature transform.

Returns: Returns the predicted parameters for the given test example.

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

template<class ProjectionFunction >

cv::Mat superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::test	(	cv::Mat	initialisations,
		cv::Mat	templates,
		ProjectionFunction	projection
	)

inline

Tests the learned regressor model with the given test data.

The test data should be specified as one row per example.

y can either be given or set to empty (=cv::Mat()), according to what was learned during training.

For a detailed explanation of the parameters, see train(cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection).

Calls the testing with a default (no-op) callback function. To specify a callback function, see the overload test(cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection, OnRegressorIterationCallback onRegressorIterationCallback).

Parameters

[in]	initialisations	Initialisation values for the parameters. Constant in case 1) and variable in case 2).
[in]	templates	An optional matrix of template values. See description above.
[in]	projection	The projection function that projects the given parameter values to the space of the template values. Could be a simple function like sin(x), a projection from 3D to 2D space, or a HoG feature transform.

Returns: Returns the final prediction of all given test examples.

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

template<class ProjectionFunction , class OnRegressorIterationCallback >

cv::Mat superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::test	(	cv::Mat	initialisations,
		cv::Mat	templates,
		ProjectionFunction	projection,
		OnRegressorIterationCallback	on_regressor_iteration_callback
	)

inline

Identical to test(cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection), but allows to specify a callback function that gets called with the current prediction after applying each regressor.

The signature of the callback function must take a cv::Mat with the current predictions and can capture any additional variables from the surrounding context. For example, to print the normalised least squares residual between groundtruth and the current predictions:

auto print_residual = [&groundtruth](const cv::Mat& current_predictions) {
 std::cout << cv::norm(current_predictions, groundtruth, cv::NORM_L2) / cv::norm(groundtruth, cv::NORM_L2) << std::endl;
};

Tests the learned regressor model with the given test data.

The test data should be specified as one row per example.

y can either be given or set to empty (=cv::Mat()), according to what was learned during training.

For a detailed explanation of the parameters, see train(cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection).

Calls the testing with a default (no-op) callback function. To specify a callback function, see the overload test(cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection, OnRegressorIterationCallback onRegressorIterationCallback).

Parameters

[in]	initialisations	Initialisation values for the parameters. Constant in case 1) and variable in case 2).
[in]	templates	An optional matrix of template values. See description above.
[in]	projection	The projection function that projects the given parameter values to the space of the template values. Could be a simple function like sin(x), a projection from 3D to 2D space, or a HoG feature transform.

Returns: Returns the final prediction of all given test examples.

Parameters

[in] on_regressor_iteration_callback A callback function that gets called after each applied regressor, with the current prediction result.

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

template<class ProjectionFunction >

void superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::train	(	cv::Mat	parameters,
		cv::Mat	initialisations,
		cv::Mat	templates,
		ProjectionFunction	projection
	)

inline

Train the regressor model from the given training data.

The function takes as input a set of ground truth parameters (parameters), initialisation values for these parameters (initialisations), an optional set of templates (templates) (see description below) and a function projection that is applied to the parameters.

In [1], the parameters are called \( x \), the initialisations are \( x_0 \), the templates \( y \) and the projection function is denoted as \( h \).

The templates y can either be given or set to empty (=cv::Mat()); There are two cases:

\( y \) is known at testing time, i.e. a fixed template. For example pose estimation using given landmarks (= \( y \)).
\( y \) is not known at testing time. For example landmark detection, where we don't know \( y \) at testing (the e.g. HoG values are different for each testing face).

Example cases:

\( x \) = the 6 DOF pose parameters (R, t); \( y \) = 2D landmark positions; \( x_0 \) = const; \( h \) = projection from 3D model to 2D, using current params \( x \).
\( x \) = groundtruth landmarks - the final location we want to be, i.e. our parameters; no \( y \) in both training and test; \( x_0 \) = landmark locations after e.g. initialisation with a facedetector; \( h \) = HoG feature extraction at the current landmark locations x.

projection is a function that takes one training sample (a cv::Mat row vector) and returns a cv::Mat row-vector.

This function calls a default (no-op) callback function after training of each regressor. To specify a callback function, see the overload train(cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection, OnTrainingEpochCallback onTrainingEpochCallback).

Parameters

[in]	parameters	A matrix of ground truth values of parameters, with each row being one training example. These are the parameters we want to learn.
[in]	initialisations	Initialisation values for the parameters. Constant in case 1) and variable in case 2).
[in]	templates	An optional matrix of template values. See description above.
[in]	projection	The projection function that projects the given parameter values to the space of the template values. Could be a simple function like sin(x), a projection from 3D to 2D space, or a HoG feature transform.

template<class RegressorType , class NormalisationStrategy = NoNormalisation>

template<class ProjectionFunction , class OnTrainingEpochCallback >

void superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >::train	(	cv::Mat	parameters,
		cv::Mat	initialisations,
		cv::Mat	templates,
		ProjectionFunction	projection,
		OnTrainingEpochCallback	on_training_epoch_callback
	)

inline

Identical to train(cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection), but allows to specify a callback function that gets called with the current prediction after every regressor.

The signature of the callback function must take a cv::Mat with the current predictions and can capture any additional variables from the surrounding context. For example, to print the normalised least squares residual between groundtruth and the current predictions:

auto print_residual = [&groundtruth](const cv::Mat& current_predictions) {
 std::cout << cv::norm(current_predictions, groundtruth, cv::NORM_L2) / cv::norm(groundtruth, cv::NORM_L2) << std::endl;
};

Train the regressor model from the given training data.

The function takes as input a set of ground truth parameters (parameters), initialisation values for these parameters (initialisations), an optional set of templates (templates) (see description below) and a function projection that is applied to the parameters.

In [1], the parameters are called \( x \), the initialisations are \( x_0 \), the templates \( y \) and the projection function is denoted as \( h \).

The templates y can either be given or set to empty (=cv::Mat()); There are two cases:

\( y \) is known at testing time, i.e. a fixed template. For example pose estimation using given landmarks (= \( y \)).
\( y \) is not known at testing time. For example landmark detection, where we don't know \( y \) at testing (the e.g. HoG values are different for each testing face).

Example cases:

\( x \) = the 6 DOF pose parameters (R, t); \( y \) = 2D landmark positions; \( x_0 \) = const; \( h \) = projection from 3D model to 2D, using current params \( x \).
\( x \) = groundtruth landmarks - the final location we want to be, i.e. our parameters; no \( y \) in both training and test; \( x_0 \) = landmark locations after e.g. initialisation with a facedetector; \( h \) = HoG feature extraction at the current landmark locations x.

projection is a function that takes one training sample (a cv::Mat row vector) and returns a cv::Mat row-vector.

This function calls a default (no-op) callback function after training of each regressor. To specify a callback function, see the overload train(cv::Mat parameters, cv::Mat initialisations, cv::Mat templates, ProjectionFunction projection, OnTrainingEpochCallback onTrainingEpochCallback).

Parameters

[in]	parameters	A matrix of ground truth values of parameters, with each row being one training example. These are the parameters we want to learn.
[in]	initialisations	Initialisation values for the parameters. Constant in case 1) and variable in case 2).
[in]	templates	An optional matrix of template values. See description above.
[in]	projection	The projection function that projects the given parameter values to the space of the template values. Could be a simple function like sin(x), a projection from 3D to 2D space, or a HoG feature transform.
[in]	on_training_epoch_callback	A callback function that gets called after the training of each individual regressor.

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

include/superviseddescent/superviseddescent.hpp

Public Member Functions

Friends

Detailed Description

template<class RegressorType, class NormalisationStrategy = NoNormalisation> class superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >

Constructor & Destructor Documentation

Member Function Documentation

template<class RegressorType, class NormalisationStrategy = NoNormalisation>
class superviseddescent::SupervisedDescentOptimiser< RegressorType, NormalisationStrategy >