Skip to content

Update documentation: ImGui, Qt, and Python env #522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bakpaul merged 7 commits into from
Jul 24, 2025
Merged

Update documentation: ImGui, Qt, and Python env #522

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
99389d4
Update documentation to explicit the use of ImGui and SOFA in Python
hugtalbot Jul 22, 2025
8d288c6
add description to use SofaQt
hugtalbot Jul 22, 2025
e5f203d
clarify and clean the installation section
hugtalbot Jul 22, 2025
aca8f2a
Rename example1 as example
hugtalbot Jul 22, 2025
492a9e0
Merge branch 'master' into 202507_update_doc_imgui
hugtalbot Jul 24, 2025
79507e0
simplify writing for ImGui use
hugtalbot Jul 24, 2025
01a9693
Apply suggestions from code review
hugtalbot Jul 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 52 additions & 19 deletions docs/sphinx/source/content/FirstSteps.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,35 @@ Executing a simulation
With runSofa
^^^^^^^^^^^^

You can load a python based simulation directly in runSofa by using the command
Making sure the SofaPython3 plugin is loaded, you can load a simulation described by a python script directly in runSofa.
Assuming you want to run a script named "example.py", you can run the following command:

.. code-block:: shell

runSofa examples/example1.py
runSofa example.py
Copy link
Copy Markdown
Contributor

@bakpaul bakpaul Jul 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we mention at one point the necessity to load SofaPython3 here ?
Add :

💡 To make sure runSofa is able to load a .py scene, either open runSofa without any argument once and add libSofaPython3 in the plugin manager or add -l SofaPython3 in this command line. For more information see link to 'using the plugin doc'


Let's now open ``examples/example1.py`` to have more insight.
The first important thin to notice is that the python script is importing modules called ``Sofa``, this module, and few other are containing
all SOFA specific component. Then the script is defining a ``createScene()`` function. This function is the entry point of your simulation and
is automatically called by the runSofa application when a python file is loaded.

We will look with more details in this ``createScene()`` but first let's how we can execute the same file without using ``runSofa``.
Let's now see how this script ``example.py`` should look like.
The first important thing to notice is that to be compatible with SOFA, a python script must define the ``createScene()`` function. This function is the entry point of your simulation and
is automatically called by the runSofa application when a python file is loaded. It is responsible for describing and building the SOFA scene graph.

In the section "`Create a new simulation <https://sofapython3.readthedocs.io/en/latest/content/FirstSteps.html#create-a-new-simulation>`_" below, we will detail how to implement this ``createScene()``.

With the python3 interpreter
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Before being able to execute a simulation from a python interpreter (including jupyter notebook) be sure you read the "`Setup your python3 environment <https://sofapython3.readthedocs.io/en/latest/content/Installation.html#using-python3>`_" section
so your python environment is properly configured and has access to the SOFA specific python modules.
SOFA simulation can also be executed from a python environment (including jupyter notebook).
To do so, the Python environment must be filled in for SOFA python modules.
Located in *site-packages/* repositories, the path to these libraries should be added to the ``PYTHONPATH``.
The section "`Setup your python3 environment <https://sofapython3.readthedocs.io/en/latest/content/Installation.html#using-python3>`_" section details how to configure it.

Once your python environment is properly configured, you will be able to import SOFA python modules (e.g. ``import Sofa``).
By running your simulation from a python interpreter, you will be responsible for:
* creating the root node
* before calling the ``createScene()`` function
* and later initializing the graph

When working a python3 interpreter, your simulation requires more than only the ``createScene()`` function.
Indeed, the python environment does not pre-generate a root node as the runSofa executable is.
One must therefore create it and then call the ``createScene()`` function:
To be run from a python environment, any python script should therefore look like:

.. code-block:: python

Expand Down Expand Up @@ -67,10 +73,20 @@ One must therefore create it and then call the ``createScene()`` function:
main()


By structuring your scripts this way, you get the advantage to have a script loadable from both runSofa and a python3 interpreter.
Note that the ``main()`` function runs 10 time steps without any graphical user interface and the script ends.
The above script can be run as follows:
.. code-block:: shell

python3 example.py

It can be noted that:
* by structuring your scripts this way, you get the advantage to have a script loadable from both runSofa and a python3 interpreter.
* in the above example, the ``main()`` function runs 10 time steps without any graphical user interface and the script ends.


Using the SOFA GUI from a python environment
""""""""""""""""""""""""""""""""""""""""""""

In case you want to manage the simulation from the runSofa GUI, you can simply change the ``main()`` function as follows:
In case you want to manage the simulation from the runSofa GUI, you can call the GUI from the ``main()`` function, as follows:

.. code-block:: python

Expand All @@ -85,10 +101,12 @@ In case you want to manage the simulation from the runSofa GUI, you can simply c
Sofa.Simulation.initRoot(root)

# Import the GUI package
import SofaRuntime
import Sofa.Gui

# Launch the GUI (qt or qglviewer)
Sofa.Gui.GUIManager.Init("myscene", "qglviewer")
# Launch the GUI (imgui is now by default, to use Qt please refer to the example "basic-useQtGui.py")
SofaRuntime.importPlugin("SofaImGui")
Sofa.Gui.GUIManager.Init("myscene", "imgui")
Sofa.Gui.GUIManager.createGUI(root, __file__)
Sofa.Gui.GUIManager.SetDimension(1080, 800)

Expand All @@ -102,6 +120,19 @@ So far, you can load this python scene, but it doesn't do much. Let's enrich thi
A scene in SOFA is an ordered tree of nodes representing objects (example of node: hand), with parent/child relationship (example of hand's child: finger). Each node has one or more components. Every node and component has a name and a few features. The main node at the top of the tree is usually called "rootNode" or "root". More about how to create a simulation scene can be found in the `SOFA online documentation <https://www.sofa-framework.org/community/doc/using-sofa/lexicography/>`_


Using the old Qt GUI
""""""""""""""""""""

Since SOFA v25.06, SOFA GUI relies on the ImGui library. The previous Qt-based GUI is still available. To use it, make sure to:

* add the *lib/* repository in the SOFA binaries to your ``LD_LIBRARY_PATH``
* add the *lib/python3/site-packages/* repository to your ``PYTHONPATH``
* make sure your SOFA install path does not include any special character

An example using the Qt GUI is available: `basic-useQtGUI.py <https://github.com/sofa-framework/SofaPython3/blob/master/examples/basic-useQtGUI.py>`_



Create a new simulation
***********************

Expand Down Expand Up @@ -345,6 +376,7 @@ Here is the entire code of the scene :
.. code-block:: python

import Sofa
import SofaRuntime
import Sofa.Gui


Expand All @@ -358,8 +390,9 @@ Here is the entire code of the scene :
# Once defined, initialization of the scene graph
Sofa.Simulation.initRoot(root)

# Launch the GUI (qt or qglviewer)
Sofa.Gui.GUIManager.Init("myscene", "qglviewer")
# Launch the GUI (imgui is now by default, to use Qt please refer to the example "basic-useQtGui.py")
SofaRuntime.importPlugin("SofaImGui")
Sofa.Gui.GUIManager.Init("myscene", "imgui")
Sofa.Gui.GUIManager.createGUI(root, __file__)
Sofa.Gui.GUIManager.SetDimension(1080, 800)

Expand Down
16 changes: 3 additions & 13 deletions docs/sphinx/source/content/Installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,20 +130,10 @@ Before running your simulations, you must make sure to define the following envi
After that, all you need to do is open a Console (cmd.exe) and run: ``runSofa -lSofaPython3``


It must be noted that depending on the plugins you use, you might have to add the *site-packages/* paths associated to these plugins to your ``PYTHONPATH``.
These are usually located in */path_to_plugin/lib/python3/site-packages*.

