Update web interface documentation, add 'Help' link

README.md

@@ -5,7 +5,7 @@
 [![PyPI license](https://img.shields.io/pypi/l/phiflow.svg)](https://pypi.org/project/phiflow/)
 [![image](https://www.tensorflow.org/images/colab_logo_32px.png) Run in Google Colab](https://colab.research.google.com/drive/1S21OY8hzh1oZK2wQyL3BNXvSlrMTtRbV#offline=true&sandboxMode=true)
 
-![Gui](documentation/figures/Gui.png)
+![Gui](documentation/figures/WebInterface.png)
 
 Φ<sub>*Flow*</sub> is a research-oriented, open-source fluid simulation toolkit.
 It is written mostly in Python and can use both NumPy and TensorFlow for execution.
@@ -52,7 +52,7 @@ The [simulation overview](documentation/Simulation_Overview.md) explains how to
 
 To learn how specific simulations are implemented, check out the documentation for [Fluids](documentation/Fluid_Simulation.md) or read about [staggered grids](documentation/Staggered_Grids.md) or [pressure solvers](documentation/Pressure_Solvers.md).
 
-[Writing a Φ<sub>*Flow*</sub> Application](documentation/Browser_GUI.md) introduces the high-level classes and explains how to use the Φ<sub>*Flow*</sub> GUI for displaying a simulation.
+[Writing a Φ<sub>*Flow*</sub> Application](documentation/Web_Interface.md) introduces the high-level classes and explains how to use the Φ<sub>*Flow*</sub> GUI for displaying a simulation.
 
 For I/O and data management, see the [data documentation](documentation/Reading_and_Writing_Data.md) or the [scene format specification](documentation/Scene_Format_Specification.md).
 

documentation/Interactive_Training_Apps.md

@@ -1,7 +1,7 @@
 # Interactive training or optimization
 
 This document assumes you have some basic knowledge of `Apps` and how they interact with the GUI.
-If not, checkout the [documentation](Browser_GUI.md).
+If not, checkout the [documentation](Web_Interface.md).
 
 If the purpose of your application is to train a TensorFlow model, your main application class should extend [TFApp](../phi/tf/app.py) which in turn extends `App`.
 This has a couple of benefits:

documentation/Simulation_Overview.md

@@ -43,7 +43,7 @@ Accessing any property of a simulation reference (such as `fluid`) will now retu
 
 To use the browser-based GUI that comes with Φ<sub>*Flow*</sub>, we need to wrap our simulation code with a
 `App`.
-How to use `App`s is documented [here](Browser_GUI.md).
+How to use `App`s is documented [here](Web_Interface.md).
 
 The following code is taken from [the simpleplume example](../demos/simpleplume.py).
 

documentation/Browser_GUI.md → documentation/Web_Interface.md

@@ -1,30 +1,54 @@
-# Φ<sub>*Flow*</sub> Browser GUI
+# Φ<sub>*Flow*</sub> Web Interface
 
-![Gui](./figures/Gui.png)
+![Gui](figures/WebInterface.png)
 
-Φ<sub>*Flow*</sub> contains an interactive GUI that can display any kind of two-dimensional or three-dimensional fields. The interface is displayed in the browser and is very easy to set up.
+Φ<sub>*Flow*</sub> contains an interactive web interface that can display 1D, 2D and 3D data.
+The interface is displayed in the browser so it can be used remotely.
 
-The default GUI will display your application in the browser.
-If you intend to use the GUI for interactive training of a TensorFlow model, make sure to read the 
+*Note*:
+If you intend to use the interface for interactive training of a TensorFlow model, make sure to read the 
 [TensorFlow specific section](Interactive_Training_Apps.md) as well. Else, you can simply create a subclass of [App](../phi/app/app.py) as described below.
 
-## Launching the GUI
+## Tabs & Features
 
-The following code defines a custom [App](../phi/app/app.py) and uses it to launch the GUI.
+The web interface consists of multiple tabs (web pages) which can be accessed from the top left.
+
+- **Home** shows the title and description of the app. It allows the user to choose one field to view and to start/pause the app or step a single frame. Additionally all app-specific controls are shown at the bottom.
+- **Side-by-Side** is similar to Home but shows two fields at a time instead of one.
+- **Info** displays additional information about the current session such as file paths and run time.
+- **Log** displays the complete application log.
+- **Φ Board** contains benchmarking functionality. For TensorFlow apps it also allows the user to launch TensorBoard and run the TensorFlow profiler.
+- **Help** refers to this page.
+
+Tips & Tricks:
+
+- You can run a specified number of frames by entering the number in the text box next to the 'Step' button. If you put a '*' before the number, it is multiplied by the app's `stride` value which can be found in the `info` tab.
+
+
+## Launching the Web Interface
+
+The web interface is based on [Dash by Plotly](https://plot.ly/dash/) which uses the popular framework [Flask](https://www.palletsprojects.com/p/flask/).
+
+To launch the web interface, you have to create an instance of [`App`](../phi/app/app.py) and pass it to the `show` method.
+
+While a direct instance of `App` can be used (with `force_show=True`), the preferred way is to create a subclass of `App`.
+The following code snippet shows how to do this and launch the interface.
 
 ```python
 from phi.flow import *
 
-class GuiTest(App):
+class HelloWorld(App):
     def __init__(self):
-        App.__init__(self, 'Hello World!')
+        App.__init__(self)
 
 show()
 ```
 
-When run, the application prints a URL to the console. Enter this URL into a browser to view the GUI.
+When run, the application prints a URL to the console.
+Enter this URL into a browser to view the interface.
+The URL always stays the same, so you can simply refresh the web page when restarting your app.
 
-You should see the _Hello World_ text at the top, followed by two empty diagrams and a bunch of controls. None of the controls will do anything useful at this point so let's focus on the diagrams.
+You should see *Hello World*, the name of our app, at the top, followed by a diagram and the controls. None of the controls will do anything useful at this point so let's focus on the diagram.
 
 A key part of any [App](../phi/app/app.py) is that it exposes a set of fields (NumPy arrays) which can change over time. How these fields are generated and how they evolve is up to the application. They could change as part of an evolving fluid simulation, they could be the predictions of a neural network that is being optimized or they could simply be a sequence read from disc.
 
@@ -58,13 +82,18 @@ Your subclass of [App](../phi/app/app.py) automatically inherits the variable `t
 
 After `step()` finishes, the GUI is updated to reflect the change in the data. Consequently, the channel generators (`numpy,ndarray`'s and `lambda` expressions in the above example) can be called after each step. In practice, however, steps can often be performed at a higher framerate than the GUI update rate.
 
-## Framerate, Sequences and Recording
+## Frame Rate and Refresh Rate
 
-The default app provides control for the display framerate and for running sequences. If `framerate control` is enabled, the corresponding slides control the number of targeted updates per second. I.e., for a setting of 2, the field displays will be updated twice per second. If the computations take more time, or the bandwidth is limited, the update frequency is reduced. The `substeps` field controls how many updates, i.e., `step()` calls should be performed at least before an UI update is triggered.
+The web interface provides a *Refresh rate* control above the field viewer.
+This value describes how often the diagrams in the browser are refreshed.
+It is independent of the frame rate of the app.
 
-In the UI section below the framerate, the run `Run sequence` button performs a chosen number of updates (each with `substeps` iterations), while `Benchmark sequence` additionally measures execution time.
+The frame rate of the app can be set in the constructor, `App.__init__(self, framerate=10)`.
+To allow the user to control the frame rate, set it to `framerate=EditableInt('Framerate', 10, minmax=(1, 30))`.
 
-The Record section controls with registered UI fields are written to disk. The data can either be saved visually as an `Image` and/or as a numpy array with `Data`. The `substeps` setting controls the interval for writing data.
+The `stride` parameter is used to segment frames of the app.
+For machine learning applications, this is equal to the number of steps in one epoch and influences how often validations are performed.
+It has no effect on the interface, except that it is multiplied to the frame count when entering `*` in front of the number into the text box.
 
 ## Custom Controls
 

phi/viz/dash/dash_gui.py

@@ -34,6 +34,8 @@ def setup(self):
                 dcc.Link(u'Φ Board', href='/board'),
                 # ' - ',
                 # dcc.Link('Scripting', href='/scripting'),
+                ' - ',
+                html.A('Help', href='https://github.com/tum-pbs/PhiFlow/blob/master/documentation/Web_Interface.md', target='_blank'),
             ])
         dash_app = self.dash_app = DashApp(self.app, self.config, header_layout)
 
@@ -64,7 +66,9 @@ def setup(self):
                 sbs_fieldnames = [sbs_fieldnames] * 2
         else:
             sbs_fieldnames = self.app.fieldnames
-            if len(sbs_fieldnames) < 2:
+            if len(sbs_fieldnames) == 0:
+                sbs_fieldnames = ['None', 'None']
+            elif len(sbs_fieldnames) < 2:
                 sbs_fieldnames = list(sbs_fieldnames) + ['None']
         layout = html.Div([
             build_view_selection(dash_app),
@@ -128,7 +132,7 @@ def setup(self):
         return self.dash_app.dash
 
     def show(self, caller_is_main):
-        if caller_is_main:
+        if caller_is_main or self.config.get('force_launch', False):
             port = self.config.get('port', 8051)
             print('Starting Dash server on http://localhost:%d/' % port)
             self.dash_app.dash.run_server(debug=True, host='0.0.0.0', port=port, use_reloader=False)

phi/viz/dash/info.py

@@ -2,6 +2,7 @@
 import inspect
 import os
 import datetime
+import subprocess
 import warnings
 from os.path import dirname, exists, join, isfile
 
@@ -56,11 +57,12 @@ def _description_markdown_src(title, subtitle=''):
 
 
 def build_phiflow_info(dashapp):
-    setup_file = join(dirname(dirname(inspect.getfile(phi))), 'setup.py')
+    root_dir = dirname(dirname(inspect.getfile(phi)))
+    setup_file = join(root_dir, 'setup.py')
     version = 'unknown'
     if isfile(setup_file):
         try:
-            version = os.popen('python %s --version' % setup_file).read()
+            version = subprocess.check_output('python %s --version' % setup_file, cwd=os.path.abspath(root_dir))
         except BaseException as exc:
             warnings.warn('Could not get PhiFlow version: %s' % exc)
     return dcc.Markdown(u"""

phi/viz/display.py

@@ -75,7 +75,7 @@ def play(self):
         from .dash.dash_gui import DashGui
         DEFAULT_DISPLAY_CLASS = DashGui
     except ImportError as import_error:
-        warnings.warn('GUI is disabled because Dash could not be imported. To install Dash, run $ pip install dash')
+        warnings.warn('GUI is disabled because of missing dependencies: %s. To install all dependencies, run $ pip install phiflow[gui]' % import_error)
 
 
 AUTORUN = 'autorun' in sys.argv
@@ -111,7 +111,7 @@ def show(app=None, **config):
             display.play()
     # --- Show ---
     if display is None:
-        warnings.warn('show() has no effect because no display is available. To use the Dash GUI, run $ pip install dash')
+        warnings.warn('show() has no effect because no display is available. To use the web interface, run $ pip install phiflow[gui]')
         return app
     else:
         return display.show(called_from_main)  # blocking call