ARX  1.2.0
The next-generation open source augmented reality toolkit.
Loading...
Searching...
No Matches
ARController Class Reference

Wrapper for artoolkitX functionality. More...

#include <ARController.h>

Public Member Functions

 ARController ()
 Constructor.
 ~ARController ()
 Destructor.
const char * getARToolKitVersion ()
 Returns a string containing the artoolkitX version, such as "10.0.0".
int getError ()
bool initialiseBase ()
 Start trackable management so trackables can be added and removed.
std::shared_ptr< ARTrackerSquare > getSquareTracker ()
bool isInited ()
 Report whether artoolkit was initialized and a trackable can be added.
bool startRunning (const char *vconf, const char *cparaName, const char *cparaBuff, const long cparaBuffLen)
 Start video capture and tracking.
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 tracking.
int videoPushInit (int videoSourceIndex, int width, int height, const char *pixelFormat, int cameraIndex, int cameraPosition)
int videoPush (int videoSourceIndex, ARUint8 *buf0p, int buf0Size, int buf0PixelStride, int buf0RowStride, ARUint8 *buf1p, int buf1Size, int buf1PixelStride, int buf1RowStride, ARUint8 *buf2p, int buf2Size, int buf2PixelStride, int buf2RowStride, ARUint8 *buf3p, int buf3Size, int buf3PixelStride, int buf3RowStride, PFN_VIDEOPUSHRELEASECALLBACK releaseCallback, void *releaseCallbackUserdata)
int videoPushFinal (int videoSourceIndex)
bool videoParameters (const int videoSourceIndex, int *width, int *height, AR_PIXEL_FORMAT *pixelFormat)
 Reports width, height and pixel format of a video source.
bool isRunning ()
 Returns true if video capture and tracking is running.
bool stopRunning ()
 Video capture and tracking stops, but trackables are still valid and can be configured.
bool shutdown ()
 Stop, if running.
bool projectionMatrix (const int videoSourceIndex, const ARdouble projectionNearPlane, const ARdouble projectionFarPlane, ARdouble proj[16])
 Populates the provided array with the ARToolKit projection matrix.
bool projectionForViewportSizeAndFittingMode (const int videoSourceIndex, const ARVideoSource::Size viewportSize, const ARVideoSource::ScalingMode scalingMode, const ARdouble projectionNearPlane, const ARdouble projectionFarPlane, ARdouble proj[16])
 Populates the provided array with the ARToolKit projection matrix, so that the projection maps to the provided viewport dimensions using the provided scaling mode.
bool drawVideoInit (const int videoSourceIndex)
 Initialise an ARVideoView for drawing a video source's frame.
bool drawVideoSettings (const int videoSourceIndex, const int width, const int height, const bool rotate90, const bool flipH, const bool flipV, const ARVideoView::HorizontalAlignment hAlign, const ARVideoView::VerticalAlignment vAlign, const ARVideoView::ScalingMode scalingMode, int32_t viewport[4])
 Sets drawing parameters for an ARVideoView for drawing a video source's frame into a graphics buffer of specified size using specified position and mode, and returns the viewport required in graphics context units.
bool drawVideo (const int videoSourceIndex)
 Use an ARVideoView to draw a video source's frame into the graphics buffer.
bool drawVideoFinal (const int videoSourceIndex)
 Finalise an ARVideoView.
int addTrackable (const std::string &cfgs)
 Adds a trackable as specified in the given configuration string.
bool removeTrackable (int UID)
 Removes the trackable with the given ID.
int removeAllTrackables ()
 Clears the collection of trackables.
unsigned int countTrackables () const
 Returns the number of currently loaded trackables.
unsigned int countTrackables (ARTrackable::TrackableType trackableType) const
 Returns the number of currently loaded trackables of the specified type.
std::vector< std::shared_ptr< ARTrackable > > getAllTrackables ()
 Returns all trackables.
std::shared_ptr< ARTrackable > findTrackable (int UID)
 Searches the collection of trackables for the given ID.
bool capture ()
 Requests the capture of a new frame from the video source(s).
bool updateTextureRGBA32 (const int videoSourceIndex, uint32_t *buffer)
 Asks the video source to push the most recent frame into the passed-in buffer.
bool update ()
 Performs tracking and updates all trackables.
bool updateDebugTexture32 (const int videoSourceIndex, uint32_t *buffer)
 Populates the provided buffer with the current contents of the debug image.
bool getPatternImage (int patternID, uint32_t *buffer)
 Populates the provided color buffer with the image for the specified pattern.
