Merge pull request opencv#1471 from ozantonkal:master

doc/tutorials/tutorials.rst

@@ -186,6 +186,21 @@ As always, we would be happy to hear your comments and receive your contribution
                     :width:  80pt
                     :alt: gpu icon
 
+*  :ref:`Table-Of-Content-Viz`
+
+   .. tabularcolumns:: m{100pt} m{300pt}
+   .. cssclass:: toctableopencv
+
+   =========== =======================================================
+      |Viz|     These tutorials show how to use Viz module effectively.
+
+   =========== =======================================================
+
+     .. |Viz| image:: images/viz.jpg
+                   :height: 80pt
+                   :width:  80pt
+                   :alt: viz icon
+
 *  :ref:`Table-Of-Content-General`
 
       .. tabularcolumns:: m{100pt} m{300pt}
@@ -221,4 +236,5 @@ As always, we would be happy to hear your comments and receive your contribution
    gpu/table_of_content_gpu/table_of_content_gpu
    bioinspired/table_of_content_bioinspired/table_of_content_bioinspired
    ios/table_of_content_ios/table_of_content_ios
+   viz/table_of_content_viz/table_of_content_viz
    general/table_of_content_general/table_of_content_general

doc/tutorials/viz/creating_widgets/creating_widgets.rst

@@ -0,0 +1,159 @@
+.. _creating_widgets:
+
+Creating Widgets
+****************
+
+Goal
+====
+
+In this tutorial you will learn how to
+
+.. container:: enumeratevisibleitemswithsquare
+
+  * Create your own widgets using WidgetAccessor and VTK.
+  * Show your widget in the visualization window.
+
+Code
+====
+
+You can download the code from :download:`here <../../../../samples/cpp/tutorial_code/viz/creating_widgets.cpp>`.
+
+.. code-block:: cpp
+
+    #include <opencv2/viz.hpp>
+    #include <opencv2/viz/widget_accessor.hpp>
+    #include <iostream>
+
+    #include <vtkPoints.h>
+    #include <vtkTriangle.h>
+    #include <vtkCellArray.h>
+    #include <vtkPolyData.h>
+    #include <vtkPolyDataMapper.h>
+    #include <vtkIdList.h>
+    #include <vtkActor.h>
+    #include <vtkProp.h>
+
+    using namespace cv;
+    using namespace std;
+
+    /**
+     * @class WTriangle
+     * @brief Defining our own 3D Triangle widget
+     */
+    class WTriangle : public viz::Widget3D
+    {
+        public:
+            WTriangle(const Point3f &pt1, const Point3f &pt2, const Point3f &pt3, const viz::Color & color = viz::Color::white());
+    };
+
+    /**
+     * @function WTriangle::WTriangle
+     */
+    WTriangle::WTriangle(const Point3f &pt1, const Point3f &pt2, const Point3f &pt3, const viz::Color & color)
+    {
+        // Create a triangle
+        vtkSmartPointer<vtkPoints> points = vtkSmartPointer<vtkPoints>::New();
+        points->InsertNextPoint(pt1.x, pt1.y, pt1.z);
+        points->InsertNextPoint(pt2.x, pt2.y, pt2.z);
+        points->InsertNextPoint(pt3.x, pt3.y, pt3.z);
+
+        vtkSmartPointer<vtkTriangle> triangle = vtkSmartPointer<vtkTriangle>::New();
+        triangle->GetPointIds()->SetId(0,0);
+        triangle->GetPointIds()->SetId(1,1);
+        triangle->GetPointIds()->SetId(2,2);
+
+        vtkSmartPointer<vtkCellArray> cells = vtkSmartPointer<vtkCellArray>::New();
+        cells->InsertNextCell(triangle);
+
+        // Create a polydata object
+        vtkSmartPointer<vtkPolyData> polyData = vtkSmartPointer<vtkPolyData>::New();
+
+        // Add the geometry and topology to the polydata
+        polyData->SetPoints(points);
+        polyData->SetPolys(cells);
+
+        // Create mapper and actor
+        vtkSmartPointer<vtkPolyDataMapper> mapper = vtkSmartPointer<vtkPolyDataMapper>::New();
+    #if VTK_MAJOR_VERSION <= 5
+        mapper->SetInput(polyData);
+    #else
+        mapper->SetInputData(polyData);
+    #endif
+
+        vtkSmartPointer<vtkActor> actor = vtkSmartPointer<vtkActor>::New();
+        actor->SetMapper(mapper);
+
+        // Store this actor in the widget in order that visualizer can access it
+        viz::WidgetAccessor::setProp(*this, actor);
+
+        // Set the color of the widget. This has to be called after WidgetAccessor.
+        setColor(color);
+    }
+
+    /**
+     * @function main
+     */
+    int main()
+    {
+        /// Create a window
+        viz::Viz3d myWindow("Creating Widgets");
+
+        /// Create a triangle widget
+        WTriangle tw(Point3f(0.0,0.0,0.0), Point3f(1.0,1.0,1.0), Point3f(0.0,1.0,0.0), viz::Color::red());
+
+        /// Show widget in the visualizer window
+        myWindow.showWidget("TRIANGLE", tw);
+
+        /// Start event loop
+        myWindow.spin();
+
+        return 0;
+    }
+
+Explanation
+===========
+
+Here is the general structure of the program:
+
+* Extend Widget3D class to create a new 3D widget.
+
+.. code-block:: cpp
+
+    class WTriangle : public viz::Widget3D
+    {
+        public:
+            WTriangle(const Point3f &pt1, const Point3f &pt2, const Point3f &pt3, const viz::Color & color = viz::Color::white());
+    };
+
+* Assign a VTK actor to the widget.
+
+.. code-block:: cpp
+
+    // Store this actor in the widget in order that visualizer can access it
+    viz::WidgetAccessor::setProp(*this, actor);
+
+* Set color of the widget.
+
+.. code-block:: cpp
+
+    // Set the color of the widget. This has to be called after WidgetAccessor.
+    setColor(color);
+
+* Construct a triangle widget and display it in the window.
+
+.. code-block:: cpp
+
+    /// Create a triangle widget
+    WTriangle tw(Point3f(0.0,0.0,0.0), Point3f(1.0,1.0,1.0), Point3f(0.0,1.0,0.0), viz::Color::red());
+
+    /// Show widget in the visualizer window
+    myWindow.showWidget("TRIANGLE", tw);
+
+Results
+=======
+
+Here is the result of the program.
+
+.. image:: images/red_triangle.png
+    :alt: Creating Widgets
+    :align: center

doc/tutorials/viz/launching_viz/launching_viz.rst

@@ -0,0 +1,118 @@
+.. _launching_viz:
+
+Launching Viz
+*************
+
+Goal
+====
+
+In this tutorial you will learn how to
+
+.. container:: enumeratevisibleitemswithsquare
+
+  * Open a visualization window.
+  * Access a window by its name.
+  * Start event loop.
+  * Start event loop for a given amount of time.
+
+Code
+====
+
+You can download the code from :download:`here <../../../../samples/cpp/tutorial_code/viz/launching_viz.cpp>`.
+
+.. code-block:: cpp
+
+    #include <opencv2/viz.hpp>
+    #include <iostream>
+
+    using namespace cv;
+    using namespace std;
+
+    /**
+    * @function main
+    */
+    int main()
+    {
+        /// Create a window
+        viz::Viz3d myWindow("Viz Demo");
+
+        /// Start event loop
+        myWindow.spin();
+
+        /// Event loop is over when pressed q, Q, e, E
+        cout << "First event loop is over" << endl;
+
+        /// Access window via its name
+        viz::Viz3d sameWindow = viz::get("Viz Demo");
+
+        /// Start event loop
+        sameWindow.spin();
+
+        /// Event loop is over when pressed q, Q, e, E
+        cout << "Second event loop is over" << endl;
+
+        /// Event loop is over when pressed q, Q, e, E
+        /// Start event loop once for 1 millisecond
+        sameWindow.spinOnce(1, true);
+        while(!sameWindow.wasStopped())
+        {
+            /// Interact with window
+
+            /// Event loop for 1 millisecond
+            sameWindow.spinOnce(1, true);
+        }
+
+        /// Once more event loop is stopped
+        cout << "Last event loop is over" << endl;
+        return 0;
+    }
+
+Explanation
+===========
+
+Here is the general structure of the program:
+
+* Create a window.
+
+.. code-block:: cpp
+
+    /// Create a window
+    viz::Viz3d myWindow("Viz Demo");
+
+* Start event loop. This event loop will run until user terminates it by pressing **e**, **E**, **q**, **Q**.
+
+.. code-block:: cpp
+
+    /// Start event loop
+    myWindow.spin();
+
+* Access same window via its name. Since windows are implicitly shared, **sameWindow** is exactly the same with **myWindow**. If the name does not exist, a new window is created.
+
+.. code-block:: cpp
+
+    /// Access window via its name
+    viz::Viz3d sameWindow = viz::get("Viz Demo");
+
+* Start a controlled event loop. Once it starts, **wasStopped** is set to false. Inside the while loop, in each iteration, **spinOnce** is called to prevent event loop from completely stopping. Inside the while loop, user can execute other statements including those which interact with the window.
+
+.. code-block:: cpp
+
+    /// Event loop is over when pressed q, Q, e, E
+    /// Start event loop once for 1 millisecond
+    sameWindow.spinOnce(1, true);
+    while(!sameWindow.wasStopped())
+    {
+        /// Interact with window
+
+        /// Event loop for 1 millisecond
+        sameWindow.spinOnce(1, true);
+    }
+
+Results
+=======
+
+Here is the result of the program.
+
+.. image:: images/window_demo.png
+    :alt: Launching Viz
+    :align: center