| # kpm
Includes: | <AR/ar.h> <KPM/kpmType.h>
## 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. © 2006-2015 ARToolworks, Inc. Last Updated: Monday, October 05, 2015