ARX  1.0
The next-generation open source augmented reality toolkit.
Loading...
Searching...
No Matches
Functions
arCreateHandle.c File Reference
#include <ARX/AR/ar.h>
#include <stdio.h>
#include <math.h>
Include dependency graph for arCreateHandle.c:

Functions

ARHandlearCreateHandle (ARParamLT *paramLT)
 Create a handle to hold settings for an artoolkitX tracker instance. More...
 
int arDeleteHandle (ARHandle *handle)
 Delete a handle which holds settings for an artoolkitX tracker instance. More...
 
void arSetDebugMode (ARHandle *handle, int mode)
 Enable or disable artoolkitX's debug mode. More...
 
int arGetDebugMode (ARHandle *handle)
 Find out whether artoolkitX's debug mode is enabled. More...
 
void arSetLabelingMode (ARHandle *handle, int mode)
 Select between detection of black markers and white markers. More...
 
int arGetLabelingMode (ARHandle *handle)
 Enquire whether detection is looking for black markers or white markers. More...
 
void arSetLabelingThresh (ARHandle *handle, int thresh)
 Set the labeling threshhold. More...
 
int arGetLabelingThresh (ARHandle *handle)
 Get the current labeling threshold. More...
 
void arSetLabelingThreshMode (ARHandle *handle, const AR_LABELING_THRESH_MODE mode)
 Set the labeling threshold mode (auto/manual). More...
 
AR_LABELING_THRESH_MODE arGetLabelingThreshMode (const ARHandle *handle)
 Get the labeling threshold mode (auto/manual). More...
 
void arSetLabelingThreshModeAutoInterval (ARHandle *handle, const int interval)
 Set the number of frames between auto-threshold calculations. More...
 
void arSetLabelingThreshAutoAdaptiveKernelSize (ARHandle *handle, const int labelingThreshAutoAdaptiveKernelSize)
 
int arGetLabelingThreshAutoAdaptiveKernelSize (ARHandle *handle)
 
void arSetLabelingThreshAutoAdaptiveBias (ARHandle *handle, const int labelingThreshAutoAdaptiveBias)
 
int arGetLabelingThreshAutoAdaptiveBias (ARHandle *handle)
 
int arGetLabelingThreshModeAutoInterval (const ARHandle *handle)
 Get the number of frames between auto-threshold calculations. More...
 
void arSetImageProcMode (ARHandle *handle, int mode)
 Set the image processing mode. More...
 
int arGetImageProcMode (ARHandle *handle)
 Get the image processing mode. More...
 
void arSetPatternDetectionMode (ARHandle *handle, int mode)
 Set the pattern detection mode. More...
 
void arSetMatrixCodeType (ARHandle *handle, const AR_MATRIX_CODE_TYPE type)
 Set the size and ECC algorithm to be used for matrix code (2D barcode) marker detection. More...
 
AR_MATRIX_CODE_TYPE arGetMatrixCodeType (ARHandle *handle)
 Get the size and ECC algorithm being used for matrix code (2D barcode) marker detection. More...
 
int arGetPatternDetectionMode (ARHandle *handle)
 Get the pattern detection mode. More...
 
void arSetMarkerExtractionMode (ARHandle *handle, int mode)
 Set the marker extraction mode. More...
 
int arGetMarkerExtractionMode (ARHandle *handle)
 Get the marker extraction mode. More...
 
void arSetBorderSize (ARHandle *handle, const ARdouble borderSize)
 Set the border size. More...
 
ARdouble arGetBorderSize (ARHandle *handle)
 Get the border size. More...
 
void arSetPattRatio (ARHandle *handle, const ARdouble pattRatio)
 Set the width/height of the marker pattern space, as a proportion of marker width/height. More...
 
ARdouble arGetPattRatio (ARHandle *handle)
 Get the width/height of the marker pattern space, as a proportion of marker width/height. More...
 
void arSetPixelFormat (ARHandle *handle, AR_PIXEL_FORMAT pixFormat)
 Set the expected pixel format for video frames being passed to arDetectMarker. More...
 
