ar

Includes:
<stdio.h>
<stdlib.h>
<stdint.h>
<AR/config.h>
<AR/arConfig.h>
<AR/matrix.h>
<AR/icp.h>
<AR/param.h>
<AR/arImageProc.h>

Introduction

ARToolKit core routines.



Groups

"Pattern identification".

Group members:

arPattActivate

Activate a previously deactivated pattern.

arPattAttach

Associate a set of patterns with an ARHandle.

arPattCreateHandle

Allocate a pattern handle.

arPattDeactivate

Deactivate a previously activated pattern.

arPattDeleteHandle

Free all loaded patterns and pattern handle.

arPattDetach

Reset an ARHandle to no pattern association.

arPattFree

Frees (unloads) a pattern file from memory.

arPattGetID2

Match the interior of a detected square against known patterns.

arPattGetIDGlobal

Match the interior of a detected square against known patterns with variable border width.

arPattGetImage2

Extract the image (i.e. locate and unwarp) of the pattern-space portion of a detected square.

arPattGetImage2b

Extract the image (i.e. locate and unwarp) of the pattern-space portion of a detected square with variable border width.

arPattLoad

Load a pattern file into a pattern handle.

arPattSave

Save a pattern to a pattern file.

arPattSaveb

Save a pattern with non-standard border width to a pattern file.

 

"Utility".

Group members:

arGetVersion

Get the ARToolKit version information in numberic and string format.

arUtilChangeToResourcesDirectory

Change to the resources directory using the specified behavior.

arUtilGetFileURI

Get a path as a file URI.

arUtilGetPixelFormatName

Get a string holding a descriptive name for a given pixel format enumeration.

arUtilGetPixelSize

Get the size in bytes of a single pixel for a given pixel format.

arUtilSleep

Relinquish CPU to the system for specified number of milliseconds.

 

"Square detection".

Group members:

arCreateHandle

Create a handle to hold settings for an ARToolKit tracker instance.

arDeleteHandle

Delete a handle which holds settings for an ARToolKit tracker instance.

arDetectMarker

Detect markers in a video frame.

arGetBorderSize

Get the border size.

arGetDebugMode

Find out whether ARToolKit's debug mode is enabled.

arGetImageProcMode

Get the image processing mode.

arGetLabelingMode

Enquire whether detection is looking for black markers or white markers.

arGetLabelingThresh

Get the current labeling threshold.

arGetLabelingThreshMode

Get the labeling threshold mode (auto/manual).

arGetLabelingThreshModeAutoInterval

Get the number of frames between auto-threshold calculations.

arGetMarkerExtractionMode

Get the marker extraction mode

arGetMarkerInfo

Examine a set of detected squares for match with known markers.

arGetMatrixCodeType

Get the size and ECC algorithm being used for matrix code (2D barcode) marker detection.

arGetPatternDetectionMode

Get the pattern detection mode

arGetPixelFormat

Get the expected pixel format for video frames being passed to arDetectMarker

arSetBorderSize

Set the border size.

arSetDebugMode

Enable or disable ARToolKit's debug mode.

arSetImageProcMode

Set the image processing mode.

arSetLabelingMode

Select between detection of black markers and white markers.

arSetLabelingThresh

Set the labeling threshhold.

arSetLabelingThreshMode

Set the labeling threshold mode (auto/manual).

arSetLabelingThreshModeAutoInterval

Set the number of frames between auto-threshold calculations.

arSetMarkerExtractionMode

Set the marker extraction mode

arSetMatrixCodeType

Set the size and ECC algorithm to be used for matrix code (2D barcode) marker detection.

arSetPatternDetectionMode

Set the pattern detection mode

arSetPixelFormat

Set the expected pixel format for video frames being passed to arDetectMarker

 

"3D calculation".

Group members:

ar3DChangeCpara

(description)

ar3DChangeLoopBreakThresh

(description)

ar3DChangeLoopBreakThreshRatio

(description)

ar3DChangeMaxLoopCount

(description)

ar3DCreateHandle

Create handle used for 3D calculation from calibrated camera parameters.

ar3DCreateHandle2

Create handle used for 3D calculation from an intrinsic parameters matrix.

ar3DDeleteHandle

Delete handle used for 3D calculation.

arGetTransMat

(description)

arGetTransMatRobust

(description)

arGetTransMatSquare

(description)

arGetTransMatSquareCont

(description)

 

"3D calculation by Stereo".


Functions

ar3DChangeCpara

(description)

ar3DChangeLoopBreakThresh

(description)

ar3DChangeLoopBreakThreshRatio

(description)

ar3DChangeMaxLoopCount

(description)

ar3DCreateHandle

Create handle used for 3D calculation from calibrated camera parameters.

ar3DCreateHandle2

Create handle used for 3D calculation from an intrinsic parameters matrix.

ar3DDeleteHandle

Delete handle used for 3D calculation.

arCreateHandle

Create a handle to hold settings for an ARToolKit tracker instance.

arDeleteHandle

Delete a handle which holds settings for an ARToolKit tracker instance.

arDetectMarker

Detect markers in a video frame.

arGetBorderSize

Get the border size.

arGetDebugMode

Find out whether ARToolKit's debug mode is enabled.

arGetImageProcMode

Get the image processing mode.

arGetLabelingMode

Enquire whether detection is looking for black markers or white markers.

arGetLabelingThresh

Get the current labeling threshold.

arGetLabelingThreshMode

Get the labeling threshold mode (auto/manual).

arGetLabelingThreshModeAutoInterval

Get the number of frames between auto-threshold calculations.

arGetMarkerExtractionMode

Get the marker extraction mode

arGetMarkerInfo

Examine a set of detected squares for match with known markers.

arGetMatrixCodeType

Get the size and ECC algorithm being used for matrix code (2D barcode) marker detection.

arGetPatternDetectionMode

Get the pattern detection mode

arGetPixelFormat

Get the expected pixel format for video frames being passed to arDetectMarker

arGetTransMat

(description)

arGetTransMatRobust

(description)

arGetTransMatSquare

(description)

arGetTransMatSquareCont

(description)

arGetVersion

Get the ARToolKit version information in numberic and string format.

arPattActivate

Activate a previously deactivated pattern.

arPattAttach

Associate a set of patterns with an ARHandle.

arPattCreateHandle

Allocate a pattern handle.

arPattDeactivate

Deactivate a previously activated pattern.

arPattDeleteHandle

Free all loaded patterns and pattern handle.

arPattDetach

Reset an ARHandle to no pattern association.

arPattFree

Frees (unloads) a pattern file from memory.

arPattGetID2

Match the interior of a detected square against known patterns.

arPattGetIDGlobal

Match the interior of a detected square against known patterns with variable border width.

arPattGetImage2

Extract the image (i.e. locate and unwarp) of the pattern-space portion of a detected square.

arPattGetImage2b

