Compute Library
 19.08
CLOpticalFlow Class Reference

Basic function to execute optical flow. More...

#include <CLOpticalFlow.h>

Collaboration diagram for CLOpticalFlow:
[legend]

Public Member Functions

 CLOpticalFlow (std::shared_ptr< IMemoryManager > memory_manager=nullptr)
 Default constructor. More...
 
 CLOpticalFlow (const CLOpticalFlow &)=delete
 Prevent instances of this class from being copied (As this class contains pointers) More...
 
CLOpticalFlowoperator= (const CLOpticalFlow &)=delete
 Prevent instances of this class from being copied (As this class contains pointers) More...
 
 CLOpticalFlow (CLOpticalFlow &&)=default
 Allow instances of this class to be moved. More...
 
CLOpticalFlowoperator= (CLOpticalFlow &&)=default
 Allow instances of this class to be moved. More...
 
void configure (const CLPyramid *old_pyramid, const CLPyramid *new_pyramid, const ICLKeyPointArray *old_points, const ICLKeyPointArray *new_points_estimates, ICLKeyPointArray *new_points, Termination termination, float epsilon, size_t num_iterations, size_t window_dimension, bool use_initial_estimate, BorderMode border_mode, uint8_t constant_border_value=0)
 Initialise the function input and output. More...
 
void run () override
 Run the kernels contained in the function. More...
 
- Public Member Functions inherited from IFunction
virtual ~IFunction ()=default
 Destructor. More...
 
virtual void prepare ()
 Prepare the function for executing. More...
 

Detailed Description

Basic function to execute optical flow.

This function calls the following OpenCL kernels and functions:

  1. CLScharr3x3
  2. CLLKTrackerInitKernel
  3. CLLKTrackerStage0Kernel
  4. CLLKTrackerStage1Kernel
  5. CLLKTrackerFinalizeKernel

Definition at line 61 of file CLOpticalFlow.h.

Constructor & Destructor Documentation

◆ CLOpticalFlow() [1/3]

CLOpticalFlow ( std::shared_ptr< IMemoryManager memory_manager = nullptr)

Default constructor.

Definition at line 40 of file CLOpticalFlow.cpp.

41  : _memory_group(std::move(memory_manager)),
42  _tracker_init_kernel(),
43  _tracker_stage0_kernel(),
44  _tracker_stage1_kernel(),
45  _tracker_finalize_kernel(),
46  _func_scharr(),
47  _scharr_gx(),
48  _scharr_gy(),
49  _old_points(nullptr),
50  _new_points_estimates(nullptr),
51  _new_points(nullptr),
52  _old_points_internal(),
53  _new_points_internal(),
54  _coefficient_table(),
55  _old_values(),
56  _num_levels(0)
57 {
58 }

◆ CLOpticalFlow() [2/3]

CLOpticalFlow ( const CLOpticalFlow )
delete

Prevent instances of this class from being copied (As this class contains pointers)

◆ CLOpticalFlow() [3/3]

CLOpticalFlow ( CLOpticalFlow &&  )
default

Allow instances of this class to be moved.

Member Function Documentation

◆ configure()

void configure ( const CLPyramid old_pyramid,
const CLPyramid new_pyramid,
const ICLKeyPointArray old_points,
const ICLKeyPointArray new_points_estimates,
ICLKeyPointArray new_points,
Termination  termination,
float  epsilon,
size_t  num_iterations,
size_t  window_dimension,
bool  use_initial_estimate,
BorderMode  border_mode,
uint8_t  constant_border_value = 0 
)

Initialise the function input and output.

Parameters
[in]old_pyramidPointer to the pyramid for the old tensor. Data types supported U8
[in]new_pyramidPointer to the pyramid for the new tensor. Data types supported U8
[in]old_pointsPointer to the IKeyPointArray storing old key points
[in]new_points_estimatesPointer to the IKeyPointArray storing new estimates key points
[out]new_pointsPointer to the IKeyPointArray storing new key points
[in]terminationThe criteria to terminate the search of each keypoint.
[in]epsilonThe error for terminating the algorithm
[in]num_iterationsThe maximum number of iterations before terminate the alogrithm
[in]window_dimensionThe size of the window on which to perform the algorithm
[in]use_initial_estimateThe flag to indicate whether the initial estimated position should be used
[in]border_modeThe border mode applied at scharr kernel stage
[in]constant_border_value(Optional) Constant value to use for borders if border_mode is set to CONSTANT

Definition at line 60 of file CLOpticalFlow.cpp.

