TEST: example refactor

.github/workflows/ci_cd.yml

@@ -635,7 +635,7 @@ jobs:
         run: |
           . /env/bin/activate
           pip install uv
-          uv pip install -e .[doc]
+          uv pip install -e .[doc,graphics]
 
       - name: Build docs
         env:

.pre-commit-config.yaml

@@ -63,7 +63,7 @@ repos:
           tests/scripts/run_python_error.py |
           tests/scripts/run_python_success.py |
           tests/scripts/log_message.py |
-          examples/embedding_n_remote/embedding_remote.py
+          examples/.*
         )$
 
 - repo: https://github.com/pre-commit/pre-commit-hooks

doc/changelog.d/1125.test.md

@@ -0,0 +1 @@
+Example refactor

doc/source/conf.py

@@ -13,13 +13,17 @@
 import warnings
 
 from ansys_sphinx_theme import ansys_favicon, get_version_match
+import pyvista
+from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
 from sphinx_gallery.sorting import FileNameSortKey
 
 import ansys.mechanical.core as pymechanical
 from ansys.mechanical.core.embedding.initializer import SUPPORTED_MECHANICAL_EMBEDDING_VERSIONS
 
 # necessary when building the sphinx gallery
 pymechanical.BUILDING_GALLERY = True
+pyvista.BUILDING_GALLERY = True
+pyvista.OFF_SCREEN = True
 
 # Whether or not to build the cheatsheet
 BUILD_CHEATSHEET = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
@@ -61,6 +65,7 @@
     "sphinx_copybutton",
     "sphinx_design",
     "sphinxemoji.sphinxemoji",
+    "pyvista.ext.viewer_directive",
 ]
 
 if pymechanical.BUILDING_GALLERY:
@@ -175,7 +180,7 @@
     "backreferences_dir": None,
     # Modules for which function level galleries are created.  In
     "doc_module": "ansys-mechanical-core",
-    "image_scrapers": ("matplotlib"),
+    "image_scrapers": (DynamicScraper(), "matplotlib"),
     "ignore_pattern": "flycheck*",
     "thumbnail_size": (350, 350),
 }

doc/source/index.rst

