Update Normals/USD/BSP examples and docs

Author: Kap44

Elements/extensions/Normals_USDimporter_BSP/README.md

@@ -3,49 +3,57 @@ Authors:
     Kapetanakis Ioannis - csd4641
 
 Tests are written for pytest
-    -> To run all the tests, type "pytest Tests"
+    -> To run all the tests, type: pytest Tests
 
-<For Proper Normals Task:>
-Implemented correct flat/smooth normal handling by detecting shared vs unique vertex indexing and converting the vertex/index buffers accordingly. Custom helper functions exist to determine whether vertices are shared or unique by analyzing index usage. This correction fixes smooth-shading artifacts caused by incorrect vertex-sharing assumptions and ensures the appropriate flat or smooth shading path is selected.
 
-Usage:
-    python cow_example.py --shading {smooth|flat} [-colored]
-    python sphere.py      --shading {smooth|flat} [-colored]
-
-Options:
-    --shading    Shading mode to use.
-                 smooth  : smooth (per-vertex) normals
-                 flat    : flat (per-face) normals
-
-Flags:
-    -colored     Enable color visualization by using normals as colors (optional)
+<Proper Normals Task:>
+Implemented correct flat/smooth normal handling by detecting shared vs unique vertex indexing and converting the vertex/index buffers accordingly. Helper utilities determine whether vertices are shared or unique by analyzing index usage. This fixes smooth-shading artifacts caused by incorrect vertex-sharing assumptions and ensures the appropriate flat or smooth shading path is selected.
 
-Example:
-    python cow_example.py --shading flat -colored
+Usage:
+    python cow_example.py
+    python sphere_example.py
 
+Runtime options (ImGui):
+    - Shading: Smooth / Flat
+    - Normals as color: toggles normal-visualization by mapping normals to RGB
 
-<For USD Importer Task:>
+<USD Importer Task:>
 The LoadScene_Blender method imports a USD scene exported from Blender and converts it into an Elements scene representation. It traverses the USD stage hierarchy, creates corresponding entities for each UsdGeom.Xform, and reconstructs parent–child relationships based on USD paths.
 
 For each UsdGeom.Mesh, the method extracts geometry data including vertex positions, face topology, normals, and material color information. It supports both smooth and flat shading by handling different normal interpolation modes (vertex and faceVarying). Polygonal faces are triangulated appropriately, with corner-space triangulation used for flat shading.
 
 The method uploads vertex attributes and indices to the GPU and performs coordinate system conversion from Blender’s Z-up convention to the engine’s Y-up convention.
 
 Usage:
-    python usd_import_example.py [-colored]
-
-Flags:
-    -colored     Enable color visualization by using normals as colors (optional)
+    python usd_import_example.py
 
+Runtime options (ImGui):
+    - Load USD (colors)
+    - Load USD (normals as color)
 
-<For BSP Task:>
+<BSP Task:>
 The implemented method builds an axis-aligned Binary Space Partitioning (BSP) tree for triangle meshes.
 
+Each triangle is implicitly assigned an ID based on its position in the index buffer (every 3 consecutive indices correspond to one triangle). The search(id) function references triangles using this index-based ID.
+
 At each node, the splitting axis is selected based on the largest spatial extent of the triangles, while the split position is chosen as the median of triangle centroids along that axis to avoid unbalanced partitions.
 
 Triangles are classified as fully on one side of the split plane or intersecting it; intersecting triangles are propagated to all child leaf nodes to preserve spatial correctness.
 
-During search, the BSP tree is traversed by testing each triangle against the split planes. Depending on whether the triangle lies on one side of the plane or intersects it, the traversal proceeds to the appropriate child nodes.
+During search, the BSP tree is traversed by testing each triangle against the split planes. The traversal path and tree structure are printed to the terminal.
 
 Usage:
-    python bsp_example.py
+    python bsp_example.py
+
+    What to try:
+    - Move the camera to view triangle placement.
+    - Use Triangle id = 0..4 and press Search to observe different traversal paths.
+    - Press Print tree to inspect the BSP structure by depth.
+
+    In each case, the result is printed to the terminal.
+
+
+Runtime options (ImGui):
+    - Triangle id (input)
+    - Search (prints traversal path to the terminal)
+    - Print tree (prints the BSP structure by depth to the terminal)

Elements/extensions/Normals_USDimporter_BSP/UsdImporter.py

@@ -7,7 +7,6 @@
 The USDImporter file, holds functionality for importing and exporting Elements scenes as .usd files
 
 """
-from pxr import Usd, UsdGeom
 
 from pxr import Usd, UsdGeom, UsdShade
 import numpy as np

Elements/extensions/Normals_USDimporter_BSP/bsp_example.py

@@ -1,4 +1,5 @@
 import numpy as np
+import imgui
 
 import Elements.pyECSS.math_utilities as util
 from Elements.pyECSS.Entity import Entity
@@ -20,14 +21,14 @@
 
 
 example_description = \
-"This is a scene with triangles (instead of cubes), a terrain and axes. \n\
-The triangles and axes are rendered with a simple shader. \n\
-that allow camera movement too, via the Elements GUI. \n\n\
-An ECSS Graph shows the Entities and Components of the \n\
-scene, in read only way, i.e., you cannot manipulate  \n\
-any information via the ECSS Graph GUI. \n\n\
-You can move the camera through the Elements GUI \n\
-or the mouse. Hit ESC OR Close the window to quit."
+"This example demonstrates building and querying a BSP tree over a small set of triangles.\n\
+Five triangles are placed in the scene along with a terrain grid and world axes.\n\
+\n\
+Use the 'BSP Controls' window to select a Triangle id and press 'Search' to print the\n\
+BSP traversal path to the terminal. Press 'Print tree' to print the BSP structure by depth.\n\
+\n\
+You can move the camera via the Elements GUI or the mouse. Hit ESC or close the window to quit."
+
 
 winWidth = 1024
 winHeight = 768
@@ -271,23 +272,42 @@
 BSP.build()
 
 print()
-print("---- BSP Tree ----")
-BSP.print_by_depth()
+# print("---- BSP Tree ----")
+# BSP.print_by_depth()
 
-print()
-print("---- Search path traversal (for a non-intersected triangle) ----")
-BSP.search(1)
+# print()
+# print("---- Search path traversal (for a non-intersected triangle) ----")
+# BSP.search(1)
 
-print()
-print("---- Search path traversal (for a intersected triangle) ----")
+# print()
+# print("---- Search path traversal (for a intersected triangle) ----")
 
-BSP.search(0)
+# BSP.search(0)
 
 model_terrain = terrain.getChild(0).trs
 model_axes = axes_trans.trs
 
+search_id = 0
+print_tree = False
+
 while running:
     running = scene.render()
+    imgui.begin("BSP Controls")
+
+    changed, search_id = imgui.input_int("Triangle id", search_id)
+
+    if imgui.button("Search"):
+        print("\n---- Search path traversal ----")
+        BSP.search(int(search_id))
+
+    imgui.same_line()
+
+    if imgui.button("Print tree"):
+        print("\n---- BSP Tree ----")
+        BSP.print_by_depth()
+
+    imgui.end()
+
     displayGUI_text(example_description)
     scene.world.traverse_visit(renderUpdate, scene.world.root)
     scene.world.traverse_visit_pre_camera(camUpdate, orthoCam)