#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:

Classes
struct	AR2SurfaceT

struct	AR2SurfaceSetT

struct	AR2Tracking2DResultT

struct	_AR2Tracking2DParamT

struct	_AR2HandleT

Macros
#define	AR2_TRACKING_6DOF 1
	artoolkitX NFT core routines. More...

#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:

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ AR2_TRACKING_6DOF

◆ AR2_TRACKING_DEFAULT_THREAD_NUM

◆ AR2_TRACKING_HOMOGRAPHY

Typedef Documentation

◆ AR2HandleT

◆ AR2Tracking2DParamT

Function Documentation

◆ ar2CreateHandle()

◆ ar2CreateHandleHomography()

◆ ar2DeleteHandle()

◆ ar2FreeSurfaceSet()

◆ ar2GetSearchFeatureNum()

◆ ar2GetSearchSize()

◆ ar2GetSimThresh()

◆ ar2GetTemplateSize1()

◆ ar2GetTemplateSize2()

◆ ar2GetTrackingMode()

◆ ar2GetTrackingThresh()

◆ ar2ReadSurfaceSet()

◆ ar2SetInitTrans()

◆ ar2SetSearchFeatureNum()

◆ ar2SetSearchSize()

◆ ar2SetSimThresh()

◆ ar2SetTemplateSize1()

◆ ar2SetTemplateSize2()

◆ ar2SetTrackingMode()

◆ ar2SetTrackingThresh()

◆ ar2Tracking()

◆ ar2Tracking2d()