Update the Omniverse module docs (#431)

doc/source/user_guide/omniverse_info.rst

@@ -17,20 +17,10 @@ ansys.tools.omniverse.dsgui kit extensions.
 The Python API is defined here: :class:`Omniverse<ansys.pyensight.core.utils.omniverse.Omniverse>`.
 
 
-Omniverse System Configuration
-------------------------------
-
-To use this functionality, a local installation of Omniverse is required.
-Please `install Omniverse <https://docs.omniverse.nvidia.com/install-guide/>`_ along
-with one application like "Create" or "View" on your local system before
-attempting to use this interface.
-
-
 PyEnSight and EnSight Python API
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
 
-The ``omniverse`` pyensight module will look for and leverage locally installed
-Omniverse to provide its APIs. If you are using the
+If you are using the
 `ansys-pyensight-core <https://pypi.org/project/ansys-pyensight-core/>`_ module
 in your own python, one can just use the API like this:
 
@@ -40,9 +30,9 @@ in your own python, one can just use the API like this:
     s = LocalLauncher(batch=False).start()
     s.load_example("waterbreak.ens")
     # Start a new connection between EnSight and Omniverse
-    uri = "omniverse://localhost/Users/water"
-    s.ensight.utils.omniverse.create_connection(uri)
-    # Do some more work...
+    directory = "/omniverse/examples/water"
+    s.ensight.utils.omniverse.create_connection(directory)
+    # Do some work...
     # Push a scene update
     s.ensight.utils.omniverse.update()
 
@@ -52,9 +42,10 @@ in your own python, one can just use the API like this:
     The ``batch=False`` option used in the examples causes the EnSight
     GUI to be displayed together with the Omniverse Composer GUI.
 
-    Also, care must be taken to close the EnSight session before
-    exiting an Omniverse application hosting a PyEnSight session or is
-    it possible to leave the EnSight instance running.
+    It is possible to run a pyensight script from inside of an Omniverse
+    kit application.  In this case, care must be taken to close the EnSight
+    session before exiting the Omniverse application hosting the PyEnSight
+    session or is it possible to leave the EnSight instance running.
 
 
 From inside an EnSight session, the API is similar:
@@ -67,49 +58,50 @@ From inside an EnSight session, the API is similar:
     options = {"host": "127.0.0.1", "port": str(grpc_port)}
     if security:
         options["security"] = security
-    uri = "omniverse://localhost/Users/water"
-    ensight.utils.omniverse.create_connection(uri, options=options)
+    directory = "/omniverse/examples/water"
+    ensight.utils.omniverse.create_connection(directory, options=options)
     # Do some more work...
     # Push a scene update
     ensight.utils.omniverse.update()
 
 
-After running the script, the scene will appear in the Nucleus tree view as
-``User/water``.  The file ``dsg_scene.usd`` can be loaded into Composer.  The
-``ensight.utils.omniverse.update()`` command can be used to update the
-USD data in Omniverse, reflecting any recent changes in the EnSight scene.
+After running the script, the scene will appear in any Omniverse kit tree view
+under the specified directory.  The file ``dsg_scene.usd`` can be loaded into
+Composer.  The ``ensight.utils.omniverse.update()`` command can be used to update
+the USD data in Omniverse, reflecting any recent changes in the EnSight scene.
 
 Starting with 2025 R1, one can also access Omniverse via an EnSight
 user-defined tool:
 
 .. image:: /_static/omniverse_tool.png
 
-This tool will only be available if EnSight detects an installed copy
-of Omniverse.  Clicking on "Connect to Omniverse" executes something
+Clicking on "Start export service" executes something
 similar to the previous Python snippet and the button will change to
-a mode where it just executes ``ensight.utils.omniverse.update()``.
+a mode where it just executes ``ensight.utils.omniverse.update()``
+when the "Export scene" button is clicked.
 
+.. note::
+    Several of the options are locked in once the service is started.
+    To change options like "Temporal", the service must often be stopped
+    and restarted using this dialog.
 
-PyEnSight/Omniverse kit from Within an Omniverse Application
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-To install the service (and the pyensight module) into an Omniverse
-application, one can install is via the third party extensions dialog.
-Select the ``Extensions`` option from the ``Window`` menu.  Select
-third party extensions and filter by ``ANSYS``.  Enabling the extension
-will install it, along with the ansys.pyensight.core module.
+PyEnSight/Omniverse kit from an Omniverse Kit Application
+---------------------------------------------------------
 
-.. image:: /_static/omniverse_extension.png
+To install the service into an Omniverse application, one can install
+it via the third party extensions dialog. Select the ``Extensions`` option
+from the ``Window`` menu.  Select third party extensions and filter
+by ``ANSYS``.  Enabling the extension will install the kit extension.
+The kit extension will find the most recent Ansys install and use the
+version of the pyensight found in the install to perform export
+operations.
 
-At this point, the same pyensight script run in the Omniverse
-``Script Editor`` panel can be used to connect to
-an EnSight session or the GUI panel can be used to connect to a
-copy of EnSight that was launched with the ``-grpc_server {port}``
-option specified.
+.. image:: /_static/omniverse_extension.png
 
 The ``ansys.tools.omniverse.dsgui`` kit includes a GUI similar to the
 EnSight 2025 R1 user-defined tool.  It allows one to select a
-target URI in Omniverse and the details of a gRPC connection
+target directory and the details of a gRPC connection
 to a running EnSight.  For example, if one launches EnSight with
 ``ensight.bat -grpc_server 2345``, then the uri:  ``grpc://127.0.0.1:2345``
 can to used to request a locally running EnSight to push the current
@@ -123,88 +115,67 @@ scene to Omniverse.
     ``git://github.com/ansys/pyensight.git?branch=main&dir=exts``.
 
 
-Developers: Running development builds
---------------------------------------
-
-There are several different ways for developers working on these
-features to debug and test them.  There is a command line approach
-perhaps more suited to the pyensight developer and there is an
-Omniverse tool GUI approach that can be useful when looking to
-develop/extend the UI kits.
-
+Developers: Running via the Command Line
+----------------------------------------
 
-From the Command Line
-^^^^^^^^^^^^^^^^^^^^^
+There is an omniverse_cli module included in the pyensight install.
+This module can be used to execute any service operation from the
+command line.  The Python included in the EnSight distribution
+includes this module as well. Assuming the pyensight repo has been
+cloned to: ``D:\repos\pyensight`` the following can be run in a
+Python virtual environment that was used to build the module and
+has it installed:
 
-Omniverse kits can be run as command line tools and
-the ``ansys.tools.omniverse.core`` is designed to support this mode
-of operation as well.  For this to work, one needs a copy of the
-pyensight wheel and the name of a ``kit`` executable. The pyensight wheel
-can be built by checking out the repo and building it. One can
-find the location of a kit via the ``Omniverse Launcher`` application
-using the ``Settings`` option:
-
-.. image:: /_static/omniverse_create_location.png
-
-Consider an example where the create app has been installed and the
-file ``C:\Users\user1\AppData\Local\ov\pkg\create-2023.2.5\kit.bat``
-exists.  A copy of the pyensight repo is located and built here:
-``D:\repos\pyensight``.  With these conditions, one can run the extension
-from the command line like this:
 
 .. code-block:: bat
 
-    cd "C:\Users\user1\AppData\Local\ov\pkg\create-2023.2.5"
-    .\kit.bat --ext-folder "D:\repos\pyensight\src\ansys\pyensight\core\exts" --enable ansys.tools.omniverse.core --/exts/ansys.tools.omniverse.core/help=1
+    cd "D:\repos\pyensight"
+    .\venv\Scripts\activate.ps1
+    python -m build
+    python -m pip install .\dist\ansys_pyensight_core-0.9.0.dev0-py3-none-any.whl
+    python -m ansys.pyensight.core.utils.omniverse_cli -h
 
 
-Will generate the following output in the logs:
+Will generate the following output:
 
 .. code-block::
-
-    ANSYS Tools Omniverse Core:: ansys.tools.omniverse.core-0.1.0
-      --/exts/ansys.tools.omniverse.core/help=1
-         Display this help.
-      --/exts/ansys.tools.omniverse.core/run=1
-         Run the server.
-      --/exts/ansys.tools.omniverse.core/omniUrl=URL
-         Omniverse pathname.  (default: omniverse://localhost/Users/test)
-      --/exts/ansys.tools.omniverse.core/dsgUrl=URL
-         Dynamic Scene Graph connection URL.  (default: grpc://127.0.0.1:5234)
-      --/exts/ansys.tools.omniverse.core/securityCode=TOKEN
-         Dynamic Scene Graph security token.  (default: )
-      --/exts/ansys.tools.omniverse.core/temporal=0|1
-         If non-zero, include all timeseteps in the scene.  (default: False)
-      --/exts/ansys.tools.omniverse.core/vrmode=0|1
-         If non-zero, do not include a camera in the scene.  (default: False)
-      --/exts/ansys.tools.omniverse.core/normalizeGeometry=0|1
-         If non-zero, remap the geometry to the domain [-1,-1,-1]-[1,1,1].  (default: False)
-
-
-Documenting the various kit command line options.  Using the ``run=1`` option will launch the server from
-from the command line.  This version of the service will be run using the version of the pyensight module
-installed in the specified ``--ext-folder``.  When run as above, the service will use the
-latest released of the ansys.pyensight.core wheel.  It is important the the ``--ext-folder`` option
-point to the ``exts`` directory inside of the ``ansys\pyensight\core`` directories as this will
-cause the kit to use the ``ansys.tools.omniverse.core`` module from the directories above the kit
-instead of the any version installed in the kit Python itself.
-
-
-From an Omniverse Application GUI
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This approach is very similar to the CLI approach in that one needs to get the GUI application
-to use the kit from either a source code checkout or perhaps from a local EnSight install.
-In either case, the key point is to add the same directory pointed out earlier to the GUI application.
-
-For example, if one has a copy of the pyensight repo checked out as in the previous CLI example, the
-key directory will be ``D:\repos\pyensight\src\ansys\pyensight\core\exts``.  This pathname can be
-added to the extensions path in an application like "Composer" through this GUI:
-
-.. image:: /_static/omniverse_app_paths.png
-
-With the path in place, the kits will show up in the Third-party extensions list and can be
-activated in the GUI.
-
-.. image:: /_static/omniverse_app_exts.png
+    usage: omniverse_cli.py [-h] [--verbose verbose_level] [--log_file log_filename] [--dsg_uri DSG_URI]
+                            [--security_token token] [--monitor_directory glb_directory] [--time_scale time_scale]
+                            [--normalize_geometry yes|no|true|false|1|0] [--include_camera yes|no|true|false|1|0]
+                            [--temporal yes|no|true|false|1|0] [--oneshot yes|no|true|false|1|0]
+                            destination
+
+    PyEnSight Omniverse Geometry Service
+
+    positional arguments:
+      destination           The directory to save the USD scene graph into.
+
+    options:
+      -h, --help            show this help message and exit
+      --verbose verbose_level
+                            Enable logging information (0-3). Default: 0
+      --log_file log_filename
+                            Save logging output to the named log file instead of stdout.
+      --dsg_uri DSG_URI     The URI of the EnSight Dynamic Scene Graph server. Default: grpc://127.0.0.1:5234
+      --security_token token
+                            Dynamic scene graph API security token. Default: none
+      --monitor_directory glb_directory
+                            Monitor specified directory for GLB files to be exported. Default: none
+      --time_scale time_scale
+                            Scaling factor to be applied to input time values. Default: 1.0
+      --normalize_geometry yes|no|true|false|1|0
+                            Enable mapping of geometry to a normalized Cartesian space. Default: false
+      --include_camera yes|no|true|false|1|0
+                            Include the camera in the output USD scene graph. Default: true
+      --temporal yes|no|true|false|1|0
+                            Export a temporal scene graph. Default: false
+      --oneshot yes|no|true|false|1|0
+                            Convert a single geometry into USD and exit. Default: false
+
+
+Documenting the various command line options.  To start the server, specify the ``destination`` directory
+where the resulting USD files should be saved and provide the correct URI to the ``--dsg_uri`` option
+needed to connect to the EnSight DSG server.  The service will continue to monitor the EnSight
+session, pushing geometry updated as specified by the EnSight session until the EnSight session
+is stopped.  If only a single download/conversion is desired, the ``--oneshot 1`` option may be specified.
 

exts/ansys.tools.omniverse.core/config/extension.toml

@@ -1,6 +1,6 @@
 [package]
 # Semantic Versioning is used: https://semver.org/
-version = "0.1.0"
+version = "0.8.10"
 
 # Lists people or organizations that are considered the "authors" of the package.
 authors = ["ANSYS"]

exts/ansys.tools.omniverse.core/docs/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [0.8.10] - 2024-09-17
+- Update for new pyensight Omniverse interface
 
 ## [0.1.0] - 2024-07-30
 - First version

exts/ansys.tools.omniverse.core/docs/README.md

@@ -1,11 +1,9 @@
 # ANSYS Tools Omniverse Core [ansys.tools.omniverse.core]
 
 The Omniverse extension provides a dynamic connection between an ANSYS
-geometry source (e.g. ANSYS EnSight) and an Omniverse instance.  The
-connection runs as a standalone service capable of supporting scripted
-execution utilizing just a kit CLI.  It can also be launched via
-PyEnSight and via a simple GUI provided by the [ansys.tools.omniverse.dsgui]
-kit extension.
+geometry source (e.g. ANSYS EnSight) and an Omniverse instance. It can
+also be launched via pyensight and via a simple GUI provided by
+the [ansys.tools.omniverse.dsgui] kit extension.
 
 For more details on this extension see:
 https://ensight.docs.pyansys.com/version/dev/user_guide/omniverse_info.html

exts/ansys.tools.omniverse.dsgui/config/extension.toml

@@ -1,6 +1,6 @@
 [package]
 # Semantic Versioning is used: https://semver.org/
-version = "0.1.0"
+version = "0.8.10"
 
 # Lists people or organizations that are considered the "authors" of the package.
 authors = ["ANSYS"]

exts/ansys.tools.omniverse.dsgui/docs/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [0.8.10] - 2024-09-17
+- Update for new pyensight Omniverse interface
 
 ## [0.1.0] - 2024-07-30
 - First version

exts/ansys.tools.omniverse.dsgui/docs/README.md

@@ -4,7 +4,7 @@ This Omniverse extension is a UI interface to the [ansys.tools.omniverse.core]
 kit extension.  It allows an Omniverse application user to connect to
 a running copy of ANSYS EnSight or other application that supports the
 Dynamic Scene Graph gRPC protocol.  The GUI allows for the remote scene
-to be pulled, on request,  into a specified Omniverse location.
+to be pulled, on request, into a specified location in USD format.
 
 
 For more details on this extension see:

src/ansys/pyensight/core/utils/omniverse.py

@@ -44,7 +44,7 @@ class Omniverse:
     >>> from ansys.pyensight.core import LocalLauncher
     >>> session = LocalLauncher().start()
     >>> ov = session.ensight.utils.omniverse
-    >>> ov.create_connection()
+    >>> ov.create_connection(r"D:\Omniverse\Example")
     >>> ov.update()
     >>> ov.close_connection()
 
@@ -202,8 +202,8 @@ def create_connection(
         Parameters
         ----------
         omniverse_path : str
-            The URI to the Omniverse server. It will look like this:
-            "omniverse://localhost/Users/test"
+            The directory name where the USD files should be saved. For example:
+            "C:/Users/test/OV/usdfiles"
         include_camera : bool
             If True, apply the EnSight camera to the Omniverse scene.  This option
             should be used if the target viewer is in AR/VR mode.  Defaults to False.