int arGetPixelFormat (ARHandle *handle)
 Get the expected pixel format for video frames being passed to arDetectMarker. More...
 
void arSetCornerRefinementMode (ARHandle *handle, int mode)
 Enable or disable square tracking subpixel corner refinement. More...
 
void arSetAreaMax (ARHandle *handle, const ARdouble areaMax)
 
ARdouble arGetAreaMax (ARHandle *handle)
 
void arSetAreaMin (ARHandle *handle, const ARdouble areaMin)
 
ARdouble arGetAreaMin (ARHandle *handle)
 
void arSetSquareFitThresh (ARHandle *handle, const ARdouble squareFitThresh)
 
ARdouble arGetSquareFitThresh (ARHandle *handle)
 
int arGetCornerRefinementMode (ARHandle *handle)
 Find out whether square tracking subpixel corner refinement is enabled. More...
 
int arGetMarkerNum (ARHandle *handle)
 Get the number of markers detected in a video frame. More...
 
ARMarkerInfoarGetMarker (ARHandle *handle)
 Get information on the markers detected in a video frame. More...
 

Function Documentation

◆ arCreateHandle()

ARHandle * arCreateHandle ( ARParamLT paramLT)

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

@functiongroup "Square detection".

ARHandle is the primary structure holding the settings for a single artoolkitX square marker tracking instance. Settings include expected video stream image size and pixel format, tracking modes, loaded markers and more.

Expected video stream image size is taken directly from the supplied ARParamLT structure's xsize and ysize fields. Video stream image pixel format must be set by a subsequent call to arSetPixelFormat() to set the correct format.

After creation of the ARHandle, tracking settings should be set via appropriate calls to other arSet*() functions.

The ARHandle should be disposed of via a call to arDeleteHandle when tracking with this instance is complete.

Parameters
paramLTThe created handle will hold a pointer to the calibrated camera parameters specified by this parameter. This parameter uses the new lookup-table based form of the camera parameters introduced in ARToolKit v5. An ARParamLT structure may be created from an ARParam structure via the call: ARParamLT *paramLT = arParamLTCreate(&param, AR_PARAM_LT_DEFAULT_OFFSET); Note that the pointer is only copied, and so the ARParamLT structure must remain valid until the ARHandle is disposed of by calling arDeleteHandle.
Returns
An ARHandle which should be passed to other functions which deal with the operations of the artoolkitX tracker.
See also
arSetPixelFormat
arDeleteHandle
Here is the call graph for this function:

◆ arDeleteHandle()

int arDeleteHandle ( ARHandle handle)

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

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

Parameters
handleThe handle to delete, as created by arCreateHandle();
Returns
0 if no error occured.
See also
arCreateHandle
Here is the call graph for this function:

◆ arGetAreaMax()

ARdouble arGetAreaMax ( ARHandle handle)

◆ arGetAreaMin()

ARdouble arGetAreaMin ( ARHandle handle)

◆ arGetBorderSize()

ARdouble arGetBorderSize ( ARHandle handle)

Get the border size.

N.B. Deprecated in favour of arGetPattRatio(), but retained for backwards compatibility.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its border size.
Returns
Value representing the border size. The default border size for newly-created ARHandle structures is AR_BORDER_SIZE_DEFAULT.
See also
arSetBorderSize

◆ arGetCornerRefinementMode()

int arGetCornerRefinementMode ( ARHandle handle)

Find out whether square tracking subpixel corner refinement is enabled.

See arSetCornerRefinementMode() for more info.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its mode.
Returns
Value representing the mode.
See also
arSetCornerRefinementMode

◆ arGetDebugMode()

int arGetDebugMode ( ARHandle handle)

Find out whether artoolkitX's debug mode is enabled.

See arSetDebugMode() for more info.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its mode.
Returns
Value representing the mode.
See also
arSetDebugMode

◆ arGetImageProcMode()

int arGetImageProcMode ( ARHandle handle)

Get the image processing mode.

See arSetImageProcMode() for a complete description.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its mode.
Returns
Value representing the current image processing mode.
See also
arSetImageProcMode

◆ arGetLabelingMode()

