AdvancedMotion.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_ADVANCED_ADVANCED_MOTION_H
#define META_OCEAN_CV_ADVANCED_ADVANCED_MOTION_H
 
#include "ocean/cv/advanced/Advanced.h"
#include "ocean/cv/advanced/AdvancedFrameInterpolatorBilinear.h"
#include "ocean/cv/advanced/AdvancedSumSquareDifferences.h"
#include "ocean/cv/advanced/AdvancedZeroMeanSumSquareDifferences.h"
 
#include "ocean/base/Frame.h"
#include "ocean/base/Worker.h"
 
#include "ocean/cv/FrameConverter.h"
#include "ocean/cv/FramePyramid.h"
#include "ocean/cv/Motion.h"
#include "ocean/cv/PixelPosition.h"
#include "ocean/cv/PixelBoundingBox.h"
#include "ocean/cv/SubRegion.h"
 
#include "ocean/cv/detector/HarrisCornerDetector.h"
 
#include "ocean/geometry/SpatialDistribution.h"
 
#include "ocean/math/Box2.h"
 
namespace Ocean
{
 
namespace CV
{
 
namespace Advanced
{
 
// Forward declaration.
template <typename TMetricInteger, typename TMetricFloat>
class AdvancedMotionT;
 
/**
 * Definition of an AdvancedMotion class that applies sum square difference calculations as metric.
 * @see AdvancedMotionZeroMeanSSD, AdvancedMotion.
 * @ingroup cvadvanced
 */
using AdvancedMotionSSD = AdvancedMotionT<SumSquareDifferences, AdvancedSumSquareDifferences>;
 
/**
 * Definition of an AdvancedMotion class that applies zero-mean sum square difference calculations as metric.
 * @see AdvancedMotionSSD, AdvancedMotion.
 * @ingroup cvadvanced
 */
using AdvancedMotionZeroMeanSSD = AdvancedMotionT<ZeroMeanSumSquareDifferences, AdvancedZeroMeanSumSquareDifferences>;
 
class OCEAN_CV_ADVANCED_EXPORT AdvancedMotion
{
    public:
 
        /**
         * Definition of a vector holding metric results.
         */
        using MetricResults = std::vector<uint32_t>;
 
        /**
         * This class manages point correspondences for bidirectional tracking across pyramid layers.
         * The class handles the state management for tracking points from a previous pyramid to a next pyramid, and then back to the previous pyramid for validation.
         * It manages the progression through pyramid layers (coarse-to-fine) and provides methods to access and update point positions during the tracking process.
         */
        class OCEAN_CV_ADVANCED_EXPORT PointCorrespondences
        {
            public:
 
                /**
                 * Creates an invalid point correspondences object.
                 */
                PointCorrespondences() = default;
 
                /**
                 * Creates a new point correspondences object with pre-defined predicted next points.
                 * In case no rough estimates for the next image points are known, use a copy of the previous points.
                 * @param previousPoints The previous image points, must be valid
                 * @param predictedNextPoints The predicted next image points (rough estimates), will be updated to the actuall tracked current next points, must be valid
                 * @param validCorrespondences The buffer to store validity flags for each correspondence, must be valid
                 * @param correspondences The number of point correspondences, with range [1, infinity)
                 * @param pyramidLayers The number of pyramid layers to be used for tracking, with range [1, infinity)
                 * @param coarsestLayerRadius The search radius on the coarsest pyramid layer, with range [2, infinity)
                 * @param maximalError Maximal error between forward and backward tracking for a valid point, with range [0, infinity)
                 * @param subPixelIterations Number of sub-pixel iterations that will be applied, with range [1, infinity)
                 */
                inline PointCorrespondences(const Vector2* previousPoints, Vector2* predictedNextPoints, uint8_t* validCorrespondences, const size_t correspondences, const unsigned int pyramidLayers, const unsigned int coarsestLayerRadius, const Scalar maximalError = Scalar(0.9), const unsigned int subPixelIterations = 4u);
 
                /**
                 * Initializes the forward tracking from the previous pyramid to the next pyramid.
                 * This method prepares the internal state for tracking points forward through the pyramid layers.
                 * @param previousPyramid The previous frame pyramid, must be valid
                 * @param nextPyramid The next frame pyramid, must be valid
                 */
                void startForwardTracking(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid);
 
                /**
                 * Initializes the backward tracking from the next pyramid back to the previous pyramid.
                 * This method prepares the internal state for tracking points backward through the pyramid layers for validation.
                 * @param previousPyramid The previous frame pyramid, must be valid
                 * @param nextPyramid The next frame pyramid, must be valid
                 */
                void startBackwardTracking(const CV::FramePyramid& /*previousPyramid*/, const CV::FramePyramid& nextPyramid);
 
                /**
                 * Starts processing a specific pyramid layer.
                 * This method sets up the internal state for tracking on the specified pyramid layer.
                 * @param layerIndex The index of the pyramid layer to process, with range [0, pyramidLayers)
                 * @param previousPyramid The previous frame pyramid, must be valid
                 * @param nextPyramid The next frame pyramid, must be valid
                 * @return True if the layer can be processed; False if the layer index is out of range
                 */
                bool startLayer(const unsigned int layerIndex, const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid);
 
                /**
                 * Returns the previous image point position at the finest pyramid layer.
                 * This method can only be called when processing the finest layer (layer index 0).
                 * @param pointIndex The index of the point to access, with range [0, size())
                 * @return The previous point position in the finest layer
                 */
                inline const Vector2& previousPosition(const size_t pointIndex) const;
 
                /**
                 * Returns the previous image point position downsampled to the current pyramid layer.
                 * This method should be called for pyramid layers other than the finest layer.
                 * @param pointIndex The index of the point to access, with range [0, size())
                 * @return The pixel position of the previous point at the current pyramid layer
                 */
                inline CV::PixelPosition previousPositionDownsampled(const size_t pointIndex) const;
 
                /**
                 * Returns the predicted next image point position downsampled to the current pyramid layer.
                 * This method should be called for pyramid layers other than the finest layer.
                 * @param pointIndex The index of the point to access, with range [0, size())
                 * @return The pixel position of the predicted next point at the current pyramid layer
                 */
                inline CV::PixelPosition predictedNextPositionDownsampled(const size_t pointIndex) const;
 
                /**
                 * Returns the predicted next image point position at the finest pyramid layer.
                 * This method can only be called when processing the finest layer (layer index 0).
                 * @param pointIndex The index of the point to access, with range [0, size())
                 * @return The predicted next point position in the finest layer
                 */
                inline const Vector2& predictedNextPosition(const size_t pointIndex) const;
 
                /**
                 * Propagates the next point position from the current pyramid layer to the finer layer below.
                 * This method upsamples the point and updates the internal state.
                 * During backward tracking, this also performs an early rejection test based on distance.
                 * @param pointIndex The index of the point to propagate, with range [0, size())
                 * @param nextPoint The next point position at the current pyramid layer
                 */
                void propagateNextPositionDownsampled(const size_t pointIndex, const CV::PixelPosition& nextPoint);
 
                /**
                 * Propagates the final next point position at the finest pyramid layer.
                 * During forward tracking, this simply stores the final result.
                 * During backward tracking, this validates the bidirectional tracking consistency and computes
                 * the corrected next point position using the forward-backward offset.
                 * @param pointIndex The index of the point to propagate, with range [0, size())
                 * @param nextPoint The next point position at the finest layer
                 */
                void propagateNextPosition(const size_t pointIndex, const Vector2& nextPoint);
 
                /**
                 * Returns whether a specific point correspondence is still valid.
                 * Points can be marked invalid during backward tracking if they fail validation criteria.
                 * @param pointIndex The index of the point to check, with range [0, size())
                 * @return True if the point correspondence is valid; False otherwise
                 */
                inline bool isPointValid(const size_t pointIndex) const;
 
                /**
                 * Returns the number of pyramid layers to be used for tracking.
                 * @return The number of pyramid layers, with range [1, infinity)
                 */
                inline unsigned int pyramidLayers() const;
 
                /**
                 * Returns the search radius for the current pyramid layer.
                 * @return The search radius in pixels, with range [2, infinity)
                 */
                inline unsigned int layerRadius() const;
 
                /**
                 * Returns the number of sub-pixel iterations to be applied at the finest pyramid layer.
                 * @return The number of sub-pixel iterations, with range [1, infinity)
                 */
                inline unsigned int subPixelIterations() const;
 
                /**
                 * Returns the number of point correspondences.
                 * @return The number of correspondences, with range [0, infinity)
                 */
                inline size_t size() const;
 
                /**
                 * Returns whether this object holds valid parameters.
                 * @return True, if so
                 */
                inline bool isValid() const;
 
                /**
                 * Determines the coarsest pyramid layer index across multiple correspondence groups.
                 * This static method finds the maximum coarsest layer that can be used based on
                 * the pyramid sizes and the requested layers for all correspondence groups.
                 * @param previousPyramid The previous frame pyramid, must be valid
                 * @param nextPyramid The next frame pyramid, must be valid
                 * @param pointCorrespondenceGroups The array of correspondence groups, must be valid
                 * @param numberCorrespondenceGroups The number of correspondence groups, with range [1, infinity)
                 * @return The coarsest pyramid layer index that can be used, with range [0, min(pyramids.layers()) - 1]
                 */
                static unsigned int coarsestPyramidLayer(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const PointCorrespondences* pointCorrespondenceGroups, const size_t numberCorrespondenceGroups);
 
            protected:
 
                /// The image points in the previous pyramid, always at finest layer resolution
                const Vector2* previousPoints_ = nullptr;
 
                /// The tracked next image points, progressively refined through pyramid layers (coarsest to finest)
                Vector2* nextPoints_ = nullptr;
 
                /// Binary validity flags for each correspondence (0x00 = invalid, 0x01 = valid)
                uint8_t* validCorrespondences_ = nullptr;
 
                /// The number of point correspondences to track
                size_t correspondences_ = 0;
 
                /// The number of pyramid layers to use for tracking
                unsigned int pyramidLayers_ = 0u;
 
                /// The search radius on the coarsest pyramid layer, in pixels
                unsigned int coarsestLayerRadius_ = 0u;
 
                /// The squared maximum error threshold for bidirectional tracking validation
                Scalar maximalSqrError_ = Scalar(-1);
 
                /// The squared maximum error threshold used during layer processing (includes search radius)
                Scalar maximalSqrErrorLayer_ = Scalar(-1);
 
                /// The number of sub-pixel iterations to apply at the finest pyramid layer
                unsigned int subPixelIterations_ = 0u;
 
                /// The index of the current pyramid layer being processed, (unsigned int)(-1) if not started
                unsigned int layerIndex_ = (unsigned int)(-1);
 
                /// The inverse scale factor for the current pyramid layer (1.0 / sizeFactor)
                Scalar invLayerFactor_ = Scalar(-1);
 
                /// The index of the coarsest pyramid layer that will be used for tracking
                unsigned int coarsestLayerIndex_ = (unsigned int)(-1);
 
                /// The width of the next pyramid's finest layer, in pixels (used for boundary checking)
                unsigned int nextPyramidFinestLayerWidth_ = 0u;
 
                /// The height of the next pyramid's finest layer, in pixels (used for boundary checking)
                unsigned int nextPyramidFinestLayerHeight_ = 0u;
 
                /// The width of the current layer being processed in the previous pyramid, in pixels
                unsigned int previousLayerWidth_ = 0u;
 
                /// The height of the current layer being processed in the previous pyramid, in pixels
                unsigned int previousLayerHeight_ = 0u;
 
                /// The width of the current layer being processed in the next pyramid, in pixels
                unsigned int nextLayerWidth_ = 0u;
 
                /// The height of the current layer being processed in the next pyramid, in pixels
                unsigned int nextLayerHeight_ = 0u;
 
                /// The search radius for the current pyramid layer being processed, in pixels
                unsigned int layerRadius_ = 0u;
 
                /// True during forward tracking (previous->next), False during backward tracking (next->previous)
                bool forwardTracking_ = true;
 
                /// Internal storage for backward tracking results used for bidirectional validation
                Vectors2 internalBackwardNextPoints_;
        };
 
        /**
         * This class collects statistics about tracking distances between corresponding 2D feature points.
         * The class calculates various statistical measures including average, median, percentiles (P95, P99), and maximum tracking distances.<br>
         * This class can be used to determine suitable tracking parameters for a specific tracking use case.
         * @see AdvancedMotionT::trackPointsBidirectionalSubPixelMirroredBorder().
         */
        class TrackingStatistic
        {
            public:
 
                /**
                 * Creates a new tracking statistic object.
                 * @param width The width of the image frame in pixels, with range [1, infinity)
                 * @param height The height of the image frame in pixels, with range [1, infinity)
                 */
                TrackingStatistic(const unsigned int width, const unsigned int height);
 
                /**
                 * Adds a set of point correspondences to the tracking statistics.
                 * @param previousImagePoints The image points from the previous frame, must be valid
                 * @param nextImagePoints The corresponding image points from the next frame, one for each previous image point, must be valid
                 * @param size The number of point correspondences, with range [1, infinity)
                 */
                void addCorrespondences(const Vector2* previousImagePoints, const Vector2* nextImagePoints, const size_t size);
 
                /**
                 * Adds a set of point correspondences to the tracking statistics, filtering by validity flags.
                 * Only correspondences marked as valid (non-zero in validCorrespondences) are added to the statistics.
                 * @param previousImagePoints The image points from the previous frame, must be valid
                 * @param nextImagePoints The corresponding image points from the next frame, one for each previous image point, must be valid
                 * @param validCorrespondences The validity flags for each correspondence, non-zero indicates valid, must be valid
                 * @param size The number of point correspondences, with range [1, infinity)
                 */
                void addCorrespondences(const Vector2* previousImagePoints, const Vector2* nextImagePoints, const uint8_t* validCorrespondences, const size_t size);
 
                /**
                 * Returns the number of measurements this statistic holds, (the number of calls to addCorrespondences()).
                 * @return The object's measurements
                 */
                inline size_t measurements() const;
 
                /**
                 * Returns whether this tracking statistic object is valid.
                 * @return True if so
                 */
                inline bool isValid() const;
 
                /**
                 * Returns a string of the tracking statistics.
                 * @return The tracking statistics as string
                 */
                std::string toString() const;
 
            protected:
 
                /// The width of the image frame in pixels
                unsigned int width_ = 0u;
 
                /// The height of the image frame in pixels
                unsigned int height_ = 0u;
 
                /// The squared Euclidean distances between all added point correspondences
                Scalars sqrDistances_;
 
                /// The number of measurements (calls to addCorrespondences())
                size_t measurements_ = 0;
        };
};
 
/**
 * This class implements advanced motion techniques (mainly with sub-pixel accuracy or binary masks) allowing to determine the motion (movement) of individual image points between two frames.
 * @tparam TMetricInteger The metric that is applied for measurements with pixel accuracy
 * @tparam TMetricFloat The metric that is applied for measurement with sub-pixel accuracy
 * @see AdvancedMotionSSD, AdvancedMotionZeroMeanSSD.
 * @ingroup cvadvanced
 */
template <typename TMetricInteger = SumSquareDifferences, typename TMetricFloat = AdvancedSumSquareDifferences>
class AdvancedMotionT : public AdvancedMotion
{
    public:
 
