ARWrapper Provides a C++ wrapper around ARToolKit and exposes a C and JNI API

- Main Page
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Files Functions Variables Typedefs Enumerations Enumerator
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
ARController Class Reference

Wrapper for ARToolKit functionality. More...

`#include <ARController.h>`

## Public Member Functions
| ARController ()
| Constructor. More...
| ~ARController ()
| Destructor. More...
const char * | getARToolKitVersion ()
| Returns a string containing the ARToolKit version, such as "4.5.1". More...
int | getError ()
bool | initialiseBase (const int patternSize=AR_PATT_SIZE1, const int patternCountMax=AR_PATT_NUM_MAX)
| Start marker management so markers can be added and removed. More...
bool | canAddMarker ()
| Report whether a marker can be added. More...
void | setProjectionNearPlane (const ARdouble projectionNearPlane)
void | setProjectionFarPlane (const ARdouble projectionFarPlane)
ARdouble | projectionNearPlane (void)
ARdouble | projectionFarPlane (void)
bool | startRunning (const char *vconf, const char *cparaName, const char *cparaBuff, const long cparaBuffLen)
| Start video capture and marker detection. More...
bool | startRunningStereo (const char *vconfL, const char *cparaNameL, const char *cparaBuffL, const long cparaBuffLenL, const char *vconfR, const char *cparaNameR, const char *cparaBuffR, const long cparaBuffLenR, const char *transL2RName, const char *transL2RBuff, const long transL2RBuffLen)
| Start stereo video capture and marker detection. More...
bool | videoAcceptImage (JNIEnv *env, jobject obj, const int videoSourceIndex, jbyteArray pinArray, jint width, jint height, jint cameraIndex, jboolean cameraIsFrontFacing)
bool | videoParameters (const int videoSourceIndex, int *width, int *height, AR_PIXEL_FORMAT *pixelFormat)
| Reports width, height and pixel format of a video source. More...
bool | isRunning ()
| Returns true if video capture and marker detection is running. More...
bool | stopRunning ()
| Video capture and marker detection stops, but markers are still valid and can be configured. More...
bool | shutdown ()
| Stop, if running. More...
bool | getProjectionMatrix (const int videoSourceIndex, ARdouble proj[16])
| Populates the provided array with the ARToolKit projection matrix. More...
int | addMarker (const char *cfg)
| Adds a marker as specified in the given configuration string. More...
bool | removeMarker (int UID)
| Removes the marker with the given ID. More...
int | removeAllMarkers ()
| Clears the collection of markers. More...
unsigned int | countMarkers ()
| Returns the number of currently loaded markers. More...
ARMarker * | findMarker (int UID)
| Searches the collection of markers for the given ID. More...
bool | capture ()
bool | updateTexture (const int videoSourceIndex, Color *buffer)
| Asks the video source to push the most recent frame into the passed-in buffer. More...
bool | updateTexture32 (const int videoSourceIndex, uint32_t *buffer)
| Asks the video source to push the most recent frame into the passed-in buffer. More...
bool | updateTextureGL (const int videoSourceIndex, const int textureID)
| Asks the video source to push the most recent frame into the OpenGL texture with the passed-in ID/name. More...
bool | update ()
| Performs marker detection and updates all markers. More...
void | setDebugMode (bool debug)
| Enables or disables debug mode in the tracker. More...
bool | getDebugMode () const
| Returns whether debug mode is currently enabled. More...
void | setImageProcMode (int mode)
int | getImageProcMode () const
void | setThreshold (int thresh)
| Sets the threshold value used for image binarization. More...
int | getThreshold () const
| Returns the current threshold value used for image binarization. More...
void | setThresholdMode (int mode)
| Sets the thresholding mode to use. More...
int | getThresholdMode () const
| Returns the current thresholding mode. More...
void | setLabelingMode (int mode)
| Sets the labeling mode to use. More...
int | getLabelingMode () const
| Returns the current labeling mode. More...
void | setPatternDetectionMode (int mode)
int | getPatternDetectionMode () const
void | setPattRatio (float ratio)
float | getPattRatio () const
void | setMatrixCodeType (int type)
int | getMatrixCodeType () const
void | setNFTMultiMode (bool on)
bool | getNFTMultiMode () const
bool | updateDebugTexture (const int videoSourceIndex, Color *buffer)
| Populates the provided color buffer with the current contents of the debug image. More...
bool | updateDebugTexture32 (const int videoSourceIndex, uint32_t *buffer)
| Populates the provided buffer with the current contents of the debug image. More...
bool | getPatternImage (int patternID, Color *buffer)
| Populates the provided color buffer with the image for the specified pattern. More...
bool | loadOpticalParams (const char *optical_param_name, const char *optical_param_buff, const long optical_param_buffLen, ARdouble *fovy_p, ARdouble *aspect_p, ARdouble m[16], ARdouble p[16])
| Loads an optical parameters structure from file or from buffer. More...

