tracking

Includes:

<thread_sub.h>
<AR/ar.h>
<AR/icp.h>
<AR2/config.h>
<AR2/featureSet.h>
<AR2/template.h>
<AR2/marker.h>

Introduction

ARToolKit NFT core routines.

Discussion

This header declares essential types and API for the NFT portion of the ARToolKit SDK.

For compile-time per-machine and NFT configuration, see <AR2/config.h>.

Functions

ar2CreateHandle: Allocate and initialise essential structures for NFT texture tracking, using full six degree-of-freedom tracking.
ar2CreateHandleHomography: Allocate and initialise essential structures for NFT texture tracking, using homography-only tracking.
ar2DeleteHandle: Finalise and dispose of structures for NFT texture tracking.
ar2FreeSurfaceSet: Finalise and dispose of an NFT texture tracking surface set.
ar2GetSearchFeatureNum
ar2GetSearchSize: Get feature point search window size.
ar2GetSimThresh
ar2GetTemplateSize1
ar2GetTemplateSize2
ar2GetTrackingMode: Report whether an AR2HandleT is providing full 6 degree-of-freedom tracking or homography extraction only.
ar2GetTrackingThresh: Get threshold value for acceptable pose estimate error.
ar2ReadSurfaceSet: Read an NFT texture tracking surface set from file.
ar2SetInitTrans: Sets initial transform for subsequent NFT texture tracking.
ar2SetSearchFeatureNum
ar2SetSearchSize: Set feature point search window size.
ar2SetSimThresh
ar2SetTemplateSize1
ar2SetTemplateSize2
ar2SetTrackingMode: Choose whether full 6 degree-of-freedom tracking is performed, or homography extraction only.
ar2SetTrackingThresh: Set threshold value for acceptable pose estimate error.
ar2Tracking: Perform NFT texture tracking on an image frame.

ar2CreateHandle

Allocate and initialise essential structures for NFT texture tracking, using full six degree-of-freedom tracking.

AR2HandleT *ar2CreateHandle (
    ARParamLT *cparamLT,
    AR_PIXEL_FORMAT pixFormat,
    int threadNum );

Parameters

cparamLT: Pointer to an ARParamLT structure holding camera parameters in lookup-table form. The pointer only is copied, and the ARParamLT structure itself is NOT copied, and must remain valid for the lifetime of the AR2HandleT. This structure also specifies the size of video frames which will be later supplied to the ar2Tracking() function as cparamLT->param.xsize and cparamLT->param.ysize.
pixFormat: Pixel format of video frames which will be later supplied to the ar2Tracking() function.
threadNum: Number of threads to spawn for the NFT texture tracking task. Use AR2_TRACKING_DEFAULT_THREAD_NUM to have ARToolKit calculate a sensible default.

Return Value

Pointer to a newly allocated AR2HandleT structure, which holds the current state of the NFT texture tracker, or NULL if an error occurred. This structure must be deallocated via a call to ar2DeleteHandle() when no longer needed.

Discussion

Full 6 degree-of-freedom tracking requires a calibrated camera lens model, and provides measurement of surface position in all axes, as well as orientation.

See Also

ar2CreateHandleHomography
ar2DeleteHandle

ar2CreateHandleHomography

Allocate and initialise essential structures for NFT texture tracking, using homography-only tracking.

AR2HandleT *ar2CreateHandleHomography (
    int xsize,
    int ysize,
    AR_PIXEL_FORMAT pixFormat,
    int threadNum );

Parameters

xsize: Width of video frames which will be later supplied to the ar2Tracking() function.
ysize: Height of video frames which will be later supplied to the ar2Tracking() function.
pixFormat: Pixel format of video frames which will be later supplied to the ar2Tracking() function.
threadNum: Number of threads to spawn for the NFT texture tracking task. Use AR2_TRACKING_DEFAULT_THREAD_NUM to have ARToolKit calculate a sensible default.

Return Value

Discussion

Homography tracking assumes that the camera has zero lens-distortion, and this does not depend on camera parameters. It is therefore unable to provide correctly calibrated position measurements, but the resulting pose is suitable for visual overlay purposes.

See Also

ar2CreateHandle
ar2DeleteHandle

ar2DeleteHandle

Finalise and dispose of structures for NFT texture tracking.

int ar2DeleteHandle (
    AR2HandleT **ar2Handle );

Parameters

ar2Handle: Pointer to a location which holds a pointer to a AR2HandleT structure. On return, the location pointed to will be set to NULL.

Return Value

-1 in case of error, or 0 otherwise.

Discussion