int arGetLabelingMode ( ARHandle handle)

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

See discussion for arSetLabelingMode.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its labeling mode.
Returns
Value representing the mode.
See also
arSetLabelingMode

◆ arGetLabelingThresh()

int arGetLabelingThresh ( ARHandle handle)

Get the current labeling threshold.

This function queries the current labeling threshold. For, AR_LABELING_THRESH_MODE_AUTO_MEDIAN, AR_LABELING_THRESH_MODE_AUTO_OTSU, and AR_LABELING_THRESH_MODE_AUTO_BRACKETING 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.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its labeling threshold value.
Returns
Value of the labeling threshhold. An integer in the range [0,255] (inclusive)
See also
arSetLabelingThresh

◆ arGetLabelingThreshAutoAdaptiveBias()

int arGetLabelingThreshAutoAdaptiveBias ( ARHandle handle)

◆ arGetLabelingThreshAutoAdaptiveKernelSize()

int arGetLabelingThreshAutoAdaptiveKernelSize ( ARHandle handle)

◆ arGetLabelingThreshMode()

AR_LABELING_THRESH_MODE arGetLabelingThreshMode ( const ARHandle handle)

Get the labeling threshold mode (auto/manual).

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its labeling threshold value.
Returns
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, AR_LABELING_THRESH_MODE_AUTO_BRACKETING
See also
arSetLabelingThresh
arSetLabelingThreshMode

◆ arGetLabelingThreshModeAutoInterval()

int arGetLabelingThreshModeAutoInterval ( const ARHandle handle)

Get the number of frames between auto-threshold calculations.

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

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its labeling threshold auto interval value.
Returns
Value of the labeling threshhold auto interval. An integer in the range [0,INT_MAX] (inclusive)
See also
arSetLabelingThreshModeAutoInterval

◆ arGetMarker()

ARMarkerInfo * arGetMarker ( ARHandle arHandle)

Get information on the markers detected in a video frame.

Returns
An array (of length arGetMarkerNum(arHandle)) of ARMarkerInfo structs. A better name for this function would be arGetDetectedMarkerInfo, but the current name lives on for historical reasons.
Parameters
arHandleHandle upon which arDetectMarker has been called.
See also
arGetMarkerNum
ARMarkerInfo
arDetectMarker

◆ arGetMarkerExtractionMode()

int arGetMarkerExtractionMode ( ARHandle handle)

Get the marker extraction mode.

(description)

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its mode.
Returns
The value representing the mode.
See also
arSetMarkerExtractionMode

◆ arGetMarkerNum()

int arGetMarkerNum ( ARHandle arHandle)

Get the number of markers detected in a video frame.

Returns
The number of detected markers in the most recent image passed to arDetectMarker. Note that this is actually a count, not an index. A better name for this function would be arGetDetectedMarkerCount, but the current name lives on for historical reasons.
Parameters
arHandleHandle upon which arDetectMarker has been called.
See also
arGetMarker
ARMarkerInfo
arDetectMarker

◆ arGetMatrixCodeType()

AR_MATRIX_CODE_TYPE arGetMatrixCodeType ( ARHandle handle)

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

See the description for arSetMatrixCodeType().

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its mode.
Returns
The value representing the mode.
See also
arGetPatternDetectionMode
arSetMatrixCodeType

◆ arGetPatternDetectionMode()

int arGetPatternDetectionMode ( ARHandle handle)

Get the pattern detection mode.

See arSetPatternDetectionMode() for a complete description.

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its mode.
Returns
Value representing the mode.
See also
arGetPatternDetectionMode

◆ arGetPattRatio()

ARdouble arGetPattRatio ( ARHandle handle)

Get the width/height of the marker pattern space, as a proportion of marker width/height.

N.B. Supercedes arGetBorderSize().

Parameters
handleAn ARHandle referring to the current AR tracker to be queried.
Returns
Value representing the width/height of the marker pattern space, as a proportion of marker width/height. The default border size for newly-created ARHandle structures is AR_PATT_RATIO.
See also
arSetPattRatio

◆ arGetPixelFormat()

int arGetPixelFormat ( ARHandle handle)

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

