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

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Enumerations | Functions
kpm.h File Reference
`#include <ARX/AR/ar.h>`
`#include <ARX/KPM/kpmType.h>`
Include dependency graph for kpm.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Classes
struct | KpmCoord2D
struct | KpmImageInfo
struct | KpmPageInfo
struct | _KpmRefData
struct | KpmRefDataSet
struct | KpmInputDataSet
struct | KpmResult

## Macros
#define | BINARY_FEATURE 1
| libKPM NFT image recognition and tracking initialisation routines.
#define | KPM_EXTERN
#define | KpmPose6DOF 1
#define | KpmPoseHomography 2
#define | KpmDefaultProcMode KpmProcFullSize
#define | KpmCompNull 0
#define | KpmCompX 1
#define | KpmCompY 2
#define | KpmDefaultComp KpmCompNull
#define | KpmChangePageNoAllPages (-1)
#define | kpmCreatHandle kpmCreateHandle
#define | kpmCreatHandle2 kpmCreateHandle2
#define | kpmCreatHandleHomography kpmCreateHandleHomography
#define | kpmMargeRefDataSet kpmMergeRefDataSet

## Typedefs
typedef struct _KpmRefData | KpmRefData
typedef struct _KpmHandle | KpmHandle

## Enumerations
enum | KPM_PROC_MODE { KpmProcFullSize = 1 , KpmProcHalfSize = 2 , KpmProcQuatSize = 3 , KpmProcOneThirdSize = 4 , KpmProcTwoThirdSize = 5 }

## Functions
KPM_EXTERN KpmHandle * | kpmCreateHandle (ARParamLT *cparamLT)
| Allocate and initialise essential structures for KPM tracking, using full six degree-of-freedom tracking.
KPM_EXTERN KpmHandle * | kpmCreateHandle2 (int xsize, int ysize)
KPM_EXTERN KpmHandle * | kpmCreateHandleHomography (int xsize, int ysize)
| Allocate and initialise essential structures for KPM tracking, using homography-only tracking.
KPM_EXTERN int | kpmDeleteHandle (KpmHandle **kpmHandle)
| Finalise and dispose of structures for KPM tracking.
KPM_EXTERN int | kpmHandleGetXSize (const KpmHandle *kpmHandle)
KPM_EXTERN int | kpmHandleGetYSize (const KpmHandle *kpmHandle)
KPM_EXTERN int | kpmSetProcMode (KpmHandle *kpmHandle, KPM_PROC_MODE procMode)
KPM_EXTERN int | kpmGetProcMode (KpmHandle *kpmHandle, KPM_PROC_MODE *procMode)
KPM_EXTERN int | kpmSetDetectedFeatureMax (KpmHandle *kpmHandle, int detectedMaxFeature)
KPM_EXTERN int | kpmGetDetectedFeatureMax (KpmHandle *kpmHandle, int *detectedMaxFeature)
KPM_EXTERN int | kpmSetSurfThreadNum (KpmHandle *kpmHandle, int surfThreadNum)
KPM_EXTERN int | kpmSetRefDataSet (KpmHandle *kpmHandle, KpmRefDataSet *refDataSet)
| Load a reference data set into the key point matcher for tracking.
KPM_EXTERN int | kpmSetRefDataSetFile (KpmHandle *kpmHandle, const char *filename, const char *ext)
| Loads a reference data set from a file into the KPM tracker.
KPM_EXTERN int | kpmSetRefDataSetFileOld (KpmHandle *kpmHandle, const char *filename, const char *ext)
KPM_EXTERN int | kpmMatching (KpmHandle *kpmHandle, ARUint8 *inImageLuma)
| Perform key-point matching on an image.
KPM_EXTERN int | kpmSetMatchingSkipPage (KpmHandle *kpmHandle, int *skipPages, int num)
KPM_EXTERN int | kpmGetRefDataSet (KpmHandle *kpmHandle, KpmRefDataSet **refDataSet)
KPM_EXTERN int | kpmGetInDataSet (KpmHandle *kpmHandle, KpmInputDataSet **inDataSet)
KPM_EXTERN int | kpmGetPose (KpmHandle *kpmHandle, float pose[3][4], int *pageNo, float *error)
KPM_EXTERN int | kpmGetResult (KpmHandle *kpmHandle, KpmResult **result, int *resultNum)
KPM_EXTERN int | kpmGenRefDataSet (ARUint8 *refImage, int xsize, int ysize, float dpi, int procMode, int compMode, int maxFeatureNum, int pageNo, int imageNo, KpmRefDataSet **refDataSet)
KPM_EXTERN int | kpmAddRefDataSet (ARUint8 *refImage, int xsize, int ysize, float dpi, int procMode, int compMode, int maxFeatureNum, int pageNo, int imageNo, KpmRefDataSet **refDataSet)
KPM_EXTERN int | kpmMergeRefDataSet (KpmRefDataSet **refDataSetPtr1, KpmRefDataSet **refDataSetPtr2)
| Merge a second KPM dataset into the first, and dispose of second.
KPM_EXTERN int | kpmDeleteRefDataSet (KpmRefDataSet **refDataSetPtr)
| Dispose of a reference data set and its allocated memory.
KPM_EXTERN int | kpmSaveRefDataSet (const char *filename, const char *ext, KpmRefDataSet *refDataSet)
KPM_EXTERN int | kpmLoadRefDataSet (const char *filename, const char *ext, KpmRefDataSet **refDataSetPtr)
| Load a reference data set from the filesystem into memory.
KPM_EXTERN int | kpmLoadRefDataSetOld (const char *filename, const char *ext, KpmRefDataSet **refDataSetPtr)
KPM_EXTERN int | kpmChangePageNoOfRefDataSet (KpmRefDataSet *refDataSet, int oldPageNo, int newPageNo)
KPM_EXTERN ARUint8 * | kpmUtilResizeImage (ARUint8 *imageLuma, int xsize, int ysize, int procMode, int *newXsize, int *newYsize)
KPM_EXTERN int | kpmUtilGetCorner (ARUint8 *inImagePtr, int xsize, int ysize, int procMode, int maxPointNum, CornerPoints *cornerPoints)
double | wallclock (void)
KPM_EXTERN int | kpmLoadImageDb (const char *filename)

