OpenCV  4.0.1
Open Source Computer Vision
Public Types | Public Member Functions | List of all members
cv::GComputation Class Reference

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 "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, const 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
 

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}\)):

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 computaion 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 gx = cv::gapi::Sobel(in, CV_32F, 1, 0);
cv::GMat gy = cv::gapi::Sobel(in, CV_32F, 0, 1);
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 unecessary objects and information.

Parameters
gengenerator 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
insInput data vector.
outsOutput data vector.
Note
Don't construct GProtoInputArgs/GProtoOutputArgs objects directly, use cv::GIn()/cvGOut() wrapper functions instead.
See also
G-API Data Objects

§ 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
ininput GMat of the defined unary computation
outoutput 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
ininput GMat of the defined unary computation
outoutput 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
in1first input GMat of the defined binary computation
in2second input GMat of the defined binary computation
outoutput 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
in1first input GMat of the defined binary computation
in2second input GMat of the defined binary computation
outoutput 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
insvector of inputs GMats for this computation
outsvector 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
insvector of input data to process. Don't create GRunArgs object manually, use cv::gin() wrapper instead.
outsvector 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.
argsa 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 Objects, 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
ininput cv::Mat for unary computation
outoutput cv::Mat for unary computation
argscompilation 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
ininput cv::Mat for unary computation
outoutput cv::Scalar for unary computation
argscompilation 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
in1first input cv::Mat for binary computation
in2second input cv::Mat for binary computation
outoutput cv::Mat for binary computation
argscompilation 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
in1first input cv::Mat for binary computation
in2second input cv::Mat for binary computation
outoutput cv::Scalar for binary computation
argscompilation arguments for underlying compilation process.

§ apply() [6/6]

void cv::GComputation::apply ( const std::vector< cv::Mat > &  ins,
const 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
insvector of input cv::Mat objects to process by the computation.
outsvector of output cv::Mat objects to produce by the computation.
argscompilation arguments for underlying compilation process.

Numbers of elements in ins/outs vectos 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_metasvector 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.
argscompilation 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.

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