Graph Views, Doc Updates and Specialize & Inherit Asset Units (#35)

* Enabled CI matrix with Py-3.9 and 3.11. * Moved `pygraphviz` to the `full` requirements and updated install instructions for Maya-2024 and Houdini-20.0. * Added `specialized` and `inherited` edit contexts for asset units. * `_GeomPrimvarInfo` now retrieves constant primvars from `Gprim` instead of `Imageable` schemas. * Added a `ConnectableAPIViewer` widget. * Added ability to filter edges by arc details on `LayerStackComposition`. * Added a custom `_GraphicsViewport` widget to navigate graphs interactively and to avoid use of `QWebEngineWidgets`. * Added `_SvgPixmapViewport` to avoid use of `QWebEngineWidgets` for `PrimComposition` widget. * Extended USDView prim context menu selection for hierarchy selection and prim introspection. * Updated doc images, links to openusd.org and sphinx theme to use shibuya.
thegrill · Mar 3, 2024 · 756935c · 756935c
1 parent b03675e
commit 756935c
Show file tree

Hide file tree

Showing 46 changed files with 2,146 additions and 411 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -12,8 +12,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: ["3.9"]
+        python-version: ["3.9", "3.11"]
+        include:
+          - python-version: "3.9"
+            install-arguments: ". PySide2 usd-core==22.5 PyOpenGL pygraphviz"
+          - python-version: "3.11"
+            install-arguments: ".[full]"
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
@@ -22,13 +28,19 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - name: Set up Graphviz
         uses: ts-graphviz/setup-graphviz@v1
+      - name: Install Required Libraries
+        # Needed for PySide6 CI only: https://stackoverflow.com/questions/75907862/pyside6-wsl2-importerror-libegl-so-1
+        if: "matrix.python-version == '3.11'"
+        run: |
+          sudo apt-get install -y libegl1
       - name: Install
         run: |
           python -m pip install --upgrade pip
-          python -m pip install pytest pytest-cov
-          python -m pip install ".[full,test]"
+          python -m pip install pytest pytest-cov codecov
+          python -m pip install ${{ matrix.install-arguments }}
       - name: Test
         run: |
           pytest --cov=./ --cov-report xml
+          codecov
       - name: Codecov Report
         uses: codecov/codecov-action@v3
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1 +1,2 @@
 include grill/resources/*/*
+include grill.pth
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -34,18 +34,15 @@
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.doctest',
               'sphinx.ext.intersphinx',
+              'sphinx.ext.inheritance_diagram',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',
-              # 'sphinx.ext.imgmath',
-              # 'sphinx.ext.ifconfig',
               'sphinx.ext.viewcode',
-              # 'sphinx.ext.githubpages',
               'sphinx.ext.graphviz',
-              'm2r2',
+              "myst_parser",
               'sphinx_copybutton',
               'sphinx_toggleprompt',
               'sphinx_togglebutton',
-              'sphinx.ext.inheritance_diagram',
               'sphinx_inline_tabs',
               'hoverxref.extension',
               'sphinx.ext.autosectionlabel',
@@ -96,7 +93,8 @@
 master_doc = 'index'
 
 # General information about the project.
-project = 'grill'
+# project = 'grill'
+project = '👨‍🍳 Cook digital.'
 copyright = f'{datetime.now().year}, The Grill'
 author = 'The Grill'
 
@@ -114,7 +112,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -135,7 +133,7 @@
 # a list of builtin themes.
 #
 # also tried: python_docs_theme, sphinx_rtd_theme
-html_theme = 'sphinx_typlog_theme'
+html_theme = 'shibuya'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -154,19 +152,16 @@
 htmlhelp_basename = 'grilldoc'
 html_sidebars = {
     '**': [
-        'logo.html',
-        'github.html',
-        'globaltoc.html',
-        'searchbox.html',
     ]
 }
-
+html_title = '👨‍🍳 The Grill'
 html_theme_options = {
-    'color': 'Coral',
-    'description': 'Cook digital',
-    'logo_name': '👨‍🍳 The Grill',
+    "accent_color": "sky",
+    "github_url": "https://github.com/thegrill/grill",
+    "globaltoc_expand_depth": 2,
+    "toctree_collapse": True,
+    "toctree_titles_only": False,
 }
-
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {

diff --git a/docs/source/connections_viewer.rst b/docs/source/connections_viewer.rst
@@ -0,0 +1,22 @@
+Connections Viewer
+------------------
+
+From a given `prim`_, recursively traverse its connections through `UsdShade.ConnectableAPI`_.
+Every node represents a `prim`_, with its name at the top, followed by each of its inputs and outputs.
+Outputs are marked as red. Inputs are blue (light for non connected inputs, dark for ones with incoming connections).
+
+.. tab:: USDView
+
+    .. image:: images/connections_viewer_usdview.gif
+
+.. tab:: Houdini
+
+    .. image:: images/connections_viewer_hou.jpg
+
+.. tab:: Maya
+
+    .. image:: images/connections_viewer_maya.jpg
+
+.. _UsdShade.ConnectableAPI: https://openusd.org/release/api/class_usd_shade_connectable_a_p_i.html
+.. _prim: https://openusd.org/release/glossary.html#usdglossary-prim
+
diff --git a/docs/source/end_to_end.rst b/docs/source/end_to_end.rst
@@ -105,4 +105,4 @@ Following the above, both a new ``taxon`` and new ``asset units`` are created, t
    Note how same rules apply (e.g. the ``Repository`` path must be set before any creation action).
 
 .. _taxonomy: https://en.wikipedia.org/wiki/Taxonomy
-.. _stage: https://graphics.pixar.com/usd/docs/USD-Glossary.html#USDGlossary-Stage
+.. _stage: https://openusd.org/release/glossary.html#usdglossary-stage
diff --git a/docs/source/environment_variables.rst b/docs/source/environment_variables.rst
@@ -0,0 +1,51 @@
+Environment Variables
+---------------------
+
+``The Grill`` defaults to an interactive graph explorer for views like the ``ConnectionViewer``, ``LayerStack Composition`` and ``Taxonomy Editor``.
+Previously, these views used to load static SVG images, leveraging ``QtWebEngine`` for performance.
+However, some environments do not bring ``QtWebEngine`` with them, and others lead to crashes (see `thegrill#36 <https://github.com/thegrill/grill/issues/36>`_ as an example).
+
+In order to help with these issues and to bring interactivity to graph views, `thegrill#35 <https://github.com/thegrill/grill/issues/35>`_ introduced a custom ``GraphView`` inheriting from ``QGraphicsView``.
+
+When needed, the following environment variables will bring the old SVG behavior and prevent ``QtWebEngine`` crashes:
+
+GRILL_GRAPH_VIEW_VIA_SVG
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enable this with a boolean value to inspect graphs as SVG images. A value of ``0`` will restore the default interactive GraphViewer:
+
+.. tab:: GRILL_GRAPH_VIEW_VIA_SVG=0
+
+    .. tab:: Connections Viewer
+
+        .. image:: images/connections_viewer_interactive.jpg
+
+    .. tab:: LayerStack Composition
+
+        .. image:: images/layerstack_composition_interactive.jpg
+
+.. tab:: GRILL_GRAPH_VIEW_VIA_SVG=1
+
+    .. tab:: Connections Viewer
+
+        .. image:: images/connections_viewer_svg.jpg
+
+    .. tab:: LayerStack Composition
+
+        .. image:: images/layerstack_composition_svg.jpg
+
+If you come across any reason to inspect images as SVG, please reach out on GitHub as this will help assess if this should be removed or better integrated beyond an environment variable.
+
+GRILL_SVG_VIEW_AS_PIXMAP
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Enable this with a boolean value to load SVG images as ``QPixmap`` (thus avoiding use of ``QtWebEngine``):
+
+.. tab:: GRILL_SVG_VIEW_AS_PIXMAP=0
+
+    .. image:: images/prim_composition_svg.jpg
+
+.. tab:: GRILL_SVG_VIEW_AS_PIXMAP=1
+
+    .. image:: images/prim_composition_pixmap.jpg
+
diff --git a/docs/source/images/connections_viewer_hou.jpg b/docs/source/images/connections_viewer_hou.jpg
diff --git a/docs/source/images/connections_viewer_interactive.jpg b/docs/source/images/connections_viewer_interactive.jpg
diff --git a/docs/source/images/connections_viewer_maya.jpg b/docs/source/images/connections_viewer_maya.jpg
diff --git a/docs/source/images/connections_viewer_svg.jpg b/docs/source/images/connections_viewer_svg.jpg
diff --git a/docs/source/images/connections_viewer_usdview.gif b/docs/source/images/connections_viewer_usdview.gif
diff --git a/docs/source/images/layerstack_composition_arc_filter_options.jpg b/docs/source/images/layerstack_composition_arc_filter_options.jpg
diff --git a/docs/source/images/layerstack_composition_interactive.jpg b/docs/source/images/layerstack_composition_interactive.jpg
diff --git a/docs/source/images/layerstack_composition_options_default.jpg b/docs/source/images/layerstack_composition_options_default.jpg
diff --git a/docs/source/images/layerstack_composition_options_precise_source_layer.jpg b/docs/source/images/layerstack_composition_options_precise_source_layer.jpg
diff --git a/docs/source/images/layerstack_composition_svg.jpg b/docs/source/images/layerstack_composition_svg.jpg
diff --git a/docs/source/images/layerstack_composition_usdview.gif b/docs/source/images/layerstack_composition_usdview.gif
diff --git a/docs/source/images/menu_hou.gif b/docs/source/images/menu_hou.gif
diff --git a/docs/source/images/menu_maya.gif b/docs/source/images/menu_maya.gif
diff --git a/docs/source/images/menu_usdview.gif b/docs/source/images/menu_usdview.gif
diff --git a/docs/source/images/prim_composition_pixmap.jpg b/docs/source/images/prim_composition_pixmap.jpg
diff --git a/docs/source/images/prim_composition_svg.jpg b/docs/source/images/prim_composition_svg.jpg
diff --git a/docs/source/images/prim_composition_usdview.gif b/docs/source/images/prim_composition_usdview.gif
diff --git a/docs/source/images/sheet_usdview.gif b/docs/source/images/sheet_usdview.gif
diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -4,7 +4,7 @@ Installation
 Pip Install
 -----------
 
-By default, ``grill`` won't install ``USD``, ``PySide2`` & ``PyOpenGL``. This is because
+By default, ``grill`` won't install ``USD``, ``PySide(2|6)`` & ``PyOpenGL``. This is because
 DCC apps and other environments bundle them outside of ``pip``. To include them, use the ``[full]`` option.
 
 .. tab:: Default
@@ -47,7 +47,7 @@ Extra Dependencies
 The following optional dependencies should be installed separately.
 
 - `graphviz <http://graphviz.org/>`_ and `pygraphviz`_ for graph widgets. See conda example below for instructions.
-- `usdview <https://graphics.pixar.com/usd/docs/USD-Toolset.html#USDToolset-usdview>`_
+- `usdview <https://openusd.org/release/toolset.html#usdview>`_
   (hopefully will be available soon via `pypi <https://pypi.org/>`_). In the meantime, it can be built from USD source
   (`conda recipe <https://github.com/PixarAnimationStudios/USD/issues/1260#issuecomment-656985888>`_).
 
@@ -92,7 +92,51 @@ walk-through on how to start using ``The Grill`` tools with a fresh
 
    .. warning::
 
-      At the moment, installing pygraphviz can be tricky. Hopefully a simpler pip based solution comes with `pygraphviz#167 <https://github.com/pygraphviz/pygraphviz/issues/167>`_.
+      At the moment, installing `pygraphviz`_ can be tricky. Hopefully a simpler pip+wheel based solution comes with `pygraphviz#167 <https://github.com/pygraphviz/pygraphviz/issues/167>`_.
+
+      Versions older than ``pip-23.3.2`` may have trouble installing `pygraphviz`_ in Windows for DCCs like ``Maya`` and ``Houdini``.
+      If you come through this trouble, visit `pygraphviz#468 <https://github.com/pygraphviz/pygraphviz/pull/468>`_ and try to install with this exact particular version of ``pip``.
+      The below tests ran successfully with ``Maya-2024`` and ``Houdini-20.0`` on ``Windows-10`` and ``pip-23.3.2``.
+
+      The current ``pip`` version can be extracted like so:
+
+      .. tab:: Standalone Python
+
+         .. code:: PowerShell
+
+            python -m pip -V
+
+      .. tab:: Houdini
+
+         .. code:: PowerShell
+
+            hython -m pip -V
+
+      .. tab:: Maya
+
+         .. code:: PowerShell
+
+            mayapy -m pip -V
+
+      To update to ``23.3.2``, update the interpreter command to run:
+
+      .. tab:: Standalone Python
+
+         .. code:: PowerShell
+
+            python -m pip install -U pip==23.3.2
+
+      .. tab:: Houdini
+
+         .. code:: PowerShell
+
+            hython -m pip install -U pip==23.3.2
+
+      .. tab:: Maya
+
+         .. code:: PowerShell
+
+            mayapy -m pip install -U pip==23.3.2
 
    .. tab:: Standalone Python
 
@@ -110,7 +154,7 @@ walk-through on how to start using ``The Grill`` tools with a fresh
      .. code:: PowerShell
 
         (grilldemo01) C:\>conda install --channel conda-forge pygraphviz
-        (grilldemo01) C:\Program Files\Side Effects Software\Houdini 19.5.534\bin>hython -m pip install --global-option=build_ext --global-option="-IC:\Users\Christian\.conda\envs\glowdeps\Library\include" --global-option="-LC:\Users\Christian\.conda\envs\glowdeps\Library\lib" pygraphviz
+        (grilldemo01) C:\Program Files\Side Effects Software\Houdini 19.5.534\bin>hython -m pip install -vvv --use-pep517 --config-settings="--global-option=build_ext" --config-settings="--global-option=-IC:\Users\Christian\.conda\envs\pygraphviz310\Library\include" --config-settings="--global-option=-LC:\Users\Christian\.conda\envs\pygraphviz310\Library\lib" pygraphviz
 
    .. tab:: Maya
 
@@ -119,22 +163,23 @@ walk-through on how to start using ``The Grill`` tools with a fresh
      .. code:: PowerShell
 
         (grilldemo01) C:\>conda install --channel conda-forge pygraphviz
-        (grilldemo01) C:\Program Files\Autodesk\Maya2023\bin>mayapy -m pip install --global-option=build_ext  --global-option="-IC:\Users\Christian\.conda\envs\glowdeps\Library\include;C:\Program Files\Autodesk\Maya2023\include\Python39\Python" --global-option="-LC:\Users\Christian\.conda\envs\glowdeps\Library\lib;C:\Program Files\Autodesk\Maya2023\lib" pygraphviz
+        (grilldemo01) C:\Program Files\Autodesk\Maya2023\bin>mayapy -m pip install -U pip==23.3.2
+        (grilldemo01) C:\Program Files\Autodesk\Maya2023\bin>mayapy -m pip install -vvv --use-pep517 --config-settings="--global-option=build_ext" --config-settings="--global-option=-IC:\Users\Christian\.conda\envs\pygraphviz310\Library\include;C:\Program Files\Autodesk\Maya2024\include\Python39\Python" --config-settings="--global-option=-LC:\Users\Christian\.conda\envs\pygraphviz310\Library\lib;C:\Program Files\Autodesk\Maya2024\lib" pygraphviz
 
 
 7. You should be able to see the ``👨‍🍳 Grill`` menu in **USDView**, **Maya** and **Houdini***.
 
    .. tab:: USDView
 
-        .. image:: https://user-images.githubusercontent.com/8294116/114263497-2d57d680-9a29-11eb-8992-6b443f942263.gif
+        .. image:: images/menu_usdview.gif
 
    .. tab:: Houdini
 
-        .. image:: https://user-images.githubusercontent.com/8294116/115981745-68d1d380-a5d9-11eb-8033-979d72ca0e6b.gif
+        .. image:: images/menu_hou.gif
 
    .. tab:: Maya
 
-        .. image:: https://user-images.githubusercontent.com/8294116/115981668-bdc11a00-a5d8-11eb-9897-6061639d1c39.gif
+        .. image:: images/menu_maya.gif
 
    .. important::
 

diff --git a/docs/source/intro.rst b/docs/source/intro.rst
@@ -1 +1,2 @@
-.. mdinclude:: ../../README.md
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
diff --git a/docs/source/layerstack_composition.rst b/docs/source/layerstack_composition.rst
@@ -1,14 +1,14 @@
 Layer Stack Composition
 -----------------------
 
-Similar to ``Prim Composition``, but available for the whole `stage`_ by
-creating a graph of `layer stacks`_. This helps answer questions like:
+Similar to ``Prim Composition``, but available for the whole `stage`_ or multiple `prims`_ at once.
+This helps answer questions like:
 
 -  What prims are being affected by `layers`_ X and Y?
 
 .. tab:: USDView
 
-    .. image:: https://user-images.githubusercontent.com/8294116/131240483-9b428c4a-92fc-4d79-b464-8b1d07f982e0.gif
+    .. image:: images/layerstack_composition_usdview.gif
 
 .. tab:: Houdini
 
@@ -20,35 +20,34 @@ creating a graph of `layer stacks`_. This helps answer questions like:
 
 In the above example, we're inspecting `Animal Logic's USD ALab`_.
 
-1. On the upper left, all used layers in the current `stage`_ are listed.
-2. On the upper right, all `prims`_ that are affected by the selected `layers`_ are listed.
-3. On the bottom, a `composition arcs`_ graph is displayed for the selected `layers`_ plus the neighbors (predecessors and successors) for each of them.
+1. On the upper left, all used layers in the composition of the inspected `stage`_ or `prims`_ are listed.
+2. On the upper right, all `prims`_ that are affected by the current selected `layers`_ are listed.
+3. On the bottom, a `composition arcs`_ graph is displayed for the selected `layers`_ plus the neighbors (predecessors and successors) for each of their `layerStacks`_.
 
-   - Nodes in the network represent `layer stacks`_.
+   - Nodes in the network represent `layerStacks`_.
    - Edges are the `composition arcs`_ between them (it follows the same color scheme as the ones provided by Pcp.PrimIndex.DumpToDotGraph).
-   - Options to filter `composition arcs`_ are provided on the up left corner of the network view.
+   - Options to filter `composition arcs`_ are provided above the network view.
 
-     .. image:: https://user-images.githubusercontent.com/8294116/131248473-8855cca9-f011-4c2e-af3c-1f1eb50d4acb.png
+     .. image:: images/layerstack_composition_arc_filter_options.jpg
 
    - The additional option ``Precise Source Layer`` (**off** by default) exists to draw the edge source from the layer from the stack that introduces it.
      This allows to go from this:
 
-     .. image:: https://user-images.githubusercontent.com/8294116/131248571-3d4a7e31-eb1c-434c-953d-eef51bc5808c.png
-
+     .. image:: images/layerstack_composition_options_default.jpg
      To (note the outputs of ``books_magazines01_surfacing`` and ``books_magazines01_modelling``):
 
-     .. image:: https://user-images.githubusercontent.com/8294116/131248575-e50a6d64-c298-48fa-a9d2-290696c6d5eb.png
+     .. image:: images/layerstack_composition_options_precise_source_layer.jpg
 
 
-.. hint::
-    It is also possible to compute the graph from currently selected prims:
+.. warning::
+    Time for computing this graph increases with stage complexity. So for larger stages, it is recommended to start the widget with the `prims`_ of interest rather than the complete `stage`_:
 
     .. image:: https://user-images.githubusercontent.com/8294116/131242428-7b06729d-f96e-4b92-b02f-1608e99859bd.gif
 
 .. _Animal Logic's USD ALab: https://animallogic.com/usd-alab
-.. _layer stacks: https://graphics.pixar.com/usd/docs/USD-Glossary.html#USDGlossary-LayerStack
-.. _layers: https://graphics.pixar.com/usd/docs/USD-Glossary.html#USDGlossary-Layer
-.. _stage: https://graphics.pixar.com/usd/docs/USD-Glossary.html#USDGlossary-Stage
-.. _prims: https://graphics.pixar.com/usd/docs/USD-Glossary.html#USDGlossary-Prim
-.. _composition arcs: https://graphics.pixar.com/usd/docs/USD-Glossary.html#USDGlossary-CompositionArcs
+.. _layerStacks: https://openusd.org/release/glossary.html#usdglossary-layerstack
+.. _layers: https://openusd.org/release/glossary.html#usdglossary-layer
+.. _stage: https://openusd.org/release/glossary.html#usdglossary-stage
+.. _prims: https://openusd.org/release/glossary.html#usdglossary-prim
+.. _composition arcs: https://openusd.org/release/glossary.html#usdglossary-compositionarcs