Once texture tracking processing has completed, this routine should be called to dispose of memory allocated.

See Also

ar2CreateHandle
ar2CreateHandleHomography

ar2FreeSurfaceSet

Finalise and dispose of an NFT texture tracking surface set.

int ar2FreeSurfaceSet (
    AR2SurfaceSetT **surfaceSet );

Parameters

surfaceSet: Pointer to a location pointing to an AR2SurfaceSetT. On return, this pointer will be set to NULL.

Return Value

0 if successful, -1 otherwise.

Discussion

Once a surface set (read by ar2ReadSurfaceSet()) is no longer required, it should be disposed of by calling ar2FreeSurfaceSet().

See Also

ar2ReadSurfaceSet

ar2GetSearchFeatureNum

int ar2GetSearchFeatureNum (
    AR2HandleT *ar2Handle,
    int *searchTemplateMax );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
searchTemplateMax

Return Value

-1 in case of error, or 0 otherwise.

ar2GetSearchSize

Get feature point search window size.

int ar2GetSearchSize (
    AR2HandleT *ar2Handle,
    int *searchSize );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
searchSize: Pointer to an int, which on return will be filled with the current search size in use.

Return Value

-1 in case of error, or 0 otherwise.

Discussion

See the discussion under ar2SetSearchSize.

Default value is AR2_DEFAULT_SEARCH_SIZE, as defined in <AR2/config.h>

See Also

ar2SetSearchSize

ar2GetSimThresh

int ar2GetSimThresh (
    AR2HandleT *ar2Handle,
    float *simThresh );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
simThresh

Return Value

-1 in case of error, or 0 otherwise.

ar2GetTemplateSize1

int ar2GetTemplateSize1 (
    AR2HandleT *ar2Handle,
    int *templateSize1 );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
templateSize1

Return Value

-1 in case of error, or 0 otherwise.

ar2GetTemplateSize2

int ar2GetTemplateSize2 (
    AR2HandleT *ar2Handle,
    int *templateSize2 );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
templateSize2

Return Value

-1 in case of error, or 0 otherwise.

ar2GetTrackingMode

Report whether an AR2HandleT is providing full 6 degree-of-freedom tracking or homography extraction only.

int ar2GetTrackingMode (
    AR2HandleT *ar2Handle,
    int *trackingMode );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
trackingMode

Return Value

-1 in case of error, or 0 otherwise.

See Also

ar2CreateHandle
ar2CreateHandleHomography
ar2SetTrackingMode

ar2GetTrackingThresh

Get threshold value for acceptable pose estimate error.

int ar2GetTrackingThresh (
    AR2HandleT *ar2Handle,
    float *trackingThresh );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
trackingThresh: Pointer to a float, which on return will be filled with the threshold value.

Return Value

-1 in case of error, or 0 otherwise.

Discussion

See the discussion under ar2SetTrackingThresh.

Default value is AR2_DEFAULT_TRACKING_THRESH, as defined in <AR2/config.h>

See Also

ar2SetTrackingThresh

ar2ReadSurfaceSet

Read an NFT texture tracking surface set from file.

AR2SurfaceSetT *ar2ReadSurfaceSet (
    const char *filename,
    const char *ext,
    ARPattHandle *pattHandle );

Parameters

filename: Pathname of the surface set to be loaded, less any filename extension.
ext: Filename extension of the surface set to be loaded. Ususally this will be "fset".
pattHandle: If the surface set includes, template markers, a valid ARPattHandle is required to be passed in this parameter. Otherwise, NULL may be passed.

Return Value

A pointer to the loaded AR2SurfaceSetT, or NULL in case of error.

Discussion

Allocates, initialises and reads the contents of a surface set from storage. The surface set is usually generated by the genTexData utility, or equivalent.

Once the surface set is no longer required, it should be disposed of by calling ar2FreeSurfaceSet().

See Also

ar2FreeSurfaceSet

ar2SetInitTrans

Sets initial transform for subsequent NFT texture tracking.

int ar2SetInitTrans (
    AR2SurfaceSetT *surfaceSet,
    float trans[3][4] );

Parameters

surfaceSet
trans: Pointer to a float[3][4] array from which the initial transform will be copied.

Return Value

0 if successful, or -1 in case of error.

Discussion