See discussion for arSetPixelFormat().

Parameters
handleHandle to AR settings structure from which to retrieve the pixel format.
Returns
Value representing the format of pixels being processed by the artoolkitX detection routines. See AR_PIXEL_FORMAT reference for more information.
See also
arSetPixelFormat
arCreateHandle
arDetectMarker

◆ arGetSquareFitThresh()

ARdouble arGetSquareFitThresh ( ARHandle handle)

◆ arSetAreaMax()

void arSetAreaMax ( ARHandle handle,
const ARdouble  areaMax 
)

◆ arSetAreaMin()

void arSetAreaMin ( ARHandle handle,
const ARdouble  areaMin 
)

◆ arSetBorderSize()

void arSetBorderSize ( ARHandle handle,
const ARdouble  borderSize 
)

Set the border size.

N.B. Deprecated in favour of arSetPattRatio(), but retained for backwards compatibility.

Parameters
handleAn ARHandle referring to the current AR tracker to have its border size set.
borderSizeThe border size. To set the default, pass (1.0 - 2*AR_PATT_RATIO). If compatibility with ARToolKit verions 1.0 through 4.4 is required, this value must be 0.25.
See also
arGetBorderSize

◆ arSetCornerRefinementMode()

void arSetCornerRefinementMode ( ARHandle handle,
int  mode 
)

Enable or disable square tracking subpixel corner refinement.

If compiled with OpenCV available, the square tracker allows marker corner locations to be subpixel-refined.

Parameters
handleHandle to settings structure in which to enable or disable subpixel corner refinement.
modeOptions for this field are: AR_CORNER_REFINEMENT_DISABLE AR_CORNER_REFINEMENT_ENSABLE The default mode is AR_CORNER_REFINEMENT_DISABLE.
See also
arGetCornerRefinementMode

◆ arSetDebugMode()

void arSetDebugMode ( ARHandle handle,
int  mode 
)

Enable or disable artoolkitX's debug mode.

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

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

Parameters
handleAn ARHandle referring to the current AR tracker in which debug mode is to be set.
modeOptions for this field are: AR_DEBUG_DISABLE AR_DEBUG_ENABLE The default mode is AR_DEBUG_DISABLE.
See also
arGetDebugMode

◆ arSetImageProcMode()

void arSetImageProcMode ( ARHandle handle,
int  mode 
)

Set the image processing mode.

When ARthe image processing mode is AR_IMAGE_PROC_FRAME_IMAGE, artoolkitX processes all pixels in each incoming image to locate markers. When the mode is AR_IMAGE_PROC_FIELD_IMAGE, artoolkitX 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.

Parameters
handleAn ARHandle referring to the current AR tracker to have its mode set.
modeOptions for this field are: AR_IMAGE_PROC_FRAME_IMAGE AR_IMAGE_PROC_FIELD_IMAGE The default mode is AR_IMAGE_PROC_FRAME_IMAGE.
See also
arGetImageProcMode

◆ arSetLabelingMode()

void arSetLabelingMode ( ARHandle handle,
int  mode 
)

Select between detection of black markers and white markers.

artoolkitX'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.

Parameters
handleAn ARHandle referring to the current AR tracker to have its labeling mode set.
modeOptions for this field are: AR_LABELING_WHITE_REGION AR_LABELING_BLACK_REGION The default mode is AR_LABELING_BLACK_REGION.
See also
arGetLabelingMode

◆ arSetLabelingThresh()

void arSetLabelingThresh ( ARHandle handle,
int  thresh 
)

Set the labeling threshhold.

This function forces sets the threshold value. The default value is AR_DEFAULT_LABELING_THRESH which is 100, unless edited in arConfig.h.

The current threshold mode is not affected by this call. Typically, this function is used when labeling threshold mode is AR_LABELING_THRESH_MODE_MANUAL.

The threshold value is not relevant if threshold mode is AR_LABELING_THRESH_MODE_AUTO_ADAPTIVE.

Background: The labeling threshold is the value which the AR library uses to differentiate between black and white portions of an artoolkitX 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.

