#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 , TAG_CIRCLE21h7 , TAG_CIRCLE49h12 , TAG_CUSTOM48h12 , TAG_STANDARD41h12 , TAG_STANDARD52h13 }

enum	vpPoseEstimationMethod { HOMOGRAPHY , HOMOGRAPHY_VIRTUAL_VS , DEMENTHON_VIRTUAL_VS , LAGRANGE_VIRTUAL_VS , BEST_RESIDUAL_VIRTUAL_VS , HOMOGRAPHY_ORTHOGONAL_ITERATION }

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

	vpDetectorAprilTag (const vpDetectorAprilTag &o)

vpDetectorAprilTag &	operator= (vpDetectorAprilTag o)

virtual	~vpDetectorAprilTag () VP_OVERRIDE

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

bool	detect (const vpImage< unsigned char > &I, double tagSize, const vpCameraParameters &cam, std::vector< vpHomogeneousMatrix > &cMo_vec, std::vector< vpHomogeneousMatrix > cMo_vec2=nullptr, std::vector< double > projErrors=nullptr, std::vector< double > *projErrors2=nullptr)

void	displayFrames (const vpImage< unsigned char > &I, const std::vector< vpHomogeneousMatrix > &cMo_vec, const vpCameraParameters &cam, double size, const vpColor &color, unsigned int thickness=1) const

void	displayFrames (const vpImage< vpRGBa > &I, const std::vector< vpHomogeneousMatrix > &cMo_vec, const vpCameraParameters &cam, double size, const vpColor &color, unsigned int thickness=1) const

void	displayTags (const vpImage< unsigned char > &I, const std::vector< std::vector< vpImagePoint > > &tagsCorners, const vpColor &color=vpColor::none, unsigned int thickness=1) const

void	displayTags (const vpImage< vpRGBa > &I, const std::vector< std::vector< vpImagePoint > > &tagsCorners, const vpColor &color=vpColor::none, unsigned int thickness=1) const

bool	getPose (size_t tagIndex, double tagSize, const vpCameraParameters &cam, vpHomogeneousMatrix &cMo, vpHomogeneousMatrix cMo2=nullptr, double projError=nullptr, double *projError2=nullptr)

vpPoseEstimationMethod	getPoseEstimationMethod () const

std::vector< std::vector< vpImagePoint > >	getTagsCorners () const

std::vector< int >	getTagsId () const

std::vector< std::vector< vpPoint > >	getTagsPoints3D (const std::vector< int > &tagsId, const std::map< int, double > &tagsSize) const

bool	isZAlignedWithCameraAxis () const

void	setAprilTagDecodeSharpening (double decodeSharpening)

void	setAprilTagFamily (const vpAprilTagFamily &tagFamily)

void	setAprilTagNbThreads (int nThreads)

void	setAprilTagPoseEstimationMethod (const vpPoseEstimationMethod &poseEstimationMethod)

void	setAprilTagQuadDecimate (float quadDecimate)

void	setAprilTagQuadSigma (float quadSigma)

void	setAprilTagRefineEdges (bool refineEdges)

void	setDisplayTag (bool display, const vpColor &color=vpColor::none, unsigned int thickness=2)

void	setZAlignedWithCameraAxis (bool zAlignedWithCameraFrame)

Protected Attributes
bool	m_displayTag

vpColor	m_displayTagColor

unsigned int	m_displayTagThickness

vpPoseEstimationMethod	m_poseEstimationMethod

vpAprilTagFamily	m_tagFamily

Friends
void	swap (vpDetectorAprilTag &o1, vpDetectorAprilTag &o2)

Inherited functionalities from vpDetectorBase
std::vector< std::vector< vpImagePoint > >	m_polygon

std::vector< std::string >	m_message

size_t	m_nb_objects

unsigned long	m_timeout_ms

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)

void	setTimeout (unsigned long timeout_ms)

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 ([40]), AprilTag 2: Efficient and robust fiducial detection ([52]) and Flexible Layouts for Fiducial Tags (Under Review) ([24]).

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, you can also estimate the 3D pose of the tag in terms of position and orientation wrt the camera considering 2 cases:

