shape_distance.hpp

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
00016 // Third party copyrights are property of their respective owners.
00017 //
00018 // Redistribution and use in source and binary forms, with or without modification,
00019 // are permitted provided that the following conditions are met:
00020 //
00021 //   * Redistribution's of source code must retain the above copyright notice,
00022 //     this list of conditions and the following disclaimer.
00023 //
00024 //   * Redistribution's in binary form must reproduce the above copyright notice,
00025 //     this list of conditions and the following disclaimer in the documentation
00026 //     and/or other materials provided with the distribution.
00027 //
00028 //   * The name of the copyright holders may not be used to endorse or promote products
00029 //     derived from this software without specific prior written permission.
00030 //
00031 // This software is provided by the copyright holders and contributors "as is" and
00032 // any express or implied warranties, including, but not limited to, the implied
00033 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00034 // In no event shall the Intel Corporation or contributors be liable for any direct,
00035 // indirect, incidental, special, exemplary, or consequential damages
00036 // (including, but not limited to, procurement of substitute goods or services;
00037 // loss of use, data, or profits; or business interruption) however caused
00038 // and on any theory of liability, whether in contract, strict liability,
00039 // or tort (including negligence or otherwise) arising in any way out of
00040 // the use of this software, even if advised of the possibility of such damage.
00041 //
00042 //M*/
00043 
00044 #ifndef __OPENCV_SHAPE_SHAPE_DISTANCE_HPP__
00045 #define __OPENCV_SHAPE_SHAPE_DISTANCE_HPP__
00046 #include "opencv2/core.hpp"
00047 #include "opencv2/shape/hist_cost.hpp"
00048 #include "opencv2/shape/shape_transformer.hpp"
00049 
00050 namespace cv
00051 {
00052 
00053 //! @addtogroup shape
00054 //! @{
00055 
00056 /** @brief Abstract base class for shape distance algorithms.
00057  */
00058 class CV_EXPORTS_W ShapeDistanceExtractor : public Algorithm
00059 {
00060 public:
00061     /** @brief Compute the shape distance between two shapes defined by its contours.
00062 
00063     @param contour1 Contour defining first shape.
00064     @param contour2 Contour defining second shape.
00065      */
00066     CV_WRAP virtual float computeDistance(InputArray contour1, InputArray contour2) = 0;
00067 };
00068 
00069 /***********************************************************************************/
00070 /***********************************************************************************/
00071 /***********************************************************************************/
00072 /** @brief Implementation of the Shape Context descriptor and matching algorithm
00073 
00074 proposed by Belongie et al. in "Shape Matching and Object Recognition Using Shape Contexts" (PAMI
00075 2002). This implementation is packaged in a generic scheme, in order to allow you the
00076 implementation of the common variations of the original pipeline.
00077 */
00078 class CV_EXPORTS_W ShapeContextDistanceExtractor : public ShapeDistanceExtractor
00079 {
00080 public:
00081     /** @brief Establish the number of angular bins for the Shape Context Descriptor used in the shape matching
00082     pipeline.
00083 
00084     @param nAngularBins The number of angular bins in the shape context descriptor.
00085      */
00086     CV_WRAP virtual void setAngularBins(int nAngularBins) = 0;
00087     CV_WRAP virtual int getAngularBins() const = 0;
00088 
00089     /** @brief Establish the number of radial bins for the Shape Context Descriptor used in the shape matching
00090     pipeline.
00091 
00092     @param nRadialBins The number of radial bins in the shape context descriptor.
00093      */
00094     CV_WRAP virtual void setRadialBins(int nRadialBins) = 0;
00095     CV_WRAP virtual int getRadialBins() const = 0;
00096 
00097     /** @brief Set the inner radius of the shape context descriptor.
00098 
00099     @param innerRadius The value of the inner radius.
00100      */
00101     CV_WRAP virtual void setInnerRadius(float innerRadius) = 0;
00102     CV_WRAP virtual float getInnerRadius() const = 0;
00103 
00104     /** @brief Set the outer radius of the shape context descriptor.
00105 
00106     @param outerRadius The value of the outer radius.
00107      */
00108     CV_WRAP virtual void setOuterRadius(float outerRadius) = 0;
00109     CV_WRAP virtual float getOuterRadius() const = 0;
00110 
00111     CV_WRAP virtual void setRotationInvariant(bool rotationInvariant) = 0;
00112     CV_WRAP virtual bool getRotationInvariant() const = 0;
00113 
00114     /** @brief Set the weight of the shape context distance in the final value of the shape distance. The shape
00115     context distance between two shapes is defined as the symmetric sum of shape context matching costs
00116     over best matching points. The final value of the shape distance is a user-defined linear
00117     combination of the shape context distance, an image appearance distance, and a bending energy.
00118 
00119     @param shapeContextWeight The weight of the shape context distance in the final distance value.
00120      */
00121     CV_WRAP virtual void setShapeContextWeight(float shapeContextWeight) = 0;
00122     CV_WRAP virtual float getShapeContextWeight() const = 0;
00123 
00124     /** @brief Set the weight of the Image Appearance cost in the final value of the shape distance. The image
00125     appearance cost is defined as the sum of squared brightness differences in Gaussian windows around
00126     corresponding image points. The final value of the shape distance is a user-defined linear
00127     combination of the shape context distance, an image appearance distance, and a bending energy. If
00128     this value is set to a number different from 0, is mandatory to set the images that correspond to
00129     each shape.
00130 
00131     @param imageAppearanceWeight The weight of the appearance cost in the final distance value.
00132      */
00133     CV_WRAP virtual void setImageAppearanceWeight(float imageAppearanceWeight) = 0;
00134     CV_WRAP virtual float getImageAppearanceWeight() const = 0;
00135 
00136     /** @brief Set the weight of the Bending Energy in the final value of the shape distance. The bending energy
00137     definition depends on what transformation is being used to align the shapes. The final value of the
00138     shape distance is a user-defined linear combination of the shape context distance, an image
00139     appearance distance, and a bending energy.
00140 
00141     @param bendingEnergyWeight The weight of the Bending Energy in the final distance value.
00142      */
00143     CV_WRAP virtual void setBendingEnergyWeight(float bendingEnergyWeight) = 0;
00144     CV_WRAP virtual float getBendingEnergyWeight() const = 0;
00145 
00146     /** @brief Set the images that correspond to each shape. This images are used in the calculation of the Image
00147     Appearance cost.
00148 
00149     @param image1 Image corresponding to the shape defined by contours1.
00150     @param image2 Image corresponding to the shape defined by contours2.
00151      */
00152     CV_WRAP virtual void setImages(InputArray image1, InputArray image2) = 0;
00153     CV_WRAP virtual void getImages(OutputArray image1, OutputArray image2) const = 0;
00154 
00155     CV_WRAP virtual void setIterations(int iterations) = 0;
00156     CV_WRAP virtual int getIterations() const = 0;
00157 
00158     /** @brief Set the algorithm used for building the shape context descriptor cost matrix.
00159 
00160     @param comparer Smart pointer to a HistogramCostExtractor, an algorithm that defines the cost
00161     matrix between descriptors.
00162      */
00163     CV_WRAP virtual void setCostExtractor(Ptr<HistogramCostExtractor> comparer) = 0;
00164     CV_WRAP virtual Ptr<HistogramCostExtractor> getCostExtractor() const = 0;
00165 
00166     /** @brief Set the value of the standard deviation for the Gaussian window for the image appearance cost.
00167 
00168     @param sigma Standard Deviation.
00169      */
00170     CV_WRAP virtual void setStdDev(float sigma) = 0;
00171     CV_WRAP virtual float getStdDev() const = 0;
00172 
00173     /** @brief Set the algorithm used for aligning the shapes.
00174 
00175     @param transformer Smart pointer to a ShapeTransformer, an algorithm that defines the aligning
00176     transformation.
00177      */
00178     CV_WRAP virtual void setTransformAlgorithm(Ptr<ShapeTransformer> transformer) = 0;
00179     CV_WRAP virtual Ptr<ShapeTransformer> getTransformAlgorithm() const = 0;
00180 };
00181 
00182 /* Complete constructor */
00183 CV_EXPORTS_W Ptr<ShapeContextDistanceExtractor>
00184     createShapeContextDistanceExtractor(int nAngularBins=12, int nRadialBins=4,
00185                                         float innerRadius=0.2f, float outerRadius=2, int iterations=3,
00186                                         const Ptr<HistogramCostExtractor> &comparer = createChiHistogramCostExtractor(),
00187                                         const Ptr<ShapeTransformer> &transformer = createThinPlateSplineShapeTransformer());
00188 
00189 /***********************************************************************************/
00190 /***********************************************************************************/
00191 /***********************************************************************************/
00192 /** @brief A simple Hausdorff distance measure between shapes defined by contours
00193 
00194 according to the paper "Comparing Images using the Hausdorff distance." by D.P. Huttenlocher, G.A.
00195 Klanderman, and W.J. Rucklidge. (PAMI 1993). :
00196  */
00197 class CV_EXPORTS_W HausdorffDistanceExtractor : public ShapeDistanceExtractor
00198 {
00199 public:
00200     /** @brief Set the norm used to compute the Hausdorff value between two shapes. It can be L1 or L2 norm.
00201 
00202     @param distanceFlag Flag indicating which norm is used to compute the Hausdorff distance
00203     (NORM_L1, NORM_L2).
00204      */
00205     CV_WRAP virtual void setDistanceFlag(int distanceFlag) = 0;
00206     CV_WRAP virtual int getDistanceFlag() const = 0;
00207 
00208     /** @brief This method sets the rank proportion (or fractional value) that establish the Kth ranked value of
00209     the partial Hausdorff distance. Experimentally had been shown that 0.6 is a good value to compare
00210     shapes.
00211 
00212     @param rankProportion fractional value (between 0 and 1).
00213      */
00214     CV_WRAP virtual void setRankProportion(float rankProportion) = 0;
00215     CV_WRAP virtual float getRankProportion() const = 0;
00216 };
00217 
00218 /* Constructor */
00219 CV_EXPORTS_W Ptr<HausdorffDistanceExtractor> createHausdorffDistanceExtractor(int distanceFlag=cv::NORM_L2, float rankProp=0.6f);
00220 
00221 //! @}
00222 
00223 } // cv
00224 #endif
00225