Parameters
handleAn ARHandle referring to the current AR tracker to have its labeling threshold value set.
threshAn integer in the range [0,255] (inclusive).
See also
arGetLabelingThresh

◆ arSetLabelingThreshAutoAdaptiveBias()

void arSetLabelingThreshAutoAdaptiveBias ( ARHandle handle,
const int  labelingThreshAutoAdaptiveBias 
)

◆ arSetLabelingThreshAutoAdaptiveKernelSize()

void arSetLabelingThreshAutoAdaptiveKernelSize ( ARHandle handle,
const int  labelingThreshAutoAdaptiveKernelSize 
)

◆ arSetLabelingThreshMode()

void arSetLabelingThreshMode ( ARHandle handle,
const AR_LABELING_THRESH_MODE  mode 
)

Set the labeling threshold mode (auto/manual).

Parameters
handleAn ARHandle referring to the current AR tracker to be queried for its labeling threshold mode.
modeAn 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, AR_LABELING_THRESH_MODE_AUTO_BRACKETING
Returns
0 if no error occured.
See also
arSetLabelingThresh
arGetLabelingThreshMode
Here is the call graph for this function:

◆ arSetLabelingThreshModeAutoInterval()

void arSetLabelingThreshModeAutoInterval ( ARHandle handle,
const int  interval 
)

Set the number of frames between auto-threshold calculations.

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

Parameters
handleAn ARHandle referring to the current AR tracker for which the labeling threshold auto interval will be set.
intervalThe 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.
See also
arGetLabelingThreshModeAutoInterval

◆ arSetMarkerExtractionMode()

void arSetMarkerExtractionMode ( ARHandle handle,
int  mode 
)

Set the marker extraction mode.

(description)

Parameters
handleAn ARHandle referring to the current AR tracker to have its mode set.
modeOptions 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.
See also
arGetMarkerExtractionMode

◆ arSetMatrixCodeType()

void arSetMatrixCodeType ( ARHandle handle,
const AR_MATRIX_CODE_TYPE  type 
)

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

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.

Parameters
handleAn ARHandle referring to the current AR tracker to have its mode set.
typeThe 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 AR_MATRIX_CODE_5x5_BCH_22_12_5 AR_MATRIX_CODE_5x5_BCH_22_7_7 The default mode is AR_MATRIX_CODE_3x3.
See also
arSetPatternDetectionMode
arGetMatrixCodeType

◆ arSetPatternDetectionMode()

void arSetPatternDetectionMode ( ARHandle handle,
int  mode 
)

Set the pattern detection mode.

The pattern detection determines the method by which artoolkitX 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.

Parameters
handleAn ARHandle referring to the current AR tracker to have its mode set.
modeOptions 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.
See also
arGetPatternDetectionMode

◆ arSetPattRatio()

void arSetPattRatio ( ARHandle handle,
const ARdouble  pattRatio 
)

Set the width/height of the marker pattern space, as a proportion of marker width/height.

N.B. Supercedes arSetBorderSize().

Parameters
handleAn ARHandle referring to the current AR tracker to be modified.
pattRatioThe the width/height of the marker pattern space, as a proportion of marker width/height. To set the default, pass AR_PATT_RATIO. If compatibility with ARToolKit verions 1.0 through 4.4 is required, this value must be 0.5.
See also
arGetPattRatio

◆ arSetPixelFormat()

void arSetPixelFormat ( ARHandle handle,
AR_PIXEL_FORMAT  pixFormat 
)

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

This function must be used at least once after creation of an ARHandle, to set the pixel format with which images will be passed to arDetectMarker(). If the pixel format of incoming video images changes, this function must be called again to update the value.

Parameters
handleHandle to settings structure in which to set the pixel format.
pixFormatValue representing the format of pixels to be processed by the artoolkitX detection routines. See AR_PIXEL_FORMAT reference for more information.
See also
arGetPixelFormat
arCreateHandle
arDetectMarker
Here is the call graph for this function:

◆ arSetSquareFitThresh()

void arSetSquareFitThresh ( ARHandle handle,
const ARdouble  squareFitThresh 
)