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

Loading...
Searching...
No Matches
kpm.h
Go to the documentation of this file.
1/*
2 * kpm.h
3 * artoolkitX
4 *
5 * This file is part of artoolkitX.
6 *
7 * artoolkitX is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU Lesser General Public License as published by
9 * the Free Software Foundation, either version 3 of the License, or
10 * (at your option) any later version.
11 *
12 * artoolkitX is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public License
18 * along with artoolkitX. If not, see <http://www.gnu.org/licenses/>.
19 *
20 * As a special exception, the copyright holders of this library give you
21 * permission to link this library with independent modules to produce an
22 * executable, regardless of the license terms of these independent modules, and to
23 * copy and distribute the resulting executable under terms of your choice,
24 * provided that you also meet, for each linked independent module, the terms and
25 * conditions of the license of that module. An independent module is a module
26 * which is neither derived from nor based on this library. If you modify this
27 * library, you may extend this exception to your version of the library, but you
28 * are not obligated to do so. If you do not wish to do so, delete this exception
29 * statement from your version.
30 *
31 * Copyright 2015 Daqri, LLC. All rights reserved.
32 * Copyright 2006-2015 ARToolworks, Inc. All rights reserved.
33 * Author(s): Hirokazu Kato, Philip Lamb
34 *
35 */
36
47#ifndef KPM_H
48#define KPM_H
49
50#define BINARY_FEATURE 1
51
52#include <ARX/AR/ar.h>
53#include <ARX/KPM/kpmType.h>
54
55#ifdef __cplusplus
56 extern "C" {
57#endif
58
59#ifdef _WIN32
60# ifdef KPM_STATIC
61# define KPM_EXTERN
62# else
63# ifdef ARX_EXPORTS
64# define KPM_EXTERN __declspec(dllexport)
65# else
66# define KPM_EXTERN __declspec(dllimport)
67# endif
68# endif
69#else
70# define KPM_EXTERN
71#endif
72
73#define KpmPose6DOF 1
74#define KpmPoseHomography 2
75
76 typedef enum {
77 KpmProcFullSize = 1,
78 KpmProcHalfSize = 2,
79 KpmProcQuatSize = 3,
80 KpmProcOneThirdSize = 4,
81 KpmProcTwoThirdSize = 5
82} KPM_PROC_MODE;
83#define KpmDefaultProcMode KpmProcFullSize
84
85#define KpmCompNull 0
86#define KpmCompX 1
87#define KpmCompY 2
88#define KpmDefaultComp KpmCompNull
89
90#define KpmChangePageNoAllPages (-1)
91
92 typedef struct {
93 float x;
94 float y;
95} KpmCoord2D;
96
97 typedef struct {
98 int width;
99 int height;
100 int imageNo;
101} KpmImageInfo;
102
103 typedef struct {
104 KpmImageInfo *imageInfo;
105 int imageNum;
106 int pageNo;
107} KpmPageInfo;
108
109 typedef struct _KpmRefData {
110 KpmCoord2D coord2D;
111 KpmCoord2D coord3D; // millimetres.
112#if BINARY_FEATURE
113 FreakFeature featureVec;
114#else
115 SurfFeature featureVec;
116#endif
117 int pageNo;
118 int refImageNo;
119} KpmRefData;
120
131 typedef struct {
132 KpmRefData *refPoint;
133 int num;
134 KpmPageInfo *pageInfo;
135 int pageNum;
136} KpmRefDataSet;
137
148 typedef struct {
149 KpmCoord2D *coord;
150 int num;
151} KpmInputDataSet;
152
153#if !BINARY_FEATURE
154 typedef struct {
155 int refIndex;
156 int inIndex;
157} KpmMatchData;
158
159 typedef struct {
160 KpmMatchData *match;
161 int num;
162} KpmMatchResult;
163#endif
164
165 typedef struct {
166 float camPose[3][4];
167 int pageNo;
168 float error;
169 int inlierNum;
170 int camPoseF;
171 int skipF;
172} KpmResult;
173
174 typedef struct _KpmHandle KpmHandle;
175
176
189 KPM_EXTERN KpmHandle *kpmCreateHandle (ARParamLT *cparamLT);
190#define kpmCreatHandle kpmCreateHandle
191
192 KPM_EXTERN KpmHandle *kpmCreateHandle2(int xsize, int ysize);
193#define kpmCreatHandle2 kpmCreateHandle2
194
208 KPM_EXTERN KpmHandle *kpmCreateHandleHomography(int xsize, int ysize);
209#define kpmCreatHandleHomography kpmCreateHandleHomography
210
222 KPM_EXTERN int kpmDeleteHandle( KpmHandle **kpmHandle );
223
224 KPM_EXTERN int kpmHandleGetXSize(const KpmHandle *kpmHandle);
225 KPM_EXTERN int kpmHandleGetYSize(const KpmHandle *kpmHandle);
226
227 KPM_EXTERN int kpmSetProcMode( KpmHandle *kpmHandle, KPM_PROC_MODE procMode );
228 KPM_EXTERN int kpmGetProcMode( KpmHandle *kpmHandle, KPM_PROC_MODE *procMode );
229 KPM_EXTERN int kpmSetDetectedFeatureMax( KpmHandle *kpmHandle, int detectedMaxFeature );
230 KPM_EXTERN int kpmGetDetectedFeatureMax( KpmHandle *kpmHandle, int *detectedMaxFeature );
231 KPM_EXTERN int kpmSetSurfThreadNum( KpmHandle *kpmHandle, int surfThreadNum );
232
248 KPM_EXTERN int kpmSetRefDataSet( KpmHandle *kpmHandle, KpmRefDataSet *refDataSet );
249
267 KPM_EXTERN int kpmSetRefDataSetFile( KpmHandle *kpmHandle, const char *filename, const char *ext );
268
269 KPM_EXTERN int kpmSetRefDataSetFileOld( KpmHandle *kpmHandle, const char *filename, const char *ext );
270
281 KPM_EXTERN int kpmMatching(KpmHandle *kpmHandle, ARUint8 *inImageLuma);
282
283 KPM_EXTERN int kpmSetMatchingSkipPage( KpmHandle *kpmHandle, int *skipPages, int num );
284#if !BINARY_FEATURE
285 KPM_EXTERN int kpmSetMatchingSkipRegion( KpmHandle *kpmHandle, SurfSubRect *skipRegion, int regionNum);
286#endif
287
288 KPM_EXTERN int kpmGetRefDataSet( KpmHandle *kpmHandle, KpmRefDataSet **refDataSet );
289 KPM_EXTERN int kpmGetInDataSet( KpmHandle *kpmHandle, KpmInputDataSet **inDataSet );
290#if !BINARY_FEATURE
291 KPM_EXTERN int kpmGetMatchingResult( KpmHandle *kpmHandle, KpmMatchResult **preRANSAC, KpmMatchResult **aftRANSAC );
292#endif
293 KPM_EXTERN int kpmGetPose( KpmHandle *kpmHandle, float pose[3][4], int *pageNo, float *error );
294 KPM_EXTERN int kpmGetResult( KpmHandle *kpmHandle, KpmResult **result, int *resultNum );
295
296
297 KPM_EXTERN int kpmGenRefDataSet ( ARUint8 *refImage, int xsize, int ysize, float dpi, int procMode, int compMode, int maxFeatureNum,
298 int pageNo, int imageNo, KpmRefDataSet **refDataSet );
299 KPM_EXTERN int kpmAddRefDataSet ( ARUint8 *refImage, int xsize, int ysize, float dpi, int procMode, int compMode, int maxFeatureNum,
300 int pageNo, int imageNo, KpmRefDataSet **refDataSet );
301
314 KPM_EXTERN int kpmMergeRefDataSet ( KpmRefDataSet **refDataSetPtr1, KpmRefDataSet **refDataSetPtr2 );
315#define kpmMargeRefDataSet kpmMergeRefDataSet
316
328 KPM_EXTERN int kpmDeleteRefDataSet ( KpmRefDataSet **refDataSetPtr );
329
337 KPM_EXTERN int kpmSaveRefDataSet ( const char *filename, const char *ext, KpmRefDataSet *refDataSet );
338
358 KPM_EXTERN int kpmLoadRefDataSet ( const char *filename, const char *ext, KpmRefDataSet **refDataSetPtr );
359
360 KPM_EXTERN int kpmLoadRefDataSetOld( const char *filename, const char *ext, KpmRefDataSet **refDataSetPtr );
361
369 KPM_EXTERN int kpmChangePageNoOfRefDataSet ( KpmRefDataSet *refDataSet, int oldPageNo, int newPageNo );
370
371
380 KPM_EXTERN ARUint8 *kpmUtilResizeImage( ARUint8 *imageLuma, int xsize, int ysize, int procMode, int *newXsize, int *newYsize );
381
382#if !BINARY_FEATURE
383 KPM_EXTERN int kpmUtilGetPose ( ARParamLT *cparamLT, KpmMatchResult *matchData, KpmRefDataSet *refDataSet, KpmInputDataSet *inputDataSet, float camPose[3][4], float *err );
384
385 KPM_EXTERN int kpmUtilGetPose2( ARParamLT *cparamLT, KpmMatchResult *matchData, KpmRefDataSet *refDataSet, int *redDataIndex, KpmInputDataSet *inputDataSet, float camPose[3][4], float *error );
386 KPM_EXTERN int kpmUtilGetPoseHomography( KpmMatchResult *matchData, KpmRefDataSet *refDataSet, KpmInputDataSet *inputDataSet, float camPose[3][4], float *err );
387#endif
388 KPM_EXTERN int kpmUtilGetCorner( ARUint8 *inImagePtr, int xsize, int ysize, int procMode, int maxPointNum, CornerPoints *cornerPoints );
389
390
391 double wallclock(void);
392
393 KPM_EXTERN int kpmLoadImageDb(const char *filename);
394
395#ifdef __cplusplus
396}
397#endif
398#endif
ar.h
artoolkitX core routines.
ARUint8
unsigned char ARUint8
Definition: ar.h:92
kpmSetProcMode
KPM_EXTERN int kpmSetProcMode(KpmHandle *kpmHandle, KPM_PROC_MODE procMode)
Definition: kpmHandle.cpp:150
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)
Definition: kpmRefDataSet.cpp:287
kpmGetRefDataSet
KPM_EXTERN int kpmGetRefDataSet(KpmHandle *kpmHandle, KpmRefDataSet **refDataSet)
Definition: kpmResult.cpp:42
kpmDeleteHandle
KPM_EXTERN int kpmDeleteHandle(KpmHandle **kpmHandle)
Finalise and dispose of structures for KPM tracking.
Definition: kpmHandle.cpp:228
kpmGetProcMode
KPM_EXTERN int kpmGetProcMode(KpmHandle *kpmHandle, KPM_PROC_MODE *procMode)
Definition: kpmHandle.cpp:195
KPM_PROC_MODE
KPM_PROC_MODE
Definition: kpm.h:76
KpmProcOneThirdSize
@ KpmProcOneThirdSize
Definition: kpm.h:80
KpmProcTwoThirdSize
@ KpmProcTwoThirdSize
Definition: kpm.h:81
KpmProcQuatSize
@ KpmProcQuatSize
Definition: kpm.h:79
KpmProcFullSize
@ KpmProcFullSize
Definition: kpm.h:77
KpmProcHalfSize
@ KpmProcHalfSize
Definition: kpm.h:78
kpmGetInDataSet
KPM_EXTERN int kpmGetInDataSet(KpmHandle *kpmHandle, KpmInputDataSet **inDataSet)
Definition: kpmResult.cpp:52
kpmSetRefDataSet
KPM_EXTERN int kpmSetRefDataSet(KpmHandle *kpmHandle, KpmRefDataSet *refDataSet)
Load a reference data set into the key point matcher for tracking.
Definition: kpmMatching.cpp:171
kpmChangePageNoOfRefDataSet
KPM_EXTERN int kpmChangePageNoOfRefDataSet(KpmRefDataSet *refDataSet, int oldPageNo, int newPageNo)
Definition: kpmRefDataSet.cpp:639
kpmLoadImageDb
KPM_EXTERN int kpmLoadImageDb(const char *filename)
kpmSaveRefDataSet
KPM_EXTERN int kpmSaveRefDataSet(const char *filename, const char *ext, KpmRefDataSet *refDataSet)
Definition: kpmRefDataSet.cpp:444
kpmSetSurfThreadNum
KPM_EXTERN int kpmSetSurfThreadNum(KpmHandle *kpmHandle, int surfThreadNum)
Definition: kpmHandle.cpp:217
KpmRefData
struct _KpmRefData KpmRefData
kpmSetMatchingSkipPage
KPM_EXTERN int kpmSetMatchingSkipPage(KpmHandle *kpmHandle, int *skipPages, int num)
kpmHandleGetXSize
KPM_EXTERN int kpmHandleGetXSize(const KpmHandle *kpmHandle)
Definition: kpmHandle.cpp:138
kpmSetRefDataSetFileOld
KPM_EXTERN int kpmSetRefDataSetFileOld(KpmHandle *kpmHandle, const char *filename, const char *ext)
Definition: kpmMatching.cpp:321
kpmGetPose
KPM_EXTERN int kpmGetPose(KpmHandle *kpmHandle, float pose[3][4], int *pageNo, float *error)
Definition: kpmResult.cpp:76
kpmCreateHandle
KPM_EXTERN KpmHandle * kpmCreateHandle(ARParamLT *cparamLT)
Allocate and initialise essential structures for KPM tracking, using full six degree-of-freedom track...
Definition: kpmHandle.cpp:48
kpmUtilGetCorner
KPM_EXTERN int kpmUtilGetCorner(ARUint8 *inImagePtr, int xsize, int ysize, int procMode, int maxPointNum, CornerPoints *cornerPoints)
Definition: kpmUtil.cpp:62
kpmCreateHandleHomography
KPM_EXTERN KpmHandle * kpmCreateHandleHomography(int xsize, int ysize)
Allocate and initialise essential structures for KPM tracking, using homography-only tracking.
Definition: kpmHandle.cpp:53
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.
Definition: kpmMatching.cpp:302
kpmLoadRefDataSetOld
KPM_EXTERN int kpmLoadRefDataSetOld(const char *filename, const char *ext, KpmRefDataSet **refDataSetPtr)
Definition: kpmRefDataSet.cpp:560
kpmMatching
KPM_EXTERN int kpmMatching(KpmHandle *kpmHandle, ARUint8 *inImageLuma)
Perform key-point matching on an image.
Definition: kpmMatching.cpp:381
kpmCreateHandle2
KPM_EXTERN KpmHandle * kpmCreateHandle2(int xsize, int ysize)
Definition: kpmHandle.cpp:58
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)
Definition: kpmRefDataSet.cpp:54
kpmUtilResizeImage
KPM_EXTERN ARUint8 * kpmUtilResizeImage(ARUint8 *imageLuma, int xsize, int ysize, int procMode, int *newXsize, int *newYsize)
Definition: kpmUtil.cpp:164
kpmGetDetectedFeatureMax
KPM_EXTERN int kpmGetDetectedFeatureMax(KpmHandle *kpmHandle, int *detectedMaxFeature)
Definition: kpmHandle.cpp:211
KPM_EXTERN
#define KPM_EXTERN
Definition: kpm.h:70
kpmGetResult
KPM_EXTERN int kpmGetResult(KpmHandle *kpmHandle, KpmResult **result, int *resultNum)
Definition: kpmResult.cpp:95
kpmMergeRefDataSet
KPM_EXTERN int kpmMergeRefDataSet(KpmRefDataSet **refDataSetPtr1, KpmRefDataSet **refDataSetPtr2)
Merge a second KPM dataset into the first, and dispose of second.
Definition: kpmRefDataSet.cpp:308
kpmLoadRefDataSet
KPM_EXTERN int kpmLoadRefDataSet(const char *filename, const char *ext, KpmRefDataSet **refDataSetPtr)
Load a reference data set from the filesystem into memory.
Definition: kpmRefDataSet.cpp:493
kpmHandleGetYSize
KPM_EXTERN int kpmHandleGetYSize(const KpmHandle *kpmHandle)
Definition: kpmHandle.cpp:144
wallclock
double wallclock(void)
kpmDeleteRefDataSet
KPM_EXTERN int kpmDeleteRefDataSet(KpmRefDataSet **refDataSetPtr)
Dispose of a reference data set and its allocated memory.
Definition: kpmRefDataSet.cpp:423
kpmSetDetectedFeatureMax
KPM_EXTERN int kpmSetDetectedFeatureMax(KpmHandle *kpmHandle, int detectedMaxFeature)
Definition: kpmHandle.cpp:202
kpmSetMatchingSkipRegion
int kpmSetMatchingSkipRegion(KpmHandle *kpmHandle, SurfSubRect *skipRegion, int regionNum)
Definition: kpmMatching.cpp:360
kpmGetMatchingResult
int kpmGetMatchingResult(KpmHandle *kpmHandle, KpmMatchResult **preRANSAC, KpmMatchResult **aftRANSAC)
Definition: kpmResult.cpp:62
kpmType.h
kpmUtilGetPose2
int kpmUtilGetPose2(ARParamLT *cparamLT, KpmMatchResult *matchData, KpmRefDataSet *refDataSet, int *redDataIndex, KpmInputDataSet *inputDataSet, float camPose[3][4], float *error)
Definition: kpmUtil.cpp:297
kpmUtilGetPose
int kpmUtilGetPose(ARParamLT *cparamLT, KpmMatchResult *matchData, KpmRefDataSet *refDataSet, KpmInputDataSet *inputDataSet, float camPose[3][4], float *error)
Definition: kpmUtil.cpp:184
kpmUtilGetPoseHomography
int kpmUtilGetPoseHomography(KpmMatchResult *matchData, KpmRefDataSet *refDataSet, KpmInputDataSet *inputDataSet, float camPose[3][4], float *error)
Definition: kpmUtil.cpp:408
_CornerPoints
Definition: kpmType.h:59
_KpmHandle
Definition: kpmPrivate.h:60
_KpmHandle::ysize
int ysize
Definition: kpmPrivate.h:70
_KpmHandle::result
KpmResult * result
Definition: kpmPrivate.h:88
_KpmHandle::procMode
KPM_PROC_MODE procMode
Definition: kpmPrivate.h:71
_KpmHandle::cparamLT
ARParamLT * cparamLT
Definition: kpmPrivate.h:68
_KpmHandle::skipRegion
KpmSkipRegionSet skipRegion
Definition: kpmPrivate.h:85
_KpmHandle::surfThreadNum
int surfThreadNum
Definition: kpmPrivate.h:74
_KpmHandle::refDataSet
KpmRefDataSet refDataSet
Definition: kpmPrivate.h:77
_KpmHandle::preRANSAC
KpmMatchResult preRANSAC
Definition: kpmPrivate.h:80
_KpmHandle::xsize
int xsize
Definition: kpmPrivate.h:70
_KpmHandle::aftRANSAC
KpmMatchResult aftRANSAC
Definition: kpmPrivate.h:81
_KpmHandle::detectedMaxFeature
int detectedMaxFeature
Definition: kpmPrivate.h:72
_KpmHandle::inDataSet
KpmInputDataSet inDataSet
Definition: kpmPrivate.h:78
_KpmHandle::resultNum
int resultNum
Definition: kpmPrivate.h:89
_KpmRefData
Definition: kpm.h:109
_KpmRefData::featureVec
FreakFeature featureVec
Definition: kpm.h:113
_KpmRefData::coord2D
KpmCoord2D coord2D
Definition: kpm.h:110
_KpmRefData::pageNo
int pageNo
Definition: kpm.h:117
_KpmRefData::coord3D
KpmCoord2D coord3D
Definition: kpm.h:111
_KpmRefData::refImageNo
int refImageNo
Definition: kpm.h:118
_SurfFeature
Definition: kpmType.h:94
ARParamLT
Structure holding camera parameters, in lookup table form.
Definition: param.h:151
KpmCoord2D
Definition: kpm.h:92
KpmCoord2D::y
float y
Definition: kpm.h:94
KpmCoord2D::x
float x
Definition: kpm.h:93
KpmImageInfo
Definition: kpm.h:97
KpmImageInfo::width
int width
Definition: kpm.h:98
KpmImageInfo::height
int height
Definition: kpm.h:99
KpmImageInfo::imageNo
int imageNo
Definition: kpm.h:100
KpmInputDataSet
Definition: kpm.h:148
KpmInputDataSet::num
int num
Definition: kpm.h:150
KpmInputDataSet::coord
KpmCoord2D * coord
Definition: kpm.h:149
KpmPageInfo
Definition: kpm.h:103
KpmPageInfo::imageInfo
KpmImageInfo * imageInfo
Definition: kpm.h:104
KpmPageInfo::imageNum
int imageNum
Definition: kpm.h:105
KpmPageInfo::pageNo
int pageNo
Definition: kpm.h:106
KpmRefDataSet
Definition: kpm.h:131
KpmRefDataSet::pageNum
int pageNum
Definition: kpm.h:135
KpmRefDataSet::refPoint
KpmRefData * refPoint
Definition: kpm.h:132
KpmRefDataSet::num
int num
Definition: kpm.h:133
KpmRefDataSet::pageInfo
KpmPageInfo * pageInfo
Definition: kpm.h:134
KpmResult
Definition: kpm.h:165
KpmResult::error
float error
Definition: kpm.h:168
KpmResult::camPoseF
int camPoseF
Definition: kpm.h:170
KpmResult::skipF
int skipF
Definition: kpm.h:171
KpmResult::pageNo
int pageNo
Definition: kpm.h:167
KpmResult::inlierNum
int inlierNum
Definition: kpm.h:169