| ARX 1.0 The next-generation open source augmented reality toolkit.

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
tracking.h File Reference
`#include <ARX/ARUtil/thread_sub.h>`
`#include <ARX/AR/ar.h>`
`#include <ARX/AR/icp.h>`
`#include <ARX/AR2/config.h>`
`#include <ARX/AR2/featureSet.h>`
`#include <ARX/AR2/template.h>`
`#include <ARX/AR2/marker.h>`
Include dependency graph for tracking.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes
struct | AR2SurfaceT
struct | AR2SurfaceSetT
struct | AR2Tracking2DResultT
struct | _AR2Tracking2DParamT
struct | _AR2HandleT

## Macros
#define | AR2_TRACKING_6DOF 1
| artoolkitX NFT core routines.
#define | AR2_TRACKING_HOMOGRAPHY 2
#define | AR2_TRACKING_DEFAULT_THREAD_NUM -1

## Typedefs
typedef struct _AR2HandleT | AR2HandleT
typedef struct _AR2Tracking2DParamT | AR2Tracking2DParamT

## Functions
int | ar2Tracking (AR2HandleT *ar2Handle, AR2SurfaceSetT *surfaceSet, ARUint8 *dataPtr, float trans[3][4], float *err)
void * | ar2Tracking2d (THREAD_HANDLE_T *threadHandle)
AR2SurfaceSetT * | ar2ReadSurfaceSet (const char *filename, const char *ext, ARPattHandle *pattHandle)
int | ar2FreeSurfaceSet (AR2SurfaceSetT **surfaceSet)
int | ar2SetInitTrans (AR2SurfaceSetT *surfaceSet, float trans[3][4])
AR2HandleT * | ar2CreateHandle (ARParamLT *cparamLT, AR_PIXEL_FORMAT pixFormat, int threadNum)
AR2HandleT * | ar2CreateHandleHomography (int xsize, int ysize, AR_PIXEL_FORMAT pixFormat, int threadNum)
int | ar2DeleteHandle (AR2HandleT **ar2Handle)
int | ar2SetSearchSize (AR2HandleT *ar2Handle, int searchSize)
int | ar2GetSearchSize (AR2HandleT *ar2Handle, int *searchSize)
int | ar2SetTemplateSize1 (AR2HandleT *ar2Handle, int templateSize1)
int | ar2GetTemplateSize1 (AR2HandleT *ar2Handle, int *templateSize1)
int | ar2SetTemplateSize2 (AR2HandleT *ar2Handle, int templateSize2)
int | ar2GetTemplateSize2 (AR2HandleT *ar2Handle, int *templateSize2)
int | ar2SetSearchFeatureNum (AR2HandleT *ar2Handle, int searchTemplateMax)
int | ar2GetSearchFeatureNum (AR2HandleT *ar2Handle, int *searchTemplateMax)
int | ar2SetSimThresh (AR2HandleT *ar2Handle, float simThresh)
int | ar2GetSimThresh (AR2HandleT *ar2Handle, float *simThresh)
int | ar2SetTrackingThresh (AR2HandleT *ar2Handle, float trackingThresh)
int | ar2GetTrackingThresh (AR2HandleT *ar2Handle, float *trackingThresh)
int | ar2SetTrackingMode (AR2HandleT *ar2Handle, int trackingMode)
int | ar2GetTrackingMode (AR2HandleT *ar2Handle, int *trackingMode)

## Macro Definition Documentation

## ◆ AR2_TRACKING_6DOF

#define AR2_TRACKING_6DOF 1

artoolkitX NFT core routines.

@header tracking

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

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

Copyright
  2015 Daqri, LLC.

## ◆ AR2_TRACKING_DEFAULT_THREAD_NUM

#define AR2_TRACKING_DEFAULT_THREAD_NUM -1

## ◆ AR2_TRACKING_HOMOGRAPHY

#define AR2_TRACKING_HOMOGRAPHY 2

## Typedef Documentation

## ◆ AR2HandleT

typedef struct _AR2HandleT AR2HandleT

## ◆ AR2Tracking2DParamT

typedef struct _AR2Tracking2DParamT AR2Tracking2DParamT

## Function Documentation

## ◆ ar2CreateHandle()

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

Allocate and initialise essential structures for NFT texture tracking, using full six degree-of-freedom tracking. 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.

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 artoolkitX calculate a sensible default.

Returns
  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.

See also
  ar2CreateHandleHomography ar2CreateHandleHomography
  ar2DeleteHandle ar2DeleteHandle

Here is the call graph for this function:

## ◆ ar2CreateHandleHomography()

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

