Merge pull request #157 from navis-org/pygfx2

Improve plotting

.github/workflows/notebooktest-package.yml

@@ -20,16 +20,23 @@ jobs:
         python-version: '3.10'
     - name: Install graphviz
       run: |
-        sudo apt-get install -y graphviz graphviz-dev
+        sudo apt-get update -y -qq
+        sudo apt-get install -y libdbus-1-3 libxkbcommon-x11-0 libxcb-icccm4 \
+          libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
+          libxcb-xinerama0 libxcb-xinput0 graphviz graphviz-dev \
+          libegl1-mesa libgl1-mesa-dri libxcb-xfixes0-dev mesa-vulkan-drivers
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         python -m pip install pathos pygraphviz neuron cloud-volume k3d scikit-image open3d
-        python -m pip install -e .[test-notebook]
+        python -m pip install -e .[test-notebook,all]
     - name: Run notebooks
+      uses: coactions/setup-xvfb@v1
       env:
         NEUPRINT_APPLICATION_CREDENTIALS: ${{ secrets.neuprint }}
         INSECT_BRAIN_DB_USER: ${{ secrets.insect_brain_db_user }}
         INSECT_BRAIN_DB_PASSWORD: ${{ secrets.insect_brain_db_password }}
-      run: |
-        python tests/test_notebooks.py
+      with:
+        run: |
+          export NAVIS_HEADLESS=TRUE
+          python tests/test_notebooks.py

.github/workflows/test-install.yml

@@ -42,6 +42,6 @@ jobs:
         run: |
           pip install --upgrade pip wheel
       - name: Install navis from Github
-        run: pip install git+https://github.com/navis-org/navis@master
+        run: pip install -e .[all]
       - name: Test import
         run: python3 -c "import navis"

.github/workflows/test-package.yml

@@ -11,8 +11,8 @@ jobs:
           - "3.9"
           - "3.10"
           - "3.11"
-          # - "3.12"
-        igraph: ["igraph", "no-igraph"]
+          - "3.12"
+        # igraph: ["igraph", "no-igraph"]
     steps:
       # This cancels any such job that is still runnning
     - name: Cancel Previous Runs
@@ -26,26 +26,27 @@ jobs:
         python-version: ${{ matrix.python-version }}
     - name: Install Linux libraries
       run: |
+        sudo apt-get update -y -qq
         sudo apt-get install -y libdbus-1-3 libxkbcommon-x11-0 libxcb-icccm4 \
           libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \
-          libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0 graphviz graphviz-dev
+          libxcb-xinerama0 libxcb-xinput0 libxcb-xfixes0 graphviz graphviz-dev \
+          mesa-vulkan-drivers
     - name: Install dependencies
       run: |
         pip install --upgrade pip
         pip install zstandard==0.16.0
         pip install numpy
         pip install flybrains --no-deps
         pip install git+https://github.com/siavashk/pycpd@master
-        pip install k3d
         pip install pyarrow
     - name: Install navis
-      run: pip install -e .[dev,vispy-pyqt5,pathos,cloudvolume,fastcore]
-    - run: pip install python-igraph
-      if: ${{ matrix.igraph == 'igraph' }}
+      run: pip install -e .[dev,all]
+    # - run: pip install python-igraph
+    #   if: ${{ matrix.igraph == 'igraph' }}
     - name: Report dependency versions
       run: pip freeze -r requirements.txt
     - name: Test
-      uses: GabrielBB/xvfb-action@v1
+      uses: coactions/setup-xvfb@v1
       with:
         run: |
           export NAVIS_HEADLESS=TRUE

docs/conf.py

@@ -153,6 +153,9 @@ def remove_pbars(filepath):
 plot_html_show_formats = False
 plot_html_show_source_link = False
 
+napoleon_use_param = False
+napoleon_custom_sections = [('Figure parameters', 'params_style'), ('Object parameters', 'params_style')]
+
 # generate autosummary pages
 autosummary_generate = True
 autoclass_content = 'both'

docs/source/install.rst

