#include <visp3/detection/vpDetectorAprilTag.h>

Inheritance diagram for vpDetectorAprilTag:

Public Types
enum	vpAprilTagFamily { TAG_36h11, TAG_36h10, TAG_36ARTOOLKIT, TAG_25h9, TAG_25h7, TAG_16h5 }

enum	vpPoseEstimationMethod { HOMOGRAPHY_VIRTUAL_VS, DEMENTHON_VIRTUAL_VS, LAGRANGE_VIRTUAL_VS, BEST_RESIDUAL_VIRTUAL_VS }

Public Member Functions
	vpDetectorAprilTag (const vpAprilTagFamily &tagFamily=TAG_36h11, const vpPoseEstimationMethod &poseEstimationMethod=HOMOGRAPHY_VIRTUAL_VS)

virtual	~vpDetectorAprilTag ()

bool	detect (const vpImage< unsigned char > &I)

bool	detect (const vpImage< unsigned char > &I, const double tagSize, const vpCameraParameters &cam, std::vector< vpHomogeneousMatrix > &cMo_vec)

vpPoseEstimationMethod	getPoseEstimationMethod () const

void	setAprilTagNbThreads (const int nThreads)

void	setAprilTagPoseEstimationMethod (const vpPoseEstimationMethod &poseEstimationMethod)

void	setAprilTagQuadDecimate (const float quadDecimate)

void	setAprilTagQuadSigma (const float quadSigma)

void	setAprilTagRefineDecode (const bool refineDecode)

void	setAprilTagRefineEdges (const bool refineEdges)

void	setAprilTagRefinePose (const bool refinePose)

void	setDisplayTag (const bool display)

Inherited functionalities from vpDetectorBase
vpRect	getBBox (size_t i) const

vpImagePoint	getCog (size_t i) const

std::vector< std::string > &	getMessage ()

std::string &	getMessage (size_t i)

size_t	getNbObjects () const

std::vector< std::vector< vpImagePoint > > &	getPolygon ()

std::vector< vpImagePoint > &	getPolygon (size_t i)

Protected Attributes
bool	m_displayTag

vpPoseEstimationMethod	m_poseEstimationMethod

vpAprilTagFamily	m_tagFamily

std::vector< std::vector< vpImagePoint > >	m_polygon

std::vector< std::string >	m_message

size_t	m_nb_objects

Detailed Description

Base class for AprilTag detector. This class is a wrapper over AprilTag. There is no need to download and install AprilTag from source code or existing pre-built packages since the source code is embedded in ViSP. Reference papers are AprilTag: A robust and flexible visual fiducial system ([32]) and AprilTag 2: Efficient and robust fiducial detection ([42]).

The detect() function allows to detect multiple tags in an image. Once detected, for each tag it is possible to retrieve the location of the corners using getPolygon(), the encoded message using getMessage(), the bounding box using getBBox() and the center of gravity using getCog().

If camera parameters and the size of the tag are provided, thanks to detect(const vpImage<unsigned char> &, const double, const vpCameraParameters &, std::vector<vpHomogeneousMatrix> &) this class allows also to estimate the 3D pose of the tag in terms of position and orientation wrt the camera.

The following sample code shows how to use this class to detect the location of 36h11 AprilTag patterns in an image.

#include <visp3/detection/vpDetectorAprilTag.h>
#include <visp3/io/vpImageIo.h>
int main()
{
#ifdef VISP_HAVE_APRILTAG
  vpImage<unsigned char> I;
  vpImageIo::read(I, "image-tag36h11.pgm");
  vpDetectorAprilTag detector(vpDetectorAprilTag::TAG_36h11);
  bool status = detector.detect(I);
  if (status) {
    for(size_t i=0; i < detector.getNbObjects(); i++) {
      std::cout << "Tag code " << i << ":" << std::endl;
      std::vector<vpImagePoint> p = detector.getPolygon(i);
      for(size_t j=0; j < p.size(); j++)
        std::cout << "  Point " << j << ": " << p[j] << std::endl;
      std::cout << "  Message: \"" << detector.getMessage(i) << "\"" << std::endl;
    }
  }
#endif
}

The previous example may produce results like:

Tag code 0:
  Point 0: 124.008, 442.226
  Point 1: 194.614, 441.237
  Point 2: 184.833, 540.386
  Point 3: 111.948, 533.634
  Message: "36h11 id: 0"
Tag code 1:
  Point 0: 245.327, 438.801
  Point 1: 338.116, 437.221
  Point 2: 339.341, 553.539
  Point 3: 238.954, 543.855
  Message: "36h11 id: 1"

This other example shows how to estimate the 3D pose of 36h11 AprilTag patterns.

#include <visp3/detection/vpDetectorAprilTag.h>
#include <visp3/io/vpImageIo.h>
int main()
{
#ifdef VISP_HAVE_APRILTAG
  vpImage<unsigned char> I;
  vpImageIo::read(I, "image-tag36h11.pgm");
  vpDetectorAprilTag detector(vpDetectorAprilTag::TAG_36h11);
  std::vector<vpHomogeneousMatrix> cMo;
  vpCameraParameters cam;
  cam.initPersProjWithoutDistortion(615.1674805, 615.1675415, 312.1889954, 243.4373779);
  double tagSize = 0.053;
  bool status = detector.detect(I, tagSize, cam, cMo);
  if (status) {
    for(size_t i=0; i < detector.getNbObjects(); i++) {
      std::cout << "Tag code " << i << ":" << std::endl;
      std::cout << "  Message: \"" << detector.getMessage(i) << "\"" << std::endl;
      std::cout << "  Pose: " << vpPoseVector(cMo[i]).t() << std::endl;
    }
  }
#endif
}

The previous example may produce results like:

Tag code 0:
  Message: "36h11 id: 0"
  Pose: 0.1015061088  -0.05239057228  0.3549037285  1.991474322  2.04143538 -0.9412360063
Tag code 1:
  Message: "36h11 id: 1"
  Pose: 0.08951250829 0.02243780207  0.306540622  1.998073197  2.061488008  -0.8699567948

Other examples are also provided in tutorial-apriltag-detector.cpp and tutorial-apriltag-detector-live.cpp

Examples:: testAprilTag.cpp, tutorial-apriltag-detector-live.cpp, and tutorial-apriltag-detector.cpp.

Definition at line 155 of file vpDetectorAprilTag.h.

Member Enumeration Documentation

◆ vpAprilTagFamily

enum vpDetectorAprilTag::vpAprilTagFamily

Enumerator
TAG_36h11	AprilTag 36h11 pattern (recommended)
TAG_36h10	AprilTag 36h10 pattern
TAG_36ARTOOLKIT	ARToolKit pattern.
TAG_25h9	AprilTag 25h9 pattern
TAG_25h7	AprilTag 25h7 pattern
TAG_16h5	AprilTag 16h5 pattern

Examples:: tutorial-apriltag-detector-live.cpp, and tutorial-apriltag-detector.cpp.

Definition at line 159 of file vpDetectorAprilTag.h.

◆ vpPoseEstimationMethod

enum vpDetectorAprilTag::vpPoseEstimationMethod

Enumerator
HOMOGRAPHY_VIRTUAL_VS	Non linear virtual visual servoing approach initialized by the homography approach
DEMENTHON_VIRTUAL_VS	Non linear virtual visual servoing approach initialized by the Dementhon approach
LAGRANGE_VIRTUAL_VS	Non linear virtual visual servoing approach initialized by the Lagrange approach
BEST_RESIDUAL_VIRTUAL_VS	Non linear virtual visual servoing approach initialized by the approach that gives the lowest residual

Examples:: tutorial-apriltag-detector-live.cpp, and tutorial-apriltag-detector.cpp.

Definition at line 179 of file vpDetectorAprilTag.h.

Constructor & Destructor Documentation

◆ vpDetectorAprilTag()

vpDetectorAprilTag::vpDetectorAprilTag	(	const vpAprilTagFamily &	tagFamily = `TAG_36h11`,
		const vpPoseEstimationMethod &	poseEstimationMethod = `HOMOGRAPHY_VIRTUAL_VS`
	)

Default constructor.

Definition at line 307 of file vpDetectorAprilTag.cpp.

◆ ~vpDetectorAprilTag()

vpDetectorAprilTag::~vpDetectorAprilTag ( )

virtual

Destructor that desallocate memory.

Definition at line 317 of file vpDetectorAprilTag.cpp.

Member Function Documentation

◆ detect() [1/2]

bool vpDetectorAprilTag::detect ( const vpImage< unsigned char > & I )

virtual

Detect AprilTag tags in the image. Return true if at least one tag is detected, false otherwise.

Parameters

I	: Input image.

Returns: true if at least one tag is detected.

Implements vpDetectorBase.

Definition at line 326 of file vpDetectorAprilTag.cpp.

References m_displayTag, vpDetectorBase::m_message, vpDetectorBase::m_nb_objects, and vpDetectorBase::m_polygon.

Referenced by vpKeyPoint::saveLearningData().

◆ detect() [2/2]

bool vpDetectorAprilTag::detect	(	const vpImage< unsigned char > &	I,
		const double	tagSize,
		const vpCameraParameters &	cam,
		std::vector< vpHomogeneousMatrix > &	cMo_vec
	)

Detect AprilTag tags in the image and compute the corresponding tag poses.

Parameters

I	: Input image.
tagSize	: Tag size in meter corresponding to the external width of the pattern.
cam	: Camera intrinsic parameters.
cMo_vec	: List of tag poses.

Returns: true if at least one tag is detected.

Definition at line 346 of file vpDetectorAprilTag.cpp.

References m_displayTag, vpDetectorBase::m_message, vpDetectorBase::m_nb_objects, and vpDetectorBase::m_polygon.

◆ getBBox()

vpRect vpDetectorBase::getBBox ( size_t i ) const

inherited

Return the bounding box of the ith object.

Examples:: testAprilTag.cpp, tutorial-apriltag-detector.cpp, tutorial-barcode-detector-live.cpp, tutorial-barcode-detector.cpp, tutorial-face-detector-live-threaded.cpp, tutorial-face-detector-live.cpp, and tutorial-face-detector.cpp.

Definition at line 87 of file vpDetectorBase.cpp.

References vpDetectorBase::m_polygon.

◆ getCog()

vpImagePoint vpDetectorBase::getCog ( size_t i ) const

inherited

Return the center of gravity location of the ith object.

Definition at line 74 of file vpDetectorBase.cpp.

References vpDetectorBase::m_polygon.

◆ getMessage() [1/2]

std::vector<std::string>& vpDetectorBase::getMessage ( void )

inlineinherited

Returns the contained message of the ith object if there is one.

Examples:: testAprilTag.cpp, tutorial-apriltag-detector.cpp, tutorial-barcode-detector-live.cpp, tutorial-barcode-detector.cpp, tutorial-face-detector-live.cpp, and tutorial-face-detector.cpp.

Definition at line 107 of file vpDetectorBase.h.

◆ getMessage() [2/2]

std::string & vpDetectorBase::getMessage ( size_t i )

inherited

Returns the contained message of the ith object if there is one.

Definition at line 62 of file vpDetectorBase.cpp.

References vpException::badValue, vpDetectorBase::m_message, and vpDetectorBase::m_polygon.

◆ getNbObjects()

size_t vpDetectorBase::getNbObjects ( ) const

inlineinherited

Return the number of objects that are detected.

Examples:: testAprilTag.cpp, tutorial-apriltag-detector-live.cpp, tutorial-apriltag-detector.cpp, tutorial-barcode-detector-live.cpp, tutorial-barcode-detector.cpp, tutorial-face-detector-live.cpp, tutorial-face-detector.cpp, and tutorial-pose-from-qrcode-image.cpp.

Definition at line 117 of file vpDetectorBase.h.

◆ getPolygon() [1/2]

std::vector<std::vector<vpImagePoint> >& vpDetectorBase::getPolygon ( )

inlineinherited

Returns object container box as a vector of points.

Examples:: testAprilTag.cpp, tutorial-apriltag-detector.cpp, tutorial-barcode-detector-live.cpp, tutorial-barcode-detector.cpp, and tutorial-pose-from-qrcode-image.cpp.

Definition at line 122 of file vpDetectorBase.h.

◆ getPolygon() [2/2]

std::vector< vpImagePoint > & vpDetectorBase::getPolygon ( size_t i )

inherited

Returns ith object container box as a vector of points.

Definition at line 50 of file vpDetectorBase.cpp.

References vpException::badValue, and vpDetectorBase::m_polygon.

◆ getPoseEstimationMethod()

vpPoseEstimationMethod vpDetectorAprilTag::getPoseEstimationMethod ( ) const

inline

Return the pose estimation method.

Definition at line 202 of file vpDetectorAprilTag.h.

◆ setAprilTagNbThreads()

void vpDetectorAprilTag::setAprilTagNbThreads ( const int nThreads )

Set the number of threads for April Tag detection (default is 1).

Parameters

nThreads : Number of thread.

Definition at line 367 of file vpDetectorAprilTag.cpp.

◆ setAprilTagPoseEstimationMethod()

void vpDetectorAprilTag::setAprilTagPoseEstimationMethod ( const vpPoseEstimationMethod & poseEstimationMethod )

Set the method to use to compute the pose,

See also: vpPoseEstimationMethod

Parameters

poseEstimationMethod : The method to used.

Definition at line 378 of file vpDetectorAprilTag.cpp.

References m_poseEstimationMethod.

◆ setAprilTagQuadDecimate()

void vpDetectorAprilTag::setAprilTagQuadDecimate ( const float quadDecimate )

From the AprilTag code:

detection of quads can be done on a lower-resolution image, improving speed at a cost of pose accuracy and a slight decrease in detection rate. Decoding the binary payload is still done at full resolution.

Default is 1.0, increase this value to reduce the computation time.

Parameters

quadDecimate : Value for quad_decimate.

Definition at line 396 of file vpDetectorAprilTag.cpp.

◆ setAprilTagQuadSigma()

void vpDetectorAprilTag::setAprilTagQuadSigma ( const float quadSigma )

From the AprilTag code:

What Gaussian blur should be applied to the segmented image (used for quad detection?) Parameter is the standard deviation in pixels. Very noisy images benefit from non-zero values (e.g. 0.8).

Default is 0.0.

Parameters

quadSigma : Value for quad_sigma.

Definition at line 410 of file vpDetectorAprilTag.cpp.

◆ setAprilTagRefineDecode()

void vpDetectorAprilTag::setAprilTagRefineDecode ( const bool refineDecode )

From the AprilTag code:

when non-zero, detections are refined in a way intended to increase the number of detected tags. Especially effective for very small tags near the resolution threshold (e.g. 10px on a side).

Default is 0.

Parameters

refineDecode : If true, set refine_decode to 1.

Definition at line 424 of file vpDetectorAprilTag.cpp.

◆ setAprilTagRefineEdges()

void vpDetectorAprilTag::setAprilTagRefineEdges ( const bool refineEdges )

From the AprilTag code:

When non-zero, the edges of the each quad are adjusted to "snap to" strong gradients nearby. This is useful when decimation is employed, as it can increase the quality of the initial quad estimate substantially. Generally recommended to be on (1). Very computationally inexpensive. Option is ignored if quad_decimate = 1.