@@ -31,7 +31,7 @@ Python API to interact with `Ansys Mechanical`_ (FEA software for structural eng
 
     .. grid-item-card:: Examples :fa:`scroll`
         :padding: 2 2 2 2
-        :link: examples/index
+        :link: examples/gallery_examples/index
         :link-type: doc
 
         Dive into examples created using PyMechanical.
@@ -109,7 +109,7 @@ Python API to interact with `Ansys Mechanical`_ (FEA software for structural eng
    :maxdepth: 3
 
    getting_started/index
-   examples/index
+   examples/gallery_examples/index
    user_guide_session/index
    user_guide_embedding/index
    user_guide_scripting/index

examples/00_tips/readme.txt

@@ -0,0 +1,5 @@
+Tips
+====
+
+This section showcases some of the useful functions that can be used
+in PyMechanical embedding workflow.

examples/00_tips/tips_01.py

@@ -0,0 +1,78 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+""".. _ref_tips_01:
+
+3D visualization
+----------------
+
+The following example demonstrates how to visualize imported geometry in 3D.
+"""
+
+# %%
+# Import the necessary libraries
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+from ansys.mechanical.core import App
+from ansys.mechanical.core.examples import delete_downloads, download_file
+
+# %%
+# Initialize the embedded application
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+app = App(globals=globals())
+print(app)
+
+# %%
+# Download and import the geometry file
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# %%
+# Download the geometry file
+geometry_path = download_file("Valve.pmdb", "pymechanical", "embedding")
+
+# %%
+# Define the model and import the geometry file
+model = app.Model
+
+geometry_import = model.GeometryImportGroup.AddGeometryImport()
+geometry_import.Import(geometry_path)
+
+# %%
+# Visualize the model in 3D
+# ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+app.plot()
+
+# %%
+# .. note::
+#     This visualization is currently available only for geometry and on version 24R2 or later
+
+# %%
+# Clean up the files and app
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Delete the downloaded files
+delete_downloads()
+
+# Close the app
+app.close()

examples/00_tips/tips_02.py

@@ -0,0 +1,142 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+""".. _ref_tips_02:
+
+Export image
+------------
+
+The following example demonstrates how to export an image of the imported geometry
+and display it using matplotlib.
+"""
+
+# %%
+# Import the necessary libraries
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+from pathlib import Path
+
+from ansys.mechanical.core import App
+from ansys.mechanical.core.examples import delete_downloads, download_file
+
+# %%
+# Initialize the embedded application
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Create an instance of the App class
+app = App()
+
+# Update the global variables
+app.update_globals(globals())
+
+# Print the app to ensure it is working
+print(app)
+
+# %%
+# Download and import the geometry file
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# %%
+# Download the geometry file
+geometry_path = download_file("Valve.pmdb", "pymechanical", "embedding")
+
+# %%
+# Import the geometry file
+
+geometry_import = Model.GeometryImportGroup.AddGeometryImport()
+geometry_import.Import(geometry_path)
+
+# %%
+# Configure graphics for image export
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Set the orientation of the camera
+ExtAPI.Graphics.Camera.SetSpecificViewOrientation(ViewOrientationType.Iso)
+
+# Set the image export format
+image_export_format = GraphicsImageExportFormat.PNG
+
+# Configure the export settings for the image
+settings_720p = Ansys.Mechanical.Graphics.GraphicsImageExportSettings()
+settings_720p.Resolution = GraphicsResolutionType.EnhancedResolution
+settings_720p.Background = GraphicsBackgroundType.White
+settings_720p.Width = 1280
+settings_720p.Height = 720
+settings_720p.CurrentGraphicsDisplay = False
+
+# Rotate the geometry on the Y-axis
+Graphics.Camera.Rotate(180, CameraAxisType.ScreenY)
+
+# %%
+# Create a function to display the image
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+from matplotlib import image as mpimg
+from matplotlib import pyplot as plt
+
+# Directory to save the image
+output_path = Path.cwd() / "out"
+
+
+def display_image(image_name) -> None:
+    """Display the image using matplotlib.
+
+    Parameters
+    ----------
+    image_name : str
+        The name of the image file to display.
+    """
+    # Create the full path to the image
+    image_path = output_path / image_name
+
+    # Plot the figure and display the image
+    plt.figure(figsize=(16, 9))
+    plt.imshow(mpimg.imread(str(image_path)))
+    plt.xticks([])
+    plt.yticks([])
+    plt.axis("off")
+    plt.show()
+
+
+# %%
+# Export and display the image
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Fit the geometry in the viewing area
+Graphics.Camera.SetFit()
+
+# Export the image
+geometry_image = output_path / "geometry.png"
+Graphics.ExportImage(str(geometry_image), image_export_format, settings_720p)
+
+# Display the image
+display_image(geometry_image.name)
+
+# %%
+# Clean up the downloaded files and app
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Delete the downloaded files
+delete_downloads()
+
+# Close the app
+app.close()

examples/00_tips/tips_03.py

@@ -0,0 +1,78 @@
+# Copyright (C) 2022 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+""".. _ref_tips_03:
+
+Project tree
+------------
+
+The following example demonstrates how to print the heirarchial Mechanical project structure.
+"""
+
+# %%
+# Import the necessary libraries
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+from ansys.mechanical.core import App
+from ansys.mechanical.core.examples import delete_downloads, download_file
+
+# %%
+# Initialize the embedded application
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+app = App(globals=globals())
+print(app)
+
+# %%
+# Download the mechdb file
+# ~~~~~~~~~~~~~~~~~~~~~~~~
+
+mechdb_path = download_file("graphics_test.mechdb", "pymechanical", "test_files")
+
+# %%
+# Load the mechdb file inside Mechanical
+
+app.open(mechdb_path)
+
+# %%
+# Display the project tree
+# ~~~~~~~~~~~~~~~~~~~~~~~~
+
+app.print_tree()
+
+# %%
+# Display the tree only under the first analysis
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+first_analysis = app.Model.Analyses[0]
+app.print_tree(first_analysis)
+
+
+# %%
+# Clean up the downloaded files and app
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# Delete the downloaded files
+delete_downloads()
+
+# Close the app
+app.close()