modules/dnn/include/opencv2/dnn/dnn.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_HPP
  43 #define OPENCV_DNN_DNN_HPP
  44
  45 #include <vector>
  46 #include <opencv2/core.hpp>
  47
  48 #if !defined CV_DOXYGEN && !defined CV_DNN_DONT_ADD_EXPERIMENTAL_NS
  49 #define CV__DNN_EXPERIMENTAL_NS_BEGIN namespace experimental_dnn_v1 {
  50 #define CV__DNN_EXPERIMENTAL_NS_END }
  51 namespace cv { namespace dnn { namespace experimental_dnn_v1 { } using namespace experimental_dnn_v1; }}
  52 #else
  53 #define CV__DNN_EXPERIMENTAL_NS_BEGIN
  54 #define CV__DNN_EXPERIMENTAL_NS_END
  55 #endif
  56
  57 #include <opencv2/dnn/dict.hpp>
  58
  59 namespace cv {
  60 namespace dnn {
  61 CV__DNN_EXPERIMENTAL_NS_BEGIN
  62 //! @addtogroup dnn
  63 //! @{
  64
  65     typedef std::vector<int> MatShape;
  66
  67     /**
  68      * @brief Enum of computation backends supported by layers.
  69      */
  70     enum Backend
  71     {
  72         DNN_BACKEND_DEFAULT,
  73         DNN_BACKEND_HALIDE
  74     };
  75
  76     /**
  77      * @brief Enum of target devices for computations.
  78      */
  79     enum Target
  80     {
  81         DNN_TARGET_CPU,
  82         DNN_TARGET_OPENCL
  83     };
  84
  85     /** @brief This class provides all data needed to initialize layer.
  86      *
  87      * It includes dictionary with scalar params (which can be readed by using Dict interface),
  88      * blob params #blobs and optional meta information: #name and #type of layer instance.
  89     */
  90     class CV_EXPORTS LayerParams : public Dict
  91     {
  92     public:
  93         //TODO: Add ability to name blob params
  94         std::vector<Mat> blobs; //!< List of learned parameters stored as blobs.
  95
  96         String name; //!< Name of the layer instance (optional, can be used internal purposes).
  97         String type; //!< Type name which was used for creating layer by layer factory (optional).
  98     };
  99
 100    /**
 101     * @brief Derivatives of this class encapsulates functions of certain backends.
 102     */
 103     class BackendNode
 104     {
 105     public:
 106         BackendNode(int backendId);
 107
 108         virtual ~BackendNode(); //!< Virtual destructor to make polymorphism.
 109
 110         int backendId; //!< Backend identifier.
 111     };
 112
 113     /**
 114      * @brief Derivatives of this class wraps cv::Mat for different backends and targets.
 115      */
 116     class BackendWrapper
 117     {
 118     public:
 119         BackendWrapper(int backendId, int targetId);
 120
 121         /**
 122          * @brief Wrap cv::Mat for specific backend and target.
 123          * @param[in] targetId Target identifier.
 124          * @param[in] m cv::Mat for wrapping.
 125          *
 126          * Make CPU->GPU data transfer if it's require for the target.
 127          */
 128         BackendWrapper(int targetId, const cv::Mat& m);
 129
 130         /**
 131          * @brief Make wrapper for reused cv::Mat.
 132          * @param[in] base Wrapper of cv::Mat that will be reused.
 133          * @param[in] shape Specific shape.
 134          *
 135          * Initialize wrapper from another one. It'll wrap the same host CPU
 136          * memory and mustn't allocate memory on device(i.e. GPU). It might
 137          * has different shape. Use in case of CPU memory reusing for reuse
 138          * associented memory on device too.
 139          */
 140         BackendWrapper(const Ptr<BackendWrapper>& base, const MatShape& shape);
 141
 142         virtual ~BackendWrapper(); //!< Virtual destructor to make polymorphism.
 143
 144         /**
 145          * @brief Transfer data to CPU host memory.
 146          */
 147         virtual void copyToHost() = 0;
 148
 149         /**
 150          * @brief Indicate that an actual data is on CPU.
 151          */
 152         virtual void setHostDirty() = 0;
 153
 154         int backendId;  //!< Backend identifier.
 155         int targetId;   //!< Target identifier.
 156     };
 157
 158     class CV_EXPORTS ActivationLayer;
 159     class CV_EXPORTS BatchNormLayer;
 160     class CV_EXPORTS ScaleLayer;
 161
 162     /** @brief This interface class allows to build new Layers - are building blocks of networks.
 163      *
 164      * Each class, derived from Layer, must implement allocate() methods to declare own outputs and forward() to compute outputs.
 165      * Also before using the new layer into networks you must register your layer by using one of @ref dnnLayerFactory "LayerFactory" macros.
 166      */
 167     class CV_EXPORTS_W Layer : public Algorithm
 168     {
 169     public:
 170
 171         //! List of learned parameters must be stored here to allow read them by using Net::getParam().
 172         CV_PROP_RW std::vector<Mat> blobs;
 173
 174         /** @brief Computes and sets internal parameters according to inputs, outputs and blobs.
 175          *  @param[in]  input  vector of already allocated input blobs
 176          *  @param[out] output vector of already allocated output blobs
 177          *
 178          * If this method is called after network has allocated all memory for input and output blobs
 179          * and before inferencing.
 180          */
 181         virtual void finalize(const std::vector<Mat*> &input, std::vector<Mat> &output);
 182
 183         /** @brief Given the @p input blobs, computes the output @p blobs.
 184          *  @param[in]  input  the input blobs.
 185          *  @param[out] output allocated output blobs, which will store results of the computation.
 186          *  @param[out] internals allocated internal blobs
 187          */
 188         virtual void forward(std::vector<Mat*> &input, std::vector<Mat> &output, std::vector<Mat> &internals) = 0;
 189
 190         /** @brief @overload */
 191         CV_WRAP void finalize(const std::vector<Mat> &inputs, CV_OUT std::vector<Mat> &outputs);
 192
 193         /** @brief @overload */
 194         CV_WRAP std::vector<Mat> finalize(const std::vector<Mat> &inputs);
 195
 196         /** @brief @overload */
 197         CV_WRAP void forward(const std::vector<Mat> &inputs, CV_IN_OUT std::vector<Mat> &outputs,
 198                              CV_IN_OUT std::vector<Mat> &internals);
 199
 200         /** @brief Allocates layer and computes output. */
 201         CV_WRAP void run(const std::vector<Mat> &inputs, CV_OUT std::vector<Mat> &outputs,
 202                          CV_IN_OUT std::vector<Mat> &internals);
 203
 204         /** @brief Returns index of input blob into the input array.
 205          *  @param inputName label of input blob
 206          *
 207          * Each layer input and output can be labeled to easily identify them using "%<layer_name%>[.output_name]" notation.
 208          * This method maps label of input blob to its index into input vector.
 209          */
 210         virtual int inputNameToIndex(String inputName);
 211         /** @brief Returns index of output blob in output array.
 212          *  @see inputNameToIndex()
 213          */
 214         virtual int outputNameToIndex(String outputName);
 215
 216         /**
 217          * @brief Ask layer if it support specific backend for doing computations.
 218          * @param[in] backendId computation backend identifier.
 219          * @see Backend
 220          */
 221         virtual bool supportBackend(int backendId);
 222
 223         /**
 224          * @brief Returns Halide backend node.
 225          * @param[in] inputs Input Halide buffers.
 226          * @see BackendNode, BackendWrapper
 227          *
 228          * Input buffers should be exactly the same that will be used in forward invocations.
 229          * Despite we can use Halide::ImageParam based on input shape only,
 230          * it helps prevent some memory management issues (if something wrong,
 231          * Halide tests will be failed).
 232          */
 233         virtual Ptr<BackendNode> initHalide(const std::vector<Ptr<BackendWrapper> > &inputs);
 234
 235        /**
 236         * @brief Automatic Halide scheduling based on layer hyper-parameters.
 237         * @param[in] node Backend node with Halide functions.
 238         * @param[in] inputs Blobs that will be used in forward invocations.
 239         * @param[in] outputs Blobs that will be used in forward invocations.
 240         * @param[in] targetId Target identifier
 241         * @see BackendNode, Target
 242         *
 243         * Layer don't use own Halide::Func members because we can have applied
 244         * layers fusing. In this way the fused function should be scheduled.
 245         */
 246         virtual void applyHalideScheduler(Ptr<BackendNode>& node,
 247                                           const std::vector<Mat*> &inputs,
 248                                           const std::vector<Mat> &outputs,
 249                                           int targetId) const;
 250
 251         /**
 252          * @brief Implement layers fusing.
 253          * @param[in] node Backend node of bottom layer.
 254          * @see BackendNode
 255          *
 256          * Actual for graph-based backends. If layer attached successfully,
 257          * returns non-empty cv::Ptr to node of the same backend.
 258          * Fuse only over the last function.
 259          */
 260         virtual Ptr<BackendNode> tryAttach(const Ptr<BackendNode>& node);
 261
 262         /**
 263          * @brief Tries to attach to the layer the subsequent activation layer, i.e. do the layer fusion in a partial case.
 264          * @param[in] layer The subsequent activation layer.
 265          *
 266          * Returns true if the activation layer has been attached successfully.
 267          */
 268         virtual bool setActivation(const Ptr<ActivationLayer>& layer);
 269
 270         /**
 271          * @brief Tries to attach to the layer the subsequent batch normalization layer, i.e. do the layer fusion in a partial case.
 272          * @param[in] layer The subsequent batch normalization layer.
 273          *
 274          * Returns true if the batch normalization layer has been attached successfully.
 275          */
 276         virtual bool setBatchNorm(const Ptr<BatchNormLayer>& layer);
 277
 278         /**
 279          * @brief Tries to attach to the layer the subsequent scaling layer, i.e. do the layer fusion in a partial case.
 280          * @param[in] layer The subsequent scaling layer.
 281          *
 282          * Returns true if the scaling layer has been attached successfully.
 283          */
 284         virtual bool setScale(const Ptr<ScaleLayer>& layer);
 285
 286         /**
 287          * @brief "Deattaches" all the layers, attached to particular layer.
 288          */
 289         virtual void unsetAttached();
 290
 291         virtual bool getMemoryShapes(const std::vector<MatShape> &inputs,
 292                                      const int requiredOutputs,
 293                                      std::vector<MatShape> &outputs,
 294                                      std::vector<MatShape> &internals) const;
 295         virtual int64 getFLOPS(const std::vector<MatShape> &inputs,
 296                                const std::vector<MatShape> &outputs) const {(void)inputs; (void)outputs; return 0;}
 297
 298         CV_PROP String name; //!< Name of the layer instance, can be used for logging or other internal purposes.
 299         CV_PROP String type; //!< Type name which was used for creating layer by layer factory.
 300         CV_PROP int preferableTarget; //!< prefer target for layer forwarding
 301
 302         Layer();
 303         explicit Layer(const LayerParams &params);      //!< Initializes only #name, #type and #blobs fields.
 304         void setParamsFrom(const LayerParams &params);  //!< Initializes only #name, #type and #blobs fields.
 305         virtual ~Layer();
 306     };
 307
 308     /** @brief This class allows to create and manipulate comprehensive artificial neural networks.
 309      *
 310      * Neural network is presented as directed acyclic graph (DAG), where vertices are Layer instances,
 311      * and edges specify relationships between layers inputs and outputs.
 312      *
 313      * Each network layer has unique integer id and unique string name inside its network.
 314      * LayerId can store either layer name or layer id.
 315      *
 316      * This class supports reference counting of its instances, i. e. copies point to the same instance.
 317      */
 318     class CV_EXPORTS_W_SIMPLE Net
 319     {
 320     public:
 321
 322         CV_WRAP Net();  //!< Default constructor.
 323         CV_WRAP ~Net(); //!< Destructor frees the net only if there aren't references to the net anymore.
 324
 325         /** Returns true if there are no layers in the network. */
 326         CV_WRAP bool empty() const;
 327
 328         /** @brief Adds new layer to the net.
 329          *  @param name   unique name of the adding layer.
 330          *  @param type   typename of the adding layer (type must be registered in LayerRegister).
 331          *  @param params parameters which will be used to initialize the creating layer.
 332          *  @returns unique identifier of created layer, or -1 if a failure will happen.
 333          */
 334         int addLayer(const String &name, const String &type, LayerParams &params);
 335         /** @brief Adds new layer and connects its first input to the first output of previously added layer.
 336          *  @see addLayer()
 337          */
 338         int addLayerToPrev(const String &name, const String &type, LayerParams &params);
 339
 340         /** @brief Converts string name of the layer to the integer identifier.
 341          *  @returns id of the layer, or -1 if the layer wasn't found.
 342          */
 343         CV_WRAP int getLayerId(const String &layer);
 344
 345         CV_WRAP std::vector<String> getLayerNames() const;
 346
 347         /** @brief Container for strings and integers. */
 348         typedef DictValue LayerId;
 349
 350         /** @brief Returns pointer to layer with specified id or name which the network use. */
 351         CV_WRAP Ptr<Layer> getLayer(LayerId layerId);
 352
 353         /** @brief Returns pointers to input layers of specific layer. */
 354         std::vector<Ptr<Layer> > getLayerInputs(LayerId layerId); // FIXIT: CV_WRAP
 355
 356         /** @brief Delete layer for the network (not implemented yet) */
 357         CV_WRAP void deleteLayer(LayerId layer);
 358
 359         /** @brief Connects output of the first layer to input of the second layer.
 360          *  @param outPin descriptor of the first layer output.
 361          *  @param inpPin descriptor of the second layer input.
 362          *
 363          * Descriptors have the following template <DFN>&lt;layer_name&gt;[.input_number]</DFN>:
 364          * - the first part of the template <DFN>layer_name</DFN> is sting name of the added layer.
 365          *   If this part is empty then the network input pseudo layer will be used;
 366          * - the second optional part of the template <DFN>input_number</DFN>
 367          *   is either number of the layer input, either label one.
 368          *   If this part is omitted then the first layer input will be used.
 369          *
 370          *  @see setNetInputs(), Layer::inputNameToIndex(), Layer::outputNameToIndex()
 371          */
 372         CV_WRAP void connect(String outPin, String inpPin);
 373
 374         /** @brief Connects #@p outNum output of the first layer to #@p inNum input of the second layer.
 375          *  @param outLayerId identifier of the first layer
 376          *  @param inpLayerId identifier of the second layer
 377          *  @param outNum number of the first layer output
 378          *  @param inpNum number of the second layer input
 379          */
 380         void connect(int outLayerId, int outNum, int inpLayerId, int inpNum);
 381
 382         /** @brief Sets outputs names of the network input pseudo layer.
 383          *
 384          * Each net always has special own the network input pseudo layer with id=0.
 385          * This layer stores the user blobs only and don't make any computations.
 386          * In fact, this layer provides the only way to pass user data into the network.
 387          * As any other layer, this layer can label its outputs and this function provides an easy way to do this.
 388          */
 389         CV_WRAP void setInputsNames(const std::vector<String> &inputBlobNames);
 390
 391         /** @brief Runs forward pass to compute output of layer with name @p outputName.
 392          *  @param outputName name for layer which output is needed to get
 393          *  @return blob for first output of specified layer.
 394          *  @details By default runs forward pass for the whole network.
 395          */
 396         CV_WRAP Mat forward(const String& outputName = String());
 397
 398         /** @brief Runs forward pass to compute output of layer with name @p outputName.
 399          *  @param outputBlobs contains all output blobs for specified layer.
 400          *  @param outputName name for layer which output is needed to get
 401          *  @details If @p outputName is empty, runs forward pass for the whole network.
 402          */
 403         CV_WRAP void forward(std::vector<Mat>& outputBlobs, const String& outputName = String());
 404
 405         /** @brief Runs forward pass to compute outputs of layers listed in @p outBlobNames.
 406          *  @param outputBlobs contains blobs for first outputs of specified layers.
 407          *  @param outBlobNames names for layers which outputs are needed to get
 408          */
 409         CV_WRAP void forward(std::vector<Mat>& outputBlobs,
 410                              const std::vector<String>& outBlobNames);
 411
 412         /** @brief Runs forward pass to compute outputs of layers listed in @p outBlobNames.
 413          *  @param outputBlobs contains all output blobs for each layer specified in @p outBlobNames.
 414          *  @param outBlobNames names for layers which outputs are needed to get
 415          */
 416         CV_WRAP void forward(std::vector<std::vector<Mat> >& outputBlobs,
 417                              const std::vector<String>& outBlobNames);
 418
 419         //TODO:
 420         /** @brief Optimized forward.
 421          *  @warning Not implemented yet.
 422          *  @details Makes forward only those layers which weren't changed after previous forward().
 423          */
 424         void forwardOpt(LayerId toLayer);
 425         /** @overload */
 426         void forwardOpt(const std::vector<LayerId> &toLayers);
 427
 428         /**
 429          * @brief Compile Halide layers.
 430          * @param[in] scheduler Path to YAML file with scheduling directives.
 431          * @see setPreferableBackend
 432          *
 433          * Schedule layers that support Halide backend. Then compile them for
 434          * specific target. For layers that not represented in scheduling file
 435          * or if no manual scheduling used at all, automatic scheduling will be applied.
 436          */
 437         CV_WRAP void setHalideScheduler(const String& scheduler);
 438
 439         /**
 440          * @brief Ask network to use specific computation backend where it supported.
 441          * @param[in] backendId backend identifier.
 442          * @see Backend
 443          */
 444         CV_WRAP void setPreferableBackend(int backendId);
 445
 446         /**
 447          * @brief Ask network to make computations on specific target device.
 448          * @param[in] targetId target identifier.
 449          * @see Target
 450          */
 451         CV_WRAP void setPreferableTarget(int targetId);
 452
 453         /** @brief Sets the new value for the layer output blob
 454          *  @param name descriptor of the updating layer output blob.
 455          *  @param blob new blob.
 456          *  @see connect(String, String) to know format of the descriptor.
 457          *  @note If updating blob is not empty then @p blob must have the same shape,
 458          *  because network reshaping is not implemented yet.
 459          */
 460         CV_WRAP void setInput(const Mat &blob, const String& name = "");
 461
 462         /** @brief Sets the new value for the learned param of the layer.
 463          *  @param layer name or id of the layer.
 464          *  @param numParam index of the layer parameter in the Layer::blobs array.
 465          *  @param blob the new value.
 466          *  @see Layer::blobs
 467          *  @note If shape of the new blob differs from the previous shape,
 468          *  then the following forward pass may fail.
 469         */
 470         CV_WRAP void setParam(LayerId layer, int numParam, const Mat &blob);
 471
 472         /** @brief Returns parameter blob of the layer.
 473          *  @param layer name or id of the layer.
 474          *  @param numParam index of the layer parameter in the Layer::blobs array.
 475          *  @see Layer::blobs
 476          */
 477         CV_WRAP Mat getParam(LayerId layer, int numParam = 0);
 478
 479         /** @brief Returns indexes of layers with unconnected outputs.
 480          */
 481         CV_WRAP std::vector<int> getUnconnectedOutLayers() const;
 482         /** @brief Returns input and output shapes for all layers in loaded model;
 483          *  preliminary inferencing isn't necessary.
 484          *  @param netInputShapes shapes for all input blobs in net input layer.
 485          *  @param layersIds output parameter for layer IDs.
 486          *  @param inLayersShapes output parameter for input layers shapes;
 487          * order is the same as in layersIds
 488          *  @param outLayersShapes output parameter for output layers shapes;
 489          * order is the same as in layersIds
 490          */
 491         CV_WRAP void getLayersShapes(const std::vector<MatShape>& netInputShapes,
 492                                      CV_OUT std::vector<int>& layersIds,
 493                                      CV_OUT std::vector<std::vector<MatShape> >& inLayersShapes,
 494                                      CV_OUT std::vector<std::vector<MatShape> >& outLayersShapes) const;
 495
 496         /** @overload */
 497         CV_WRAP void getLayersShapes(const MatShape& netInputShape,
 498                                      CV_OUT std::vector<int>& layersIds,
 499                                      CV_OUT std::vector<std::vector<MatShape> >& inLayersShapes,
 500                                      CV_OUT std::vector<std::vector<MatShape> >& outLayersShapes) const;
 501
 502         /** @brief Returns input and output shapes for layer with specified
 503          * id in loaded model; preliminary inferencing isn't necessary.
 504          *  @param netInputShape shape input blob in net input layer.
 505          *  @param layerId id for layer.
 506          *  @param inLayerShapes output parameter for input layers shapes;
 507          * order is the same as in layersIds
 508          *  @param outLayerShapes output parameter for output layers shapes;
 509          * order is the same as in layersIds
 510          */
 511         void getLayerShapes(const MatShape& netInputShape,
 512                                     const int layerId,
 513                                     CV_OUT std::vector<MatShape>& inLayerShapes,
 514                                     CV_OUT std::vector<MatShape>& outLayerShapes) const; // FIXIT: CV_WRAP
 515
 516         /** @overload */
 517         void getLayerShapes(const std::vector<MatShape>& netInputShapes,
 518                                     const int layerId,
 519                                     CV_OUT std::vector<MatShape>& inLayerShapes,
 520                                     CV_OUT std::vector<MatShape>& outLayerShapes) const; // FIXIT: CV_WRAP
 521
 522         /** @brief Computes FLOP for whole loaded model with specified input shapes.
 523          * @param netInputShapes vector of shapes for all net inputs.
 524          * @returns computed FLOP.
 525          */
 526         CV_WRAP int64 getFLOPS(const std::vector<MatShape>& netInputShapes) const;
 527         /** @overload */
 528         CV_WRAP int64 getFLOPS(const MatShape& netInputShape) const;
 529         /** @overload */
 530         CV_WRAP int64 getFLOPS(const int layerId,
 531                                const std::vector<MatShape>& netInputShapes) const;
 532         /** @overload */
 533         CV_WRAP int64 getFLOPS(const int layerId,
 534                                const MatShape& netInputShape) const;
 535
 536         /** @brief Returns list of types for layer used in model.
 537          * @param layersTypes output parameter for returning types.
 538          */
 539         CV_WRAP void getLayerTypes(CV_OUT std::vector<String>& layersTypes) const;
 540
 541         /** @brief Returns count of layers of specified type.
 542          * @param layerType type.
 543          * @returns count of layers
 544          */
 545         CV_WRAP int getLayersCount(const String& layerType) const;
 546
 547         /** @brief Computes bytes number which are requered to store
 548          * all weights and intermediate blobs for model.
 549          * @param netInputShapes vector of shapes for all net inputs.
 550          * @param weights output parameter to store resulting bytes for weights.
 551          * @param blobs output parameter to store resulting bytes for intermediate blobs.
 552          */
 553         void getMemoryConsumption(const std::vector<MatShape>& netInputShapes,
 554                                           CV_OUT size_t& weights, CV_OUT size_t& blobs) const; // FIXIT: CV_WRAP
 555         /** @overload */
 556         CV_WRAP void getMemoryConsumption(const MatShape& netInputShape,
 557                                           CV_OUT size_t& weights, CV_OUT size_t& blobs) const;
 558         /** @overload */
 559         CV_WRAP void getMemoryConsumption(const int layerId,
 560                                           const std::vector<MatShape>& netInputShapes,
 561                                           CV_OUT size_t& weights, CV_OUT size_t& blobs) const;
 562         /** @overload */
 563         CV_WRAP void getMemoryConsumption(const int layerId,
 564                                           const MatShape& netInputShape,
 565                                           CV_OUT size_t& weights, CV_OUT size_t& blobs) const;
 566
 567         /** @brief Computes bytes number which are requered to store
 568          * all weights and intermediate blobs for each layer.
 569          * @param netInputShapes vector of shapes for all net inputs.
 570          * @param layerIds output vector to save layer IDs.
 571          * @param weights output parameter to store resulting bytes for weights.
 572          * @param blobs output parameter to store resulting bytes for intermediate blobs.
 573          */
 574         void getMemoryConsumption(const std::vector<MatShape>& netInputShapes,
 575                                           CV_OUT std::vector<int>& layerIds,
 576                                           CV_OUT std::vector<size_t>& weights,
 577                                           CV_OUT std::vector<size_t>& blobs) const; // FIXIT: CV_WRAP
 578         /** @overload */
 579         void getMemoryConsumption(const MatShape& netInputShape,
 580                                           CV_OUT std::vector<int>& layerIds,
 581                                           CV_OUT std::vector<size_t>& weights,
 582                                           CV_OUT std::vector<size_t>& blobs) const; // FIXIT: CV_WRAP
 583
 584         /** @brief Enables or disables layer fusion in the network.
 585          * @param fusion true to enable the fusion, false to disable. The fusion is enabled by default.
 586          */
 587         CV_WRAP void enableFusion(bool fusion);
 588
 589         /** @brief Returns overall time for inference and timings (in ticks) for layers.
 590          * Indexes in returned vector correspond to layers ids. Some layers can be fused with others,
 591          * in this case zero ticks count will be return for that skipped layers.
 592          * @param timings vector for tick timings for all layers.
 593          * @return overall ticks for model inference.
 594          */
 595         CV_WRAP int64 getPerfProfile(CV_OUT std::vector<double>& timings);
 596
 597     private:
 598         struct Impl;
 599         Ptr<Impl> impl;
 600     };
 601
 602     /**
 603      * @deprecated Deprecated as external interface. Will be for internal needs only.
 604      * @brief Small interface class for loading trained serialized models of different dnn-frameworks. */
 605     class CV_EXPORTS_W Importer : public Algorithm
 606     {
 607     public:
 608
 609         /** @brief Adds loaded layers into the @p net and sets connections between them. */
 610         CV_DEPRECATED CV_WRAP virtual void populateNet(Net net) = 0;
 611
 612         virtual ~Importer();
 613     };
 614
 615     /** @brief Reads a network model stored in <a href="https://pjreddie.com/darknet/">Darknet</a> model files.
 616     *  @param cfgFile      path to the .cfg file with text description of the network architecture.
 617     *  @param darknetModel path to the .weights file with learned network.
 618     *  @returns Network object that ready to do forward, throw an exception in failure cases.
 619     * @details This is shortcut consisting from DarknetImporter and Net::populateNet calls.
 620     */
 621     CV_EXPORTS_W Net readNetFromDarknet(const String &cfgFile, const String &darknetModel = String());
 622
 623     /**
 624      *  @deprecated Use @ref readNetFromCaffe instead.
 625      *  @brief Creates the importer of <a href="http://caffe.berkeleyvision.org">Caffe</a> framework network.
 626      *  @param prototxt   path to the .prototxt file with text description of the network architecture.
 627      *  @param caffeModel path to the .caffemodel file with learned network.
 628      *  @returns Pointer to the created importer, NULL in failure cases.
 629      */
 630     CV_DEPRECATED CV_EXPORTS_W Ptr<Importer> createCaffeImporter(const String &prototxt, const String &caffeModel = String());
 631
 632     /** @brief Reads a network model stored in Caffe model files.
 633       * @details This is shortcut consisting from createCaffeImporter and Net::populateNet calls.
 634       */
 635     CV_EXPORTS_W Net readNetFromCaffe(const String &prototxt, const String &caffeModel = String());
 636
 637     /** @brief Reads a network model stored in Tensorflow model file.
 638       * @details This is shortcut consisting from createTensorflowImporter and Net::populateNet calls.
 639       */
 640     CV_EXPORTS_W Net readNetFromTensorflow(const String &model, const String &config = String());
 641
 642     /** @brief Reads a network model stored in Torch model file.
 643       * @details This is shortcut consisting from createTorchImporter and Net::populateNet calls.
 644       */
 645     CV_EXPORTS_W Net readNetFromTorch(const String &model, bool isBinary = true);
 646
 647     /**
 648      *  @deprecated Use @ref readNetFromTensorflow instead.
 649      *  @brief Creates the importer of <a href="http://www.tensorflow.org">TensorFlow</a> framework network.
 650      *  @param model   path to the .pb file with binary protobuf description of the network architecture.
 651      *  @returns Pointer to the created importer, NULL in failure cases.
 652      */
 653     CV_DEPRECATED CV_EXPORTS_W Ptr<Importer> createTensorflowImporter(const String &model);
 654
 655     /**
 656      *  @deprecated Use @ref readNetFromTorch instead.
 657      *  @brief Creates the importer of <a href="http://torch.ch">Torch7</a> framework network.
 658      *  @param filename path to the file, dumped from Torch by using torch.save() function.
 659      *  @param isBinary specifies whether the network was serialized in ascii mode or binary.
 660      *  @returns Pointer to the created importer, NULL in failure cases.
 661      *
 662      *  @warning Torch7 importer is experimental now, you need explicitly set CMake `opencv_dnn_BUILD_TORCH_IMPORTER` flag to compile its.
 663      *
 664      *  @note Ascii mode of Torch serializer is more preferable, because binary mode extensively use `long` type of C language,
 665      *  which has various bit-length on different systems.
 666      *
 667      * The loading file must contain serialized <a href="https://github.com/torch/nn/blob/master/doc/module.md">nn.Module</a> object
 668      * with importing network. Try to eliminate a custom objects from serialazing data to avoid importing errors.
 669      *
 670      * List of supported layers (i.e. object instances derived from Torch nn.Module class):
 671      * - nn.Sequential
 672      * - nn.Parallel
 673      * - nn.Concat
 674      * - nn.Linear
 675      * - nn.SpatialConvolution
 676      * - nn.SpatialMaxPooling, nn.SpatialAveragePooling
 677      * - nn.ReLU, nn.TanH, nn.Sigmoid
 678      * - nn.Reshape
 679      * - nn.SoftMax, nn.LogSoftMax
 680      *
 681      * Also some equivalents of these classes from cunn, cudnn, and fbcunn may be successfully imported.
 682      */
 683     CV_DEPRECATED CV_EXPORTS_W Ptr<Importer> createTorchImporter(const String &filename, bool isBinary = true);
 684
 685     /** @brief Loads blob which was serialized as torch.Tensor object of Torch7 framework.
 686      *  @warning This function has the same limitations as createTorchImporter().
 687      */
 688     CV_EXPORTS_W Mat readTorchBlob(const String &filename, bool isBinary = true);
 689     /** @brief Creates 4-dimensional blob from image. Optionally resizes and crops @p image from center,
 690      *  subtract @p mean values, scales values by @p scalefactor, swap Blue and Red channels.
 691      *  @param image input image (with 1- or 3-channels).
 692      *  @param size spatial size for output image
 693      *  @param mean scalar with mean values which are subtracted from channels. Values are intended
 694      *  to be in (mean-R, mean-G, mean-B) order if @p image has BGR ordering and @p swapRB is true.
 695      *  @param scalefactor multiplier for @p image values.
 696      *  @param swapRB flag which indicates that swap first and last channels
 697      *  in 3-channel image is necessary.
 698      *  @details input image is resized so one side after resize is equal to corresponing
 699      *  dimension in @p size and another one is equal or larger. Then, crop from the center is performed.
 700      *  @returns 4-dimansional Mat with NCHW dimensions order.
 701      */
 702     CV_EXPORTS_W Mat blobFromImage(const Mat& image, double scalefactor=1.0, const Size& size = Size(),
 703                                    const Scalar& mean = Scalar(), bool swapRB=true);
 704     /** @brief Creates 4-dimensional blob from series of images. Optionally resizes and
 705      *  crops @p images from center, subtract @p mean values, scales values by @p scalefactor,
 706      *  swap Blue and Red channels.
 707      *  @param images input images (all with 1- or 3-channels).
 708      *  @param size spatial size for output image
 709      *  @param mean scalar with mean values which are subtracted from channels. Values are intended
 710      *  to be in (mean-R, mean-G, mean-B) order if @p image has BGR ordering and @p swapRB is true.
 711      *  @param scalefactor multiplier for @p images values.
 712      *  @param swapRB flag which indicates that swap first and last channels
 713      *  in 3-channel image is necessary.
 714      *  @details input image is resized so one side after resize is equal to corresponing
 715      *  dimension in @p size and another one is equal or larger. Then, crop from the center is performed.
 716      *  @returns 4-dimansional Mat with NCHW dimensions order.
 717      */
 718     CV_EXPORTS_W Mat blobFromImages(const std::vector<Mat>& images, double scalefactor=1.0,
 719                                     Size size = Size(), const Scalar& mean = Scalar(), bool swapRB=true);
 720
 721     /** @brief Convert all weights of Caffe network to half precision floating point.
 722      * @param src Path to origin model from Caffe framework contains single
 723      *            precision floating point weights (usually has `.caffemodel` extension).
 724      * @param dst Path to destination model with updated weights.
 725      *
 726      * @note Shrinked model has no origin float32 weights so it can't be used
 727      *       in origin Caffe framework anymore. However the structure of data
 728      *       is taken from NVidia's Caffe fork: https://github.com/NVIDIA/caffe.
 729      *       So the resulting model may be used there.
 730      */
 731     CV_EXPORTS_W void shrinkCaffeModel(const String& src, const String& dst);
 732
 733
 734 //! @}
 735 CV__DNN_EXPERIMENTAL_NS_END
 736 }
 737 }
 738
 739 #include <opencv2/dnn/layer.hpp>
 740 #include <opencv2/dnn/dnn.inl.hpp>
 741
 742 #endif  /* OPENCV_DNN_DNN_HPP */