It is possible to use SOFA in any python3 interpreter.
The following code should cover most basic SOFA elements:

.. code-block:: python

# to be able to create SOFA objects you need to first load the plugins that implement them.
# For simplicity you can load the plugin "Sofa.Component" that will load all most
# common sofa objects.
import SofaRuntime
SofaRuntime.importPlugin("Sofa.Component")

# to create elements like Node or objects
import Sofa.Core
To discover, how to use SOFA in any python3 interpreter, please refer to the associated `FirstSteps section <https://sofapython3.readthedocs.io/en/latest/content/FirstSteps.html#with-the-python3-interpreter>`_


Get support
Expand Down
14 changes: 9 additions & 5 deletions docs/sphinx/source/content/UsingThePlugin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,8 +221,10 @@ By structuring your scripts this way, you get the advantage to have a script loa
# Once defined, initialization of the scene graph
Sofa.Simulation.init(root)

# Launch the GUI (qt or qglviewer)
Sofa.Gui.GUIManager.Init("myscene", "qglviewer")
# Launch the GUI (imgui is now by default, to use Qt please refer to the example "basic-useQtGui.py")
import SofaRuntime
SofaRuntime.importPlugin("SofaImGui")
Sofa.Gui.GUIManager.Init("myscene", "imgui")
Sofa.Gui.GUIManager.createGUI(root, __file__)
Sofa.Gui.GUIManager.SetDimension(1080, 800)

Expand Down Expand Up @@ -415,6 +417,7 @@ Here is the entire code of the scene :
.. code-block:: python

import Sofa
import SofaRuntime
import Sofa.Gui


Expand All @@ -428,8 +431,9 @@ Here is the entire code of the scene :
# Once defined, initialization of the scene graph
Sofa.Simulation.init(root)

# Launch the GUI (qt or qglviewer)
Sofa.Gui.GUIManager.Init("myscene", "qglviewer")
# Launch the GUI (imgui is now by default, to use Qt please refer to the example "basic-useQtGui.py")
SofaRuntime.importPlugin("SofaImGui")
Sofa.Gui.GUIManager.Init("myscene", "imgui")
Sofa.Gui.GUIManager.createGUI(root, __file__)
Sofa.Gui.GUIManager.SetDimension(1080, 800)

Expand Down Expand Up @@ -644,6 +648,6 @@ Do not hesitate to take a look and get inspiration!
Get support
***********

To freely get technical assistance from the community, please do not hesitate to join the `SofaPython3 GitHub forum <https://github.com/sofa-framework/sofapython3/discussions>`_ and post there any question related to SofaPython3.
To freely get technical assistance from the community, please do not hesitate to join the `SofaPython3 GitHub forum <https://github.com/sofa-framework/sofa/discussions/categories/sofapython3>`_ and post there any question related to SofaPython3.

To quickly level up on SOFA, never hesitate to request `SOFA training sessions <https://www.sofa-framework.org/sofa-events/sofa-training-sessions/>`_.
Loading