@@ -16,8 +16,7 @@ you have already installed Python and its package manager ``pip``.
 From pip, with "batteries included"
 -----------------------------------
 
-Install navis including optional dependencies plus a GUI backend for the
-terminal (see bottom of the page for details):
+Install navis including optional dependencies plus a GUI backend for plotting (see bottom of the page for details):
 
 ::
 
@@ -67,14 +66,19 @@ These extras can be installed directly, or along with navis with
 The user-facing extras, the dependencies they install,
 and how to install those dependencies directly, are below.
 
+Performance
+~~~~~~~~~~~
+
+Dependencies that aren't strictly necessary but will speed up certain operations:
+
 .. _fastcore:
 
 ``fastcore``: `navis-fastcore <https://github.com/schlegelp/fastcore-rs>`_
   ``navis-fastcore`` re-implements a bunch of low-level functions in Rust
   and wraps them in Python. ``navis`` will use ``fastcore`` under-the-hood
-  if it is available. This is a highly recommended extra as it will
-  speed up certain operations such as geodesic distances, Strahler Index
-  or pruning by several orders of magnitude.
+  if it is available. This is a highly recommended extra as it can
+  speed up operations such as geodesic distances, Strahler Index, pruning
+  and other downstream functions by several orders of magnitude.
 
   ::
 
@@ -85,9 +89,7 @@ and how to install those dependencies directly, are below.
 
 ``kdtree``: `pykdtree <https://github.com/storpipfugl/pykdtree>`_
   Faster than scipy's cKDTree implementation. If available, will be used to
-  speed up e.g. NBLAST. **Important**: on Linux I found that I need to set
-  a ``OMP_NUM_THREADS=4`` environment variable (see also ``pykdtree`` docs).
-  Otherwise it's actually slower than scipy's KDTree.
+  speed up e.g. NBLAST.
 
   ::
 
@@ -103,47 +105,66 @@ and how to install those dependencies directly, are below.
 
     pip3 install pathos
 
-.. _pyoc:
+.. _hash:
 
-``octree``: `PyOctree <https://pypi.python.org/pypi/pyoctree/>`_
-  Slower alternative to ncollpyde.
+  ``hash``: `xxhash <https://cyan4973.github.io/xxHash/>`_
+  For speeding up some lookup tables.
 
-  ::
+    ::
 
-    pip3 install pyoctree
+      pip3 install xxhash
 
-.. _rpy:
+.. _meshes:
 
-``r``: `Rpy2 <https://rpy2.readthedocs.io/en/version_2.8.x/overview.html#installation>`_ (``rpy2``)
-  Provides interface with R. This allows you to use e.g. the
-  `natverse <https://natverse.org>`_  R packages. Note that
-  this package is not installed automatically as it would fail
-  if R is not already installed on the system. You have to
-  install Rpy2 manually!
+``meshes``: `open3d <https://pypi.org/project/open3d/>`_, `pyfqmr <https://github.com/Kramer84/pyfqmr-Fast-quadric-Mesh-Reduction>`_
+  Assorted functionality associated with meshes. ``pyfqmr`` in particular is
+  highly recommended if you want to downsample meshes.
 
   ::
 
-    pip3 install rpy2
+    pip3 install open3d pyfqmr
 
-.. _shapely:
+.. _viz_install:
 
-``shapely``: `Shapely <https://shapely.readthedocs.io/en/latest/>`_ (``shapely``)
-  This is used to get 2D outlines of navis.Volumes.
+Visualization
+~~~~~~~~~~~~~
+
+``navis`` supports various different backends for 2D and 3D visualization. For 2D visualizations we
+use ``matplotlib`` by default which is installed automatically. For 3D visualizations, you can use
+``octarine3d``, ``vispy``, ``plotly`` or ``k3d`` backends.
+
+.. _octarine:
+
+``octarine3d``: `octarine3d <https://schlegelp.github.io/octarine/>`_ (``octarine3d``)
+  For 3D visualisation in terminal and Jupyter notebooks.
+
+  Octarine3d is a modern, high-performance, WGPU-based viewer for 3D visualisation of neurons.
+  It is the default 3D viewer for navis. It is recommended to install it as it is the fastest, most
+  feature-rich viewer available. By default, ``navis[all]`` will install ``octarine3d`` with
+  standard windows manager ``pyside6`` and Jupyter notebook manager ``jupyter_rfb``. It will also
+  install the ``navis-octarine-plugin`` which is required to use octarine3d as a viewer for navis.
+  This is equivalent to the following command:
 
   ::
 
