| OpenCV 4.3.0 Open Source Computer Vision

Public Types | Public Member Functions | Protected Member Functions | List of all members
cv::GComputation Class Reference
G-API framework » G-API Main Classes

GComputation class represents a captured computation graph. GComputation objects form boundaries for expression code user writes with G-API, allowing to compile and execute it. More...

`#include <opencv2/gapi/gcomputation.hpp>`

## Public Types
typedef std::function< GComputation()> | Generator

## Public Member Functions
| GComputation (const Generator &gen)
| Define a computation using a generator function. More...
| GComputation (GProtoInputArgs &&ins, GProtoOutputArgs &&outs)
| Generic GComputation constructor. More...
| GComputation (GMat in, GMat out)
| Defines an unary (one input – one output) computation. More...
| GComputation (GMat in, GScalar out)
| Defines an unary (one input – one output) computation. More...
| GComputation (GMat in1, GMat in2, GMat out)
| Defines a binary (two inputs – one output) computation. More...
| GComputation (GMat in1, GMat in2, GScalar out)
| Defines a binary (two inputs – one output) computation. More...
| GComputation (const std::vector< GMat > &ins, const std::vector< GMat > &outs)
| Defines a computation with arbitrary input/output number. More...
void | apply (GRunArgs &&ins, GRunArgsP &&outs, GCompileArgs &&args={})
| Compile graph on-the-fly and immediately execute it on the inputs data vectors. More...
void | apply (cv::Mat in, cv::Mat &out, GCompileArgs &&args={})
| Execute an unary computation (with compilation on the fly) More...
void | apply (cv::Mat in, cv::Scalar &out, GCompileArgs &&args={})
| Execute an unary computation (with compilation on the fly) More...
void | apply (cv::Mat in1, cv::Mat in2, cv::Mat &out, GCompileArgs &&args={})
| Execute a binary computation (with compilation on the fly) More...
void | apply (cv::Mat in1, cv::Mat in2, cv::Scalar &out, GCompileArgs &&args={})
| Execute an binary computation (with compilation on the fly) More...
void | apply (const std::vector< cv::Mat > &ins, std::vector< cv::Mat > &outs, GCompileArgs &&args={})
| Execute a computation with arbitrary number of inputs/outputs (with compilation on-the-fly). More...
GCompiled | compile (GMetaArgs &&in_metas, GCompileArgs &&args={})
| Compile the computation for specific input format(s). More...
template<typename... Ts>
auto | compile (const Ts &... metas) -> typename std::enable_if< detail::are_meta_descrs< Ts... >::value, GCompiled >::type
template<typename... Ts>
auto | compile (const Ts &... meta_and_compile_args) -> typename std::enable_if< detail::are_meta_descrs_but_last< Ts... >::value &&std::is_same< GCompileArgs, detail::last_type_t< Ts... > >::value, GCompiled >::type
GStreamingCompiled | compileStreaming (GMetaArgs &&in_metas, GCompileArgs &&args={})
| Compile the computation for streaming mode. More...
GStreamingCompiled | compileStreaming (GCompileArgs &&args={})
| Compile the computation for streaming mode. More...
template<typename... Ts>
auto | compileStreaming (const Ts &... metas) -> typename std::enable_if< detail::are_meta_descrs< Ts... >::value, GStreamingCompiled >::type
template<typename... Ts>
auto | compileStreaming (const Ts &... meta_and_compile_args) -> typename std::enable_if< detail::are_meta_descrs_but_last< Ts... >::value &&std::is_same< GCompileArgs, detail::last_type_t< Ts... > >::value, GStreamingCompiled >::type

## Protected Member Functions
template<typename... Ts, int... IIs>
GStreamingCompiled | compileStreaming (const std::tuple< Ts... > &meta_and_compile_args, detail::Seq< IIs... >)

## Detailed Description

GComputation class represents a captured computation graph. GComputation objects form boundaries for expression code user writes with G-API, allowing to compile and execute it.

G-API computations are defined with input/output data objects. G-API will track automatically which operations connect specified outputs to the inputs, forming up a call graph to be executed. The below example expresses calculation of Sobel operator for edge detection ( \(G = \sqrt{G_x^2 + G_y^2}\)):

cv::GMat in;
cv::GMat gx = cv::gapi::Sobel(in, CV_32F, 1, 0);
cv::GMat gy = cv::gapi::Sobel(in, CV_32F, 0, 1);
cv::GMat g = cv::gapi::sqrt(cv::gapi::mul(gx, gx) + cv::gapi::mul(gy, gy));
cv::GMat out = cv::gapi::convertTo(g, CV_8U);

Full pipeline can be now captured with this object declaration:

cv::GComputation sobelEdge(cv::GIn(in), cv::GOut(out));

Input/output data objects on which a call graph should be reconstructed are passed using special wrappers cv::GIn and cv::GOut. G-API will track automatically which operations form a path from inputs to outputs and build the execution graph appropriately.

Note that cv::GComputation doesn't take ownership on data objects it is defined. Moreover, multiple GComputation objects may be defined on the same expressions, e.g. a smaller pipeline which expects that image gradients are already pre-calculated may be defined like this:

cv::GComputation sobelEdgeSub(cv::GIn(gx, gy), cv::GOut(out));

The resulting graph would expect two inputs and produce one output. In this case, it doesn't matter if gx/gy data objects are results of cv::gapi::Sobel operators – G-API will stop unrolling expressions and building the underlying graph one reaching this data objects.

The way how GComputation is defined is important as its definition specifies graph protocol – the way how the graph should be used. Protocol is defined by number of inputs, number of outputs, and shapes of inputs and outputs.

In the above example, sobelEdge expects one Mat on input and produces one Mat; while sobelEdgeSub expects two Mats on input and produces one Mat. GComputation's protocol defines how other computation methods should be used – cv::GComputation::compile() and cv::GComputation::apply(). For example, if a graph is defined on two GMat inputs, two cv::Mat objects have to be passed to apply() for execution. GComputation checks protocol correctness in runtime so passing a different number of objects in apply() or passing cv::Scalar instead of cv::Mat there would compile well as a C++ source but raise an exception in run-time. G-API also comes with a typed wrapper cv::GComputationT<> which introduces this type-checking in compile-time.

cv::GComputation itself is a thin object which just captures what the graph is. The compiled graph (which actually process data) is represented by class GCompiled. Use compile() method to generate a compiled graph with given compile options. cv::GComputation can also be used to process data with implicit graph compilation on-the-fly, see apply() for details.

GComputation is a reference-counted object – once defined, all its copies will refer to the same instance.

See also
  GCompiled

## Member Typedef Documentation

## ◆ Generator

typedef std::function<GComputation()> cv::GComputation::Generator

## Constructor & Destructor Documentation

## ◆ GComputation() [1/7]

cv::GComputation::GComputation | ( | const Generator & | gen | ) |

Define a computation using a generator function.

Graph can be defined in-place directly at the moment of its construction with a lambda:

cv::GComputation sobelEdgeGen([](){
cv::GMat in;
cv::GMat gx = cv::gapi::Sobel(in, CV_32F, 1, 0);
cv::GMat gy = cv::gapi::Sobel(in, CV_32F, 0, 1);
cv::GMat g = cv::gapi::sqrt(cv::gapi::mul(gx, gx) + cv::gapi::mul(gy, gy));
cv::GMat out = cv::gapi::convertTo(g, CV_8U);
return cv::GComputation(in, out);
});

This may be useful since all temporary objects (cv::GMats) and namespaces can be localized to scope of lambda, without contaminating the parent scope with probably unnecessary objects and information.

Parameters

  gen | generator function which returns a cv::GComputation, see Generator.

## ◆ GComputation() [2/7]

cv::GComputation::GComputation | ( | GProtoInputArgs && | ins,
|  | GProtoOutputArgs && | outs
| ) |  |

Generic GComputation constructor.

Constructs a new graph with a given protocol, specified as a flow of operations connecting input/output objects. Throws if the passed boundaries are invalid, e.g. if there's no functional dependency (path) between given outputs and inputs.

Parameters

  ins | Input data vector.
  outs | Output data vector.

Note
  Don't construct GProtoInputArgs/GProtoOutputArgs objects directly, use cv::GIn()/cvGOut() wrapper functions instead.

See also
  G-API Data Types

## ◆ GComputation() [3/7]

cv::GComputation::GComputation | ( | GMat | in,
|  | GMat | out
| ) |  |

Defines an unary (one input – one output) computation.

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

Parameters

  in | input GMat of the defined unary computation
  out | output GMat of the defined unary computation

## ◆ GComputation() [4/7]

cv::GComputation::GComputation | ( | GMat | in,
|  | GScalar | out
| ) |  |

Defines an unary (one input – one output) computation.

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

Parameters

  in | input GMat of the defined unary computation
  out | output GScalar of the defined unary computation

## ◆ GComputation() [5/7]

cv::GComputation::GComputation | ( | GMat | in1,
|  | GMat | in2,
|  | GMat | out
| ) |  |

Defines a binary (two inputs – one output) computation.

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

Parameters

  in1 | first input GMat of the defined binary computation
  in2 | second input GMat of the defined binary computation
  out | output GMat of the defined binary computation

## ◆ GComputation() [6/7]

cv::GComputation::GComputation | ( | GMat | in1,
|  | GMat | in2,
|  | GScalar | out
| ) |  |