        /**
         * Tracks multiple groups of point correspondences bidirectionally between two frame pyramids with sub-pixel accuracy.
         * This function provides fine-grained control over the tracking process by accepting pre-configured PointCorrespondences groups.
         * Each group can have its own parameters (e.g., different pyramid layers, search radii, or sub-pixel iterations).
         * The points are tracked from the previous pyramid to the next pyramid (forward tracking), and then from the next pyramid back to the previous pyramid (backward tracking).
         * Point correspondences with inconsistent bidirectional tracking are marked as invalid.
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousPyramid The previous frame pyramid, must be valid
         * @param nextPyramid The next frame pyramid, with same pixel format and pixel origin as the previous pyramid, must be valid
         * @param pointCorrespondenceGroups The array of point correspondence groups to track, must be valid
         * @param numberCorrespondenceGroups The number of correspondence groups, with range [1, infinity)
         * @return True if succeeded; False otherwise
         * @tparam tChannels The number of channels both frame pyramids have, with range [1, 4]
         * @tparam tSize The size of the image patch used to determine motion, with range [3, infinity), must be odd
         */
        template <unsigned int tChannels, unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, PointCorrespondences* pointCorrespondenceGroups, const size_t numberCorrespondenceGroups);
 
        /**
         * Tracks a set of given points between two frames, with sub-pixel accuracy.
         * Actually, this function simply creates two frame pyramids and invokes the corresponding function needing frame pyramid as parameters.<br>
         * The motion is determined by application of an image patch centered around the point to be tracked.<br>
         * The points are tracked unidirectional (from the previous frame to the current frame).<br>
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousFrame The previous frame in which the previous points are located, must be valid
         * @param currentFrame The current frame, with same pixel format and pixel orientation as the previous frame, must be valid
         * @param previousPoints The points that are located in the previous frame (the points to be tracked from the previous frame to the current frame), with ranges [0, previousFrame.width())x[0, previousFrame.height())
         * @param roughPoints Rough locations of the previous points in the current frame (if known), otherwise simply provide the previous points again, one for each previous point, with ranges [0, currentFrame.width())x[0, currentFrame.height())
         * @param currentPoints Resulting current points, that have been tracked from the previous frame to the current frame, with ranges [0, currentFrame.width())x[0, currentFrame.height())
         * @param maximalOffset Maximal expected offset between two corresponding points in pixel, defined in the domain of previous/current frame, with range [1, infinity)
         * @param coarsestLayerRadius The search radius on the coarsest layer in pixel, with range [2, infinity)
         * @param downsamplingMode The downsampling mode that is applied to create the pyramid layers
         * @param subPixelIterations The number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param worker Optional worker object to distribute the computation
         * @param metricResults Optional resulting matching quality of the applied metric, nullptr if the results do not matter
         * @param metricIdentityResults Optional resulting matching quality of the applied metric between both frames at the identity location (the previous and rough position), nullptr if the results do not matter
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, with range [3, infinity), must be odd, recommended is 5, 7, 15, 31, or 63
         */
        template <unsigned int tSize>
        static bool trackPointsSubPixelMirroredBorder(const Frame& previousFrame, const Frame& currentFrame, const Vectors2& previousPoints, const Vectors2& roughPoints, Vectors2& currentPoints, const unsigned int maximalOffset, const unsigned int coarsestLayerRadius, const FramePyramid::DownsamplingMode downsamplingMode = FramePyramid::DM_FILTER_14641, const unsigned int subPixelIterations = 4u, Worker* worker = nullptr, MetricResults* metricResults = nullptr, MetricResults* metricIdentityResults = nullptr);
 
        /**
         * Tracks a set of given points between two frame pyramids, with sub-pixel accuracy.
         * The points are tracked unidirectional (from the previous frame to the current frame).<br>
         * The motion is determined by application of an image patch centered around the point to be tracked.<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * This function can apply a larger search radius on the coarsest pyramid layer than on all other layers.<br>
         * The search radius on the intermediate layers and on the finest layer is always 2.
         * @param previousPyramid The frame pyramid of the previous frame in which the previous points are located, must be valid
         * @param currentPyramid The frame pyramid of the current frame, with same pixel format and pixel origin as the previous frame pyramid, must be valid
         * @param previousPoints The points that are located in the previous frame (the points to be tracked from the previous frame to the current frame), with ranges [0, previousPyramid.finestWidth())x[0, previousPyramid.finestHeight())
         * @param roughPoints Rough locations of the previous points in the current frame (if known), otherwise simply provide the previous points again, one for each previous point, with ranges [0, currentPyramid.finestWidth())x[0, currentPyramid.finestHeight())
         * @param currentPoints Resulting current points, that have been tracked from the previous frame to the current frame, with ranges [0, currentPyramid.finestWidth())x[0, currentPyramid.finestHeight())
         * @param coarsestLayerRadius The search radius on the coarsest layer in pixel, with range [2, infinity)
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param worker Optional worker object to distribute the computation
         * @param metricResults Optional resulting matching quality of the applied metric, nullptr if the results do not matter
         * @param metricIdentityResults Optional resulting matching quality of the applied metric between both frames at the identity location (the previous and rough position), nullptr if the results do not matter
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, with range [3, infinity), must be odd, recommended is 5, 7, 15, 31, or 63
         */
        template <unsigned int tSize>
        static inline bool trackPointsSubPixelMirroredBorder(const FramePyramid& previousPyramid, const FramePyramid& currentPyramid, const Vectors2& previousPoints, const Vectors2& roughPoints, Vectors2& currentPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations = 4u, Worker* worker = nullptr, MetricResults* metricResults = nullptr, MetricResults* metricIdentityResults = nullptr);
 
        /**
         * Tracks a set of given points between two frame pyramids, with sub-pixel accuracy.
         * The points are tracked unidirectional (from the previous frame to the current frame).<br>
         * The motion is determined by application of an image patch centered around the point to be tracked.<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * This function can apply a larger search radius on the coarsest pyramid layer than on all other layers.<br>
         * The search radius on the intermediate layers and on the finest layer is always 2.<br>
         * This function has two template parameters: a) the number of frame channels and b) the patch size, both known at compile time.<br>
         * @param previousPyramid The frame pyramid of the previous frame in which the previous points are located, with pixel format matching with the number of frame channels 'tChannels', must be valid
         * @param currentPyramid The frame pyramid of the current frame, with same pixel format and pixel origin as the previous frame pyramid, must be valid
         * @param previousPoints The points that are located in the previous frame (the points to be tracked from the previous frame to the current frame), with ranges [0, previousPyramid.finestWidth())x[0, previousPyramid.finestHeight())
         * @param roughPoints Rough locations of the previous points in the current frame (if known), otherwise simply provide the previous points again, one for each previous point, with ranges [0, currentPyramid.finestWidth())x[0, currentPyramid.finestHeight())
         * @param currentPoints Resulting current points, that have been tracked from the previous frame to the current frame, with ranges [0, currentPyramid.finestWidth())x[0, currentPyramid.finestHeight())
         * @param coarsestLayerRadius The search radius on the coarsest layer in pixel, with range [2, infinity)
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param worker Optional worker object to distribute the computation
         * @param metricResults Optional resulting matching quality of the applied metric, nullptr if the results do not matter
         * @param metricIdentityResults Optional resulting matching quality of the applied metric between both frames at the identity location (the previous and rough position), nullptr if the results do not matter
         * @return True, if succeeded
         * @tparam tChannels The number of channels the frame pyramids have, with range [1, 4]
         * @tparam tSize Size of the image patch that is used to determine the motion, with range [3, infinity), must be odd, recommended is 5, 7, 15, 31, or 63
         */
        template <unsigned int tChannels, unsigned int tSize>
        static inline bool trackPointsSubPixelMirroredBorder(const FramePyramid& previousPyramid, const FramePyramid& currentPyramid, const Vectors2& previousPoints, const Vectors2& roughPoints, Vectors2& currentPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations = 4u, Worker* worker = nullptr, MetricResults* metricResults = nullptr, MetricResults* metricIdentityResults = nullptr);
 
        /**
         * Tracks a set of arbitrary (unknown) points between two frame pyramids with sub-pixel accuracy.
         * An optional sub-region can be specified shrinking the tracking area.<br>
         * Further, the arbitrary points can be separated into individual bin arrays allowing to distribute the points over the image area.<br>
         * The points are tracked bidirectional, thus the points are tracked from the previous to the current and from the current to the previous frame.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * The number of pyramid layers on which points are tracked can be specified. Both pyramids need to contain at least this number of layers.
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousPyramid Previous frame pyramid
         * @param nextPyramid Next frame pyramid, with same frame type as the previous frame
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints Resulting set of points that are located in the previous frame
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point (by index)
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param previousSubRegion An optional sub-region in that the points are tracked only
         * @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 strength parameter of the tracked feature points
         * @param worker Optional worker object to distribute the computation
         * @param trackingLayers Number of pyramid layers on which points are tracked
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         */
        template <unsigned int tSize>
        static bool trackArbitraryPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), const SubRegion& previousSubRegion = SubRegion(), const unsigned int horizontalBins = 0u, const unsigned int verticalBins = 0u, const unsigned int strength = 30u, Worker* worker = nullptr, const unsigned int trackingLayers = 1u);
 
        /**
         * Tracks a set of arbitrary (unknown) points between two frame pyramids with sub-pixel accuracy.
         * An optional sub-region can be specified shrinking the tracking area.<br>
         * Further, the arbitrary points can be separated into individual bin arrays allowing to distribute the points over the image area.<br>
         * The points are tracked bidirectional, thus the points are tracked from the previous to the current and from the current to the previous frame.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * The number of pyramid layers on which points are tracked can be specified.
         * @param previousFrame Previous frame
         * @param nextFrame Next frame, with same frame type as the previous frame
         * @param maximalOffset Maximal offset between two corresponding points, in pixel
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints Resulting set of points that are located in the previous frame
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point (by index)
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param previousSubRegion An optional sub-region in that the points are tracked only
         * @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 strength parameter of the tracked feature points
         * @param downsamplingMode The downsampling mode that is applied to create the pyramid layers
         * @param worker Optional worker object to distribute the computation
         * @param trackingLayers Number of pyramid layers on which points are tracked
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         */
        template <unsigned int tSize>
        static bool trackArbitraryPointsBidirectionalSubPixelMirroredBorder(const Frame& previousFrame, const Frame& nextFrame, const unsigned int maximalOffset, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), const SubRegion& previousSubRegion = SubRegion(), const unsigned int horizontalBins = 0u, const unsigned int verticalBins = 0u, const unsigned int strength = 30u, const FramePyramid::DownsamplingMode downsamplingMode = FramePyramid::DM_FILTER_14641, Worker* worker = nullptr, const unsigned int trackingLayers = 1u);
 
        /**
         * Tracks a set of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous pyramid to the next pyramid and from the next pyramid back to the previous pyramid.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousPyramid The previous frame pyramid, must be valid
         * @param nextPyramid The next frame pyramid, with same pixel format and pixel origin as the previous pyramid, must be valid
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints A set of points that are located in the previous frame, this set may be reduced as some points may be discarded (if no validIndices parameter is specified)
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param validIndices Optional vector receiving the indices of the valid point correspondences. Beware: If this parameter is defined, the resulting previousPoints and nextImagePoints have to be explicitly filtered by application of the indices
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         * @see trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations().
         */
        template <unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), Worker* worker = nullptr, Indices32* validIndices = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Tracks a set of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous to the current and from the current to the previous frame.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * This function has two template parameters: a) the number of frame channels and b) the patch size, both known at compile time.
         * @param previousPyramid Previous frame pyramid with pixel format matching with the number of frame channels 'tChannels', must be valid
         * @param nextPyramid Next frame pyramid, with same frame type as the previous pyramid, must be valid
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints A set of points that are located in the previous frame, this set may be reduced as some points may be discarded (if no validIndices parameter is specified)
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param validIndices Optional vector receiving the indices of the valid point correspondences. Beware: If this parameter is defined, the resulting previousPoints and nextImagePoints have to be explicitly filtered by application of the indices
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tChannels The number of channels both frame pyramids have, with range [1, 4]
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         * @see trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations().
         */
        template <unsigned int tChannels, unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), Worker* worker = nullptr, Indices32* validIndices = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Tracks a set of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous pyramid to the next pyramid and from the next pyramid back to the previous pyramid.<br>
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousPyramid The previous frame pyramid, must be valid
         * @param nextPyramid The next frame pyramid, with same pixel format and pixel origin as the previous pyramid, must be valid
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints The image points located in the previous frame
         * @param nextImagePoints The resulting points in the next frame, each point corresponds to one previous point
         * @param validCorrespondences Resulting binary mask for all provided correspondences (0x00 = invalid, 0x01 = valid)
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         * @see trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations().
         */
        template <unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, const Vectors2& previousImagePoints, Vectors2& nextImagePoints, std::vector<uint8_t>& validCorrespondences, const Scalar maximalSqrError = Scalar(0.9 * 0.9), Worker* worker = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Tracks a set of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous to the current and from the current to the previous frame.<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * This function has two template parameters: a) the number of frame channels and b) the patch size, both known at compile time.
         * @param previousPyramid Previous frame pyramid with pixel format matching with the number of frame channels 'tChannels', must be valid
         * @param nextPyramid Next frame pyramid, with same frame type as the previous pyramid, must be valid
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints The image points located in the previous frame
         * @param nextImagePoints The resulting points in the next frame, each point corresponds to one previous point
         * @param validCorrespondences Resulting binary mask for all provided correspondences (0x00 = invalid, 0x01 = valid)
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tChannels The number of channels both frame pyramids have, with range [1, 4]
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         * @see trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations().
         */
        template <unsigned int tChannels, unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, const Vectors2& previousImagePoints, Vectors2& nextImagePoints, std::vector<uint8_t>& validCorrespondences, const Scalar maximalSqrError = Scalar(0.9 * 0.9), Worker* worker = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Tracks a set of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous to the current and from the current to the previous frame.<br>
         * This function uses a rough guess for the next image points allowing to improve the tracking quality as long as the rough guess is better than no guess.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousPyramid Previous frame pyramid, must be valid
         * @param nextPyramid Next frame pyramid, with same pixel format and pixel orientation as the previous frame, must be valid
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints A set of points that are located in the previous frame, this set may be reduced as some points may be discarded (if no validIndices parameter is specified)
         * @param roughNextImagePoints The rough locations of the previous image points in the current next frame, one for each previous image point
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param validIndices Optional vector receiving the indices of the valid point correspondences. Beware: If this parameter is defined, the resulting previousPoints and nextImagePoints have to be explicitly filtered by application of the indices
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         * @see trackPointsBidirectionalSubPixelMirroredBorder().
         */
        template <unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, const Vectors2& roughNextImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), Worker* worker = nullptr, Indices32* validIndices = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Tracks a set of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous to the current and from the current to the previous frame.<br>
         * This function uses a rough guess for the next image points allowing to improve the tracking quality as long as the rough guess is better than no guess.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * This function has two template parameters: a) the number of frame channels and b) the patch size, both known at compile time.
         * @param previousPyramid Previous frame pyramid with pixel format matching with the number of frame channels 'tChannels', must be valid
         * @param nextPyramid Next frame pyramid, with same pixel format and pixel orientation as the previous frame, must be valid
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints A set of points that are located in the previous frame, this set may be reduced as some points may be discarded (if no validIndices parameter is specified)
         * @param roughNextImagePoints The rough locations of the previous image points in the current next frame, one for each previous image point
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param validIndices Optional vector receiving the indices of the valid point correspondences. Beware: If this parameter is defined, the resulting previousPoints and nextImagePoints have to be explicitly filtered by application of the indices
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tChannels The number of channels both frame pyramids have, with range [1, 4]
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         * @see trackPointsBidirectionalSubPixelMirroredBorder().
         */
        template <unsigned int tChannels, unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, const Vectors2& roughNextImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), Worker* worker = nullptr, Indices32* validIndices = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Tracks a set of given points between two frames with sub-pixel accuracy.
         * The points are tracked bidirectional, thus the points are tracked from the previous frame to the next frame and from the next frame back to the previous frame.<br>
         * Point correspondences with an inaccurate bidirectional tracking are discarded.<br>
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousFrame The previous frame, must be valid
         * @param nextFrame The next frame, with same pixel format and pixel origin as the previous frame, must be valid
         * @param maximalOffset Maximal offset between two corresponding points, in pixel
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param previousImagePoints A set of points that are located in the previous frame, this set may be reduced as some points may be discarded
         * @param nextImagePoints Resulting points in the next frame, each point corresponds to one previous point
         * @param maximalSqrError Maximal square distance between forward and backward tracking for a valid point
         * @param worker Optional worker object to distribute the computation
         * @param downsamplingMode The downsampling mode that is applied to create the pyramid layers
         * @param validIndices Optional vector receiving the indices of the valid point correspondences
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @return True, if succeeded
         * @tparam tSize Size of the image patch that is used to determine the motion, must be odd
         */
        template <unsigned int tSize>
        static bool trackPointsBidirectionalSubPixelMirroredBorder(const Frame& previousFrame, const Frame& nextFrame, const unsigned int maximalOffset, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError = Scalar(0.9 * 0.9), const FramePyramid::DownsamplingMode downsamplingMode = FramePyramid::DM_FILTER_14641, Worker* worker = nullptr, Indices32* validIndices = nullptr, const unsigned int subPixelIterations = 4u);
 
        /**
         * Detects and tracks reliable arbitrary reference points between two frames.
         * The reference points are distributed into an array to receive wide spread points.
         * @param previousPyramid Frame pyramid of the previous image
         * @param currentPyramid Frame pyramid of the current image
         * @param previousReferencePoints Resulting reliable reference points inside the previous frame
         * @param currentReferencePoints Resulting and tracked reliable reference points inside the current frame
         * @param horizontalBins Number of horizontal bins to subdivide the specified bounding box
         * @param verticalBins Number of vertical bins to subdivide the specified bounding box
         * @param boundingBox Optional bounding box to shrink the search area of reliable tracking points
         * @param maskFrame Optional mask frame allowing to use only reference points outside a given mask
         * @param worker Optional worker object to distribute the computation
         * @return True, if succeeded
         * @tparam tSize Size of the tracking patch in pixels
         */
        template <unsigned int tSize>
        static bool trackReliableReferencePoints(const FramePyramid& previousPyramid, const FramePyramid& currentPyramid, Vectors2& previousReferencePoints, Vectors2& currentReferencePoints, const unsigned int horizontalBins = 16u, const unsigned int verticalBins = 16u, const PixelBoundingBox& boundingBox = PixelBoundingBox(), const Frame& maskFrame = Frame(), Worker* worker = nullptr);
 
        /**
         * Tracks the location of one given 2D point from one image to another image with sub-pixel precision by application of an image patch without the use of a multi-resolution approach.
         * Patch pixels outside the frame are mirrored into the frame before compared.
         * @param frame0 The first frame, must be valid
         * @param frame1 The second frame, must be valid
         * @param width0 Width of the first frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param height0 Height of the first frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param width1 Width of the second frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param height1 Height of the second frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param frame0PaddingElements The number of padding elements at the end of each first frame row, in elements, with range [0, infinity)
         * @param frame1PaddingElements The number of padding elements at the end of each second frame row, in elements, with range [0, infinity)
         * @param position0 Position in the first frame, with range [0, width)x[0, height)
         * @param radiusX The search radius in horizontal direction, in pixel, with range [0, width - 1]
         * @param radiusY The search radius in vertical direction, in pixel, with range [0, height - 1]
         * @param rough1 The optional rough guess of the point in the second frame, (Numeric::maxValue(), Numeric::maxValue()) if unknown
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param metricResult Optional resulting matching quality of the applied metric, nullptr if the result does not matter
         * @param metricIdentityResult Optional resulting matching quality of the applied metric between both frames at the identity location (the previous and rough position), nullptr if the result does not matter
         * @return Best matching position in the second frame
         * @tparam tChannels The number of frame channels, with range [1, infinity)
         * @tparam tPatchSize The size of the square patch (the edge length) in pixel, with range [3, infinity), must be odd, recommended is 5, 7, 15, 31, or 63
         */
        template <unsigned int tChannels, unsigned int tPatchSize>
        static Vector2 trackPointSubPixelMirroredBorder(const uint8_t* frame0, const uint8_t* frame1, const unsigned int width0, const unsigned int height0, const unsigned int width1, const unsigned int height1, const unsigned int frame0PaddingElements, const unsigned int frame1PaddingElements, const Vector2& position0, const unsigned int radiusX, const unsigned int radiusY, const Vector2& rough1 = Vector2(Numeric::maxValue(), Numeric::maxValue()), const unsigned int subPixelIterations = 4u, uint32_t* metricResult = nullptr, uint32_t* metricIdentityResult = nullptr);
 
        /**
         * Tracks the location of one given 2D point from one image to another image with sub-pixel precision by application of an image patch without the use of a multi-resolution approach.
         * Patch pixels outside the frame are mirrored into the frame before compared.
         * @param frame0 The first frame, must be valid
         * @param frame1 The second frame, must be valid
         * @param channels The number of frame channels, with range [1, 4]
         * @param width0 Width of the first frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param height0 Height of the first frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param width1 Width of the second frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param height1 Height of the second frame in pixel, with range [tPatchSize / 2u, infinity)
         * @param frame0PaddingElements The number of padding elements at the end of each first frame row, in elements, with range [0, infinity)
         * @param frame1PaddingElements The number of padding elements at the end of each second frame row, in elements, with range [0, infinity)
         * @param position0 Position in the first frame, with range [0, width)x[0, height)
         * @param radiusX The search radius in horizontal direction, in pixel, with range [0, width - 1]
         * @param radiusY The search radius in vertical direction, in pixel, with range [0, height - 1]
         * @param rough1 The optional rough guess of the point in the second frame, (Numeric::maxValue(), Numeric::maxValue()) if unknown
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param metricResult Optional resulting matching quality of the applied metric, nullptr if the result does not matter
         * @param metricIdentityResult Optional resulting matching quality of the applied metric in both frames at the same previous position, nullptr if the results do not matter
         * @return Best matching position in the second frame
         * @tparam tPatchSize The size of the square patch (the edge length) in pixel, with range [3, infinity), must be odd, recommended is 5, 7, 15, 31, or 63
         */
        template <unsigned int tPatchSize>
        static inline Vector2 trackPointSubPixelMirroredBorder(const uint8_t* frame0, const uint8_t* frame1, const unsigned int channels, const unsigned int width0, const unsigned int height0, const unsigned int width1, const unsigned int height1, const unsigned int frame0PaddingElements, const unsigned int frame1PaddingElements, const Vector2& position0, const unsigned int radiusX, const unsigned int radiusY, const Vector2& rough1 = Vector2(Numeric::maxValue(), Numeric::maxValue()), const unsigned int subPixelIterations = 4u, uint32_t* metricResult = nullptr, uint32_t* metricIdentityResult = nullptr);
 
    private:
 
        /**
         * Tracks the location of one given 2D point from one image to another image with sub-pixel precision by application of an image patch without the use of a multi-resolution approach.
         * Patch pixels outside the frame are mirrored into the frame before compared.
         * @param buffer0 The buffer containing the (interpolated) first image patch as one continuous memory block, must be valid
         * @param frame1 The second image, with same pixel format as the buffer, must be valid
         * @param width1 Width of the second frame in pixel, with range [tSize, infinity)
         * @param height1 Height of the second frame in pixel, with range [tSize, infinity)
         * @param frame1PaddingElements The number of padding elements at the end of each second image row, in elements, with range [0, infinity)
         * @param roughPosition1 The rough position in the second frame, with range [0, width1)x[0, height1)
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param metricResult Optional resulting result of the applied metric, nullptr if the result does not matter
         * @return Best matching position in the second frame
         * @tparam tChannels The number of data channel each frame has, with range [1, infinity)
         * @tparam tPatchSize The size of the square patch (the edge length) in pixel, with range [3, infinity), must be odd, recommended is 5, 7, 15, 31, or 63
         */
        template <unsigned int tChannels, unsigned int tPatchSize>
        static Vector2 trackPointBufferSubPixelMirroredBorder(const uint8_t* buffer0, const uint8_t* frame1, const unsigned int width1, const unsigned int height1, const unsigned int frame1PaddingElements, const Vector2& roughPosition1, const unsigned int subPixelIterations, uint32_t* metricResult = nullptr);
 
        /**
         * Tracks a subset of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked unidirectional (from the previous frame to the current frame).<br>
         * If a point is near the frame border, a mirrored image patch is applied.
         * @param previousPyramid The previous frame pyramid, must be valid
         * @param nextPyramid The next frame pyramid, with same pixel format and pixel orientation as the previous frame pyramid, must be valid
         * @param numberLayers The number of pyramid layers that will be used for tracking, with range [1, min(pyramids->layers(), 'coarsest layer that match with the patch size')]
         * @param previousPoints A set of points that are located in the previous frame
         * @param roughNextPoints The rough points located in the finest pyramid layer of the next pyramid (if known), nullptr if unknown
         * @param nextPoints Resulting tracked points located in the finest layer of the next pyramid
         * @param coarsestLayerRadius The search radius on the coarsest pyramid layer, with range [2, infinity)
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param metricResults Optional resulting results of the applied metric, nullptr if the results do not matter
         * @param metricIdentityResults Optional resulting results of the applied metric in both frames at the same previous position, nullptr if the results do not matter
         * @param firstPoint First point to be applied
         * @param numberPoints Number of points to be applied
         * @tparam tSize The size of the applied image patches in pixel, with range [1, infinity), must be odd
         */
        template <unsigned int tSize>
        static void trackPointsSubPixelMirroredBorderSubset(const FramePyramid* previousPyramid, const FramePyramid* nextPyramid, const unsigned int numberLayers, const Vectors2* previousPoints, const Vectors2* roughNextPoints, Vectors2* nextPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations, unsigned int* metricResults, unsigned int* metricIdentityResults, const unsigned int firstPoint, const unsigned int numberPoints);
 
        /**
         * Tracks a subset of given points between two frame pyramids with sub-pixel accuracy.
         * The points are tracked unidirectional (from the previous frame to the current frame).<br>
         * If a point is near the frame border, a mirrored image patch is applied.<br>
         * This function has two template parameters: a) the number of frame channels and b) the patch size, both known at compile time.<br>
         * @param previousPyramid Previous frame pyramid, must be valid
         * @param currentPyramid Current frame pyramid, with same pixel format and pixel orientation as the previous frame pyramid, must be valid
         * @param numberLayers The number of pyramid layers that will be used for tracking, with range [1, min(pyramids->layers(), 'coarsest layer that match with the patch size')]
         * @param previousPoints A set of points that are located in the previous frame
         * @param roughPoints The rough points in the current frame (if known), otherwise the previousPoints may be provided
         * @param currentPoints Resulting current points, that have been tracking between the two points
         * @param coarsestLayerRadius The search radius on the coarsest layer, with range [2, infinity)
         * @param subPixelIterations Number of sub-pixel iterations that will be applied, each iteration doubles the sub-pixel accuracy, with range [1, infinity)
         * @param metricResults Optional resulting results of the applied metric, nullptr if the results do not matter
         * @param metricIdentityResults Optional resulting results of the applied metric in both frames at the same previous position, nullptr if the results do not matter
         * @param firstPoint First point to be applied
         * @param numberPoints Number of points to be applied
         * @tparam tChannels The number of channels both frame pyramids have, with range [1, 4]
         * @tparam tSize Defines the size of the applied image patches in pixel, must be odd
         */
        template <unsigned int tChannels, unsigned int tSize>
        static void trackPointsSubPixelMirroredBorderSubset(const FramePyramid* previousPyramid, const FramePyramid* currentPyramid, const unsigned int numberLayers, const Vectors2* previousPoints, const Vectors2* roughPoints, Vectors2* currentPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations, unsigned int* metricResults, unsigned int* metricIdentityResults, const unsigned int firstPoint, const unsigned int numberPoints);
};
 
inline AdvancedMotion::PointCorrespondences::PointCorrespondences(const Vector2* previousPoints, Vector2* predictedNextPoints, uint8_t* validCorrespondences, const size_t correspondences, const unsigned int pyramidLayers, const unsigned int coarsestLayerRadius, const Scalar maximalError, const unsigned int subPixelIterations) :
    previousPoints_(previousPoints),
    nextPoints_(predictedNextPoints),
    validCorrespondences_(validCorrespondences),
    correspondences_(correspondences),
    pyramidLayers_(pyramidLayers),
    coarsestLayerRadius_(coarsestLayerRadius),
    subPixelIterations_(subPixelIterations)
{
    ocean_assert(previousPoints_ != nullptr);
    ocean_assert(nextPoints_ != nullptr);
    ocean_assert(validCorrespondences_ != nullptr);
 
    ocean_assert(previousPoints_ != nextPoints_); // must not point to the same memory
 
    ocean_assert(pyramidLayers_ != 0u);
 
    ocean_assert(maximalError >= 0);
    maximalSqrError_ = Numeric::sqr(maximalError);
 
    maximalSqrErrorLayer_ = Numeric::sqr(Scalar(2) + maximalError); // search radius 2 plus maximal error
}
 
inline const Vector2& AdvancedMotion::PointCorrespondences::previousPosition(const size_t pointIndex) const
{
    ocean_assert(layerIndex_ == 0u);
 
    ocean_assert(pointIndex < correspondences_);
 
    const Vector2& previousPoint = forwardTracking_ ? previousPoints_[pointIndex] : nextPoints_[pointIndex];
 
    ocean_assert(previousPoint.x() >= Scalar(0) && previousPoint.x() < Scalar(previousLayerWidth_));
    ocean_assert(previousPoint.y() >= Scalar(0) && previousPoint.y() < Scalar(previousLayerHeight_));
 
    return previousPoint;
}
 
inline CV::PixelPosition AdvancedMotion::PointCorrespondences::previousPositionDownsampled(const size_t pointIndex) const
{
    ocean_assert(layerIndex_ != (unsigned int)(-1));
    ocean_assert(layerIndex_ != 0u);
 
    ocean_assert(pointIndex < correspondences_);
    ocean_assert(invLayerFactor_ > Scalar(0));
 
    const Vector2& previousPoint = forwardTracking_ ? previousPoints_[pointIndex] : nextPoints_[pointIndex];
 
    const int32_t downsampledX = Numeric::round32(previousPoint.x() * invLayerFactor_);
    const int32_t downsampledY = Numeric::round32(previousPoint.y() * invLayerFactor_);
 
    const int32_t clampedX = std::min(downsampledX, int32_t(previousLayerWidth_) - 1);
    const int32_t clampedY = std::min(downsampledY, int32_t(previousLayerHeight_) - 1);
 
    ocean_assert(clampedX >= 0 && clampedY >= 0);
 
    return CV::PixelPosition((unsigned int)(clampedX), (unsigned int)(clampedY));
}
 
inline CV::PixelPosition AdvancedMotion::PointCorrespondences::predictedNextPositionDownsampled(const size_t pointIndex) const
{
    ocean_assert(layerIndex_ != (unsigned int)(-1));
    ocean_assert(layerIndex_ != 0u);
 
    ocean_assert(pointIndex < correspondences_);
 
    const Vector2& predictedNextPoint = forwardTracking_ ? nextPoints_[pointIndex] : internalBackwardNextPoints_[pointIndex];
 
    ocean_assert(predictedNextPoint.x() == Scalar(Numeric::round32(predictedNextPoint.x())));
    ocean_assert(predictedNextPoint.y() == Scalar(Numeric::round32(predictedNextPoint.y())));
 
    ocean_assert(predictedNextPoint.x() >= Scalar(0) && predictedNextPoint.x() < Scalar(nextLayerWidth_));
    ocean_assert(predictedNextPoint.y() >= Scalar(0) && predictedNextPoint.y() < Scalar(nextLayerHeight_));
 
    return CV::PixelPosition((unsigned int)(predictedNextPoint.x()), (unsigned int)(predictedNextPoint.y()));
}
 
inline const Vector2& AdvancedMotion::PointCorrespondences::predictedNextPosition(const size_t pointIndex) const
{
    ocean_assert(layerIndex_ == 0u);
 
    ocean_assert(pointIndex < correspondences_);
 
    if (forwardTracking_)
    {
        return nextPoints_[pointIndex];
    }
    else
    {
        return internalBackwardNextPoints_[pointIndex];
    }
}
 
inline bool AdvancedMotion::PointCorrespondences::isPointValid(const size_t pointIndex) const
{
    ocean_assert(layerIndex_ != (unsigned int)(-1));
 
    ocean_assert(pointIndex < correspondences_);
 
    ocean_assert(validCorrespondences_ != nullptr);
    return validCorrespondences_[pointIndex] != 0u;
}
 
inline unsigned int AdvancedMotion::PointCorrespondences::pyramidLayers() const
{
    ocean_assert(pyramidLayers_ != 0u);
 
    return pyramidLayers_;
}
 
inline unsigned int AdvancedMotion::PointCorrespondences::layerRadius() const
{
    return layerRadius_;
}
 
inline unsigned int AdvancedMotion::PointCorrespondences::subPixelIterations() const
{
    ocean_assert(layerIndex_ == 0u);
 
    return subPixelIterations_;
}
 
inline size_t AdvancedMotion::PointCorrespondences::size() const
{
    return correspondences_;
}
 
inline bool AdvancedMotion::PointCorrespondences::isValid() const
{
    return previousPoints_ != nullptr;
}
 
inline size_t AdvancedMotion::TrackingStatistic::measurements() const
{
    return measurements_;
}
 
inline bool AdvancedMotion::TrackingStatistic::isValid() const
{
    return width_ >= 1u && height_ >= 1u;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, PointCorrespondences* pointCorrespondenceGroups, const size_t numberCorrespondenceGroups)
{
    static_assert(tChannels >= 1u, "Invalid channel number!");
    static_assert(tSize >= 1u, "Invalid patch size!");
 
    ocean_assert(previousPyramid && nextPyramid);
    ocean_assert(previousPyramid.frameType().channels() == tChannels);
    ocean_assert(previousPyramid.frameType().numberPlanes() == 1u);
    ocean_assert(previousPyramid.frameType().isPixelFormatCompatible(nextPyramid.frameType().pixelFormat()));
    ocean_assert(previousPyramid.frameType().pixelOrigin() == nextPyramid.frameType().pixelOrigin());
 
    if (!previousPyramid.isValid() || !nextPyramid.isValid())
    {
        return false;
    }
 
    if (previousPyramid.frameType().channels() != tChannels || previousPyramid.frameType().numberPlanes() != 1u)
    {
        return false;
    }
 
    if (!previousPyramid.frameType().isPixelFormatCompatible(nextPyramid.frameType().pixelFormat()) || previousPyramid.frameType().pixelOrigin() != nextPyramid.frameType().pixelOrigin())
    {
        return false;
    }
 
    ocean_assert(pointCorrespondenceGroups != nullptr && numberCorrespondenceGroups >= 1);
 
    if (pointCorrespondenceGroups == nullptr || numberCorrespondenceGroups == 0)
    {
        return false;
    }
 
    const unsigned int coarsestPyramidLayerIndex = PointCorrespondences::coarsestPyramidLayer(previousPyramid, nextPyramid, pointCorrespondenceGroups, numberCorrespondenceGroups);
 
    ocean_assert(coarsestPyramidLayerIndex < previousPyramid.layers());
    ocean_assert(coarsestPyramidLayerIndex < nextPyramid.layers());
 
    // forward point tracking
 
    for (size_t nCorrespondenceGroup = 0; nCorrespondenceGroup < numberCorrespondenceGroups; ++nCorrespondenceGroup)
    {
        PointCorrespondences& correspondences = pointCorrespondenceGroups[nCorrespondenceGroup];
 
        correspondences.startForwardTracking(previousPyramid, nextPyramid);
    }
 
    for (unsigned int layerIndex = coarsestPyramidLayerIndex; layerIndex < previousPyramid.layers(); --layerIndex)
    {
        for (size_t nCorrespondenceGroup = 0; nCorrespondenceGroup < numberCorrespondenceGroups; ++nCorrespondenceGroup)
        {
            PointCorrespondences& correspondences = pointCorrespondenceGroups[nCorrespondenceGroup];
 
            if (!correspondences.startLayer(layerIndex, previousPyramid, nextPyramid))
            {
                continue;
            }
 
            const Frame& previousFrame = previousPyramid[layerIndex];
            const Frame& nextFrame = nextPyramid[layerIndex];
 
            const uint8_t* const previousFrameData = previousFrame.constdata<uint8_t>();
            const uint8_t* const nextFrameData = nextFrame.constdata<uint8_t>();
 
            const unsigned int previousFramePaddingElements = previousFrame.paddingElements();
            const unsigned int nextFramePaddingElements = nextFrame.paddingElements();
 
            const unsigned int previousWidth = previousFrame.width();
            const unsigned int previousHeight = previousFrame.height();
 
            const unsigned int nextWidth = nextFrame.width();
            const unsigned int nextHeight = nextFrame.height();
 
            const unsigned int layerRadius = correspondences.layerRadius();
 
            if (layerIndex == 0u)
            {
                // sub-pixel-precise tracking
 
                const unsigned int subPixelIterations = correspondences.subPixelIterations();
 
                for (size_t nPoint = 0; nPoint < correspondences.size(); ++nPoint)
                {
                    const Vector2& previousPosition = correspondences.previousPosition(nPoint);
                    Vector2 nextPosition = correspondences.predictedNextPosition(nPoint);
 
                    const Vector2 position = trackPointSubPixelMirroredBorder<tChannels, tSize>(previousFrameData, nextFrameData, previousWidth, previousHeight, nextWidth, nextHeight, previousFramePaddingElements, nextFramePaddingElements, previousPosition, layerRadius, layerRadius, nextPosition, subPixelIterations);
 
                    correspondences.propagateNextPosition(nPoint, position);
                }
            }
            else
            {
                // pixel-precise tracking
 
                for (size_t nPoint = 0; nPoint < correspondences.size(); ++nPoint)
                {
                    const CV::PixelPosition previousPosition = correspondences.previousPositionDownsampled(nPoint);
                    const CV::PixelPosition predictedNextPosition = correspondences.predictedNextPositionDownsampled(nPoint);
 
                    const PixelPosition actualNextPoint = MotionT<TMetricInteger>::template pointMotionInFrameMirroredBorder<tChannels, tSize>(previousFrameData, nextFrameData, previousWidth, previousHeight, nextWidth, nextHeight, previousPosition, layerRadius, layerRadius, previousFramePaddingElements, nextFramePaddingElements, predictedNextPosition);
 
                    correspondences.propagateNextPositionDownsampled(nPoint, actualNextPoint);
                }
            }
        }
    }
 
    // backward point tracking
 
    const CV::FramePyramid& backwardPreviousPyramid = nextPyramid; // an alias for the backward motion
    const CV::FramePyramid& backwardNextPyramid = previousPyramid;
 
    for (size_t nCorrespondenceGroup = 0; nCorrespondenceGroup < numberCorrespondenceGroups; ++nCorrespondenceGroup)
    {
        PointCorrespondences& correspondences = pointCorrespondenceGroups[nCorrespondenceGroup];
 
        correspondences.startBackwardTracking(backwardPreviousPyramid, backwardNextPyramid);
    }
 
    for (unsigned int layerIndex = coarsestPyramidLayerIndex; layerIndex < previousPyramid.layers(); --layerIndex)
    {
        for (size_t nCorrespondenceGroup = 0; nCorrespondenceGroup < numberCorrespondenceGroups; ++nCorrespondenceGroup)
        {
            PointCorrespondences& correspondences = pointCorrespondenceGroups[nCorrespondenceGroup];
 
            if (!correspondences.startLayer(layerIndex, backwardPreviousPyramid, backwardNextPyramid))
            {
                continue;
            }
 
            const Frame& previousFrame = backwardPreviousPyramid[layerIndex];
            const Frame& nextFrame = backwardNextPyramid[layerIndex];
 
            const uint8_t* const previousFrameData = previousFrame.constdata<uint8_t>();
            const uint8_t* const nextFrameData = nextFrame.constdata<uint8_t>();
 
            const unsigned int previousFramePaddingElements = previousFrame.paddingElements();
            const unsigned int nextFramePaddingElements = nextFrame.paddingElements();
 
            const unsigned int previousWidth = previousFrame.width();
            const unsigned int previousHeight = previousFrame.height();
 
            const unsigned int nextWidth = nextFrame.width();
            const unsigned int nextHeight = nextFrame.height();
 
            const unsigned int layerRadius = correspondences.layerRadius();
 
            if (layerIndex == 0u)
            {
                // sub-pixel-precise tracking
 
                const unsigned int subPixelIterations = correspondences.subPixelIterations();
 
                for (size_t nPoint = 0; nPoint < correspondences.size(); ++nPoint)
                {
                    if (correspondences.isPointValid(nPoint))
                    {
                        const Vector2& previousPosition = correspondences.previousPosition(nPoint);
                        Vector2 nextPosition = correspondences.predictedNextPosition(nPoint);
 
                        const Vector2 position = trackPointSubPixelMirroredBorder<tChannels, tSize>(previousFrameData, nextFrameData, previousWidth, previousHeight, nextWidth, nextHeight, previousFramePaddingElements, nextFramePaddingElements, previousPosition, layerRadius, layerRadius, nextPosition, subPixelIterations);
 
                        correspondences.propagateNextPosition(nPoint, position);
                    }
                }
            }
            else
            {
                // pixel-precise tracking
 
                for (size_t nPoint = 0; nPoint < correspondences.size(); ++nPoint)
                {
                    if (correspondences.isPointValid(nPoint))
                    {
                        const CV::PixelPosition previousPosition = correspondences.previousPositionDownsampled(nPoint);
                        const CV::PixelPosition predictedNextPosition = correspondences.predictedNextPositionDownsampled(nPoint);
 
                        const PixelPosition actualNextPoint = MotionT<TMetricInteger>::template pointMotionInFrameMirroredBorder<tChannels, tSize>(previousFrameData, nextFrameData, previousWidth, previousHeight, nextWidth, nextHeight, previousPosition, layerRadius, layerRadius, previousFramePaddingElements, nextFramePaddingElements, predictedNextPosition);
 
                        correspondences.propagateNextPositionDownsampled(nPoint, actualNextPoint);
                    }
                }
            }
        }
    }
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsSubPixelMirroredBorder(const Frame& previousFrame, const Frame& currentFrame, const Vectors2& previousPoints, const Vectors2& roughPoints, Vectors2& currentPoints, const unsigned int maximalOffset, const unsigned int coarsestLayerRadius, const FramePyramid::DownsamplingMode downsamplingMode, const unsigned int subPixelIterations, Worker* worker, MetricResults* metricResults, MetricResults* metricIdentityResults)
{
    static_assert(tSize % 2u == 1u, "Invalid image patch size, must be odd!");
    static_assert(tSize >= 3u, "Invalid image patch size, must be larger than 2!");
 
    ocean_assert(previousFrame && currentFrame);
 
    ocean_assert(previousFrame.frameType().pixelFormat() == currentFrame.frameType().pixelFormat());
    ocean_assert(previousFrame.frameType().pixelOrigin() == currentFrame.frameType().pixelOrigin());
 
    ocean_assert(previousPoints.size() == roughPoints.size());
 
    ocean_assert(maximalOffset >= 1u);
    ocean_assert(subPixelIterations >= 1u);
 
    const unsigned int idealLayers = FramePyramid::idealLayers(previousFrame.width(), previousFrame.height(), (tSize / 2u) * 4u, (tSize / 2u) * 4u, 2u, maximalOffset, coarsestLayerRadius);
    ocean_assert(idealLayers >= 1u);
 
    if (idealLayers == 0u)
    {
        return false;
    }
 
    const FramePyramid previousPyramid(previousFrame, downsamplingMode, idealLayers, false /*copyFirstLayer*/, worker);
    const FramePyramid currentPyramid(currentFrame, downsamplingMode, idealLayers, false /*copyFirstLayer*/, worker);
 
    return trackPointsSubPixelMirroredBorder<tSize>(previousPyramid, currentPyramid, previousPoints, roughPoints, currentPoints, coarsestLayerRadius, subPixelIterations, worker, metricResults, metricIdentityResults);
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
inline bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsSubPixelMirroredBorder(const FramePyramid& previousPyramid, const FramePyramid& currentPyramid, const Vectors2& previousPoints, const Vectors2& roughPoints, Vectors2& currentPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations, Worker* worker, MetricResults* metricResults, MetricResults* metricIdentityResults)
{
    static_assert(tSize % 2u == 1u, "Invalid image patch size, must be odd!");
    static_assert(tSize >= 3u, "Invalid image patch size, must be larger than 2!");
 
    ocean_assert(previousPyramid.frameType().pixelFormat() == currentPyramid.frameType().pixelFormat());
    ocean_assert(previousPyramid.frameType().pixelOrigin() == currentPyramid.frameType().pixelOrigin());
 
    ocean_assert(previousPoints.size() == roughPoints.size());
 
    ocean_assert(subPixelIterations >= 1u);
 
    const unsigned int idealLayers = CV::FramePyramid::idealLayers(previousPyramid.finestWidth(), previousPyramid.finestHeight(), (tSize / 2u) * 4u, (tSize / 2u) * 4u, 2u);
    const unsigned int numberLayers = min(min(previousPyramid.layers(), currentPyramid.layers()), idealLayers);
 
    if (numberLayers == 0u)
    {
        return false;
    }
 
    currentPoints.resize(previousPoints.size());
 
    if (metricResults != nullptr)
    {
        metricResults->resize(previousPoints.size());
    }
 
    if (metricIdentityResults != nullptr)
    {
        metricIdentityResults->resize(previousPoints.size());
    }
 
    if (worker != nullptr)
    {
        worker->executeFunction(Worker::Function::createStatic(&AdvancedMotionT::trackPointsSubPixelMirroredBorderSubset<tSize>, &previousPyramid, &currentPyramid, numberLayers, &previousPoints, &roughPoints, &currentPoints, coarsestLayerRadius, subPixelIterations, metricResults ? metricResults->data() : nullptr, metricIdentityResults ? metricIdentityResults->data() : nullptr, 0u, 0u), 0u, (unsigned int)(previousPoints.size()));
    }
    else
    {
        trackPointsSubPixelMirroredBorderSubset<tSize>(&previousPyramid, &currentPyramid, numberLayers, &previousPoints, &roughPoints, &currentPoints, coarsestLayerRadius, subPixelIterations, metricResults ? metricResults->data() : nullptr, metricIdentityResults ? metricIdentityResults->data() : nullptr, 0u, (unsigned int)(previousPoints.size()));
    }
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tSize>
inline bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsSubPixelMirroredBorder(const FramePyramid& previousPyramid, const FramePyramid& currentPyramid, const Vectors2& previousPoints, const Vectors2& roughPoints, Vectors2& currentPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations, Worker* worker, MetricResults* metricResults, MetricResults* metricIdentityResults)
{
    static_assert(tSize % 2u == 1u, "Invalid image patch size, must be odd!");
    static_assert(tSize >= 3u, "Invalid image patch size, must be larger than 2!");
 
    ocean_assert(FrameType::arePixelFormatsCompatible(previousPyramid.frameType().pixelFormat(), currentPyramid.frameType().pixelFormat()));
    ocean_assert(previousPyramid.frameType().pixelOrigin() == currentPyramid.frameType().pixelOrigin());
 
    ocean_assert(previousPyramid.frameType().channels() == tChannels);
    ocean_assert(currentPyramid.frameType().channels() == tChannels);
 
    ocean_assert(previousPoints.size() == roughPoints.size());
 
    ocean_assert(subPixelIterations >= 1u);
 
    const unsigned int idealLayers = CV::FramePyramid::idealLayers(previousPyramid.finestWidth(), previousPyramid.finestHeight(), (tSize / 2u) * 4u, (tSize / 2u) * 4u, 2u);
    const unsigned int numberLayers = min(min(previousPyramid.layers(), currentPyramid.layers()), idealLayers);
 
    if (numberLayers == 0u)
    {
        return false;
    }
 
    currentPoints.resize(previousPoints.size());
 
    if (metricResults != nullptr)
    {
        metricResults->resize(previousPoints.size());
    }
 
    if (metricIdentityResults != nullptr)
    {
        metricIdentityResults->resize(previousPoints.size());
    }
 
    if (worker != nullptr)
    {
        worker->executeFunction(Worker::Function::createStatic(&AdvancedMotionT::trackPointsSubPixelMirroredBorderSubset<tChannels, tSize>, &previousPyramid, &currentPyramid, numberLayers, &previousPoints, &roughPoints, &currentPoints, coarsestLayerRadius, subPixelIterations, metricResults ? metricResults->data() : nullptr, metricIdentityResults ? metricIdentityResults->data() : nullptr, 0u, 0u), 0u, (unsigned int)(previousPoints.size()));
    }
    else
    {
        trackPointsSubPixelMirroredBorderSubset<tChannels, tSize>(&previousPyramid, &currentPyramid, numberLayers, &previousPoints, &roughPoints, &currentPoints, coarsestLayerRadius, subPixelIterations, metricResults ? metricResults->data() : nullptr, metricIdentityResults ? metricIdentityResults->data() : nullptr, 0u, (unsigned int)(previousPoints.size()));
    }
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackArbitraryPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, const SubRegion& previousSubRegion, const unsigned int horizontalBins, const unsigned int verticalBins, const unsigned int strength, Worker* worker, const unsigned int trackingLayers)
{
    ocean_assert(previousPyramid && nextPyramid);
 
    ocean_assert(previousImagePoints.empty() && nextImagePoints.empty());
 
    if (!previousPyramid || previousPyramid.frameType() != nextPyramid.frameType())
    {
        return false;
    }
 
    const unsigned int maximalTrackingLayers = min(trackingLayers, min(previousPyramid.layers(), nextPyramid.layers()));
 
    for (unsigned int n = 0u; n < maximalTrackingLayers; ++n)
    {
        const Frame& previousLayer = previousPyramid[n];
 
        if (previousLayer.width() < tSize || previousLayer.height() < tSize)
        {
            break;
        }
 
        Frame yFrame;
        if (!FrameConverter::Comfort::convert(previousLayer, FrameType::FORMAT_Y8, yFrame, FrameConverter::CP_AVOID_COPY_IF_POSSIBLE, worker))
        {
            return false;
        }
 
        if (yFrame.width() == 0u || yFrame.height() == 0u)
        {
            return false;
        }
 
        const Scalar layerFactor = Scalar((unsigned int)(1 << n));
        const Scalar invLayerFactor = Scalar(1) / layerFactor;
 
        // Calculate bounding box:
        Box2 boundingBox = previousSubRegion.boundingBox().isValid() ? previousSubRegion.boundingBox() * invLayerFactor : Box2();
        if (!boundingBox.isValid())
        {
            boundingBox = Box2(0, 0, Scalar(yFrame.width()), Scalar(yFrame.height()));
        }
 
        // Calculate clip window by intersecting bounding box with image borders:
        unsigned int windowLeft, windowTop, windowWidth, windowHeight;
        if (!boundingBox.box2integer(yFrame.width(), yFrame.height(), windowLeft, windowTop, windowWidth, windowHeight))
        {
            continue;
        }
 
        ocean_assert(windowWidth >= 1u && windowWidth <= yFrame.width());
        ocean_assert(windowHeight >= 1u && windowHeight <= yFrame.height());
 
        Detector::HarrisCorners corners;
        if (!Detector::HarrisCornerDetector::detectCorners(yFrame, windowLeft, windowTop, windowWidth, windowHeight, strength, true, corners, true, worker))
        {
            return false;
        }
 
        // If first run went bad, we try again with lowered expectations:
        if (n == 0u && corners.size() < 50)
        {
            corners.clear();
            if (!Detector::HarrisCornerDetector::detectCorners(yFrame, windowLeft, windowTop, windowWidth, windowHeight, strength / 2u, true, corners, true, worker))
            {
                return false;
            }
        }
 
        // If second run went bad, we try once more with even lower expectations:
        if (n == 0u && corners.size() < 20)
        {
            corners.clear();
            if (!Detector::HarrisCornerDetector::detectCorners(yFrame, windowLeft, windowTop, windowWidth, windowHeight, strength / 4u, true, corners, true, worker))
            {
                return false;
            }
        }
 
        if (corners.empty())
        {
            continue;
        }
 
        // Restrict corners to those lying inside sub regions:
        Detector::HarrisCorners cornersSubRegion;
 
        // if no sub-area filter is provided, use all corners
        if (previousSubRegion.isEmpty())
        {
            cornersSubRegion = std::move(corners);
        }
        else
        {
            cornersSubRegion.reserve(corners.size());
 
            for (Detector::HarrisCorners::const_iterator i = corners.begin(); i != corners.end(); ++i)
            {
                if (previousSubRegion.isInside(i->observation() * layerFactor))
                {
                    cornersSubRegion.push_back(*i);
                }
            }
        }
 
        if (cornersSubRegion.empty())
        {
            continue;
        }
 
        std::sort(cornersSubRegion.begin(), cornersSubRegion.end()); // Sort by corner strength in descending order
        Vectors2 smallPreviousImagePoints = Detector::HarrisCorner::corners2imagePoints(cornersSubRegion);
 
        if (!smallPreviousImagePoints.empty() && horizontalBins != 0u && verticalBins != 0u)
        {
            smallPreviousImagePoints = Geometry::SpatialDistribution::distributeAndFilter(smallPreviousImagePoints.data(), smallPreviousImagePoints.size(), Scalar(windowLeft), Scalar(windowTop), Scalar(windowWidth), Scalar(windowHeight), horizontalBins, verticalBins);
        }
 
        if (smallPreviousImagePoints.empty())
        {
            continue;
        }
 
        // Create sub pyramid using fast frame data referencing:
        const FramePyramid previousSmall = FramePyramid(previousPyramid, n, previousPyramid.layers() - n, false);
        const FramePyramid nextSmall = FramePyramid(nextPyramid, n, nextPyramid.layers() - n, false);
 
        Vectors2 smallNextImagePoints;
 
        // Find corresponding points in next frame:
        if (trackPointsBidirectionalSubPixelMirroredBorder<tSize>(previousSmall, nextSmall, coarsestLayerRadius, smallPreviousImagePoints, smallNextImagePoints, maximalSqrError, worker))
        {
            for (unsigned int i = 0u; i < smallPreviousImagePoints.size(); ++i)
            {
                previousImagePoints.push_back(smallPreviousImagePoints[i] * layerFactor);
                nextImagePoints.push_back(smallNextImagePoints[i] * layerFactor);
            }
        }
    }
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackArbitraryPointsBidirectionalSubPixelMirroredBorder(const Frame& previousFrame, const Frame& nextFrame, const unsigned int maximalOffset, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, const SubRegion& previousSubRegion, const unsigned int horizontalBins, const unsigned int verticalBins, const unsigned int strength, const FramePyramid::DownsamplingMode downsamplingMode, Worker* worker, const unsigned int trackingLayers)
{
    ocean_assert(previousFrame && nextFrame);
 
    if (!previousFrame || previousFrame.frameType() != nextFrame.frameType())
    {
        return false;
    }
 
    const unsigned int layers = min(trackingLayers, FramePyramid::idealLayers(previousFrame.width(), previousFrame.height(), (tSize / 2u) * 4u, (tSize / 2u) * 4u, 2u, maximalOffset, coarsestLayerRadius));
 
    if (layers == 0u)
    {
        return false;
    }
 
    const FramePyramid previousPyramid(previousFrame, downsamplingMode, layers, false /*copyFirstLayer*/, worker);
    const FramePyramid nextPyramid(nextFrame, downsamplingMode, layers, false /*copyFirstLayer*/, worker);
 
    return trackArbitraryPointsBidirectionalSubPixelMirroredBorder<tSize>(previousPyramid, nextPyramid, coarsestLayerRadius, previousImagePoints, nextImagePoints, maximalSqrError, previousSubRegion, horizontalBins, verticalBins, strength, worker, trackingLayers);
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, Worker* worker, Indices32* validIndices, const unsigned int subPixelIterations)
{
    ocean_assert(previousPyramid && nextPyramid);
 
    ocean_assert(!previousImagePoints.empty() && nextImagePoints.empty());
    ocean_assert(validIndices == nullptr || validIndices->empty());
 
    if (previousImagePoints.empty())
    {
        return true;
    }
 
    if (!previousPyramid || !previousPyramid.frameType().isPixelFormatCompatible(nextPyramid.frameType().pixelFormat()) || previousPyramid.frameType().pixelOrigin() != nextPyramid.frameType().pixelOrigin())
    {
        return false;
    }
 
    Vectors2 previousPointCandidates(std::move(previousImagePoints));
    ocean_assert(previousImagePoints.empty());
 
    // forward point motion
    Vectors2 nextPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tSize>(previousPyramid, nextPyramid, previousPointCandidates, previousPointCandidates, nextPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    // backward point motion
    Vectors2 backwardsPreviousPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tSize>(nextPyramid, previousPyramid, nextPointCandidates, nextPointCandidates, backwardsPreviousPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    ocean_assert(previousPointCandidates.size() == nextPointCandidates.size());
    ocean_assert(previousPointCandidates.size() == backwardsPreviousPointCandidates.size());
 
    previousImagePoints = Vectors2();
    previousImagePoints.reserve(previousPointCandidates.size());
 
    nextImagePoints.clear();
    nextImagePoints.reserve(previousPointCandidates.size());
 
    if (validIndices != nullptr)
    {
        validIndices->clear();
        validIndices->reserve(previousPointCandidates.size());
 
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
            const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
            previousImagePoints.push_back(previousPointCandidates[n]);
            nextImagePoints.push_back(nextImagePoint);
 
            // identify point pairs with almost identical point motion
 
            if (sqrDistance <= maximalSqrError && nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
            {
                validIndices->push_back(Index32(n));
            }
        }
    }
    else
    {
        // identify point pairs with almost identical point motion
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
 
            if (sqrDistance <= maximalSqrError)
            {
                const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
                if (nextImagePoint.x() >= Scalar(0) && nextImagePoint.y() >= Scalar(0) && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
                {
                    previousImagePoints.push_back(previousPointCandidates[n]);
                    nextImagePoints.push_back(nextImagePoint);
                }
            }
        }
    }
 
    ocean_assert(previousImagePoints.size() == nextImagePoints.size());
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, Worker* worker, Indices32* validIndices, const unsigned int subPixelIterations)
{
    ocean_assert(previousPyramid && nextPyramid);
    ocean_assert(previousPyramid.frameType().channels() == tChannels);
    ocean_assert(nextPyramid.frameType().channels() == tChannels);
 
    ocean_assert(!previousImagePoints.empty() && nextImagePoints.empty());
    ocean_assert(validIndices == nullptr || validIndices->empty());
 
    if (previousImagePoints.empty())
    {
        return true;
    }
 
    if (!previousPyramid || previousPyramid.frameType() != nextPyramid.frameType())
    {
        return false;
    }
 
    Vectors2 previousPointCandidates(std::move(previousImagePoints));
    ocean_assert(previousImagePoints.empty());
 
    // forward point motion
    Vectors2 nextPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tChannels, tSize>(previousPyramid, nextPyramid, previousPointCandidates, previousPointCandidates, nextPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    // backward point motion
    Vectors2 backwardsPreviousPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tChannels, tSize>(nextPyramid, previousPyramid, nextPointCandidates, nextPointCandidates, backwardsPreviousPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    ocean_assert(previousPointCandidates.size() == nextPointCandidates.size());
    ocean_assert(previousPointCandidates.size() == backwardsPreviousPointCandidates.size());
 
    previousImagePoints = Vectors2();
    previousImagePoints.reserve(previousPointCandidates.size());
 
    nextImagePoints.clear();
    nextImagePoints.reserve(previousPointCandidates.size());
 
    if (validIndices != nullptr)
    {
        validIndices->clear();
        validIndices->reserve(previousPointCandidates.size());
 
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
            const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
            previousImagePoints.push_back(previousPointCandidates[n]);
            nextImagePoints.push_back(nextImagePoint);
 
            // identify point pairs with almost identical point motion
            if (sqrDistance <= maximalSqrError && nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
            {
                validIndices->push_back(Index32(n));
            }
        }
    }
    else
    {
        // identify point pairs with almost identical point motion
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
 
            if (sqrDistance <= maximalSqrError)
            {
                const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
                if (nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
                {
                    previousImagePoints.push_back(previousPointCandidates[n]);
                    nextImagePoints.push_back(nextImagePoint);
                }
            }
        }
    }
 
    ocean_assert(previousImagePoints.size() == nextImagePoints.size());
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, const Vectors2& previousImagePoints, Vectors2& nextImagePoints, std::vector<uint8_t>& validCorrespondences, const Scalar maximalSqrError, Worker* worker, const unsigned int subPixelIterations)
{
    ocean_assert(previousPyramid && nextPyramid);
 
    ocean_assert(!previousImagePoints.empty() && nextImagePoints.empty());
 
    if (previousImagePoints.empty())
    {
        return true;
    }
 
    if (!previousPyramid || !previousPyramid.frameType().isPixelFormatCompatible(nextPyramid.frameType().pixelFormat()) || previousPyramid.frameType().pixelOrigin() != nextPyramid.frameType().pixelOrigin())
    {
        return false;
    }
 
    // forward point motion
    if (!trackPointsSubPixelMirroredBorder<tSize>(previousPyramid, nextPyramid, previousImagePoints, previousImagePoints, nextImagePoints, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    // backward point motion
    Vectors2 backwardsPreviousImagePoints(previousImagePoints.size());
    if (!trackPointsSubPixelMirroredBorder<tSize>(nextPyramid, previousPyramid, nextImagePoints, nextImagePoints, backwardsPreviousImagePoints, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    validCorrespondences.assign(previousImagePoints.size(), uint8_t(0));
 
    for (size_t n = 0; n < previousImagePoints.size(); ++n)
    {
        const Vector2 forwardBackwardOffset = previousImagePoints[n] - backwardsPreviousImagePoints[n];
 
        const Scalar sqrDistance = forwardBackwardOffset.sqr();
 
        // let's check whether forward and backward motion is almost identical
 
        if (sqrDistance <= maximalSqrError)
        {
            const Vector2 nextImagePoint(nextImagePoints[n] + forwardBackwardOffset * Scalar(0.5));
 
            if (nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
            {
                nextImagePoints[n] = nextImagePoint;
 
                validCorrespondences[n] = uint8_t(1);
            }
        }
    }
 
    ocean_assert(previousImagePoints.size() == nextImagePoints.size());
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorder(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, const Vectors2& previousImagePoints, Vectors2& nextImagePoints, std::vector<uint8_t>& validCorrespondences, const Scalar maximalSqrError, Worker* worker, const unsigned int subPixelIterations)
{
    ocean_assert(previousPyramid && nextPyramid);
    ocean_assert(previousPyramid.frameType().channels() == tChannels);
    ocean_assert(nextPyramid.frameType().channels() == tChannels);
 
    ocean_assert(!previousImagePoints.empty() && nextImagePoints.empty());
 
    if (previousImagePoints.empty())
    {
        return true;
    }
 
    if (!previousPyramid || previousPyramid.frameType() != nextPyramid.frameType())
    {
        return false;
    }
 
    // forward point motion
    nextImagePoints.reserve(previousImagePoints.size());
    if (!trackPointsSubPixelMirroredBorder<tChannels, tSize>(previousPyramid, nextPyramid, previousImagePoints, previousImagePoints, nextImagePoints, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    // backward point motion
    Vectors2 backwardsPreviousImagePoints(previousImagePoints.size());
    if (!trackPointsSubPixelMirroredBorder<tChannels, tSize>(nextPyramid, previousPyramid, nextImagePoints, nextImagePoints, backwardsPreviousImagePoints, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    validCorrespondences.assign(previousImagePoints.size(), uint8_t(0));
 
    for (size_t n = 0; n < previousImagePoints.size(); ++n)
    {
        const Vector2 forwardBackwardOffset = previousImagePoints[n] - backwardsPreviousImagePoints[n];
 
        const Scalar sqrDistance = forwardBackwardOffset.sqr();
 
        // let's check whether forward and backward motion is almost identical
 
        if (sqrDistance <= maximalSqrError)
        {
            const Vector2 nextImagePoint(nextImagePoints[n] + forwardBackwardOffset * Scalar(0.5));
 
            if (nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
            {
                nextImagePoints[n] = nextImagePoint;
 
                validCorrespondences[n] = uint8_t(1);
            }
        }
    }
 
    ocean_assert(previousImagePoints.size() == nextImagePoints.size());
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, const Vectors2& roughNextImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, Worker* worker, Indices32* validIndices, const unsigned int subPixelIterations)
{
    ocean_assert(previousPyramid && nextPyramid);
    ocean_assert(previousPyramid.frameType().pixelFormat() == nextPyramid.frameType().pixelFormat() && previousPyramid.frameType().pixelOrigin() == nextPyramid.frameType().pixelOrigin());
 
    ocean_assert(!previousImagePoints.empty() && nextImagePoints.empty());
    ocean_assert(validIndices == nullptr || validIndices->empty());
 
    ocean_assert(&previousImagePoints != &roughNextImagePoints);
 
    if (previousImagePoints.empty())
    {
        return true;
    }
 
    if (!previousPyramid || previousPyramid.frameType().pixelFormat() != nextPyramid.frameType().pixelFormat() || previousPyramid.frameType().pixelOrigin() != nextPyramid.frameType().pixelOrigin())
    {
        return false;
    }
 
    Vectors2 previousPointCandidates(std::move(previousImagePoints));
    ocean_assert(previousImagePoints.empty());
 
    // forward point motion
    Vectors2 nextPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tSize>(previousPyramid, nextPyramid, previousPointCandidates, roughNextImagePoints, nextPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    // backward point motion
    Vectors2 backwardsPreviousPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tSize>(nextPyramid, previousPyramid, nextPointCandidates, previousPointCandidates, backwardsPreviousPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    previousImagePoints = Vectors2();
    previousImagePoints.reserve(previousPointCandidates.size());
 
    nextImagePoints.clear();
    nextImagePoints.reserve(previousPointCandidates.size());
 
    if (validIndices != nullptr)
    {
        validIndices->clear();
        validIndices->reserve(previousPointCandidates.size());
 
        // identify point pairs with almost identical point motion
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
            const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
            previousImagePoints.push_back(previousPointCandidates[n]);
            nextImagePoints.push_back(nextImagePoint);
 
            if (sqrDistance <= maximalSqrError && nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
            {
                validIndices->push_back((unsigned int)(n));
            }
        }
    }
    else
    {
        // identify point pairs with almost identical point motion
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
 
            if (sqrDistance <= maximalSqrError)
            {
                const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
                if (nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
                {
                    previousImagePoints.push_back(previousPointCandidates[n]);
                    nextImagePoints.push_back(nextImagePoint);
                }
            }
        }
    }
 
    ocean_assert(previousImagePoints.size() == nextImagePoints.size());
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorderWithRoughLocations(const CV::FramePyramid& previousPyramid, const CV::FramePyramid& nextPyramid, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, const Vectors2& roughNextImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, Worker* worker, Indices32* validIndices, const unsigned int subPixelIterations)
{
    ocean_assert(previousPyramid && nextPyramid);
    ocean_assert(FrameType::arePixelFormatsCompatible(previousPyramid.frameType().pixelFormat(), nextPyramid.frameType().pixelFormat()));
    ocean_assert(previousPyramid.frameType().pixelOrigin() == nextPyramid.frameType().pixelOrigin());
    ocean_assert(previousPyramid.frameType().channels() == tChannels);
    ocean_assert(nextPyramid.frameType().channels() == tChannels);
 
    ocean_assert(!previousImagePoints.empty() && nextImagePoints.empty());
    ocean_assert(validIndices == nullptr || validIndices->empty());
 
    ocean_assert(&previousImagePoints != &roughNextImagePoints);
 
    if (previousImagePoints.empty())
    {
        return true;
    }
 
    if (!previousPyramid
            || !nextPyramid
            || !FrameType::arePixelFormatsCompatible(previousPyramid.frameType().pixelFormat(), nextPyramid.frameType().pixelFormat())
            || previousPyramid.frameType().pixelOrigin() != nextPyramid.frameType().pixelOrigin()
            || previousPyramid.frameType().channels() != tChannels)
    {
        return false;
    }
 
    Vectors2 previousPointCandidates(std::move(previousImagePoints));
    ocean_assert(previousImagePoints.empty());
 
    // forward point motion
    Vectors2 nextPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tChannels, tSize>(previousPyramid, nextPyramid, previousPointCandidates, roughNextImagePoints, nextPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    // backward point motion
    Vectors2 backwardsPreviousPointCandidates(previousPointCandidates.size());
    if (!trackPointsSubPixelMirroredBorder<tChannels, tSize>(nextPyramid, previousPyramid, nextPointCandidates, previousPointCandidates, backwardsPreviousPointCandidates, coarsestLayerRadius, subPixelIterations, worker))
    {
        return false;
    }
 
    previousImagePoints = Vectors2();
    previousImagePoints.reserve(previousPointCandidates.size());
 
    nextImagePoints.clear();
    nextImagePoints.reserve(previousPointCandidates.size());
 
    if (validIndices != nullptr)
    {
        validIndices->clear();
        validIndices->reserve(previousPointCandidates.size());
 
        // identify point pairs with almost identical point motion
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
            const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
            previousImagePoints.push_back(previousPointCandidates[n]);
            nextImagePoints.push_back(nextImagePoint);
 
            if (sqrDistance <= maximalSqrError && nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
            {
                validIndices->push_back((unsigned int)(n));
            }
        }
    }
    else
    {
        // identify point pairs with almost identical point motion
        for (size_t n = 0; n < previousPointCandidates.size(); ++n)
        {
            const Scalar sqrDistance(previousPointCandidates[n].sqrDistance(backwardsPreviousPointCandidates[n]));
 
            if (sqrDistance <= maximalSqrError)
            {
                const Vector2 nextImagePoint(nextPointCandidates[n] + (previousPointCandidates[n] - backwardsPreviousPointCandidates[n]) * Scalar(0.5));
 
                if (nextImagePoint.x() >= 0 && nextImagePoint.y() >= 0 && nextImagePoint.x() < Scalar(nextPyramid.finestWidth()) && nextImagePoint.y() < Scalar(nextPyramid.finestHeight()))
                {
                    previousImagePoints.push_back(previousPointCandidates[n]);
                    nextImagePoints.push_back(nextImagePoint);
                }
            }
        }
    }
 
    ocean_assert(previousImagePoints.size() == nextImagePoints.size());
 
    return true;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsBidirectionalSubPixelMirroredBorder(const Frame& previousFrame, const Frame& nextFrame, const unsigned int maximalOffset, const unsigned int coarsestLayerRadius, Vectors2& previousImagePoints, Vectors2& nextImagePoints, const Scalar maximalSqrError, const FramePyramid::DownsamplingMode downsamplingMode, Worker* worker, Indices32* validIndices, const unsigned int subPixelIterations)
{
    ocean_assert(previousFrame.isValid() && nextFrame.isValid());
 
    if (!previousFrame || !previousFrame.isPixelFormatCompatible(nextFrame.pixelFormat()) || previousFrame.pixelOrigin() != nextFrame.pixelOrigin())
    {
        return false;
    }
 
    const unsigned int previousLayers = FramePyramid::idealLayers(previousFrame.width(), previousFrame.height(), (tSize / 2u) * 4u, (tSize / 2u) * 4u, 2u, maximalOffset, coarsestLayerRadius);
    const unsigned int nextLayers = FramePyramid::idealLayers(nextFrame.width(), nextFrame.height(), (tSize / 2u) * 4u, (tSize / 2u) * 4u, 2u, maximalOffset, coarsestLayerRadius);
    ocean_assert(previousLayers >= 1u && nextLayers >= 1u);
 
    const unsigned int layers = std::min(previousLayers, nextLayers);
 
    if (layers == 0u)
    {
        return false;
    }
 
    const FramePyramid previousPyramid(previousFrame, downsamplingMode, layers, false /*copyFirstLayer*/, worker);
    const FramePyramid nextPyramid(nextFrame, downsamplingMode, layers, false /*copyFirstLayer*/, worker);
 
    return trackPointsBidirectionalSubPixelMirroredBorder<tSize>(previousPyramid, nextPyramid, coarsestLayerRadius, previousImagePoints, nextImagePoints, maximalSqrError, worker, validIndices, subPixelIterations);
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
bool AdvancedMotionT<TMetricInteger, TMetricFloat>::trackReliableReferencePoints(const FramePyramid& previousPyramid, const FramePyramid& currentPyramid, Vectors2& previousReferencePoints, Vectors2& currentReferencePoints, const unsigned int horizontalBins, const unsigned int verticalBins, const PixelBoundingBox& boundingBox, const Frame& maskFrame, Worker* worker)
{
    ocean_assert(previousReferencePoints.empty());
    ocean_assert(currentReferencePoints.empty());
 
    ocean_assert(&previousReferencePoints != &currentReferencePoints);
 
    ocean_assert(horizontalBins >= 1u);
    ocean_assert(verticalBins >= 1u);
 
    const Frame& previousFrame = previousPyramid.finestLayer();
 
    const unsigned int width = previousFrame.width();
    const unsigned int height = previousFrame.height();
 
    const unsigned int areaLeft = boundingBox ? boundingBox.left() : 0u;
    const unsigned int areaTop = boundingBox ? boundingBox.top() : 0u;
    const unsigned int areaWidth = boundingBox ? boundingBox.width() : width;
    const unsigned int areaHeight = boundingBox ? boundingBox.height() : height;
 
    ocean_assert(areaLeft + areaWidth <= width);
    ocean_assert(areaTop + areaHeight <= height);
 
    ocean_assert(!maskFrame.isValid() || maskFrame.isPixelFormatCompatible(FrameType::genericPixelFormat<uint8_t, 1u>()));
 
    Detector::HarrisCorners features;
    features.reserve(5000);
    Detector::HarrisCornerDetector::detectCorners(previousFrame, areaLeft, areaTop, areaWidth, areaHeight, 1u, true, features, false, worker);
    ocean_assert(!features.empty());
 
    if (features.empty())
    {
        return false;
    }
 
    std::sort(features.begin(), features.end());
    const Vectors2 allPreviousReferencePoints(CV::Detector::HarrisCorner::corners2imagePoints(features));
 
    const Geometry::SpatialDistribution::DistributionArray distribution(Geometry::SpatialDistribution::distributeToArray(allPreviousReferencePoints.data(), (unsigned int)allPreviousReferencePoints.size(), Scalar(areaLeft), Scalar(areaTop), Scalar(areaWidth), Scalar(areaHeight), horizontalBins, verticalBins));
 
    const uint8_t* const maskData = maskFrame ? maskFrame.constdata<uint8_t>() : nullptr;
    const unsigned int maskStrideElements = maskFrame ? maskFrame.strideElements() : 0u;
 
    previousReferencePoints.reserve(distribution.bins());
    for (unsigned int n = 0u; n < distribution.bins(); ++n)
    {
        const Indices32& indices = distribution[n];
 
        if (!indices.empty())
        {
            ocean_assert(indices.front() < allPreviousReferencePoints.size());
            const Vector2& point = allPreviousReferencePoints[indices.front()];
 
            const unsigned int xPosition = (unsigned int)(point.x());
            const unsigned int yPosition = (unsigned int)(point.y());
 
            ocean_assert(xPosition < width);
            ocean_assert(yPosition < height);
 
            if (maskData == nullptr || maskData[yPosition * maskStrideElements + xPosition] == 0xFFu)
            {
                previousReferencePoints.push_back(point);
            }
        }
    }
 
    if (previousReferencePoints.empty())
    {
        return false;
    }
 
    return trackPointsSubPixelMirroredBorder<tSize>(previousPyramid, currentPyramid, previousReferencePoints, previousReferencePoints, currentReferencePoints, 2u, 4u, worker);
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tPatchSize>
Vector2 AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointSubPixelMirroredBorder(const uint8_t* frame0, const uint8_t* frame1, const unsigned int width0, const unsigned int height0, const unsigned int width1, const unsigned int height1, const unsigned int frame0PaddingElements, const unsigned int frame1PaddingElements, const Vector2& position0, const unsigned int radiusX, const unsigned int radiusY, const Vector2& rough1, const unsigned int subPixelIterations, uint32_t* metricResult, uint32_t* metricIdentityResult)
{
    static_assert(tChannels != 0u, "Invalid number of data channels!");
    static_assert(tPatchSize % 2u == 1u, "Invalid size of the image patch, must be odd!");
 
    constexpr unsigned int tPatchSize_2 = tPatchSize / 2u;
 
    ocean_assert(frame0 != nullptr && frame1 != nullptr);
 
    ocean_assert(width0 >= tPatchSize && height0 >= tPatchSize);
    ocean_assert(width1 >= tPatchSize && height1 >= tPatchSize);
 
    ocean_assert(position0.x() >= Scalar(0) && position0.x() < Scalar(width0));
    ocean_assert(position0.y() >= Scalar(0) && position0.y() < Scalar(height0));
 
    const PixelPosition position1(rough1.x() != Numeric::maxValue() ? PixelPosition::vector2pixelPosition(rough1) : PixelPosition::vector2pixelPosition(position0));
 
    const unsigned int leftCenter1 = (unsigned int)(max(0, int(position1.x() - radiusX)));
    const unsigned int topCenter1 = (unsigned int)(max(0, int(position1.y() - radiusY)));
 
    const unsigned int rightCenter1 = min(position1.x() + radiusX, width1 - 1u);
    const unsigned int bottomCenter1 = min(position1.y() + radiusY, height1 - 1u);
 
    // first, we determine a buffer containing the first (interpolated) image patch
 
    uint8_t buffer0[tPatchSize * tPatchSize * tChannels];
    uint8_t buffer1[tPatchSize * tPatchSize * tChannels];
 
    const unsigned int x0 = (unsigned int)(position0.x());
    const unsigned int y0 = (unsigned int)(position0.y());
 
    if (x0 - tPatchSize_2 < width0 - tPatchSize && y0 - tPatchSize_2 < height0 - tPatchSize)
    {
        ocean_assert(x0 >= tPatchSize_2 && x0 < width0 - (tPatchSize_2 + 1u) && y0 >= tPatchSize_2 && y0 < height0 - (tPatchSize_2 + 1u));
        AdvancedFrameInterpolatorBilinear::interpolateSquarePatch8BitPerChannel<tChannels, tPatchSize, PC_TOP_LEFT>(frame0, width0, frame0PaddingElements, buffer0, position0);
    }
    else
    {
        ocean_assert(!(x0 >= tPatchSize_2 && x0 < width0 - (tPatchSize_2 + 1u) && y0 >= tPatchSize_2 && y0 < height0 - (tPatchSize_2 + 1u)));
        AdvancedFrameInterpolatorBilinear::interpolateSquareMirroredBorder8BitPerChannel<tChannels, tPatchSize>(frame0, width0, height0, frame0PaddingElements, buffer0, position0);
    }
 
    PixelPosition bestPosition;
    uint32_t bestMetric = uint32_t(-1);
    unsigned int bestSqrDistance = (unsigned int)(-1);
 
    for (unsigned int y1 = topCenter1; y1 <= bottomCenter1; ++y1)
    {
        for (unsigned int x1 = leftCenter1; x1 <= rightCenter1; ++x1)
        {
            uint32_t candidateMetric;
 
            if (x1 - tPatchSize_2 < width1 - tPatchSize && y1 - tPatchSize_2 < height1 - tPatchSize)
            {
                candidateMetric = TMetricInteger::template patchBuffer8BitPerChannel<tChannels, tPatchSize>(frame1, width1, x1, y1, frame1PaddingElements, buffer0);
            }
            else
            {
                constexpr unsigned int buffer1PaddingElements = 0u;
 
                FrameConverter::patchFrameMirroredBorder<uint8_t, tChannels>(frame1, buffer1, width1, height1, x1, y1, tPatchSize, frame1PaddingElements, buffer1PaddingElements); // **TODO** for performance improvements: use patch/patch mirrored border metric
 
                candidateMetric = TMetricInteger::template buffer8BitPerChannel<tChannels, tPatchSize * tPatchSize>(buffer0, buffer1);
            }
 
            const PixelPosition position(x1, y1);
 
            if (candidateMetric < bestMetric || (candidateMetric == bestMetric && position1.sqrDistance(position) < bestSqrDistance))
            {
                bestMetric = candidateMetric;
                bestPosition = position;
 
                bestSqrDistance = position1.sqrDistance(position);
            }
 
            if (metricIdentityResult && x1 == position1.x() && y1 == position1.y())
            {
                *metricIdentityResult = candidateMetric;
            }
        }
    }
 
    ocean_assert(bestMetric != (unsigned int)(-1) && bestPosition);
 
    ocean_assert(abs(int(bestPosition.x()) - int(position1.x())) <= int(radiusX));
    ocean_assert(abs(int(bestPosition.y()) - int(position1.y())) <= int(radiusY));
 
    if (metricResult)
    {
        *metricResult = bestMetric;
    }
 
    return trackPointBufferSubPixelMirroredBorder<tChannels, tPatchSize>(buffer0, frame1, width1, height1, frame1PaddingElements, Vector2(Scalar(bestPosition.x()), Scalar(bestPosition.y())), subPixelIterations, metricResult);
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tPatchSize>
inline Vector2 AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointSubPixelMirroredBorder(const uint8_t* frame0, const uint8_t* frame1, const unsigned int channels, const unsigned int width0, const unsigned int height0, const unsigned int width1, const unsigned int height1, const unsigned int frame0PaddingElements, const unsigned int frame1PaddingElements, const Vector2& position0, const unsigned int radiusX, const unsigned int radiusY, const Vector2& rough1, const unsigned int subPixelIterations, uint32_t* metricResult, uint32_t* metricIdentityResult)
{
    ocean_assert(channels >= 1u);
 
    switch (channels)
    {
        case 1u:
            return trackPointSubPixelMirroredBorder<1u, tPatchSize>(frame0, frame1, width0, height0, width1, height1, frame0PaddingElements, frame1PaddingElements, position0, radiusX, radiusY, rough1, subPixelIterations, metricResult, metricIdentityResult);
 
        case 2u:
            return trackPointSubPixelMirroredBorder<2u, tPatchSize>(frame0, frame1, width0, height0, width1, height1, frame0PaddingElements, frame1PaddingElements, position0, radiusX, radiusY, rough1, subPixelIterations, metricResult, metricIdentityResult);
 
        case 3u:
            return trackPointSubPixelMirroredBorder<3u, tPatchSize>(frame0, frame1, width0, height0, width1, height1, frame0PaddingElements, frame1PaddingElements, position0, radiusX, radiusY, rough1, subPixelIterations, metricResult, metricIdentityResult);
 
        case 4u:
            return trackPointSubPixelMirroredBorder<4u, tPatchSize>(frame0, frame1, width0, height0, width1, height1, frame0PaddingElements, frame1PaddingElements, position0, radiusX, radiusY, rough1, subPixelIterations, metricResult, metricIdentityResult);
    }
 
    ocean_assert(false && "Invalid pixel format!");
    return rough1;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tPatchSize>
Vector2 AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointBufferSubPixelMirroredBorder(const uint8_t* buffer0, const uint8_t* frame1, const unsigned int width1, const unsigned int height1, const unsigned int frame1PaddingElements, const Vector2& roughPosition1, const unsigned int subPixelIterations, uint32_t* metricResult)
{
    static_assert(tChannels >= 1u, "Invalid number of data channels!");
    static_assert(tPatchSize % 2u == 1u, "Invalid size of the image patch, must be odd!");
 
    ocean_assert(buffer0 != nullptr && frame1 != nullptr);
 
    ocean_assert(width1 >= tPatchSize && height1 >= tPatchSize);
 
    ocean_assert(roughPosition1.x() >= Scalar(0) && roughPosition1.x() < Scalar(width1));
    ocean_assert(roughPosition1.y() >= Scalar(0) && roughPosition1.y() < Scalar(height1));
 
    uint32_t metricBest = uint32_t(-1);
 
    if (metricResult != nullptr)
    {
        metricBest = *metricResult;
 
#ifdef OCEAN_DEBUG
        const bool result = metricBest == TMetricFloat::template patchMirroredBorderBuffer8BitPerChannel<tChannels, tPatchSize>(frame1, width1, height1, roughPosition1.x(), roughPosition1.y(), frame1PaddingElements, buffer0);
        ocean_assert_and_suppress_unused(result, result);
#endif
    }
    else
    {
        const unsigned int x1 = (unsigned int)(roughPosition1.x());
        const unsigned int y1 = (unsigned int)(roughPosition1.y());
 
        if (x1 - (tPatchSize / 2u) < width1 - tPatchSize && y1 - (tPatchSize / 2u) < height1 - tPatchSize)
        {
            ocean_assert(x1 >= (tPatchSize / 2u) && y1 >= (tPatchSize / 2u) && x1 < width1 - (tPatchSize / 2u + 1u) && y1 < height1 - (tPatchSize / 2u + 1u));
            metricBest = TMetricFloat::template patchBuffer8BitPerChannel<tChannels, tPatchSize>(frame1, width1, roughPosition1.x(), roughPosition1.y(), frame1PaddingElements, buffer0);
        }
        else
        {
            ocean_assert(!(x1 >= (tPatchSize / 2u) && y1 >= (tPatchSize / 2u) && x1 < width1 - (tPatchSize / 2u + 1u) && y1 < height1 - (tPatchSize / 2u + 1u)));
            metricBest = TMetricFloat::template patchMirroredBorderBuffer8BitPerChannel<tChannels, tPatchSize>(frame1, width1, height1, roughPosition1.x(), roughPosition1.y(), frame1PaddingElements, buffer0);
        }
    }
 
    constexpr unsigned int numberSteps = 8u;
 
    const Vector2 steps[numberSteps] =
    {
        Vector2(-1, -1),
        Vector2(0, -1),
        Vector2(1, -1),
        Vector2(-1, 0),
        Vector2(1, 0),
        Vector2(-1, 1),
        Vector2(0, 1),
        Vector2(1, 1)
    };
 
    Scalar offset = Scalar(0.5);
    Vector2 position1 = roughPosition1;
 
    for (unsigned int n = 0u; n < subPixelIterations; ++n)
    {
        Vector2 bestPosition1 = position1;
 
        // make 8 sample calculations
 
        for (unsigned int i = 0u; i < numberSteps; ++i)
        {
            const Vector2 candidatePosition1(position1.x() + steps[i].x() * offset, position1.y() + steps[i].y() * offset);
 
            if (candidatePosition1.x() >= Scalar(0) && candidatePosition1.x() < Scalar(width1) && candidatePosition1.y() >= Scalar(0) && candidatePosition1.y() < Scalar(height1))
            {
                const unsigned int x1 = (unsigned int)(candidatePosition1.x());
                const unsigned int y1 = (unsigned int)(candidatePosition1.y());
 
                const uint32_t candidateMetric = (x1 - (tPatchSize / 2u) < width1 - tPatchSize && y1 - (tPatchSize / 2u) < height1 - tPatchSize) ?
                                    TMetricFloat::template patchBuffer8BitPerChannel<tChannels, tPatchSize>(frame1, width1, candidatePosition1.x(), candidatePosition1.y(), frame1PaddingElements, buffer0) :
                                    TMetricFloat::template patchMirroredBorderBuffer8BitPerChannel<tChannels, tPatchSize>(frame1, width1, height1, candidatePosition1.x(), candidatePosition1.y(), frame1PaddingElements, buffer0);
 
                if (candidateMetric < metricBest)
                {
                    metricBest = candidateMetric;
                    bestPosition1 = candidatePosition1;
                }
            }
        }
 
        position1 = bestPosition1;
        offset *= Scalar(0.5);
    }
 
    if (metricResult != nullptr)
    {
        *metricResult = metricBest;
    }
 
    ocean_assert(position1.x() >= 0 && position1.y() >= 0);
    ocean_assert(position1.x() < Scalar(width1) && position1.y() < Scalar(height1));
 
    return position1;
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tSize>
void AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsSubPixelMirroredBorderSubset(const FramePyramid* previousPyramid, const FramePyramid* nextPyramid, const unsigned int numberLayers, const Vectors2* previousPoints, const Vectors2* roughNextPoints, Vectors2* nextPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations, unsigned int* metricResults, unsigned int* metricIdentityResults, const unsigned int firstPoint, const unsigned int numberPoints)
{
    static_assert(tSize % 2u == 1u, "Invalid patch size, must be odd!");
 
    ocean_assert(previousPyramid != nullptr && nextPyramid != nullptr);
    ocean_assert(previousPoints != nullptr && nextPoints != nullptr);
 
    ocean_assert(previousPyramid->isValid() && nextPyramid->isValid());
 
    ocean_assert(previousPyramid->frameType().pixelFormat() == nextPyramid->frameType().pixelFormat());
    ocean_assert(previousPyramid->frameType().pixelOrigin() == nextPyramid->frameType().pixelOrigin());
 
    ocean_assert(roughNextPoints == nullptr || previousPoints->size() == roughNextPoints->size());
    ocean_assert(nextPoints->size() == previousPoints->size());
 
    ocean_assert(firstPoint + numberPoints <= previousPoints->size());
 
    ocean_assert(numberLayers >= 1u);
    ocean_assert(numberLayers <= previousPyramid->layers());
    ocean_assert(numberLayers <= nextPyramid->layers());
 
    ocean_assert(previousPyramid->layer(numberLayers - 1u).width() >= tSize / 2u);
    ocean_assert(previousPyramid->layer(numberLayers - 1u).height() >= tSize / 2u);
 
    ShiftVector<Vector2> intermediateRoughNextPoints(firstPoint, numberPoints);
 
    const Scalar coarsestWidthNextPyramid = Scalar(nextPyramid->layer(numberLayers - 1u).width());
    const Scalar coarsestHeightNextPyramid = Scalar(nextPyramid->layer(numberLayers - 1u).height());
    const Scalar coarsestLayerFactorNextPyramid = Scalar(1) / Scalar(nextPyramid->sizeFactor(numberLayers - 1u));
    ocean_assert(coarsestWidthNextPyramid >= 1u && coarsestHeightNextPyramid >= 1u);
 
    const unsigned int channels = previousPyramid->frameType().channels();
    ocean_assert(channels >= 1u && channels <= 4u);
 
    for (unsigned int n = firstPoint; n < firstPoint + numberPoints; ++n)
    {
        const Vector2& roughNextPoint = roughNextPoints != nullptr ? (*roughNextPoints)[n] : (*previousPoints)[n];
 
        const Scalar x = min(roughNextPoint.x() * coarsestLayerFactorNextPyramid, coarsestWidthNextPyramid - Scalar(1));
        const Scalar y = min(roughNextPoint.y() * coarsestLayerFactorNextPyramid, coarsestHeightNextPyramid - Scalar(1));
 
        intermediateRoughNextPoints[n] = Vector2(x, y);
    }
 
    for (unsigned int layerIndex = numberLayers - 1u; layerIndex < numberLayers; --layerIndex)
    {
        const Frame& previousLayer = (*previousPyramid)[layerIndex];
        const Frame& nextLayer = (*nextPyramid)[layerIndex];
 
        const uint8_t* const previousLayerData = previousLayer.constdata<uint8_t>();
        const uint8_t* const nextLayerData = nextLayer.constdata<uint8_t>();
 
        const unsigned int previousLayerPaddingElements = previousLayer.paddingElements();
        const unsigned int nextLayerPaddingElements = nextLayer.paddingElements();
 
        const unsigned int previousLayerWidth = previousLayer.width();
        const unsigned int previousLayerHeight = previousLayer.height();
 
        const unsigned int nextLayerWidth = nextLayer.width();
        const unsigned int nextLayerHeight = nextLayer.height();
 
        if (layerIndex == 0u)
        {
            //  we apply a sub-pixel accurate tracking on the finest pyramid layer
 
            const unsigned int layerRadiusX = numberLayers == 1u ? coarsestLayerRadius : 2u;
            const unsigned int layerRadiusY = numberLayers == 1u ? coarsestLayerRadius : 2u;
 
            for (unsigned int pointIndex = firstPoint; pointIndex < firstPoint + numberPoints; ++pointIndex)
            {
                const Vector2& previousPosition = (*previousPoints)[pointIndex];
                ocean_assert(previousPosition.x() >= Scalar(0) && previousPosition.y() >= Scalar(0));
                ocean_assert(previousPosition.x() < Scalar(previousLayerWidth) && previousPosition.y() < Scalar(previousLayerHeight));
 
                const Vector2& intermediateRoughNextPoint = intermediateRoughNextPoints[pointIndex];
                ocean_assert(intermediateRoughNextPoint.x() >= Scalar(0) && intermediateRoughNextPoint.y() >= Scalar(0));
                ocean_assert(intermediateRoughNextPoint.x() < Scalar(nextLayerWidth) && intermediateRoughNextPoint.y() < Scalar(nextLayerHeight));
 
                unsigned int* const metricResult = metricResults ? metricResults + pointIndex : nullptr;
                unsigned int* const metricIdentityResult = metricIdentityResults ? metricIdentityResults + pointIndex : nullptr;
 
                const Vector2 nextPoint = trackPointSubPixelMirroredBorder<tSize>(previousLayerData, nextLayerData, channels, previousLayerWidth, previousLayerHeight, nextLayerWidth, nextLayerHeight, previousLayerPaddingElements, nextLayerPaddingElements, previousPosition, layerRadiusX, layerRadiusY, intermediateRoughNextPoint, subPixelIterations, metricResult, metricIdentityResult);
 
                ocean_assert(nextPoint.x() >= 0 && nextPoint.x() < Scalar(nextLayerWidth));
                ocean_assert(nextPoint.y() >= 0 && nextPoint.y() < Scalar(nextLayerHeight));
 
                ocean_assert(pointIndex < nextPoints->size());
                (*nextPoints)[pointIndex] = nextPoint;
            }
        }
        else // otherwise we apply a pixel accurate determination
        {
            ocean_assert(layerIndex > 0u);
 
            const unsigned int layerRadius = (layerIndex == numberLayers - 1u) ? coarsestLayerRadius : 2u;
 
            const Scalar layerFactor = Scalar(1) / Scalar(1u << layerIndex);
 
            const Scalar finerNextLayerWidth1 = Scalar((*nextPyramid)[layerIndex - 1u].width()) - Scalar(1);
            const Scalar finerNextLayerHeight1 = Scalar((*nextPyramid)[layerIndex - 1u].height()) - Scalar(1);
 
            for (unsigned int pointIndex = firstPoint; pointIndex < firstPoint + numberPoints; ++pointIndex)
            {
                ocean_assert(intermediateRoughNextPoints[pointIndex].x() >= Scalar(0) && intermediateRoughNextPoints[pointIndex].y() >= Scalar(0));
                ocean_assert(intermediateRoughNextPoints[pointIndex].x() < Scalar(nextLayerWidth) && intermediateRoughNextPoints[pointIndex].y() < Scalar(nextLayerHeight));
 
                const PixelPosition intermediateRoughNextPoint(Numeric::round32(intermediateRoughNextPoints[pointIndex].x()), Numeric::round32(intermediateRoughNextPoints[pointIndex].y()));
                ocean_assert(intermediateRoughNextPoint.x() < nextLayerWidth && intermediateRoughNextPoint.y() < nextLayerHeight);
 
                unsigned int* const metricResult = metricResults ? metricResults + pointIndex : nullptr;
 
                const Vector2& previousPointFinestLayer = (*previousPoints)[pointIndex];
 
                const PixelPosition previousPoint(std::min(Numeric::round32(previousPointFinestLayer.x() * layerFactor), int(previousLayerWidth - 1u)), std::min(Numeric::round32(previousPointFinestLayer.y() * layerFactor), int(previousLayerHeight - 1u)));
 
                ocean_assert(previousPoint.x() < previousLayerWidth && previousPoint.y() < previousLayerHeight);
                if (previousPoint.x() < previousLayerWidth && previousPoint.y() < previousLayerHeight)
                {
                    const PixelPosition nextPoint = MotionT<TMetricInteger>::template pointMotionInFrameMirroredBorder<tSize>(previousLayerData, nextLayerData, channels, previousLayerWidth, previousLayerHeight, nextLayerWidth, nextLayerHeight, previousPoint, layerRadius, layerRadius, previousLayerPaddingElements, nextLayerPaddingElements, intermediateRoughNextPoint, metricResult);
 
                    ocean_assert(nextPoint.x() < nextLayerWidth && nextPoint.y() < nextLayerHeight);
 
                    intermediateRoughNextPoints[pointIndex] = Vector2(min(Scalar(nextPoint.x() * 2u), finerNextLayerWidth1), min(Scalar(nextPoint.y() * 2u), finerNextLayerHeight1));
 
                    ocean_assert(intermediateRoughNextPoints[pointIndex].x() >= 0 && intermediateRoughNextPoints[pointIndex].x() <= finerNextLayerWidth1);
                    ocean_assert(intermediateRoughNextPoints[pointIndex].y() >= 0 && intermediateRoughNextPoints[pointIndex].y() <= finerNextLayerHeight1);
                }
                else
                {
                    ocean_assert(false && "This should never happen!");
 
                    intermediateRoughNextPoints[pointIndex] = Vector2(previousPointFinestLayer.x() * layerFactor * Scalar(2), previousPointFinestLayer.y() * layerFactor * Scalar(2));
 
                    ocean_assert(intermediateRoughNextPoints[pointIndex].x() >= 0 && intermediateRoughNextPoints[pointIndex].x() < finerNextLayerWidth1);
                    ocean_assert(intermediateRoughNextPoints[pointIndex].y() >= 0 && intermediateRoughNextPoints[pointIndex].y() < finerNextLayerHeight1);
                }
            }
        }
    }
}
 
template <typename TMetricInteger, typename TMetricFloat>
template <unsigned int tChannels, unsigned int tSize>
void AdvancedMotionT<TMetricInteger, TMetricFloat>::trackPointsSubPixelMirroredBorderSubset(const FramePyramid* previousPyramid, const FramePyramid* currentPyramid, const unsigned int numberLayers, const Vectors2* previousPoints, const Vectors2* roughPoints, Vectors2* currentPoints, const unsigned int coarsestLayerRadius, const unsigned int subPixelIterations, unsigned int* metricResults, unsigned int* metricIdentityResults, const unsigned int firstPoint, const unsigned int numberPoints)
{
    static_assert(tSize % 2u == 1u, "Invalid patch size, must be odd!");
 
    ocean_assert(previousPyramid && currentPyramid);
    ocean_assert(previousPoints && roughPoints && currentPoints);
 
    ocean_assert(*previousPyramid && *currentPyramid);
 
    ocean_assert(FrameType::arePixelFormatsCompatible(previousPyramid->frameType().pixelFormat(), currentPyramid->frameType().pixelFormat()));
    ocean_assert(previousPyramid->frameType().pixelOrigin() == currentPyramid->frameType().pixelOrigin());
 
    ocean_assert(previousPyramid->frameType().channels() == tChannels);
    ocean_assert(currentPyramid->frameType().channels() == tChannels);
 
    ocean_assert(previousPoints->size() == roughPoints->size());
    ocean_assert(currentPoints->size() == previousPoints->size());
 
    ocean_assert(firstPoint + numberPoints <= previousPoints->size());
 
    ocean_assert(numberLayers >= 1u);
    ocean_assert(numberLayers <= previousPyramid->layers());
    ocean_assert(numberLayers <= currentPyramid->layers());
 
    ocean_assert(previousPyramid->layer(numberLayers - 1u).width() >= tSize / 2u);
    ocean_assert(previousPyramid->layer(numberLayers - 1u).height() >= tSize / 2u);
 
    ShiftVector<Vector2> intermediateRoughPoints(firstPoint, numberPoints);
 
    const Scalar lowestCurrentWidth = Scalar(currentPyramid->layer(numberLayers - 1u).width());
    const Scalar lowestCurrentHeight = Scalar(currentPyramid->layer(numberLayers - 1u).height());
    const Scalar lowestLayerFactor = Scalar(1) / Scalar(currentPyramid->sizeFactor(numberLayers - 1u));
    ocean_assert(lowestCurrentWidth >= 1u && lowestCurrentHeight >= 1u);
 
    const unsigned int channels = previousPyramid->frameType().channels();
    ocean_assert_and_suppress_unused(channels >= 1u && channels <= 4u, channels);
 
    for (unsigned int n = firstPoint; n < firstPoint + numberPoints; ++n)
    {
        const Vector2& roughPoint = (*roughPoints)[n];
 
        const Scalar x = min(roughPoint.x() * lowestLayerFactor, lowestCurrentWidth - 1);
        const Scalar y = min(roughPoint.y() * lowestLayerFactor, lowestCurrentHeight - 1);
 
        intermediateRoughPoints[n] = Vector2(x, y);
    }
 
    for (int layerIndex = int(numberLayers) - 1; layerIndex >= 0; --layerIndex)
    {
        const Frame& previousFrame = (*previousPyramid)[layerIndex];
        const Frame& currentFrame = (*currentPyramid)[layerIndex];
 
        const uint8_t* const previousFrameData = previousFrame.constdata<uint8_t>();
        const uint8_t* const currentFrameData = currentFrame.constdata<uint8_t>();
 
        const unsigned int previousFramePaddingElements = previousFrame.paddingElements();
        const unsigned int currentFramePaddingElements = currentFrame.paddingElements();
 
        const unsigned int previousWidth = previousFrame.width();
        const unsigned int previousHeight = previousFrame.height();
 
        const unsigned int currentWidth = currentFrame.width();
        const unsigned int currentHeight = currentFrame.height();
 
        // if the finest layer is reached we apply a subpixel accurate determination
        if (layerIndex == 0)
        {
            const unsigned int layerRadiusX = numberLayers == 1u ? coarsestLayerRadius : 2u;
            const unsigned int layerRadiusY = numberLayers == 1u ? coarsestLayerRadius : 2u;
 
            for (unsigned int i = firstPoint; i < firstPoint + numberPoints; ++i)
            {
                ocean_assert(intermediateRoughPoints[i].x() >= Scalar(0) && intermediateRoughPoints[i].y() >= Scalar(0));
                ocean_assert(intermediateRoughPoints[i].x() < Scalar(currentWidth) && intermediateRoughPoints[i].y() < Scalar(currentHeight));
 
                const Vector2& intermediateRoughPoint = intermediateRoughPoints[i];
 
                unsigned int* const metricResult = metricResults ? metricResults + i : nullptr;
                unsigned int* const metricIdentityResult = metricIdentityResults ? metricIdentityResults + i : nullptr;
 
                const Vector2& previousPosition = (*previousPoints)[i];
 
                ocean_assert(previousPosition.x() >= Scalar(0) && previousPosition.y() >= Scalar(0));
                ocean_assert(previousPosition.x() < Scalar(previousWidth) && previousPosition.y() < Scalar(previousHeight));
 
                const Vector2 position(trackPointSubPixelMirroredBorder<tChannels, tSize>(previousFrameData, currentFrameData, previousWidth, previousHeight, currentWidth, currentHeight, previousFramePaddingElements, currentFramePaddingElements, previousPosition, layerRadiusX, layerRadiusY, intermediateRoughPoint, subPixelIterations, metricResult, metricIdentityResult));
 
                ocean_assert(position.x() >= 0 && position.x() < Scalar(currentWidth));
                ocean_assert(position.y() >= 0 && position.y() < Scalar(currentHeight));
 
                ocean_assert(i < currentPoints->size());
                (*currentPoints)[i] = position;
            }
        }
        else // otherwise we apply a pixel accurate determination
        {
            ocean_assert(layerIndex > 0);
 
            const unsigned int layerRadiusX = (layerIndex == int(numberLayers) - 1) ? coarsestLayerRadius : 2u;
            const unsigned int layerRadiusY = (layerIndex == int(numberLayers) - 1) ? coarsestLayerRadius : 2u;
 
            for (unsigned int i = firstPoint; i < firstPoint + numberPoints; ++i)
            {
                ocean_assert(intermediateRoughPoints[i].x() >= Scalar(0) && intermediateRoughPoints[i].y() >= Scalar(0));
                ocean_assert(intermediateRoughPoints[i].x() < Scalar(currentWidth) && intermediateRoughPoints[i].y() < Scalar(currentHeight));
 
                const PixelPosition intermediateRoughPoint(Numeric::round32(intermediateRoughPoints[i].x()), Numeric::round32(intermediateRoughPoints[i].y()));
 
                unsigned int* const metricResult = metricResults ? metricResults + i : nullptr;
 
                const Scalar layerFactor = Scalar(1) / Scalar((unsigned int)(1 << layerIndex));
                const PixelPosition previousPosition(min(Numeric::round32((*previousPoints)[i].x() * layerFactor), int(previousWidth) - 1),
                                                     min(Numeric::round32((*previousPoints)[i].y() * layerFactor), int(previousHeight) - 1));
 
                if (previousPosition.x() < previousWidth && previousPosition.y() < previousHeight)
                {
                    const PixelPosition position(MotionT<TMetricInteger>::template pointMotionInFrameMirroredBorder<tChannels, tSize>(previousFrameData, currentFrameData, previousWidth, previousHeight, currentWidth, currentHeight, previousPosition, layerRadiusX, layerRadiusY, previousFramePaddingElements, currentFramePaddingElements, intermediateRoughPoint, metricResult));
 
                    ocean_assert(position.x() < currentWidth && position.y() < currentHeight);
 
                    const Scalar higherWidth = Scalar((*currentPyramid)[layerIndex - 1].width());
                    const Scalar higherHeight = Scalar((*currentPyramid)[layerIndex - 1].height());
 
                    intermediateRoughPoints[i] = Vector2(min(Scalar(position.x() * 2u), higherWidth - 1), min(Scalar(position.y() * 2u), higherHeight - 1));
 
                    ocean_assert(intermediateRoughPoints[i].x() >= 0 && intermediateRoughPoints[i].x() < Scalar(higherWidth));
                    ocean_assert(intermediateRoughPoints[i].y() >= 0 && intermediateRoughPoints[i].y() < Scalar(higherHeight));
                }
                else
                {
                    intermediateRoughPoints[i] = Vector2((*previousPoints)[i].x() * layerFactor * Scalar(2), (*previousPoints)[i].y() * layerFactor * Scalar(2));
 
                    ocean_assert(intermediateRoughPoints[i].x() >= 0 && intermediateRoughPoints[i].x() < Scalar(currentFrame.width() * 2u));
                    ocean_assert(intermediateRoughPoints[i].y() >= 0 && intermediateRoughPoints[i].y() < Scalar(currentFrame.height() * 2u));
                }
            }
        }
    }
}
 
}
 
}
 
}
 
#endif // META_OCEAN_CV_ADVANCED_ADVANCED_MOTION_H