OpenCV  4.10.0-dev
Open Source Computer Vision
No Matches
Graph API


OpenCV Graph API (or G-API) is a new OpenCV module targeted to make regular image processing fast and portable. These two goals are achieved by introducing a new graph-based model of execution.

G-API is a special module in OpenCV – in contrast with the majority of other main modules, this one acts as a framework rather than some specific CV algorithm. G-API provides means to define CV operations, construct graphs (in form of expressions) using it, and finally implement and run the operations for a particular backend.

G-API is a new module and now is in active development. It's API is volatile at the moment and there may be minor but compatibility-breaking changes in the future.


G-API documentation is organized into the following chapters:

API Example

A very basic example of G-API pipeline is shown below:

#include <opencv2/gapi.hpp>
int main(int argc, char *argv[])
if (argc > 1)[1]);
cv::GMat vga = cv::gapi::resize(in, cv::Size(), 0.5, 0.5);
cv::GMat blurred = cv::gapi::blur(gray, cv::Size(5,5));
cv::GMat edges = cv::gapi::Canny(blurred, 32, 128, 3);
cv::GMat b,g,r;
std::tie(b,g,r) = cv::gapi::split3(vga);
cv::GMat out = cv::gapi::merge3(b, g | edges, r);
cv::GComputation ac(in, out);
cv::Mat input_frame;
cv::Mat output_frame;
ac.apply(input_frame, output_frame);
cv::imshow("output", output_frame);
} while ( && cv::waitKey(30) < 0);
return 0;
GComputation class represents a captured computation graph. GComputation objects form boundaries for ...
Definition gcomputation.hpp:121
GMat class represents image or tensor data in the graph.
Definition gmat.hpp:68
n-dimensional dense array class
Definition mat.hpp:812
Template class for specifying the size of an image or rectangle.
Definition types.hpp:335
Class for video capturing from video files, image sequences or cameras.
Definition videoio.hpp:731
virtual bool read(OutputArray image)
Grabs, decodes and returns the next video frame.
virtual bool open(const String &filename, int apiPreference=CAP_ANY)
Opens a video file or a capturing device or an IP video stream for video capturing.
virtual bool isOpened() const
Returns true if video capturing has been initialized already.
#define CV_Assert(expr)
Checks a condition at runtime and throws exception if it fails.
Definition base.hpp:342
GMat BGR2Gray(const GMat &src)
Converts an image from BGR color space to gray-scaled.
GMat Canny(const GMat &image, double threshold1, double threshold2, int apertureSize=3, bool L2gradient=false)
Finds edges in an image using the Canny algorithm.
GMat blur(const GMat &src, const Size &ksize, const Point &anchor=Point(-1,-1), int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
Blurs an image using the normalized box filter.
std::tuple< GMat, GMat, GMat > split3(const GMat &src)
Divides a 3-channel matrix into 3 single-channel matrices.
GMat resize(const GMat &src, const Size &dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR)
Resizes an image.
GMat merge3(const GMat &src1, const GMat &src2, const GMat &src3)
Creates one 3-channel matrix out of 3 single-channel ones.
void imshow(const String &winname, InputArray mat)
Displays an image in the specified window.
int waitKey(int delay=0)
Waits for a pressed key.
int main(int argc, char *argv[])
Definition highgui_qt.cpp:3

G-API is a separate OpenCV module so its header files have to be included explicitly. The first four lines of main() create and initialize OpenCV's standard video capture object, which fetches video frames from either an attached camera or a specified file.

G-API pipeline is constructed next. In fact, it is a series of G-API operation calls on cv::GMat data. The important aspect of G-API is that this code block is just a declaration of actions, but not the actions themselves. No processing happens at this point, G-API only tracks which operations form pipeline and how it is connected. G-API Data objects (here it is cv::GMat) are used to connect operations each other. in is an empty cv::GMat signalling that it is a beginning of computation.

After G-API code is written, it is captured into a call graph with instantiation of cv::GComputation object. This object takes input/output data references (in this example, in and out cv::GMat objects, respectively) as parameters and reconstructs the call graph based on all the data flow between in and out.

cv::GComputation is a thin object in sense that it just captures which operations form up a computation. However, it can be used to execute computations – in the following processing loop, every captured frame (a cv::Mat input_frame) is passed to cv::GComputation::apply().

Example pipeline running on sample video 'vtest.avi'

cv::GComputation::apply() is a polimorphic method which accepts a variadic number of arguments. Since this computation is defined on one input, one output, a special overload of cv::GComputation::apply() is used to pass input data and get output data.

Internally, cv::GComputation::apply() compiles the captured graph for the given input parameters and executes the compiled graph on data immediately.

There is a number important concepts can be outlines with this example:

  • Graph declaration and graph execution are distinct steps;
  • Graph is built implicitly from a sequence of G-API expressions;
  • G-API supports function-like calls – e.g. cv::gapi::resize(), and operators, e.g operator|() which is used to compute bitwise OR;
  • G-API syntax aims to look pure: every operation call within a graph yields a new result, thus forming a directed acyclic graph (DAG);
  • Graph declaration is not bound to any data – real data objects (cv::Mat) come into picture after the graph is already declared.

See tutorials and porting examples to learn more on various G-API features and concepts.