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.

	GComputation (GProtoInputArgs &&ins, GProtoOutputArgs &&outs)
	Generic GComputation constructor.

	GComputation (GMat in, GMat out)
	Defines an unary (one input – one output) computation.

	GComputation (GMat in, GScalar out)
	Defines an unary (one input – one output) computation.

	GComputation (GMat in1, GMat in2, GMat out)
	Defines a binary (two inputs – one output) computation.

	GComputation (GMat in1, GMat in2, GScalar out)
	Defines a binary (two inputs – one output) computation.

	GComputation (const std::vector< GMat > &ins, const std::vector< GMat > &outs)
	Defines a computation with arbitrary input/output number.

void	apply (GRunArgs &&ins, GRunArgsP &&outs, GCompileArgs &&args={})
	Compile graph on-the-fly and immediately execute it on the inputs data vectors.

void	apply (cv::Mat in, cv::Mat &out, GCompileArgs &&args={})
	Execute an unary computation (with compilation on the fly)

void	apply (cv::Mat in, cv::Scalar &out, GCompileArgs &&args={})
	Execute an unary computation (with compilation on the fly)

void	apply (cv::Mat in1, cv::Mat in2, cv::Mat &out, GCompileArgs &&args={})
	Execute a binary computation (with compilation on the fly)

void	apply (cv::Mat in1, cv::Mat in2, cv::Scalar &out, GCompileArgs &&args={})
	Execute an binary computation (with compilation on the fly)

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).

GCompiled	compile (GMetaArgs &&in_metas, GCompileArgs &&args={})
	Compile the computation for specific input format(s).

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

    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 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

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

Constructor & Destructor Documentation

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.

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 Objects

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

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

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

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

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

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 Objects, G-API Graph Compilation Arguments

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.

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.

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.

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.

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

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 vectos must match numbers of inputs/outputs which were used to define this GComputation.

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

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.

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:

gcomputation.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation