opencv-4.2的brief.cpp

/home/cgm/opencv-4.2/opencv_contrib-4.2.0/modules/xfeatures2d/src/brief.cpp

/*M///
//
//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
//
//  By downloading, copying, installing or using the software you agree to this license.
//  If you do not agree to this license, do not download, install,
//  copy or use the software.
//
//
//                           License Agreement
//                For Open Source Computer Vision Library
//
// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
// Copyright (C) 2009-2010, Willow Garage Inc., all rights reserved.
// Third party copyrights are property of their respective owners.
//
// Redistribution and use in source and binary forms, with or without modification,
// are permitted provided that the following conditions are met:
//
//   * Redistribution's of source code must retain the above copyright notice,
//     this list of conditions and the following disclaimer.
//
//   * Redistribution's in binary form must reproduce the above copyright notice,
//     this list of conditions and the following disclaimer in the documentation
//     and/or other materials provided with the distribution.
//
//   * The name of the copyright holders may not be used to endorse or promote products
//     derived from this software without specific prior written permission.
//
// This software is provided by the copyright holders and contributors "as is" and
// any express or implied warranties, including, but not limited to, the implied
// warranties of merchantability and fitness for a particular purpose are disclaimed.
// In no event shall the Intel Corporation or contributors be liable for any direct,
// indirect, incidental, special, exemplary, or consequential damages
// (including, but not limited to, procurement of substitute goods or services;
// loss of use, data, or profits; or business interruption) however caused
// and on any theory of liability, whether in contract, strict liability,
// or tort (including negligence or otherwise) arising in any way out of
// the use of this software, even if advised of the possibility of such damage.
//
//M*/

#include "precomp.hpp"
#include <algorithm>
#include <vector>

#include <iostream>
#include <iomanip>

namespace cv
{
namespace xfeatures2d
{

/*
 * BRIEF Descriptor
 */
// 继承
class BriefDescriptorExtractorImpl : public BriefDescriptorExtractor
{
public:
    enum { PATCH_SIZE = 48, KERNEL_SIZE = 9 };//邻域范围48，//平滑积分核大小9

    // bytes is a length of descriptor in bytes. It can be equal 16, 32 or 64 bytes.
    BriefDescriptorExtractorImpl( int bytes = 32, bool use_orientation = false );//占用字节数32,对应描述子长度为32×8=256;

    virtual void read( const FileNode& ) CV_OVERRIDE; //子类必须重写父类中的纯虚函数，否则也属于抽象类
    virtual void write( FileStorage& ) const CV_OVERRIDE;

    virtual int descriptorSize() const CV_OVERRIDE;
    virtual int descriptorType() const CV_OVERRIDE;
    virtual int defaultNorm() const CV_OVERRIDE;

    virtual void compute(InputArray image, std::vector<KeyPoint>& keypoints, OutputArray descriptors) CV_OVERRIDE;

protected:
    typedef void(*PixelTestFn)(InputArray, const std::vector<KeyPoint>&, OutputArray, bool use_orientation );

    int bytes_;
    bool use_orientation_;
    PixelTestFn test_fn_;
};

Ptr<BriefDescriptorExtractor> BriefDescriptorExtractor::create( int bytes, bool use_orientation )
{
    return makePtr<BriefDescriptorExtractorImpl>(bytes, use_orientation );
}
// 对点进行盒装高斯平滑作用，函数是根据像素点位置，返回此区域的差分和
// sum为积分图像，pt为特征点变量，x和y表示点对中某一个像素相对于特征点的坐标，函数返回滤波的结果
inline int smoothedSum(const Mat& sum, const KeyPoint& pt, int y, int x, bool use_orientation, Matx21f R)
{
    static const int HALF_KERNEL = BriefDescriptorExtractorImpl::KERNEL_SIZE / 2; // 盒状滤波器边长的一半

    if ( use_orientation )
    {
      int rx = (int)(((float)x)*R(1,0) - ((float)y)*R(0,0));
      int ry = (int)(((float)x)*R(0,0) + ((float)y)*R(1,0));
      if (rx > 24) rx = 24; // PATCH_SIZE = 48
      if (rx < -24) rx = -24;
      if (ry > 24) ry = 24;
      if (ry < -24) ry = -24;
      x = rx; y = ry;
    }
    // 计算点对中某一个像素的绝对坐标 
    const int img_y = (int)(pt.pt.y + 0.5) + y;
    const int img_x = (int)(pt.pt.x + 0.5) + x;
    // 计算以该像素为中心，以KERNEL_SIZE为边长的正方形内所有像素灰度值之和，本质上是均值滤波
    return   sum.at<int>(img_y + HALF_KERNEL + 1, img_x + HALF_KERNEL + 1)  
           - sum.at<int>(img_y + HALF_KERNEL + 1, img_x - HALF_KERNEL)
           - sum.at<int>(img_y - HALF_KERNEL, img_x + HALF_KERNEL + 1)
           + sum.at<int>(img_y - HALF_KERNEL, img_x - HALF_KERNEL);
}

static void pixelTests16(InputArray _sum, const std::vector<KeyPoint>& keypoints, OutputArray _descriptors, bool use_orientation )
{
    Matx21f R; // Matx<float, 2, 1> 两行一列矩阵
    Mat sum = _sum.getMat(), descriptors = _descriptors.getMat();// 积分图像sum，描述子descriptors
    for (size_t i = 0; i < keypoints.size(); ++i) // 遍历所有的特征点  
    {
        // 2.4.9版本的代码是 uchar* desc = descriptors.ptr(i);  
        // static_cast是一个c++运算符，功能是把一个表达式转换为某种类型，但没有运行时类型检查来保证转换的安全性。 
        uchar* desc = descriptors.ptr(static_cast<int>(i));// 描述符的首地址指针。 
        const KeyPoint& pt = keypoints[i]; // 特征点的首地址指针  
        if ( use_orientation )
        {
          float angle = pt.angle;
          angle *= (float)(CV_PI/180.f);
          R(0,0) = sin(angle);
          R(1,0) = cos(angle);
        }

#include "generated_16.i" //执行generated_16.i预处理文件 
    }
}

static void pixelTests32(InputArray _sum, const std::vector<KeyPoint>& keypoints, OutputArray _descriptors, bool use_orientation)
{
    Matx21f R;
    Mat sum = _sum.getMat(), descriptors = _descriptors.getMat();
    for (size_t i = 0; i < keypoints.size(); ++i)
    {
        uchar* desc = descriptors.ptr(static_cast<int>(i));
        const KeyPoint& pt = keypoints[i];
        if ( use_orientation )
        {
          float angle = pt.angle;
          angle *= (float)(CV_PI / 180.f);
          R(0,0) = sin(angle);
          R(1,0) = cos(angle);
        }

#include "generated_32.i"
    }
}

static void pixelTests64(InputArray _sum, const std::vector<KeyPoint>& keypoints, OutputArray _descriptors, bool use_orientation)
{
    Matx21f R;
    Mat sum = _sum.getMat(), descriptors = _descriptors.getMat();
    for (size_t i = 0; i < keypoints.size(); ++i)
    {
        uchar* desc = descriptors.ptr(static_cast<int>(i));
        const KeyPoint& pt = keypoints[i];
        if ( use_orientation )
        {
          float angle = pt.angle;
          angle *= (float)(CV_PI/180.f);
          R(0,0) = sin(angle);
          R(1,0) = cos(angle);
        }

#include "generated_64.i"
    }
}
// BriefDescriptorExtractorImpl继承类的构造函数
// 根据描述符字节数的不同，test_fn_指向不同的函数，这些函数的意义相同，区别在于处理的点对数量不同
// bytes表示描述符的字节数，即公式3中的k = nd/8，k只可能为16，32和64，默认为32 
BriefDescriptorExtractorImpl::BriefDescriptorExtractorImpl(int bytes, bool use_orientation) :
    bytes_(bytes), test_fn_(NULL)
{
    use_orientation_ = use_orientation;
 //根据字节数选择不同的函数，字节数不同，则所需要的像素点对的数量就不同，所以要调用不同的函数
    switch (bytes)
    {
        case 16: //128个点对  
            test_fn_ = pixelTests16;
            break;
        case 32: //256个点对
            test_fn_ = pixelTests32;
            break;
        case 64: //512个点对  
            test_fn_ = pixelTests64;
            break;
        default: //只可能为以上三种情况  
            CV_Error(Error::StsBadArg, "bytes must be 16, 32, or 64");
    }
}

int BriefDescriptorExtractorImpl::descriptorSize() const
{
    return bytes_;
}

int BriefDescriptorExtractorImpl::descriptorType() const
{
    return CV_8UC1;
}

int BriefDescriptorExtractorImpl::defaultNorm() const
{
    return NORM_HAMMING;
}

void BriefDescriptorExtractorImpl::read( const FileNode& fn)
{
    int dSize = fn["descriptorSize"];
    switch (dSize)
    {
        case 16:
            test_fn_ = pixelTests16;
            break;
        case 32:
            test_fn_ = pixelTests32;
            break;
        case 64:
            test_fn_ = pixelTests64;
            break;
        default:
            CV_Error(Error::StsBadArg, "descriptorSize must be 16, 32, or 64");
    }
    bytes_ = dSize;
}

void BriefDescriptorExtractorImpl::write( FileStorage& fs) const
{
    fs << "descriptorSize" << bytes_;
}

void BriefDescriptorExtractorImpl::compute(InputArray image,
                                           std::vector<KeyPoint>& keypoints,
                                           OutputArray descriptors)
{
    // Construct integral image for fast smoothing (box filter)
    Mat sum;  //积分图像矩阵 

    Mat grayImage = image.getMat();  //输入图像
    if( image.type() != CV_8U ) cvtColor( image, grayImage, COLOR_BGR2GRAY ); //把输入图像image转换为灰度图像grayImage  

    ///TODO allow the user to pass in a precomputed integral image
    //if(image.type() == CV_32S)
    //  sum = image;
    //else

    integral( grayImage, sum, CV_32S); //用得到的灰度图像grayImag，计算积分图像sum  

    //Remove keypoints very close to the border
    // PATCH_SIZE = 48;表示补丁区域的边长，KERNEL_SIZE = 9;表示盒状滤波器的边长  
    //根据补丁区域和盒状滤波器的尺寸大小，去掉那些过于靠近图像边界的特征点  
    KeyPointsFilter::runByImageBorder(keypoints, image.size(), PATCH_SIZE/2 + KERNEL_SIZE/2);
    // 描述符矩阵变量清零，2.4.9版本的代码是 descriptors = Mat::zeros((int)keypoints.size(), bytes_, CV_8U);  
    descriptors.create((int)keypoints.size(), bytes_, CV_8U);
    // setTo(value, mask);当默认不添加mask的时候，表明mask是一个与原图尺寸大小一致的且元素值全为非0的矩阵，因此不加mask的时候，会将原矩阵的像素值全部赋值为value；
    // 当带有mask这个参数的时候，该函数会把矩阵mask中元素不为0的点全部变为value值
    descriptors.setTo(Scalar::all(0)); 
    //调用test_fn_指向的函数，如 test_fn_ = pixelTests32; 创建BRIEF描述符
    test_fn_(sum, keypoints, descriptors, use_orientation_);
}

}
} // namespace cv