## Macro Definition Documentation

## ◆ BINARY_FEATURE

#define BINARY_FEATURE 1

libKPM NFT image recognition and tracking initialisation routines.

@header kpm

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.

Copyright
  2006-2015 ARToolworks, Inc.

## ◆ KPM_EXTERN

#define KPM_EXTERN

## ◆ KpmChangePageNoAllPages

#define KpmChangePageNoAllPages (-1)

## ◆ KpmCompNull

#define KpmCompNull 0

## ◆ KpmCompX

#define KpmCompX 1

## ◆ KpmCompY

#define KpmCompY 2

## ◆ kpmCreatHandle

#define kpmCreatHandle kpmCreateHandle

## ◆ kpmCreatHandle2

#define kpmCreatHandle2 kpmCreateHandle2

## ◆ kpmCreatHandleHomography

#define kpmCreatHandleHomography kpmCreateHandleHomography

## ◆ KpmDefaultComp

#define KpmDefaultComp KpmCompNull

## ◆ KpmDefaultProcMode

#define KpmDefaultProcMode KpmProcFullSize

## ◆ kpmMargeRefDataSet

#define kpmMargeRefDataSet kpmMergeRefDataSet

## ◆ KpmPose6DOF

#define KpmPose6DOF 1

## ◆ KpmPoseHomography

#define KpmPoseHomography 2

## Typedef Documentation

## ◆ KpmHandle

typedef struct _KpmHandle KpmHandle

## ◆ KpmRefData

typedef struct _KpmRefData KpmRefData

## Enumeration Type Documentation

## ◆ KPM_PROC_MODE

enum KPM_PROC_MODE

Enumerator
KpmProcFullSize |
KpmProcHalfSize |
KpmProcQuatSize |
KpmProcOneThirdSize |
KpmProcTwoThirdSize |

## Function Documentation

## ◆ kpmAddRefDataSet()

KPM_EXTERN int kpmAddRefDataSet | ( | ARUint8 * | refImage,
|  | int | xsize,
|  | int | ysize,
|  | float | dpi,
|  | int | procMode,
|  | int | compMode,
|  | int | maxFeatureNum,
|  | int | pageNo,
|  | int | imageNo,
|  | KpmRefDataSet ** | refDataSet
| ) |  |

Here is the call graph for this function:

## ◆ kpmChangePageNoOfRefDataSet()

