FeatureDetector.h

Go to the documentation of this file.

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
 
#ifndef META_OCEAN_CV_DETECTOR_FEATURE_DETECTOR_H
#define META_OCEAN_CV_DETECTOR_FEATURE_DETECTOR_H
 
#include "ocean/cv/detector/Detector.h"
 
#include "ocean/base/Frame.h"
#include "ocean/base/Worker.h"
 
#include "ocean/cv/FrameConverter.h"
#include "ocean/cv/SubRegion.h"
 
#include "ocean/math/Vector2.h"
 
namespace Ocean
{
 
namespace CV
{
 
namespace Detector
{
 
/**
 * This class provides an abstraction for visual features and strong feature points.
 * @ingroup cvdetector
 */
class OCEAN_CV_DETECTOR_EXPORT FeatureDetector
{
    public:
 
        /**
         * The following comfort class provides comfortable functions simplifying prototyping applications but also increasing binary size of the resulting applications.
         * Best practice is to avoid using these functions if binary size matters,<br>
         * as for every comfort function a corresponding function exists with specialized functionality not increasing binary size significantly.<br>
         */
        class OCEAN_CV_EXPORT Comfort
        {
            public:
 
                /**
                 * Determines strong feature points in a given image, optional a sub-region can be specified in that the points are detected.
                 * @param frame The frame in which the feature points are detected, will be converted to a frame with pixel format FORMAT_Y8 internally, must be valid
                 * @param subRegion Optional sub-region specifying a small image area in that the points are detected, an invalid sub-region to use the entire frame
                 * @param horizontalBins Optional horizontal bins that can be used to distribute the tracked points into array bins (in each bin there will be at most one point)
                 * @param verticalBins Optional vertical bins that can be used to distribute the tracked points into array bins (in each bin there will be at most one point)
                 * @param strength Minimal aiming strength parameter of the tracked feature points, this value will be weakened if too less feature points can be detected
                 * @param worker Optional worker object to distribute the computation
                 * @param strengths Optional resulting strength values individual for each point
                 * @return The resulting feature points, feature points with high strength value first
                 */
                static Vectors2 determineHarrisPoints(const Frame& frame, const SubRegion& subRegion = SubRegion(), const unsigned int horizontalBins = 0u, const unsigned int verticalBins = 0u, const unsigned int strength = 30u, Worker* worker = nullptr, std::vector<int>* strengths = nullptr);
        };
 
    protected:
 
        /**
         * This class implements a vector extension holding an additional intensity parameter.
         */
        class IntensityVector2 : public Vector2
        {
            public:
 
                /**
                 * Creates a new intensity vector object with undefined vector elements.
                 * Beware: The elements are neither zero nor a specific value!
                 * @see VectorT2::VectorT2()
                 */
                IntensityVector2() = default;
 
                /**
                 * Creates a new intensity vector by the given position and intensity value.
                 * @param position Vector position
                 * @param intensity Vector intensity
                 */
                inline IntensityVector2(const Vector2& position, const int intensity);
 
                /**
                 * Returns the intensity value of this object.
                 * @return Intensity value
                 */
                inline int intensity() const;
 
                /**
                 * Compares two intensity objects.
                 * @param object Second object to compare
                 * @return True, if the intensity of the left object is higher than the intensity of the right object
                 */
                inline bool operator<(const IntensityVector2& object) const;
 
            private:
 
                /// Intensity value.
                int intensity_ = NumericT<int>::minValue();
        };
 
        /**
         * Definition of a vector holding intensity vector objects.
         */
        using IntensityVectors2 = std::vector<IntensityVector2>;
 
    public:
 
        /**
         * Determines the points in an 8bit grayscale image with highest Harris corner response votes.
         * @param yFrame The 8bit grayscale frame in which the Harris corner responses have to be determined, must be valid
         * @param width The width of the frame in pixel, with range [5, infinity)
         * @param height The height of the frame in pixel, with range [5, infinity)
         * @param yFramePaddingElements The number of padding elements at the end of each row of yFrame, in elements, with range [0, infinity)
         * @param positions Given 2D positions inside the frame that have to be ordered according their response intensities
         * @param maximalPoints Number of maximal points that have to be returned
         * @param minSqrDistance Minimal squared distance between the points to be accepted
         * @param harrisThreshold Minimal threshold for all Harris responses (points below this threshold will be skipped)
         * @param worker Optional worker object to distribute the computation
         * @return The resulting feature points
         */
        static Vectors2 filterStrongHarrisPoints(const uint8_t* yFrame, const unsigned int width, const unsigned int height, const unsigned int yFramePaddingElements, const Vectors2& positions, const unsigned int maximalPoints, const Scalar minSqrDistance, const int harrisThreshold = 0, Worker* worker = nullptr);
 
        /**
         * Determines strong feature points in a given image, optional a sub-region can be specified in that the points are detected.
         * @param yFrame The grayscale frame in which the feature points are detected, must have pixel format FORMAT_Y8, must be valid
         * @param subRegion Optional sub-region specifying a small image area in that the points are detected, an invalid sub-region to use the entire frame
         * @param horizontalBins Optional horizontal bins that can be used to distribute the tracked points into array bins (in each bin there will be at most one point)
         * @param verticalBins Optional vertical bins that can be used to distribute the tracked points into array bins (in each bin there will be at most one point)
         * @param strength Minimal aiming strength parameter of the tracked feature points, this value will be weakened if too less feature points can be detected
         * @param worker Optional worker object to distribute the computation
         * @param strengths Optional resulting strength values individual for each point
         * @return The resulting feature points, feature points with high strength value first
         */
        static inline Vectors2 determineHarrisPoints(const Frame& yFrame, const SubRegion& subRegion = SubRegion(), const unsigned int horizontalBins = 0u, const unsigned int verticalBins = 0u, const unsigned int strength = 30u, Worker* worker = nullptr, std::vector<int>* strengths = nullptr);
 
        /**
         * Determines strong feature points in a given image, optional a sub-region can be specified in that the points are detected.
         * @param yFrame The 8 bit grayscale frame (Y8 pixel format) in which the feature points are detected, must be valid
         * @param width The width of the given frame in pixel, with range [7, infinity)
         * @param height The height of the given frame in pixel, with range [7, infinity)
         * @param yFramePaddingElements The number of padding elements at the end of each row of yFrame, in elements, with range [0, infinity)
         * @param subRegion Optional sub-region specifying a small image area in that the points are detected
         * @param horizontalBins Optional horizontal bins that can be used to distribute the tracked points into array bins (in each bin there will be at most one point)
         * @param verticalBins Optional vertical bins that can be used to distribute the tracked points into array bins (in each bin there will be at most one point)
         * @param strength Minimal aiming strength parameter of the tracked feature points, this value will be weakened if too less feature points can be detected
         * @param worker Optional worker object to distribute the computation
         * @param strengths Optional resulting strength values individual for each point
         * @return The resulting feature points, feature points with high strength value first
         */
        static Vectors2 determineHarrisPoints(const uint8_t* yFrame, const unsigned int width, const unsigned int height, const unsigned int yFramePaddingElements, const SubRegion& subRegion, const unsigned int horizontalBins = 0u, const unsigned int verticalBins = 0u, const unsigned int strength = 30u, Worker* worker = nullptr, std::vector<int>* strengths = nullptr);
};
 
inline FeatureDetector::IntensityVector2::IntensityVector2(const Vector2& position, const int intensity) :
    Vector2(position),
    intensity_(intensity)
{
    // nothing to do here
}
 
inline int FeatureDetector::IntensityVector2::intensity() const
{
    return intensity_;
}
 
inline bool FeatureDetector::IntensityVector2::operator<(const IntensityVector2& object) const
{
    return intensity_ > object.intensity_;
}
 
inline Vectors2 FeatureDetector::determineHarrisPoints(const Frame& yFrame, const SubRegion& subRegion, const unsigned int horizontalBins, const unsigned int verticalBins, const unsigned int strength, Worker* worker, std::vector<int>* strengths)
{
    ocean_assert(yFrame.isValid());
    ocean_assert(yFrame.isPixelFormatCompatible(FrameType::FORMAT_Y8));
 
    if (!yFrame.isValid() || !yFrame.isPixelFormatCompatible(FrameType::FORMAT_Y8))
    {
        return Vectors2();
    }
 
    return determineHarrisPoints(yFrame.constdata<uint8_t>(), yFrame.width(), yFrame.height(), yFrame.paddingElements(), subRegion, horizontalBins, verticalBins, strength, worker, strengths);
}
 
}
 
}
 
}
 
#endif // META_OCEAN_CV_DETECTOR_FEATURE_DETECTOR_H