1. If all the tags have the same size use detect(const vpImage<unsigned char> &, double, const vpCameraParameters &, std::vector<vpHomogeneousMatrix> &, std::vector<vpHomogeneousMatrix> *, std::vector<double> *, std::vector<double> *)
2. If tag sizes differ, use rather getPose()

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>
 
#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif
 
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"

As shown in the next image, two different tag frames could be considered for pose estimation.

Tag 36h11_00000 with location of the 4 corners and tag frame

There is the function setZAlignedWithCameraAxis() that allows to choose which tag frame has to be considered.

This other example shows how to estimate the 3D pose of 36h11 AprilTag patterns considering that all the tags have the same size (in our example 0.053 m). Here we consider the default case, when z-camera and z-tag axis are not aligned.

#include <visp3/detection/vpDetectorAprilTag.h>
#include <visp3/io/vpImageIo.h>
 
#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif
 
int main()
{
#ifdef VISP_HAVE_APRILTAG
  vpImage<unsigned char> I;
  vpImageIo::read(I, "image-tag36h11.pgm");
 
  vpDetectorAprilTag detector(vpDetectorAprilTag::TAG_36h11);
  detector.setZAlignedWithCameraAxis(false); // Default configuration
  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 number " << i << ":" << std::endl;
      std::cout << "  Message: \"" << detector.getMessage(i) << "\"" << std::endl;
      std::cout << "  Pose: " << vpPoseVector(cMo[i]).t() << std::endl;
      std::size_t tag_id_pos = detector.getMessage(i).find("id: ");
      if (tag_id_pos != std::string::npos) {
        std::string tag_id = detector.getMessage(i).substr(tag_id_pos + 4);
        std::cout << "  Tag Id: " << tag_id << std::endl;
      }
    }
  }
#endif
}

The previous example may produce results like:

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

In this other example we estimate the 3D pose of 36h11 AprilTag patterns considering that tag 36h11 with id 0 (in that case the tag message is "36h11 id: 0") has a size of 0.040 m, while all the others have a size of 0.053m.

#include <visp3/detection/vpDetectorAprilTag.h>
#include <visp3/io/vpImageIo.h>
 
#ifdef ENABLE_VISP_NAMESPACE
using namespace VISP_NAMESPACE_NAME;
#endif
 
int main()
{
#ifdef VISP_HAVE_APRILTAG
  vpImage<unsigned char> I;
  vpImageIo::read(I, "image-tag36h11.pgm");
 
  vpDetectorAprilTag detector(vpDetectorAprilTag::TAG_36h11);
  vpHomogeneousMatrix cMo;
  vpCameraParameters cam;
  cam.initPersProjWithoutDistortion(615.1674805, 615.1675415, 312.1889954, 243.4373779);
  double tagSize_id_0 = 0.04;
  double tagSize_id_others = 0.053;
 
  bool status = detector.detect(I);
  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;
      if (detector.getMessage(i) == std::string("36h11 id: 0")) {
        if (! detector.getPose(i, tagSize_id_0, cam, cMo)) {
          std::cout << "Unable to get tag index " << i << " pose!" << std::endl;
        }
      }
      else {
        if (! detector.getPose(i, tagSize_id_others, cam, cMo)) {
          std::cout << "Unable to get tag index " << i << " pose!" << std::endl;
        }
      }
      std::cout << "  Pose: " << vpPoseVector(cMo).t() << std::endl;
    }
  }
#endif
}

With respect to the previous example, this example may now produce a different pose for tag with id 0:

Tag code 0:
  Message: "36h11 id: 0"
  Pose: 0.07660838403  -0.03954005455  0.2678518706  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

Definition at line 234 of file vpDetectorAprilTag.h.

Member Enumeration Documentation

◆ vpAprilTagFamily

enum vpDetectorAprilTag::vpAprilTagFamily

Enumerator
TAG_36h11	AprilTag 36h11 pattern (recommended)
TAG_36h10	DEPRECATED.
TAG_36ARTOOLKIT	DEPRECATED AND WILL NOT DETECT ARTOOLKIT TAGS.
TAG_25h9	AprilTag 25h9 pattern.
TAG_25h7	DEPRECATED AND POOR DETECTION PERFORMANCE.
TAG_16h5	AprilTag 16h5 pattern.
TAG_CIRCLE21h7	AprilTag Circle21h7 pattern.
TAG_CIRCLE49h12	AprilTag Circle49h12 pattern.
TAG_CUSTOM48h12	AprilTag Custom48h12 pattern.
TAG_STANDARD41h12	AprilTag Standard41h12 pattern.
TAG_STANDARD52h13	AprilTag Standard52h13 pattern.

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, tutorial-mb-generic-tracker-apriltag-rs2.cpp, and tutorial-mb-generic-tracker-apriltag-webcam.cpp.

Definition at line 237 of file vpDetectorAprilTag.h.

◆ vpPoseEstimationMethod

enum vpDetectorAprilTag::vpPoseEstimationMethod

Enumerator
HOMOGRAPHY	Pose from homography
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
HOMOGRAPHY_ORTHOGONAL_ITERATION	Pose from homography followed by a refinement by Orthogonal Iteration

Examples: tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, and tutorial-apriltag-detector-live.cpp.

Definition at line 252 of file vpDetectorAprilTag.h.

Constructor & Destructor Documentation

◆ vpDetectorAprilTag() [1/2]

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

Definition at line 857 of file vpDetectorAprilTag.cpp.

◆ vpDetectorAprilTag() [2/2]

vpDetectorAprilTag::vpDetectorAprilTag ( const vpDetectorAprilTag & o )

Definition at line 864 of file vpDetectorAprilTag.cpp.

◆ ~vpDetectorAprilTag()

vpDetectorAprilTag::~vpDetectorAprilTag ( )

virtual

Definition at line 876 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.

Examples: catchAprilTag.cpp, mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, perfApriltagDetection.cpp, servoBiclopsPoint2DArtVelocity.cpp, servoPololuPtuPoint2DJointVelocity.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, tutorial-apriltag-detector.cpp, tutorial-flir-ptu-ibvs.cpp, tutorial-mb-generic-tracker-apriltag-rs2.cpp, and tutorial-mb-generic-tracker-apriltag-webcam.cpp.

Definition at line 885 of file vpDetectorAprilTag.cpp.

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

◆ detect() [2/2]

bool vpDetectorAprilTag::detect	(	const vpImage< unsigned char > &	I,
		double	tagSize,
		const vpCameraParameters &	cam,
		std::vector< vpHomogeneousMatrix > &	cMo_vec,
		std::vector< vpHomogeneousMatrix > *	cMo_vec2 = `nullptr`,
		std::vector< double > *	projErrors = `nullptr`,
		std::vector< double > *	projErrors2 = `nullptr`
	)

Detect AprilTag tags in the image and compute the corresponding tag poses considering that all the tags have the same size.

If tags with different sizes have to be considered, you may use getPose().

Parameters

[in]	I	: Input image.
[in]	tagSize	: Tag size in meter corresponding to the external width of the pattern.
[in]	cam	: Camera intrinsic parameters.
[out]	cMo_vec	: List of tag poses.
[out]	cMo_vec2	: Optional second list of tag poses, since there are 2 solutions for planar pose estimation.
[out]	projErrors	: Optional (sum of squared) projection errors in the normalized camera frame.
[out]	projErrors2	: Optional (sum of squared) projection errors for the 2nd solution in the normalized camera frame.

Returns: true if at least one tag is detected.

See also: getPose()

Definition at line 917 of file vpDetectorAprilTag.cpp.

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

◆ displayFrames() [1/2]

void vpDetectorAprilTag::displayFrames	(	const vpImage< unsigned char > &	I,
		const std::vector< vpHomogeneousMatrix > &	cMo_vec,
		const vpCameraParameters &	cam,
		double	size,
		const vpColor &	color,
		unsigned int	thickness = `1`
	)		const

Display the tag frames on a grayscale image.

Parameters

[in]	I	: The image.
[in]	cMo_vec	: The vector of computed tag poses.
[in]	cam	: Camera intrinsic parameters.
[out]	size	: Size of the frame.
[out]	color	: The desired color, if none the X-axis is red, the Y-axis green and the Z-axis blue.
[out]	thickness	: The thickness of the lines.

Examples: tutorial-apriltag-detector.cpp.

Definition at line 946 of file vpDetectorAprilTag.cpp.

◆ displayFrames() [2/2]

void vpDetectorAprilTag::displayFrames	(	const vpImage< vpRGBa > &	I,
		const std::vector< vpHomogeneousMatrix > &	cMo_vec,
		const vpCameraParameters &	cam,
		double	size,
		const vpColor &	color,
		unsigned int	thickness = `1`
	)		const

Display the tag frames on a vpRGBa image.

Parameters

[in]	I	: The image.
[in]	cMo_vec	: The vector of computed tag poses.
[in]	cam	: Camera intrinsic parameters.
[out]	size	: Size of the frame.
[out]	color	: The desired color, if none the X-axis is red, the Y-axis green and the Z-axis blue.
[out]	thickness	: The thickness of the lines.

Definition at line 962 of file vpDetectorAprilTag.cpp.

◆ displayTags() [1/2]

void vpDetectorAprilTag::displayTags	(	const vpImage< unsigned char > &	I,
		const std::vector< std::vector< vpImagePoint > > &	tagsCorners,
		const vpColor &	color = `vpColor::none`,
		unsigned int	thickness = `1`
	)		const

Display the tag contours on a grayscale image.

Parameters

[in]	I	: The image.
[in]	tagsCorners	: The vector of tag contours.
[out]	color	: The desired color, if none RGBY colors are used.
[out]	thickness	: The thickness of the lines.

Examples: tutorial-apriltag-detector.cpp.

Definition at line 976 of file vpDetectorAprilTag.cpp.

◆ displayTags() [2/2]

void vpDetectorAprilTag::displayTags	(	const vpImage< vpRGBa > &	I,
		const std::vector< std::vector< vpImagePoint > > &	tagsCorners,
		const vpColor &	color = `vpColor::none`,
		unsigned int	thickness = `1`
	)		const

Display the tag contours on a vpRGBa image.

Parameters

[in]	I	: The image.
[in]	tagsCorners	: The vector of tag contours.
[out]	color	: The desired color, if none RGBY colors are used.
[out]	thickness	: The thickness of the lines.

Definition at line 990 of file vpDetectorAprilTag.cpp.

◆ getBBox()

vpRect vpDetectorBase::getBBox ( size_t i ) const

inherited

Return the bounding box of the ith object.

Examples: tutorial-apriltag-detector-live-T265-realsense.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 93 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.

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, servoBiclopsPoint2DArtVelocity.cpp, servoPololuPtuPoint2DJointVelocity.cpp, and tutorial-flir-ptu-ibvs.cpp.

Definition at line 79 of file vpDetectorBase.cpp.

References vpDetectorBase::m_polygon.

◆ getMessage() [1/2]

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

inlineinherited

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

Examples: catchAprilTag.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 98 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 65 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: catchAprilTag.cpp, mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.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, tutorial-flir-ptu-ibvs.cpp, tutorial-mb-generic-tracker-apriltag-rs2.cpp, and tutorial-mb-generic-tracker-apriltag-webcam.cpp.

Definition at line 108 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: catchAprilTag.cpp, mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector.cpp, tutorial-barcode-detector-live.cpp, and tutorial-barcode-detector.cpp.

Definition at line 113 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 51 of file vpDetectorBase.cpp.

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

◆ getPose()

bool vpDetectorAprilTag::getPose	(	size_t	tagIndex,
		double	tagSize,
		const vpCameraParameters &	cam,
		vpHomogeneousMatrix &	cMo,
		vpHomogeneousMatrix *	cMo2 = `nullptr`,
		double *	projError = `nullptr`,
		double *	projError2 = `nullptr`
	)

Get the pose of a tag depending on its size and camera parameters. This function is useful to get the pose of tags with different sizes, while detect(const vpImage<unsigned char> &, const double, const vpCameraParameters &, std::vector<vpHomogeneousMatrix> &) considers that all the tags have the same size.

Parameters

[in]	tagIndex	: Index of the tag. Value should be in range [0, nb tags-1] with nb_tags = getNbObjects(). Note that this index doesn't correspond to the tag id.
[in]	tagSize	: Tag size in meter corresponding to the external width of the pattern.
[in]	cam	: Camera intrinsic parameters.
[out]	cMo	: Pose of the tag.
[out]	cMo2	: Optional second pose of the tag.
[out]	projError	: Optional (sum of squared) projection errors in the normalized camera frame.
[out]	projError2	: Optional (sum of squared) projection errors for the 2nd solution in the normalized camera frame.

Returns: true if success, false otherwise.

The following code shows how to use this function:

vpCameraParameters cam;
vpDetectorAprilTag detector(vpDetectorAprilTag::TAG_36h11);
detector.detect(I);
for (size_t i = 0; i < detector.getNbObjects(); i++) {
  vpHomogeneousMatrix cMo;
  double tagSize = 0.1;
  detector.getPose(i, tagSize, cam, cMo);
}

See also: detect(const vpImage<unsigned char> &, double, const vpCameraParameters &, std::vector<vpHomogeneousMatrix> *, std::vector<vpHomogeneousMatrix> *, std::vector<double> *, std::vector<double> *)

Examples: catchAprilTag.cpp.

Definition at line 1027 of file vpDetectorAprilTag.cpp.

◆ getPoseEstimationMethod()

vpPoseEstimationMethod vpDetectorAprilTag::getPoseEstimationMethod ( ) const

inline

Return the pose estimation method.

Definition at line 295 of file vpDetectorAprilTag.h.

◆ getTagsCorners()

std::vector< std::vector< vpImagePoint > > vpDetectorAprilTag::getTagsCorners ( ) const

Return the corners coordinates for the detected tags.

See also: getTagsId(), getTagsPoints3D()

Examples: catchAprilTag.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, and tutorial-apriltag-detector.cpp.

Definition at line 1102 of file vpDetectorAprilTag.cpp.

References vpDetectorBase::m_polygon.

◆ getTagsId()

std::vector< int > vpDetectorAprilTag::getTagsId ( ) const

Return the decoded Apriltag id for each detection.

See also: getTagsCorners(), getTagsPoints3D()

Examples: catchAprilTag.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, and tutorial-apriltag-detector-live-rgbd-structure-core.cpp.

Definition at line 1109 of file vpDetectorAprilTag.cpp.

◆ getTagsPoints3D()

std::vector< std::vector< vpPoint > > vpDetectorAprilTag::getTagsPoints3D	(	const std::vector< int > &	tagsId,
		const std::map< int, double > &	tagsSize
	)		const

Return a vector that contains for each tag id the corresponding tag 3D corners coordinates in the tag frame.

Parameters

tagsId : A vector containing the id of each tag that is detected. It's size corresponds to the number of tags that are detected. This vector is returned by getTagsId().

tagsSize

: a map that contains as first element a tag id and as second elements its 3D size in meter. When first element of this map is -1, the second element corresponds to the default tag size.

std::map<int, double> tagsSize;
tagsSize[-1] = 0.05; // Default tag size in meter, used when detected tag id is not in this map
tagsSize[10] = 0.1;  // All tags with id 10 are 0.1 meter large
tagsSize[20] = 0.2;  // All tags with id 20 are 0.2 meter large

See also: getTagsCorners(), getTagsId()

Examples: catchAprilTag.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, and tutorial-apriltag-detector-live-rgbd-structure-core.cpp.

Definition at line 1051 of file vpDetectorAprilTag.cpp.

References vpException::fatalError.

◆ isZAlignedWithCameraAxis()

bool vpDetectorAprilTag::isZAlignedWithCameraAxis ( ) const

Indicate it z-axis of the tag frame is aligned with the camera frame or not.

Returns: When true, z-axis are aligned, false otherwise

Definition at line 1243 of file vpDetectorAprilTag.cpp.

◆ operator=()

vpDetectorAprilTag & vpDetectorAprilTag::operator= ( vpDetectorAprilTag o )

Definition at line 870 of file vpDetectorAprilTag.cpp.

References swap.

◆ setAprilTagDecodeSharpening()

void vpDetectorAprilTag::setAprilTagDecodeSharpening ( double decodeSharpening )

Definition at line 1111 of file vpDetectorAprilTag.cpp.

◆ setAprilTagFamily()

void vpDetectorAprilTag::setAprilTagFamily ( const vpAprilTagFamily & tagFamily )

Definition at line 1116 of file vpDetectorAprilTag.cpp.

References m_poseEstimationMethod.

◆ setAprilTagNbThreads()

void vpDetectorAprilTag::setAprilTagNbThreads ( int nThreads )

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

Parameters

nThreads : Number of thread.

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, tutorial-apriltag-detector.cpp, tutorial-mb-generic-tracker-apriltag-rs2.cpp, and tutorial-mb-generic-tracker-apriltag-webcam.cpp.

Definition at line 1146 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.

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-pbvs.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, tutorial-apriltag-detector.cpp, and tutorial-flir-ptu-ibvs.cpp.

Definition at line 1158 of file vpDetectorAprilTag.cpp.

References m_poseEstimationMethod.

◆ setAprilTagQuadDecimate()

void vpDetectorAprilTag::setAprilTagQuadDecimate ( 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.

Examples: catchAprilTag.cpp, mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, perfApriltagDetection.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, tutorial-apriltag-detector.cpp, tutorial-flir-ptu-ibvs.cpp, tutorial-mb-generic-tracker-apriltag-rs2.cpp, and tutorial-mb-generic-tracker-apriltag-webcam.cpp.

Definition at line 1176 of file vpDetectorAprilTag.cpp.

◆ setAprilTagQuadSigma()

void vpDetectorAprilTag::setAprilTagQuadSigma ( 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 1190 of file vpDetectorAprilTag.cpp.

◆ setAprilTagRefineEdges()

void vpDetectorAprilTag::setAprilTagRefineEdges ( 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 parameter.

Definition at line 1216 of file vpDetectorAprilTag.cpp.

◆ setDisplayTag()

void vpDetectorAprilTag::setDisplayTag	(	bool	display,
		const vpColor &	color = `vpColor::none`,
		unsigned int	thickness = `2`
	)

inline

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

Examples: mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, tutorial-apriltag-detector.cpp, and tutorial-flir-ptu-ibvs.cpp.

Definition at line 316 of file vpDetectorAprilTag.h.

◆ setTimeout()

void vpDetectorBase::setTimeout ( unsigned long timeout_ms )

inlineinherited

Set detector timeout in milli-seconds. When set to 0, there is no timeout.

Definition at line 123 of file vpDetectorBase.h.

Referenced by vpDetectorDataMatrixCode::vpDetectorDataMatrixCode().

◆ setZAlignedWithCameraAxis()

void vpDetectorAprilTag::setZAlignedWithCameraAxis ( bool zAlignedWithCameraFrame )

Modify the resulting tag pose returned by getPose() or detect(const vpImage<unsigned char> &, double, const vpCameraParameters &, std::vector<vpHomogeneousMatrix> &, std::vector<vpHomogeneousMatrix> *, std::vector<double> *, std::vector<double> *) in order to get a pose where z-axis is aligned when the camera plane is parallel to the tag.

Tag 36h11_00000 with location of the 4 corners and tag frame

Parameters

zAlignedWithCameraFrame : When set to true, estimated tag pose has a z-axis aligned with the camera frame.

Examples: tutorial-apriltag-detector-live-T265-realsense.cpp, tutorial-apriltag-detector-live-rgbd-realsense.cpp, tutorial-apriltag-detector-live-rgbd-structure-core.cpp, tutorial-apriltag-detector-live.cpp, and tutorial-apriltag-detector.cpp.

Definition at line 1234 of file vpDetectorAprilTag.cpp.

Friends And Related Function Documentation

◆ swap

void swap	(	vpDetectorAprilTag &	o1,
		vpDetectorAprilTag &	o2
	)

friend

Definition at line 323 of file vpDetectorAprilTag.h.

Referenced by operator=().

Member Data Documentation

◆ m_displayTag

bool vpDetectorAprilTag::m_displayTag

protected

Definition at line 342 of file vpDetectorAprilTag.h.

Referenced by detect().

◆ m_displayTagColor

vpColor vpDetectorAprilTag::m_displayTagColor

protected

Definition at line 343 of file vpDetectorAprilTag.h.

Referenced by detect().

◆ m_displayTagThickness

unsigned int vpDetectorAprilTag::m_displayTagThickness

protected

Definition at line 344 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 129 of file vpDetectorBase.h.

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

◆ m_nb_objects

size_t vpDetectorBase::m_nb_objects

protectedinherited

Number of detected objects.

Definition at line 130 of file vpDetectorBase.h.

Referenced by vpDetectorFace::detect(), detect(), and vpDetectorDataMatrixCode::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 128 of file vpDetectorBase.h.

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

◆ m_poseEstimationMethod

vpPoseEstimationMethod vpDetectorAprilTag::m_poseEstimationMethod

protected

Definition at line 345 of file vpDetectorAprilTag.h.

Referenced by setAprilTagFamily(), and setAprilTagPoseEstimationMethod().

◆ m_tagFamily

vpAprilTagFamily vpDetectorAprilTag::m_tagFamily

protected

Definition at line 346 of file vpDetectorAprilTag.h.

◆ m_timeout_ms

unsigned long vpDetectorBase::m_timeout_ms

protectedinherited

Detection timeout.

Definition at line 131 of file vpDetectorBase.h.

Referenced by vpDetectorDataMatrixCode::detect().

Public Types

Public Member Functions

Protected Attributes

Friends

Inherited functionalities from vpDetectorBase

Detailed Description

Member Enumeration Documentation

◆ vpAprilTagFamily

◆ vpPoseEstimationMethod

Constructor & Destructor Documentation

◆ vpDetectorAprilTag() [1/2]

◆ vpDetectorAprilTag() [2/2]

◆ ~vpDetectorAprilTag()

Member Function Documentation

◆ detect() [1/2]

◆ detect() [2/2]

◆ displayFrames() [1/2]

◆ displayFrames() [2/2]

◆ displayTags() [1/2]

◆ displayTags() [2/2]

◆ getBBox()

◆ getCog()

◆ getMessage() [1/2]

◆ getMessage() [2/2]

◆ getNbObjects()

◆ getPolygon() [1/2]

◆ getPolygon() [2/2]

◆ getPose()

◆ getPoseEstimationMethod()

◆ getTagsCorners()

◆ getTagsId()

◆ getTagsPoints3D()

◆ isZAlignedWithCameraAxis()

◆ operator=()

◆ setAprilTagDecodeSharpening()

◆ setAprilTagFamily()

◆ setAprilTagNbThreads()

◆ setAprilTagPoseEstimationMethod()

◆ setAprilTagQuadDecimate()

◆ setAprilTagQuadSigma()

◆ setAprilTagRefineEdges()

◆ setDisplayTag()

◆ setTimeout()

◆ setZAlignedWithCameraAxis()

Friends And Related Function Documentation

◆ swap

Member Data Documentation

◆ m_displayTag

◆ m_displayTagColor

◆ m_displayTagThickness

◆ m_message

◆ m_nb_objects

◆ m_polygon

◆ m_poseEstimationMethod

◆ m_tagFamily

◆ m_timeout_ms