Added an interactive explorer, now as TUI and a jupyter mode

README.md

@@ -21,6 +21,13 @@ The package is available on PyPI and can be installed using pip:
 ```sh
 pip install fdsreader
 ```
+
+The Jupyter [explorer](#explorer) needs a plotting stack, which is an optional extra:
+```sh
+pip install "fdsreader[notebook]"
+```
+Its command line counterpart needs nothing beyond numpy and is always installed.
+
 _FDS Version 6.7.5 and above are fully supported. Versions below 6.7.5 might work, but are not guaranteed to work._
 
 ## Usage example
@@ -60,6 +67,116 @@ fds.settings.DEBUG = True
 Beware that not all attributes and methods are covered in this diagram. For a complete
 documentation of all classes check the API Documentation below.
 
+## Explorer
+
+`fdsreader.explorer` looks at a simulation without writing plotting code for it: a time
+bar driving a 2D slice, and any number of device or HRR quantities plotted against time.
+In Jupyter that is an interactive widget; in a terminal you can either explore it
+interactively or draw a single view and exit.
+
+### In Jupyter
+
+```python
+from fdsreader.explorer import explore
+
+explorer = explore()
+```
+
+That renders the whole interface — a directory browser, the time bar, the slice on the
+left and the curves on the right. Browse to a case and press *Load simulation*.
+
+```python
+explore("./sample_data")            # skip the browser and load this case
+explore(start_dir="/data/cases")    # open the browser somewhere specific
+explore(interactive_canvas=False)   # static images instead of ipympl canvases
+explore(caching=True)               # allow the .pickle cache (writable data only)
+```
+
+`explore()` returns the explorer, so the simulation and the current selection stay
+available in later cells:
+
+```python
+sim = explorer.sim
+explorer.current_time               # where the time bar is, in seconds
+explorer.selection                  # the curves currently ticked
+explorer.field.frame(400)           # the slice on screen, at time step 400
+```
+
+`ipympl` is optional; with it each plot gains a toolbar to zoom, pan and save. If the
+plots come up as `Failed to load model class 'MPLCanvasModel'`, its browser-side
+extension is not loading — pass `interactive_canvas=False`.
+
+### In a terminal
+
+The command line front end needs nothing but numpy, so it works over SSH on a machine
+with no plotting stack and no browser.
+
+`-i` opens a full-screen interactive view, where the slice and the curves are chosen from
+lists rather than named on the command line:
+
+```sh
+fdsreader-explorer-cli ./sample_data -i
+```
+
+| key | |
+|---|---|
+| `←` `→` or `h` `l` | step through time |
+| `page up` / `page down` | ten steps |
+| `home` / `end` | first / last step |
+| `space` | play, pause |
+| `+` `-` | play speed |
+| `f` | pick the slice from a list |
+| `c` | pick the curves from a list (`space` ticks, `enter` accepts) |
+| `[` `]` | previous / next slice |
+| `g` / `s` | colour scale over the whole run / this step |
+| `?` | help |
+| `q` | quit |
+
+Without `-i` it draws one view and exits, which is what you want in a script:
+
+```sh
+fdsreader-explorer-cli ./sample_data                        # what is in it
+fdsreader-explorer-cli ./sample_data --list                 # slices and curves by name
+fdsreader-explorer-cli ./sample_data --slice 0 --time 4.4   # draw a slice
+fdsreader-explorer-cli ./sample_data --curve TC_1 --curve HRR
+fdsreader-explorer-cli ./sample_data --json                 # for scripting
+```
+
+```
+TEMPERATURE [C] — x = 0 m  #0   ·   t = 4.401 s (step 630 of 749)
+
+  10.00 |                  
+        |                  
+   8.82 |                  
+        |                  
+        |                  
+        |          ...     
+        |        .....     
+   5.88 |       .....      
+        |      ...:...     
+        |       .....      
+        |        ....      
+        |        ...       
+   2.94 |       .:..       
+        |       -.         
+        |       -:-.       
+        |       .-*:       
+        |        +%+.      
+   0.00 |        +#:       
+        +------------------
+         -2.5           2.5   y [m]
+         scale 20 … 1412   ramp ' .:-=+*#%@'   grid 18x18
+```
+
+`--save FILE` writes the current view as an image or an animation instead
+(`.png`/`.pdf`/`.svg`/`.gif`/`.mp4`, needs matplotlib).
+
+The interactive view uses `curses`, which is in the standard library everywhere except
+Windows; there, `pip install windows-curses` provides it.
+
+Slices are read one time step at a time, so stepping through a long run costs a few
+hundred kilobytes rather than loading the whole series into memory.
+
 ## API Documentation
 [https://fdsreader.readthedocs.io](https://fdsreader.readthedocs.io)
 

docs/conf.py

@@ -37,6 +37,10 @@
 # ones.
 extensions = ["sphinx.ext.autodoc", "sphinx.ext.viewcode", "autodocsumm"]
 
+# fdsreader.explorer's Jupyter front end needs matplotlib and ipywidgets, which are an
+# optional extra and are not installed for a docs build.
+autodoc_mock_imports = ["matplotlib", "ipywidgets", "ipympl", "IPython"]
+
 autoclass_content = "both"
 
 # List of patterns, relative to source directory, that match files and

docs/explorer.rst

@@ -0,0 +1,61 @@
+Explorer
+________
+
+Front ends for looking at a simulation: an interactive widget for Jupyter, and a terminal
+application that either explores it interactively (``-i``) or draws one view and exits.
+The core is importable with nothing but numpy; only the Jupyter front end needs
+``pip install "fdsreader[notebook]"``.
+
+.. automodule:: fdsreader.explorer
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.data
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.fields
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.state
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.plots
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.render
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.notebook
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.tui
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:
+
+.. automodule:: fdsreader.explorer.cli
+   :autosummary:
+   :members:
+   :undoc-members:
+   :noindex:

docs/index.rst

@@ -33,6 +33,7 @@ Source code, issue tracker and releases are hosted on
    fds_classes
    utils
    export
+   explorer
 
 .. include::  simulation.rst
 .. include::  slcf.rst
@@ -48,3 +49,4 @@ Source code, issue tracker and releases are hosted on
 .. include::  fds_classes.rst
 .. include::  utils.rst
 .. include::  export.rst
+.. include::  explorer.rst

fdsreader/explorer/__init__.py

@@ -0,0 +1,103 @@
+"""Front ends for looking at an FDS simulation.
+
+Three of them share one core:
+
+* :mod:`~fdsreader.explorer.notebook` -- widgets for Jupyter, ``explore()``
+* :mod:`~fdsreader.explorer.cli` -- ``fdsreader-explorer-cli``, which draws one view
+  in a terminal and exits, or with ``-i`` hands over to
+  :mod:`~fdsreader.explorer.tui` for a full-screen interactive view
+* a desktop front end may follow; it would sit beside these two
+
+The shared parts are :mod:`~fdsreader.explorer.data` (reading devices, HRR and slices,
+numpy only), :mod:`~fdsreader.explorer.plots` (matplotlib) and
+:mod:`~fdsreader.explorer.render` (characters in a terminal).
+
+Importing this package pulls in nothing beyond numpy. The names that need matplotlib or
+ipywidgets are resolved on first use, so::
+
+    from fdsreader.explorer.cli import main        # numpy only
+    from fdsreader.explorer import explore         # needs the notebook extras
+"""
+
+from .data import (
+    axis_label as axis_label,
+)
+from .data import (
+    build_series as build_series,
+)
+from .data import (
+    color_limits as color_limits,
+)
+from .data import (
+    device_label as device_label,
+)
+from .data import (
+    device_time as device_time,
+)
+from .data import (
+    hrr_units as hrr_units,
+)
+from .data import (
+    list_devices as list_devices,
+)
+from .data import (
+    load_device_data as load_device_data,
+)
+from .data import (
+    prepare_slice as prepare_slice,
+)
+from .data import (
+    quantity_of as quantity_of,
+)
+from .data import (
+    slice_label as slice_label,
+)
+from .data import (
+    unit_of as unit_of,
+)
+
+#: Names that live in a module with heavier requirements, resolved on first access.
+_LAZY = {
+    "NotebookExplorer": "notebook",
+    "SimulationBrowser": "notebook",
+    "explore": "notebook",
+    "DIVERGING_CMAPS": "plots",
+    "SEQUENTIAL_CMAPS": "plots",
+    "plot_device": "plots",
+    "plot_series": "plots",
+    "plot_slice": "plots",
+    "Interactive": "tui",
+    "RAMP": "render",
+    "series_lines": "render",
+    "slice_lines": "render",
+}
+
+
+def __getattr__(name):
+    """Import the front-end modules only when something from them is asked for."""
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    return getattr(import_module(f".{module}", __name__), name)
+
+
+def __dir__():
+    return sorted(list(globals()) + list(_LAZY))
+
+
+__all__ = sorted(_LAZY) + [
+    "axis_label",
+    "build_series",
+    "color_limits",
+    "device_label",
+    "device_time",
+    "hrr_units",
+    "list_devices",
+    "load_device_data",
+    "prepare_slice",
+    "quantity_of",
+    "slice_label",
+    "unit_of",
+]

fdsreader/explorer/__main__.py

@@ -0,0 +1,5 @@
+"""Run the command line front end with ``python -m fdsreader.explorer``."""
+
+from .cli import main
+
+raise SystemExit(main())