Merge branch 'master' of https://github.com/20tab/UnrealEnginePython

Author: Roberto De Ioris

tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython.md

@@ -20,14 +20,52 @@ We will use the third person template
 
 ## Installing the Python plugin
 
+Ensure your project/editor has been closed.
+
+Download the most recent embedded binary release from here: https://github.com/20tab/UnrealEnginePython/releases
+
+You can use a non-embedded version if you already have python in your system and you are confident with it. The only difference in the tutorial is in where the matplotlib will be installed. For embedded version, the installation will happen in the plugin directory itself. For non-embedded it will be in the python system path. Obviously if your system python installation already includes matplotlib, you can simply skip the related paragraph below.
+
+>Note: on Linux and Mac system, you will use the system installation (no embedded distributions are provided) or directly the source one. The rest of the tutorial will be platform independent.
+
+Create a Plugins/ directory in your project and unzip the plugin archive into it.
+
+Re-start your project and in the Edit/Plugins menu you will be able to enable the python plugin:
+
 ![Plugin Installation](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/enable_plugin.png)
 
 ## pip-installing matplotlib
 
+If you installed the embedded distribution, just move to the Plugins/UnrealEnginePython/Binaries/Win64 directory in your terminal, and run:
+
+```sh
+./python.exe -m pip install matplotlib
+```
+
 ![pip install matplotlib](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/pip_install.png)
 
+If you are using a system python installation (or you are on Linux/Mac) just run:
+
+```sh
+pip3 install matplotlib
+```
+
+or (based on your config)
+
+```sh
+pip install matplotlib
+```
+
 ## Testing matplotlib in Unreal Engine: generating a graph-texture
 
+Time to check if all is working well.
+
+We will start by generating a texture asset. The content of this texture will be generated by matplotlib.
+
+You can use the included python editor to edit your scripts (it is under Wndow/Python Editor), or your favourite one SsublimeText, Vim, PyCharm...) just ensure scripts are under the Content/Scripts directory of your project.
+
+The steps are generating a texture in memory, plotting the graph, transferring the graph data into texture memory, save it as an asset and opening the related editor:
+
 ```python
 import unreal_engine as ue
 # EPixelFormat defines the various pixel formats for a texture/image, we will use RGBA with 8bit per channel
@@ -71,6 +109,9 @@ ue.open_editor_for_asset(texture)
 
 ![Texture Created](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/texture_created.png)
 
+
+if you ended up with the texture editor opened on your new graph, you are ready for the next steps
+
 ## Our project: Plotting a Pie chart tracking overlap events
 
 Our objective is to have a special blueprint in our level exposing 3 cube in 3 different colors.
@@ -95,7 +136,17 @@ We need 4 materials and 1 material instance for the project:
 
 ### The "pie chart carpet" blueprint
 
+The first blueprint we are about to create, is the 'carpet' (we call it Graph_Blueprint)
+
+![Graph Blueprint](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/graph_blueprint.png)
 
+As you can see it is really simple:
+
+* add a StaticMeshComponent (as root if you want) with a plane as the mesh and the material instance you created before
+* add a Python component with the module as 'plotter' and the class as 'PlotComponent' (this is where the matplotlib part will be)
+* add an event dispatcher called 'OnGraphDataUpdated' (this will be triggered whenever the character steps over a cube)
+
+You can now create (again into Content/Scripts) the plotter.py python script
 
 ```python
 import unreal_engine as ue
@@ -133,8 +184,28 @@ class PlotComponent:
         self.texture.texture_set_data(self.fig.canvas.buffer_rgba())
 ```
 
+The only relevant part is the update_graph function that is triggered by the 'OnGraphDataUpdated' event dispatcher.
+
+This function receives as the 'platform' argument the Actor triggering the event. This Actor (that we will create in the next phase), expose the counters of the overlapping cubes. We use that values to re-generate our pie chart and uploading it into texture memory whenever the event is triggered 
+
 ### The "Plotter Platforms"
 
+The 'PlotterPlatforms' blueprint, implements the actor containing the 3 cubes and manages the overlapping events as well as incrementing the 3 counters.
+
+Let's start with the viewport, you need to add 3 static meshes, each with a cube and the related solid-color material we created earlier:
+
+![PlotterPlatforms Blueprint Viewport](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/platforms_viewport.png)
+
+then we define a blueprint function 'NotifyPlotter', that will trigger the event dispatcher on the Graph_Blueprint (our carpet):
+
+![PlotterPlatforms Blueprint Notify Plotter](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/platforms_notify_plotter.png)
+
+finally we have the Event Graph, here we simply increment the related counter variables and call the 'NotifyPlotter' function:
+
+![PlotterPlatforms Blueprint Event Graph](https://github.com/20tab/UnrealEnginePython/blob/master/tutorials/PlottingGraphsWithMatplotlibAndUnrealEnginePython_Assets/platforms_event_graph.png)
+
+Ensure to add the 3 Integer variables (check the lower-left side of the screenshots) for the counters !
+
 ### Playing it
 
 ### Writing a simple unit test