2 * Copyright (c) 2017 ARM Limited.
4 * SPDX-License-Identifier: MIT
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:
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
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
24 #ifndef __ARM_COMPUTE_CLLKTRACKERKERNEL_H__
25 #define __ARM_COMPUTE_CLLKTRACKERKERNEL_H__
27 #include "arm_compute/core/CL/ICLArray.h"
28 #include "arm_compute/core/CL/ICLKernel.h"
29 #include "arm_compute/core/Types.h"
38 /** Internal keypoint structure for Lucas-Kanade Optical Flow */
39 struct CLLKInternalKeypoint
41 float x{ 0.f }; /**< x coordinate of the keypoint */
42 float y{ 0.f }; /**< y coordinate of the keypoint */
43 float tracking_status{ 0.f }; /**< the tracking status of the keypoint */
44 float dummy{ 0.f }; /**< Dummy field, to make sure the data structure 128-bit align, so that GPU can use vload4 */
47 /** Structure for storing Spatial Gradient Matrix and the minimum eigenvalue for each keypoint */
48 struct CLCoefficientTable
50 float A11; /**< iA11 * FLT_SCALE */
51 float A12; /**< iA11 * FLT_SCALE */
52 float A22; /**< iA11 * FLT_SCALE */
53 float min_eig; /**< Minimum eigenvalue */
56 /** Structure for storing ival, ixval and iyval for each point inside the window */
59 int16_t ival; /**< ival extracts from old image */
60 int16_t ixval; /**< ixval extracts from scharr Gx image */
61 int16_t iyval; /**< iyval extracts from scharr Gy image */
62 int16_t dummy; /**< Dummy field, to make sure the data structure 128-bit align, so that GPU can use vload4 */
65 using ICLLKInternalKeypointArray = ICLArray<CLLKInternalKeypoint>;
66 using ICLCoefficientTableArray = ICLArray<CLCoefficientTable>;
67 using ICLOldValArray = ICLArray<CLOldValue>;
69 /** Interface to run the initialization step of LKTracker */
70 class CLLKTrackerInitKernel : public ICLKernel
73 /** Initialise the kernel input and output
75 * @param[in] old_points Pointer to the @ref ICLKeyPointArray storing old key points
76 * @param[in] new_points_estimates Pointer to the @ref ICLKeyPointArray storing new estimates key points
77 * @param[out] old_points_internal Pointer to the array of internal @ref CLLKInternalKeypoint old points
78 * @param[out] new_points_internal Pointer to the array of internal @ref CLLKInternalKeypoint new points
79 * @param[in] use_initial_estimate The flag to indicate whether the initial estimated position should be used
80 * @param[in] level The pyramid level
81 * @param[in] num_levels The number of pyramid levels
82 * @param[in] pyramid_scale Scale factor used for generating the pyramid
84 void configure(const ICLKeyPointArray *old_points, const ICLKeyPointArray *new_points_estimates,
85 ICLLKInternalKeypointArray *old_points_internal, ICLLKInternalKeypointArray *new_points_internal,
86 bool use_initial_estimate, size_t level, size_t num_levels, float pyramid_scale);
88 // Inherited methods overridden:
89 void run(const Window &window, cl::CommandQueue &queue) override;
92 /** Interface to run the finalize step of LKTracker, where it truncates the coordinates stored in new_points array */
93 class CLLKTrackerFinalizeKernel : public ICLKernel
96 /** Initialise the kernel input and output
98 * @param[in] new_points_internal Pointer to the array of internal @ref CLLKInternalKeypoint new points
99 * @param[out] new_points Pointer to the @ref ICLKeyPointArray storing new key points
101 void configure(ICLLKInternalKeypointArray *new_points_internal, ICLKeyPointArray *new_points);
103 // Inherited methods overridden:
104 void run(const Window &window, cl::CommandQueue &queue) override;
107 /** Interface to run the first stage of LKTracker, where A11, A12, A22, min_eig, ival, ixval and iyval are computed */
108 class CLLKTrackerStage0Kernel : public ICLKernel
111 /** Initialise the kernel input and output
113 * @param[in] old_input Pointer to the input old tensor. Data types supported: U8
114 * @param[in] old_scharr_gx Pointer to the input scharr X tensor. Data types supported: S16
115 * @param[in] old_scharr_gy Pointer to the input scharr Y tensor. Data types supported: S16
116 * @param[in] old_points_internal Pointer to the array of CLLKInternalKeypoint old points
117 * @param[in, out] new_points_internal Pointer to the array of CLLKInternalKeypoint new points
118 * @param[out] coeff_table Pointer to the array holding the Spatial Gradient coefficients
119 * @param[out] old_ival Pointer to the array holding internal values
120 * @param[in] window_dimension The size of the window on which to perform the algorithm
121 * @param[in] level The pyramid level
122 * @param[in] border_offset The offset used to define the boundary of the tracked pixels in different border modes
124 void configure(const ICLTensor *old_input, const ICLTensor *old_scharr_gx, const ICLTensor *old_scharr_gy,
125 ICLLKInternalKeypointArray *old_points_internal, ICLLKInternalKeypointArray *new_points_internal,
126 ICLCoefficientTableArray *coeff_table, ICLOldValArray *old_ival,
127 size_t window_dimension, size_t level, int32_t border_offset);
129 // Inherited methods overridden:
130 void run(const Window &window, cl::CommandQueue &queue) override;
133 /** Interface to run the second stage of LKTracker, where the motion vectors of the given points are computed */
134 class CLLKTrackerStage1Kernel : public ICLKernel
137 /** Initialise the kernel input and output
139 * @param[in] new_input Pointer to the input new tensor. Data types supported: U8
140 * @param[in, out] new_points_internal Pointer to the array of CLLKInternalKeypoint for new points
141 * @param[in] coeff_table Pointer to the array holding the Spatial Gradient coefficients
142 * @param[in] old_ival Pointer to the array holding internal values
143 * @param[in] termination The criteria to terminate the search of each keypoint.
144 * @param[in] epsilon The error for terminating the algorithm
145 * @param[in] num_iterations The maximum number of iterations before terminating the algorithm
146 * @param[in] window_dimension The size of the window on which to perform the algorithm
147 * @param[in] level The pyramid level
148 * @param[in] border_offset The offset used to define the boundary of the tracked pixels in different border modes
150 void configure(const ICLTensor *new_input, ICLLKInternalKeypointArray *new_points_internal, ICLCoefficientTableArray *coeff_table, ICLOldValArray *old_ival,
151 Termination termination, float epsilon, size_t num_iterations, size_t window_dimension, size_t level, int32_t border_offset);
153 // Inherited methods overridden:
154 void run(const Window &window, cl::CommandQueue &queue) override;
157 #endif /*__ARM_COMPUTE_CLLKTRACKERKERNEL_H__ */