## Static Public Member Functions
static void | logv (const int logLevel, const char *format,...)
static void | logv (const char *msg,...)
| If a log callback has been set, then this passes the formatted message to it. More...

## Static Public Attributes
static PFN_LOGCALLBACK | logCallback = NULL
| Callback where log messages are passed to. More...

## Detailed Description

Wrapper for ARToolKit functionality.

This class handles ARToolKit initialisation, updates, and cleanup. It maintains a collection of markers, providing methods to add and remove them.

## Constructor & Destructor Documentation

ARController::ARController | ( |  | ) |

Constructor.

ARController::~ARController | ( |  | ) |

Destructor.

## Member Function Documentation

int ARController::addMarker | ( | const char * | cfg | ) |

Adds a marker as specified in the given configuration string.

The format of the string can be one of:

- Single marker: "single;pattern_file;pattern_width", e.g. "single;data/patt.hiro;80"
- Multi marker: "multi;config_file", e.g. "multi;data/multi/marker.dat"
- NFT marker: "nft;nft_dataset_pathname", e.g. "nft;gibraltar"

Parameters

  cfg | The configuration string

Returns
  The UID of the marker instantiated based on the configuration string, or -1 if an error occurred.

bool ARController::canAddMarker | ( |  | ) |

Report whether a marker can be added.

Markers can be added once basic initialisation has occurred.

Returns
  true if adding a marker is currently possible

bool ARController::capture | ( |  | ) |

unsigned int ARController::countMarkers | ( |  | ) |

Returns the number of currently loaded markers.

Returns
  The number of currently loaded markers.

ARMarker * ARController::findMarker | ( | int | UID | ) |

Searches the collection of markers for the given ID.

Parameters

  UID | The UID of the marker to find

Returns
  The found marker, or NULL if no matching ID was found.

const char * ARController::getARToolKitVersion | ( |  | ) |

Returns a string containing the ARToolKit version, such as "4.5.1".

Returns
  The ARToolKit version

bool ARController::getDebugMode | ( |  | ) | const

Returns whether debug mode is currently enabled.

Returns
  true when debug mode is enabled, false when debug mode is disabled

See Also
  setDebugMode()

int ARController::getError | ( |  | ) |

int ARController::getImageProcMode | ( |  | ) | const

int ARController::getLabelingMode | ( |  | ) | const

Returns the current labeling mode.

Returns
  The current labeling mode.

See Also
  setLabelingMode()

int ARController::getMatrixCodeType | ( |  | ) | const

bool ARController::getNFTMultiMode | ( |  | ) | const

int ARController::getPatternDetectionMode | ( |  | ) | const

bool ARController::getPatternImage | ( | int | patternID,
|  | Color * | buffer
| ) |  |

Populates the provided color buffer with the image for the specified pattern.

Parameters

  patternID | The ARToolKit pattern ID to use
  buffer | The color buffer to populate

Returns
  true if successful, false if an error occurred

float ARController::getPattRatio | ( |  | ) | const

