arm_compute/core/Types.h

   1 /*
   2  * Copyright (c) 2016, 2017 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_TYPES_H__
  25 #define __ARM_COMPUTE_TYPES_H__
  26
  27 #include "arm_compute/core/Coordinates.h"
  28 #include "arm_compute/core/TensorShape.h"
  29
  30 #include <cstddef>
  31 #include <cstdint>
  32 #include <string>
  33 #include <utility>
  34
  35 namespace arm_compute
  36 {
  37 /** Image colour formats */
  38 enum class Format
  39 {
  40     UNKNOWN,  /** Unknown image format */
  41     U8,       /** 1 channel, 1 U8 per channel */
  42     S16,      /** 1 channel, 1 S16 per channel */
  43     U16,      /** 1 channel, 1 U16 per channel */
  44     S32,      /** 1 channel, 1 S32 per channel */
  45     U32,      /** 1 channel, 1 U32 per channel */
  46     F16,      /** 1 channel, 1 F16 per channel */
  47     F32,      /** 1 channel, 1 F32 per channel */
  48     UV88,     /** 2 channel, 1 U8 per channel */
  49     RGB888,   /** 3 channels, 1 U8 per channel */
  50     RGBA8888, /** 4 channels, 1 U8 per channel */
  51     YUV444,   /** A 3 plane of 8 bit 4:4:4 sampled Y, U, V planes */
  52     YUYV422,  /** A single plane of 32-bit macro pixel of Y0, U0, Y1, V0 bytes */
  53     NV12,     /** A 2 plane YUV format of Luma (Y) and interleaved UV data at 4:2:0 sampling */
  54     NV21,     /** A 2 plane YUV format of Luma (Y) and interleaved VU data at 4:2:0 sampling */
  55     IYUV,     /** A 3 plane of 8-bit 4:2:0 sampled Y, U, V planes */
  56     UYVY422   /** A single plane of 32-bit macro pixel of U0, Y0, V0, Y1 byte */
  57 };
  58
  59 /** Available data types */
  60 enum class DataType
  61 {
  62     UNKNOWN,
  63     U8,
  64     S8,
  65     U16,
  66     S16,
  67     U32,
  68     S32,
  69     U64,
  70     S64,
  71     F16,
  72     F32,
  73     F64,
  74     SIZET
  75 };
  76
  77 /** Constant value of the border pixels when using BorderMode::CONSTANT */
  78 constexpr uint8_t CONSTANT_BORDER_VALUE = 199;
  79
  80 /* Constant value used to indicate a half-scale pyramid */
  81 constexpr float SCALE_PYRAMID_HALF = 0.5f;
  82
  83 /* Constant value used to indicate a ORB scaled pyramid */
  84 constexpr float SCALE_PYRAMID_ORB = 8.408964152537146130583778358414e-01;
  85
  86 struct ValidRegion
  87 {
  88     ValidRegion()
  89         : anchor{}, shape{}
  90     {
  91     }
  92
  93     ValidRegion(const ValidRegion &) = default;
  94     ValidRegion(ValidRegion &&)      = default;
  95     ValidRegion &operator=(const ValidRegion &) = default;
  96     ValidRegion &operator=(ValidRegion &&) = default;
  97     ~ValidRegion()                         = default;
  98
  99     ValidRegion(Coordinates anchor, TensorShape shape)
 100         : anchor{ anchor }, shape{ shape }
 101     {
 102     }
 103
 104     /** Return the start of the valid region for the given dimension @p d */
 105     int start(unsigned int d) const
 106     {
 107         return anchor[d];
 108     }
 109
 110     /** Return the end of the valid region for the given dimension @p d */
 111     int end(unsigned int d) const
 112     {
 113         return anchor[d] + shape[d];
 114     }
 115
 116     Coordinates anchor;
 117     TensorShape shape;
 118 };
 119
 120 /** Methods available to handle borders */
 121 enum class BorderMode
 122 {
 123     UNDEFINED, /**< Borders are left undefined */
 124     CONSTANT,  /**< Pixels outside the image are assumed to have a constant value */
 125     REPLICATE  /**< Pixels outside the image are assumed to have the same value as the closest image pixel */
 126 };
 127
 128 /** Container for 2D border size */
 129 struct BorderSize
 130 {
 131     /** Empty border, i.e. no border */
 132     constexpr BorderSize()
 133         : top{ 0 }, right{ 0 }, bottom{ 0 }, left{ 0 }
 134     {
 135     }
 136
 137     /** Border with equal size around the 2D plane */
 138     constexpr BorderSize(unsigned int size)
 139         : top{ size }, right{ size }, bottom{ size }, left{ size }
 140     {
 141     }
 142
 143     /** Border with same size for top/bottom and left/right */
 144     constexpr BorderSize(unsigned int top_bottom, unsigned int left_right)
 145         : top{ top_bottom }, right{ left_right }, bottom{ top_bottom }, left{ left_right }
 146     {
 147     }
 148
 149     /** Border with different sizes */
 150     constexpr BorderSize(unsigned int top, unsigned int right, unsigned int bottom, unsigned int left)
 151         : top{ top }, right{ right }, bottom{ bottom }, left{ left }
 152     {
 153     }
 154
 155     /** Check if the entire border is zero */
 156     constexpr bool empty() const
 157     {
 158         return top == 0 && right == 0 && bottom == 0 && left == 0;
 159     }
 160
 161     /** Check if the border is the same size on all sides */
 162     constexpr bool uniform() const
 163     {
 164         return top == right && top == bottom && top == left;
 165     }
 166
 167     BorderSize &operator*=(float scale)
 168     {
 169         top *= scale;
 170         right *= scale;
 171         bottom *= scale;
 172         left *= scale;
 173
 174         return *this;
 175     }
 176
 177     BorderSize operator*(float scale)
 178     {
 179         BorderSize size = *this;
 180         size *= scale;
 181
 182         return size;
 183     }
 184
 185     unsigned int top;
 186     unsigned int right;
 187     unsigned int bottom;
 188     unsigned int left;
 189 };
 190
 191 using PaddingSize = BorderSize;
 192
 193 /** Policy to handle overflow */
 194 enum class ConvertPolicy
 195 {
 196     WRAP,    /**< Wrap around */
 197     SATURATE /**< Saturate */
 198 };
 199
 200 /** Interpolation method */
 201 enum class InterpolationPolicy
 202 {
 203     NEAREST_NEIGHBOR, /**< Output values are defined to match the source pixel whose center is nearest to the sample position */
 204     BILINEAR,         /**< Output values are defined by bilinear interpolation between the pixels */
 205     AREA,             /**< Output values are determined by averaging the source pixels whose areas fall under the area of the destination pixel, projected onto the source image */
 206 };
 207
 208 /** Bilinear Interpolation method used by LKTracker */
 209 enum class BilinearInterpolation
 210 {
 211     BILINEAR_OLD_NEW,
 212     BILINEAR_SCHARR
 213 };
 214
 215 /** Threshold mode */
 216 enum class ThresholdType
 217 {
 218     BINARY, /**< Threshold with one value */
 219     RANGE   /**< Threshold with two values*/
 220 };
 221
 222 /** Rounding method */
 223 enum class RoundingPolicy
 224 {
 225     TO_ZERO,        /**< Truncates the least significand values that are lost in operations. */
 226     TO_NEAREST_EVEN /**< Rounds to nearest even output value */
 227 };
 228
 229 /** Termination criteria */
 230 enum class Termination
 231 {
 232     TERM_CRITERIA_EPSILON,
 233     TERM_CRITERIA_ITERATIONS,
 234     TERM_CRITERIA_BOTH
 235 };
 236
 237 /** Magnitude calculation type. */
 238 enum class MagnitudeType
 239 {
 240     L1NORM, /**< L1 normalization type */
 241     L2NORM  /**< L2 normalization type */
 242 };
 243
 244 /** Phase calculation type.
 245  *
 246  * @note When PhaseType == SIGNED, each angle is mapped to the range 0 to 255 inclusive otherwise angles between 0 and 180
 247  */
 248 enum class PhaseType
 249 {
 250     SIGNED,  /**< Angle range: [0, 360] */
 251     UNSIGNED /**< Angle range: [0, 180] */
 252 };
 253
 254 /** Keypoint type */
 255 struct KeyPoint
 256 {
 257     int32_t x{ 0 };               /**< X coordinates */
 258     int32_t y{ 0 };               /**< Y coordinates */
 259     float   strength{ 0.f };      /**< Strength of the point */
 260     float   scale{ 0.f };         /**< Scale initialized to 0 by the corner detector */
 261     float   orientation{ 0.f };   /**< Orientation initialized to 0 by the corner detector */
 262     int32_t tracking_status{ 0 }; /**< Status initialized to 1 by the corner detector, set to 0 when the point is lost */
 263     float   error{ 0.f };         /**< Tracking error initialized to 0 by the corner detector */
 264 };
 265
 266 using InternalKeypoint = std::tuple<float, float, float>; /* x,y,strength */
 267
 268 /** Rectangle type */
 269 struct Rectangle
 270 {
 271     uint16_t x;      /**< Top-left x coordinate */
 272     uint16_t y;      /**< Top-left y coordinate */
 273     uint16_t width;  /**< Width of the rectangle */
 274     uint16_t height; /**< Height of the rectangle */
 275 };
 276
 277 /** Coordinate type */
 278 struct Coordinates2D
 279 {
 280     int32_t x; /**< X coordinates */
 281     int32_t y; /**< Y coordinates */
 282 };
 283
 284 /** Coordinate type */
 285 struct Coordinates3D
 286 {
 287     uint32_t x; /**< X coordinates */
 288     uint32_t y; /**< Y coordinates */
 289     uint32_t z; /**< Z coordinates */
 290 };
 291
 292 /** Available channels */
 293 enum class Channel
 294 {
 295     UNKNOWN, /** Unknown channel format */
 296     C0,      /**< First channel (used by formats with unknown channel types). */
 297     C1,      /**< Second channel (used by formats with unknown channel types). */
 298     C2,      /**< Third channel (used by formats with unknown channel types). */
 299     C3,      /**< Fourth channel (used by formats with unknown channel types). */
 300     R,       /**< Red channel. */
 301     G,       /**< Green channel. */
 302     B,       /**< Blue channel. */
 303     A,       /**< Alpha channel. */
 304     Y,       /**< Luma channel. */
 305     U,       /**< Cb/U channel. */
 306     V        /**< Cr/V/Value channel. */
 307 };
 308
 309 /** Available matrix patterns */
 310 enum class MatrixPattern
 311 {
 312     BOX,   /**< Box pattern matrix. */
 313     CROSS, /**< Cross pattern matrix. */
 314     DISK,  /**< Disk pattern matrix. */
 315     OTHER  /**< Any other matrix pattern. */
 316 };
 317
 318 /** Available non linear functions. */
 319 enum class NonLinearFilterFunction : unsigned
 320 {
 321     MEDIAN = 0, /**< Non linear median filter. */
 322     MIN    = 1, /**< Non linear erode. */
 323     MAX    = 2, /**< Non linear dilate. */
 324 };
 325
 326 /** The normalization type used for the normalization layer */
 327 enum class NormType
 328 {
 329     IN_MAP,   /* Normalization applied within the same map */
 330     CROSS_MAP /* Normalization applied cross maps */
 331 };
 332
 333 /** Normalization type for Histogram of Oriented Gradients (HOG) */
 334 enum class HOGNormType
 335 {
 336     L2_NORM,    /**< L2-norm */
 337     L2HYS_NORM, /**< L2-norm followed by clipping */
 338     L1_NORM,    /**< L1 norm */
 339     L1SQRT_NORM /**< L1 norm with SQRT */
 340 };
 341
 342 /** Detection window used for the object detection. The detection window keeps the following information:
 343  *
 344  *  -# Geometry of the rectangular window (x/y of top-left corner and width/height)
 345  *  -# Index of the class used for evaluating which class the detection window belongs to
 346  *  -# Confidence value (score) obtained with the classifier
 347  */
 348 struct DetectionWindow
 349 {
 350     uint16_t x{ 0 };         /**< Top-left x coordinate */
 351     uint16_t y{ 0 };         /**< Top-left y coordinate */
 352     uint16_t width{ 0 };     /**< Width of the detection window */
 353     uint16_t height{ 0 };    /**< Height of the detection window */
 354     uint16_t idx_class{ 0 }; /**< Index of the class */
 355     float    score{ 0.f };   /**< Confidence value for the detection window */
 356 };
 357
 358 /** Dimension rounding type when down-scaling on CNNs
 359  * @note Used in pooling and convolution layer
 360  */
 361 enum class DimensionRoundingType
 362 {
 363     FLOOR, /**< Floor rounding */
 364     CEIL   /**< Ceil rounding */
 365 };
 366
 367 /** Available pooling types */
 368 enum class PoolingType
 369 {
 370     MAX, /**< Max Pooling */
 371     AVG  /**< Average Pooling */
 372 };
 373
 374 /** Padding and stride information class */
 375 class PadStrideInfo
 376 {
 377 public:
 378     /** Constructor
 379      *
 380      * @param[in] stride_x (Optional) Stride, in elements, across x. Defaults to 1.
 381      * @param[in] stride_y (Optional) Stride, in elements, across y. Defaults to 1.
 382      * @param[in] pad_x    (Optional) Padding, in elements, across x. Defaults to 0.
 383      * @param[in] pad_y    (Optional) Padding, in elements, across y. Defaults to 0.
 384      * @param[in] round    (Optional) Dimensions rounding. Defaults to @ref FLOOR.
 385      */
 386     PadStrideInfo(unsigned int stride_x = 1, unsigned int stride_y = 1,
 387                   unsigned int pad_x = 0, unsigned int pad_y = 0,
 388                   DimensionRoundingType round = DimensionRoundingType::FLOOR)
 389         : _stride(std::make_pair(stride_x, stride_y)),
 390           _pad(std::make_pair(pad_x, pad_y)),
 391           _round_type(round)
 392     {
 393     }
 394     std::pair<unsigned int, unsigned int> stride() const
 395     {
 396         return _stride;
 397     }
 398     std::pair<unsigned int, unsigned int> pad() const
 399     {
 400         return _pad;
 401     }
 402     DimensionRoundingType round() const
 403     {
 404         return _round_type;
 405     }
 406
 407 private:
 408     std::pair<unsigned int, unsigned int> _stride;
 409     std::pair<unsigned int, unsigned int> _pad;
 410     DimensionRoundingType _round_type;
 411 };
 412
 413 /** Pooling Layer Information class */
 414 class PoolingLayerInfo
 415 {
 416 public:
 417     /** Default Constructor
 418      *
 419      * @param[in] pool_type       Pooling type @ref PoolingType. Defaults to @ref PoolingType::MAX
 420      * @param[in] pool_size       (Optional) Pooling size, in elements, across  x and y. Defaults to 2.
 421      * @param[in] pad_stride_info (Optional) Padding and stride information @ref PadStrideInfo
 422      */
 423     PoolingLayerInfo(PoolingType pool_type = PoolingType::MAX, unsigned int pool_size = 2, PadStrideInfo pad_stride_info = PadStrideInfo())
 424         : _pool_type(pool_type), _pool_size(pool_size), _pad_stride_info(pad_stride_info)
 425     {
 426     }
 427     PoolingType pool_type() const
 428     {
 429         return _pool_type;
 430     }
 431     unsigned int pool_size() const
 432     {
 433         return _pool_size;
 434     }
 435     PadStrideInfo pad_stride_info() const
 436     {
 437         return _pad_stride_info;
 438     }
 439
 440 private:
 441     PoolingType   _pool_type;
 442     unsigned int  _pool_size;
 443     PadStrideInfo _pad_stride_info;
 444 };
 445
 446 /** Activation Layer Information class */
 447 class ActivationLayerInfo
 448 {
 449 public:
 450     /** Available activation functions */
 451     enum class ActivationFunction
 452     {
 453         LOGISTIC,     /**< Logistic */
 454         TANH,         /**< Hyperbolic tangent */
 455         RELU,         /**< Rectifier */
 456         BOUNDED_RELU, /**< Bounded Rectifier */
 457         SOFT_RELU,    /**< Soft Rectifier */
 458         ABS,          /**< Absolute */
 459         SQUARE,       /**< Square */
 460         SQRT,         /**< Square root */
 461         LINEAR        /**< Linear */
 462     };
 463
 464     /** Default Constructor
 465      *
 466      * @param[in] f The activation function to use.
 467      * @param[in] a (Optional) The alpha parameter used by some activation functions
 468      *              (@ref ActivationFunction::BOUNDED_RELU, @ref ActivationFunction::LINEAR, @ref ActivationFunction::TANH).
 469      * @param[in] b (Optional) The beta parameter used by some activation functions (@ref ActivationFunction::LINEAR, @ref ActivationFunction::TANH).
 470      */
 471     ActivationLayerInfo(ActivationFunction f, float a = 0.0f, float b = 0.0f)
 472         : _act(f), _a(a), _b(b)
 473     {
 474     }
 475     ActivationFunction activation() const
 476     {
 477         return _act;
 478     }
 479     float a() const
 480     {
 481         return _a;
 482     }
 483     float b() const
 484     {
 485         return _b;
 486     }
 487
 488 private:
 489     ActivationFunction _act;
 490     float              _a;
 491     float              _b;
 492 };
 493
 494 /** Normalization Layer Information class */
 495 class NormalizationLayerInfo
 496 {
 497 public:
 498     /** Default Constructor
 499      *
 500      * @param[in] type      The normalization type. Can be @ref NormType::IN_MAP or NORM_TYPE::CROSS_MAP
 501      * @param[in] norm_size The normalization size is the number of elements to normalize across. Defaults to 5.
 502      * @param[in] alpha     Alpha parameter used by normalization equation. Defaults to 0.0001.
 503      * @param[in] beta      Beta parameter used by normalization equation. Defaults to 0.5.
 504      * @param[in] kappa     Kappa parameter used by [Krichevksy 2012] Across Channel Local Brightness Normalization equation.
 505      */
 506     NormalizationLayerInfo(NormType type, uint32_t norm_size = 5, float alpha = 0.0001f, float beta = 0.5f, float kappa = 1.f)
 507         : _type(type), _norm_size(norm_size), _alpha(alpha), _beta(beta), _kappa(kappa)
 508     {
 509     }
 510     NormType type() const
 511     {
 512         return _type;
 513     }
 514     uint32_t norm_size() const
 515     {
 516         return _norm_size;
 517     }
 518     float alpha() const
 519     {
 520         return _alpha;
 521     }
 522     float beta() const
 523     {
 524         return _beta;
 525     }
 526     float kappa() const
 527     {
 528         return _kappa;
 529     }
 530     /** Return the scaling factor of the normalization function. If kappa is not 1 then [Krichevksy 2012] normalization scaling is specified.
 531      * @return The normalization scaling factor.
 532      */
 533     float scale_coeff() const
 534     {
 535         return (_kappa == 1.f) ? (_alpha / _norm_size) : _alpha;
 536     }
 537
 538 private:
 539     NormType _type;
 540     uint32_t _norm_size;
 541     float    _alpha;
 542     float    _beta;
 543     float    _kappa;
 544 };
 545
 546 /** IO formatting information class*/
 547 struct IOFormatInfo
 548 {
 549     /** Precision type used when printing floating point numbers */
 550     enum class PrecisionType
 551     {
 552         Default, /**< Default precision to the one that the current stream has */
 553         Custom,  /**< Custom precision specified by the user using the precision parameter */
 554         Full     /**< The maximum precision of the floating point representation */
 555     };
 556
 557     /** Specifies the area to be printed, used by Tensor objects */
 558     enum class PrintRegion
 559     {
 560         ValidRegion, /**< Prints the valid region of the Tensor object */
 561         NoPadding,   /**< Prints the Tensor object without the padding */
 562         Full         /**< Print the tensor object including padding */
 563     };
 564
 565     IOFormatInfo(PrintRegion   print_region   = PrintRegion::ValidRegion,
 566                  PrecisionType precision_type = PrecisionType::Default,
 567                  unsigned int  precision      = 10,
 568                  bool          align_columns  = true,
 569                  std::string   element_delim  = " ",
 570                  std::string   row_delim      = "\n")
 571         : print_region(print_region),
 572           precision_type(precision_type),
 573           precision(precision),
 574           element_delim(element_delim),
 575           row_delim(row_delim),
 576           align_columns(align_columns)
 577     {
 578     }
 579
 580     PrintRegion   print_region;
 581     PrecisionType precision_type;
 582     unsigned int  precision;
 583     std::string   element_delim;
 584     std::string   row_delim;
 585     bool          align_columns;
 586 };
 587 }
 588 #endif /* __ARM_COMPUTE_TYPES_H__ */