64 {
65  ARM_COMPUTE_ERROR_ON(nullptr == old_pyramid);
66  ARM_COMPUTE_ERROR_ON(nullptr == new_pyramid);
67  ARM_COMPUTE_ERROR_ON(nullptr == old_points);
68  ARM_COMPUTE_ERROR_ON(nullptr == new_points_estimates);
69  ARM_COMPUTE_ERROR_ON(nullptr == new_points);
70  ARM_COMPUTE_ERROR_ON(old_pyramid->info()->num_levels() != new_pyramid->info()->num_levels());
71  ARM_COMPUTE_ERROR_ON(0 == old_pyramid->info()->num_levels());
72  ARM_COMPUTE_ERROR_ON(old_pyramid->info()->width() != new_pyramid->info()->width());
73  ARM_COMPUTE_ERROR_ON(old_pyramid->info()->height() != new_pyramid->info()->height());
74  ARM_COMPUTE_ERROR_ON(use_initial_estimate && old_points->num_values() != new_points_estimates->num_values());
75 
76  // Set member variables
77  _old_points = old_points;
78  _new_points_estimates = new_points_estimates;
79  _new_points = new_points;
80  _num_levels = old_pyramid->info()->num_levels();
81 
82  const float pyr_scale = old_pyramid->info()->scale();
83  const int list_length = old_points->num_values();
84  const int old_values_list_length = list_length * window_dimension * window_dimension;
85 
86  // Create kernels and tensors
87  _tracker_init_kernel.resize(_num_levels);
88  _tracker_stage0_kernel.resize(_num_levels);
89  _tracker_stage1_kernel.resize(_num_levels);
90  _func_scharr.resize(_num_levels);
91  _scharr_gx.resize(_num_levels);
92  _scharr_gy.resize(_num_levels);
93 
94  // Create internal keypoint arrays
95  _old_points_internal = arm_compute::support::cpp14::make_unique<CLLKInternalKeypointArray>(list_length);
96  _old_points_internal->resize(list_length);
97  _new_points_internal = arm_compute::support::cpp14::make_unique<CLLKInternalKeypointArray>(list_length);
98  _new_points_internal->resize(list_length);
99  _coefficient_table = arm_compute::support::cpp14::make_unique<CLCoefficientTableArray>(list_length);
100  _coefficient_table->resize(list_length);
101  _old_values = arm_compute::support::cpp14::make_unique<CLOldValueArray>(old_values_list_length);
102  _old_values->resize(old_values_list_length);
103  _new_points->resize(list_length);
104 
105  for(size_t i = 0; i < _num_levels; ++i)
106  {
107  // Get images from the ith level of old and right pyramid
108  ICLImage *old_ith_input = old_pyramid->get_pyramid_level(i);
109  ICLImage *new_ith_input = new_pyramid->get_pyramid_level(i);
110 
111  // Get width and height of images
112  const unsigned int width_ith = old_ith_input->info()->dimension(0);
113  const unsigned int height_ith = new_ith_input->info()->dimension(1);
114 
115  // Initialize Scharr tensors
116  TensorInfo tensor_info(TensorShape(width_ith, height_ith), 1, DataType::S16);
117  _scharr_gx[i].allocator()->init(tensor_info);
118  _scharr_gy[i].allocator()->init(tensor_info);
119 
120  // Manage intermediate buffers
121  _memory_group.manage(&_scharr_gx[i]);
122  _memory_group.manage(&_scharr_gy[i]);
123 
124  // Init Scharr kernel
125  _func_scharr[i].configure(old_ith_input, &_scharr_gx[i], &_scharr_gy[i], border_mode, constant_border_value);
126 
127  // Init Lucas-Kanade init kernel
128  _tracker_init_kernel[i].configure(old_points, new_points_estimates, _old_points_internal.get(), _new_points_internal.get(), use_initial_estimate, i, _num_levels, pyr_scale);
129 
130  // Init Lucas-Kanade stage0 kernel
131  _tracker_stage0_kernel[i].configure(old_ith_input, &_scharr_gx[i], &_scharr_gy[i],
132  _old_points_internal.get(), _new_points_internal.get(), _coefficient_table.get(), _old_values.get(),
133  window_dimension, i);
134 
135  // Init Lucas-Kanade stage1 kernel
136  _tracker_stage1_kernel[i].configure(new_ith_input, _new_points_internal.get(), _coefficient_table.get(), _old_values.get(),
137  termination, epsilon, num_iterations, window_dimension, i);
138 
139  // Allocate intermediate buffers
140  _scharr_gx[i].allocator()->allocate();
141  _scharr_gy[i].allocator()->allocate();
142  }
143 
144  // Finalize Lucas-Kanade
145  _tracker_finalize_kernel.configure(_new_points_internal.get(), new_points);
146 }
Shape of a tensor.
Definition: TensorShape.h:39
virtual size_t dimension(size_t index) const =0
Return the size of the requested dimension.
constexpr float epsilon
const PyramidInfo * info() const override
Interface to be implemented by the child class to return the Pyramid's metadata.
Definition: CLPyramid.cpp:118
void resize(size_t num)
Resizes the array to contain "num" elements.
Definition: IArray.h:128
#define ARM_COMPUTE_ERROR_ON(cond)
If the condition is true then an error message is printed and an exception thrown.
Definition: Error.h:337
void configure(ICLLKInternalKeypointArray *new_points_internal, ICLKeyPointArray *new_points)
Initialise the kernel input and output.
size_t num_values() const
Number of values currently stored in the array.
Definition: IArray.h:68
void manage(TensorType *obj)
Sets a object to be managed by the given memory group.
virtual ITensorInfo * info() const =0
Interface to be implemented by the child class to return the tensor's metadata.
float scale() const
Return the scale factor of the pyramid.
1 channel, 1 S16 per channel
Interface for OpenCL tensor.
Definition: ICLTensor.h:42
CLTensor * get_pyramid_level(size_t index) const override
Retrieves a level of the pyramid as a ITensor pointer.
Definition: CLPyramid.cpp:123
Store the tensor's metadata.
Definition: TensorInfo.h:45
size_t width() const
Return the width of the 0th level tensor.
Definition: PyramidInfo.cpp:82
size_t num_levels() const
Return the number of the pyramid levels.
Definition: PyramidInfo.cpp:77
size_t height() const
Return the height of the 0th level tensor.
Definition: PyramidInfo.cpp:87

