Instance Check (#45)

* usdview submenus for selecting prototype and instances

* note on crashes when opening Prim Composition due to QtWebEngine

* remove printree dependency

* update actions version and enabled pythonwarnings as errors

Signed-off-by: Christian López Barrón <chris.gfz@gmail.com>

Author: chrizzFTD

.github/workflows/python-package.yml

@@ -22,9 +22,9 @@ jobs:
           - python-version: "3.13"
             install-arguments: ".[full,create]"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Set up Graphviz
@@ -41,7 +41,7 @@ jobs:
           python -m pip install ${{ matrix.install-arguments }}
       - name: Test
         run: |
-          pytest --cov .
+          PYTHONWARNINGS=error,ignore:::pyparsing pytest --cov --durations=10 .
         # https://github.com/marketplace/actions/codecov
       - name: Codecov Report
         uses: codecov/codecov-action@v4

docs/source/conf.py

@@ -163,7 +163,7 @@
 }
 html_title = '👨‍🍳 The Grill'
 html_theme_options = {
-    "accent_color": "sky",
+    "accent_color": "blue",
     "github_url": "https://github.com/thegrill/grill",
     "globaltoc_expand_depth": 2,
     "toctree_collapse": True,

docs/source/prim_composition.rst

@@ -5,6 +5,10 @@ Uses :ref:`Prim Index <glossary:index>` and its utilities (:usdcpp:`PcpPrimIndex
 
 To visualize the :ref:`glossary:composition` graph, the ``graphviz`` library needs to be available in the environment.
 
+.. important::
+
+    If you experience crashes when launching this widget, it could be due to issues with ``QtWebEngine``. Try setting environment variable ``GRILL_SVG_VIEW_AS_PIXMAP=1`` to avoid use of ``QtWebEngine`` (`see environment variables <views.html#environment-variables>`_ for more details).
+
 .. tab:: USDView
 
     .. image:: images/prim_composition_usdview.gif

grill/cook/__init__.py

@@ -139,6 +139,7 @@ def define_taxon(stage: Usd.Stage, name: str, *, references: tuple[Usd.Prim] = t
     Optional ``field=value`` items can be provided for identification purposes through ``id_fields``.
 
     """
+    # This could create a new schema in the future if codeless schemas are allowed to be registered at runtime
     if name == _TAXONOMY_NAME:
         # TODO: prevent upper case lower case mismatch handle between multiple OS?
         #  (e.g. Windows considers both the same but Linux does not)
@@ -406,6 +407,7 @@ def spawn_many(parent: Usd.Prim, child: Usd.Prim, paths: list[Sdf.Path], labels:
     # Ensure prims are defined to spawn units unto (paths might be deep e.g. /world/parent/nested/path/for/child)
     spawned = [parent_stage.DefinePrim(path) for path in paths_to_create]
     child_is_model = child.IsModel()
+    checked_parents = set()
     with Sdf.ChangeBlock():
         # Action of bringing a unit from our catalogue turns parent into an assembly only if child is a model.
         if child_is_model and not (parent_model := Usd.ModelAPI(parent)).IsKind(Kind.Tokens.assembly):
@@ -431,9 +433,13 @@ def spawn_many(parent: Usd.Prim, child: Usd.Prim, paths: list[Sdf.Path], labels:
             # Action of bringing a unit from our catalogue turns parent into an assembly only if child is a model.
             if child_is_model:
                 # check for all intermediate parents of our spawned unit to ensure valid model hierarchy
-                for inner_parent in _usd.iprims(parent_stage, [parent_path], lambda p: p == spawned_unit.GetParent()):
+                inner_parent = spawned_unit.GetParent()
+                while inner_parent != parent and inner_parent not in checked_parents:
                     if not inner_parent.IsModel():
                         Usd.ModelAPI(inner_parent).SetKind(Kind.Tokens.group)
+                        checked_parents.add(inner_parent)
+                    inner_parent = inner_parent.GetParent()
+
                 if not child.IsGroup():
                     # Sensible defaults: component prims are instanced
                     spawned_unit.SetInstanceable(True)
@@ -551,3 +557,9 @@ def taxonomy_graph(prims: Usd.Prim, url_id_prefix: str) -> nx.DiGraph:
 def _(stage: Usd.Stage, url_id_prefix: str) -> nx.DiGraph:
     # Convenience for the stage
     return taxonomy_graph(itaxa(stage), url_id_prefix)
+
+
+def filter_taxa(prims: abc.Iterable[Usd.Prim], taxon: Usd.Prim | str, *taxa: Usd.Prim) -> abc.Iterator[Usd.Prim]:
+    """From the given prims, yield those that are part of the given taxa."""
+    taxa_names = {i if isinstance(i, str) else i.GetName() for i in (taxon, *taxa)}
+    return (prim for prim in prims if taxa_names.intersection(prim.GetAssetInfoByKey(_ASSETINFO_TAXA_KEY) or {}))

grill/usd/__init__.py

@@ -13,7 +13,6 @@
 from collections import abc
 
 from pxr import Usd, UsdGeom, Sdf, Plug, Ar, Tf
-from printree import TreePrinter
 
 logger = logging.getLogger(__name__)
 
@@ -294,31 +293,6 @@ def is_target(arc):
     return edit_context(prim, query_filter, is_target)
 
 
-@contextlib.contextmanager
-def _prim_tree_printer(predicate, prims_to_include: abc.Container = frozenset()):
-    prim_entry = Usd.Prim.GetName if predicate != Usd.PrimIsModel else lambda prim: f"{prim.GetName()} ({Usd.ModelAPI(prim).GetKind()})"
-
-    class PrimTreePrinter(TreePrinter):
-        """For everything else, use usdtree from the vanilla USD toolset"""
-
-        def ftree(self, prim: Usd.Prim):
-            self.ROOT = f"{super().ROOT}{prim_entry(prim)}"
-            return super().ftree(prim)
-
-    # another duck
-    Usd.Prim.__iter__ = lambda prim: (p for p in prim.GetFilteredChildren(predicate) if not prims_to_include or p in prims_to_include)
-    Usd.Prim.items = lambda prim: ((prim_entry(p), p) for p in prim)
-    current = type(abc.Mapping).__instancecheck__  # can't unregister abc.Mapping.register, so use __instancecheck__
-
-    type(abc.Mapping).__instancecheck__ = lambda cls, inst: current(cls, inst) or (cls == abc.Mapping and type(inst) == Usd.Prim)
-    try:
-        yield PrimTreePrinter()
-    finally:
-        type(abc.Mapping).__instancecheck__ = current
-        del Usd.Prim.__iter__
-        del Usd.Prim.items
-
-
 def _format_prim_hierarchy(prims, include_descendants=True, predicate=Usd.PrimDefaultPredicate):
     for prim in prims:
         if prim.IsPseudoRoot():
@@ -328,8 +302,56 @@ def _format_prim_hierarchy(prims, include_descendants=True, predicate=Usd.PrimDe
         root_paths = dict.fromkeys(common_paths((prim.GetPath() for prim in prims)))
         prims_to_tree = (prim for prim in prims if prim.GetPath() in root_paths)
 
-    with _prim_tree_printer(predicate, set(prims) if not include_descendants else set()) as printer:
-        return "\n".join(printer.ftree(prim) for prim in prims_to_tree)
+    prim_entry = Usd.Prim.GetName if predicate != Usd.PrimIsModel else lambda prim: f"{prim.GetName()} ({Usd.ModelAPI(prim).GetKind()})"
+    prims_to_include = set(prims) if not include_descendants else set()
+
+    def ftree(prim, prefix="", last=True, buffer=None):
+        if buffer is None:  # we're at the root
+            buffer = []
+            marker, child_prefix = "┐", ""
+        elif not last:
+            marker, child_prefix = '├── ', f"{prefix}│   "
+        else:
+            marker, child_prefix = '└── ', f"{prefix}    "
+
+        buffer.append(f"{prefix}{marker}{prim_entry(prim)}")
+        for index, child in enumerate(children := prim.GetFilteredChildren(predicate)):
+            if not prims_to_include or child in prims_to_include:
+                ftree(child, child_prefix, index == len(children)-1, buffer)
+        return buffer
+
+    return "\n".join(chain.from_iterable(ftree(prim) for prim in prims_to_tree))
+
+
+def iter_recursive_instances(prims: abc.Iterable[Usd.Prim]) -> abc.Iterator[Usd.Prim]:
+    """For the given prims, recursively iterate over all instances from their prototypes."""
+
+    visited_prototypes = set()
+
+    def get_instances_from_prototype_child(child):
+        child_path = child.GetPath()
+        root_path = child_path.GetPrefixes()[0]  # contract: all prototypes are root prims like /__Prototype_3
+        stage = child.GetStage()
+        proto = stage.GetPrimAtPath(root_path)
+        rel_path = child_path.MakeRelativePath(root_path)
+        return [stage.GetPrimAtPath(instance.GetPath().AppendPath(rel_path)) for instance in proto.GetInstances()]
+
+    def visit_prototype(prototype, instances_getter):
+        if prototype in visited_prototypes:
+            return
+        visited_prototypes.add(prototype)
+        for instance in (instances:=instances_getter(prototype)):
+            yield instance
+        yield from iterate_instances(instances)
+
+    def iterate_instances(prims):
+        for prim in prims:
+            if (is_instance := prim.IsInstance()) or prim.IsPrototype():
+                yield from visit_prototype(prim.GetPrototype() if is_instance else prim, Usd.Prim.GetInstances)
+            if (is_proxy := prim.IsInstanceProxy()) or prim.IsInPrototype():  # we're beneath an instance
+                yield from visit_prototype(prim.GetPrimInPrototype() if is_proxy else prim, get_instances_from_prototype_child)
+
+    yield from iterate_instances(prims)
 
 
 # add other mesh creation utilities here?

grill/views/usdview.py

@@ -175,6 +175,43 @@ class GrillPrimConnectionViewerMenuItem(GrillPrimCompositionMenuItem):
     _subtitle = "Connections"
 
 
+class GrillSelectPrimPrototypeMenuItem(GrillPrimCompositionMenuItem):
+
+    @property
+    def _subtitle(self):
+        return f"Select Prototype{'s' if len(self._selectionDataModel.getPrims()) > 1 else ''}"
+
+    def IsEnabled(self):
+        return any((prim.IsInstance() or prim.IsInstanceProxy()) for prim in self._selectionDataModel.getPrims())
+
+    def RunCommand(self):
+        selection_model = self._selectionDataModel
+        prims = selection_model.getPrims()
+        with selection_model.batchPrimChanges:
+            selection_model.clearPrims()
+            for prim in prims:
+                if prim.IsInstance() and (proto := prim.GetPrototype()):
+                    selection_model.addPrim(proto)
+                elif prim.IsInstanceProxy():
+                    selection_model.addPrim(prim.GetPrimInPrototype())
+
+
+class GrillSelectPrimPrototypeInstancesMenuItem(GrillPrimCompositionMenuItem):
+    """Recursively (e.g. traversing nested instancing) select all instances of the selected prims"""
+    _subtitle = "Select Prototype Instances"
+
+    def IsEnabled(self):
+        return any((prim.IsInstance() or prim.IsInstanceProxy() or prim.IsInPrototype()) for prim in self._selectionDataModel.getPrims())
+
+    def RunCommand(self):
+        selection_model = self._selectionDataModel
+        prims = selection_model.getPrims()
+        with selection_model.batchPrimChanges:
+            selection_model.clearPrims()
+            for instance in sorted(gusd.iter_recursive_instances(prims), key=lambda p: p.GetPath()):
+                selection_model.addPrim(instance)
+
+
 class AllHierarchyTextMenuItem(_GrillPrimContextMenuItem):
     _include_descendants = True
     _subtitle = "All Descendants"

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = grill
-version = 0.19.0
+version = 0.19.1
 description = Pipeline tools for (but not limited to) audiovisual projects.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -17,7 +17,6 @@ classifiers =
 
 [options]
 install_requires =
-    printree
     numpy
     pydot>=3.0.1
     networkx>=3.4; python_version > "3.9"
@@ -30,19 +29,19 @@ include = grill.*
 
 [options.extras_require]
 # USD build:
-# conda create -n py313usd2411build python=3.13
-# conda activate py313usd2411build
-# conda install -c conda-forge cmake=3.27
-# python -m pip install PySide6 PyOpenGL jinja2
+# conda create -n py314usdbuild python=3.14 -c conda-forge
+# conda activate py314usdbuild
+# conda install conda-forge::cmake=3.27
+# python -m pip install PySide6 PyOpenGL jinja2 <- fails 2025/10/12
 # conda install -c rdonnelly vs2019_win-64
-# python "A:\write\code\git\OpenUSD\build_scripts\build_usd.py" -v "A:\write\builds\py313usd2411build"
+# python "A:\write\code\git\OpenUSD\build_scripts\build_usd.py" -v "A:\write\builds\py314usdbuild"
 #
 # --- dev env ---:
-# conda create -n py313usd2411 python=3.13
-# conda activate py313usd2411
+# conda create -n py314usd python=3.13
+# conda activate py314usd
 # runtime dependencies:
-# conda install conda-forge::graphviz
-# python -m pip install grill-names>=2.6.0 networkx>=3.4 pydot>=3.0.1 numpy printree PyOpenGL pyside6
+# conda install conda-forge::graphviz=11 # 13.1.2 brings up libffi which messes up _ctypes from python-3.13, and 12 fails to load gvplugin_pango.dll
+# python -m pip install grill-names>=2.6.0 networkx>=3.4 pydot>=3.0.1 numpy PyOpenGL pyside6
 # docs dependencies:
 # python -m pip install sphinx myst-parser sphinx-toggleprompt sphinx-copybutton sphinx-togglebutton sphinx-hoverxref>=1.4.1 sphinx_autodoc_typehints sphinx-inline-tabs shibuya sphinxcontrib-doxylink
 # For EDGEDB (coming up)

tests/mini_test_bed/Model-Blocks-Block.1.usda

@@ -18,6 +18,7 @@ def "Origin" (
 {
     def "Building1" (
         prepend references = @Model-Buildings-Multi_Story_Building.1.usda@
+        instanceable = true
     )
     {
         double3 xformOp:translate = (-54, 126, 1)
@@ -26,6 +27,7 @@ def "Origin" (
 
     def "Building2" (
         prepend references = @Model-Buildings-Multi_Story_Building.1.usda@
+        instanceable = true
     )
     {
         double3 xformOp:translate = (54, 126, 1)
@@ -34,6 +36,7 @@ def "Origin" (
 
     def "Building3" (
         prepend references = @Model-Buildings-Multi_Story_Building.1.usda@
+        instanceable = true
     )
     {
         double3 xformOp:translate = (-54, -126, 1)
@@ -42,6 +45,7 @@ def "Origin" (
 
     def "Building4" (
         prepend references = @Model-Buildings-Multi_Story_Building.1.usda@
+        instanceable = true
     )
     {
         double3 xformOp:translate = (54, -126, 1)

tests/test_cook.py

@@ -142,6 +142,16 @@ def test_taxonomy(self):
         self.assertEqual(first_successors, {second.GetName(), third.GetName()})
         self.assertEqual(set(cook.taxonomy_graph(stage, "").nodes), set(graph_from_stage.nodes))
 
+    def test_filter_taxa(self):
+        stage = cook.fetch_stage(self.root_asset)
+        root = cook.define_taxon(stage, "Root")
+        parent, child = cook.create_many(root, ['A', 'B'])
+        another = cook.define_taxon(stage, "Another")
+        cook.create_many(another, ['C', 'D'])
+        inherited = cook.define_taxon(stage, "Inherited", references=[root])
+        grandchild = cook.create_unit(inherited, 'E')
+        self.assertSetEqual({parent, child, grandchild}, set(cook.filter_taxa(stage.Traverse(), root)))
+
     def test_asset_unit(self):
         stage = cook.fetch_stage(self.root_asset)
         taxon_name = "taxon"

tests/test_usd.py

@@ -1,4 +1,5 @@
 import unittest
+from pathlib import Path
 
 from pxr import Usd, UsdGeom, Sdf
 
@@ -16,6 +17,7 @@
 # (durations < 0.001s were hidden; use -v to show these durations)
 # ----------------------------------------------------------------------
 # Ran 5 tests in 0.030s
+_test_bed = Path(__file__).parent / "mini_test_bed" / "main-world-test.1.usda"
 
 
 class TestUSD(unittest.TestCase):
@@ -103,3 +105,34 @@ def test_make_plane(self):
         self.assertEqual(80, len(mesh.GetPointsAttr().Get()))
         self.assertEqual(252, len(mesh.GetFaceVertexIndicesAttr().Get()))
         self.assertEqual(63, len(mesh.GetFaceVertexCountsAttr().Get()))
+
+    def test_recursive_instances(self):
+        """Confirm we can collect all instances recursively"""
+
+        paths = (
+            "/Catalogue/Model/Buildings/Multi_Story_Building/Windows/Apartment",
+            "/Catalogue/Model/Buildings/Multi_Story_Building/Windows/Apartment_blue",
+        )
+        stage = Usd.Stage.Open(str(_test_bed))
+        expected_prim_paths = {Sdf.Path(path) for path in (
+            "/Catalogue/Model/Blocks/Block/Building1/Windows/Apartment",
+            "/Catalogue/Model/Blocks/Block/Building1/Windows/Apartment_blue",
+            "/Catalogue/Model/Blocks/Block/Building2/Windows/Apartment",
+            "/Catalogue/Model/Blocks/Block/Building2/Windows/Apartment_blue",
+            "/Catalogue/Model/Blocks/Block/Building3/Windows/Apartment",
+            "/Catalogue/Model/Blocks/Block/Building3/Windows/Apartment_blue",
+            "/Catalogue/Model/Blocks/Block/Building4/Windows/Apartment",
+            "/Catalogue/Model/Blocks/Block/Building4/Windows/Apartment_blue",
+            "/Catalogue/Model/Buildings/Multi_Story_Building/Windows/Apartment",
+            "/Catalogue/Model/Buildings/Multi_Story_Building/Windows/Apartment_blue",
+            "/__Prototype_1/Windows/Apartment",
+            "/__Prototype_1/Windows/Apartment_blue",
+        )}
+        prims = (stage.GetPrimAtPath(p) for p in paths)
+        result = [instance.GetPath() for instance in gusd.iter_recursive_instances(prims)]
+
+        non_proto__result_paths = {path for path in result if not str(path).startswith("/__Prototype_")}
+        non_proto_expected_paths = {path for path in expected_prim_paths if not str(path).startswith("/__Prototype_")}
+
+        self.assertEqual(len(result), len(expected_prim_paths))
+        self.assertSetEqual(non_proto__result_paths, non_proto_expected_paths)