| # 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 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 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 © 2015 Daqri, LLC. Last Updated: Monday, October 05, 2015