Compute Library
 20.02.1
Helpers.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2019 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_HELPERS_H
25 #define ARM_COMPUTE_HELPERS_H
26 
28 #include "arm_compute/core/Error.h"
30 #include "arm_compute/core/Steps.h"
33 #include "arm_compute/core/Types.h"
35 
36 #include <array>
37 #include <cstddef>
38 #include <cstdint>
39 #include <memory>
40 #include <tuple>
41 #include <type_traits>
42 #include <utility>
43 
44 namespace arm_compute
45 {
46 class IKernel;
47 class ITensor;
48 class ITensorInfo;
49 
50 /** Disable bitwise operations by default */
51 template <typename T>
53 {
54  static constexpr bool value = false; /**< Disabled */
55 };
56 
57 #ifndef DOXYGEN_SKIP_THIS
58 template <typename T>
59 typename std::enable_if<enable_bitwise_ops<T>::value, T>::type operator&(T lhs, T rhs)
60 {
61  using underlying_type = typename std::underlying_type<T>::type;
62  return static_cast<T>(static_cast<underlying_type>(lhs) & static_cast<underlying_type>(rhs));
63 }
64 #endif /* DOXYGEN_SKIP_THIS */
65 
66 /** Helper function to create and return a unique_ptr pointed to a CL/GLES kernel object
67  * It also calls the kernel's configuration.
68  *
69  * @param[in] args All the arguments that need pass to kernel's configuration.
70  *
71  * @return A unique pointer pointed to a CL/GLES kernel object
72  */
73 template <typename Kernel, typename... T>
74 std::unique_ptr<Kernel> create_configure_kernel(T &&... args)
75 {
76  std::unique_ptr<Kernel> k = arm_compute::support::cpp14::make_unique<Kernel>();
77  k->configure(std::forward<T>(args)...);
78  return k;
79 }
80 
81 /** Helper function to create and return a unique_ptr pointed to a CL/GLES kernel object
82  *
83  * @return A unique pointer pointed to a Kernel kernel object
84  */
85 template <typename Kernel>
86 std::unique_ptr<Kernel> create_kernel()
87 {
88  std::unique_ptr<Kernel> k = arm_compute::support::cpp14::make_unique<Kernel>();
89  return k;
90 }
91 
92 namespace traits
93 {
94 /** Check if a type T is contained in a tuple Tuple of types */
95 template <typename T, typename Tuple>
96 struct is_contained;
97 
98 template <typename T>
99 struct is_contained<T, std::tuple<>> : std::false_type
100 {
101 };
102 
103 template <typename T, typename... Ts>
104 struct is_contained<T, std::tuple<T, Ts...>> : std::true_type
105 {
106 };
107 
108 template <typename T, typename U, typename... Ts>
109 struct is_contained<T, std::tuple<U, Ts...>> : is_contained<T, std::tuple<Ts...>>
110 {
111 };
112 }
113 
114 /** Computes bilinear interpolation using the pointer to the top-left pixel and the pixel's distance between
115  * the real coordinates and the smallest following integer coordinates. Input must be in single channel format.
116  *
117  * @param[in] pixel_ptr Pointer to the top-left pixel value of a single channel input.
118  * @param[in] stride Stride to access the bottom-left and bottom-right pixel values
119  * @param[in] dx Pixel's distance between the X real coordinate and the smallest X following integer
120  * @param[in] dy Pixel's distance between the Y real coordinate and the smallest Y following integer
121  *
122  * @note dx and dy must be in the range [0, 1.0]
123  *
124  * @return The bilinear interpolated pixel value
125  */
126 template <typename T>
127 inline T delta_bilinear_c1(const T *pixel_ptr, size_t stride, float dx, float dy)
128 {
129  ARM_COMPUTE_ERROR_ON(pixel_ptr == nullptr);
130 
131  const float dx1 = 1.0f - dx;
132  const float dy1 = 1.0f - dy;
133 
134  const T a00 = *pixel_ptr;
135  const T a01 = *(pixel_ptr + 1);
136  const T a10 = *(pixel_ptr + stride);
137  const T a11 = *(pixel_ptr + stride + 1);
138 
139  const float w1 = dx1 * dy1;
140  const float w2 = dx * dy1;
141  const float w3 = dx1 * dy;
142  const float w4 = dx * dy;
143 
144  return static_cast<T>(a00 * w1 + a01 * w2 + a10 * w3 + a11 * w4);
145 }
146 
147 /** Computes bilinear interpolation for quantized input and output, using the pointer to the top-left pixel and the pixel's distance between
148  * the real coordinates and the smallest following integer coordinates. Input must be quantized and in single channel format.
149  *
150  * @param[in] pixel_ptr Pointer to the top-left pixel value of a single channel input.
151  * @param[in] stride Stride to access the bottom-left and bottom-right pixel values
152  * @param[in] dx Pixel's distance between the X real coordinate and the smallest X following integer
153  * @param[in] dy Pixel's distance between the Y real coordinate and the smallest Y following integer
154  * @param[in] iq_info Input QuantizationInfo
155  * @param[in] oq_info Output QuantizationInfo
156  *
157  * @note dx and dy must be in the range [0, 1.0]
158  *
159  * @return The bilinear interpolated pixel value
160  */
161 inline uint8_t delta_bilinear_c1_quantized(const uint8_t *pixel_ptr, size_t stride, float dx, float dy, UniformQuantizationInfo iq_info, UniformQuantizationInfo oq_info)
162 {
163  ARM_COMPUTE_ERROR_ON(pixel_ptr == nullptr);
164 
165  const float dx1 = 1.0f - dx;
166  const float dy1 = 1.0f - dy;
167 
168  const float a00 = dequantize_qasymm8(*pixel_ptr, iq_info);
169  const float a01 = dequantize_qasymm8(*(pixel_ptr + 1), iq_info);
170  const float a10 = dequantize_qasymm8(*(pixel_ptr + stride), iq_info);
171  const float a11 = dequantize_qasymm8(*(pixel_ptr + stride + 1), iq_info);
172 
173  const float w1 = dx1 * dy1;
174  const float w2 = dx * dy1;
175  const float w3 = dx1 * dy;
176  const float w4 = dx * dy;
177  float res = a00 * w1 + a01 * w2 + a10 * w3 + a11 * w4;
178  return static_cast<uint8_t>(quantize_qasymm8(res, oq_info));
179 }
180 
181 /** Computes linear interpolation using the pointer to the top pixel and the pixel's distance between
182  * the real coordinates and the smallest following integer coordinates. Input must be in single channel format.
183  *
184  * @param[in] pixel_ptr Pointer to the top pixel value of a single channel input.
185  * @param[in] stride Stride to access the bottom pixel value
186  * @param[in] dy Pixel's distance between the Y real coordinate and the smallest Y following integer
187  *
188  * @note dy must be in the range [0, 1.0]
189  *
190  * @return The linear interpolated pixel value
191  */
192 template <typename T>
193 inline T delta_linear_c1_y(const T *pixel_ptr, size_t stride, float dy)
194 {
195  ARM_COMPUTE_ERROR_ON(pixel_ptr == nullptr);
196 
197  const float dy1 = 1.0f - dy;
198 
199  const T a00 = *pixel_ptr;
200  const T a10 = *(pixel_ptr + stride);
201 
202  const float w1 = dy1;
203  const float w3 = dy;
204 
205  return static_cast<T>(a00 * w1 + a10 * w3);
206 }
207 /** Computes linear interpolation using the pointer to the left pixel and the pixel's distance between
208  * the real coordinates and the smallest following integer coordinates. Input must be in single channel format.
209  *
210  * @param[in] pixel_ptr Pointer to the left pixel value of a single channel input.
211  * @param[in] dx Pixel's distance between the X real coordinate and the smallest X following integer
212  *
213  * @note dx must be in the range [0, 1.0]
214  *
215  * @return The linear interpolated pixel value
216  */
217 template <typename T>
218 inline T delta_linear_c1_x(const T *pixel_ptr, float dx)
219 {
220  ARM_COMPUTE_ERROR_ON(pixel_ptr == nullptr);
221 
222  const T a00 = *pixel_ptr;
223  const T a01 = *(pixel_ptr + 1);
224 
225  const float dx1 = 1.0f - dx;
226 
227  const float w1 = dx1;
228  const float w2 = dx;
229 
230  return static_cast<T>(a00 * w1 + a01 * w2);
231 }
232 /** Return the pixel at (x,y) using bilinear interpolation.
233  *
234  * @warning Only works if the iterator was created with an IImage
235  *
236  * @param[in] first_pixel_ptr Pointer to the first pixel of a single channel input.
237  * @param[in] stride Stride in bytes of the image;
238  * @param[in] x X position of the wanted pixel
239  * @param[in] y Y position of the wanted pixel
240  *
241  * @return The pixel at (x, y) using bilinear interpolation.
242  */
243 template <typename T>
244 inline T pixel_bilinear_c1(const T *first_pixel_ptr, size_t stride, float x, float y)
245 {
246  ARM_COMPUTE_ERROR_ON(first_pixel_ptr == nullptr);
247 
248  const int32_t xi = std::floor(x);
249  const int32_t yi = std::floor(y);
250 
251  const float dx = x - xi;
252  const float dy = y - yi;
253 
254  return delta_bilinear_c1(first_pixel_ptr + xi + yi * stride, stride, dx, dy);
255 }
256 
257 /** Return the pixel at (x,y) using bilinear interpolation by clamping when out of borders. The image must be single channel input
258  *
259  * @warning Only works if the iterator was created with an IImage
260  *
261  * @param[in] first_pixel_ptr Pointer to the first pixel of a single channel image.
262  * @param[in] stride Stride in bytes of the image
263  * @param[in] width Width of the image
264  * @param[in] height Height of the image
265  * @param[in] x X position of the wanted pixel
266  * @param[in] y Y position of the wanted pixel
267  *
268  * @return The pixel at (x, y) using bilinear interpolation.
269  */
270 template <typename T>
271 inline uint8_t pixel_bilinear_c1_clamp(const T *first_pixel_ptr, size_t stride, size_t width, size_t height, float x, float y)
272 {
273  ARM_COMPUTE_ERROR_ON(first_pixel_ptr == nullptr);
274 
275  x = std::max(-1.f, std::min(x, static_cast<float>(width)));
276  y = std::max(-1.f, std::min(y, static_cast<float>(height)));
277 
278  const float xi = std::floor(x);
279  const float yi = std::floor(y);
280 
281  const float dx = x - xi;
282  const float dy = y - yi;
283 
284  if(dx == 0.0f)
285  {
286  if(dy == 0.0f)
287  {
288  return static_cast<T>(first_pixel_ptr[static_cast<int32_t>(xi) + static_cast<int32_t>(yi) * stride]);
289  }
290  return delta_linear_c1_y(first_pixel_ptr + static_cast<int32_t>(xi) + static_cast<int32_t>(yi) * stride, stride, dy);
291  }
292  if(dy == 0.0f)
293  {
294  return delta_linear_c1_x(first_pixel_ptr + static_cast<int32_t>(xi) + static_cast<int32_t>(yi) * stride, dx);
295  }
296  return delta_bilinear_c1(first_pixel_ptr + static_cast<int32_t>(xi) + static_cast<int32_t>(yi) * stride, stride, dx, dy);
297 }
298 
299 /** Return the pixel at (x,y) using area interpolation by clamping when out of borders. The image must be single channel U8
300  *
301  * @note The interpolation area depends on the width and height ration of the input and output images
302  * @note Currently average of the contributing pixels is calculated
303  *
304  * @param[in] first_pixel_ptr Pointer to the first pixel of a single channel U8 image.
305  * @param[in] stride Stride in bytes of the image
306  * @param[in] width Width of the image
307  * @param[in] height Height of the image
308  * @param[in] wr Width ratio among the input image width and output image width.
309  * @param[in] hr Height ratio among the input image height and output image height.
310  * @param[in] x X position of the wanted pixel
311  * @param[in] y Y position of the wanted pixel
312  *
313  * @return The pixel at (x, y) using area interpolation.
314  */
315 inline uint8_t pixel_area_c1u8_clamp(const uint8_t *first_pixel_ptr, size_t stride, size_t width, size_t height, float wr, float hr, int x, int y);
316 
317 /** Iterator updated by @ref execute_window_loop for each window element */
318 class Iterator
319 {
320 public:
321  /** Default constructor to create an empty iterator */
322  constexpr Iterator();
323  /** Create a container iterator for the metadata and allocation contained in the ITensor
324  *
325  * @param[in] tensor The tensor to associate to the iterator.
326  * @param[in] window The window which will be used to iterate over the tensor.
327  */
328  Iterator(const ITensor *tensor, const Window &window);
329 
330  /** Increment the iterator along the specified dimension of the step value associated to the dimension.
331  *
332  * @warning It is the caller's responsibility to call increment(dimension+1) when reaching the end of a dimension, the iterator will not check for overflow.
333  *
334  * @note When incrementing a dimension 'n' the coordinates of all the dimensions in the range (0,n-1) are reset. For example if you iterate over a 2D image, everytime you change row (dimension 1), the iterator for the width (dimension 0) is reset to its start.
335  *
336  * @param[in] dimension Dimension to increment
337  */
338  void increment(size_t dimension);
339 
340  /** Return the offset in bytes from the first element to the current position of the iterator
341  *
342  * @return The current position of the iterator in bytes relative to the first element.
343  */
344  constexpr int offset() const;
345 
346  /** Return a pointer to the current pixel.
347  *
348  * @warning Only works if the iterator was created with an ITensor.
349  *
350  * @return equivalent to buffer() + offset()
351  */
352  constexpr uint8_t *ptr() const;
353 
354  /** Move the iterator back to the beginning of the specified dimension.
355  *
356  * @param[in] dimension Dimension to reset
357  */
358  void reset(size_t dimension);
359 
360 private:
361  uint8_t *_ptr;
362 
363  class Dimension
364  {
365  public:
366  constexpr Dimension()
367  : _dim_start(0), _stride(0)
368  {
369  }
370 
371  int _dim_start;
372  int _stride;
373  };
374 
375  std::array<Dimension, Coordinates::num_max_dimensions> _dims;
376 };
377 
378 /** Iterate through the passed window, automatically adjusting the iterators and calling the lambda_functino for each element.
379  * It passes the x and y positions to the lambda_function for each iteration
380  *
381  * @param[in] w Window to iterate through.
382  * @param[in] lambda_function The function of type void(function)( const Coordinates & id ) to call at each iteration.
383  * Where id represents the absolute coordinates of the item to process.
384  * @param[in,out] iterators Tensor iterators which will be updated by this function before calling lambda_function.
385  */
386 template <typename L, typename... Ts>
387 inline void execute_window_loop(const Window &w, L &&lambda_function, Ts &&... iterators);
388 
389 /** Update window and padding size for each of the access patterns.
390  *
391  * First the window size is reduced based on all access patterns that are not
392  * allowed to modify the padding of the underlying tensor. Then the padding of
393  * the remaining tensors is increased to match the window.
394  *
395  * @param[in] win Window that is used by the kernel.
396  * @param[in] patterns Access patterns used to calculate the final window and padding.
397  *
398  * @return True if the window has been changed. Changes to the padding do not
399  * influence the returned value.
400  */
401 template <typename... Ts>
402 bool update_window_and_padding(Window &win, Ts &&... patterns)
403 {
404  bool window_changed = false;
405 
406  utility::for_each([&](const IAccessWindow & w)
407  {
408  window_changed |= w.update_window_if_needed(win);
409  },
410  patterns...);
411 
412  bool padding_changed = false;
413 
415  {
416  padding_changed |= w.update_padding_if_needed(win);
417  },
418  patterns...);
419 
420  return window_changed;
421 }
422 
423 /** Calculate the maximum window for a given tensor shape and border setting
424  *
425  * @param[in] valid_region Valid region object defining the shape of the tensor space for which the window is created.
426  * @param[in] steps (Optional) Number of elements processed for each step.
427  * @param[in] skip_border (Optional) If true exclude the border region from the window.
428  * @param[in] border_size (Optional) Border size.
429  *
430  * @return The maximum window the kernel can be executed on.
431  */
432 Window calculate_max_window(const ValidRegion &valid_region, const Steps &steps = Steps(), bool skip_border = false, BorderSize border_size = BorderSize());
433 
434 /** Calculate the maximum window for a given tensor shape and border setting
435  *
436  * @param[in] info Tensor info object defining the shape of the object for which the window is created.
437  * @param[in] steps (Optional) Number of elements processed for each step.
438  * @param[in] skip_border (Optional) If true exclude the border region from the window.
439  * @param[in] border_size (Optional) Border size.
440  *
441  * @return The maximum window the kernel can be executed on.
442  */
443 inline Window calculate_max_window(const ITensorInfo &info, const Steps &steps = Steps(), bool skip_border = false, BorderSize border_size = BorderSize())
444 {
445  return calculate_max_window(info.valid_region(), steps, skip_border, border_size);
446 }
447 
448 /** Calculate the maximum window used by a horizontal kernel for a given tensor shape and border setting
449  *
450  * @param[in] valid_region Valid region object defining the shape of the tensor space for which the window is created.
451  * @param[in] steps (Optional) Number of elements processed for each step.
452  * @param[in] skip_border (Optional) If true exclude the border region from the window.
453  * @param[in] border_size (Optional) Border size. The border region will be excluded from the window.
454  *
455  * @return The maximum window the kernel can be executed on.
456  */
457 Window calculate_max_window_horizontal(const ValidRegion &valid_region, const Steps &steps = Steps(), bool skip_border = false, BorderSize border_size = BorderSize());
458 
459 /** Calculate the maximum window used by a horizontal kernel for a given tensor shape and border setting
460  *
461  * @param[in] info Tensor info object defining the shape of the object for which the window is created.
462  * @param[in] steps (Optional) Number of elements processed for each step.
463  * @param[in] skip_border (Optional) If true exclude the border region from the window.
464  * @param[in] border_size (Optional) Border size.
465  *
466  * @return The maximum window the kernel can be executed on.
467  */
468 inline Window calculate_max_window_horizontal(const ITensorInfo &info, const Steps &steps = Steps(), bool skip_border = false, BorderSize border_size = BorderSize())
469 {
470  return calculate_max_window_horizontal(info.valid_region(), steps, skip_border, border_size);
471 }
472 
473 /** Calculate the maximum window for a given tensor shape and border setting. The window will also includes the border.
474  *
475  * @param[in] valid_region Valid region object defining the shape of the tensor space for which the window is created.
476  * @param[in] steps (Optional) Number of elements processed for each step.
477  * @param[in] border_size (Optional) Border size. The border region will be included in the window.
478  *
479  * @return The maximum window the kernel can be executed on.
480  */
481 Window calculate_max_enlarged_window(const ValidRegion &valid_region, const Steps &steps = Steps(), BorderSize border_size = BorderSize());
482 
483 /** Calculate the maximum window for a given tensor shape and border setting. The window will also includes the border.
484  *
485  * @param[in] info Tensor info object defining the shape of the object for which the window is created.
486  * @param[in] steps (Optional) Number of elements processed for each step.
487  * @param[in] border_size (Optional) Border size. The border region will be included in the window.
488  *
489  * @return The maximum window the kernel can be executed on.
490  */
491 inline Window calculate_max_enlarged_window(const ITensorInfo &info, const Steps &steps = Steps(), BorderSize border_size = BorderSize())
492 {
493  return calculate_max_enlarged_window(info.valid_region(), steps, border_size);
494 }
495 
496 /** Intersect multiple valid regions.
497  *
498  * @param[in] regions Valid regions.
499  *
500  * @return Intersection of all regions.
501  */
502 template <typename... Ts>
503 ValidRegion intersect_valid_regions(const Ts &... regions)
504 {
505  auto intersect = [](const ValidRegion & r1, const ValidRegion & r2) -> ValidRegion
506  {
507  ValidRegion region;
508 
509  for(size_t d = 0; d < std::min(r1.anchor.num_dimensions(), r2.anchor.num_dimensions()); ++d)
510  {
511  region.anchor.set(d, std::max(r1.anchor[d], r2.anchor[d]));
512  }
513 
514  for(size_t d = 0; d < std::min(r1.shape.num_dimensions(), r2.shape.num_dimensions()); ++d)
515  {
516  region.shape.set(d, std::min(r1.shape[d], r2.shape[d]));
517  }
518 
519  return region;
520  };
521 
522  return utility::foldl(intersect, regions...);
523 }
524 
525 /** Create a strides object based on the provided strides and the tensor dimensions.
526  *
527  * @param[in] info Tensor info object providing the shape of the tensor for unspecified strides.
528  * @param[in] stride_x Stride to be used in X dimension (in bytes).
529  * @param[in] fixed_strides Strides to be used in higher dimensions starting at Y (in bytes).
530  *
531  * @return Strides object based on the specified strides. Missing strides are
532  * calculated based on the tensor shape and the strides of lower dimensions.
533  */
534 template <typename T, typename... Ts>
535 inline Strides compute_strides(const ITensorInfo &info, T stride_x, Ts &&... fixed_strides)
536 {
537  const TensorShape &shape = info.tensor_shape();
538 
539  // Create strides object
540  Strides strides(stride_x, fixed_strides...);
541 
542  for(size_t i = 1 + sizeof...(Ts); i < info.num_dimensions(); ++i)
543  {
544  strides.set(i, shape[i - 1] * strides[i - 1]);
545  }
546 
547  return strides;
548 }
549 
550 /** Create a strides object based on the tensor dimensions.
551  *
552  * @param[in] info Tensor info object used to compute the strides.
553  *
554  * @return Strides object based on element size and tensor shape.
555  */
556 template <typename... Ts>
558 {
559  return compute_strides(info, info.element_size());
560 }
561 
562 /** Permutes given Dimensions according to a permutation vector
563  *
564  * @warning Validity of permutation is not checked
565  *
566  * @param[in, out] dimensions Dimensions to permute
567  * @param[in] perm Permutation vector
568  */
569 template <typename T>
570 inline void permute(Dimensions<T> &dimensions, const PermutationVector &perm)
571 {
572  auto dimensions_copy = utility::make_array<Dimensions<T>::num_max_dimensions>(dimensions.begin(), dimensions.end());
573  for(unsigned int i = 0; i < perm.num_dimensions(); ++i)
574  {
575  T dimension_val = (perm[i] < dimensions.num_dimensions()) ? dimensions_copy[perm[i]] : 0;
576  dimensions.set(i, dimension_val);
577  }
578 }
579 
580 /** Permutes given TensorShape according to a permutation vector
581  *
582  * @warning Validity of permutation is not checked
583  *
584  * @param[in, out] shape Shape to permute
585  * @param[in] perm Permutation vector
586  */
587 inline void permute(TensorShape &shape, const PermutationVector &perm)
588 {
589  TensorShape shape_copy = shape;
590  for(unsigned int i = 0; i < perm.num_dimensions(); ++i)
591  {
592  size_t dimension_val = (perm[i] < shape.num_dimensions()) ? shape_copy[perm[i]] : 1;
593  shape.set(i, dimension_val, false); // Avoid changes in _num_dimension
594  }
595 }
596 
597 /** Auto initialize the tensor info (shape, number of channels and data type) if the current assignment is empty.
598  *
599  * @param[in,out] info Tensor info used to check and assign.
600  * @param[in] shape New shape.
601  * @param[in] num_channels New number of channels.
602  * @param[in] data_type New data type
603  * @param[in] quantization_info (Optional) New quantization info
604  *
605  * @return True if the tensor info has been initialized
606  */
607 bool auto_init_if_empty(ITensorInfo &info,
608  const TensorShape &shape,
609  int num_channels, DataType data_type,
610  QuantizationInfo quantization_info = QuantizationInfo());
611 
612 /** Auto initialize the tensor info using another tensor info.
613  *
614  * @param info_sink Tensor info used to check and assign
615  * @param info_source Tensor info used to assign
616  *
617  * @return True if the tensor info has been initialized
618  */
619 bool auto_init_if_empty(ITensorInfo &info_sink, const ITensorInfo &info_source);
620 
621 /** Set the shape to the specified value if the current assignment is empty.
622  *
623  * @param[in,out] info Tensor info used to check and assign.
624  * @param[in] shape New shape.
625  *
626  * @return True if the shape has been changed.
627  */
628 bool set_shape_if_empty(ITensorInfo &info, const TensorShape &shape);
629 
630 /** Set the format, data type and number of channels to the specified value if
631  * the current data type is unknown.
632  *
633  * @param[in,out] info Tensor info used to check and assign.
634  * @param[in] format New format.
635  *
636  * @return True if the format has been changed.
637  */
638 bool set_format_if_unknown(ITensorInfo &info, Format format);
639 
640 /** Set the data type and number of channels to the specified value if
641  * the current data type is unknown.
642  *
643  * @param[in,out] info Tensor info used to check and assign.
644  * @param[in] data_type New data type.
645  *
646  * @return True if the data type has been changed.
647  */
648 bool set_data_type_if_unknown(ITensorInfo &info, DataType data_type);
649 
650 /** Set the data layout to the specified value if
651  * the current data layout is unknown.
652  *
653  * @param[in,out] info Tensor info used to check and assign.
654  * @param[in] data_layout New data layout.
655  *
656  * @return True if the data type has been changed.
657  */
659 
660 /** Set the quantization info to the specified value if
661  * the current quantization info is empty and the data type of asymmetric quantized type
662  *
663  * @param[in,out] info Tensor info used to check and assign.
664  * @param[in] quantization_info Quantization info
665  *
666  * @return True if the quantization info has been changed.
667  */
668 bool set_quantization_info_if_empty(ITensorInfo &info, QuantizationInfo quantization_info);
669 
670 /** Helper function to calculate the Valid Region for Scale.
671  *
672  * @param[in] src_info Input tensor info used to check.
673  * @param[in] dst_shape Shape of the output.
674  * @param[in] interpolate_policy Interpolation policy.
675  * @param[in] sampling_policy Sampling policy.
676  * @param[in] border_undefined True if the border is undefined.
677  *
678  * @return The corresponding valid region
679  */
680 ValidRegion calculate_valid_region_scale(const ITensorInfo &src_info, const TensorShape &dst_shape,
681  InterpolationPolicy interpolate_policy, SamplingPolicy sampling_policy, bool border_undefined);
682 
683 /** Convert a linear index into n-dimensional coordinates.
684  *
685  * @param[in] shape Shape of the n-dimensional tensor.
686  * @param[in] index Linear index specifying the i-th element.
687  *
688  * @return n-dimensional coordinates.
689  */
690 inline Coordinates index2coords(const TensorShape &shape, int index);
691 
692 /** Convert n-dimensional coordinates into a linear index.
693  *
694  * @param[in] shape Shape of the n-dimensional tensor.
695  * @param[in] coord N-dimensional coordinates.
696  *
697  * @return linead index
698  */
699 inline int coords2index(const TensorShape &shape, const Coordinates &coord);
700 
701 /** Get the index of the given dimension.
702  *
703  * @param[in] data_layout The data layout.
704  * @param[in] data_layout_dimension The dimension which this index is requested for.
705  *
706  * @return The int conversion of the requested data layout index.
707  */
708 inline size_t get_data_layout_dimension_index(const DataLayout data_layout, const DataLayoutDimension data_layout_dimension);
709 
710 /** Get the DataLayoutDimension of a given index and layout.
711  *
712  * @param[in] data_layout The data layout.
713  * @param[in] index The data layout index.
714  *
715  * @return The dimension which this index is requested for.
716  */
718 
719 /** Calculate the normalization dimension index for a given normalization type
720  *
721  * @param[in] layout Data layout of the input and output tensor
722  * @param[in] info Normalization info
723  *
724  * @return Normalization dimension index
725  */
727 {
728  const unsigned int width_idx = get_data_layout_dimension_index(layout, DataLayoutDimension::WIDTH);
729  const unsigned int channel_idx = get_data_layout_dimension_index(layout, DataLayoutDimension::CHANNEL);
730 
731  return info.is_in_map() ? width_idx : channel_idx;
732 }
733 
734 /** Calculate the number of output tiles required by Winograd Convolution layer. This utility function can be used by the Winograd input transform
735  * to know the number of tiles on the x and y direction
736  *
737  * @param[in] in_dims Spatial dimensions of the input tensor of convolution layer
738  * @param[in] kernel_size Kernel size
739  * @param[in] output_tile_size Size of a single output tile
740  * @param[in] conv_info Convolution info (i.e. pad, stride,...)
741  *
742  * @return the number of output tiles along the x and y directions of size "output_tile_size"
743  */
744 inline Size2D compute_winograd_convolution_tiles(const Size2D &in_dims, const Size2D &kernel_size, const Size2D &output_tile_size, const PadStrideInfo &conv_info)
745 {
746  int num_tiles_x = std::ceil((in_dims.width - (kernel_size.width - 1) + conv_info.pad_left() + conv_info.pad_right()) / static_cast<float>(output_tile_size.width));
747  int num_tiles_y = std::ceil((in_dims.height - (kernel_size.height - 1) + conv_info.pad_top() + conv_info.pad_bottom()) / static_cast<float>(output_tile_size.height));
748 
749  // Clamp in case we provide paddings but we have 1D convolution
750  num_tiles_x = std::min(num_tiles_x, static_cast<int>(in_dims.width));
751  num_tiles_y = std::min(num_tiles_y, static_cast<int>(in_dims.height));
752 
753  return Size2D(num_tiles_x, num_tiles_y);
754 }
755 
756 /** Wrap-around a number within the range 0 <= x < m
757  *
758  * @param[in] x Input value
759  * @param[in] m Range
760  *
761  * @return the wrapped-around number
762  */
763 template <typename T>
764 inline T wrap_around(T x, T m)
765 {
766  return x >= 0 ? x % m : (x % m + m) % m;
767 }
768 
769 /** Convert negative coordinates to positive in the range [0, num_dims_input]
770  *
771  * @param[out] coords Array of coordinates to be converted.
772  * @param[in] max_value Maximum value to be used when wrapping the negative values in coords
773  */
774 inline Coordinates &convert_negative_axis(Coordinates &coords, int max_value)
775 {
776  for(unsigned int i = 0; i < coords.num_dimensions(); ++i)
777  {
778  coords[i] = wrap_around(coords[i], max_value);
779  }
780  return coords;
781 }
782 
783 /** Given an integer value, this function returns the next power of two
784  *
785  * @param[in] x Input value
786  *
787  * @return the next power of two
788  */
789 inline unsigned int get_next_power_two(unsigned int x)
790 {
791  // Decrement by 1
792  x--;
793 
794  // Shift right by 1
795  x |= x >> 1u;
796  // Shift right by 2
797  x |= x >> 2u;
798  // Shift right by 4
799  x |= x >> 4u;
800  // Shift right by 8
801  x |= x >> 8u;
802  // Shift right by 16
803  x |= x >> 16u;
804 
805  // Increment by 1
806  x++;
807 
808  return x;
809 }
810 } // namespace arm_compute
811 
813 #endif /*ARM_COMPUTE_HELPERS_H */
InterpolationPolicy
Interpolation method.
Definition: Types.h:366
SimpleTensor< float > w
Definition: DFT.cpp:156
T delta_linear_c1_x(const T *pixel_ptr, float dx)
Computes linear interpolation using the pointer to the left pixel and the pixel's distance between th...
Definition: Helpers.h:218
Shape of a tensor.
Definition: TensorShape.h:39
const DataLayout data_layout
Definition: Im2Col.cpp:146
static constexpr bool value
Disabled.
Definition: Helpers.h:54
Disable bitwise operations by default.
Definition: Helpers.h:52
Coordinates index2coords(const TensorShape &shape, int index)
Convert a linear index into n-dimensional coordinates.
Definition: Helpers.inl:290
uint8_t delta_bilinear_c1_quantized(const uint8_t *pixel_ptr, size_t stride, float dx, float dy, UniformQuantizationInfo iq_info, UniformQuantizationInfo oq_info)
Computes bilinear interpolation for quantized input and output, using the pointer to the top-left pix...
Definition: Helpers.h:161
float dequantize_qasymm8(uint8_t value, const INFO_TYPE &qinfo)
Dequantize a value given an unsigned 8-bit asymmetric quantization scheme.
TensorShape shape
Shape of the valid region.
Definition: Types.h:257
Container for 2D border size.
Definition: Types.h:269
void increment(size_t dimension)
Increment the iterator along the specified dimension of the step value associated to the dimension.
Definition: Helpers.inl:168
unsigned int get_next_power_two(unsigned int x)
Given an integer value, this function returns the next power of two.
Definition: Helpers.h:789
uint8_t quantize_qasymm8(float value, const INFO_TYPE &qinfo, RoundingPolicy rounding_policy=RoundingPolicy::TO_NEAREST_UP)
Quantize a value given an unsigned 8-bit asymmetric quantization scheme.
DataLayoutDimension
[DataLayout enum definition]
Definition: Types.h:126
std::unique_ptr< Kernel > create_configure_kernel(T &&... args)
Helper function to create and return a unique_ptr pointed to a CL/GLES kernel object It also calls th...
Definition: Helpers.h:74
Normalization Layer Information class.
Definition: Types.h:1677
#define ARM_COMPUTE_ERROR_ON(cond)
If the condition is true then an error message is printed and an exception thrown.
Definition: Error.h:466
Store the tensor's metadata.
Definition: ITensorInfo.h:40
Quantization info when assuming per layer quantization.
bool set_data_layout_if_unknown(ITensorInfo &info, DataLayout data_layout)
Set the data layout to the specified value if the current data layout is unknown.
Definition: Helpers.inl:268
Size2D compute_winograd_convolution_tiles(const Size2D &in_dims, const Size2D &kernel_size, const Size2D &output_tile_size, const PadStrideInfo &conv_info)
Calculate the number of output tiles required by Winograd Convolution layer.
Definition: Helpers.h:744
void set(size_t dimension, T value)
Accessor to set the value of one of the dimensions.
Definition: Dimensions.h:74
Interface for NEON tensor.
Definition: ITensor.h:36
bool set_data_type_if_unknown(ITensorInfo &info, DataType data_type)
Set the data type and number of channels to the specified value if the current data type is unknown.
Definition: Helpers.inl:257
Window calculate_max_window(const ValidRegion &valid_region, const Steps &steps=Steps(), bool skip_border=false, BorderSize border_size=BorderSize())
Calculate the maximum window for a given tensor shape and border setting.
Definition: Helpers.cpp:28
Copyright (c) 2017-2020 ARM Limited.
bool auto_init_if_empty(ITensorInfo &info, const TensorShape &shape, int num_channels, DataType data_type, QuantizationInfo quantization_info=QuantizationInfo())
Auto initialize the tensor info (shape, number of channels and data type) if the current assignment i...
Definition: Helpers.inl:202
size_t height
Height of the image region or rectangle.
Definition: Size2D.h:93
Strides compute_strides(const ITensorInfo &info, T stride_x, Ts &&... fixed_strides)
Create a strides object based on the provided strides and the tensor dimensions.
Definition: Helpers.h:535
void permute(Dimensions< T > &dimensions, const PermutationVector &perm)
Permutes given Dimensions according to a permutation vector.
Definition: Helpers.h:570
Window calculate_max_enlarged_window(const ValidRegion &valid_region, const Steps &steps=Steps(), BorderSize border_size=BorderSize())
Calculate the maximum window for a given tensor shape and border setting.
Definition: Helpers.cpp:82
T wrap_around(T x, T m)
Wrap-around a number within the range 0 <= x < m.
Definition: Helpers.h:764
bool update_window_and_padding(Window &win, Ts &&... patterns)
Update window and padding size for each of the access patterns.
Definition: Helpers.h:402
T && foldl(F &&, T &&value)
Base case of foldl.
Definition: Utility.h:130
T delta_linear_c1_y(const T *pixel_ptr, size_t stride, float dy)
Computes linear interpolation using the pointer to the top pixel and the pixel's distance between the...
Definition: Helpers.h:193
Format
Image colour formats.
Definition: Types.h:53
constexpr int offset() const
Return the offset in bytes from the first element to the current position of the iterator.
Definition: Helpers.inl:180
Class to describe a number of elements in each dimension.
Definition: Steps.h:40
Interface describing methods to update access window and padding based on kernel parameters.
Definition: IAccessWindow.h:71
Coordinates of an item.
Definition: Coordinates.h:37
Check if a type T is contained in a tuple Tuple of types.
Definition: Helpers.h:96
Dimensions with dimensionality.
Definition: Dimensions.h:41
int coords2index(const TensorShape &shape, const Coordinates &coord)
Convert n-dimensional coordinates into a linear index.
Definition: Helpers.inl:309
constexpr uint8_t * ptr() const
Return a pointer to the current pixel.
Definition: Helpers.inl:185
Padding and stride information class.
Definition: Types.h:686
ValidRegion intersect_valid_regions(const Ts &... regions)
Intersect multiple valid regions.
Definition: Helpers.h:503
std::array< T, num_max_dimensions >::iterator begin()
Returns a read/write iterator that points to the first element in the dimension array.
Definition: Dimensions.h:194
std::unique_ptr< Kernel > create_kernel()
Helper function to create and return a unique_ptr pointed to a CL/GLES kernel object.
Definition: Helpers.h:86
DataLayoutDimension get_index_data_layout_dimension(const DataLayout data_layout, const size_t index)
Get the DataLayoutDimension of a given index and layout.
Definition: Helpers.inl:356
constexpr Iterator()
Default constructor to create an empty iterator.
Definition: Helpers.inl:136
T delta_bilinear_c1(const T *pixel_ptr, size_t stride, float dx, float dy)
Computes bilinear interpolation using the pointer to the top-left pixel and the pixel's distance betw...
Definition: Helpers.h:127
void for_each(F &&)
Base case of for_each.
Definition: Utility.h:108
TensorInfo src_info(src_shape, 1, data_type)
Strides of an item in bytes.
Definition: Strides.h:37
ValidRegion calculate_valid_region_scale(const ITensorInfo &src_info, const TensorShape &dst_shape, InterpolationPolicy interpolate_policy, SamplingPolicy sampling_policy, bool border_undefined)
Helper function to calculate the Valid Region for Scale.
Definition: Helpers.cpp:184
uint8_t pixel_area_c1u8_clamp(const uint8_t *first_pixel_ptr, size_t stride, size_t width, size_t height, float wr, float hr, int x, int y)
Return the pixel at (x,y) using area interpolation by clamping when out of borders.
Definition: Helpers.inl:32
DatasetMode operator &(DatasetMode t1, DatasetMode t2)
Definition: DatasetModes.h:48
void reset(size_t dimension)
Move the iterator back to the beginning of the specified dimension.
Definition: Helpers.inl:190
std::array< T, num_max_dimensions >::iterator end()
Returns a read/write iterator that points one past the last element in the dimension array.
Definition: Dimensions.h:218
size_t width
Width of the image region or rectangle.
Definition: Size2D.h:92
T pixel_bilinear_c1(const T *first_pixel_ptr, size_t stride, float x, float y)
Return the pixel at (x,y) using bilinear interpolation.
Definition: Helpers.h:244
Class for specifying the size of an image or rectangle.
Definition: Size2D.h:34
unsigned int num_dimensions() const
Returns the effective dimensionality of the tensor.
Definition: Dimensions.h:122
bool set_shape_if_empty(ITensorInfo &info, const TensorShape &shape)
Set the shape to the specified value if the current assignment is empty.
Definition: Helpers.inl:235
TensorShape & set(size_t dimension, size_t value, bool apply_dim_correction=true)
Accessor to set the value of one of the dimensions.
Definition: TensorShape.h:78
void execute_window_loop(const Window &w, L &&lambda_function, Ts &&... iterators)
Iterate through the passed window, automatically adjusting the iterators and calling the lambda_funct...
Definition: Helpers.inl:123
bool set_format_if_unknown(ITensorInfo &info, Format format)
Set the format, data type and number of channels to the specified value if the current data type is u...
Definition: Helpers.inl:246
Coordinates & convert_negative_axis(Coordinates &coords, int max_value)
Convert negative coordinates to positive in the range [0, num_dims_input].
Definition: Helpers.h:774
Container for valid region of a window.
Definition: Types.h:184
size_t get_data_layout_dimension_index(const DataLayout data_layout, const DataLayoutDimension data_layout_dimension)
Get the index of the given dimension.
Definition: Helpers.inl:327
uint8_t pixel_bilinear_c1_clamp(const T *first_pixel_ptr, size_t stride, size_t width, size_t height, float x, float y)
Return the pixel at (x,y) using bilinear interpolation by clamping when out of borders.
Definition: Helpers.h:271
Iterator updated by execute_window_loop for each window element.
Definition: Helpers.h:318
DataType
Available data types.
Definition: Types.h:75
unsigned int get_normalization_dimension_index(DataLayout layout, const NormalizationLayerInfo &info)
Calculate the normalization dimension index for a given normalization type.
Definition: Helpers.h:726
DataLayout
[DataLayout enum definition]
Definition: Types.h:117
bool set_quantization_info_if_empty(ITensorInfo &info, QuantizationInfo quantization_info)
Set the quantization info to the specified value if the current quantization info is empty and the da...
Definition: Helpers.inl:279
Describe a multidimensional execution window.
Definition: Window.h:39
Window calculate_max_window_horizontal(const ValidRegion &valid_region, const Steps &steps=Steps(), bool skip_border=false, BorderSize border_size=BorderSize())
Calculate the maximum window used by a horizontal kernel for a given tensor shape and border setting.
Definition: Helpers.cpp:131
Coordinates anchor
Anchor for the start of the valid region.
Definition: Types.h:256
SamplingPolicy
Available Sampling Policies.
Definition: Types.h:99