diff --git a/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/UserManual/Manual.dox b/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/UserManual/Manual.dox deleted file mode 100644 index 343ef00178..0000000000 --- a/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/UserManual/Manual.dox +++ /dev/null @@ -1,17 +0,0 @@ -/** -\page org_mitk_example_gui_pythonexample The Python Example - -\imageMacro{icon.png,"Icon of Python Example",2.00} - -\tableofcontents - -\section org_mitk_example_gui_pythonexampleOverview Overview -Describe the features of your awesome plugin here - - -*/ diff --git a/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/UserManual/icon.xpm b/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/UserManual/icon.xpm deleted file mode 100644 index 9057c20bc6..0000000000 --- a/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/UserManual/icon.xpm +++ /dev/null @@ -1,21 +0,0 @@ -/* XPM */ -static const char * icon_xpm[] = { -"16 16 2 1", -" c #FF0000", -". c #000000", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" ", -" "}; diff --git a/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/doxygen/modules.dox b/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/doxygen/modules.dox deleted file mode 100644 index d9018cfdd1..0000000000 --- a/Examples/Plugins/org.mitk.example.gui.pythonexample/documentation/doxygen/modules.dox +++ /dev/null @@ -1,16 +0,0 @@ -/** - \defgroup org_mitk_example_gui_pythonexample org.mitk.example.gui.pythonexample - \ingroup MITKPlugins - - \brief Describe your plugin here. - -*/ - -/** - \defgroup org_mitk_example_gui_pythonexample_internal Internal - \ingroup org_mitk_example_gui_pythonexample - - \brief This subcategory includes the internal classes of the org.mitk.example.gui.pythonexample plugin. Other - plugins must not rely on these classes. They contain implementation details and their interface - may change at any time. We mean it. -*/ diff --git a/Modules/Python/documentation/mitkPython.dox b/Modules/Python/documentation/mitkPython.dox index b25d78554c..e8861b99ec 100644 --- a/Modules/Python/documentation/mitkPython.dox +++ b/Modules/Python/documentation/mitkPython.dox @@ -1,47 +1,135 @@ /** \page mitkPython_Overview Python Module -\section python_sec1 Brief description -The MITK Python Module provides a service class to interactively run python code (passed as C++ strings) and -evaluate the results. Furthermore the service class offers means to convert an MITK Image to an ITK/OpenCV image in their wrapped python environment. -Thus, one can process MITK images with Python Code from the OpenCV and ITK wrapping system. -Furthermore one can convert an mitk::Surface to a vtkPolyData in its Python environment.
-Under the hood, the MITK build system takes care that the wrapping build process for SimpleITK/VTK/OpenCV is correctly initiated and all paths are correctly set within MITK code. -To use the features of the different toolkits make sure they are enabled during the superbuild process. - -\section python_sec2 Build Instructions - -Have a look at \ref python_ssec3 on how to build MITK-Python with Qt5. -The following CMake build options are available: +\section python_sec1 Description +The MITK Python Module provides a service class to interactively run python code and evaluate the results. Furthermore, you can transfer some data structures such as MITK images to your python environment for processing. +Currently, there are two different implementations of the MITK Python Module: The PythonService and the QtPythonService. +The two implementations will be described in the following sections. + +\section python_sec2 The QtPythonService +The QtPythonService is a service implementation which is based on CTK and PythonQt. + +\warning The QtPythonService is the legacy implementation of the Python Module. There might be issues especially regarding multithreading. +The implementation might be deprecated in nearer future. It is therefore recommended to use the \ref python_sec3 unless you need Data Types, that are not yet supported by the PythonService. + +\subsection qtpython_build Build instructions + +To build MITK with the QtPythonService, the following CMake build options have to be enabled: +MITK_USE_Python3 enables the python wrapping in MITK. When the option is activated the build of the additional dependency SimpleITK is also enabled. The default behaviour is to use the python runtime from the system is used. Only Python 3.x is supported. -\subsection python_ssec1 MITK_USE_Python3 -MITK_USE_Python3 enables the python wrapping in MITK. When the option is activated -the build of the additional dependency SimpleITK is also enabled. The default behaviour is to use the python runtime from the system is used. -Only Python 3.x is supported. -The user can also specify it's own runtime by modifying the variables added by the -FindPythonLib.cmake script. Note: A Python runtime with numpy is needed to use the MITK Python wrapping. -When using this options all additional libraries installed in the python runtime will be available within the MITK-Python console. - -\section python_sec3 Suported Data Types -The following data types in MITK are supported in the MITK Python Wrapping: +\subsection qt_data_types Supported Data Types +The following data types in MITK are supported in the QtPythonService wrapping: -\subsection python_ssec4 Image +\subsubsection qtpython_image Image Mitk Images can be transferred to python. The images are copied in-memory and transferred as a numpy array to Python and vice versa. The MITK python wrapping creates a SimpleITK image using the numpy array with the properties of the MITK Image. Two dimensional images can also be transferred as an OpenCV image to python. -\subsection python_ssec5 Surface +\subsubsection qtpython_surface Surface Surfaces within mitk can be transferred as a vtkPolyData Object to Python. The surfaces are fully memory mapped. When changing a python wrapped surface the original object is also modified on the C++ side of MITK. - */ + +\section python_sec3 The PythonService +The PythonService is a service implementation that uses the Python/C API to execute Python Code. Additionally, SWIG is used to wrap some MITK datatypes in python. + +\subsection python_build Build instructions + +To build MITK with the QtPythonService, the following CMake build options have to be enabled: + + +The use of Python is already explained in \ref qtpython_build. The other options are all for wrapping MITK classes in Python classes. + +\subsection python_setup Setup +To get an instance of the PythonService, the following code is necessary: + +\code{.cpp} +us::ModuleContext *context = us::GetModuleContext(); +std::string filter = "(Name=PythonService)"; +auto m_PythonServiceRefs = context->GetServiceReferences(filter); +auto *m_PythonService = dynamic_cast (context->GetService (m_PythonServiceRefs.front())); +\endcode + +\subsection python_usage Usage +In the following sections, some of the key features of the PythonService are described. + +\subsubsection python_executing_code Executing python code +Python code can be executed in two ways: +
    +
  • With the method Execute(const std::string &pythonCommand, int commandType), code can be executed in form of a C++ string. The variable commandType can have the following values: +
      +
    • IPythonService::SINGLE_LINE_COMMAND for single statements +
    • IPythonService::MULTI_LINE_COMMAND for larger code snippets +
    • IPythonService::EVAL_COMMAND for isolated expressions, e.g. calculations. +
    + If no commandType is given, IPythonService::MULTI_LINE_COMMAND is the default. +
  • With the method ExecuteScript(const std::string &pythonScript), whole python scripts can be executed. pythonScript is the path to the script which should be executed. + If this file is located within the MITK sourcecode, the path can be determined by the method FindFile(const char *filename, const char *pathInSourceDir) which is implemented in the class mitk::StandardFileLocations. The following code shows an example of a script to be executed: + \code{.cpp} + std::string pythonFileName = "hello.py"; + std::string fileName = mitk::StandardFileLocations::GetInstance()->FindFile( pythonFileName.c_str(), "Examples/Plugins/org.mitk.example.gui.pythonexample/resources"); + m_PythonService->ExecuteScript(fileName); + \endcode +
