## arFilterTransMat
## IntroductionProvides filtering of transformation matrices (pose estimates). ## DiscussionHigh 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: ## 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.
## arFilterTransMatFilters 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 Value0 No error. ## DiscussionThis performs the filter function for a single transformation matrix. ## arFilterTransMatFinalFinalise a filter. void arFilterTransMatFinal( ARFilterTransMatInfo *ftmi); ## Parameters## DiscussionWhen all filter use has completed, this function should be called to dispose of the filter structure. ## arFilterTransMatInitInitialise 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 ValuePointer to an ARFilterTransMatInfo structure, which should be passed to other filter functions dealing with the same transformation matrix, or NULL in case of error. ## DiscussionIn 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. ## arFilterTransMatSetParamsSet 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 Value0 The filter parameters were set without error. ## DiscussionThis 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_DEFAULTDefault cutoff frequency (in Hertz). #define AR_FILTER_TRANS_MAT_CUTOFF_FREQ_DEFAULT 5.0 ## DiscussionThis value provides a default value for the cutoffFreq parameter in arFilterTransMatInit(). ## AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULTDefault sample rate (in Hertz). #define AR_FILTER_TRANS_MAT_SAMPLE_RATE_DEFAULT 30.0 ## DiscussionThis value provides a default value for the sampleRate parameter in arFilterTransMatInit(). |