1 /**************************************************************************** 2 * 3 * ViSP, open source Visual Servoing Platform software. 4 * Copyright (C) 2005 - 2019 by Inria. All rights reserved. 5 * 6 * This software is free software; you can redistribute it and/or modify 7 * it under the terms of the GNU General Public License as published by 8 * the Free Software Foundation; either version 2 of the License, or 9 * (at your option) any later version. 10 * See the file LICENSE.txt at the root directory of this source 11 * distribution for additional information about the GNU GPL. 12 * 13 * For using ViSP with software that can not be combined with the GNU 14 * GPL, please contact Inria about acquiring a ViSP Professional 15 * Edition License. 16 * 17 * See http://visp.inria.fr for more information. 18 * 19 * This software was developed at: 20 * Inria Rennes - Bretagne Atlantique 21 * Campus Universitaire de Beaulieu 22 * 35042 Rennes Cedex 23 * France 24 * 25 * If you have questions regarding the use of this file, please contact 26 * Inria at visp@inria.fr 27 * 28 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE 29 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 30 * 31 * Description: 32 * Visual feature circle. 33 * 34 * Authors: 35 * Eric Marchand 36 * 37 *****************************************************************************/ 38 39 /*! 40 \file vpCircle.h 41 \brief class that defines what is a circle 42 */ 43 44 #ifndef vpCircle_hh 45 #define vpCircle_hh 46 47 #include <math.h> 48 #include <visp3/core/vpDebug.h> 49 #include <visp3/core/vpForwardProjection.h> 50 #include <visp3/core/vpHomogeneousMatrix.h> 51 #include <visp3/core/vpMath.h> 52 53 /*! 54 \class vpCircle 55 \ingroup group_core_geometry 56 \brief Class that defines a 3D circle in the object frame and allows forward projection of a 3D circle in the 57 camera frame and in the 2D image plane by perspective projection. 58 All the parameters must be set in meter. 59 60 Note that a 3D circle is defined from the intersection between a 3D plane and a 3D sphere. 61 62 A 3D circle has the followings parameters: 63 - **in the object frame**: the parameters oA, oB, oC corresponding to the 3D plane with equation 64 oA*(x-oX)+oB*(y-oY)+oC*(z-oZ)=0 passing through the 3D sphere center and the 65 3D coordinates oX, oY, oZ of the center and radius R of the 3D sphere. These 66 parameters registered in vpForwardProjection::oP internal 7-dim vector are set using the constructors 67 vpCircle(double oA, double oB, double oC, double oX, double oY, double oZ, double R), 68 vpCircle(const vpColVector &oP) or the fonctions 69 setWorldCoordinates(double oA, double oB, double oC, double oX, double oY, double oZ, double R) 70 and setWorldCoordinates(const vpColVector &oP). To get theses parameters use get_oP(). 71 72 - **in the camera frame**: the parameters cA, cB, cC corresponding to the 3D plane cAx+cBy+cCz+D=0 73 and the coordinates cX, cY, cZ of the center and radius R of the 3D sphere. These 74 parameters registered in vpTracker::cP internal 7-dim vector are computed using 75 changeFrame(const vpHomogeneousMatrix &cMo, vpColVector &cP) const or changeFrame(const vpHomogeneousMatrix &cMo). 76 These parameters could be retrieved using getA(), getB(), getC(), getX(), getY(), getZ() and getR(). 77 To get theses parameters use get_cP(). 78 79 - **in the image plane**: here we consider the parameters of the ellipse corresponding 80 to the perspective projection of the 3D circle. The parameters are the ellipse centroid (x, y) 81 and n20, n11, n02 which are the second order centered moments of 82 the ellipse normalized by its area (i.e., such that \f$n_{ij} = \mu_{ij}/a\f$ where 83 \f$\mu_{ij}\f$ are the centered moments and a the area). 84 These parameters are registered in vpTracker::p internal 5-dim vector 85 and computed using projection() and 86 projection(const vpColVector &cP, vpColVector &p) const. They could be retrieved using get_x(), get_y(), get_n20(), 87 get_n11() and get_n02(). They correspond to 2D normalized circle parameters with values expressed in meters. 88 To get theses parameters use get_p(). 89 90 */ 91 class VISP_EXPORT vpCircle : public vpForwardProjection 92 { 93 public: 94 vpCircle(); 95 explicit vpCircle(const vpColVector &oP); 96 vpCircle(double oA, double oB, double oC, double oX, double oY, double oZ, double R); 97 virtual ~vpCircle(); 98 99 void changeFrame(const vpHomogeneousMatrix &cMo, vpColVector &cP) const; 100 void changeFrame(const vpHomogeneousMatrix &cMo); 101 102 void display(const vpImage<unsigned char> &I, const vpCameraParameters &cam, const vpColor &color = vpColor::green, 103 unsigned int thickness = 1); 104 void display(const vpImage<unsigned char> &I, const vpHomogeneousMatrix &cMo, const vpCameraParameters &cam, 105 const vpColor &color = vpColor::green, unsigned int thickness = 1); 106 vpCircle *duplicate() const; 107 get_x()108 double get_x() const { return p[0]; } get_y()109 double get_y() const { return p[1]; } 110 get_n20()111 double get_n20() const { return p[2]; } get_n11()112 double get_n11() const { return p[3]; } get_n02()113 double get_n02() const { return p[4]; } 114 getA()115 double getA() const { return cP[0]; } getB()116 double getB() const { return cP[1]; } getC()117 double getC() const { return cP[2]; } 118 getX()119 double getX() const { return cP[3]; } getY()120 double getY() const { return cP[4]; } getZ()121 double getZ() const { return cP[5]; } 122 getR()123 double getR() const { return cP[6]; } 124 125 void projection(); 126 void projection(const vpColVector &cP, vpColVector &p) const; 127 128 void setWorldCoordinates(const vpColVector &oP); 129 void setWorldCoordinates(double oA, double oB, double oC, double oX, double oY, double oZ, double R); 130 131 //################### 132 // Static Functions 133 //################### 134 static void computeIntersectionPoint(const vpCircle &circle, const vpCameraParameters &cam, const double &rho, 135 const double &theta, double &i, double &j); 136 137 protected: 138 void init(); 139 140 public: 141 #if defined(VISP_BUILD_DEPRECATED_FUNCTIONS) 142 /*! 143 @name Deprecated functions 144 */ 145 //@{ 146 /*! 147 * \deprecated You should rather use get_n20(). 148 * This function is incorrectly named and is confusing since it 149 * returns second order centered moments of the ellipse normalized 150 * by its area that corresponds to \f$n_20 = mu_20/a\f$. 151 */ get_mu20()152 vp_deprecated double get_mu20() const { return p[2]; } 153 /*! 154 * \deprecated You should rather use get_n11(). 155 * This function is incorrectly named and is confusing since it 156 * returns second order centered moments of the ellipse normalized 157 * by its area that corresponds to \f$n_11 = mu_11/a\f$. 158 */ get_mu11()159 vp_deprecated double get_mu11() const { return p[3]; } 160 /*! 161 * \deprecated You should rather use get_n02(). 162 * This function is incorrectly named and is confusing since it 163 * returns second order centered moments of the ellipse normalized 164 * by its area that corresponds to \f$n_02 = mu_02/a\f$. 165 */ get_mu02()166 vp_deprecated double get_mu02() const { return p[4]; } 167 //@} 168 #endif 169 }; 170 171 #endif 172