bool ARController::getProjectionMatrix | ( | const int | videoSourceIndex,
|  | ARdouble | proj[16]
| ) |  |

Populates the provided array with the ARToolKit projection matrix.

The projection matrix is computed once the video source has been opened, and camera parameters become available. If this method is called before this happens, then the passed array is untouched and the method will return false.

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  proj | Array to populate with OpenGL compatible projection matrix

Returns
  true if the projection matrix has been computed, otherwise false

int ARController::getThreshold | ( |  | ) | const

Returns the current threshold value used for image binarization.

Returns
  The current threshold value

See Also
  setThreshold()

int ARController::getThresholdMode | ( |  | ) | const

Returns the current thresholding mode.

Returns
  The current thresholding mode.

See Also
  setThresholdMode()

bool ARController::initialiseBase | ( | const int | patternSize = `AR_PATT_SIZE1`,
|  | const int | patternCountMax = `AR_PATT_NUM_MAX`
| ) |  |

Start marker management so markers can be added and removed.

Parameters

  patternSize | For any square template (pattern) markers, the number of rows and columns in the template.
  patternCountMax | For any square template (pattern) markers, the maximum number of markers that may be loaded for a single matching pass. Must be > 0.

Returns
  true if initialisation was OK, false if an error occured.

bool ARController::isRunning | ( |  | ) |

Returns true if video capture and marker detection is running.

Returns
  true if the video source(s) is/are open and returning frames, otherwise false.

bool ARController::loadOpticalParams | ( | const char * | optical_param_name,
|  | const char * | optical_param_buff,
|  | const long | optical_param_buffLen,
|  | ARdouble * | fovy_p,
|  | ARdouble * | aspect_p,
|  | ARdouble | m[16],
|  | ARdouble | p[16]
| ) |  |

Loads an optical parameters structure from file or from buffer.

Parameters

  optical_param_name | If supplied, points to a buffer specifying the path to the optical parameters file (as generated by the calib_optical utility.)
  optical_param_buff | If optical_param_name is NULL, the contents of this buffer will be interpreted as containing the contents of an optical parameters file.
  optical_param_buffLen | Length of the buffer specified in optical_param_buff. Ignored if optical_param_buff is NULL.
  fovy_p | Pointer to an ARdouble, which will be filled with the field-of-view (Y axis) component of the optical parameters.
  aspect_p | Pointer to an ARdouble, which will be filled with the aspect ratio (width / height) component of the optical parameters.
  m | Pointer to an array of 16 ARdoubles, which will be filled with the transformation matrix component of the optical parameters. Note that the position vector (m[12], m[13], m[14]) will be scaled by the viewScale value supplued in startRunning().
  p | (Optional) May be NULL, or a pointer to an array of 16 ARdoubles, which will be filled with the perspective matrix calculated from fovy and aspect combined with the near and far projection values supplied in startRunning().

void ARController::logv | ( | const int | logLevel,
|  | const char * | format,
|  |  | ...
| ) |  |
| static

void ARController::logv | ( | const char * | msg,
|  |  | ...
| ) |  |
| static

If a log callback has been set, then this passes the formatted message to it.

If no log callback has been set, then the message is discarded.

Parameters

  msg | The message to output. Follows the same formatting rules as printf().

ARdouble ARController::projectionFarPlane | ( | void |  | ) |

ARdouble ARController::projectionNearPlane | ( | void |  | ) |

int ARController::removeAllMarkers | ( |  | ) |

Clears the collection of markers.

Returns
  The number of markers removed

bool ARController::removeMarker | ( | int | UID | ) |

Removes the marker with the given ID.

Parameters

  UID | The UID of the marker to remove

Returns
  true if the marker was removed, false if an error occurred.

void ARController::setDebugMode | ( | bool | debug | ) |

Enables or disables debug mode in the tracker.

When enabled, a black and white debug image is generated during marker detection. The debug image is useful for visualising the binarization process and choosing a threshold value.

Parameters

  debug | true to enable debug mode, false to disable debug mode

See Also
  getDebugMode()

void ARController::setImageProcMode | ( | int | mode | ) |

void ARController::setLabelingMode | ( | int | mode | ) |

Sets the labeling mode to use.

Parameters

  mode | The new labeling mode to use.

See Also
  getLabelingMode()

void ARController::setMatrixCodeType | ( | int | type | ) |

void ARController::setNFTMultiMode | ( | bool | on | ) |

void ARController::setPatternDetectionMode | ( | int | mode | ) |

void ARController::setPattRatio | ( | float | ratio | ) |

void ARController::setProjectionFarPlane | ( | const ARdouble | projectionFarPlane | ) |

void ARController::setProjectionNearPlane | ( | const ARdouble | projectionNearPlane | ) |

void ARController::setThreshold | ( | int | thresh | ) |

Sets the threshold value used for image binarization.

Parameters

  thresh | The new threshold value to use

See Also
  getThreshold()

void ARController::setThresholdMode | ( | int | mode | ) |

Sets the thresholding mode to use.

Parameters

  mode | The new thresholding mode to use.

See Also
  getThresholdMode()

bool ARController::shutdown | ( |  | ) |

Stop, if running.

Remove all markers, clean up all memory. Starting again from this state requires initialiseBase() to be called again.

Returns
  true if shutdown was successful, otherwise false

bool ARController::startRunning | ( | const char * | vconf,
|  | const char * | cparaName,
|  | const char * | cparaBuff,
|  | const long | cparaBuffLen
| ) |  |

Start video capture and marker detection.

(AR/NFT initialisation will begin on a subsequent call to update().)

Parameters

  vconf | Video configuration string.
  cparaName | Camera parameters filename, or NULL if camera parameters file not being used.
  cparaBuff | A byte-buffer containing contents of a camera parameters file, or NULL if a camera parameters file is being used.
  cparaBuffLen | Length (in bytes) of cparaBuffLen, or 0 if a camera parameters file is being used.

Returns
  true if video capture and marker detection was started, otherwise false.

bool ARController::startRunningStereo | ( | const char * | vconfL,
|  | const char * | cparaNameL,
|  | const char * | cparaBuffL,
|  | const long | cparaBuffLenL,
|  | const char * | vconfR,
|  | const char * | cparaNameR,
|  | const char * | cparaBuffR,
|  | const long | cparaBuffLenR,
|  | const char * | transL2RName,
|  | const char * | transL2RBuff,
|  | const long | transL2RBuffLen
| ) |  |

Start stereo video capture and marker detection.

(AR/NFT initialisation will begin on a subsequent call to update().)

Parameters

  vconfL | Video configuration string for the "left" video source.
  cparaNameL | Camera parameters filename for the "left" video source, or NULL if camera parameters file not being used.
  cparaBuffL | A byte-buffer containing contents of a camera parameters file for the "left" video source, or NULL if a camera parameters file is being used.
  cparaBuffLenL | Length (in bytes) of cparaBuffLenL, or 0 if a camera parameters file is being used.
  vconfR | Video configuration string for the "right" video source.
  cparaNameR | Camera parameters filename for the "right" video source, or NULL if camera parameters file not being used.
  cparaBuffR | A byte-buffer containing contents of a camera parameters file for the "right" video source, or NULL if a camera parameters file is being used.
  cparaBuffLenR | Length (in bytes) of cparaBuffLenR, or 0 if a camera parameters file is being used.
  transL2RName | Stereo calibration filename, or NULL if stereo calibration file not being used.
  transL2RBuff | A byte-buffer containing contents of a stereo calibration file, or NULL if a stereo calibration file is being used.
  transL2RBuffLen | Length (in bytes) of transL2RBuff, or 0 if a stereo calibration file is being used.

Returns
  true if video capture and marker detection was started, otherwise false.

bool ARController::stopRunning | ( |  | ) |

Video capture and marker detection stops, but markers are still valid and can be configured.

Returns
  true if video capture and marker detection was stopped, otherwise false.

bool ARController::update | ( |  | ) |

Performs marker detection and updates all markers.

The latest frame from the current video source is retrieved and analysed. Each marker in the collection is updated with new tracking information. The marker info array is iterated over, and detected markers are matched up with those in the marker collection. Each matched marker is updated with visibility and transformation information. Any markers not detected are considered not currently visible.

Returns
  true if update completed successfully, false if an error occurred

bool ARController::updateDebugTexture | ( | const int | videoSourceIndex,
|  | Color * | buffer
| ) |  |

Populates the provided color buffer with the current contents of the debug image.

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  buffer | Pointer to a buffer of pixels (of type 'Color') to be filled. It is the caller's responsibility to ensure that the buffer is of sufficient size.

Returns
  true if successful, false if an error occurred

bool ARController::updateDebugTexture32 | ( | const int | videoSourceIndex,
|  | uint32_t * | buffer
| ) |  |

Populates the provided buffer with the current contents of the debug image.

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  buffer | Pointer to a buffer of pixels (of type 'uint32_t') to be filled. It is the caller's responsibility to ensure that the buffer is of sufficient size. The pixels are RGBA in little-endian systems, or ABGR in big-endian systems.

bool ARController::updateTexture | ( | const int | videoSourceIndex,
|  | Color * | buffer
| ) |  |

Asks the video source to push the most recent frame into the passed-in buffer.

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  buffer | Pointer to a buffer of pixels (of type 'Color') to be filled. It is the caller's responsibility to ensure that the buffer is of sufficient size.

bool ARController::updateTexture32 | ( | const int | videoSourceIndex,
|  | uint32_t * | buffer
| ) |  |

Asks the video source to push the most recent frame into the passed-in buffer.

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  buffer | Pointer to a buffer of pixels (of type 'uint32_t') to be filled. It is the caller's responsibility to ensure that the buffer is of sufficient size. The pixels are RGBA in little-endian systems, or ABGR in big-endian systems.

bool ARController::updateTextureGL | ( | const int | videoSourceIndex,
|  | const int | textureID
| ) |  |

Asks the video source to push the most recent frame into the OpenGL texture with the passed-in ID/name.

Must be called on a thread with a valid OpenGL context and a valid OpenGL 2D texture with the given ID/name.

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  textureID | OpenGL texture ID/name of the initialised texture to push the video frame to. It is the caller's responsibility to ensure that the texture is valid and of correct size and format.

bool ARController::videoAcceptImage | ( | JNIEnv * | env,
|  | jobject | obj,
|  | const int | videoSourceIndex,
|  | jbyteArray | pinArray,
|  | jint | width,
|  | jint | height,
|  | jint | cameraIndex,
|  | jboolean | cameraIsFrontFacing
| ) |  |

bool ARController::videoParameters | ( | const int | videoSourceIndex,
|  | int * | width,
|  | int * | height,
|  | AR_PIXEL_FORMAT * | pixelFormat
| ) |  |

Reports width, height and pixel format of a video source.

To retrieve the size (in bytes) of each pixel, use arUtilGetPixelSize(*pixelFormat); To get a C-string with the name of the pixel format, use arUtilGetPixelFormatName(*pixelFormat);

Parameters

  videoSourceIndex | Index into an array of video sources, specifying which source should be queried.
  width | Pointer to an int which will be filled with the width (in pixels) of the video frame, or NULL if this information is not required.
  height | Pointer to an int which will be filled with the height (in pixels) of the video frame, or NULL if this information is not required.
  pixelFormat | Pointer to an AR_PIXEL_FORMAT which will be filled with the pixel format of the video frame, or NULL if this information is not required.

Returns
  true if the video source(s) is/are open and returning frames, otherwise false.

## Member Data Documentation

PFN_LOGCALLBACK ARController::logCallback = NULL
| static

Callback where log messages are passed to.

The documentation for this class was generated from the following files:

- include/ARWrapper/ARController.h
- lib/SRC/ARWrapper/ARController.cpp