KPM_EXTERN int kpmChangePageNoOfRefDataSet | ( | KpmRefDataSet * | refDataSet,
|  | int | oldPageNo,
|  | int | newPageNo
| ) |  |

Parameters

  refDataSet |
  oldPageNo |
  newPageNo |

Returns

## ◆ kpmCreateHandle()

KPM_EXTERN KpmHandle * kpmCreateHandle | ( | ARParamLT * | cparamLT | ) |

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

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.

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

See also
  kpmCreateHandleHomography kpmCreateHandleHomography
  kpmDeleteHandle kpmDeleteHandle

## ◆ kpmCreateHandle2()

KPM_EXTERN KpmHandle * kpmCreateHandle2 | ( | int | xsize,
|  | int | ysize
| ) |  |

## ◆ kpmCreateHandleHomography()

KPM_EXTERN KpmHandle * kpmCreateHandleHomography | ( | int | xsize,
|  | int | ysize
| ) |  |

Allocate and initialise essential structures for KPM 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 kpmMatching() function.
  ysize | Height of video frames which will be later supplied to the kpmMatching() function.

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

See also
  kpmCreateHandle kpmCreateHandle
  kpmDeleteHandle kpmDeleteHandle

## ◆ kpmDeleteHandle()

KPM_EXTERN int kpmDeleteHandle | ( | KpmHandle ** | kpmHandle | ) |

Finalise and dispose of structures for KPM tracking.

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

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.

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

See also
  kpmCreateHandle kpmCreateHandle
  kpmCreateHandleHomography kpmCreateHandleHomography

## ◆ kpmDeleteRefDataSet()

KPM_EXTERN int kpmDeleteRefDataSet | ( | KpmRefDataSet ** | refDataSetPtr | ) |

Dispose of a reference data set and its allocated memory.

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.

Parameters

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

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

See also
  kpmLoadRefDataSet kpmLoadRefDataSet

## ◆ kpmGenRefDataSet()

KPM_EXTERN int kpmGenRefDataSet | ( | ARUint8 * | refImage,
|  | int | xsize,
|  | int | ysize,
|  | float | dpi,
|  | int | procMode,
|  | int | compMode,
|  | int | maxFeatureNum,
|  | int | pageNo,
|  | int | imageNo,
|  | KpmRefDataSet ** | refDataSet
| ) |  |

Here is the call graph for this function:

## ◆ kpmGetDetectedFeatureMax()

KPM_EXTERN int kpmGetDetectedFeatureMax | ( | KpmHandle * | kpmHandle,
|  | int * | detectedMaxFeature
| ) |  |

## ◆ kpmGetInDataSet()

KPM_EXTERN int kpmGetInDataSet | ( | KpmHandle * | kpmHandle,
|  | KpmInputDataSet ** | inDataSet
| ) |  |

## ◆ kpmGetPose()

KPM_EXTERN int kpmGetPose | ( | KpmHandle * | kpmHandle,
|  | float | pose[3][4],
|  | int * | pageNo,
|  | float * | error
| ) |  |

## ◆ kpmGetProcMode()

KPM_EXTERN int kpmGetProcMode | ( | KpmHandle * | kpmHandle,
|  | KPM_PROC_MODE * | procMode
| ) |  |

## ◆ kpmGetRefDataSet()

KPM_EXTERN int kpmGetRefDataSet | ( | KpmHandle * | kpmHandle,
|  | KpmRefDataSet ** | refDataSet
| ) |  |

## ◆ kpmGetResult()

KPM_EXTERN int kpmGetResult | ( | KpmHandle * | kpmHandle,
|  | KpmResult ** | result,
|  | int * | resultNum
| ) |  |

## ◆ kpmHandleGetXSize()

KPM_EXTERN int kpmHandleGetXSize | ( | const KpmHandle * | kpmHandle | ) |

## ◆ kpmHandleGetYSize()

KPM_EXTERN int kpmHandleGetYSize | ( | const KpmHandle * | kpmHandle | ) |

## ◆ kpmLoadImageDb()

KPM_EXTERN int kpmLoadImageDb | ( | const char * | filename | ) |

## ◆ kpmLoadRefDataSet()

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

Load a reference data set from the filesystem into memory.

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.

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

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

Parameters

  refDataSetPtr | Pointer to a location which after loading will point to the loaded reference data set.

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

