1 /*M/////////////////////////////////////////////////////////////////////////////////////// 2 // 3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING. 4 // 5 // By downloading, copying, installing or using the software you agree to this license. 6 // If you do not agree to this license, do not download, install, 7 // copy or use the software. 8 // 9 // 10 // License Agreement 11 // For Open Source Computer Vision Library 12 // 13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved. 14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved. 15 // Copyright (C) 2013, OpenCV Foundation, all rights reserved. 16 // Third party copyrights are property of their respective owners. 17 // 18 // Redistribution and use in source and binary forms, with or without modification, 19 // are permitted provided that the following conditions are met: 20 // 21 // * Redistribution's of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // * Redistribution's in binary form must reproduce the above copyright notice, 25 // this list of conditions and the following disclaimer in the documentation 26 // and/or other materials provided with the distribution. 27 // 28 // * The name of the copyright holders may not be used to endorse or promote products 29 // derived from this software without specific prior written permission. 30 // 31 // This software is provided by the copyright holders and contributors "as is" and 32 // any express or implied warranties, including, but not limited to, the implied 33 // warranties of merchantability and fitness for a particular purpose are disclaimed. 34 // In no event shall the Intel Corporation or contributors be liable for any direct, 35 // indirect, incidental, special, exemplary, or consequential damages 36 // (including, but not limited to, procurement of substitute goods or services; 37 // loss of use, data, or profits; or business interruption) however caused 38 // and on any theory of liability, whether in contract, strict liability, 39 // or tort (including negligence or otherwise) arising in any way out of 40 // the use of this software, even if advised of the possibility of such damage. 41 // 42 //M*/ 43 44 #ifndef __OPENCV_SHAPE_SHAPE_DISTANCE_HPP__ 45 #define __OPENCV_SHAPE_SHAPE_DISTANCE_HPP__ 46 #include "opencv2/core.hpp" 47 #include "opencv2/shape/hist_cost.hpp" 48 #include "opencv2/shape/shape_transformer.hpp" 49 50 namespace cv 51 { 52 53 //! @addtogroup shape 54 //! @{ 55 56 /** @brief Abstract base class for shape distance algorithms. 57 */ 58 class CV_EXPORTS_W ShapeDistanceExtractor : public Algorithm 59 { 60 public: 61 /** @brief Compute the shape distance between two shapes defined by its contours. 62 63 @param contour1 Contour defining first shape. 64 @param contour2 Contour defining second shape. 65 */ 66 CV_WRAP virtual float computeDistance(InputArray contour1, InputArray contour2) = 0; 67 }; 68 69 /***********************************************************************************/ 70 /***********************************************************************************/ 71 /***********************************************************************************/ 72 /** @brief Implementation of the Shape Context descriptor and matching algorithm 73 74 proposed by Belongie et al. in "Shape Matching and Object Recognition Using Shape Contexts" (PAMI 75 2002). This implementation is packaged in a generic scheme, in order to allow you the 76 implementation of the common variations of the original pipeline. 77 */ 78 class CV_EXPORTS_W ShapeContextDistanceExtractor : public ShapeDistanceExtractor 79 { 80 public: 81 /** @brief Establish the number of angular bins for the Shape Context Descriptor used in the shape matching 82 pipeline. 83 84 @param nAngularBins The number of angular bins in the shape context descriptor. 85 */ 86 CV_WRAP virtual void setAngularBins(int nAngularBins) = 0; 87 CV_WRAP virtual int getAngularBins() const = 0; 88 89 /** @brief Establish the number of radial bins for the Shape Context Descriptor used in the shape matching 90 pipeline. 91 92 @param nRadialBins The number of radial bins in the shape context descriptor. 93 */ 94 CV_WRAP virtual void setRadialBins(int nRadialBins) = 0; 95 CV_WRAP virtual int getRadialBins() const = 0; 96 97 /** @brief Set the inner radius of the shape context descriptor. 98 99 @param innerRadius The value of the inner radius. 100 */ 101 CV_WRAP virtual void setInnerRadius(float innerRadius) = 0; 102 CV_WRAP virtual float getInnerRadius() const = 0; 103 104 /** @brief Set the outer radius of the shape context descriptor. 105 106 @param outerRadius The value of the outer radius. 107 */ 108 CV_WRAP virtual void setOuterRadius(float outerRadius) = 0; 109 CV_WRAP virtual float getOuterRadius() const = 0; 110 111 CV_WRAP virtual void setRotationInvariant(bool rotationInvariant) = 0; 112 CV_WRAP virtual bool getRotationInvariant() const = 0; 113 114 /** @brief Set the weight of the shape context distance in the final value of the shape distance. The shape 115 context distance between two shapes is defined as the symmetric sum of shape context matching costs 116 over best matching points. The final value of the shape distance is a user-defined linear 117 combination of the shape context distance, an image appearance distance, and a bending energy. 118 119 @param shapeContextWeight The weight of the shape context distance in the final distance value. 120 */ 121 CV_WRAP virtual void setShapeContextWeight(float shapeContextWeight) = 0; 122 CV_WRAP virtual float getShapeContextWeight() const = 0; 123 124 /** @brief Set the weight of the Image Appearance cost in the final value of the shape distance. The image 125 appearance cost is defined as the sum of squared brightness differences in Gaussian windows around 126 corresponding image points. The final value of the shape distance is a user-defined linear 127 combination of the shape context distance, an image appearance distance, and a bending energy. If 128 this value is set to a number different from 0, is mandatory to set the images that correspond to 129 each shape. 130 131 @param imageAppearanceWeight The weight of the appearance cost in the final distance value. 132 */ 133 CV_WRAP virtual void setImageAppearanceWeight(float imageAppearanceWeight) = 0; 134 CV_WRAP virtual float getImageAppearanceWeight() const = 0; 135 136 /** @brief Set the weight of the Bending Energy in the final value of the shape distance. The bending energy 137 definition depends on what transformation is being used to align the shapes. The final value of the 138 shape distance is a user-defined linear combination of the shape context distance, an image 139 appearance distance, and a bending energy. 140 141 @param bendingEnergyWeight The weight of the Bending Energy in the final distance value. 142 */ 143 CV_WRAP virtual void setBendingEnergyWeight(float bendingEnergyWeight) = 0; 144 CV_WRAP virtual float getBendingEnergyWeight() const = 0; 145 146 /** @brief Set the images that correspond to each shape. This images are used in the calculation of the Image 147 Appearance cost. 148 149 @param image1 Image corresponding to the shape defined by contours1. 150 @param image2 Image corresponding to the shape defined by contours2. 151 */ 152 CV_WRAP virtual void setImages(InputArray image1, InputArray image2) = 0; 153 CV_WRAP virtual void getImages(OutputArray image1, OutputArray image2) const = 0; 154 155 CV_WRAP virtual void setIterations(int iterations) = 0; 156 CV_WRAP virtual int getIterations() const = 0; 157 158 /** @brief Set the algorithm used for building the shape context descriptor cost matrix. 159 160 @param comparer Smart pointer to a HistogramCostExtractor, an algorithm that defines the cost 161 matrix between descriptors. 162 */ 163 CV_WRAP virtual void setCostExtractor(Ptr<HistogramCostExtractor> comparer) = 0; 164 CV_WRAP virtual Ptr<HistogramCostExtractor> getCostExtractor() const = 0; 165 166 /** @brief Set the value of the standard deviation for the Gaussian window for the image appearance cost. 167 168 @param sigma Standard Deviation. 169 */ 170 CV_WRAP virtual void setStdDev(float sigma) = 0; 171 CV_WRAP virtual float getStdDev() const = 0; 172 173 /** @brief Set the algorithm used for aligning the shapes. 174 175 @param transformer Smart pointer to a ShapeTransformer, an algorithm that defines the aligning 176 transformation. 177 */ 178 CV_WRAP virtual void setTransformAlgorithm(Ptr<ShapeTransformer> transformer) = 0; 179 CV_WRAP virtual Ptr<ShapeTransformer> getTransformAlgorithm() const = 0; 180 }; 181 182 /* Complete constructor */ 183 CV_EXPORTS_W Ptr<ShapeContextDistanceExtractor> 184 createShapeContextDistanceExtractor(int nAngularBins=12, int nRadialBins=4, 185 float innerRadius=0.2f, float outerRadius=2, int iterations=3, 186 const Ptr<HistogramCostExtractor> &comparer = createChiHistogramCostExtractor(), 187 const Ptr<ShapeTransformer> &transformer = createThinPlateSplineShapeTransformer()); 188 189 /***********************************************************************************/ 190 /***********************************************************************************/ 191 /***********************************************************************************/ 192 /** @brief A simple Hausdorff distance measure between shapes defined by contours 193 194 according to the paper "Comparing Images using the Hausdorff distance." by D.P. Huttenlocher, G.A. 195 Klanderman, and W.J. Rucklidge. (PAMI 1993). : 196 */ 197 class CV_EXPORTS_W HausdorffDistanceExtractor : public ShapeDistanceExtractor 198 { 199 public: 200 /** @brief Set the norm used to compute the Hausdorff value between two shapes. It can be L1 or L2 norm. 201 202 @param distanceFlag Flag indicating which norm is used to compute the Hausdorff distance 203 (NORM_L1, NORM_L2). 204 */ 205 CV_WRAP virtual void setDistanceFlag(int distanceFlag) = 0; 206 CV_WRAP virtual int getDistanceFlag() const = 0; 207 208 /** @brief This method sets the rank proportion (or fractional value) that establish the Kth ranked value of 209 the partial Hausdorff distance. Experimentally had been shown that 0.6 is a good value to compare 210 shapes. 211 212 @param rankProportion fractional value (between 0 and 1). 213 */ 214 CV_WRAP virtual void setRankProportion(float rankProportion) = 0; 215 CV_WRAP virtual float getRankProportion() const = 0; 216 }; 217 218 /* Constructor */ 219 CV_EXPORTS_W Ptr<HausdorffDistanceExtractor> createHausdorffDistanceExtractor(int distanceFlag=cv::NORM_L2, float rankProp=0.6f); 220 221 //! @} 222 223 } // cv 224 #endif 225