Defines a binary (two inputs – one output) computation.

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

Parameters

  in1 | first input GMat of the defined binary computation
  in2 | second input GMat of the defined binary computation
  out | output GScalar of the defined binary computation

## ◆ GComputation() [7/7]

cv::GComputation::GComputation | ( | const std::vector< GMat > & | ins,
|  | const std::vector< GMat > & | outs
| ) |  |

Defines a computation with arbitrary input/output number.

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

Parameters

  ins | vector of inputs GMats for this computation
  outs | vector of outputs GMats for this computation

Use this overload for cases when number of computation inputs/outputs is not known in compile-time – e.g. when graph is programmatically generated to build an image pyramid with the given number of levels, etc.

## Member Function Documentation

## ◆ apply() [1/6]

void cv::GComputation::apply | ( | GRunArgs && | ins,
|  | GRunArgsP && | outs,
|  | GCompileArgs && | args = `{}`
| ) |  |

Compile graph on-the-fly and immediately execute it on the inputs data vectors.

Number of input/output data objects must match GComputation's protocol, also types of host data objects (cv::Mat, cv::Scalar) must match the shapes of data objects from protocol (cv::GMat, cv::GScalar). If there's a mismatch, a run-time exception will be generated.

Internally, a cv::GCompiled object is created for the given input format configuration, which then is executed on the input data immediately. cv::GComputation caches compiled objects produced within apply() – if this method would be called next time with the same input parameters (image formats, image resolution, etc), the underlying compiled graph will be reused without recompilation. If new metadata doesn't match the cached one, the underlying compiled graph is regenerated.

Note
  compile() always triggers a compilation process and produces a new GCompiled object regardless if a similar one has been cached via apply() or not.

Parameters

  ins | vector of input data to process. Don't create GRunArgs object manually, use cv::gin() wrapper instead.
  outs | vector of output data to fill results in. cv::Mat objects may be empty in this vector, G-API will automatically initialize it with the required format & dimensions. Don't create GRunArgsP object manually, use cv::gout() wrapper instead.
  args | a list of compilation arguments to pass to the underlying compilation process. Don't create GCompileArgs object manually, use cv::compile_args() wrapper instead.

See also
  G-API Data Types, G-API Graph Compilation Arguments

## ◆ apply() [2/6]

void cv::GComputation::apply | ( | cv::Mat | in,
|  | cv::Mat & | out,
|  | GCompileArgs && | args = `{}`
| ) |  |

Execute an unary computation (with compilation on the fly)

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

Parameters

  in | input cv::Mat for unary computation
  out | output cv::Mat for unary computation
  args | compilation arguments for underlying compilation process.

## ◆ apply() [3/6]

void cv::GComputation::apply | ( | cv::Mat | in,
|  | cv::Scalar & | out,
|  | GCompileArgs && | args = `{}`
| ) |  |

Execute an unary computation (with compilation on the fly)

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

Parameters

  in | input cv::Mat for unary computation
  out | output cv::Scalar for unary computation
  args | compilation arguments for underlying compilation process.

## ◆ apply() [4/6]

void cv::GComputation::apply | ( | cv::Mat | in1,
|  | cv::Mat | in2,
|  | cv::Mat & | out,
|  | GCompileArgs && | args = `{}`
| ) |  |

Execute a binary computation (with compilation on the fly)

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

Parameters

  in1 | first input cv::Mat for binary computation
  in2 | second input cv::Mat for binary computation
  out | output cv::Mat for binary computation
  args | compilation arguments for underlying compilation process.

## ◆ apply() [5/6]

void cv::GComputation::apply | ( | cv::Mat | in1,
|  | cv::Mat | in2,
|  | cv::Scalar & | out,
|  | GCompileArgs && | args = `{}`
| ) |  |

Execute an binary computation (with compilation on the fly)

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

Parameters

  in1 | first input cv::Mat for binary computation
  in2 | second input cv::Mat for binary computation
  out | output cv::Scalar for binary computation
  args | compilation arguments for underlying compilation process.

## ◆ apply() [6/6]

void cv::GComputation::apply | ( | const std::vector< cv::Mat > & | ins,
|  | std::vector< cv::Mat > & | outs,
|  | GCompileArgs && | args = `{}`
| ) |  |

Execute a computation with arbitrary number of inputs/outputs (with compilation on-the-fly).

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

Parameters

  ins | vector of input cv::Mat objects to process by the computation.
  outs | vector of output cv::Mat objects to produce by the computation.
  args | compilation arguments for underlying compilation process.

Numbers of elements in ins/outs vectors must match numbers of inputs/outputs which were used to define this GComputation.

## ◆ compile() [1/3]

GCompiled cv::GComputation::compile | ( | GMetaArgs && | in_metas,
|  | GCompileArgs && | args = `{}`
| ) |  |

Compile the computation for specific input format(s).

This method triggers compilation process and produces a new GCompiled object which then can process data of the given format. Passing data with different format to the compiled computation will generate a run-time exception.

Parameters

  in_metas | vector of input metadata configuration. Grab metadata from real data objects (like cv::Mat or cv::Scalar) using cv::descr_of(), or create it on your own.
  args | compilation arguments for this compilation process. Compilation arguments directly affect what kind of executable object would be produced, e.g. which kernels (and thus, devices) would be used to execute computation.

Returns
  GCompiled, an executable computation compiled specifically for the given input parameters.

See also
  G-API Graph Compilation Arguments

## ◆ compile() [2/3]

template<typename... Ts>

auto cv::GComputation::compile | ( | const Ts &... | metas | ) | -> typename std::enable_if<detail::are_meta_descrs<Ts...>::value, GCompiled>::type
| inline

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

Takes a variadic parameter pack with metadata descriptors for which a compiled object needs to be produced.

Returns
  GCompiled, an executable computation compiled specifically for the given input parameters.

## ◆ compile() [3/3]

template<typename... Ts>

auto cv::GComputation::compile | ( | const Ts &... | meta_and_compile_args | ) | -> typename std::enable_if<detail::are_meta_descrs_but_last<Ts...>::value && std::is_same<GCompileArgs, detail::last_type_t<Ts...> >::value, GCompiled>::type
| inline

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

Takes a variadic parameter pack with metadata descriptors for which a compiled object needs to be produced, followed by GCompileArgs object representing compilation arguments for this process.

Returns
  GCompiled, an executable computation compiled specifically for the given input parameters.

## ◆ compileStreaming() [1/5]

GStreamingCompiled cv::GComputation::compileStreaming | ( | GMetaArgs && | in_metas,
|  | GCompileArgs && | args = `{}`
| ) |  |

Compile the computation for streaming mode.

This method triggers compilation process and produces a new GStreamingCompiled object which then can process video stream data of the given format. Passing a stream in a different format to the compiled computation will generate a run-time exception.

Parameters

  in_metas | vector of input metadata configuration. Grab metadata from real data objects (like cv::Mat or cv::Scalar) using cv::descr_of(), or create it on your own.
  args | compilation arguments for this compilation process. Compilation arguments directly affect what kind of executable object would be produced, e.g. which kernels (and thus, devices) would be used to execute computation.

Returns
  GStreamingCompiled, a streaming-oriented executable computation compiled specifically for the given input parameters.

See also
  G-API Graph Compilation Arguments

## ◆ compileStreaming() [2/5]

GStreamingCompiled cv::GComputation::compileStreaming | ( | GCompileArgs && | args = `{}` | ) |

Compile the computation for streaming mode.

This method triggers compilation process and produces a new GStreamingCompiled object which then can process video stream data in any format. Underlying mechanisms will be adjusted to every new input video stream automatically, but please note that not all existing backends support this (see reshape()).

Parameters

  args | compilation arguments for this compilation process. Compilation arguments directly affect what kind of executable object would be produced, e.g. which kernels (and thus, devices) would be used to execute computation.

Returns
  GStreamingCompiled, a streaming-oriented executable computation compiled for any input image format.

See also
  G-API Graph Compilation Arguments

## ◆ compileStreaming() [3/5]

template<typename... Ts>

auto cv::GComputation::compileStreaming | ( | const Ts &... | metas | ) | -> typename std::enable_if<detail::are_meta_descrs<Ts...>::value, GStreamingCompiled>::type
| inline

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

Takes a variadic parameter pack with metadata descriptors for which a compiled object needs to be produced.

Returns
  GStreamingCompiled, a streaming-oriented executable computation compiled specifically for the given input parameters.

## ◆ compileStreaming() [4/5]

template<typename... Ts>

auto cv::GComputation::compileStreaming | ( | const Ts &... | meta_and_compile_args | ) | -> typename std::enable_if<detail::are_meta_descrs_but_last<Ts...>::value && std::is_same<GCompileArgs, detail::last_type_t<Ts...> >::value, GStreamingCompiled>::type
| inline

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

Takes a variadic parameter pack with metadata descriptors for which a compiled object needs to be produced, followed by GCompileArgs object representing compilation arguments for this process.

Returns
  GStreamingCompiled, a streaming-oriented executable computation compiled specifically for the given input parameters.

## ◆ compileStreaming() [5/5]

template<typename... Ts, int... IIs>

GStreamingCompiled cv::GComputation::compileStreaming | ( | const std::tuple< Ts... > & | meta_and_compile_args,
|  | detail::Seq< IIs... > |
| ) |  |
| inline protected

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

- opencv2/gapi/gcomputation.hpp