arFilterTransMat

Includes:

Introduction

Provides filtering of transformation matrices (pose estimates).

Discussion

High frequency noise ("jitter") can be an undesirable property in optical tracking systems like ARToolKit. 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().

Functions

arFilterTransMat: Filters the supplied pose estimate transformation matrix in-place.
arFilterTransMatFinal: Finalise a filter.
arFilterTransMatInit: Initialise a filter for a single transformation matrix (pose estimate).
arFilterTransMatSetParams: Set the filter parameters.

arFilterTransMat

Filters the supplied pose estimate transformation matrix in-place.

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

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.

Return Value

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

Discussion

This performs the filter function for a single transformation matrix.

arFilterTransMatFinal

Finalise a filter.

void arFilterTransMatFinal(
    ARFilterTransMatInfo *ftmi);

Parameters

ftmi: Filter settings to dispose of.

Discussion

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

arFilterTransMatInit

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

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

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.

Return Value

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.

Discussion

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.

arFilterTransMatSetParams

Set the filter parameters.

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

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.

Return Value

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

Discussion

This convenience function allows adjustment of the initial filter parameters.

Macro Definitions

AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT: Default cutoff frequency (in Hertz).
AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT: Default sample rate (in Hertz).

AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT

Default cutoff frequency (in Hertz).

#define AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT 5.0

Discussion

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

AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT

Default sample rate (in Hertz).

#define AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT 30.0

Discussion

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

Last Updated: Tuesday, May 08, 2012