diff --git a/docs/sphinx/source/content/FirstSteps.rst b/docs/sphinx/source/content/FirstSteps.rst index 9efb32fef..5697879eb 100644 --- a/docs/sphinx/source/content/FirstSteps.rst +++ b/docs/sphinx/source/content/FirstSteps.rst @@ -8,29 +8,40 @@ Executing a simulation With runSofa ^^^^^^^^^^^^ -You can load a python based simulation directly in runSofa by using the command +💡 To make sure runSofa is able to load a scene described by a python, you can either: +* open runSofa without any argument once and then add libSofaPython3 in the plugin manager +* or add -l SofaPython3 in this command line. -.. code-block:: shell +For more information, please refer to the documentation: `What is a plugin > Plugin loading`_ + +Once the SofaPython3 plugin is loaded, you can load a simulation from a python script directly in runSofa. +Assuming you want to run a script named "example.py", you can run the following command: - runSofa examples/example1.py +.. code-block:: shell -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. + runSofa example.py -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(root : Sofa.Core.Node)`` function. This function is the entry point of your simulation and it 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 `_" 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 `_" 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 `_" 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 @@ -67,10 +78,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. + -In case you want to manage the simulation from the runSofa GUI, you can simply change the ``main()`` function as follows: +Using the SOFA GUI from a python environment +"""""""""""""""""""""""""""""""""""""""""""" + +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 @@ -85,10 +106,11 @@ 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 SofaImGui 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") + Sofa.Gui.GUIManager.Init("myscene", "imgui") Sofa.Gui.GUIManager.createGUI(root, __file__) Sofa.Gui.GUIManager.SetDimension(1080, 800) @@ -102,6 +124,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 `_ +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 `_ + + + Create a new simulation *********************** @@ -345,6 +380,7 @@ Here is the entire code of the scene : .. code-block:: python import Sofa + import SofaImGui import Sofa.Gui @@ -358,8 +394,8 @@ 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") + Sofa.Gui.GUIManager.Init("myscene", "imgui") Sofa.Gui.GUIManager.createGUI(root, __file__) Sofa.Gui.GUIManager.SetDimension(1080, 800) diff --git a/docs/sphinx/source/content/Installation.rst b/docs/sphinx/source/content/Installation.rst index f08fda875..9ce3f9ae1 100644 --- a/docs/sphinx/source/content/Installation.rst +++ b/docs/sphinx/source/content/Installation.rst @@ -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 `_ Get support diff --git a/docs/sphinx/source/content/UsingThePlugin.rst b/docs/sphinx/source/content/UsingThePlugin.rst index 88b95707d..45deee6e4 100644 --- a/docs/sphinx/source/content/UsingThePlugin.rst +++ b/docs/sphinx/source/content/UsingThePlugin.rst @@ -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 SofaImGui + import Sofa.Gui + Sofa.Gui.GUIManager.Init("myscene", "imgui") Sofa.Gui.GUIManager.createGUI(root, __file__) Sofa.Gui.GUIManager.SetDimension(1080, 800) @@ -415,6 +417,7 @@ Here is the entire code of the scene : .. code-block:: python import Sofa + import SofaImGui import Sofa.Gui @@ -428,8 +431,8 @@ 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") + Sofa.Gui.GUIManager.Init("myscene", "imgui") Sofa.Gui.GUIManager.createGUI(root, __file__) Sofa.Gui.GUIManager.SetDimension(1080, 800) @@ -644,6 +647,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 `_ 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 `_ and post there any question related to SofaPython3. To quickly level up on SOFA, never hesitate to request `SOFA training sessions `_.