SIFT::SIFT( int _nfeatures, int _nOctaveLayers,
           double _contrastThreshold, double _edgeThreshold, double _sigma )
    : nfeatures(_nfeatures), nOctaveLayers(_nOctaveLayers),
    contrastThreshold(_contrastThreshold), edgeThreshold(_edgeThreshold), sigma(_sigma)
    // sigma：对第0层进行高斯模糊的尺度空间因子。
    // 默认为1.6（如果是软镜摄像头捕获的图像，可以适当减小此值）
{
}

void SIFT::operator()(InputArray _image, InputArray _mask,
                      vector<KeyPoint>& keypoints,
                      OutputArray _descriptors,
                      bool useProvidedKeypoints) const
// mask ：Optional input mask that marks the regions where we should detect features.
// Boolean flag. If it is true, the keypoint detector is not run. Instead,
// the provided vector of keypoints is used and the algorithm just computes their descriptors.
// descriptors – The output matrix of descriptors.
// Pass cv::noArray() if you do not need them.              
{
    Mat image = _image.getMat(), mask = _mask.getMat();

    if( image.empty() || image.depth() != CV_8U )
        CV_Error( CV_StsBadArg, "image is empty or has incorrect depth (!=CV_8U)" );

    if( !mask.empty() && mask.type() != CV_8UC1 )
        CV_Error( CV_StsBadArg, "mask has incorrect type (!=CV_8UC1)" );

        
    // 得到第1组（Octave）图像
    Mat base = createInitialImage(image, false, (float)sigma);
    vector<Mat> gpyr, dogpyr;
    // 每层金字塔图像的组数（Octave）
    int nOctaves = cvRound(log( (double)std::min( base.cols, base.rows ) ) / log(2.) - 2);

    // double t, tf = getTickFrequency();
    // t = (double)getTickCount();
    
    // 构建金字塔（金字塔层数和组数相等）
    buildGaussianPyramid(base, gpyr, nOctaves);
    // 构建高斯差分金字塔
    buildDoGPyramid(gpyr, dogpyr);

    //t = (double)getTickCount() - t;
    //printf("pyramid construction time: %g\n", t*1000./tf);
    
    // useProvidedKeypoints默认为false
    // 使用keypoints并计算特征点的描述符
    if( !useProvidedKeypoints )
    {
        //t = (double)getTickCount();
        findScaleSpaceExtrema(gpyr, dogpyr, keypoints);
        //除去重复特征点
        KeyPointsFilter::removeDuplicated( keypoints ); 

        // mask标记检测区域（可选）
        if( !mask.empty() )
            KeyPointsFilter::runByPixelsMask( keypoints, mask );

        // retainBest:根据相应保留指定数目的特征点（features2d.hpp）
        if( nfeatures > 0 )
            KeyPointsFilter::retainBest(keypoints, nfeatures);
        //t = (double)getTickCount() - t;
        //printf("keypoint detection time: %g\n", t*1000./tf);
    }
    else
    {
        // filter keypoints by mask
        // KeyPointsFilter::runByPixelsMask( keypoints, mask );
    }

    // 特征点输出数组
    if( _descriptors.needed() )
    {
        //t = (double)getTickCount();
        int dsize = descriptorSize();
        _descriptors.create((int)keypoints.size(), dsize, CV_32F);
        Mat descriptors = _descriptors.getMat();

        calcDescriptors(gpyr, keypoints, descriptors, nOctaveLayers);
        //t = (double)getTickCount() - t;
        //printf("descriptor extraction time: %g\n", t*1000./tf);
    }
}