Skip to content

Commit 340f862

Browse files
fferrifferri
committed
python client page
1 parent bf30540 commit 340f862

File tree

1 file changed

+73
-29
lines changed

1 file changed

+73
-29
lines changed

‎en/pythonClient.htm

+73-29
Original file line numberDiff line numberDiff line change
@@ -17,46 +17,69 @@
1717

1818

1919

20-
<h1>CoppeliaSim's library and Python client</h1>
20+
<a name="lib"></a>
21+
<h1>CoppeliaSim's library</h1>
2122

2223
<p>CoppeliaSim offers a wide range of functionalities via its graphical user interface. For more customized scenarios where fine-grained control of the simulation(s) loop is required (e.g. reinforcement learning), it also offers the flexibility to be used as a library within custom programs.</p>
2324

24-
<p>Using CoppeliaSIm as a library consists of the following steps:</p>
25+
<p>Using CoppeliaSim as a library consists of the following steps:</p>
2526

2627
<ol>
27-
<li>Loading the CoppeliaSim's library (coppeliaSim.dll / libcoppeliaSim.so / libcoppeliaSim.dylib) via the specific function (dlopen() on POSIX or LoadLibrary() on Win32).</li>
28+
<li>Loading the CoppeliaSim's library:
29+
<ul>
30+
<li>Windows: <code>LoadLibrary("coppeliaSim.dll")</code></li>
31+
<li>Linux: <code>dlopen("libcoppeliaSim.so")</code></li>
32+
<li>macOS: <code>dlopen("libcoppeliaSim.dylib")</code></li>
33+
</ul>
34+
</li>
35+
36+
<li>Creating a secondary (SIM) thread (this step is mandatory) and in the secondary thread:
37+
<ol>
38+
<li>call <code>simInitialize</code> to initialize.</li>
39+
<li>any other coppeliaSim API functions, and/or call <code>simLoop</code> until <code>simGetExitRequest</code> returns false</li>
40+
<li>call <code>simDeinitialize</code> before termination.</li>
41+
</ol>
42+
</li>
43+
44+
<li>On the main (UI) thread: call the <code>simRunGui</code> function (this step is mandatory, also when running headless, i.e. without GUI). Argument to <code>simRunGui</code> can be used to toggle on/off individual part of the interface (use <code>sim_gui_all</code> to enable all), or to run in headless mode (<code>sim_gui_headless</code>).</li>
45+
</ol>
2846

29-
<li>Creating a secondary (SIM) thread (as of current version, this step is mandatory) and in the secondary thread execute:
30-
<ol>
31-
<li>simInitialize</li>
32-
<li>any other coppeliaSim API functions, or simply simLoop until simGetExitRequest returns false</li>
33-
<li>simDeinitialize.</li>
34-
</ol>
35-
</li>
47+
<a name="pythonClient"></a>
48+
<h1>Python client</h1>
3649

37-
<li>On the main (UI) thread: call the simRunGui function (as of current version, this step is mandatory, also when running headless, i.e. without GUI).</li>
38-
</ol>
50+
<p>A complete working example of loading the CoppeliaSim library in Python is given in <a href="https://github.com/CoppeliaRobotics/coppeliaSimClientPython">coppeliaSimClientPython</a>.</p>
3951

40-
<h3>Python client application</h3>
52+
<p>In this section, relevant parts are explained.</p>
4153

42-
<p>A complete working example of loading the CoppeliaSim library in Python using ctypes is given in <a href="https://github.com/CoppeliaRobotics/coppeliaSimClientPython">coppeliaSimClientPython</a>.</p>
54+
<h2>Initialization</h2>
4355

44-
<p>The coppeliaSim.bridge module provides seamless access to the regular API used by scripts, e.g.:</p>
56+
<p>Module <code>coppeliaSim.lib</code> handles the load and setup of core functions (<code>simInitialize</code>, <code>simDeinitialize</code>, etc...) via <code>ctypes</code>.</p>
4557

4658
<code class="hljs language-python coppelia-coppeliasim-script">
47-
import coppeliaSim.bridge
59+
import builtins
60+
import os
61+
import threading
4862

49-
# load the bridge compoennt:
50-
coppeliaSim.bridge.load()
63+
from ctypes import *
5164

52-
# fetch API objects:
53-
sim = coppeliaSim.bridge.require('sim')
65+
# set the path to the coppeliaSim's library:
66+
builtins.coppeliaSim_library = "/path/to/libcoppeliaSim.so"
5467

55-
# e.g.: use some API function:
56-
program_version = sim.getInt32Param(sim.intparam_program_full_version)
68+
# import the coppeliaSim's library functions:
69+
from coppeliaSim.lib import *
70+
71+
appDir = os.path.dirname(builtins.coppeliaSim_library)
72+
73+
# start the sim thread (see in the next section)
74+
t = threading.Thread(target=simThreadFunc, args=(appDir,))
75+
t.start()
76+
simRunGui(sim_gui_all) # use sim_gui_headless for headless mode
77+
t.join()
5778
</code>
5879

59-
<p>The default implementation of simThreadFunc simply executes the application until quit is requested:</p>
80+
<h2>SIM thread loop</h2>
81+
82+
<p>The basic implementation of simThreadFunc simply executes the application until quit is requested:</p>
6083

6184
<code class="hljs language-python coppelia-coppeliasim-script">
6285
def simThreadFunc(appDir):
@@ -66,12 +89,13 @@ <h3>Python client application</h3>
6689
simDeinitialize()
6790
</code>
6891

69-
<p>Another possible scenario would be to manually control the operations used to setup a simulation environment (e.g. sim.loadScene) and to execute a simulation, e.g. by manually stepping for a predetermined amount of steps:</p>
92+
<p>Another possible scenario would be to manually control the operations used to setup a simulation environment (e.g. <code>sim.loadScene</code>) and to execute a simulation, e.g. by manually stepping for a predetermined amount of steps:</p>
7093

7194
<code class="hljs language-python coppelia-coppeliasim-script">
7295
def simThreadFunc(appDir):
7396
simInitialize(c_char_p(appDir.encode('utf-8')), 0)
7497

98+
# script bridge, see next section
7599
import coppeliaSim.bridge
76100
coppeliaSim.bridge.load()
77101

@@ -82,7 +106,7 @@ <h3>Python client application</h3>
82106
simStart()
83107
for i in range(1000):
84108
t = sim.getSimulationTime()
85-
print(f'Simulation time: {t:.2f} [s] (simulation running synchronously to client, i.e. stepped)')
109+
print(f'Simulation time: {t:.2f} [s] (running in stepped mode)')
86110
simStep()
87111
simStop()
88112

@@ -104,15 +128,35 @@ <h3>Python client application</h3>
104128
simLoop(None, 0)
105129
</code>
106130

131+
<h2>coppeliaSim.bridge</h2>
132+
133+
<p>The <code>coppeliaSim.bridge</code> module provides seamless access to the regular API used by scripts, e.g.:</p>
134+
135+
<code class="hljs language-python coppelia-coppeliasim-script">
136+
import coppeliaSim.bridge
137+
138+
# load the bridge component:
139+
coppeliaSim.bridge.load()
140+
141+
# fetch API objects:
142+
sim = coppeliaSim.bridge.require('sim')
143+
144+
# e.g.: use some API function:
145+
program_version = sim.getInt32Param(sim.intparam_program_full_version)
146+
</code>
147+
148+
<br/>
149+
<br/>
150+
107151
<p>Please refer to <a href="https://github.com/CoppeliaRobotics/coppeliaSimClientPython/blob/main/main_with_ui.py">coppeliaSimClientPython/main_with_ui.py</a> for the complete code.</p>
108152

109153
<br>
110154
<br>
111155
</tr>
112-
</table>
113-
</div>
114-
115-
156+
</table>
157+
</div>
158+
159+
116160
<link rel="stylesheet" href="../js/hljs/11.8.0/styles/default.min.css" />
117161
<script src="../js/hljs/11.8.0/highlight.min.js"></script>
118162
<script src="../js/hljs/11.8.0/languages/cmake.min.js"></script>

0 commit comments

Comments
 (0)