kpm

Includes:

Introduction

libKPM NFT image recognition and tracking initialisation routines.

Discussion

This header declares types and API for an NFT tracker, in particular those routines involved in recognising a texture page and initialising the tracking for use by the texture tracker.

Functions

kpmChangePageNoOfRefDataSet
kpmCreateHandle: Allocate and initialise essential structures for KPM tracking, using full six degree-of-freedom tracking.
kpmCreateHandleHomography: Allocate and initialise essential structures for KPM tracking, using homography-only tracking.
kpmDeleteHandle: Finalise and dispose of structures for KPM tracking.
kpmDeleteRefDataSet: Dispose of a reference data set and its allocated memory.
kpmLoadRefDataSet: Load a reference data set from the filesystem into memory.
kpmMatching: Perform key-point matching on an image.
kpmMergeRefDataSet: Merge a second KPM dataset into the first, and dispose of second.
kpmSaveRefDataSet
kpmSetRefDataSet: Load a reference data set into the key point matcher for tracking.
kpmSetRefDataSetFile: Loads a reference data set from a file into the KPM tracker.
kpmUtilGenBWImage

kpmChangePageNoOfRefDataSet

int kpmChangePageNoOfRefDataSet (
    KpmRefDataSet *refDataSet,
    int oldPageNo,
    int newPageNo );

Parameters

refDataSet
oldPageNo
newPageNo

kpmCreateHandle

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

KpmHandle *kpmCreateHandle (
    ARParamLT *cparamLT,
    AR_PIXEL_FORMAT pixFormat );

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 KpmHandle. This structure also specifies the size of video frames which will be later supplied to the kpmMatching() function as cparamLT->param.xsize and cparamLT->param.ysize.
pixFormat: Pixel format of video frames which will be later supplied to the kpmMatching() function.

Return Value

Pointer to a newly-allocated KpmHandle structure. This structure must be deallocated via a call to kpmDeleteHandle() when no longer needed.

See Also

kpmCreateHandleHomography
kpmDeleteHandle

kpmCreateHandleHomography

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

KpmHandle *kpmCreateHandleHomography(
    int xsize,
    int ysize,
    AR_PIXEL_FORMAT pixFormat );

Parameters

xsize: Width of video frames which will be later supplied to the kpmMatching() function.
ysize: Height of video frames which will be later supplied to the kpmMatching() function.
pixFormat: Pixel format of video frames which will be later supplied to the kpmMatching() function.

Return Value

Pointer to a newly-allocated KpmHandle structure. This structure must be deallocated via a call to kpmDeleteHandle() 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

kpmCreateHandle
kpmDeleteHandle

kpmDeleteHandle

Finalise and dispose of structures for KPM tracking.

int kpmDeleteHandle(
    KpmHandle **kpmHandle );

Parameters

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

Return Value

0 if successful, or value <0 in case of error.

Discussion

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

See Also

kpmCreateHandle
kpmCreateHandleHomography

kpmDeleteRefDataSet

Dispose of a reference data set and its allocated memory.

int kpmDeleteRefDataSet (
    KpmRefDataSet **refDataSetPtr );

Parameters

refDataSetPtr: Pointer to memory location which points to the dataset. On success, this location will be set to NULL.

Return Value

0 if the delete succeeded, or a value < 0 in case of error.

Discussion

Once a data set has been loaded into a KPM handle, or is otherwise no longer required to be held in memory, it should be deleted (i.e. disposed) from memory by calling this function.

See Also

kpmLoadRefDataSet

kpmLoadRefDataSet

Load a reference data set from the filesystem into memory.

int kpmLoadRefDataSet (
    const char *filename,
    const char *ext,
    KpmRefDataSet **refDataSetPtr );

Parameters

filename: Path to the dataset. Either full path, or a relative path if supported by the operating system.
ext: If non-NULL, a '.' charater and this string will be appended to 'filename'. Often, this parameter is a pointer to the string "fset3".
refDataSetPtr: Pointer to a location which after loading will point to the loaded reference data set.

Return Value

0 if the load succeeded, or a value < 0 in case of error.

Discussion

This does not set the reference data as the current tracking set. To do that, call kpmSetRefDataSet after this load completes. Alternately, the loaded set can be merged with another loaded set by calling kpmMergeRefDataSet. To dispose of the loaded dataset, call kpmDeleteRefDataSet.

See Also

kpmSetRefDataSet
kpmMergeRefDataSet
kpmDeleteRefDataSet

kpmMatching

Perform key-point matching on an image.

int kpmMatching(
    KpmHandle *kpmHandle,
    ARUint8 *inImage );

Parameters

kpmHandle
inImage: Source image containing the pixels which will be searched for features. Typically, this is one frame from a video stream. The dimensions and pixel format of this image must match the values specified at the time of creation of the KPM handle.

Return Value

0 if successful, or value <0 in case of error.

See Also

kpmCreateHandle
kpmCreateHandleHomography

kpmMergeRefDataSet

Merge a second KPM dataset into the first, and dispose of second.

int kpmMergeRefDataSet (
    KpmRefDataSet **refDataSetPtr1,
    KpmRefDataSet **refDataSetPtr2 );

Parameters

refDataSetPtr1: Pointer to a location which points to the first data set, or pointer to NULL if a new dataset is to be created. This will hold the results of the merge.
refDataSetPtr2: Pointer to a location which points to the second data set. After the merge, the dataset pointed to will be deleted and the location pointed to set to NULL.

Return Value

0 if the merge succeeded, or a value < 0 in case of error.

Discussion

This function merges two KPM datasets by adding the reference points in the second into the first (allocating a new set if the location pointed to by refDataSetPtr1 is NULL) and then deleting the second set.

kpmSaveRefDataSet

int kpmSaveRefDataSet (
    const char *filename,
    const char *ext,
    KpmRefDataSet *refDataSet );

Parameters

filename
ext
refDataSet

kpmSetRefDataSet

Load a reference data set into the key point matcher for tracking.

int kpmSetRefDataSet(
    KpmHandle *kpmHandle,
    KpmRefDataSet *refDataSet );

Parameters

kpmHandle: Handle to the current KPM tracker instance, as generated by kpmCreateHandle or kpmCreateHandleHomography.
refDataSet: The reference data set to load into the KPM handle. The operation takes a copy of the data required from this dataset, thus unless the need for a further load at a later time is required, the dataset can be disposed of by calling kpmDeleteRefDataSet after this operation succeeds.

Return Value

0 if successful, or value <0 in case of error.

Discussion

This function takes a reference data set already in memory and makes it the current dataset for key point matching.

See Also

kpmCreateHandle
kpmCreateHandleHomography
kpmDeleteRefDataSet

kpmSetRefDataSetFile

Loads a reference data set from a file into the KPM tracker.

int kpmSetRefDataSetFile(
    KpmHandle *kpmHandle,
    const char *filename,
    const char *ext );

Parameters

kpmHandle: Handle to the current KPM tracker instance, as generated by kpmCreateHandle or kpmCreateHandleHomography.
filename: Path to the dataset. Either full path, or a relative path if supported by the operating system.
ext: If non-NULL, a '.' charater and this string will be appended to 'filename'. Often, this parameter is a pointer to the string "fset3".

Return Value

Returns 0 if successful, or value <0 in case of error.

Discussion

This is a convenience method which performs a sequence of kpmLoadRefDataSet, followed by kpmSetRefDataSet and finally kpmDeleteRefDataSet. When tracking from a single reference dataset file, this is the simplest means to start.

See Also

kpmLoadRefDataSet
kpmSetRefDataSet
kpmDeleteRefDataSet

kpmUtilGenBWImage

ARUint8 *kpmUtilGenBWImage(
    ARUint8 *image,
    AR_PIXEL_FORMAT pixFormat,
    int xsize,
    int ysize,
    int procMode,
    int *newXsize,
    int *newYsize );

Parameters

image: Source image, as an unpadded pixel buffer beginning with the leftmost pixel of the top row.
pixFormat: Layout of pixel data in 'image'.
xsize: Layout of pixel data in 'image'.
ysize: Layout of pixel data in 'image'.
procMode

Typedefs

KpmInputDataSet: Data describing the number and location of keypoints in an input image to be matched against a loaded data set.
KpmRefDataSet: A loaded dataset for KPM tracking.

KpmInputDataSet

Data describing the number and location of keypoints in an input image to be matched against a loaded data set.

typedef struct { 
    KpmCoord2D *coord; 
    int num; 
} KpmInputDataSet;

Fields

coord: Array of pixel locations of the keypoints in an input image.
num: Number of coords in the array.

Discussion

Key point matching occurs between a loaded data set and a set of keypoints extracted from an input image. This structure holds the number and pixel location of keypoints in the input image. The keypoints themselves are an array of 'num' KpmRefData structures.

KpmRefDataSet

A loaded dataset for KPM tracking.

typedef struct { 
    KpmRefData *refPoint; 
    int num; 
    KpmPageInfo *pageInfo; 
    int pageNum; 
} KpmRefDataSet;

Fields

refPoint: Tracking reference points.
num: Number of refPoints in the dataset.
pageInfo: Array of info about each page in the dataset. One entry per page.
pageNum: Number of pages in the dataset (i.e. a count, not an index).

Discussion

Key point matching takes as input a reference data set of points. This structure holds a set of points in memory prior to loading into the tracker.

Last Updated: Wednesday, March 23, 2016