arFilterTransMat.h File Reference

Provides filtering of transformation matrices (pose estimates). More...

#include <ARX/AR/ar.h>

Include dependency graph for arFilterTransMat.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT   30.0
	Default sample rate (in Hertz).
#define	AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT   15.0
	Default cutoff frequency (in Hertz).

Typedefs
typedef struct _ARFilterTransMatInfo	ARFilterTransMatInfo

Functions
ARFilterTransMatInfo *	arFilterTransMatInit (const ARdouble sampleRate, const ARdouble cutoffFreq)
	Initialise a filter for a single transformation matrix (pose estimate).
int	arFilterTransMatSetParams (ARFilterTransMatInfo *ftmi, const ARdouble sampleRate, const ARdouble cutoffFreq)
	Set the filter parameters.
int	arFilterTransMat (ARFilterTransMatInfo *ftmi, ARdouble m[3][4], const int reset)
	Filters the supplied pose estimate transformation matrix in-place.
void	arFilterTransMatFinal (ARFilterTransMatInfo *ftmi)
	Finalise a filter.

Detailed Description

Provides filtering of transformation matrices (pose estimates).

High frequency noise ("jitter") can be an undesirable property in optical tracking systems like artoolkitX. These functions implement a first-order low-pass filter for both the position and orientation components of the pose estimate transformation matrices.

Usage:
For each pose estimate which is to be filtered, an ARFilterTransMatInfo structure should be allocated by calling arFilterTransMatInit(). Samples are then added to the filter and the filtered value returned by calling arFilterTransMat(). At the end of operations, the filter should be disposed of by calling arFilterTransMatFinal().

Macro Definition Documentation

AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT

#define AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT   15.0

Default cutoff frequency (in Hertz).

@defined

This value provides a default value for the cutoffFreq parameter in arFilterTransMatInit().

AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT

#define AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT   30.0

Default sample rate (in Hertz).

@defined

This value provides a default value for the sampleRate parameter in arFilterTransMatInit().

Typedef Documentation

ARFilterTransMatInfo

typedef struct _ARFilterTransMatInfo ARFilterTransMatInfo

Function Documentation

arFilterTransMat()

int arFilterTransMat	(	ARFilterTransMatInfo *	ftmi,
		ARdouble	m[3][4],
		const int	reset
	)

Filters the supplied pose estimate transformation matrix in-place.

This performs the filter function for a single transformation matrix.

Parameters

ftmi	Filter settings to be used with this transformation matrix.
m	Transformation matrix representing the current pose estimate.
reset	If a discontinuity in transformation matrix pose estimates has occured (e.g. when a marker is first acquired, or is reacquired after a period of not being visible) the filter initial state or "memory" should be set to the same value as the current sample by setting this parameter to 1. If transformation matrix pose estimates have occured continuously, set this parameter to 0.

Returns

0 No error.
-1 Invalid parameter.
-2 Invalid transformation matrix.

Here is the call graph for this function:

arFilterTransMatFinal()

void arFilterTransMatFinal

(

ARFilterTransMatInfo *

ftmi

)

Finalise a filter.

When all filter use has completed, this function should be called to dispose of the filter structure.

Parameters

ftmi	Filter settings to dispose of.

arFilterTransMatInit()

ARFilterTransMatInfo * arFilterTransMatInit	(	const ARdouble	sampleRate,
		const ARdouble	cutoffFreq
	)

Initialise a filter for a single transformation matrix (pose estimate).

In order to filter a pose estimate, this function should be called to setup filter data structures.

Each ARFilterTransMatInfo structure should be used only with a single transformation matrix. For example, if you have 5 pose estimates to filter, you would call this function 5 times, once for each pose, and keep the pose data and filter data paired.

The structure produced should be passed to other filter functions dealing with the same transformation matrix.

Parameters

sampleRate

This value partially determines the filter properties. It should be as close as possible to the rate at which pose estimates arrive, which is usually the camera frame rate. If you are unsure what value to use, use the constant AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT. This value may not be 0.0.

cutoffFreq

This value partially determines the filter properties. It should be as close as possible to the rate above which you do not wish changes to the incoming transformation matrix pose estimate to be observed. This would usually be the maximum rate at which you imagine to-and-fro rotiational or positional motion of a marker to occur. If you are unsure what value to use, use the constant AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT. This value may not be 0.0.

Returns

Pointer to an ARFilterTransMatInfo structure, which should be passed to other filter functions dealing with the same transformation matrix, or NULL in case of error.

Here is the call graph for this function:

arFilterTransMatSetParams()

int arFilterTransMatSetParams	(	ARFilterTransMatInfo *	ftmi,
		const ARdouble	sampleRate,
		const ARdouble	cutoffFreq
	)

Set the filter parameters.

This convenience function allows adjustment of the initial filter parameters.

Parameters

ftmi	Filter settings of which the parameters should be set.
sampleRate	This value partially determines the filter properties. It should be as close as possible to the rate at which pose estimates arrive, which is usually the camera frame rate. If you are unsure what value to use, use the constant AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT. This value may not be 0.0.
cutoffFreq	This value partially determines the filter properties. It should be as close as possible to the rate above which you do not wish changes to the incoming transformation matrix pose estimate to be observed. This would usually be the maximum rate at which you imagine to-and-fro rotiational or positional motion of a marker to occur. If you are unsure what value to use, use the constant AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT. This value may not be 0.0.

Returns

0 The filter parameters were set without error.
-1 Invalid parameter.
-2 One of the parameters was 0.0.