From 7d032d02c9ea45fa605eb222871fb9d39e87080d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20M=C3=B6bius?= <moebius@cs.rwth-aachen.de>
Date: Tue, 26 Feb 2019 11:04:47 +0100
Subject: [PATCH] Initial documentation for python interface

---
 .../.python-scripting.docu.kate-swp           | Bin 123 -> 0 bytes
 .../DeveloperHelpSources/Interfaces.docu      |   8 ++++
 .../DeveloperHelpSources/mainpage.docu        |   2 +-
 .../python-scripting.docu                     |  14 +++++-
 PythonInterpreter/PythonTypeConversions.hh    |  45 ++++++++++++++++--
 5 files changed, 61 insertions(+), 8 deletions(-)
 delete mode 100644 Documentation/DeveloperHelpSources/.python-scripting.docu.kate-swp

diff --git a/Documentation/DeveloperHelpSources/.python-scripting.docu.kate-swp b/Documentation/DeveloperHelpSources/.python-scripting.docu.kate-swp
deleted file mode 100644
index 65acf55b70fbf351a856cb73867296be20871f9a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 123
zcmZQzU=Z?7EJ;-eE>A2_aLdd|RWQ;sU|?VniP~~u`hWe8VFr(9Jx`uh9r)m<tVeJ-
oP=*_b8C-)sfg}%z2?Q((K;Rl21Z2X6P*pGjrC~Z4fy#h<09rv7z5oCK

diff --git a/Documentation/DeveloperHelpSources/Interfaces.docu b/Documentation/DeveloperHelpSources/Interfaces.docu
index c9d331df..4557f0e6 100644
--- a/Documentation/DeveloperHelpSources/Interfaces.docu
+++ b/Documentation/DeveloperHelpSources/Interfaces.docu
@@ -207,6 +207,13 @@ This page shows interfaces for other operations.
 Interface to call functions across plugins ( \ref RPCInterfacePage  )
 \n
 
+\subpage pythonInterfacePage
+\n
+\image html ScriptInterface.png
+\n
+For plugins which provide python scriptable functions ( \ref pythonInterfacePage  )
+\n
+
 \subpage scriptInterfacePage
 \n
 \image html ScriptInterface.png
@@ -214,6 +221,7 @@ Interface to call functions across plugins ( \ref RPCInterfacePage  )
 For plugins which provide scriptable functions ( \ref scriptInterfacePage  )
 \n
 
+
 \subpage pluginConnectionInterfacePage
 \n
 \image html PluginConnectionInterface.png
diff --git a/Documentation/DeveloperHelpSources/mainpage.docu b/Documentation/DeveloperHelpSources/mainpage.docu
index f141f25f..d3c3cad2 100644
--- a/Documentation/DeveloperHelpSources/mainpage.docu
+++ b/Documentation/DeveloperHelpSources/mainpage.docu
@@ -21,7 +21,7 @@
  * - \subpage dataFlow "Dataflow"
  * - \subpage options "Command line options and config files"
  * - \subpage scripting
- * - \subpage python_scripting "OpenFlipper Scripting with python"
+ * - \subpage python_scripting
  *
  * \subpage misc
  * - \ref changelog
diff --git a/Documentation/DeveloperHelpSources/python-scripting.docu b/Documentation/DeveloperHelpSources/python-scripting.docu
index 5ab4d097..8223d1a6 100644
--- a/Documentation/DeveloperHelpSources/python-scripting.docu
+++ b/Documentation/DeveloperHelpSources/python-scripting.docu
@@ -1,5 +1,5 @@
 /*!
-\page python-scripting OpenFlipper Python Scripting and Batch Mode
+\page python_scripting OpenFlipper Python Scripting and Batch Mode
 
   \section python_scripting_batch_mode OpenFlipper Batch mode with python
     OpenFlipper can be started in batch mode without a graphical user interface by providing "-b" 
@@ -10,5 +10,15 @@
     or graphical functionality will be loaded. You can see on the command line (when "-c" is given),
     which plugins are activated and which are skipped in batch mode.
 
-
+  
+    \section python_scripting_datattypes DataTypes
+      \subsection  python_scripting_matrixtype Matrix4x4 data type
+        The Matrix4x4T type used in the C++ code is mapped from python. Details can be found here:
+        \subpage python_scripting_matrix4x4_type
+  
+      \subsection  python_scripting_vectortype 3 Dimensional vector type
+        The Vector type used in the C++ code is mapped from python. Details can be found here:
+        \subpage python_scripting_vector_type
+  
+  
  */
diff --git a/PythonInterpreter/PythonTypeConversions.hh b/PythonInterpreter/PythonTypeConversions.hh
index 1136630a..2a6e121a 100644
--- a/PythonInterpreter/PythonTypeConversions.hh
+++ b/PythonInterpreter/PythonTypeConversions.hh
@@ -96,7 +96,23 @@ namespace pybind11 { namespace detail {
     };
 }} // namespace pybind11::detail
 
-
+/** \page python_scripting_vector_type Vector data type used for python scripting
+ *
+ *   The matrix type Vector is mapped to python to handle Vector operations.
+ *
+ *   The integrated conversion can map the C++ Vector type to and from a tuple, a list or a numpy array.
+ *   The preferred choice is the numpy array. Tuple and list have to contain 3 elements. A numpy array
+ *   has to have a dimension of 1, with 3 elements.
+ *
+ *   Creating a matrix in python is the done like in the following example:
+ *   \code
+ *     import numpy as np
+ *
+ *     vector = np.array([1.0,0.0,0.0]);
+ *   \endcode
+ *
+ *   The conversion from C++ to python will always create a numpy array on the python side.
+ */
 namespace pybind11 { namespace detail {
     template <> struct type_caster<Vector> {
     public:
@@ -192,7 +208,24 @@ namespace pybind11 { namespace detail {
     };
 }} // namespace pybind11::detail
 
-
+/** \page python_scripting_matrix4x4_type Matrix4x4 data type used for python scripting
+ *
+ *   The matrix type Matrix4x4 is mapped to python to handle matrix operations.
+ *
+ *   The integrated conversion can map the C++ Matrix4x4 type to and from a tuple, a list or a numpy array.
+ *   The preferred choice is the numpy array. Tuple and list have to contain 16 elements. A numpy array
+ *   has to have a dimension of 2, with 4x4 elements. All data is assumed to be given column major. Therefore
+ *   the first for elements define the first column and so on.
+ *
+ *   Creating a matrix in python is the done like in the following example:
+ *   \code
+ *     import numpy as np
+ *
+ *     matr = np.array( [[1.0,0.0,0.0,0.0],[0.0,1.0,0.0,0.0],[0.0,0.0,1.0,0.0],[0.0,0.0,0.0,1.0]])
+ *   \endcode
+ *
+ *   The conversion from C++ to python will always create a numpy array on the python side.
+ */
 namespace pybind11 { namespace detail {
     template <> struct type_caster<Matrix4x4> {
     public:
@@ -235,7 +268,8 @@ namespace pybind11 { namespace detail {
                                        PyFloat_AsDouble(PyList_GetItem(source,11)),
                                        PyFloat_AsDouble(PyList_GetItem(source,12)),
                                        PyFloat_AsDouble(PyList_GetItem(source,13)),
-                                       PyFloat_AsDouble(PyList_GetItem(source,14))};
+                                       PyFloat_AsDouble(PyList_GetItem(source,14)),
+                                       PyFloat_AsDouble(PyList_GetItem(source,15))};
 
                /* Now convert into a C++ Matrix4x4 */
                value = Matrix4x4(convert);
@@ -257,11 +291,12 @@ namespace pybind11 { namespace detail {
                                        PyFloat_AsDouble(PyTuple_GetItem(source,7)),
                                        PyFloat_AsDouble(PyTuple_GetItem(source,8)),
                                        PyFloat_AsDouble(PyTuple_GetItem(source,9)),
-                                       PyFloat_AsDouble(PyTuple_GetItem(source,0)),
+                                       PyFloat_AsDouble(PyTuple_GetItem(source,10)),
                                        PyFloat_AsDouble(PyTuple_GetItem(source,11)),
                                        PyFloat_AsDouble(PyTuple_GetItem(source,12)),
                                        PyFloat_AsDouble(PyTuple_GetItem(source,13)),
-                                       PyFloat_AsDouble(PyTuple_GetItem(source,14)) };
+                                       PyFloat_AsDouble(PyTuple_GetItem(source,14)),
+                                       PyFloat_AsDouble(PyTuple_GetItem(source,15))};
 
                /* Now convert into a C++ Matrix4x4 */
                value = Matrix4x4(convert);
-- 
GitLab