OpenCV: cv::dnn::Net Class Reference

| OpenCV 3.4.2 Open Source Computer Vision

Public Types | Public Member Functions | Static Public Member Functions | List of all members
cv::dnn::Net Class Reference
Deep Neural Network module

This class allows to create and manipulate comprehensive artificial neural networks. More...

`#include "dnn.hpp"`

## Public Types
typedef DictValue | LayerId
| Container for strings and integers. More...

## Public Member Functions
| Net ()
| Default constructor. More...
| ~Net ()
| Destructor frees the net only if there aren't references to the net anymore. More...
int | addLayer (const String &name, const String &type, LayerParams &params)
| Adds new layer to the net. More...
int | addLayerToPrev (const String &name, const String &type, LayerParams &params)
| Adds new layer and connects its first input to the first output of previously added layer. More...
void | connect (String outPin, String inpPin)
| Connects output of the first layer to input of the second layer. More...
void | connect (int outLayerId, int outNum, int inpLayerId, int inpNum)
| Connects #`outNum` output of the first layer to #`inNum` input of the second layer. More...
void | deleteLayer (LayerId layer)
| Delete layer for the network (not implemented yet) More...
bool | empty () const
void | enableFusion (bool fusion)
| Enables or disables layer fusion in the network. More...
Mat | forward (const String &outputName=String())
| Runs forward pass to compute output of layer with name `outputName`. More...
void | forward (OutputArrayOfArrays outputBlobs, const String &outputName=String())
| Runs forward pass to compute output of layer with name `outputName`. More...
void | forward (OutputArrayOfArrays outputBlobs, const std::vector< String > &outBlobNames)
| Runs forward pass to compute outputs of layers listed in `outBlobNames`. More...
void | forward (std::vector< std::vector< Mat > > &outputBlobs, const std::vector< String > &outBlobNames)
| Runs forward pass to compute outputs of layers listed in `outBlobNames`. More...
int64 | getFLOPS (const std::vector< MatShape > &netInputShapes) const
| Computes FLOP for whole loaded model with specified input shapes. More...
int64 | getFLOPS (const MatShape &netInputShape) const
int64 | getFLOPS (const int layerId, const std::vector< MatShape > &netInputShapes) const
int64 | getFLOPS (const int layerId, const MatShape &netInputShape) const
Ptr< Layer > | getLayer (LayerId layerId)
| Returns pointer to layer with specified id or name which the network use. More...
int | getLayerId (const String &layer)
| Converts string name of the layer to the integer identifier. More...
std::vector< Ptr< Layer > > | getLayerInputs (LayerId layerId)
| Returns pointers to input layers of specific layer. More...
std::vector< String > | getLayerNames () const
int | getLayersCount (const String &layerType) const
| Returns count of layers of specified type. More...
void | getLayerShapes (const MatShape &netInputShape, const int layerId, std::vector< MatShape > &inLayerShapes, std::vector< MatShape > &outLayerShapes) const
| Returns input and output shapes for layer with specified id in loaded model; preliminary inferencing isn't necessary. More...
void | getLayerShapes (const std::vector< MatShape > &netInputShapes, const int layerId, std::vector< MatShape > &inLayerShapes, std::vector< MatShape > &outLayerShapes) const
void | getLayersShapes (const std::vector< MatShape > &netInputShapes, std::vector< int > &layersIds, std::vector< std::vector< MatShape > > &inLayersShapes, std::vector< std::vector< MatShape > > &outLayersShapes) const
| Returns input and output shapes for all layers in loaded model; preliminary inferencing isn't necessary. More...
void | getLayersShapes (const MatShape &netInputShape, std::vector< int > &layersIds, std::vector< std::vector< MatShape > > &inLayersShapes, std::vector< std::vector< MatShape > > &outLayersShapes) const
void | getLayerTypes (std::vector< String > &layersTypes) const
| Returns list of types for layer used in model. More...
void | getMemoryConsumption (const std::vector< MatShape > &netInputShapes, size_t &weights, size_t &blobs) const
| Computes bytes number which are required to store all weights and intermediate blobs for model. More...
void | getMemoryConsumption (const MatShape &netInputShape, size_t &weights, size_t &blobs) const
void | getMemoryConsumption (const int layerId, const std::vector< MatShape > &netInputShapes, size_t &weights, size_t &blobs) const
void | getMemoryConsumption (const int layerId, const MatShape &netInputShape, size_t &weights, size_t &blobs) const
void | getMemoryConsumption (const std::vector< MatShape > &netInputShapes, std::vector< int > &layerIds, std::vector< size_t > &weights, std::vector< size_t > &blobs) const
| Computes bytes number which are required to store all weights and intermediate blobs for each layer. More...
void | getMemoryConsumption (const MatShape &netInputShape, std::vector< int > &layerIds, std::vector< size_t > &weights, std::vector< size_t > &blobs) const
Mat | getParam (LayerId layer, int numParam=0)
| Returns parameter blob of the layer. More...
int64 | getPerfProfile (std::vector< double > &timings)
| Returns overall time for inference and timings (in ticks) for layers. Indexes in returned vector correspond to layers ids. Some layers can be fused with others, in this case zero ticks count will be return for that skipped layers. More...
std::vector< int > | getUnconnectedOutLayers () const
| Returns indexes of layers with unconnected outputs. More...
void | setHalideScheduler (const String &scheduler)
| Compile Halide layers. More...
void | setInput (InputArray blob, const String &name="")
| Sets the new value for the layer output blob. More...
void | setInputsNames (const std::vector< String > &inputBlobNames)
| Sets outputs names of the network input pseudo layer. More...
void | setParam (LayerId layer, int numParam, const Mat &blob)
| Sets the new value for the learned param of the layer. More...
void | setPreferableBackend (int backendId)
| Ask network to use specific computation backend where it supported. More...
void | setPreferableTarget (int targetId)
| Ask network to make computations on specific target device. More...

## Static Public Member Functions
static Net | readFromModelOptimizer (const String &xml, const String &bin)
| Create a network from Intel's Model Optimizer intermediate representation. More...

## Detailed Description

This class allows to create and manipulate comprehensive artificial neural networks.

Neural network is presented as directed acyclic graph (DAG), where vertices are Layer instances, and edges specify relationships between layers inputs and outputs.

Each network layer has unique integer id and unique string name inside its network. LayerId can store either layer name or layer id.

This class supports reference counting of its instances, i. e. copies point to the same instance.

## Member Typedef Documentation

## ◆ LayerId

typedef DictValue cv::dnn::Net::LayerId

Container for strings and integers.

## Constructor & Destructor Documentation

## ◆ Net()

cv::dnn::Net::Net | ( |  | ) |

Default constructor.

## ◆ ~Net()

cv::dnn::Net::~Net | ( |  | ) |

Destructor frees the net only if there aren't references to the net anymore.

## Member Function Documentation

## ◆ addLayer()

int cv::dnn::Net::addLayer | ( | const String & | name,
|  | const String & | type,
|  | LayerParams & | params
| ) |  |

Adds new layer to the net.

Parameters

  name | unique name of the adding layer.
  type | typename of the adding layer (type must be registered in LayerRegister).
  params | parameters which will be used to initialize the creating layer.

Returns
  unique identifier of created layer, or -1 if a failure will happen.

## ◆ addLayerToPrev()

int cv::dnn::Net::addLayerToPrev | ( | const String & | name,
|  | const String & | type,
|  | LayerParams & | params
| ) |  |

Adds new layer and connects its first input to the first output of previously added layer.

See also
  addLayer()

## ◆ connect() [1/2]

void cv::dnn::Net::connect | ( | String | outPin,
|  | String | inpPin
| ) |  |

Connects output of the first layer to input of the second layer.

Parameters

  outPin | descriptor of the first layer output.
  inpPin | descriptor of the second layer input.

Descriptors have the following template `<layer_name>[.input_number]`:

- the first part of the template `layer_name` is sting name of the added layer. If this part is empty then the network input pseudo layer will be used;

- the second optional part of the template `input_number` is either number of the layer input, either label one. If this part is omitted then the first layer input will be used.

  See also
    setNetInputs(), Layer::inputNameToIndex(), Layer::outputNameToIndex()

## ◆ connect() [2/2]

void cv::dnn::Net::connect | ( | int | outLayerId,
|  | int | outNum,
|  | int | inpLayerId,
|  | int | inpNum
| ) |  |

Connects #`outNum` output of the first layer to #`inNum` input of the second layer.

Parameters

  outLayerId | identifier of the first layer
  outNum | number of the first layer output
  inpLayerId | identifier of the second layer
  inpNum | number of the second layer input

## ◆ deleteLayer()

void cv::dnn::Net::deleteLayer | ( | LayerId | layer | ) |

Delete layer for the network (not implemented yet)

## ◆ empty()

bool cv::dnn::Net::empty | ( |  | ) | const

Returns true if there are no layers in the network.

## ◆ enableFusion()

void cv::dnn::Net::enableFusion | ( | bool | fusion | ) |

Enables or disables layer fusion in the network.

Parameters

  fusion | true to enable the fusion, false to disable. The fusion is enabled by default.

## ◆ forward() [1/4]

Mat cv::dnn::Net::forward | ( | const String & | outputName = `String()` | ) |

Runs forward pass to compute output of layer with name `outputName`.

Parameters

  outputName | name for layer which output is needed to get

Returns
  blob for first output of specified layer.

By default runs forward pass for the whole network.

## ◆ forward() [2/4]

void cv::dnn::Net::forward | ( | OutputArrayOfArrays | outputBlobs,
|  | const String & | outputName = `String()`
| ) |  |

Runs forward pass to compute output of layer with name `outputName`.

Parameters

  outputBlobs | contains all output blobs for specified layer.
  outputName | name for layer which output is needed to get

If `outputName` is empty, runs forward pass for the whole network.

## ◆ forward() [3/4]

void cv::dnn::Net::forward | ( | OutputArrayOfArrays | outputBlobs,
|  | const std::vector< String > & | outBlobNames
| ) |  |

Runs forward pass to compute outputs of layers listed in `outBlobNames`.

Parameters

  outputBlobs | contains blobs for first outputs of specified layers.
  outBlobNames | names for layers which outputs are needed to get

## ◆ forward() [4/4]

void cv::dnn::Net::forward | ( | std::vector< std::vector< Mat > > & | outputBlobs,
|  | const std::vector< String > & | outBlobNames
| ) |  |

Runs forward pass to compute outputs of layers listed in `outBlobNames`.

Parameters

  outputBlobs | contains all output blobs for each layer specified in `outBlobNames`.
  outBlobNames | names for layers which outputs are needed to get

## ◆ getFLOPS() [1/4]

int64 cv::dnn::Net::getFLOPS | ( | const std::vector< MatShape > & | netInputShapes | ) | const

Computes FLOP for whole loaded model with specified input shapes.

Parameters

  netInputShapes | vector of shapes for all net inputs.

Returns
  computed FLOP.

## ◆ getFLOPS() [2/4]

int64 cv::dnn::Net::getFLOPS | ( | const MatShape & | netInputShape | ) | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getFLOPS() [3/4]

int64 cv::dnn::Net::getFLOPS | ( | const int | layerId,
|  | const std::vector< MatShape > & | netInputShapes
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getFLOPS() [4/4]

int64 cv::dnn::Net::getFLOPS | ( | const int | layerId,
|  | const MatShape & | netInputShape
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getLayer()

Ptr<Layer> cv::dnn::Net::getLayer | ( | LayerId | layerId | ) |

Returns pointer to layer with specified id or name which the network use.

## ◆ getLayerId()

int cv::dnn::Net::getLayerId | ( | const String & | layer | ) |

Converts string name of the layer to the integer identifier.

Returns
  id of the layer, or -1 if the layer wasn't found.

## ◆ getLayerInputs()

std::vector<Ptr<Layer> > cv::dnn::Net::getLayerInputs | ( | LayerId | layerId | ) |

Returns pointers to input layers of specific layer.

## ◆ getLayerNames()

std::vector<String> cv::dnn::Net::getLayerNames | ( |  | ) | const

## ◆ getLayersCount()

int cv::dnn::Net::getLayersCount | ( | const String & | layerType | ) | const

Returns count of layers of specified type.

Parameters

  layerType | type.

Returns
  count of layers

## ◆ getLayerShapes() [1/2]

void cv::dnn::Net::getLayerShapes | ( | const MatShape & | netInputShape,
|  | const int | layerId,
|  | std::vector< MatShape > & | inLayerShapes,
|  | std::vector< MatShape > & | outLayerShapes
| ) |  | const

Returns input and output shapes for layer with specified id in loaded model; preliminary inferencing isn't necessary.

Parameters

  netInputShape | shape input blob in net input layer.
  layerId | id for layer.
  inLayerShapes | output parameter for input layers shapes; order is the same as in layersIds
  outLayerShapes | output parameter for output layers shapes; order is the same as in layersIds

## ◆ getLayerShapes() [2/2]

void cv::dnn::Net::getLayerShapes | ( | const std::vector< MatShape > & | netInputShapes,
|  | const int | layerId,
|  | std::vector< MatShape > & | inLayerShapes,
|  | std::vector< MatShape > & | outLayerShapes
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getLayersShapes() [1/2]

void cv::dnn::Net::getLayersShapes | ( | const std::vector< MatShape > & | netInputShapes,
|  | std::vector< int > & | layersIds,
|  | std::vector< std::vector< MatShape > > & | inLayersShapes,
|  | std::vector< std::vector< MatShape > > & | outLayersShapes
| ) |  | const

Returns input and output shapes for all layers in loaded model; preliminary inferencing isn't necessary.

Parameters

  netInputShapes | shapes for all input blobs in net input layer.
  layersIds | output parameter for layer IDs.
  inLayersShapes | output parameter for input layers shapes; order is the same as in layersIds
  outLayersShapes | output parameter for output layers shapes; order is the same as in layersIds

## ◆ getLayersShapes() [2/2]

void cv::dnn::Net::getLayersShapes | ( | const MatShape & | netInputShape,
|  | std::vector< int > & | layersIds,
|  | std::vector< std::vector< MatShape > > & | inLayersShapes,
|  | std::vector< std::vector< MatShape > > & | outLayersShapes
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getLayerTypes()

void cv::dnn::Net::getLayerTypes | ( | std::vector< String > & | layersTypes | ) | const

Returns list of types for layer used in model.

Parameters

  layersTypes | output parameter for returning types.

## ◆ getMemoryConsumption() [1/6]

void cv::dnn::Net::getMemoryConsumption | ( | const std::vector< MatShape > & | netInputShapes,
|  | size_t & | weights,
|  | size_t & | blobs
| ) |  | const

Computes bytes number which are required to store all weights and intermediate blobs for model.

Parameters

  netInputShapes | vector of shapes for all net inputs.
  weights | output parameter to store resulting bytes for weights.
  blobs | output parameter to store resulting bytes for intermediate blobs.

## ◆ getMemoryConsumption() [2/6]

void cv::dnn::Net::getMemoryConsumption | ( | const MatShape & | netInputShape,
|  | size_t & | weights,
|  | size_t & | blobs
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getMemoryConsumption() [3/6]

void cv::dnn::Net::getMemoryConsumption | ( | const int | layerId,
|  | const std::vector< MatShape > & | netInputShapes,
|  | size_t & | weights,
|  | size_t & | blobs
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getMemoryConsumption() [4/6]

void cv::dnn::Net::getMemoryConsumption | ( | const int | layerId,
|  | const MatShape & | netInputShape,
|  | size_t & | weights,
|  | size_t & | blobs
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getMemoryConsumption() [5/6]

void cv::dnn::Net::getMemoryConsumption | ( | const std::vector< MatShape > & | netInputShapes,
|  | std::vector< int > & | layerIds,
|  | std::vector< size_t > & | weights,
|  | std::vector< size_t > & | blobs
| ) |  | const

Computes bytes number which are required to store all weights and intermediate blobs for each layer.

Parameters

  netInputShapes | vector of shapes for all net inputs.
  layerIds | output vector to save layer IDs.
  weights | output parameter to store resulting bytes for weights.
  blobs | output parameter to store resulting bytes for intermediate blobs.

## ◆ getMemoryConsumption() [6/6]

void cv::dnn::Net::getMemoryConsumption | ( | const MatShape & | netInputShape,
|  | std::vector< int > & | layerIds,
|  | std::vector< size_t > & | weights,
|  | std::vector< size_t > & | blobs
| ) |  | const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ getParam()

Mat cv::dnn::Net::getParam | ( | LayerId | layer,
|  | int | numParam = `0`
| ) |  |

Returns parameter blob of the layer.

Parameters

  layer | name or id of the layer.
  numParam | index of the layer parameter in the Layer::blobs array.

See also
  Layer::blobs

## ◆ getPerfProfile()

int64 cv::dnn::Net::getPerfProfile | ( | std::vector< double > & | timings | ) |

Returns overall time for inference and timings (in ticks) for layers. Indexes in returned vector correspond to layers ids. Some layers can be fused with others, in this case zero ticks count will be return for that skipped layers.

Parameters

  timings | vector for tick timings for all layers.

Returns
  overall ticks for model inference.

## ◆ getUnconnectedOutLayers()

std::vector<int> cv::dnn::Net::getUnconnectedOutLayers | ( |  | ) | const

Returns indexes of layers with unconnected outputs.

## ◆ readFromModelOptimizer()

static Net cv::dnn::Net::readFromModelOptimizer | ( | const String & | xml,
|  | const String & | bin
| ) |  |
| static

Create a network from Intel's Model Optimizer intermediate representation.

Parameters

  [in] | xml | XML configuration file with network's topology.
  [in] | bin | Binary file with trained weights. Networks imported from Intel's Model Optimizer are launched in Intel's Inference Engine backend.

## ◆ setHalideScheduler()

void cv::dnn::Net::setHalideScheduler | ( | const String & | scheduler | ) |

Compile Halide layers.

Parameters

  [in] | scheduler | Path to YAML file with scheduling directives.

See also
  setPreferableBackend

Schedule layers that support Halide backend. Then compile them for specific target. For layers that not represented in scheduling file or if no manual scheduling used at all, automatic scheduling will be applied.

## ◆ setInput()

void cv::dnn::Net::setInput | ( | InputArray | blob,
|  | const String & | name = `""`
| ) |  |

Sets the new value for the layer output blob.

Parameters

  name | descriptor of the updating layer output blob.
  blob | new blob.

See also
  connect(String, String) to know format of the descriptor.

Note
  If updating blob is not empty then `blob` must have the same shape, because network reshaping is not implemented yet.

## ◆ setInputsNames()

void cv::dnn::Net::setInputsNames | ( | const std::vector< String > & | inputBlobNames | ) |

Sets outputs names of the network input pseudo layer.

Each net always has special own the network input pseudo layer with id=0. This layer stores the user blobs only and don't make any computations. In fact, this layer provides the only way to pass user data into the network. As any other layer, this layer can label its outputs and this function provides an easy way to do this.

## ◆ setParam()

void cv::dnn::Net::setParam | ( | LayerId | layer,
|  | int | numParam,
|  | const Mat & | blob
| ) |  |

Sets the new value for the learned param of the layer.

Parameters

  layer | name or id of the layer.
  numParam | index of the layer parameter in the Layer::blobs array.
  blob | the new value.

See also
  Layer::blobs

Note
  If shape of the new blob differs from the previous shape, then the following forward pass may fail.

## ◆ setPreferableBackend()

void cv::dnn::Net::setPreferableBackend | ( | int | backendId | ) |

Ask network to use specific computation backend where it supported.

Parameters

  [in] | backendId | backend identifier.

See also
  Backend

If OpenCV is compiled with Intel's Inference Engine library, DNN_BACKEND_DEFAULT means DNN_BACKEND_INFERENCE_ENGINE. Otherwise it equals to DNN_BACKEND_OPENCV.

## ◆ setPreferableTarget()

void cv::dnn::Net::setPreferableTarget | ( | int | targetId | ) |

Ask network to make computations on specific target device.

Parameters

  [in] | targetId | target identifier.

See also
  Target

List of supported combinations backend / target:

| DNN_BACKEND_OPENCV | DNN_BACKEND_INFERENCE_ENGINE | DNN_BACKEND_HALIDE
--- | --- | --- | ---
DNN_TARGET_CPU | + | + | +
DNN_TARGET_OPENCL | + | + | +
DNN_TARGET_OPENCL_FP16 | + | + |
DNN_TARGET_MYRIAD |  | + |

The documentation for this class was generated from the following file:

- dnn/include/opencv2/dnn/dnn.hpp