-    pip3 install shapely
+    pip3 install octarine3d[all] octarine-navis-plugin
+
+  Please see ``octarine3`` `installataion instructions <https://schlegelp.github.io/octarine/install/>`_
+  for information on how to choose a different backend.
+
+  Note: older systems (pre ~2018) might not support WGPU, in which case you might want to fall back
+  to the ``vispy`` backend.
 
 .. _vispy:
 
 ``vispy-*`` backends: `vispy <https://vispy.org>`_
-  For 3D visualisation.
+  For 3D visualisation in terminal and Jupyter notebooks.
 
-  Vispy provides a high-performance viewer for 3D visualisation of neurons.
-  Vispy itself has a choice of backends: the one which works for you will depend on
+  Vispy provides a high-performance, OpenGL-based viewer for 3D data visualisation.
+  Vispy itself has a choice of window managers: the one which works for you will depend on
   your operating system, hardware, other installed packages, and how you're using navis.
-  The default, supplied with navis' ``vispy-default`` extra, is pyside6;
-  this works best when called from an ``ipython`` console.
+  The default, supplied with navis' ``vispy-default`` extra, is ``pyside6`` (for use from the console)
+  and ``jupyter_rfb`` (for use in Jupyter notebooks).
   Each of vispy's backends, listed
   `here <https://vispy.org/installation.html#backend-requirements>`_,
   can be installed through vispy and its extras, or navis' `vispy-*` extras.
@@ -154,10 +175,51 @@ and how to install those dependencies directly, are below.
     # or
     pip3 install vispy[pyqt5]
 
-.. _hash:
 
-``hash``: `xxhash <https://cyan4973.github.io/xxHash/>`_
-  For speeding up some lookup tables.
+.. _plotly:
+
+``plotly``: `plotly <https://plotly.com/python/>`_
+  For 3D visualisation in Jupyter notebooks.
+
+  ::
+
+    pip3 install plotly
+
+.. _k3d:
+
+``k3d``: `k3d <https://k3d-jupyter.org/>`_
+  For 3D visualisation in Jupyter notebooks.
+
+  ::
+
+    pip3 install k3d
+
+
+Miscellaneous
+~~~~~~~~~~~~~
+
+.. _rpy:
+
+``r``: `Rpy2 <https://rpy2.readthedocs.io/en/version_2.8.x/overview.html#installation>`_ (``rpy2``)
+  Provides interface with R. This allows you to use e.g. the
+  `natverse <https://natverse.org>`_ R packages. Note that
+  this package is not installed automatically as it would fail
+  if R is not already installed on the system. You have to
+  install Rpy2 manually!
+
+  ::
+
+    pip3 install rpy2
+
+.. _shapely:
+
+``shapely``: `Shapely <https://shapely.readthedocs.io/en/latest/>`_ (``shapely``)
+  This is used to get 2D outlines of :class:`navis.Volumes` when plotting in 2D
+  with ``volume_outlines=True``.
+
+  ::
+
+    pip3 install shapely
 
 .. _flybrains:
 
@@ -170,8 +232,3 @@ and how to install those dependencies directly, are below.
   Reading and writing images, meshes, and skeletons in Neuroglancer precomputed format.
   This is required required for e.g. the MICrONs interface.
 
-.. _meshes:
-
-``meshes``: `open3d <https://pypi.org/project/open3d/>`_, `pyfqmr <https://github.com/Kramer84/pyfqmr-Fast-quadric-Mesh-Reduction>`_
-  Assorted functionality associated with meshes. ``pyfqmr`` in particular is
-  highly recommended if you want to downsample meshes.