![]() |
ARX
1.0
The next-generation open source augmented reality toolkit.
|
Functions | |
ARHandle * | arCreateHandle (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... | |
ARMarkerInfo * | arGetMarker (ARHandle *handle) |
Get information on the markers detected in a video frame. More... | |
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.
paramLT | The 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(¶m, 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. |
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.
handle | The handle to delete, as created by arCreateHandle(); |
Get the border size.
N.B. Deprecated in favour of arGetPattRatio(), but retained for backwards compatibility.
handle | An ARHandle referring to the current AR tracker to be queried for its border size. |
int arGetCornerRefinementMode | ( | ARHandle * | handle | ) |
Find out whether square tracking subpixel corner refinement is enabled.
See arSetCornerRefinementMode() for more info.
handle | An ARHandle referring to the current AR tracker to be queried for its mode. |
int arGetDebugMode | ( | ARHandle * | handle | ) |
Find out whether artoolkitX's debug mode is enabled.
See arSetDebugMode() for more info.
handle | An ARHandle referring to the current AR tracker to be queried for its mode. |
int arGetImageProcMode | ( | ARHandle * | handle | ) |
Get the image processing mode.
See arSetImageProcMode() for a complete description.
handle | An ARHandle referring to the current AR tracker to be queried for its mode. |
int arGetLabelingMode | ( | ARHandle * | handle | ) |
Enquire whether detection is looking for black markers or white markers.
See discussion for arSetLabelingMode.
handle | An ARHandle referring to the current AR tracker to be queried for its labeling mode. |
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.
handle | An ARHandle referring to the current AR tracker to be queried for its labeling threshold value. |
int arGetLabelingThreshAutoAdaptiveBias | ( | ARHandle * | handle | ) |
int arGetLabelingThreshAutoAdaptiveKernelSize | ( | ARHandle * | handle | ) |
AR_LABELING_THRESH_MODE arGetLabelingThreshMode | ( | const ARHandle * | handle | ) |
Get the labeling threshold mode (auto/manual).
handle | An ARHandle referring to the current AR tracker to be queried for its labeling threshold value. |
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.
handle | An ARHandle referring to the current AR tracker to be queried for its labeling threshold auto interval value. |
ARMarkerInfo * arGetMarker | ( | ARHandle * | arHandle | ) |
Get information on the markers detected in a video frame.
arHandle | Handle upon which arDetectMarker has been called. |
int arGetMarkerExtractionMode | ( | ARHandle * | handle | ) |
Get the marker extraction mode.
(description)
handle | An ARHandle referring to the current AR tracker to be queried for its mode. |
int arGetMarkerNum | ( | ARHandle * | arHandle | ) |
Get the number of markers detected in a video frame.
arHandle | Handle upon which arDetectMarker has been called. |
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().
handle | An ARHandle referring to the current AR tracker to be queried for its mode. |
int arGetPatternDetectionMode | ( | ARHandle * | handle | ) |
Get the pattern detection mode.
See arSetPatternDetectionMode() for a complete description.
handle | An ARHandle referring to the current AR tracker to be queried for its mode. |
Get the width/height of the marker pattern space, as a proportion of marker width/height.
N.B. Supercedes arGetBorderSize().
handle | An ARHandle referring to the current AR tracker to be queried. |
int arGetPixelFormat | ( | ARHandle * | handle | ) |
Get the expected pixel format for video frames being passed to arDetectMarker.
See discussion for arSetPixelFormat().
handle | Handle to AR settings structure from which to retrieve the pixel format. |
Set the border size.
N.B. Deprecated in favour of arSetPattRatio(), but retained for backwards compatibility.
handle | An ARHandle referring to the current AR tracker to have its border size set. |
borderSize | The 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. |
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.
handle | Handle to settings structure in which to enable or disable subpixel corner refinement. |
mode | Options for this field are: AR_CORNER_REFINEMENT_DISABLE AR_CORNER_REFINEMENT_ENSABLE The default mode is AR_CORNER_REFINEMENT_DISABLE. |
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.
handle | An ARHandle referring to the current AR tracker in which debug mode is to be set. |
mode | Options for this field are: AR_DEBUG_DISABLE AR_DEBUG_ENABLE The default mode is AR_DEBUG_DISABLE. |
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.
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. |
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.
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. |
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.
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). |
void arSetLabelingThreshAutoAdaptiveBias | ( | ARHandle * | handle, |
const int | labelingThreshAutoAdaptiveBias | ||
) |
void arSetLabelingThreshAutoAdaptiveKernelSize | ( | ARHandle * | handle, |
const int | labelingThreshAutoAdaptiveKernelSize | ||
) |
void arSetLabelingThreshMode | ( | ARHandle * | handle, |
const AR_LABELING_THRESH_MODE | mode | ||
) |
Set the labeling threshold mode (auto/manual).
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, AR_LABELING_THRESH_MODE_AUTO_BRACKETING |
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.
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. |
void arSetMarkerExtractionMode | ( | ARHandle * | handle, |
int | mode | ||
) |
Set the marker extraction mode.
(description)
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. |
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.
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 AR_MATRIX_CODE_5x5_BCH_22_12_5 AR_MATRIX_CODE_5x5_BCH_22_7_7 The default mode is AR_MATRIX_CODE_3x3. |
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.
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. |
Set the width/height of the marker pattern space, as a proportion of marker width/height.
N.B. Supercedes arSetBorderSize().
handle | An ARHandle referring to the current AR tracker to be modified. |
pattRatio | The 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. |
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.
handle | Handle to settings structure in which to set the pixel format. |
pixFormat | Value representing the format of pixels to be processed by the artoolkitX detection routines. See AR_PIXEL_FORMAT reference for more information. |