Shape Distance and Common Interfaces

Shape Distance algorithms in OpenCV are derivated from a common interface that allows you to switch between them in a practical way for solving the same problem with different methods. Thus, all objects that implement shape distance measures inherit the ShapeDistanceExtractor interface.

ShapeDistanceExtractor

class ShapeDistanceExtractor : public Algorithm

Abstract base class for shape distance algorithms.

class CV_EXPORTS_W ShapeDistanceExtractor : public Algorithm
{
public:
    CV_WRAP virtual float computeDistance(InputArray contour1, InputArray contour2) = 0;
};

ShapeDistanceExtractor::computeDistance

Compute the shape distance between two shapes defined by its contours.

C++: float ShapeDistanceExtractor::computeDistance(InputArray contour1, InputArray contour2)

Parameters:

• contour1 – Contour defining first shape.
• contour2 – Contour defining second shape.

ShapeContextDistanceExtractor

class ShapeContextDistanceExtractor : public ShapeDistanceExtractor

Implementation of the Shape Context descriptor and matching algorithm proposed by Belongie et al. in “Shape Matching and Object Recognition Using Shape Contexts” (PAMI 2002). This implementation is packaged in a generic scheme, in order to allow you the implementation of the common variations of the original pipeline.

class CV_EXPORTS_W ShapeContextDistanceExtractor : public ShapeDistanceExtractor
{
public:
    CV_WRAP virtual void setAngularBins(int nAngularBins) = 0;
    CV_WRAP virtual int getAngularBins() const = 0;

    CV_WRAP virtual void setRadialBins(int nRadialBins) = 0;
    CV_WRAP virtual int getRadialBins() const = 0;

    CV_WRAP virtual void setInnerRadius(float innerRadius) = 0;
    CV_WRAP virtual float getInnerRadius() const = 0;

    CV_WRAP virtual void setOuterRadius(float outerRadius) = 0;
    CV_WRAP virtual float getOuterRadius() const = 0;

    CV_WRAP virtual void setRotationInvariant(bool rotationInvariant) = 0;
    CV_WRAP virtual bool getRotationInvariant() const = 0;

    CV_WRAP virtual void setShapeContextWeight(float shapeContextWeight) = 0;
    CV_WRAP virtual float getShapeContextWeight() const = 0;

    CV_WRAP virtual void setImageAppearanceWeight(float imageAppearanceWeight) = 0;
    CV_WRAP virtual float getImageAppearanceWeight() const = 0;

    CV_WRAP virtual void setBendingEnergyWeight(float bendingEnergyWeight) = 0;
    CV_WRAP virtual float getBendingEnergyWeight() const = 0;

    CV_WRAP virtual void setImages(InputArray image1, InputArray image2) = 0;
    CV_WRAP virtual void getImages(OutputArray image1, OutputArray image2) const = 0;

    CV_WRAP virtual void setIterations(int iterations) = 0;
    CV_WRAP virtual int getIterations() const = 0;

    CV_WRAP virtual void setCostExtractor(Ptr<HistogramCostExtractor> comparer) = 0;
    CV_WRAP virtual Ptr<HistogramCostExtractor> getCostExtractor() const = 0;

    CV_WRAP virtual void setTransformAlgorithm(Ptr<ShapeTransformer> transformer) = 0;
    CV_WRAP virtual Ptr<ShapeTransformer> getTransformAlgorithm() const = 0;
};

/* Complete constructor */
CV_EXPORTS_W Ptr<ShapeContextDistanceExtractor>
    createShapeContextDistanceExtractor(int nAngularBins=12, int nRadialBins=4,
                                        float innerRadius=0.2, float outerRadius=2, int iterations=3,
                                        const Ptr<HistogramCostExtractor> &comparer = createChiHistogramCostExtractor(),
                                        const Ptr<ShapeTransformer> &transformer = createThinPlateSplineShapeTransformer());

ShapeContextDistanceExtractor::setAngularBins

Establish the number of angular bins for the Shape Context Descriptor used in the shape matching pipeline.

C++: void setAngularBins(int nAngularBins)

Parameters:

• nAngularBins – The number of angular bins in the shape context descriptor.

ShapeContextDistanceExtractor::setRadialBins

Establish the number of radial bins for the Shape Context Descriptor used in the shape matching pipeline.

C++: void setRadialBins(int nRadialBins)

Parameters:

• nRadialBins – The number of radial bins in the shape context descriptor.

ShapeContextDistanceExtractor::setInnerRadius

Set the inner radius of the shape context descriptor.

C++: void setInnerRadius(float innerRadius)

Parameters:

• innerRadius – The value of the inner radius.

ShapeContextDistanceExtractor::setOuterRadius

Set the outer radius of the shape context descriptor.

C++: void setOuterRadius(float outerRadius)

Parameters:

• outerRadius – The value of the outer radius.

ShapeContextDistanceExtractor::setShapeContextWeight

Set the weight of the shape context distance in the final value of the shape distance. The shape context distance between two shapes is defined as the symmetric sum of shape context matching costs over best matching points. The final value of the shape distance is a user-defined linear combination of the shape context distance, an image appearance distance, and a bending energy.

C++: void setShapeContextWeight(float shapeContextWeight)

Parameters:

• shapeContextWeight – The weight of the shape context distance in the final distance value.

ShapeContextDistanceExtractor::setImageAppearanceWeight

Set the weight of the Image Appearance cost in the final value of the shape distance. The image appearance cost is defined as the sum of squared brightness differences in Gaussian windows around corresponding image points. The final value of the shape distance is a user-defined linear combination of the shape context distance, an image appearance distance, and a bending energy. If this value is set to a number different from 0, is mandatory to set the images that correspond to each shape.

C++: void setImageAppearanceWeight(float imageAppearanceWeight)

Parameters:

• imageAppearanceWeight – The weight of the appearance cost in the final distance value.

ShapeContextDistanceExtractor::setBendingEnergyWeight

Set the weight of the Bending Energy in the final value of the shape distance. The bending energy definition depends on what transformation is being used to align the shapes. The final value of the shape distance is a user-defined linear combination of the shape context distance, an image appearance distance, and a bending energy.

C++: void setBendingEnergyWeight(float bendingEnergyWeight)

Parameters:

• bendingEnergyWeight – The weight of the Bending Energy in the final distance value.

ShapeContextDistanceExtractor::setImages

Set the images that correspond to each shape. This images are used in the calculation of the Image Appearance cost.

C++: void setImages(InputArray image1, InputArray image2)

Parameters:

• image1 – Image corresponding to the shape defined by contours1.
• image2 – Image corresponding to the shape defined by contours2.

ShapeContextDistanceExtractor::setCostExtractor

Set the algorithm used for building the shape context descriptor cost matrix.

C++: void setCostExtractor(Ptr<HistogramCostExtractor> comparer)

Parameters:

• comparer – Smart pointer to a HistogramCostExtractor, an algorithm that defines the cost matrix between descriptors.

ShapeContextDistanceExtractor::setStdDev

Set the value of the standard deviation for the Gaussian window for the image appearance cost.

C++: void setStdDev(float sigma)

Parameters:

• sigma – Standard Deviation.

ShapeContextDistanceExtractor::setTransformAlgorithm

Set the algorithm used for aligning the shapes.

C++: void setTransformAlgorithm(Ptr<ShapeTransformer> transformer)

Parameters:

• comparer – Smart pointer to a ShapeTransformer, an algorithm that defines the aligning transformation.

HausdorffDistanceExtractor

class HausdorffDistanceExtractor : public ShapeDistanceExtractor

A simple Hausdorff distance measure between shapes defined by contours, according to the paper “Comparing Images using the Hausdorff distance.” by D.P. Huttenlocher, G.A. Klanderman, and W.J. Rucklidge. (PAMI 1993).

class CV_EXPORTS_W HausdorffDistanceExtractor : public ShapeDistanceExtractor
{
public:
    CV_WRAP virtual void setDistanceFlag(int distanceFlag) = 0;
    CV_WRAP virtual int getDistanceFlag() const = 0;

    CV_WRAP virtual void setRankProportion(float rankProportion) = 0;
    CV_WRAP virtual float getRankProportion() const = 0;
};

/* Constructor */
CV_EXPORTS_W Ptr<HausdorffDistanceExtractor> createHausdorffDistanceExtractor(int distanceFlag=cv::NORM_L2, float rankProp=0.6);

HausdorffDistanceExtractor::setDistanceFlag

Set the norm used to compute the Hausdorff value between two shapes. It can be L1 or L2 norm.

C++: void setDistanceFlag(int distanceFlag)

Parameters:

• distanceFlag – Flag indicating which norm is used to compute the Hausdorff distance (NORM_L1, NORM_L2).

HausdorffDistanceExtractor::setRankProportion

This method sets the rank proportion (or fractional value) that establish the Kth ranked value of the partial Hausdorff distance. Experimentally had been shown that 0.6 is a good value to compare shapes.

C++: void setRankProportion(float rankProportion)

Parameters:

• rankProportion – fractional value (between 0 and 1).