Before the first call to ar2Tracking(), this function must be called to set the initial tracking transform. The initial transform may be obtained from NFT KPM tracking, or via a fiducial marker embedded in the NFT image. The initial transform must also be set after each loss of tracking (i.e. after each instance when ar2Tracking() does not return 0.

See Also

ar2Tracking

ar2SetSearchFeatureNum

int ar2SetSearchFeatureNum (
    AR2HandleT *ar2Handle,
    int searchTemplateMax );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
searchTemplateMax

Return Value

-1 in case of error, or 0 otherwise.

ar2SetSearchSize

Set feature point search window size.

int ar2SetSearchSize (
    AR2HandleT *ar2Handle,
    int searchSize );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
searchSize: The new search size to use.

Return Value

-1 in case of error, or 0 otherwise.

Discussion

Sets the size of the window around a feature location from previous frame in which the feature will be searched for in the next frame. Value is radius of the search window, in pixels. I.e. searchSize pixels either size of the current feature position will be searched for the new location of the feature.

A larger search window allows for greater movement of a feature between frames (e.g. faster optical motion, or same degree of optical motion but at a higher frame resolution), at the cost of greater search effort. Search effort increases with the square of the search radius.

Default value is AR2_DEFAULT_SEARCH_SIZE, as defined in <AR2/config.h>

See Also

ar2GetSearchSize

ar2SetSimThresh

int ar2SetSimThresh (
    AR2HandleT *ar2Handle,
    float simThresh );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
simThresh

Return Value

-1 in case of error, or 0 otherwise.

ar2SetTemplateSize1

int ar2SetTemplateSize1 (
    AR2HandleT *ar2Handle,
    int templateSize1 );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
templateSize1

Return Value

-1 in case of error, or 0 otherwise.

ar2SetTemplateSize2

int ar2SetTemplateSize2 (
    AR2HandleT *ar2Handle,
    int templateSize2 );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
templateSize2

Return Value

-1 in case of error, or 0 otherwise.

ar2SetTrackingMode

Choose whether full 6 degree-of-freedom tracking is performed, or homography extraction only.

int ar2SetTrackingMode (
    AR2HandleT *ar2Handle,
    int trackingMode );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
trackingMode: Either AR2_TRACKING_6DOF or AR2_TRACKING_HOMOGRAPHY.

Return Value

-1 in case of error, or 0 otherwise.

Discussion

Note that while it is possible to switch an AR2HandleT created in 6DOF mode (via ar2CreateHandle) to HOMOGRAPHY mode and back to 6DOF ,an AR2HandleT created in HOMOGRAPHY mode (via ar2CreateHandleHomography) cannot be switched to 6DOF mode.

See Also

ar2CreateHandle
ar2CreateHandleHomography
ar2GetTrackingMode

ar2SetTrackingThresh

Set threshold value for acceptable pose estimate error.

int ar2SetTrackingThresh (
    AR2HandleT *ar2Handle,
    float trackingThresh );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
trackingThresh: floating point value to use as the new tracking threshold.

Return Value

-1 in case of error, or 0 otherwise.

Discussion

During the final phase of a single tracking pass, the pose estimate is calculated, along with an estimate of the error in this value (an uncertainty). A higher value indicates less goodness-of-fit of the pose estimate to the data. If only high-quality pose estimates are desired, this function can be used to lower the acceptable maximum error value.

The actual error value itself is reported in parameter 'err' of function ar2Tracking.

Default value is AR2_DEFAULT_TRACKING_THRESH, as defined in <AR2/config.h>

See Also

ar2GetTrackingThresh
ar2Tracking

ar2Tracking

Perform NFT texture tracking on an image frame.

int ar2Tracking (
    AR2HandleT *ar2Handle,
    AR2SurfaceSetT *surfaceSet, 
    ARUint8 *dataPtr,
    float trans[3][4],
    float *err );

Parameters

ar2Handle: Tracking settings structure, as returned via ar2CreateHandle.
surfaceSet: Tracking surface set, as returned via ar2ReadSurfaceSet.
dataPtr: Pointer to image data on which tracking will be performed.
trans: Pointer to a float[3][4] array which will be filled out with the pose.
err: On successful return, will be filled out with pose error value.

Return Value

0 in case of successful tracking, or < 0 in case of error. Error codes:
-1: Bad parameter
-2: Tracking not initialised
-3: Insufficient texture features
-4: Pose error exceeds value set with ar2SetTrackingThresh()

Discussion

Before the first call to this function, ar2SetInitTrans() must be called to set the initial tracking transform. The initial transform may be obtained from NFT KPM tracking, or via a fiducial marker embedded in the NFT image. The initial transform must also be set after each loss of tracking (i.e. after each instance when this function does not return 0.

See Also

ar2SetInitTrans
ar2SetTrackingThresh
ar2CreateHandle
ar2ReadSurfaceSet

Last Updated: Wednesday, March 23, 2016