Extract the image (i.e. locate and unwarp) of the pattern-space portion of a detected square with variable border width.

arPattLoad

Load a pattern file into a pattern handle.

arPattSave

Save a pattern to a pattern file.

arPattSaveb

Save a pattern with non-standard border width to a pattern file.

arSetBorderSize

Set the border size.

arSetDebugMode

Enable or disable ARToolKit's debug mode.

arSetImageProcMode

Set the image processing mode.

arSetLabelingMode

Select between detection of black markers and white markers.

arSetLabelingThresh

Set the labeling threshhold.

arSetLabelingThreshMode

Set the labeling threshold mode (auto/manual).

arSetLabelingThreshModeAutoInterval

Set the number of frames between auto-threshold calculations.

arSetMarkerExtractionMode

Set the marker extraction mode

arSetMatrixCodeType

Set the size and ECC algorithm to be used for matrix code (2D barcode) marker detection.

arSetPatternDetectionMode

Set the pattern detection mode

arSetPixelFormat

Set the expected pixel format for video frames being passed to arDetectMarker

arUtilChangeToResourcesDirectory

Change to the resources directory using the specified behavior.

arUtilGetFileURI

Get a path as a file URI.

arUtilGetPixelFormatName

Get a string holding a descriptive name for a given pixel format enumeration.

arUtilGetPixelSize

Get the size in bytes of a single pixel for a given pixel format.

arUtilSleep

Relinquish CPU to the system for specified number of milliseconds.


ar3DChangeCpara


(description)

int ar3DChangeCpara(
    AR3DHandle *handle,
    ARdouble cpara[3][4] );  
Parameters
handle

(description)

cpara

(description)

Return Value

(description)

Discussion

(description)


ar3DChangeLoopBreakThresh


(description)

int ar3DChangeLoopBreakThresh(
    AR3DHandle *handle,
    ARdouble loopBreakThresh );  
Parameters
handle

(description)

loopBreakThresh

(description)

Return Value

(description)

Discussion

(description)


ar3DChangeLoopBreakThreshRatio


(description)

int ar3DChangeLoopBreakThreshRatio(
    AR3DHandle *handle,
    ARdouble loopBreakThreshRatio );  
Parameters
handle

(description)

loopBreakThreshRatio

(description)

Return Value

(description)

Discussion

(description)


ar3DChangeMaxLoopCount


(description)

int ar3DChangeMaxLoopCount(
    AR3DHandle *handle,
    int maxLoopCount );  
Parameters
handle

(description)

maxLoopCount

(description)

Return Value

(description)

Discussion

(description)


ar3DCreateHandle


Create handle used for 3D calculation from calibrated camera parameters.

Parameters
arParam

(description)

Return Value

The handle. When no more ar3D*() functions need be called, the handle should be deleted by calling ar3DDeleteHandle().

Discussion

An AR3DHandle holds data structures used in calculating the 3D pose of a marker from the 2D location of its corners (i.e. pose estimation).

See Also


ar3DCreateHandle2


Create handle used for 3D calculation from an intrinsic parameters matrix.

AR3DHandle *ar3DCreateHandle2(
    ARdouble cpara[3][4]);  
Parameters
cpara

(description)

Return Value

The handle. When no more ar3D*() functions need be called, the handle should be deleted by calling ar3DDeleteHandle().

Discussion

An AR3DHandle holds data structures used in calculating the 3D pose of a marker from the 2D location of its corners (i.e. pose estimation).

See Also


ar3DDeleteHandle


Delete handle used for 3D calculation.

int ar3DDeleteHandle(
    AR3DHandle **handle );  
Parameters
handle

A pointer to the 3D handle. On success, the contents of this location will be set to NULL.

Return Value

0 if the handle was successfully deleted, -1 otherwise.

Discussion

When no more ar3D*() functions need be called, the handle should be deleted by calling ar3DDeleteHandle().

See Also


arCreateHandle


Create a handle to hold settings for an ARToolKit tracker instance.

Parameters
param

The created handle will hold a pointer to the calibrated camera parameters specified by this parameter.

Return Value

An ARHandle which should be passed to other functions which deal with the operations of the ARToolKit tracker.

Discussion

(description)


arDeleteHandle


Delete a handle which holds settings for an ARToolKit tracker instance.

int arDeleteHandle(
    ARHandle *handle );  
Parameters
handle

The handle to delete, as created by arCreateHandle();

Return Value

0 if no error occured.

Discussion

The calibrated camera parameters pointed to by the handle are NOT deleted by this operation.


arDetectMarker


Detect markers in a video frame.

int arDetectMarker(
    ARHandle *arHandle,
    ARUint8 *dataPtr );  
Parameters
arHandle

Handle to initialised settings, including camera parameters, markers, detection modes and other information.

dataPtr

Pointer to the first byte of a block of memory containing pixel data for an image which is to be processed for marker detection. The format of pixels in this image is specified by arSetPixelFormat(). The width and height of the image are specified by the xsize and ysize parameters of the camera parameters held in arHandle.

Return Value

0 if the function proceeded without error, or a value < 0 in case of error. A result of 0 does not imply any markers were detected.

Discussion

This is the core ARToolKit marker detection function. It calls through to a set of internal functions to perform the key marker detection steps of binarization and labelling, contour extraction, and template matching and/or matrix code extraction.


arGetBorderSize


Get the border size.

int arGetBorderSize(
    ARHandle *handle,
    ARdouble *borderSize );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its border size.

borderSize

Pointer into which will be placed the value representing the border size. The default border size for newly-created ARHandle structures is AR_BORDER_SIZE_DEFAULT.

Return Value

0 if no error occured.


arGetDebugMode


Find out whether ARToolKit's debug mode is enabled.

