inference-engine/thirdparty/fluid/modules/gapi/doc/00-root.markdown

   1 # Graph API {#gapi}
   2
   3 # Introduction {#gapi_root_intro}
   4
   5 OpenCV Graph API (or G-API) is a new OpenCV module targeted to make
   6 regular image processing fast and portable. These two goals are
   7 achieved by introducing a new graph-based model of execution.
   8
   9 G-API is a special module in OpenCV -- in contrast with the majority
  10 of other main modules, this one acts as a framework rather than some
  11 specific CV algorithm. G-API provides means to define CV operations,
  12 construct graphs (in form of expressions) using it, and finally
  13 implement and run the operations for a particular backend.
  14
  15 @note G-API is a new module and now is in active development. It's API
  16 is volatile at the moment and there may be minor but
  17 compatibility-breaking changes in the future.
  18
  19 # Contents
  20
  21 G-API documentation is organized into the following chapters:
  22
  23 - @subpage gapi_purposes
  24
  25   The motivation behind G-API and its goals.
  26
  27 - @subpage gapi_hld
  28
  29   General overview of G-API architecture and its major internal
  30   components.
  31
  32 - @subpage gapi_kernel_api
  33
  34   Learn how to introduce new operations in G-API and implement it for
  35   various backends.
  36
  37 - @subpage gapi_impl
  38
  39   Low-level implementation details of G-API, for those who want to
  40   contribute.
  41
  42 - API Reference: functions and classes
  43
  44     - @subpage gapi_core
  45
  46       Core G-API operations - arithmetic, boolean, and other matrix
  47       operations;
  48
  49     - @subpage gapi_imgproc
  50
  51       Image processing functions: color space conversions, various
  52       filters, etc.
  53
  54 # API Example {#gapi_example}
  55
  56 A very basic example of G-API pipeline is shown below:
  57
  58 @include modules/gapi/samples/api_example.cpp
  59
  60 <!-- TODO align this code with text using marks and itemized list -->
  61
  62 G-API is a separate OpenCV module so its header files have to be
  63 included explicitly. The first four lines of `main()` create and
  64 initialize OpenCV's standard video capture object, which fetches
  65 video frames from either an attached camera or a specified file.
  66
  67 G-API pipelie is constructed next. In fact, it is a series of G-API
  68 operation calls on cv::GMat data. The important aspect of G-API is
  69 that this code block is just a declaration of actions, but not the
  70 actions themselves. No processing happens at this point, G-API only
  71 tracks which operations form pipeline and how it is connected. G-API
  72 _Data objects_ (here it is cv::GMat) are used to connect operations
  73 each other. `in` is an _empty_ cv::GMat signalling that it is a
  74 beginning of computation.
  75
  76 After G-API code is written, it is captured into a call graph with
  77 instantiation of cv::GComputation object. This object takes
  78 input/output data references (in this example, `in` and `out`
  79 cv::GMat objects, respectively) as parameters and reconstructs the
  80 call graph based on all the data flow between `in` and `out`.
  81
  82 cv::GComputation is a thin object in sense that it just captures which
  83 operations form up a computation. However, it can be used to execute
  84 computations -- in the following processing loop, every captured frame (a
  85 cv::Mat `input_frame`) is passed to cv::GComputation::apply().
  86
  87 ![Example pipeline running on sample video 'vtest.avi'](pics/demo.jpg)
  88
  89 cv::GComputation::apply() is a polimorphic method which accepts a
  90 variadic number of arguments. Since this computation is defined on one
  91 input, one output, a special overload of cv::GComputation::apply() is
  92 used to pass input data and get output data.
  93
  94 Internally, cv::GComputation::apply() compiles the captured graph for
  95 the given input parameters and executes the compiled graph on data
  96 immediately.
  97
  98 There is a number important concepts can be outlines with this examle:
  99 * Graph declaration and graph execution are distinct steps;
 100 * Graph is built implicitly from a sequence of G-API expressions;
 101 * G-API supports function-like calls -- e.g. cv::gapi::resize(), and
 102   operators, e.g operator|() which is used to compute bitwise OR;
 103 * G-API syntax aims to look pure: every operation call within a graph
 104   yields a new result, thus forming a directed acyclic graph (DAG);
 105 * Graph declaration is not bound to any data -- real data objects
 106   (cv::Mat) come into picture after the graph is already declared.
 107
 108 <!-- FIXME: The above operator|() link links to MatExpr not GAPI -->
 109
 110 See [tutorials and porting examples](@ref tutorial_table_of_content_gapi)
 111 to learn more on various G-API features and concepts.
 112
 113 <!-- TODO Add chapter on declaration, compilation, execution -->