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/hiro.patt;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

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation