vpDetectorAprilTag.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2025 by Inria. All rights reserved.
 *
 * This software is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file LICENSE.txt at the root directory of this source
 * distribution for additional information about the GNU GPL.
 *
 * For using ViSP with software that can not be combined with the GNU
 * GPL, please contact Inria about acquiring a ViSP Professional
 * Edition License.
 *
 * See https://visp.inria.fr for more information.
 *
 * This software was developed at:
 * Inria Rennes - Bretagne Atlantique
 * Campus Universitaire de Beaulieu
 * 35042 Rennes Cedex
 * France
 *
 * If you have questions regarding the use of this file, please contact
 * Inria at visp@inria.fr
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 *
 * Description:
 * Base class for AprilTag detection.
 */
#ifndef VP_DETECTOR_APRILTAG_H
#define VP_DETECTOR_APRILTAG_H
 
#include <map>
 
#include <visp3/core/vpConfig.h>
 
#ifdef VISP_HAVE_APRILTAG
#include <visp3/core/vpCameraParameters.h>
#include <visp3/core/vpColor.h>
#include <visp3/core/vpHomogeneousMatrix.h>
#include <visp3/core/vpImage.h>
#include <visp3/detection/vpDetectorBase.h>
 
BEGIN_VISP_NAMESPACE
class VISP_EXPORT vpDetectorAprilTag : public vpDetectorBase
{
public:
  enum vpAprilTagFamily
  {
    TAG_36h11,           
    TAG_36h10,           
    TAG_36ARTOOLKIT,     
    TAG_25h9,            
    TAG_25h7,            
    TAG_16h5,            
    TAG_CIRCLE21h7,      
    TAG_CIRCLE49h12,     
    TAG_CUSTOM48h12,     
    TAG_STANDARD41h12,   
    TAG_STANDARD52h13,   
    TAG_ARUCO_4x4_50,    
    TAG_ARUCO_4x4_100,   
    TAG_ARUCO_4x4_250,   
    TAG_ARUCO_4x4_1000,  
    TAG_ARUCO_5x5_50,    
    TAG_ARUCO_5x5_100,   
    TAG_ARUCO_5x5_250,   
    TAG_ARUCO_5x5_1000,  
    TAG_ARUCO_6x6_50,    
    TAG_ARUCO_6x6_100,   
    TAG_ARUCO_6x6_250,   
    TAG_ARUCO_6x6_1000,  
    TAG_ARUCO_7x7_50,  
    TAG_ARUCO_7x7_100,  
    TAG_ARUCO_7x7_250,  
    TAG_ARUCO_7x7_1000,  
    TAG_ARUCO_MIP_36h12  
  };
 
  enum vpPoseEstimationMethod
  {
    HOMOGRAPHY,                     
    HOMOGRAPHY_VIRTUAL_VS,          
    DEMENTHON_VIRTUAL_VS,           
    LAGRANGE_VIRTUAL_VS,            
    BEST_RESIDUAL_VIRTUAL_VS,       
    HOMOGRAPHY_ORTHOGONAL_ITERATION 
  };
 
  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;
 
  float getAprilTagDecisionMarginThreshold() const;
  int getAprilTagHammingDistanceThreshold() const;
  bool getPose(size_t tagIndex, double tagSize, const vpCameraParameters &cam, vpHomogeneousMatrix &cMo,
               vpHomogeneousMatrix *cMo2 = nullptr, double *projError = nullptr, double *projError2 = nullptr);

  inline vpPoseEstimationMethod getPoseEstimationMethod() const { return m_poseEstimationMethod; }
 
  bool getTagImage(vpImage<unsigned char> &I, int id);
  std::vector<std::vector<vpImagePoint> > getTagsCorners() const;
  std::vector<float> getTagsDecisionMargin() const;
  std::vector<int> getTagsHammingDistance() 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 setAprilTagDebugOption(bool flag);
  void setAprilTagDecisionMarginThreshold(float decisionMarginThreshold);
  void setAprilTagDecodeSharpening(double decodeSharpening);
  void setAprilTagFamily(const vpAprilTagFamily &tagFamily);
  void setAprilTagHammingDistanceThreshold(int hammingDistanceThreshold);
  void setAprilTagNbThreads(int nThreads);
  void setAprilTagPoseEstimationMethod(const vpPoseEstimationMethod &poseEstimationMethod);
  void setAprilTagQuadDecimate(float quadDecimate);
  void setAprilTagQuadSigma(float quadSigma);
  void setAprilTagRefineEdges(bool refineEdges);
 

  inline void setDisplayTag(bool display, const vpColor &color = vpColor::none, unsigned int thickness = 2)
  {
    m_displayTag = display;
    m_displayTagColor = color;
    m_displayTagThickness = thickness;
  }
 
  inline friend void swap(vpDetectorAprilTag &o1, vpDetectorAprilTag &o2)
  {
    using std::swap;
    swap(o1.m_impl, o2.m_impl);
  }
 
  void setZAlignedWithCameraAxis(bool zAlignedWithCameraFrame);
 
#if defined(VISP_BUILD_DEPRECATED_FUNCTIONS)
  VP_DEPRECATED void setAprilTagRefinePose(bool refinePose);
  VP_DEPRECATED void setAprilTagRefineDecode(bool refineDecode);
#endif
 
protected:
  bool m_displayTag;
  vpColor m_displayTagColor;
  unsigned int m_displayTagThickness;
  vpPoseEstimationMethod m_poseEstimationMethod;
  vpAprilTagFamily m_tagFamily;
 
private:
  vpCameraParameters m_defaultCam;
 
  // PIMPL idiom
  class Impl;
  Impl *m_impl;
};
 
inline std::ostream &operator<<(std::ostream &os, const vpDetectorAprilTag::vpPoseEstimationMethod &method)
{
  switch (method) {
  case vpDetectorAprilTag::HOMOGRAPHY:
    os << "HOMOGRAPHY";
    break;
 
  case vpDetectorAprilTag::HOMOGRAPHY_VIRTUAL_VS:
    os << "HOMOGRAPHY_VIRTUAL_VS";
    break;
 
  case vpDetectorAprilTag::DEMENTHON_VIRTUAL_VS:
    os << "DEMENTHON_VIRTUAL_VS";
    break;
 
  case vpDetectorAprilTag::LAGRANGE_VIRTUAL_VS:
    os << "LAGRANGE_VIRTUAL_VS";
    break;
 
  case vpDetectorAprilTag::BEST_RESIDUAL_VIRTUAL_VS:
    os << "BEST_RESIDUAL_VIRTUAL_VS";
    break;
 
  case vpDetectorAprilTag::HOMOGRAPHY_ORTHOGONAL_ITERATION:
    os << "HOMOGRAPHY_ORTHOGONAL_ITERATION";
    break;
 
  default:
    os << "ERROR_UNKNOWN_POSE_METHOD!";
    break;
  }
 
  return os;
}
 
inline std::ostream &operator<<(std::ostream &os, const vpDetectorAprilTag::vpAprilTagFamily &tagFamily)
{
  switch (tagFamily) {
  case vpDetectorAprilTag::TAG_36h11:
    os << "36h11";
    break;
 
  case vpDetectorAprilTag::TAG_36h10:
    os << "36h10";
    break;
 
  case vpDetectorAprilTag::TAG_36ARTOOLKIT:
    os << "36artoolkit";
    break;
 
  case vpDetectorAprilTag::TAG_25h9:
    os << "25h9";
    break;
 
  case vpDetectorAprilTag::TAG_25h7:
    os << "25h7";
    break;
 
  case vpDetectorAprilTag::TAG_16h5:
    os << "16h5";
    break;
 
  case vpDetectorAprilTag::TAG_CIRCLE21h7:
    os << "CIRCLE21h7";
    break;
 
  case vpDetectorAprilTag::TAG_CIRCLE49h12:
    os << "CIRCLE49h12";
    break;
 
  case vpDetectorAprilTag::TAG_CUSTOM48h12:
    os << "CUSTOM48h12";
    break;
 
  case vpDetectorAprilTag::TAG_STANDARD52h13:
    os << "STANDARD52h13";
    break;
 
  case vpDetectorAprilTag::TAG_STANDARD41h12:
    os << "STANDARD41h12";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_4x4_50:
    os << "TAG_ARUCO_4x4_50";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_4x4_100:
    os << "TAG_ARUCO_4x4_100";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_4x4_250:
    os << "TAG_ARUCO_4x4_250";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_4x4_1000:
    os << "TAG_ARUCO_4x4_1000";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_5x5_50:
    os << "TAG_ARUCO_5x5_50";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_5x5_100:
    os << "TAG_ARUCO_5x5_100";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_5x5_250:
    os << "TAG_ARUCO_5x5_250";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_5x5_1000:
    os << "TAG_ARUCO_5x5_1000";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_6x6_50:
    os << "TAG_ARUCO_6x6_50";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_6x6_100:
    os << "TAG_ARUCO_6x6_100";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_6x6_250:
    os << "TAG_ARUCO_6x6_250";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_6x6_1000:
    os << "TAG_ARUCO_6x6_1000";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_7x7_50:
    os << "TAG_ARUCO_7x7_50";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_7x7_100:
    os << "TAG_ARUCO_7x7_100";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_7x7_250:
    os << "TAG_ARUCO_7x7_250";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_7x7_1000:
    os << "TAG_ARUCO_7x7_1000";
    break;
 
  case vpDetectorAprilTag::TAG_ARUCO_MIP_36h12:
    os << "TAG_ARUCO_MIP_36h12";
    break;
 
  default:
    os << "UNKNOWN";
    break;
  }
 
  return os;
}
 
END_VISP_NAMESPACE
 
#endif
#endif