Default is 1.

Parameters

refineEdges : If true, set refine_edges to 1.

Definition at line 440 of file vpDetectorAprilTag.cpp.

◆ setAprilTagRefinePose()

void vpDetectorAprilTag::setAprilTagRefinePose ( const bool refinePose )

From the AprilTag code:

when non-zero, detections are refined in a way intended to increase the accuracy of the extracted pose. This is done by maximizing the contrast around the black and white border of the tag. This generally increases the number of successfully detected tags, though not as effectively (or quickly) as refine_decode. This option must be enabled in order for "goodness" to be computed.

Default is 0.

Parameters

refinePose : If true, set refine_pose to 1.

Definition at line 458 of file vpDetectorAprilTag.cpp.

◆ setDisplayTag()

void vpDetectorAprilTag::setDisplayTag ( const bool display )

inline

Allow to enable the display of overlay tag information in the windows (vpDisplay) associated to the input image.

Definition at line 214 of file vpDetectorAprilTag.h.

Member Data Documentation

◆ m_displayTag

bool vpDetectorAprilTag::m_displayTag

protected

Definition at line 217 of file vpDetectorAprilTag.h.

Referenced by detect().

◆ m_message

std::vector<std::string> vpDetectorBase::m_message

protectedinherited

Message attached to each object.

Definition at line 71 of file vpDetectorBase.h.

Referenced by vpDetectorFace::detect(), vpDetectorDataMatrixCode::detect(), vpDetectorQRCode::detect(), detect(), and vpDetectorBase::getMessage().

◆ m_nb_objects

size_t vpDetectorBase::m_nb_objects

protectedinherited

Number of detected objects.

Definition at line 72 of file vpDetectorBase.h.

Referenced by vpDetectorFace::detect(), vpDetectorDataMatrixCode::detect(), vpDetectorQRCode::detect(), and detect().

◆ m_polygon

std::vector<std::vector<vpImagePoint> > vpDetectorBase::m_polygon

protectedinherited

For each object, defines the polygon that contains the object.

Definition at line 67 of file vpDetectorBase.h.

Referenced by vpDetectorFace::detect(), vpDetectorDataMatrixCode::detect(), vpDetectorQRCode::detect(), detect(), vpDetectorBase::getBBox(), vpDetectorBase::getCog(), vpDetectorBase::getMessage(), and vpDetectorBase::getPolygon().

◆ m_poseEstimationMethod

vpPoseEstimationMethod vpDetectorAprilTag::m_poseEstimationMethod

protected

Definition at line 218 of file vpDetectorAprilTag.h.

Referenced by setAprilTagPoseEstimationMethod().

◆ m_tagFamily

vpAprilTagFamily vpDetectorAprilTag::m_tagFamily

protected

Definition at line 219 of file vpDetectorAprilTag.h.

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ vpAprilTagFamily

◆ vpPoseEstimationMethod

Constructor & Destructor Documentation

◆ vpDetectorAprilTag()

◆ ~vpDetectorAprilTag()

Member Function Documentation

◆ detect() [1/2]

◆ detect() [2/2]

◆ getBBox()

◆ getCog()

◆ getMessage() [1/2]

◆ getMessage() [2/2]

◆ getNbObjects()

◆ getPolygon() [1/2]

◆ getPolygon() [2/2]

◆ getPoseEstimationMethod()

◆ setAprilTagNbThreads()

◆ setAprilTagPoseEstimationMethod()

◆ setAprilTagQuadDecimate()

◆ setAprilTagQuadSigma()

◆ setAprilTagRefineDecode()

◆ setAprilTagRefineEdges()

◆ setAprilTagRefinePose()

◆ setDisplayTag()

Member Data Documentation

◆ m_displayTag

◆ m_message

◆ m_nb_objects

◆ m_polygon

◆ m_poseEstimationMethod

◆ m_tagFamily