bool loadOpticalParams (const char *optical_param_name, const char *optical_param_buff, const long optical_param_buffLen, const ARdouble projectionNearPlane, const ARdouble projectionFarPlane, ARdouble *fovy_p, ARdouble *aspect_p, ARdouble m[16], ARdouble p[16])
 Loads an optical parameters structure from file or from buffer.

Detailed Description

Wrapper for artoolkitX functionality.

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

Constructor & Destructor Documentation

◆ ARController()

ARController::ARController ( )

Constructor.

◆ ~ARController()

ARController::~ARController ( )

Destructor.

Here is the call graph for this function:

Member Function Documentation

◆ addTrackable()

int ARController::addTrackable ( const std::string & cfgs)

Adds a trackable as specified in the given configuration string.

The format of the string can be one of:

  • Square marker from pattern file: "single;pattern_file;pattern_width", e.g. "single;data/hiro.patt;80"
  • Square marker from pattern passed in config: "single_buffer;pattern_width;buffer=[]", e.g. "single_buffer;80;buffer=234 221 237..."
  • Square barcode marker: "single_barcode;barcode_id;pattern_width", e.g. "single_barcode;0;80"
  • Multi-square marker: "multi;config_file", e.g. "multi;data/multi/marker.dat"
  • Multi-square auto marker: "multi;origin_barcode_id;pattern_width", e.g. "multi;0;80.0"
  • NFT marker: "nft;nft_dataset_pathname", e.g. "nft;gibraltar"
Parameters
cfgsThe configuration string
Returns
The UID of the trackable instantiated based on the configuration string, or -1 if an error occurred.
Here is the call graph for this function:

◆ capture()

bool ARController::capture ( )

Requests the capture of a new frame from the video source(s).

In the case of stereo video sources, capture from both sources will be attempted.

Returns
The capture succeeded, or false if no frame was captured.

◆ countTrackables() [1/2]

unsigned int ARController::countTrackables ( ) const

Returns the number of currently loaded trackables.

Returns
The number of currently loaded trackables.

◆ countTrackables() [2/2]

unsigned int ARController::countTrackables ( ARTrackable::TrackableType trackableType) const

Returns the number of currently loaded trackables of the specified type.

Returns
The number of currently loaded trackables.
Here is the call graph for this function:

◆ drawVideo()

bool ARController::drawVideo ( const int videoSourceIndex)

Use an ARVideoView to draw a video source's frame into the graphics buffer.

Requires a current graphics context.

Parameters
videoSourceIndexThe 0-based index of the video source.
Returns
true if successful, false in case of error.

◆ drawVideoFinal()

bool ARController::drawVideoFinal ( const int videoSourceIndex)

Finalise an ARVideoView.

Requires a current graphics context.

Parameters
videoSourceIndexThe 0-based index of the video source.
Returns
true if successful, false in case of error.

◆ drawVideoInit()

bool ARController::drawVideoInit ( const int videoSourceIndex)

Initialise an ARVideoView for drawing a video source's frame.

Requires a current graphics context.

Parameters
videoSourceIndexThe 0-based index of the video source.
Returns
true if successful, false in case of error.

◆ drawVideoSettings()

bool ARController::drawVideoSettings ( const int videoSourceIndex,
const int width,
const int height,
const bool rotate90,
const bool flipH,
const bool flipV,
const ARVideoView::HorizontalAlignment hAlign,
const ARVideoView::VerticalAlignment vAlign,
const ARVideoView::ScalingMode scalingMode,
int32_t viewport[4] )

Sets drawing parameters for an ARVideoView for drawing a video source's frame into a graphics buffer of specified size using specified position and mode, and returns the viewport required in graphics context units.

Requires a current graphics context.

Parameters
videoSourceIndexThe 0-based index of the video source.
widthwidth of the graphics context into which the frame will be drawn, in pixels.
heightheight of the graphics context into which the frame will be drawn, in pixels.
rotate90If true, rotate the video frame anticlockwise by 90 degrees,
flipHIf true, flip the video frame horizontally (i.e. mirror about the vertical axis).
hAlignWhether to left-align, centre, or right-align the video frame.
vAlignWhether to top-align, centre, or bottom-align the video frame.
scalingModeWhether to fit, fill or draw unscaled. In fit mode, undrawn regions may appear above and below or left and right of the frame if it has a dfferent aspect ratio to the graphics context. In fill mode, the graphics context will be entirely filled, but some of the video frame may be cropped top and bottom or left and right if it has a dfferent aspect ratio to the graphics context.
viewport(Output). If the resulting viewport is required, set this to a pointer to an array of 4 int32, which will be filled with the origin lower-left x and y coordinates, and the width and height of the viewport, all in pixels. Note that the viewport origin x or y values may be negative depending on alignment and positioning of the video frame.
Returns
true if the settings were successfully set, false in case of error.