References ARM_COMPUTE_ERROR_ON, arm_compute::test::validation::border_mode, CLLKTrackerFinalizeKernel::configure(), ITensorInfo::dimension(), epsilon, CLPyramid::get_pyramid_level(), PyramidInfo::height(), ITensor::info(), CLPyramid::info(), MemoryGroupBase< TensorType >::manage(), PyramidInfo::num_levels(), IArray< T >::num_values(), IArray< T >::resize(), arm_compute::S16, PyramidInfo::scale(), and PyramidInfo::width().

◆ operator=() [1/2]

CLOpticalFlow& operator= ( const CLOpticalFlow )
delete

Prevent instances of this class from being copied (As this class contains pointers)

◆ operator=() [2/2]

CLOpticalFlow& operator= ( CLOpticalFlow &&  )
default

Allow instances of this class to be moved.

◆ run()

void run ( )
overridevirtual

Run the kernels contained in the function.

For NEON kernels:

  • Multi-threading is used for the kernels which are parallelisable.
  • By default std::thread::hardware_concurrency() threads are used.
Note
CPPScheduler::set_num_threads() can be used to manually set the number of threads

For OpenCL kernels:

  • All the kernels are enqueued on the queue associated with CLScheduler.
  • The queue is then flushed.
Note
The function will not block until the kernels are executed. It is the user's responsibility to wait.
Will call prepare() on first run if hasn't been done

Implements IFunction.

Definition at line 148 of file CLOpticalFlow.cpp.

149 {
150  ARM_COMPUTE_ERROR_ON_MSG(_num_levels == 0, "Unconfigured function");
151 
152  MemoryGroupResourceScope scope_mg(_memory_group);
153 
154  for(unsigned int level = _num_levels; level > 0; --level)
155  {
156  // Run Scharr kernel
157  _func_scharr[level - 1].run();
158 
159  // Run Lucas-Kanade init kernel
160  CLScheduler::get().enqueue(_tracker_init_kernel[level - 1]);
161 
162  // Run Lucas-Kanade stage0 kernel
163  CLScheduler::get().enqueue(_tracker_stage0_kernel[level - 1]);
164 
165  // Run Lucas-Kanade stage1 kernel
166  CLScheduler::get().enqueue(_tracker_stage1_kernel[level - 1]);
167  }
168 
169  CLScheduler::get().enqueue(_tracker_finalize_kernel, true);
170 }
static CLScheduler & get()
Access the scheduler singleton.
Definition: CLScheduler.cpp:41
void enqueue(ICLKernel &kernel, bool flush=true)
Schedule the execution of the passed kernel if possible.
Definition: CLScheduler.cpp:95
Memory group resources scope handling class.
Definition: IMemoryGroup.h:46
#define ARM_COMPUTE_ERROR_ON_MSG(cond,...)
Definition: Error.h:328

References ARM_COMPUTE_ERROR_ON_MSG, CLScheduler::enqueue(), and CLScheduler::get().


The documentation for this class was generated from the following files: