Class Net

Namespace

OpenCvSharp.Dnn

Assembly

OpenCvSharp.dll

Base class for objects that own a single native OpenCV pointer through an OpenCvSafeHandle. The SafeHandle is the single source of truth for the native handle value and is responsible for releasing it (including from its own finalizer when the managed object is dropped without Dispose()).

[SuppressMessage("Microsoft.Design", "CA1724: Type names should not match namespaces")]
public class Net : CvObject, IDisposable

Inheritance

object

CvObject

Net

Implements

IDisposable

Inherited Members

CvObject.IsDisposed

CvObject.ptr

CvObject.SetSafeHandle(OpenCvSafeHandle)

CvObject.Dispose()

CvObject.Dispose(bool)

CvObject.DisposeManaged()

CvObject.DisposeUnmanaged()

CvObject.ThrowIfDisposed()

CvObject.CvPtr

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

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.

Constructors

Net()

Default constructor

public Net()

Net(nint)

Constructor (backward compatibility). Wraps the pointer in a non-owning SafeHandle. Derived classes that own the native resource should call SetSafeHandle(OpenCvSafeHandle) to replace it with an owning handle.

protected Net(nint ptr)

Parameters

ptr nint

Properties

ProfilingMode

Gets or sets the profiling mode of the new DNN engine (OpenCV 5).

public ProfilingMode ProfilingMode { get; set; }

Property Value

ProfilingMode

TracingMode

Gets or sets the tracing mode of the new DNN engine (OpenCV 5).

public TracingMode TracingMode { get; set; }

Property Value

TracingMode

Methods

Connect(int, int, int, int)

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

public void Connect(int outLayerId, int outNum, int inpLayerId, int inpNum)

Parameters

outLayerId int

identifier of the first layer

outNum int

identifier of the second layer

inpLayerId int

number of the first layer output

inpNum int

number of the second layer input

Connect(string, string)

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

public void Connect(string outPin, string inpPin)

Parameters

outPin string

descriptor of the first layer output.

inpPin string

descriptor of the second layer input.

DisableKVCache()

Disables the Key-Value (KV) cache.

public void DisableKVCache()

Dump()

Dump net to String. Call method after setInput(). To see correct backend, target and fusion run after forward().

public string Dump()

Returns

string

String with structure, hyperparameters, backend, target and fusion

DumpToFile(string)

Dump net structure, hyperparameters, backend, target and fusion to dot file

public void DumpToFile(string path)

Parameters

path string

path to output file with .dot extension

DumpToPbtxt(string)

Dump net structure, hyperparameters, backend, target and fusion to a pbtxt file.

public void DumpToPbtxt(string path)

Parameters

path string

path to output file with .pbtxt extension.

Remarks

Requires the network's output blobs to be allocated (e.g. after the input shape is known and the net has been set up); otherwise OpenCV raises an exception.

Empty()

Returns true if there are no layers in the network.

public bool Empty()

Returns

bool

EnableFusion(bool)

Enables or disables layer fusion in the network.

public void EnableFusion(bool fusion)

Parameters

fusion bool

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

EnableKVCache()

Enables the Key-Value (KV) cache, used to accelerate inference of transformer / LLM models.

public void EnableKVCache()

EnableWinograd(bool)

Enables or disables the Winograd convolution optimization.

public void EnableWinograd(bool useWinograd)

Parameters

useWinograd bool

true to enable, false to disable.

FinalizeNet()

Finalizes the network (new DNN engine, OpenCV 5). The first forward() does this automatically; calling it early pays the one-time setup cost at a predictable point and surfaces configuration errors before inference.

public void FinalizeNet()

Forward(IEnumerable<Mat>, IEnumerable<string>)

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

public void Forward(IEnumerable<Mat> outputBlobs, IEnumerable<string> outBlobNames)

Parameters

outputBlobs IEnumerable<Mat>

contains blobs for first outputs of specified layers.

outBlobNames IEnumerable<string>

names for layers which outputs are needed to get

Forward(IEnumerable<Mat>, string?)

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

public void Forward(IEnumerable<Mat> outputBlobs, string? outputName = null)

Parameters

outputBlobs IEnumerable<Mat>

contains all output blobs for specified layer.

outputName string

name for layer which output is needed to get. If outputName is empty, runs forward pass for the whole network.

Forward(string?)

Runs forward pass to compute output of layer with name @p outputName. By default runs forward pass for the whole network.

public Mat Forward(string? outputName = null)

Parameters

outputName string

name for layer which output is needed to get

Returns

Mat

blob for first output of specified layer.

ForwardAndRetrieve(IEnumerable<string>)

Runs forward pass to compute outputs of layers listed in @p outBlobNames, retrieving all output blobs for each layer specified in @p outBlobNames.

public Mat[][] ForwardAndRetrieve(IEnumerable<string> outBlobNames)

Parameters

outBlobNames IEnumerable<string>

names for layers which outputs are needed to get

Returns

Mat[][]

for each requested layer, an array containing all of that layer's output blobs.

GetFLOPS(MatShape, MatType)

Computes FLOP for whole loaded model with the specified single input shape and type (OpenCV 5).

public long GetFLOPS(MatShape netInputShape, MatType netInputType)

Parameters

netInputShape MatShape

shape for the net input.

netInputType MatType

element type for the net input.

Returns

long

computed FLOP.

GetFLOPS(IEnumerable<MatShape>, IEnumerable<MatType>)

Computes FLOP for whole loaded model with specified input shapes (OpenCV 5).

public long GetFLOPS(IEnumerable<MatShape> netInputShapes, IEnumerable<MatType> netInputTypes)

Parameters

netInputShapes IEnumerable<MatShape>

shapes for all net inputs.

netInputTypes IEnumerable<MatType>

element types for all net inputs (parallel to netInputShapes).

Returns

long

computed FLOP.

GetFLOPS(int, IEnumerable<MatShape>, IEnumerable<MatType>)

Computes FLOP for a specific layer with specified input shapes (OpenCV 5).

public long GetFLOPS(int layerId, IEnumerable<MatShape> netInputShapes, IEnumerable<MatType> netInputTypes)

Parameters

layerId int

id of the layer.

netInputShapes IEnumerable<MatShape>

shapes for all net inputs.

netInputTypes IEnumerable<MatType>

element types for all net inputs (parallel to netInputShapes).

Returns

long

computed FLOP.

GetLayer(int)

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

public Layer GetLayer(int layerId)

Parameters

layerId int

Returns

Layer

GetLayer(string)

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

public Layer GetLayer(string layerName)

Parameters

layerName string

Returns

Layer

GetLayerId(string)

Converts string name of the layer to the integer identifier.

public int GetLayerId(string layer)

Parameters

layer string

Returns

int

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

GetLayerNames()

public string?[] GetLayerNames()

Returns

string[]

GetLayerShapes(IEnumerable<MatShape>, IEnumerable<MatType>, int, out MatShape[], out MatShape[])

Returns input and output shapes for the layer with the specified id; preliminary inferencing isn't necessary (OpenCV 5).

public void GetLayerShapes(IEnumerable<MatShape> netInputShapes, IEnumerable<MatType> netInputTypes, int layerId, out MatShape[] inLayerShapes, out MatShape[] outLayerShapes)

Parameters

netInputShapes IEnumerable<MatShape>

shapes for all net inputs.

netInputTypes IEnumerable<MatType>

element types for all net inputs (parallel to netInputShapes).

layerId int

id of the layer.

inLayerShapes MatShape[]

output: input shapes of the layer.

outLayerShapes MatShape[]

output: output shapes of the layer.

Remarks

When the model is backed by OpenCV 5's new dnn engine, only layerId 0 is supported (it infers the whole graph); other ids throw. Use GetLayersShapes(IEnumerable<MatShape>, IEnumerable<MatType>, out int[], out MatShape[][], out MatShape[][]) to enumerate every layer, or pass one of the ids it reports.

GetLayerTypes()

Returns list of types for layer used in model.

public string?[] GetLayerTypes()

Returns

string[]

GetLayersCount(string)

Returns count of layers of specified type.

public int GetLayersCount(string layerType)

Parameters

layerType string

type.

Returns

int

count of layers

GetLayersShapes(IEnumerable<MatShape>, IEnumerable<MatType>, out int[], out MatShape[][], out MatShape[][])

Returns input and output shapes for all layers in the loaded model; preliminary inferencing isn't necessary (OpenCV 5).

public void GetLayersShapes(IEnumerable<MatShape> netInputShapes, IEnumerable<MatType> netInputTypes, out int[] layerIds, out MatShape[][] inLayersShapes, out MatShape[][] outLayersShapes)

Parameters

netInputShapes IEnumerable<MatShape>

shapes for all net inputs.

netInputTypes IEnumerable<MatType>

element types for all net inputs (parallel to netInputShapes).

layerIds int[]

output: layer IDs.

inLayersShapes MatShape[][]

output: input shapes per layer (order matches layerIds).

outLayersShapes MatShape[][]

output: output shapes per layer (order matches layerIds).

GetMemoryConsumption(IEnumerable<MatShape>, IEnumerable<MatType>, out int[], out long[], out long[])

Computes the number of bytes required to store all weights and intermediate blobs for each layer (OpenCV 5).

public void GetMemoryConsumption(IEnumerable<MatShape> netInputShapes, IEnumerable<MatType> netInputTypes, out int[] layerIds, out long[] weights, out long[] blobs)

Parameters

netInputShapes IEnumerable<MatShape>

shapes for all net inputs.

netInputTypes IEnumerable<MatType>

element types for all net inputs (parallel to netInputShapes).

layerIds int[]

output: layer IDs.

weights long[]

output: bytes for weights per layer (order matches layerIds).

blobs long[]

output: bytes for intermediate blobs per layer (order matches layerIds).

GetMemoryConsumption(IEnumerable<MatShape>, IEnumerable<MatType>, out long, out long)

Computes the number of bytes required to store all weights and intermediate blobs for the model (OpenCV 5).

public void GetMemoryConsumption(IEnumerable<MatShape> netInputShapes, IEnumerable<MatType> netInputTypes, out long weights, out long blobs)

Parameters

netInputShapes IEnumerable<MatShape>

shapes for all net inputs.

netInputTypes IEnumerable<MatType>

element types for all net inputs (parallel to netInputShapes).

weights long

output: bytes for weights.

blobs long

output: bytes for intermediate blobs.

GetModelFormat()

Returns the original framework format the network was loaded from.

public ModelFormat GetModelFormat()

Returns

ModelFormat

GetParam(int, int)

Returns parameter blob of the layer.

public Mat GetParam(int layer, int numParam = 0)

Parameters

layer int

id of the layer.

numParam int

index of the layer parameter in the Layer::blobs array.

Returns

Mat

GetParam(string, int)

Returns parameter blob of the layer.

public Mat GetParam(string layerName, int numParam = 0)

Parameters

layerName string

name of the layer.

numParam int

index of the layer parameter in the Layer::blobs array.

Returns

Mat

GetPerfProfile(out double[])

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.

public long GetPerfProfile(out double[] timings)

Parameters

timings double[]

vector for tick timings for all layers.

Returns

long

overall ticks for model inference.

GetPerfProfileDetailed(out string[], out string[], out string[])

Returns the detailed per-layer performance profile (new DNN engine, OpenCV 5): for each reported layer, its name, execution time and call count (all as strings).

public void GetPerfProfileDetailed(out string[] names, out string[] timems, out string[] counts)

Parameters

names string[]

Output layer names.

timems string[]

Output per-layer execution times (ms), as strings.

counts string[]

Output per-layer call counts, as strings.

GetUnconnectedOutLayers()

Returns indexes of layers with unconnected outputs.

public int[] GetUnconnectedOutLayers()

Returns

int[]

GetUnconnectedOutLayersNames()

Returns names of layers with unconnected outputs.

public string?[] GetUnconnectedOutLayersNames()

Returns

string[]

PrintPerfProfile()

Prints per-layer performance profile to the standard output.

public void PrintPerfProfile()

ReadFromModelOptimizer(string, string)

Create a network from Intel's Model Optimizer intermediate representation (IR). Networks imported from Intel's Model Optimizer are launched in Intel's Inference Engine backend.

public static Net? ReadFromModelOptimizer(string xml, string bin)

Parameters

xml string

XML configuration file with network's topology.

bin string

Binary file with trained weights.

Returns

Net

ReadNet(string, string, string, EngineType)

Read deep learning network represented in one of the supported formats.

This function automatically detects an origin framework of trained model and calls an appropriate function such @ref readNetFromTensorflow, @ref readNetFromONNX, or @ref readNetFromModelOptimizer. The Caffe, Darknet and Torch parsers were removed in OpenCV 5.

public static Net ReadNet(string model, string config = "", string framework = "", EngineType engine = EngineType.Auto)

Parameters

model string

Binary file contains trained weights. The following file * extensions are expected for models from different frameworks: * * *.pb (TensorFlow, https://www.tensorflow.org/) * * *.onnx (ONNX, https://onnx.ai/) * * *.bin (OpenVINO, https://software.intel.com/openvino-toolkit)

config string

Text file contains network configuration. It could be a * file with the following extensions: * * *.pbtxt (TensorFlow, https://www.tensorflow.org/) * * *.xml (OpenVINO, https://software.intel.com/openvino-toolkit)

framework string

Explicit framework name tag to determine a format.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

ReadNetFromModelOptimizer(string, string)

Load a network from Intel's Model Optimizer intermediate representation. Networks imported from Intel's Model Optimizer are launched in Intel's Inference Engine backend.

public static Net? ReadNetFromModelOptimizer(string xml, string bin)

Parameters

xml string

XML configuration file with network's topology.

bin string

Binary file with trained weights.

Returns

Net

ReadNetFromONNX(byte[], EngineType)

Reads a network model ONNX https://onnx.ai/ from memory

public static Net? ReadNetFromONNX(byte[] onnxFileData, EngineType engine = EngineType.Auto)

Parameters

onnxFileData byte[]

memory of the first byte of the buffer.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Network object that ready to do forward, throw an exception in failure cases.

ReadNetFromONNX(ReadOnlySpan<byte>, EngineType)

Reads a network model ONNX https://onnx.ai/ from memory

public static Net? ReadNetFromONNX(ReadOnlySpan<byte> onnxFileData, EngineType engine = EngineType.Auto)

Parameters

onnxFileData ReadOnlySpan<byte>

memory of the first byte of the buffer.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Network object that ready to do forward, throw an exception in failure cases.

ReadNetFromONNX(string, EngineType)

Reads a network model ONNX https://onnx.ai/

public static Net? ReadNetFromONNX(string onnxFile, EngineType engine = EngineType.Auto)

Parameters

onnxFile string

path to the .onnx file with text description of the network architecture.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Network object that ready to do forward, throw an exception in failure cases.

ReadNetFromTFLite(byte[], EngineType)

Reads a network model stored in TFLite framework's format from memory.

public static Net? ReadNetFromTFLite(byte[] bufferModel, EngineType engine = EngineType.Auto)

Parameters

bufferModel byte[]

buffer containing the content of the tflite file.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Network object that ready to do forward, throw an exception in failure cases.

ReadNetFromTFLite(ReadOnlySpan<byte>, EngineType)

Reads a network model stored in TFLite framework's format from memory.

public static Net? ReadNetFromTFLite(ReadOnlySpan<byte> bufferModel, EngineType engine = EngineType.Auto)

Parameters

bufferModel ReadOnlySpan<byte>

buffer containing the content of the tflite file.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Network object that ready to do forward, throw an exception in failure cases.

ReadNetFromTFLite(string, EngineType)

Reads a network model stored in TFLite (https://www.tensorflow.org/lite) framework's format.

public static Net? ReadNetFromTFLite(string model, EngineType engine = EngineType.Auto)

Parameters

model string

path to the .tflite file with binary flatbuffers description of the network architecture.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Network object that ready to do forward, throw an exception in failure cases.

ReadNetFromTensorflow(byte[], byte[]?, EngineType)

Reads a network model stored in Tensorflow model from memory.

public static Net? ReadNetFromTensorflow(byte[] bufferModel, byte[]? bufferConfig = null, EngineType engine = EngineType.Auto)

Parameters

bufferModel byte[]

buffer containing the content of the pb file

bufferConfig byte[]

buffer containing the content of the pbtxt file (optional)

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Remarks

This is shortcut consisting from createTensorflowImporter and Net::populateNet calls.

ReadNetFromTensorflow(ReadOnlySpan<byte>, ReadOnlySpan<byte>, EngineType)

Reads a network model stored in Tensorflow model from memory.

public static Net? ReadNetFromTensorflow(ReadOnlySpan<byte> bufferModel, ReadOnlySpan<byte> bufferConfig = default, EngineType engine = EngineType.Auto)

Parameters

bufferModel ReadOnlySpan<byte>

buffer containing the content of the pb file

bufferConfig ReadOnlySpan<byte>

buffer containing the content of the pbtxt file (optional)

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Remarks

This is shortcut consisting from createTensorflowImporter and Net::populateNet calls.

ReadNetFromTensorflow(string, string?, EngineType)

Reads a network model stored in Tensorflow model file.

public static Net? ReadNetFromTensorflow(string model, string? config = null, EngineType engine = EngineType.Auto)

Parameters

model string

path to the .pb file with binary protobuf description of the network architecture

config string

path to the .pbtxt file that contains text graph definition in protobuf format.

engine EngineType

DNN engine to use. Auto tries the new engine first and falls back to the classic one.

Returns

Net

Resulting Net object is built by text graph using weights from a binary one that let us make it more flexible.

Remarks

This is shortcut consisting from createTensorflowImporter and Net::populateNet calls.

RegisterOutput(string, int, int)

Registers a network output by name (new DNN engine, OpenCV 5).

public int RegisterOutput(string outputName, int layerId, int outputPort)

Parameters

outputName string

Name to register the output under.

layerId int

Id of the producing layer.

outputPort int

Output port of the producing layer.

Returns

int

The index of the registered output.

ResetKVCache()

Resets the Key-Value (KV) cache contents.

public void ResetKVCache()

SetInput(Mat, string)

Sets the new value for the layer output blob

public void SetInput(Mat blob, string name = "")

Parameters

blob Mat

new blob.

name string

descriptor of the updating layer output blob.

Remarks

connect(String, String) to know format of the descriptor. If updating blob is not empty then @p blob must have the same shape, because network reshaping is not implemented yet.

SetInputShape(string, IEnumerable<int>)

Specify shape of network input.

public void SetInputShape(string inputName, IEnumerable<int> shape)

Parameters

inputName string

name of the input layer.

shape IEnumerable<int>

the shape of the input blob.

SetInputsNames(IEnumerable<string>)

Sets outputs names of the network input pseudo layer.

public void SetInputsNames(IEnumerable<string> inputBlobNames)

Parameters

inputBlobNames IEnumerable<string>

Remarks

• 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(int, int, Mat)

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

public void SetParam(int layer, int numParam, Mat blob)

Parameters

layer int

id of the layer.

numParam int

index of the layer parameter in the Layer::blobs array.

blob Mat

the new value.

SetParam(string, int, Mat)

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

public void SetParam(string layerName, int numParam, Mat blob)

Parameters

layerName string

name of the layer.

numParam int

index of the layer parameter in the Layer::blobs array.

blob Mat

the new value.

SetPreferableBackend(Backend)

Ask network to use specific computation backend where it supported.

public void SetPreferableBackend(Backend backendId)

Parameters

backendId Backend

backend identifier.

SetPreferableTarget(Target)

Ask network to make computations on specific target device.

public void SetPreferableTarget(Target targetId)

Parameters

targetId Target

target identifier.