See also
  kpmSetRefDataSet kpmSetRefDataSet
  kpmMergeRefDataSet kpmMergeRefDataSet
  kpmDeleteRefDataSet kpmDeleteRefDataSet

Here is the call graph for this function:

## ◆ kpmLoadRefDataSetOld()

KPM_EXTERN int kpmLoadRefDataSetOld | ( | const char * | filename,
|  | const char * | ext,
|  | KpmRefDataSet ** | refDataSetPtr
| ) |  |

Here is the call graph for this function:

## ◆ kpmMatching()

KPM_EXTERN int kpmMatching | ( | KpmHandle * | kpmHandle,
|  | ARUint8 * | inImageLuma
| ) |  |

Perform key-point matching on an image.

Parameters

  kpmHandle |
  inImageLuma | Source image containing the pixels which will be searched for features. Typically, this is one frame from a video stream. The dimensions of this image must match the values specified at the time of creation of the KPM handle. Luma only.

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

See also
  kpmCreateHandle kpmCreateHandle
  kpmCreateHandleHomography kpmCreateHandleHomography

Here is the call graph for this function:

## ◆ kpmMergeRefDataSet()

KPM_EXTERN int kpmMergeRefDataSet | ( | KpmRefDataSet ** | refDataSetPtr1,
|  | KpmRefDataSet ** | refDataSetPtr2
| ) |  |

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

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.

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.

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

Here is the call graph for this function:

## ◆ kpmSaveRefDataSet()

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

Parameters

  filename |
  ext |
  refDataSet |

Returns

Here is the call graph for this function:

## ◆ kpmSetDetectedFeatureMax()

KPM_EXTERN int kpmSetDetectedFeatureMax | ( | KpmHandle * | kpmHandle,
|  | int | detectedMaxFeature
| ) |  |

## ◆ kpmSetMatchingSkipPage()

KPM_EXTERN int kpmSetMatchingSkipPage | ( | KpmHandle * | kpmHandle,
|  | int * | skipPages,
|  | int | num
| ) |  |

## ◆ kpmSetProcMode()

KPM_EXTERN int kpmSetProcMode | ( | KpmHandle * | kpmHandle,
|  | KPM_PROC_MODE | procMode
| ) |  |

## ◆ kpmSetRefDataSet()

KPM_EXTERN int kpmSetRefDataSet | ( | KpmHandle * | kpmHandle,
|  | KpmRefDataSet * | refDataSet
| ) |  |

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

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

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.

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

See also
  kpmCreateHandle kpmCreateHandle
  kpmCreateHandleHomography kpmCreateHandleHomography
  kpmDeleteRefDataSet kpmDeleteRefDataSet

## ◆ kpmSetRefDataSetFile()

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

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

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.

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

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

See also
  kpmLoadRefDataSet kpmLoadRefDataSet
  kpmSetRefDataSet kpmSetRefDataSet
  kpmDeleteRefDataSet kpmDeleteRefDataSet

Here is the call graph for this function:

## ◆ kpmSetRefDataSetFileOld()

KPM_EXTERN int kpmSetRefDataSetFileOld | ( | KpmHandle * | kpmHandle,
|  | const char * | filename,
|  | const char * | ext
| ) |  |

Here is the call graph for this function:

## ◆ kpmSetSurfThreadNum()

KPM_EXTERN int kpmSetSurfThreadNum | ( | KpmHandle * | kpmHandle,
|  | int | surfThreadNum
| ) |  |

## ◆ kpmUtilGetCorner()

KPM_EXTERN int kpmUtilGetCorner | ( | ARUint8 * | inImagePtr,
|  | int | xsize,
|  | int | ysize,
|  | int | procMode,
|  | int | maxPointNum,
|  | CornerPoints * | cornerPoints
| ) |  |

Here is the call graph for this function:

## ◆ kpmUtilResizeImage()

KPM_EXTERN ARUint8 * kpmUtilResizeImage | ( | ARUint8 * | imageLuma,
|  | int | xsize,
|  | int | ysize,
|  | int | procMode,
|  | int * | newXsize,
|  | int * | newYsize
| ) |  |

Parameters

  imageLuma | Source luminance image, as an unpadded pixel buffer beginning with the leftmost pixel of the top row.
  xsize | Width of pixel data in 'imageLuma'.
  ysize | height of pixel data in 'imageLuma'.
  procMode |

Returns

## ◆ wallclock()

double wallclock | ( | void |  | ) |