+ +\subsubsection python_access_variables Accessing variables +The following methods are available for accessing varaibles: +
    +
  • GetVariableStack() returns all variables from the python context. The variables are returned as a list of the type PythonVariable. This contains for all variables the name, type and value as string format. +
  • DoesVariableExist(const std::string& name) returns a boolean, whether a variable with a given name exists in the current python context. +
  • GetVariable (const std::string& name) returns the value of a python variable with the given name as a string. +
+ +\subsubsection python_transfer_images Transfer Images + +With the PythonService, images can be transferred from C++ to the python context. +\note Currently, MITK images can be transferred and can be used in the python context either as MITK image as well or as SimpleITK image. If you want to use the MITK image data structure in the python context, you need to import pyMITK in your script. + +\subsubsection python_images_mitk_python Transfer images from C++ to python +To transfer images from C++ to python, the following methods are provided: +
    +
  • CopyToPythonAsSimpleItkImage(mitk::Image::Pointer image, const std::string &stdvarName) to transfer a MITK image to python which should be used as SimpleITK image in the python context. +
  • CopyMITKImageToPython(mitk::Image::Pointer &image, const std::string &stdvarName) to transfer a MITK image to python which should be used as MITK image in the python context as well. +
+ +In this methods image defines the image which should be transferred and stdvarName the name of the image variable in the python context. + +\subsubsection python_images_python_mitk Transfer Images from python to C++ +To transfer images from python to C++, the following methods are provided: +
    +
  • CopySimpleItkImageFromPython(const std::string &stdvarName) for transferring a SimpleITK image from the python context to a MITK image in C++. +
  • CopyMITKImageFromPython(const std::string &stdvarName) for transferring a MITK image from the python context to a MITK image in C++. +
+The parameter stdvarName is the variable name of the image in the python context. + +\subsubsection python_multiple_images Transferring multiple images +\note Multiple images can currently only be transferred from the python context to C++ and only, if they are provided as a list of MITK images in the python context. + +Sometimes, multiple images should be transferred from python to C++, e.g. when you have a multilabel segmentation and want to return the result as single images. +If the images are stored in a list, this list can be transferred to C++, where it will be a std::vector of the type mitk::Image::Pointer. +Therefore, the method CopyListOfMITKImagesFromPython(const std::string, &listVarName) exists. listVarName ist the name of the list variable of images in python, that should be transferred. + +\subsection python_observer Inform observer +If a class should be notified as soon as a python command gets executed, the interface PythonCommandObserver has to be implemented. +Within this, only the method CommandExecuted(const std::string& pythonCommand) has to be implemented, which is called as soon as the python service executes a command. +To register the observer, the method AddPythonCommandObserver(PythonCommandObserver* observer) has to be called with the implemented observer class as parameter. +Analogously, the observer can be removed with the method RemovePythonCommandObserver(PythonCommandObserver* observer) + +With the method GetNumberOfObserver(), the number of currently registered observers can be determined. + +*/ \ No newline at end of file