modules/dnn/include/opencv2/dnn/all_layers.hpp

   1 /*M///////////////////////////////////////////////////////////////////////////////////////
   2 //
   3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
   4 //
   5 //  By downloading, copying, installing or using the software you agree to this license.
   6 //  If you do not agree to this license, do not download, install,
   7 //  copy or use the software.
   8 //
   9 //
  10 //                           License Agreement
  11 //                For Open Source Computer Vision Library
  12 //
  13 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
  14 // Third party copyrights are property of their respective owners.
  15 //
  16 // Redistribution and use in source and binary forms, with or without modification,
  17 // are permitted provided that the following conditions are met:
  18 //
  19 //   * Redistribution's of source code must retain the above copyright notice,
  20 //     this list of conditions and the following disclaimer.
  21 //
  22 //   * Redistribution's in binary form must reproduce the above copyright notice,
  23 //     this list of conditions and the following disclaimer in the documentation
  24 //     and/or other materials provided with the distribution.
  25 //
  26 //   * The name of the copyright holders may not be used to endorse or promote products
  27 //     derived from this software without specific prior written permission.
  28 //
  29 // This software is provided by the copyright holders and contributors "as is" and
  30 // any express or implied warranties, including, but not limited to, the implied
  31 // warranties of merchantability and fitness for a particular purpose are disclaimed.
  32 // In no event shall the Intel Corporation or contributors be liable for any direct,
  33 // indirect, incidental, special, exemplary, or consequential damages
  34 // (including, but not limited to, procurement of substitute goods or services;
  35 // loss of use, data, or profits; or business interruption) however caused
  36 // and on any theory of liability, whether in contract, strict liability,
  37 // or tort (including negligence or otherwise) arising in any way out of
  38 // the use of this software, even if advised of the possibility of such damage.
  39 //
  40 //M*/
  41
  42 #ifndef OPENCV_DNN_DNN_ALL_LAYERS_HPP
  43 #define OPENCV_DNN_DNN_ALL_LAYERS_HPP
  44 #include <opencv2/dnn.hpp>
  45
  46 namespace cv {
  47 namespace dnn {
  48 CV__DNN_EXPERIMENTAL_NS_BEGIN
  49 //! @addtogroup dnn
  50 //! @{
  51
  52 /** @defgroup dnnLayerList Partial List of Implemented Layers
  53   @{
  54   This subsection of dnn module contains information about built-in layers and their descriptions.
  55
  56   Classes listed here, in fact, provides C++ API for creating instances of built-in layers.
  57   In addition to this way of layers instantiation, there is a more common factory API (see @ref dnnLayerFactory), it allows to create layers dynamically (by name) and register new ones.
  58   You can use both API, but factory API is less convenient for native C++ programming and basically designed for use inside importers (see @ref readNetFromCaffe(), @ref readNetFromTorch(), @ref readNetFromTensorflow()).
  59
  60   Built-in layers partially reproduce functionality of corresponding Caffe and Torch7 layers.
  61   In partuclar, the following layers and Caffe importer were tested to reproduce <a href="http://caffe.berkeleyvision.org/tutorial/layers.html">Caffe</a> functionality:
  62   - Convolution
  63   - Deconvolution
  64   - Pooling
  65   - InnerProduct
  66   - TanH, ReLU, Sigmoid, BNLL, Power, AbsVal
  67   - Softmax
  68   - Reshape, Flatten, Slice, Split
  69   - LRN
  70   - MVN
  71   - Dropout (since it does nothing on forward pass -))
  72 */
  73
  74     class CV_EXPORTS BlankLayer : public Layer
  75     {
  76     public:
  77         static Ptr<Layer> create(const LayerParams &params);
  78     };
  79
  80     //! LSTM recurrent layer
  81     class CV_EXPORTS LSTMLayer : public Layer
  82     {
  83     public:
  84         /** Creates instance of LSTM layer */
  85         static Ptr<LSTMLayer> create(const LayerParams& params);
  86
  87         /** @deprecated Use LayerParams::blobs instead.
  88         @brief Set trained weights for LSTM layer.
  89
  90         LSTM behavior on each step is defined by current input, previous output, previous cell state and learned weights.
  91
  92         Let @f$x_t@f$ be current input, @f$h_t@f$ be current output, @f$c_t@f$ be current state.
  93         Than current output and current cell state is computed as follows:
  94         @f{eqnarray*}{
  95         h_t &= o_t \odot tanh(c_t),               \\
  96         c_t &= f_t \odot c_{t-1} + i_t \odot g_t, \\
  97         @f}
  98         where @f$\odot@f$ is per-element multiply operation and @f$i_t, f_t, o_t, g_t@f$ is internal gates that are computed using learned wights.
  99
 100         Gates are computed as follows:
 101         @f{eqnarray*}{
 102         i_t &= sigmoid&(W_{xi} x_t + W_{hi} h_{t-1} + b_i), \\
 103         f_t &= sigmoid&(W_{xf} x_t + W_{hf} h_{t-1} + b_f), \\
 104         o_t &= sigmoid&(W_{xo} x_t + W_{ho} h_{t-1} + b_o), \\
 105         g_t &= tanh   &(W_{xg} x_t + W_{hg} h_{t-1} + b_g), \\
 106         @f}
 107         where @f$W_{x?}@f$, @f$W_{h?}@f$ and @f$b_{?}@f$ are learned weights represented as matrices:
 108         @f$W_{x?} \in R^{N_h \times N_x}@f$, @f$W_{h?} \in R^{N_h \times N_h}@f$, @f$b_? \in R^{N_h}@f$.
 109
 110         For simplicity and performance purposes we use @f$ W_x = [W_{xi}; W_{xf}; W_{xo}, W_{xg}] @f$
 111         (i.e. @f$W_x@f$ is vertical contacentaion of @f$ W_{x?} @f$), @f$ W_x \in R^{4N_h \times N_x} @f$.
 112         The same for @f$ W_h = [W_{hi}; W_{hf}; W_{ho}, W_{hg}], W_h \in R^{4N_h \times N_h} @f$
 113         and for @f$ b = [b_i; b_f, b_o, b_g]@f$, @f$b \in R^{4N_h} @f$.
 114
 115         @param Wh is matrix defining how previous output is transformed to internal gates (i.e. according to abovemtioned notation is @f$ W_h @f$)
 116         @param Wx is matrix defining how current input is transformed to internal gates (i.e. according to abovemtioned notation is @f$ W_x @f$)
 117         @param b  is bias vector (i.e. according to abovemtioned notation is @f$ b @f$)
 118         */
 119         CV_DEPRECATED virtual void setWeights(const Mat &Wh, const Mat &Wx, const Mat &b) = 0;
 120
 121         /** @brief Specifies shape of output blob which will be [[`T`], `N`] + @p outTailShape.
 122           * @details If this parameter is empty or unset then @p outTailShape = [`Wh`.size(0)] will be used,
 123           * where `Wh` is parameter from setWeights().
 124           */
 125         virtual void setOutShape(const MatShape &outTailShape = MatShape()) = 0;
 126
 127         /** @deprecated Use flag `produce_cell_output` in LayerParams.
 128           * @brief Specifies either interpret first dimension of input blob as timestamp dimenion either as sample.
 129           *
 130           * If flag is set to true then shape of input blob will be interpreted as [`T`, `N`, `[data dims]`] where `T` specifies number of timestamps, `N` is number of independent streams.
 131           * In this case each forward() call will iterate through `T` timestamps and update layer's state `T` times.
 132           *
 133           * If flag is set to false then shape of input blob will be interpreted as [`N`, `[data dims]`].
 134           * In this case each forward() call will make one iteration and produce one timestamp with shape [`N`, `[out dims]`].
 135           */
 136         CV_DEPRECATED virtual void setUseTimstampsDim(bool use = true) = 0;
 137
 138         /** @deprecated Use flag `use_timestamp_dim` in LayerParams.
 139          * @brief If this flag is set to true then layer will produce @f$ c_t @f$ as second output.
 140          * @details Shape of the second output is the same as first output.
 141          */
 142         CV_DEPRECATED virtual void setProduceCellOutput(bool produce = false) = 0;
 143
 144         /* In common case it use single input with @f$x_t@f$ values to compute output(s) @f$h_t@f$ (and @f$c_t@f$).
 145          * @param input should contain packed values @f$x_t@f$
 146          * @param output contains computed outputs: @f$h_t@f$ (and @f$c_t@f$ if setProduceCellOutput() flag was set to true).
 147          *
 148          * If setUseTimstampsDim() is set to true then @p input[0] should has at least two dimensions with the following shape: [`T`, `N`, `[data dims]`],
 149          * where `T` specifies number of timestamps, `N` is number of independent streams (i.e. @f$ x_{t_0 + t}^{stream} @f$ is stored inside @p input[0][t, stream, ...]).
 150          *
 151          * If setUseTimstampsDim() is set to fase then @p input[0] should contain single timestamp, its shape should has form [`N`, `[data dims]`] with at least one dimension.
 152          * (i.e. @f$ x_{t}^{stream} @f$ is stored inside @p input[0][stream, ...]).
 153         */
 154
 155         int inputNameToIndex(String inputName) CV_OVERRIDE;
 156         int outputNameToIndex(const String& outputName) CV_OVERRIDE;
 157     };
 158
 159     /** @brief Classical recurrent layer
 160
 161     Accepts two inputs @f$x_t@f$ and @f$h_{t-1}@f$ and compute two outputs @f$o_t@f$ and @f$h_t@f$.
 162
 163     - input: should contain packed input @f$x_t@f$.
 164     - output: should contain output @f$o_t@f$ (and @f$h_t@f$ if setProduceHiddenOutput() is set to true).
 165
 166     input[0] should have shape [`T`, `N`, `data_dims`] where `T` and `N` is number of timestamps and number of independent samples of @f$x_t@f$ respectively.
 167
 168     output[0] will have shape [`T`, `N`, @f$N_o@f$], where @f$N_o@f$ is number of rows in @f$ W_{xo} @f$ matrix.
 169
 170     If setProduceHiddenOutput() is set to true then @p output[1] will contain a Mat with shape [`T`, `N`, @f$N_h@f$], where @f$N_h@f$ is number of rows in @f$ W_{hh} @f$ matrix.
 171     */
 172     class CV_EXPORTS RNNLayer : public Layer
 173     {
 174     public:
 175         /** Creates instance of RNNLayer */
 176         static Ptr<RNNLayer> create(const LayerParams& params);
 177
 178         /** Setups learned weights.
 179
 180         Recurrent-layer behavior on each step is defined by current input @f$ x_t @f$, previous state @f$ h_t @f$ and learned weights as follows:
 181         @f{eqnarray*}{
 182         h_t &= tanh&(W_{hh} h_{t-1} + W_{xh} x_t + b_h),  \\
 183         o_t &= tanh&(W_{ho} h_t + b_o),
 184         @f}
 185
 186         @param Wxh is @f$ W_{xh} @f$ matrix
 187         @param bh  is @f$ b_{h}  @f$ vector
 188         @param Whh is @f$ W_{hh} @f$ matrix
 189         @param Who is @f$ W_{xo} @f$ matrix
 190         @param bo  is @f$ b_{o}  @f$ vector
 191         */
 192         virtual void setWeights(const Mat &Wxh, const Mat &bh, const Mat &Whh, const Mat &Who, const Mat &bo) = 0;
 193
 194         /** @brief If this flag is set to true then layer will produce @f$ h_t @f$ as second output.
 195          * @details Shape of the second output is the same as first output.
 196          */
 197         virtual void setProduceHiddenOutput(bool produce = false) = 0;
 198
 199     };
 200
 201     class CV_EXPORTS BaseConvolutionLayer : public Layer
 202     {
 203     public:
 204         Size kernel, stride, pad, dilation, adjustPad;
 205         String padMode;
 206         int numOutput;
 207     };
 208
 209     class CV_EXPORTS ConvolutionLayer : public BaseConvolutionLayer
 210     {
 211     public:
 212         static Ptr<BaseConvolutionLayer> create(const LayerParams& params);
 213     };
 214
 215     class CV_EXPORTS DeconvolutionLayer : public BaseConvolutionLayer
 216     {
 217     public:
 218         static Ptr<BaseConvolutionLayer> create(const LayerParams& params);
 219     };
 220
 221     class CV_EXPORTS LRNLayer : public Layer
 222     {
 223     public:
 224         int type;
 225
 226         int size;
 227         float alpha, beta, bias;
 228         bool normBySize;
 229
 230         static Ptr<LRNLayer> create(const LayerParams& params);
 231     };
 232
 233     class CV_EXPORTS PoolingLayer : public Layer
 234     {
 235     public:
 236         int type;
 237         Size kernel, stride, pad;
 238         bool globalPooling;
 239         bool computeMaxIdx;
 240         String padMode;
 241         bool ceilMode;
 242         // If true for average pooling with padding, divide an every output region
 243         // by a whole kernel area. Otherwise exclude zero padded values and divide
 244         // by number of real values.
 245         bool avePoolPaddedArea;
 246         // ROIPooling parameters.
 247         Size pooledSize;
 248         float spatialScale;
 249         // PSROIPooling parameters.
 250         int psRoiOutChannels;
 251
 252         static Ptr<PoolingLayer> create(const LayerParams& params);
 253     };
 254
 255     class CV_EXPORTS SoftmaxLayer : public Layer
 256     {
 257     public:
 258         bool logSoftMax;
 259
 260         static Ptr<SoftmaxLayer> create(const LayerParams& params);
 261     };
 262
 263     class CV_EXPORTS InnerProductLayer : public Layer
 264     {
 265     public:
 266         int axis;
 267         static Ptr<InnerProductLayer> create(const LayerParams& params);
 268     };
 269
 270     class CV_EXPORTS MVNLayer : public Layer
 271     {
 272     public:
 273         float eps;
 274         bool normVariance, acrossChannels;
 275
 276         static Ptr<MVNLayer> create(const LayerParams& params);
 277     };
 278
 279     /* Reshaping */
 280
 281     class CV_EXPORTS ReshapeLayer : public Layer
 282     {
 283     public:
 284         MatShape newShapeDesc;
 285         Range newShapeRange;
 286
 287         static Ptr<ReshapeLayer> create(const LayerParams& params);
 288     };
 289
 290     class CV_EXPORTS FlattenLayer : public Layer
 291     {
 292     public:
 293         static Ptr<FlattenLayer> create(const LayerParams &params);
 294     };
 295
 296     class CV_EXPORTS ConcatLayer : public Layer
 297     {
 298     public:
 299         int axis;
 300         /**
 301          * @brief Add zero padding in case of concatenation of blobs with different
 302          * spatial sizes.
 303          *
 304          * Details: https://github.com/torch/nn/blob/master/doc/containers.md#depthconcat
 305          */
 306         bool padding;
 307
 308         static Ptr<ConcatLayer> create(const LayerParams &params);
 309     };
 310
 311     class CV_EXPORTS SplitLayer : public Layer
 312     {
 313     public:
 314         int outputsCount; //!< Number of copies that will be produced (is ignored when negative).
 315
 316         static Ptr<SplitLayer> create(const LayerParams &params);
 317     };
 318
 319     /**
 320      * Slice layer has several modes:
 321      * 1. Caffe mode
 322      * @param[in] axis Axis of split operation
 323      * @param[in] slice_point Array of split points
 324      *
 325      * Number of output blobs equals to number of split points plus one. The
 326      * first blob is a slice on input from 0 to @p slice_point[0] - 1 by @p axis,
 327      * the second output blob is a slice of input from @p slice_point[0] to
 328      * @p slice_point[1] - 1 by @p axis and the last output blob is a slice of
 329      * input from @p slice_point[-1] up to the end of @p axis size.
 330      *
 331      * 2. TensorFlow mode
 332      * @param begin Vector of start indices
 333      * @param size Vector of sizes
 334      *
 335      * More convenient numpy-like slice. One and only output blob
 336      * is a slice `input[begin[0]:begin[0]+size[0], begin[1]:begin[1]+size[1], ...]`
 337      *
 338      * 3. Torch mode
 339      * @param axis Axis of split operation
 340      *
 341      * Split input blob on the equal parts by @p axis.
 342      */
 343     class CV_EXPORTS SliceLayer : public Layer
 344     {
 345     public:
 346         /**
 347          * @brief Vector of slice ranges.
 348          *
 349          * The first dimension equals number of output blobs.
 350          * Inner vector has slice ranges for the first number of input dimensions.
 351          */
 352         std::vector<std::vector<Range> > sliceRanges;
 353         int axis;
 354
 355         static Ptr<SliceLayer> create(const LayerParams &params);
 356     };
 357
 358     class CV_EXPORTS PermuteLayer : public Layer
 359     {
 360     public:
 361         static Ptr<PermuteLayer> create(const LayerParams& params);
 362     };
 363
 364     /**
 365      * @brief Adds extra values for specific axes.
 366      * @param paddings Vector of paddings in format
 367      *                 @code
 368      *                 [ pad_before, pad_after,  // [0]th dimension
 369      *                   pad_before, pad_after,  // [1]st dimension
 370      *                   ...
 371      *                   pad_before, pad_after ] // [n]th dimension
 372      *                 @endcode
 373      *                 that represents number of padded values at every dimension
 374      *                 starting from the first one. The rest of dimensions won't
 375      *                 be padded.
 376      * @param value Value to be padded. Defaults to zero.
 377      * @param type Padding type: 'constant', 'reflect'
 378      * @param input_dims Torch's parameter. If @p input_dims is not equal to the
 379      *                   actual input dimensionality then the `[0]th` dimension
 380      *                   is considered as a batch dimension and @p paddings are shifted
 381      *                   to a one dimension. Defaults to `-1` that means padding
 382      *                   corresponding to @p paddings.
 383      */
 384     class CV_EXPORTS PaddingLayer : public Layer
 385     {
 386     public:
 387         static Ptr<PaddingLayer> create(const LayerParams& params);
 388     };
 389
 390     /* Activations */
 391     class CV_EXPORTS ActivationLayer : public Layer
 392     {
 393     public:
 394         virtual void forwardSlice(const float* src, float* dst, int len,
 395                                   size_t outPlaneSize, int cn0, int cn1) const = 0;
 396     };
 397
 398     class CV_EXPORTS ReLULayer : public ActivationLayer
 399     {
 400     public:
 401         float negativeSlope;
 402
 403         static Ptr<ReLULayer> create(const LayerParams &params);
 404     };
 405
 406     class CV_EXPORTS ReLU6Layer : public ActivationLayer
 407     {
 408     public:
 409         float minValue, maxValue;
 410
 411         static Ptr<ReLU6Layer> create(const LayerParams &params);
 412     };
 413
 414     class CV_EXPORTS ChannelsPReLULayer : public ActivationLayer
 415     {
 416     public:
 417         static Ptr<Layer> create(const LayerParams& params);
 418     };
 419
 420     class CV_EXPORTS ELULayer : public ActivationLayer
 421     {
 422     public:
 423         static Ptr<ELULayer> create(const LayerParams &params);
 424     };
 425
 426     class CV_EXPORTS TanHLayer : public ActivationLayer
 427     {
 428     public:
 429         static Ptr<TanHLayer> create(const LayerParams &params);
 430     };
 431
 432     class CV_EXPORTS SigmoidLayer : public ActivationLayer
 433     {
 434     public:
 435         static Ptr<SigmoidLayer> create(const LayerParams &params);
 436     };
 437
 438     class CV_EXPORTS BNLLLayer : public ActivationLayer
 439     {
 440     public:
 441         static Ptr<BNLLLayer> create(const LayerParams &params);
 442     };
 443
 444     class CV_EXPORTS AbsLayer : public ActivationLayer
 445     {
 446     public:
 447         static Ptr<AbsLayer> create(const LayerParams &params);
 448     };
 449
 450     class CV_EXPORTS PowerLayer : public ActivationLayer
 451     {
 452     public:
 453         float power, scale, shift;
 454
 455         static Ptr<PowerLayer> create(const LayerParams &params);
 456     };
 457
 458     /* Layers used in semantic segmentation */
 459
 460     class CV_EXPORTS CropLayer : public Layer
 461     {
 462     public:
 463         int startAxis;
 464         std::vector<int> offset;
 465
 466         static Ptr<CropLayer> create(const LayerParams &params);
 467     };
 468
 469     class CV_EXPORTS EltwiseLayer : public Layer
 470     {
 471     public:
 472         static Ptr<EltwiseLayer> create(const LayerParams &params);
 473     };
 474
 475     class CV_EXPORTS BatchNormLayer : public Layer
 476     {
 477     public:
 478         bool hasWeights, hasBias;
 479         float epsilon;
 480
 481         static Ptr<BatchNormLayer> create(const LayerParams &params);
 482     };
 483
 484     class CV_EXPORTS MaxUnpoolLayer : public Layer
 485     {
 486     public:
 487         Size poolKernel;
 488         Size poolPad;
 489         Size poolStride;
 490
 491         static Ptr<MaxUnpoolLayer> create(const LayerParams &params);
 492     };
 493
 494     class CV_EXPORTS ScaleLayer : public Layer
 495     {
 496     public:
 497         bool hasBias;
 498         int axis;
 499
 500         static Ptr<ScaleLayer> create(const LayerParams& params);
 501     };
 502
 503     class CV_EXPORTS ShiftLayer : public Layer
 504     {
 505     public:
 506         static Ptr<ShiftLayer> create(const LayerParams& params);
 507     };
 508
 509     class CV_EXPORTS PriorBoxLayer : public Layer
 510     {
 511     public:
 512         static Ptr<PriorBoxLayer> create(const LayerParams& params);
 513     };
 514
 515     class CV_EXPORTS ReorgLayer : public Layer
 516     {
 517     public:
 518         static Ptr<ReorgLayer> create(const LayerParams& params);
 519     };
 520
 521     class CV_EXPORTS RegionLayer : public Layer
 522     {
 523     public:
 524         static Ptr<RegionLayer> create(const LayerParams& params);
 525     };
 526
 527     class CV_EXPORTS DetectionOutputLayer : public Layer
 528     {
 529     public:
 530         static Ptr<DetectionOutputLayer> create(const LayerParams& params);
 531     };
 532
 533     /**
 534      * @brief \f$ L_p \f$ - normalization layer.
 535      * @param p Normalization factor. The most common `p = 1` for \f$ L_1 \f$ -
 536      *          normalization or `p = 2` for \f$ L_2 \f$ - normalization or a custom one.
 537      * @param eps Parameter \f$ \epsilon \f$ to prevent a division by zero.
 538      * @param across_spatial If true, normalize an input across all non-batch dimensions.
 539      *                       Otherwise normalize an every channel separately.
 540      *
 541      * Across spatial:
 542      * @f[
 543      * norm = \sqrt[p]{\epsilon + \sum_{x, y, c} |src(x, y, c)|^p } \\
 544      * dst(x, y, c) = \frac{ src(x, y, c) }{norm}
 545      * @f]
 546      *
 547      * Channel wise normalization:
 548      * @f[
 549      * norm(c) = \sqrt[p]{\epsilon + \sum_{x, y} |src(x, y, c)|^p } \\
 550      * dst(x, y, c) = \frac{ src(x, y, c) }{norm(c)}
 551      * @f]
 552      *
 553      * Where `x, y` - spatial cooridnates, `c` - channel.
 554      *
 555      * An every sample in the batch is normalized separately. Optionally,
 556      * output is scaled by the trained parameters.
 557      */
 558     class NormalizeBBoxLayer : public Layer
 559     {
 560     public:
 561         float pnorm, epsilon;
 562         CV_DEPRECATED bool acrossSpatial;
 563
 564         static Ptr<NormalizeBBoxLayer> create(const LayerParams& params);
 565     };
 566
 567     /**
 568      * @brief Resize input 4-dimensional blob by nearest neghbor strategy.
 569      *
 570      * Layer is used to support TensorFlow's resize_nearest_neighbor op.
 571      */
 572     class CV_EXPORTS ResizeNearestNeighborLayer : public Layer
 573     {
 574     public:
 575         static Ptr<ResizeNearestNeighborLayer> create(const LayerParams& params);
 576     };
 577
 578     class CV_EXPORTS ProposalLayer : public Layer
 579     {
 580     public:
 581         static Ptr<ProposalLayer> create(const LayerParams& params);
 582     };
 583
 584 //! @}
 585 //! @}
 586 CV__DNN_EXPERIMENTAL_NS_END
 587 }
 588 }
 589 #endif