◆ findTrackable()

std::shared_ptr< ARTrackable > ARController::findTrackable ( int UID)

Searches the collection of trackables for the given ID.

Once the trackable has been found, its parameters such as whether it is currently tracked and its pose can be queried, or configuration of the trackable can be changed.

Parameters
UIDThe UID of the trackable to find
Returns
The found trackable, or null pointer if no matching UID was found.
See also
ARTrackable.

◆ getAllTrackables()

std::vector< std::shared_ptr< ARTrackable > > ARController::getAllTrackables ( )

Returns all trackables.

Returns
A vector of shared pointers to the trackables.

◆ getARToolKitVersion()

const char * ARController::getARToolKitVersion ( )

Returns a string containing the artoolkitX version, such as "10.0.0".

Returns
The artoolkitX version
Here is the call graph for this function:

◆ getError()

int ARController::getError ( )

◆ getPatternImage()

bool ARController::getPatternImage ( int patternID,
uint32_t * buffer )

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

Parameters
patternIDThe artoolkitX pattern ID to use
bufferThe color buffer to populate
Returns
true if successful, false if an error occurred
Here is the call graph for this function:

◆ getSquareTracker()

std::shared_ptr< ARTrackerSquare > ARController::getSquareTracker ( )
inline

◆ initialiseBase()

bool ARController::initialiseBase ( )

Start trackable management so trackables can be added and removed.

Returns
true if initialisation was OK, false if an error occured.
Here is the call graph for this function:

◆ isInited()

bool ARController::isInited ( )

Report whether artoolkit was initialized and a trackable can be added.

Trackables can be added once basic initialisation has occurred.

Returns
true if adding a trackable is currently possible

◆ isRunning()

bool ARController::isRunning ( )

Returns true if video capture and tracking is running.

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

◆ loadOpticalParams()

bool ARController::loadOpticalParams ( const char * optical_param_name,
const char * optical_param_buff,
const long optical_param_buffLen,
const ARdouble projectionNearPlane,
const ARdouble projectionFarPlane,
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_nameIf supplied, points to a buffer specifying the path to the optical parameters file (as generated by the calib_optical utility.)
optical_param_buffIf optical_param_name is NULL, the contents of this buffer will be interpreted as containing the contents of an optical parameters file.
optical_param_buffLenLength of the buffer specified in optical_param_buff. Ignored if optical_param_buff is NULL.
projectionNearPlaneIf p is non-NULL, near plane distance for projection matrix calculation.
projectionFarPlaneIf p is non-NULL, far plane distance for projection matrix calculation.
fovy_pPointer to an ARdouble, which will be filled with the field-of-view (Y axis) component of the optical parameters.
aspect_pPointer to an ARdouble, which will be filled with the aspect ratio (width / height) component of the optical parameters.
mPointer to an array of 16 ARdoubles, which will be filled with the transformation matrix component of the optical parameters.
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 projectionNearPlane and projectionFarPlane.
Here is the call graph for this function:

◆ projectionForViewportSizeAndFittingMode()

bool ARController::projectionForViewportSizeAndFittingMode ( const int videoSourceIndex,
const ARVideoSource::Size viewportSize,
const ARVideoSource::ScalingMode scalingMode,
const ARdouble projectionNearPlane,
const ARdouble projectionFarPlane,
ARdouble proj[16] )

Populates the provided array with the ARToolKit projection matrix, so that the projection maps to the provided viewport dimensions using the provided scaling mode.

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
videoSourceIndexIndex into an array of video sources, specifying which source should be queried.
viewportSizewidth and height of the viewport to which the projection is to be fitted.
scalingModeWhether the camera projection should completely fill, completely fit within, stratch, or map 1:1 to the viewport.
projectionNearPlaneNear plane distance for projection matrix calculation.
projectionFarPlaneFar plane distance for projection matrix calculation.
projArray to populate with OpenGL compatible projection matrix
Returns
true if the projection matrix has been computed, otherwise false
Here is the call graph for this function:

◆ projectionMatrix()

bool ARController::projectionMatrix ( const int videoSourceIndex,
const ARdouble projectionNearPlane,
const ARdouble projectionFarPlane,
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
videoSourceIndexIndex into an array of video sources, specifying which source should be queried.
projectionNearPlaneNear plane distance for projection matrix calculation.
projectionFarPlaneFar plane distance for projection matrix calculation.
projArray to populate with OpenGL compatible projection matrix
Returns
true if the projection matrix has been computed, otherwise false
Here is the call graph for this function:

◆ removeAllTrackables()

int ARController::removeAllTrackables ( )

Clears the collection of trackables.

Returns
The number of trackables removed
Here is the call graph for this function:

◆ removeTrackable()

bool ARController::removeTrackable ( int UID)

Removes the trackable with the given ID.

Parameters
UIDThe UID of the trackable to remove
Returns
true if the trackable was removed, false if an error occurred.
Here is the call graph for this function:

◆ shutdown()

bool ARController::shutdown ( )

Stop, if running.

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

Returns
true if shutdown was successful, otherwise false
Here is the call graph for this function:

◆ startRunning()

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

Start video capture and tracking.

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

Parameters
vconfVideo configuration string.
cparaNameCamera parameters filename, or NULL if camera parameters file not being used.
cparaBuffA byte-buffer containing contents of a camera parameters file, or NULL if a camera parameters file is being used.
cparaBuffLenLength (in bytes) of cparaBuffLen, or 0 if a camera parameters file is being used.
Returns
true if video capture and tracking was started, otherwise false.
Here is the call graph for this function:

◆ startRunningStereo()

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 tracking.

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

Parameters
vconfLVideo configuration string for the "left" video source.
cparaNameLCamera parameters filename for the "left" video source, or NULL if camera parameters file not being used.
cparaBuffLA byte-buffer containing contents of a camera parameters file for the "left" video source, or NULL if a camera parameters file is being used.
cparaBuffLenLLength (in bytes) of cparaBuffLenL, or 0 if a camera parameters file is being used.
vconfRVideo configuration string for the "right" video source.
cparaNameRCamera parameters filename for the "right" video source, or NULL if camera parameters file not being used.
cparaBuffRA byte-buffer containing contents of a camera parameters file for the "right" video source, or NULL if a camera parameters file is being used.
cparaBuffLenRLength (in bytes) of cparaBuffLenR, or 0 if a camera parameters file is being used.
transL2RNameStereo calibration filename, or NULL if stereo calibration file not being used.
transL2RBuffA byte-buffer containing contents of a stereo calibration file, or NULL if a stereo calibration file is being used.
transL2RBuffLenLength (in bytes) of transL2RBuff, or 0 if a stereo calibration file is being used.
Returns
true if video capture and tracking was started, otherwise false.
Here is the call graph for this function:

◆ stopRunning()

bool ARController::stopRunning ( )

Video capture and tracking stops, but trackables are still valid and can be configured.

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

◆ update()

bool ARController::update ( )

Performs tracking and updates all trackables.

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

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

◆ updateDebugTexture32()

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

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

Parameters
videoSourceIndexIndex into an array of video sources, specifying which source should be queried.
bufferPointer 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.

◆ updateTextureRGBA32()

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

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

Parameters
videoSourceIndexIndex into an array of video sources, specifying which source should be queried.
bufferPointer 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.
Here is the call graph for this function:

◆ videoParameters()

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
videoSourceIndex0-based index into an array of video sources, specifying which source should be queried.
widthPointer to an int which will be filled with the width (in pixels) of the video frame, or NULL if this information is not required.
heightPointer to an int which will be filled with the height (in pixels) of the video frame, or NULL if this information is not required.
pixelFormatPointer 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.
Here is the call graph for this function:

◆ videoPush()

int ARController::videoPush ( int videoSourceIndex,
ARUint8 * buf0p,
int buf0Size,
int buf0PixelStride,
int buf0RowStride,
ARUint8 * buf1p,
int buf1Size,
int buf1PixelStride,
int buf1RowStride,
ARUint8 * buf2p,
int buf2Size,
int buf2PixelStride,
int buf2RowStride,
ARUint8 * buf3p,
int buf3Size,
int buf3PixelStride,
int buf3RowStride,
PFN_VIDEOPUSHRELEASECALLBACK releaseCallback,
void * releaseCallbackUserdata )
Here is the call graph for this function:

◆ videoPushFinal()

int ARController::videoPushFinal ( int videoSourceIndex)
Here is the call graph for this function:

◆ videoPushInit()

int ARController::videoPushInit ( int videoSourceIndex,
int width,
int height,
const char * pixelFormat,
int cameraIndex,
int cameraPosition )
Here is the call graph for this function:

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