int arGetDebugMode(
    ARHandle *handle,
    int *mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its mode.

mode

Pointer into which will be placed the value representing the mode.

Return Value

0 if no error occured.

Discussion

See arSetDebugMode() for more info.


arGetImageProcMode


Get the image processing mode.

int arGetImageProcMode(
    ARHandle *handle,
    int *mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its mode.

mode

Pointer into which will be placed the value representing the current image processing mode.

Return Value

0 if no error occured.

Discussion

See arSetImageProcMode() for a complete description.


arGetLabelingMode


Enquire whether detection is looking for black markers or white markers.

int arGetLabelingMode(
    ARHandle *handle,
    int *mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its labeling mode.

mode

Pointer into which will be placed the value representing the mode.

Return Value

0 if no error occured.

Discussion

See discussion for arSetLabelingMode.


arGetLabelingThresh


Get the current labeling threshold.

int arGetLabelingThresh(
    ARHandle *handle,
    int *thresh );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its labeling threshold value.

thresh

Pointer into which will be placed the value of the labeling threshhold. An integer in the range [0,255] (inclusive)

Return Value

0 if no error occured.

Discussion

This function queries the current labeling threshold. For, AR_LABELING_THRESH_MODE_AUTO_MEDIAN and AR_LABELING_THRESH_MODE_AUTO_OTSU, the threshold value is only valid until the next auto-update. The current threshold mode is not affected by this call. The threshold value is not relevant if threshold mode is AR_LABELING_THRESH_MODE_AUTO_ADAPTIVE.

See Also


arGetLabelingThreshMode


Get the labeling threshold mode (auto/manual).

int arGetLabelingThreshMode(
    const ARHandle *handle,
    AR_LABELING_THRESH_MODE *mode_p);  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its labeling threshold value.

mode_p

Pointer into which will be placed the value of the labeling threshold mode, one of: AR_LABELING_THRESH_MODE_MANUAL, AR_LABELING_THRESH_MODE_AUTO_MEDIAN, AR_LABELING_THRESH_MODE_AUTO_OTSU, AR_LABELING_THRESH_MODE_AUTO_ADAPTIVE

Return Value

0 if no error occured.

See Also


arGetLabelingThreshModeAutoInterval


Get the number of frames between auto-threshold calculations.

int arGetLabelingThreshModeAutoInterval(
    const ARHandle *handle,
    int *interval_p);  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its labeling threshold auto interval value.

interval_p

Pointer into which will be placed the value of the labeling threshhold auto interval. An integer in the range [0,INT_MAX] (inclusive)

Return Value

0 if no error occured.

Discussion

This is the number of frames BETWEEN calculations, meaning that the calculation occurs every (interval + 1) frames.

See Also


arGetMarkerExtractionMode


Get the marker extraction mode

int arGetMarkerExtractionMode(
    ARHandle *handle,
    int *mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its mode.

mode

Pointer into which will be placed the value representing the mode.

Return Value

0 if no error occured.

Discussion

(description)


arGetMarkerInfo


Examine a set of detected squares for match with known markers.

int arGetMarkerInfo(
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat, 
    ARMarkerInfo2 *markerInfo2,
    int marker2_num, 
    ARPattHandle *pattHandle,
    int imageProcMode,
    int pattDetectMode,
    ARdouble dist_factor[], 
    ARMarkerInfo *markerInfo,
    int *marker_num, 
    int dist_function_version,
    const AR_MATRIX_CODE_TYPE matrixCodeType,
    const ARdouble borderSize );  
Parameters
image

Image in which squares were detected.

xsize

Horizontal dimension of image, in pixels.

ysize

Vertical dimension of image, in pixels.

pixelFormat

Format of pixels in image. See <AR/config.h> for values.

markerInfo2

Pointer to an array of ARMarkerInfo2 structures holding information on detected squares which are candidates for marker matching.

marker2_num

Size of markerInfo2 array.

pattHandle

Handle to loaded patterns for template matching against detected squares.

imageProcMode

Indicates whether square detection was performed treating the image as a frame or a field.

pattDetectMode

Whether to perform color/mono template matching, matrix code detection, or both.

dist_factor

Lens distortion model factors.

markerInfo

Output: Pointer to an array of ARMarkerInfo structures holding information on successful matches.

marker_num

Output: Size of markerInfo array.

dist_function_version

Version of lens distortion model passed in dist_factor.

matrixCodeType

When matrix code pattern detection mode is active, indicates the type of matrix code to detect.

borderSize

A value between 0.0 and 0.5, representing the proportion of the marker width which defines the border region.

Return Value

0 in case of no error, or -1 otherwise.

Discussion

Performs the intermediate marker-detection stage of taking detected squares in a processed image, and matching the interior of these squares against known marker templates, or extracting matrix codes from the interior of the square.


arGetMatrixCodeType


Get the size and ECC algorithm being used for matrix code (2D barcode) marker detection.

int arGetMatrixCodeType(
    ARHandle *handle,
    AR_MATRIX_CODE_TYPE *type_p);  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its mode.

type_p

Pointer into which will be placed the value representing the mode.

Return Value

0 if no error occured.

Discussion

See the description for arSetMatrixCodeType().

See Also


arGetPatternDetectionMode


Get the pattern detection mode

int arGetPatternDetectionMode(
    ARHandle *handle,
    int *mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its mode.

mode

Pointer into which will be placed the value representing the mode.

Return Value

0 if no error occured.

Discussion

See arSetPatternDetectionMode() for a complete description.


arGetPixelFormat


Get the expected pixel format for video frames being passed to arDetectMarker

int arGetPixelFormat(
    ARHandle *handle,
    AR_PIXEL_FORMAT *pixFormat );  
Parameters
handle

Handle to AR settings structure from which to retrieve the pixel format.

pixFormat

Pointer into which will be placed the value representing the format of pixels being processed by the ARToolKit detection routines. See AR_PIXEL_FORMAT reference for more information.

Return Value

0 if no error occured.

Discussion

(description)


arGetTransMat


(description)

ARdouble arGetTransMat(
    AR3DHandle *handle,
    ARdouble initConv[3][4], 
    ARdouble pos2d[][2],
    ARdouble pos3d[][3],
    int num, 
    ARdouble conv[3][4] );  
Parameters
handle

(description)

(description)

initConv

(description)

pos2d

(description)

pos3d

(description)

num

(description)

conv

(description)

Return Value

(description)

Discussion

(description)


arGetTransMatRobust


(description)

ARdouble arGetTransMatRobust(
    AR3DHandle *handle,
    ARdouble initConv[3][4], 
    ARdouble pos2d[][2],
    ARdouble pos3d[][3],
    int num, 
    ARdouble conv[3][4] );  
Parameters
handle

(description)

initConv

(description)

pos2d

(description)

pos3d

(description)

num

(description)

conv

(description)

Return Value

(description)

Discussion

(description)


arGetTransMatSquare


(description)

ARdouble arGetTransMatSquare(
    AR3DHandle *handle,
    ARMarkerInfo *marker_info, 
    ARdouble width,
    ARdouble conv[3][4] );  
Parameters
handle

(description)

marker_info

(description)

width

(description)

conv

(description)

Return Value

(description)

Discussion

(description)


arGetTransMatSquareCont


(description)

ARdouble arGetTransMatSquareCont(
    AR3DHandle *handle,
    ARMarkerInfo *marker_info, 
    ARdouble initConv[3][4], 
    ARdouble width,
    ARdouble conv[3][4] );  
Parameters
handle

(description)

marker_info

(description)

initConv

(description)

width

(description)

conv

(description)

Return Value

(description)

Discussion

(description)


arGetVersion


Get the ARToolKit version information in numberic and string format.

ARUint32 arGetVersion(
    char **versionStringRef);  
Parameters
versionStringRef

If non-NULL, the location pointed to will be filled with a pointer to a string containing the version information. Fields in the version string are separated by spaces. As of version 2.72.0, there is only one field implemented, and this field contains the major, minor and tiny version numbers in dotted-decimal format. The string is guaranteed to contain at least this field in all future versions of the toolkit. Later versions of the toolkit may add other fields to this string to report other types of version information. The storage for the string is malloc'ed inside the function. The caller is responsible for free'ing the string.

Return Value

Returns the full version number of the ARToolKit in binary coded decimal (BCD) format. BCD format allows simple tests of version number in the caller e.g. if ((arGetVersion(NULL) >> 16) > 0x0272) printf("This release is later than 2.72\n"); The major version number is encoded in the most-significant byte (bits 31-24), the minor version number in the second-most-significant byte (bits 23-16), the tiny version number in the third-most-significant byte (bits 15-8), and the build version number in the least-significant byte (bits 7-0).

Discussion

As of version 2.72, ARToolKit now allows querying of the version number of the toolkit available at runtime. It is highly recommended that any calling program that depends on features in a certain ARToolKit version, check at runtime that it is linked to a version of ARToolKit that can supply those features. It is NOT sufficient to check the ARToolKit SDK header versions, since with ARToolKit implemented in dynamically-loaded libraries, there is no guarantee that the version of ARToolKit installed on the machine at run-time will be as recent as the version of the ARToolKit SDK which the host program was compiled against.

The version information is reported in binary-coded decimal format, and optionally in an ASCII string.

A increase in the major version number indicates the removal of functionality previously provided in the API. An increase in the minor version number indicates that new functionality has been added. A change in the tiny version number indicates changes (e.g. bug fixes) which do not affect the API. See the comments in the config.h header for more discussion of the definition of major, minor, tiny and build version numbers.


arPattActivate


Activate a previously deactivated pattern.

int arPattActivate(
    ARPattHandle *pattHandle,
    int patno );  
Parameters
pattHandle

The handle holding the loaded pattern which is to be reactivated.

patno

The index into the pattern handle's array of patterns to the pattern to be reactivated.

Return Value

0 on success, or -1 if the pattern was already activated or no pattern was loaded.

Discussion

When a pattern is activated, is becomes available for recognition in a scene. This is the default state for a loaded pattern.

See Also


arPattAttach


Associate a set of patterns with an ARHandle.

int arPattAttach(
    ARHandle *arHandle,
    ARPattHandle *pattHandle);  
Parameters
arHandle

(description)

pattHandle

(description)

Return Value

Returns 0 in the case of success, or -1 if the specified ARHandle already has an ARPattHandle attached, or if arHandle is NULL.

Discussion

Associating a set of patterns with an ARHandle makes the patterns the set which will be searched when marker identification is performed on an image associated with the same ARHandle.

See Also


arPattCreateHandle


Allocate a pattern handle.

Return Value

The created pattern handle, or NULL in case of error.

Discussion

Allocates an empty pattern handle, into which patterns can be loaded by calling arPattLoad(). When the pattern handle is no longer needed, it should be freed by calling arPattDeleteHandle().

Note that a pattern handle is NOT required when using only matrix- code (2D barcode) markers.

See Also


arPattDeactivate


Deactivate a previously activated pattern.

int arPattDeactivate(
    ARPattHandle *pattHandle,
    int patno);  
Parameters
pattHandle

The handle holding the loaded pattern which is to be deactivated.

patno

The index into the pattern handle's array of patterns to the pattern to be deactivated.

Return Value

0 on success, or -1 if the pattern was already deactivated or no pattern was loaded.

Discussion

When a pattern is activated, is becomes unavailable for recognition in a scene. Deactivating unused patterns can speed up recognition time and accuracy when there are multiple patterns in a scene, and it is also useful for controlling interactivity in a scene.

See Also


arPattDeleteHandle


Free all loaded patterns and pattern handle.

int arPattDeleteHandle(
    ARPattHandle *pattHandle);  
Parameters
pattHandle

The handle to free.

Return Value

0 on success, or -1 if trying to free a NULL handle.

Discussion

Frees a pattern handle, freeing (unloading) any patterns loaded into the handle in the process.


arPattDetach


Reset an ARHandle to no pattern association.

int arPattDetach(
    ARHandle *arHandle);  
Parameters
arHandle

(description)

Return Value

Returns 0 in the case of success, or -1 if the specified ARHandle has no ARPattHandle attached, or if arHandle is NULL.

Discussion

See arPattAttach() for more information.

See Also


arPattFree


Frees (unloads) a pattern file from memory.

int arPattFree(
    ARPattHandle *pattHandle,
    int patno );  
Parameters
pattHandle

The pattern handle to unload from.

patno

The index into the pattern handle's array of patterns to the pattern to be unloaded.

Return Value

0 if the pattern was successfully unloaded, or -1 if there was no pattern loaded.

Discussion

Unloads a pattern from a pattern handle, freeing that slot for another pattern to be loaded, if necessary.

See Also


arPattGetID2


Match the interior of a detected square against known patterns.

int arPattGetID2(
    ARPattHandle *pattHandle,
    int imageProcMode,
    int pattDetectMode, 
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat,
    ARdouble dist_factor[],
    ARdouble vertex[4][2], 
    int *codePatt,
    int *dirPatt,
    ARdouble *cfPatt,
    int *codeMatrix,
    int *dirMatrix,
    ARdouble *cfMatrix, 
    int dist_function_version,
    const AR_MATRIX_CODE_TYPE matrixCodeType );  
Parameters
pattHandle

Handle contained details of known patterns, i.e. loaded templates, or valid barcode IDs.

imageProcMode

See discussion of arSetImageProcMode().

pattDetectMode

See discussion of arSetPatternDetectionMode().

image

Pointer to packed raw image data.

xsize

Horizontal pixel dimension of raw image data.

ysize

Vertical pixel dimension of raw image data.

pixelFormat

Pixel format of raw image data.

dist_factor

Distortion factor of imaging source from which image was acquired.

dist_function_version

Version of the distortion factor measurement.

vertex

4x2 array of points which correspond to the x and y locations of the corners of the detected marker square.

codePatt

Where the pattern matching mode includes template (picture) matching, and a valid template is matched, the ID of the pattern from pattHandle, or -1 if not identified.

dirPatt

Where the pattern matching mode includes template (picture) matching, and a valid template is matched, the direction (up, right, down, left) of the pattern from pattHandle.

cfPatt

Where the pattern matching mode includes template (picture) matching, and a valid template is matched, the confidence factor of the match (range [0.0 - 1.0]).

codeMatrix

Where the pattern matching mode includes matrix (barcode) matching, and a valid matrix is matched, the ID of the pattern, or -1 if not identified.

dirMatrix

Where the pattern matching mode includes matrix (barcode) matching, and a valid matrix is matched, the direction (up, right, down, left) of the pattern.

cfMatrix

Where the pattern matching mode includes matrix (barcode) matching, and a valid matrix is matched, the confidence factor of the match (range [0.0 - 1.0]).

matrixCodeType

When matrix code pattern detection mode is active, indicates the type of matrix code to detect.

Return Value

0 if the function was able to correctly match, or -1 in case of error or no match.


arPattGetIDGlobal


Match the interior of a detected square against known patterns with variable border width.

int arPattGetIDGlobal(
    ARPattHandle *pattHandle,
    int imageProcMode,
    int pattDetectMode, 
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat,
    ARdouble dist_factor[],
    ARdouble vertex[4][2], 
    int *codePatt,
    int *dirPatt,
    ARdouble *cfPatt,
    int *codeMatrix,
    int *dirMatrix,
    ARdouble *cfMatrix, 
    int dist_function_version,
    const AR_MATRIX_CODE_TYPE matrixCodeType,
    const ARdouble borderSize,
    int *errorCorrected,
    uint64_t *codeGlobalID_p );  
Parameters
pattHandle

Handle contained details of known patterns, i.e. loaded templates, or valid barcode IDs.

imageProcMode

See discussion of arSetImageProcMode().

pattDetectMode

See discussion of arSetPatternDetectionMode().

image

Pointer to packed raw image data.

xsize

Horizontal pixel dimension of raw image data.

ysize

Vertical pixel dimension of raw image data.

pixelFormat

Pixel format of raw image data.

dist_factor

Distortion factor of imaging source from which image was acquired.

dist_function_version

Version of the distortion factor measurement.

vertex

4x2 array of points which correspond to the x and y locations of the corners of the detected marker square.

codePatt

Where the pattern matching mode includes template (picture) matching, and a valid template is matched, the ID of the pattern from pattHandle, or -1 if not identified.

dirPatt

Where the pattern matching mode includes template (picture) matching, and a valid template is matched, the direction (up, right, down, left) of the pattern from pattHandle.

cfPatt

Where the pattern matching mode includes template (picture) matching, and a valid template is matched, the confidence factor of the match (range [0.0 - 1.0]).

codeMatrix

Where the pattern matching mode includes matrix (barcode) matching, and a valid matrix is matched, the ID of the pattern, or -1 if not identified.

dirMatrix

Where the pattern matching mode includes matrix (barcode) matching, and a valid matrix is matched, the direction (up, right, down, left) of the pattern.

cfMatrix

Where the pattern matching mode includes matrix (barcode) matching, and a valid matrix is matched, the confidence factor of the match (range [0.0 - 1.0]).

matrixCodeType

When matrix code pattern detection mode is active, indicates the type of matrix code to detect.

borderSize

A value between 0.0 and 0.5, representing the proportion of the marker width which defines the border region.

errorCorrected

Pointer to an integer which will be filled out with the number of errors detected and corrected during marker identification, or NULL if this information is not required.

codeGlobalID_p

Pointer to uint64_t which will be filled out with the global ID, or NULL if this value is not required.

Return Value

0 if the function was able to correctly match, or -1 in case of error or no match.


arPattGetImage2


Extract the image (i.e. locate and unwarp) of the pattern-space portion of a detected square.

int arPattGetImage2(
    int imageProcMode,
    int pattDetectMode,
    int patt_size,
    int sample_size, 
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat,
    ARdouble dist_factor[], 
    ARdouble vertex[4][2],
    ARUint8 *ext_patt,
    int dist_function_version );  
Parameters
imageProcMode

See discussion of arSetImageProcMode().

pattDetectMode

See discussion of arSetPatternDetectionMode().

patt_size

The number of horizontal and vertical units to subdivide the pattern-space into.

sample_size

At present, must always be the square of patt_size.

image

Pointer to packed raw image data.

xsize

Horizontal pixel dimension of raw image data.

ysize

Vertical pixel dimension of raw image data.

pixelFormat

Pixel format of raw image data.

dist_factor

Distortion factor of imaging source from which image was acquired.

dist_function_version

Version of the distortion factor measurement.

vertex

4x2 array of points which correspond to the x and y locations of the corners of the detected marker square.

ext_patt

Pointer to an array of appropriate size (i.e. patt_size*patt_size*3), which will be filled with the extracted image. Where a colour image is available, it will be supplied in BGR byte order.

Return Value

0 if the function was able to correctly get the image, or -1 in case of error or no match.


arPattGetImage2b


Extract the image (i.e. locate and unwarp) of the pattern-space portion of a detected square with variable border width.

int arPattGetImage2b(
    int imageProcMode,
    int pattDetectMode,
    int patt_size,
    int sample_size, 
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat,
    ARdouble dist_factor[], 
    ARdouble vertex[4][2],
    ARUint8 *ext_patt,
    int dist_function_version,
    const ARdouble borderSize);  
Parameters
imageProcMode

See discussion of arSetImageProcMode().

pattDetectMode

See discussion of arSetPatternDetectionMode().

patt_size

The number of horizontal and vertical units to subdivide the pattern-space into.

sample_size

At present, must always be the square of patt_size.

image

Pointer to packed raw image data.

xsize

Horizontal pixel dimension of raw image data.

ysize

Vertical pixel dimension of raw image data.

pixelFormat

Pixel format of raw image data.

dist_factor

Distortion factor of imaging source from which image was acquired.

dist_function_version

Version of the distortion factor measurement.

vertex

4x2 array of points which correspond to the x and y locations of the corners of the detected marker square.

ext_patt

Pointer to an array of appropriate size (i.e. patt_size*patt_size*3), which will be filled with the extracted image. Where a colour image is available, it will be supplied in BGR byte order.

borderSize

A value between 0.0 and 0.5, representing the proportion of the marker width which defines the border region.

Return Value

0 if the function was able to correctly get the image, or -1 in case of error or no match.


arPattLoad


Load a pattern file into a pattern handle.

int arPattLoad(
    ARPattHandle *pattHandle,
    const char *filename );  
Parameters
pattHandle

Pattern handle, as generated by arPattCreateHandle(), into which the pattern file infomation will be loaded.

filename

Pathname of pattern file to load. The pattern file is typically generated by the make_patt program. The pathname is relative to the current working directory, which is operating system- specific.

Return Value

Returns the index number of the loaded pattern, in the range [0, AR_PATT_NUM_MAX - 1], or -1 if the pattern could not be loaded because the maximum number of patterns (AR_PATT_NUM_MAX) has already been loaded already into this handle.

Discussion

This function loads a pattern template from a file on disk, and attaches it to the given ARPattHandle so making it available for future pattern-matching. Additional patterns can be loaded by calling again with the same ARPattHandle (however no more than AR_PATT_NUM_MAX patterns can be attached to a single ARPattHandle). Patterns are initially loaded in an active state.

Note that matrix-code (2D barcode) markers do not have any associated pattern file and do not need to be loaded.

See Also


arPattSave


Save a pattern to a pattern file.

int arPattSave(
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat,
    ARdouble dist_factor[], 
    int imageProcMode,
    ARMarkerInfo *marker_info,
    const char *filename,
    int dist_function_version );  
Parameters
image

(description)

xsize

(description)

ysize

(description)

pixelFormat

(description)

dist_factor

(description)

imageProcMode

(description)

marker_info

(description)

filename

(description)

dist_function_version

an integer, corresponding to the version number of the distortion function used to create the data in dist_factor.

Return Value

(description)

Discussion

This function is used by the make_patt utility. See the sourcecode to mk_patt for usage.


arPattSaveb


Save a pattern with non-standard border width to a pattern file.

int arPattSaveb(
    ARUint8 *image,
    int xsize,
    int ysize,
    int pixelFormat,
    ARdouble dist_factor[], 
    int imageProcMode,
    ARMarkerInfo *marker_info,
    const char *filename,
    int dist_function_version,
    const ARdouble borderSize );  
Parameters
image

(description)

xsize

(description)

ysize

(description)

pixelFormat

(description)

dist_factor

(description)

imageProcMode

(description)

marker_info

(description)

filename

(description)

dist_function_version

an integer, corresponding to the version number of the distortion function used to create the data in dist_factor.

borderSize

Width of border inside the marker, in range (0, 0.5).

Return Value

(description)

Discussion

This function is used by the make_patt utility. See the sourcecode to mk_patt for usage.


arSetBorderSize


Set the border size.

int arSetBorderSize(
    ARHandle *handle,
    const ARdouble borderSize );  
Parameters
handle

An ARHandle referring to the current AR tracker to have its border size set.

borderSize

The border size. To set the default, pass AR_BORDER_SIZE_DEFAULT. If compatibility with ARToolKit verions 1.0 through 4.4 is required, this value must be 0.25.

Return Value

0 if no error occured.


arSetDebugMode


Enable or disable ARToolKit's debug mode.

int arSetDebugMode(
    ARHandle *handle,
    int mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its debug mode.

mode

Options for this field are: AR_DEBUG_DISABLE AR_DEBUG_ENABLE The default mode is AR_DEBUG_DISABLE.

Return Value

0 if no error occured.

Discussion

In debug mode, ARToolKit offers additional error reporting. Use this function to enable or disable debug mode at runtime.

Additionally, in debug mode, ARToolKit creates a mono (8-bit grayscale) image of the thresholded video input, and makes this available through the field ARHandle->labelImage.


arSetImageProcMode


Set the image processing mode.

int arSetImageProcMode(
    ARHandle *handle,
    int mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to have its mode set.

mode

Options for this field are: AR_IMAGE_PROC_FRAME_IMAGE AR_IMAGE_PROC_FIELD_IMAGE The default mode is AR_IMAGE_PROC_FRAME_IMAGE.

Return Value

0 if no error occured.

Discussion

When ARthe image processing mode is AR_IMAGE_PROC_FRAME_IMAGE, ARToolKit processes all pixels in each incoming image to locate markers. When the mode is AR_IMAGE_PROC_FIELD_IMAGE, ARToolKit processes pixels in only every second pixel row and column. This is useful both for handling images from interlaced video sources (where alternate lines are assembled from alternate fields and thus have one field time-difference, resulting in a "comb" effect) such as Digital Video cameras. The effective reduction by 75% in the pixels processed also has utility in accelerating tracking by effectively reducing the image size to one quarter size, at the cost of pose accuraccy.


arSetLabelingMode


Select between detection of black markers and white markers.

int arSetLabelingMode(
    ARHandle *handle,
    int mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to have its labeling mode set.

mode

Options for this field are: AR_LABELING_WHITE_REGION AR_LABELING_BLACK_REGION The default mode is AR_LABELING_BLACK_REGION.

Return Value

0 if no error occured.

Discussion

ARToolKit's labelling algorithm can work with both black-bordered markers on a white background (AR_LABELING_BLACK_REGION) or white-bordered markers on a black background (AR_LABELING_WHITE_REGION). This function allows you to specify the type of markers to look for. Note that this does not affect the pattern-detection algorith which works on the interior of the marker.


arSetLabelingThresh


Set the labeling threshhold.

int arSetLabelingThresh(
    ARHandle *handle,
    int thresh );  
Parameters
handle

An ARHandle referring to the current AR tracker to have its labeling threshold value set.

thresh

An integer in the range [0,255] (inclusive).

Return Value

0 if no error occured.

Discussion

This function forces the labeling threshold mode to AR_LABELING_THRESH_MODE_MANUAL and sets the threshold value. The default value is AR_DEFAULT_LABELING_THRESHm which is 100, unless edited in arConfig.h.

Background: The labeling threshold is the value which the AR library uses to differentiate between black and white portions of an ARToolKit marker. Since the actual brightness, contrast, and gamma of incoming images can vary signficantly between different cameras and lighting conditions, this value typically needs to be adjusted dynamically to a suitable midpoint between the observed values for black and white portions of the markers in the image.


arSetLabelingThreshMode


Set the labeling threshold mode (auto/manual).

int arSetLabelingThreshMode(
    ARHandle *handle,
    const AR_LABELING_THRESH_MODE mode);  
Parameters
handle

An ARHandle referring to the current AR tracker to be queried for its labeling threshold mode.

mode

An integer specifying the mode. One of: AR_LABELING_THRESH_MODE_MANUAL, AR_LABELING_THRESH_MODE_AUTO_MEDIAN, AR_LABELING_THRESH_MODE_AUTO_OTSU, AR_LABELING_THRESH_MODE_AUTO_ADAPTIVE

Return Value

0 if no error occured.

See Also


arSetLabelingThreshModeAutoInterval


Set the number of frames between auto-threshold calculations.

int arSetLabelingThreshModeAutoInterval(
    ARHandle *handle,
    const int interval);  
Parameters
handle

An ARHandle referring to the current AR tracker for which the labeling threshold auto interval will be set.

interval

The interval, specifying the number of frames between automatic updates to the threshold. An integer in the range [0,INT_MAX] (inclusive). Default value is AR_LABELING_THRESH_AUTO_INTERVAL_DEFAULT.

Return Value

0 if no error occured.

Discussion

This is the number of frames BETWEEN calculations, meaning that the calculation occurs every (interval + 1) frames.

See Also


arSetMarkerExtractionMode


Set the marker extraction mode

int arSetMarkerExtractionMode(
    ARHandle *handle,
    int mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to have its mode set.

mode

Options for this field are: AR_USE_TRACKING_HISTORY AR_NOUSE_TRACKING_HISTORY AR_USE_TRACKING_HISTORY_V2 The default mode is AR_USE_TRACKING_HISTORY_V2.

Return Value

0 if no error occured.

Discussion

(description)


arSetMatrixCodeType


Set the size and ECC algorithm to be used for matrix code (2D barcode) marker detection.

int arSetMatrixCodeType(
    ARHandle *handle,
    const AR_MATRIX_CODE_TYPE type);  
Parameters
handle

An ARHandle referring to the current AR tracker to have its mode set.

type

The type of matrix code (2D barcode) in use. Options include: AR_MATRIX_CODE_3x3 AR_MATRIX_CODE_3x3_HAMMING63 AR_MATRIX_CODE_3x3_PARITY65 AR_MATRIX_CODE_4x4 AR_MATRIX_CODE_4x4_BCH_13_9_3 AR_MATRIX_CODE_4x4_BCH_13_5_5 The default mode is AR_MATRIX_CODE_3x3.

Return Value

0 if no error occured.

Discussion

When matrix-code (2D barcode) marker detection is enabled (see arSetPatternDetectionMode) then the size of the barcode pattern and the type of error checking and correction (ECC) with which the markers were produced can be set via this function.

This setting is global to a given ARHandle; It is not possible to have two different matrix code types in use at once.

See Also


arSetPatternDetectionMode


Set the pattern detection mode

int arSetPatternDetectionMode(
    ARHandle *handle,
    int mode );  
Parameters
handle

An ARHandle referring to the current AR tracker to have its mode set.

mode

Options for this field are: AR_TEMPLATE_MATCHING_COLOR AR_TEMPLATE_MATCHING_MONO AR_MATRIX_CODE_DETECTION AR_TEMPLATE_MATCHING_COLOR_AND_MATRIX AR_TEMPLATE_MATCHING_MONO_AND_MATRIX The default mode is AR_TEMPLATE_MATCHING_COLOR.

Return Value

0 if no error occured.

Discussion

The pattern detection determines the method by which ARToolKit matches detected squares in the video image to marker templates and/or IDs. ARToolKit v4.x can match against pictorial "template" markers, whose pattern files are created with the mk_patt utility, in either colour or mono, and additionally can match against 2D-barcode-type "matrix" markers, which have an embedded marker ID. Two different two-pass modes are also available, in which a matrix-detection pass is made first, followed by a template-matching pass.


arSetPixelFormat


Set the expected pixel format for video frames being passed to arDetectMarker

int arSetPixelFormat(
    ARHandle *handle,
    AR_PIXEL_FORMAT pixFormat );  
Parameters
handle

Handle to settings structure in which to set the pixel format.

pixFormat

Value representing the format of pixels to be processed by the ARToolKit detection routines. See AR_PIXEL_FORMAT reference for more information.

Return Value

0 if no error occured.

Discussion

(description)


arUtilChangeToResourcesDirectory


Change to the resources directory using the specified behavior.

Parameters
behavior

See AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR type for allowed values.

path

Normally NULL, or when behavior is AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_SUPPLIED_PATH, the path to change to (absolute or relative to current working directory).

Return Value

-1 in the case of error, or 0 otherwise.

Discussion

ARToolKit uses relative paths to locate several types of resources, including camera parameter files, pattern files, multimarker files and others. This function provides the convenience of setting the current process working directory to the appropriate value for your application.


arUtilGetFileURI


Get a path as a file URI.

char *arUtilGetFileURI(
    const char *path);  
Parameters
path

Full or partial pathname.

On Windows, both partial pathnames, full pathnames including the drive letter, or UNC pathnames (beginning with "\\" are all OK.

Return Value

A string with the the file URI for that path, or NULL in the case of error. NB: The returned string must be freed by the caller (by calling free() once its use is complete).

Discussion

Given a full or partial pathname passed in string path, returns a string with the file URI for that path.

Partial pathnames are handled by concatening with the process's current working directory.


arUtilGetPixelFormatName


Get a string holding a descriptive name for a given pixel format enumeration.

const char *arUtilGetPixelFormatName(
    const AR_PIXEL_FORMAT arPixelFormat);  
Parameters
arPixelFormat

Enumerated pixel format number for which to retrieve a name.

Return Value

A constant c-string holding a descriptive name for the pixel format. The string returned matches the constants used in the definition of the type AR_PIXEL_FORMAT, e.g. "AR_PIXEL_FORMAT_RGB".

Discussion

On occasions it can be useful to display to the user the format of the pixels which ARToolKit is processing. This funtion converts a pixel-format number into a human-readable string description.


arUtilGetPixelSize


Get the size in bytes of a single pixel for a given pixel format.

int arUtilGetPixelSize(
    const AR_PIXEL_FORMAT arPixelFormat );  
Parameters
arPixelFormat

The pixel type whose size is to be measured.

Return Value

Number of bytes required to store 1 pixel of the given type.

Discussion

Different pixel formats have different sizes in bytes, and therefore different storage requirements per row of pixels. Use this function to calculate the number of bytes required to store a single pixel of the given type.


arUtilSleep


Relinquish CPU to the system for specified number of milliseconds.

void arUtilSleep(
    int msec );  
Parameters
msec

Sleep time in milliseconds (thousandths of a second).

Discussion

This function calls the native system-provided sleep routine to relinquish CPU control to the system for the specified time.


Typedefs

AR3DHandle

(description)

AR3DStereoHandle

(description)

AR_MARKER_INFO_CUTOFF_PHASE

Result codes returned by arDetectMarker to report state of individual detected trapezoidal regions.

AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR

Options for controlling the behavior of arUtilChangeToResourcesDirectory.

ARHandle

(description)

ARLabelInfo

(description)

ARMarkerInfo

(description)

ARMarkerInfo2

(description)

ARPattHandle

A structure which holds descriptions of trained patterns for template matching.

ARTrackingHistory

(description)


AR3DHandle


(description)

typedef struct { 
    ICPHandleT *icpHandle; 
} AR3DHandle;  
Fields
icpHandle

(description)

Discussion

(description)


AR3DStereoHandle


(description)

typedef struct { 
    ICPStereoHandleT *icpStereoHandle; 
} AR3DStereoHandle;  
Fields
icpStereoHandle

(description)

Discussion

(description)


AR_MARKER_INFO_CUTOFF_PHASE


Result codes returned by arDetectMarker to report state of individual detected trapezoidal regions.

Constants
AR_MARKER_INFO_CUTOFF_PHASE_NONE

Marker OK.

AR_MARKER_INFO_CUTOFF_PHASE_MATCH_GENERIC

Generic error during matching phase.

AR_MARKER_INFO_CUTOFF_PHASE_MATCH_CONTRAST

Insufficient contrast during matching.

AR_MARKER_INFO_CUTOFF_PHASE_MATCH_BARCODE_NOT_FOUND

Barcode matching could not find correct barcode locator pattern.

AR_MARKER_INFO_CUTOFF_PHASE_MATCH_BARCODE_EDC_FAIL

Barcode matching error detection/correction found unrecoverable error.

AR_MARKER_INFO_CUTOFF_PHASE_MATCH_CONFIDENCE

Matching confidence cutoff value not reached.

AR_MARKER_INFO_CUTOFF_PHASE_POSE_ERROR

Maximum allowable pose error exceeded.

AR_MARKER_INFO_CUTOFF_PHASE_POSE_ERROR_MULTI

Multi-marker pose error value exceeded.

Discussion

When detecting markers, all trapezoidal regions in the incoming image are considered for marker matching. Various heuristics are used to reject regions judged to be non-markers. The code will, as far as possible, report rejection by placing one of these constants into the ARMarkerInfo.cutoffPhase field of regions rejected during the arDetectMarker() call. Note that the ARMarkerInfo.id of such rejected regions will be -1.


AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR


Options for controlling the behavior of arUtilChangeToResourcesDirectory.

Constants
AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_BEST

Use a platform-dependent recommended-best option. Note the this behavior is subject to change in future versions of ARToolKit. At present, on Mac OS X and iOS, this will change to the Apple-provided resources directory inside the application bundle. At present, on other platforms, this will change to the same directory as the executable.

AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_CWD

Leave the working directory unchanged.

AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_SUPPLIED_PATH

Change to the working directory specified.

AR_UTIL_RESOURCES_DIRECTORY_BEHAVIOR_USE_EXECUTABLE_DIR

Change to the same directory as the executable.


ARHandle


(description)

typedef struct { 
    int arDebug; 
    AR_PIXEL_FORMAT arPixelFormat; 
    int arPixelSize; 
    int arLabelingMode; 
    int arLabelingThresh; 
    int arImageProcMode; 
    int arPatternDetectionMode; 
    int arMarkerExtractionMode; 
    ARParam arParam; 
    int marker_num; 
    ARMarkerInfo markerInfo[AR_SQUARE_MAX]; 
    int marker2_num; 
    ARMarkerInfo2 markerInfo2[AR_SQUARE_MAX]; 
    int history_num; 
    ARTrackingHistory history[AR_SQUARE_MAX]; 
    ARLabelInfo labelInfo; 
    ARPattHandle *pattHandle; 
    AR_LABELING_THRESH_MODE arLabelingThreshMode; 
    int arLabelingThreshAutoInterval; 
    int arLabelingThreshAutoIntervalTTL; 
    ARImageProcInfo *arImageProcInfo; 
    ARdouble borderSize; 
    AR_MATRIX_CODE_TYPE matrixCodeType; 
} ARHandle;  
Fields
arDebug

(description)

arPixelFormat

(description)

arPixelSize

(description)

arLabelingMode

(description)

arLabelingThresh

(description)

arImageProcMode

To query this value, call arGetImageProcMode(). To set this value, call arSetImageProcMode().

arPatternDetectionMode

(description)

arMarkerExtractionMode

(description)

arParam

(description)

marker_num

(description)

markerInfo

(description)

marker2_num

(description)

markerInfo2

(description)

history_num

(description)

history

(description)

labelInfo

(description)

pattHandle

(description)

borderSize

Percentage of the inner portion of a marker considered to be the border (and therefore not considered part of the pattern space). Default value is AR_BORDER_SIZE_DEFAULT. To query this value, call arGetBorderSize(). To set this value, call arSetBorderSize().

Discussion

(description)


ARLabelInfo


(description)

typedef struct { 
    ARInt16 *labelImage; 
    #if !AR_DISABLE_LABELING_DEBUG_MODE 
    ARUint8 *bwImage; 
    #endif  
    int label_num; 
    int area[AR_LABELING_WORK_SIZE]; 
    int clip[AR_LABELING_WORK_SIZE][4]; 
    ARdouble pos[AR_LABELING_WORK_SIZE][2]; 
    int work[AR_LABELING_WORK_SIZE]; 
    int work2[AR_LABELING_WORK_SIZE*7]; // area, pos[2], clip[4]. 
} ARLabelInfo;  
Fields
labelImage

(description)

bwImage

(description)

label_num

(description)

area

(description)

clip

(description)

pos

(description)

work

(description)

work2

(description)

Discussion

(description)


ARMarkerInfo


(description)

typedef struct { 
    int area; 
    int id; 
    int idPatt; 
    int idMatrix; 
    int dir; 
    int dirPatt; 
    int dirMatrix; 
    ARdouble cf; 
    ARdouble cfPatt; 
    ARdouble cfMatrix; 
    ARdouble pos[2]; 
    ARdouble line[4][3]; 
    ARdouble vertex[4][2]; 
    ARMarkerInfo2 *markerInfo2Ptr; 
    AR_MARKER_INFO_CUTOFF_PHASE cutoffPhase; 
    int errorCorrected; 
    uint64_t globalID; 
} ARMarkerInfo;  
Fields
area

(description)

id

(description)

idPatt

(description)

idMatrix

(description)

dir

(description)

dirPatt

(description)

dirMatrix

(description)

cf

(description)

cfPatt

(description)

cfMatrix

(description)

pos

(description)

line

(description)

vertex

(description)

markerInfo2Ptr

(description)

cutoffPhase

If a trapezoidal region is detected, but is eliminated from the candidates for tracking, this field is filled out with the tracking phase at which the marker was cut off. An English-language description of the phase can be obtained by indexing into the C-string array arMarkerInfoCutoffPhaseDescriptions[].

globalID

(description)

Discussion

(description)


ARMarkerInfo2


(description)

typedef struct { 
    int area; 
    ARdouble pos[2]; 
    int coord_num; 
    int x_coord[AR_CHAIN_MAX]; 
    int y_coord[AR_CHAIN_MAX]; 
    int vertex[5]; 
} ARMarkerInfo2;  
Fields
area

(description)

pos

(description)

coord_num

(description)

x_coord

(description)

y_coord

(description)

vertex

(description)

Discussion

(description)


ARPattHandle


A structure which holds descriptions of trained patterns for template matching.

typedef struct { 
    int patt_num; 
    int pattf[AR_PATT_NUM_MAX]; 
    int patt[AR_PATT_NUM_MAX][4][AR_PATT_SIZE1*AR_PATT_SIZE1*3]; 
    ARdouble pattpow[AR_PATT_NUM_MAX][4]; 
    int pattBW[AR_PATT_NUM_MAX][4][AR_PATT_SIZE1*AR_PATT_SIZE1]; 
    ARdouble pattpowBW[AR_PATT_NUM_MAX][4]; 
} ARPattHandle;  
Fields
patt_num

Number of valid patterns in the structure.

pattf

Flag: 0 = no pattern loaded at this position. 1 = pattern loaded and activated. 2 = pattern loaded but deactivated.

patt

Array of 4 different orientations of each pattern's colour values, in 1-byte per component BGR order.

pattpow

Root-mean-square of the pattern intensities.

pattBW

Array of 4 different orientations of each pattern's 1-byte luminosity values.

pattpowBW

Root-mean-square of the pattern intensities.

Discussion

Template (picture)-based pattern matching requires details of the pattern to be supplied to the matching functions. This structure holds such details. It is generally setup by loading pattern files from disk.


ARTrackingHistory


(description)

typedef struct { 
    ARMarkerInfo marker; 
    int count; 
} ARTrackingHistory;  
Fields
marker

(description)

count

(description)

Discussion

(description)