Allocate and initialise essential structures for NFT texture tracking, using homography-only tracking. 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.

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 artoolkitX calculate a sensible default.

Returns
  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.

See also
  ar2CreateHandle ar2CreateHandle
  ar2DeleteHandle ar2DeleteHandle

## ◆ ar2DeleteHandle()

int ar2DeleteHandle | ( | AR2HandleT ** | ar2Handle | ) |

Finalise and dispose of structures for NFT texture tracking. Once texture tracking processing has completed, this routine should be called to dispose of memory allocated.

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.

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2CreateHandle ar2CreateHandle
  ar2CreateHandleHomography ar2CreateHandleHomography

Here is the call graph for this function:

## ◆ ar2FreeSurfaceSet()

int ar2FreeSurfaceSet | ( | AR2SurfaceSetT ** | surfaceSet | ) |

Finalise and dispose of an NFT texture tracking surface set. Once a surface set (read by ar2ReadSurfaceSet()) is no longer required, it should be disposed of by calling ar2FreeSurfaceSet().

Parameters

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

Returns
  0 if successful, -1 otherwise.

See also
  ar2ReadSurfaceSet ar2ReadSurfaceSet

Here is the call graph for this function:

## ◆ ar2GetSearchFeatureNum()

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

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

## ◆ ar2GetSearchSize()

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

Get feature point search window size. See the discussion under ar2SetSearchSize.

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

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.

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2SetSearchSize ar2SetSearchSize

## ◆ ar2GetSimThresh()

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

Parameters

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

Returns
  -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 |

Returns
  -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 |

Returns
  -1 in case of error, or 0 otherwise.

## ◆ ar2GetTrackingMode()

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

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

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2CreateHandle ar2CreateHandle
  ar2CreateHandleHomography ar2CreateHandleHomography
  ar2SetTrackingMode ar2SetTrackingMode

## ◆ ar2GetTrackingThresh()

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

Get threshold value for acceptable pose estimate error. See the discussion under ar2SetTrackingThresh.

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

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2SetTrackingThresh ar2SetTrackingThresh

## ◆ ar2ReadSurfaceSet()

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

Read an NFT texture tracking surface set from file. 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().

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.

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

See also
  ar2FreeSurfaceSet ar2FreeSurfaceSet

Here is the call graph for this function:

## ◆ ar2SetInitTrans()

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

Sets initial transform for subsequent NFT texture tracking. 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.

Parameters

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

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

See also
  ar2Tracking ar2Tracking

## ◆ ar2SetSearchFeatureNum()

int ar2SetSearchFeatureNum | ( | AR2HandleT * | ar2Handle,
|  | int | searchTemplateMax
| ) |  |

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

## ◆ ar2SetSearchSize()

int ar2SetSearchSize | ( | AR2HandleT * | ar2Handle,
|  | int | searchSize
| ) |  |

Set feature point search window size. 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>

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2GetSearchSize ar2GetSearchSize

## ◆ ar2SetSimThresh()

int ar2SetSimThresh | ( | AR2HandleT * | ar2Handle,
|  | float | simThresh
| ) |  |

Parameters

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

Returns
  -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 |

Returns
  -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 |

Returns
  -1 in case of error, or 0 otherwise.

## ◆ ar2SetTrackingMode()

int ar2SetTrackingMode | ( | AR2HandleT * | ar2Handle,
|  | int | trackingMode
| ) |  |

Choose whether full 6 degree-of-freedom tracking is performed, or homography extraction only. 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.

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2CreateHandle ar2CreateHandle
  ar2CreateHandleHomography ar2CreateHandleHomography
  ar2GetTrackingMode ar2GetTrackingMode

## ◆ ar2SetTrackingThresh()

int ar2SetTrackingThresh | ( | AR2HandleT * | ar2Handle,
|  | float | trackingThresh
| ) |  |

Set threshold value for acceptable pose estimate error. 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>

Parameters

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

Returns
  -1 in case of error, or 0 otherwise.

See also
  ar2GetTrackingThresh ar2GetTrackingThresh
  ar2Tracking ar2Tracking

## ◆ ar2Tracking()

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

Perform NFT texture tracking on an image frame. 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.

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.

Returns
  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()

See also
  ar2SetInitTrans ar2SetInitTrans
  ar2SetTrackingThresh ar2SetTrackingThresh
  ar2CreateHandle ar2CreateHandle
  ar2ReadSurfaceSet ar2ReadSurfaceSet

Here is the call graph for this function:

## ◆ ar2Tracking2d()

void * ar2Tracking2d | ( | THREAD_HANDLE_T * | threadHandle | ) |

Here is the call graph for this function: