arm_compute/runtime/CL/functions/CLOpticalFlow.h

   1 /*
   2  * Copyright (c) 2017-2018 ARM Limited.
   3  *
   4  * SPDX-License-Identifier: MIT
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to
   8  * deal in the Software without restriction, including without limitation the
   9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  10  * sell copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in all
  14  * copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24 #ifndef __ARM_COMPUTE_CLOPTICALFLOW_H__
  25 #define __ARM_COMPUTE_CLOPTICALFLOW_H__
  26
  27 #include "arm_compute/core/CL/kernels/CLLKTrackerKernel.h"
  28
  29 #include "arm_compute/core/IArray.h"
  30 #include "arm_compute/core/Types.h"
  31 #include "arm_compute/runtime/CL/CLArray.h"
  32 #include "arm_compute/runtime/CL/CLMemoryGroup.h"
  33 #include "arm_compute/runtime/CL/CLTensor.h"
  34 #include "arm_compute/runtime/CL/functions/CLScharr3x3.h"
  35 #include "arm_compute/runtime/IFunction.h"
  36 #include "arm_compute/runtime/IMemoryManager.h"
  37
  38 #include <cstddef>
  39 #include <cstdint>
  40 #include <memory>
  41
  42 namespace arm_compute
  43 {
  44 class CLPyramid;
  45
  46 /** OpenCL Array of Internal Keypoints */
  47 using CLLKInternalKeypointArray = CLArray<CLLKInternalKeypoint>;
  48 /** OpenCL Array of Coefficient Tables */
  49 using CLCoefficientTableArray = CLArray<CLCoefficientTable>;
  50 /** OpenCL Array of Old Values */
  51 using CLOldValueArray = CLArray<CLOldValue>;
  52
  53 /** Basic function to execute optical flow. This function calls the following OpenCL kernels and functions:
  54  *
  55  * -# @ref CLScharr3x3
  56  * -# @ref CLLKTrackerInitKernel
  57  * -# @ref CLLKTrackerStage0Kernel
  58  * -# @ref CLLKTrackerStage1Kernel
  59  * -# @ref CLLKTrackerFinalizeKernel
  60  */
  61 class CLOpticalFlow : public IFunction
  62 {
  63 public:
  64     /** Default constructor */
  65     CLOpticalFlow(std::shared_ptr<IMemoryManager> memory_manager = nullptr);
  66     /** Prevent instances of this class from being copied (As this class contains pointers) */
  67     CLOpticalFlow(const CLOpticalFlow &) = delete;
  68     /** Prevent instances of this class from being copied (As this class contains pointers) */
  69     CLOpticalFlow &operator=(const CLOpticalFlow &) = delete;
  70     /** Allow instances of this class to be moved */
  71     CLOpticalFlow(CLOpticalFlow &&) = default;
  72     /** Allow instances of this class to be moved */
  73     CLOpticalFlow &operator=(CLOpticalFlow &&) = default;
  74     /**  Initialise the function input and output
  75      *
  76      * @param[in]  old_pyramid           Pointer to the pyramid for the old tensor. Data types supported U8
  77      * @param[in]  new_pyramid           Pointer to the pyramid for the new tensor. Data types supported U8
  78      * @param[in]  old_points            Pointer to the IKeyPointArray storing old key points
  79      * @param[in]  new_points_estimates  Pointer to the IKeyPointArray storing new estimates key points
  80      * @param[out] new_points            Pointer to the IKeyPointArray storing new key points
  81      * @param[in]  termination           The criteria to terminate the search of each keypoint.
  82      * @param[in]  epsilon               The error for terminating the algorithm
  83      * @param[in]  num_iterations        The maximum number of iterations before terminate the alogrithm
  84      * @param[in]  window_dimension      The size of the window on which to perform the algorithm
  85      * @param[in]  use_initial_estimate  The flag to indicate whether the initial estimated position should be used
  86      * @param[in]  border_mode           The border mode applied at scharr kernel stage
  87      * @param[in]  constant_border_value (Optional) Constant value to use for borders if border_mode is set to CONSTANT
  88      *
  89      */
  90     void configure(const CLPyramid *old_pyramid, const CLPyramid *new_pyramid,
  91                    const ICLKeyPointArray *old_points, const ICLKeyPointArray *new_points_estimates, ICLKeyPointArray *new_points,
  92                    Termination termination, float epsilon, size_t num_iterations, size_t window_dimension, bool use_initial_estimate,
  93                    BorderMode border_mode, uint8_t constant_border_value = 0);
  94
  95     // Inherited methods overridden:
  96     void run() override;
  97
  98 private:
  99     CLMemoryGroup                              _memory_group;
 100     std::unique_ptr<CLLKTrackerInitKernel[]>   _tracker_init_kernel;
 101     std::unique_ptr<CLLKTrackerStage0Kernel[]> _tracker_stage0_kernel;
 102     std::unique_ptr<CLLKTrackerStage1Kernel[]> _tracker_stage1_kernel;
 103     CLLKTrackerFinalizeKernel                  _tracker_finalize_kernel;
 104     std::unique_ptr<CLScharr3x3[]>             _func_scharr;
 105     std::unique_ptr<CLTensor[]>                _scharr_gx;
 106     std::unique_ptr<CLTensor[]>                _scharr_gy;
 107     const ICLKeyPointArray                    *_old_points;
 108     const ICLKeyPointArray                    *_new_points_estimates;
 109     ICLKeyPointArray                          *_new_points;
 110     std::unique_ptr<CLLKInternalKeypointArray> _old_points_internal;
 111     std::unique_ptr<CLLKInternalKeypointArray> _new_points_internal;
 112     std::unique_ptr<CLCoefficientTableArray>   _coefficient_table;
 113     std::unique_ptr<CLOldValueArray>           _old_values;
 114     size_t                                     _num_levels;
 115 };
 116 }
 117 #endif /*__ARM_COMPUTE_CLOPTICALFLOW_H__ */