Python Plugin¶
Overview¶
The Python plugin (PythonPlugin) is a plugin that makes the Python programming language available on Choreonoid.
The C++ libraries of Choreonoid have Python bindings, and by importing modules such as cnoid.Base and cnoid.Body from Python, you can write operations on project items and various processes using body models in Python. This plugin provides the following functions for executing such Python scripts on Choreonoid.
Python script item (PythonScriptItem)
An item corresponding to Python script files (.py). Load it from the main menu with “File” - “Load” - “Python Script”.
Scripts are executed from the context menu displayed by right-clicking this item on the item tree view. The context menu has the “Execute” and “Terminate” entries added, with which you can execute the script at any time and terminate a running script.
In addition, when the “Execution on project loading” property is set to true, the script is automatically executed when the project is loaded. This is convenient for scripting the initialization processes of projects.
Python console view (PythonConsoleView)
A console for interactively executing Python on Choreonoid. It can be shown from the main menu with “View” - “Show View” - “PythonConsoleView”. You can enter and execute Python code on the spot to check and manipulate the states of items and models.
As a related plugin, the PythonSimScript plugin (PythonSimScriptPlugin) is also built together. It provides the Python simulation script (PythonSimScript item) that is executed in conjunction with simulations, which allows scripts to be executed at timings such as the start of a simulation.
Item Properties¶
The following properties are available in the Python script item.
Property |
Default value |
Meaning |
|---|---|---|
Script |
— |
The file name of the loaded script (display only). |
Execution on project loading |
false |
When set to true, the script is automatically executed when the project is loaded. |
Background execution |
false |
When set to true, the script is executed in the background in a thread separate from the main thread. GUI operations are not blocked even by time-consuming scripts. |
Individual namespace |
false |
When set to true, the script is executed in an independent namespace. Use this when you do not want to share variables etc. with other scripts or the Python console. |
In the PythonSimScript item, the following properties are available in addition to the background execution and individual namespace properties above.
Property |
Default value |
Meaning |
|---|---|---|
Timing |
After init. |
Selects the timing of executing the script from “Before init.”, “During init.”, “After init.”, “During final.”, and “After final.”. The execution timing is determined relative to the initialization and finalization of the simulation. |
Delay |
0.0 |
The delay time from the above timing [s]. |
Simulation only |
true |
When true, the script is executed only at the timing linked with simulations. When set to false, manual execution with “Execute” in the context menu also becomes possible. |
How to Build¶
The Python support corresponds to the CMake option ENABLE_PYTHON, which is ON by default on Ubuntu. Python itself (including the development libraries) and NumPy are required for the build.
For how to build on Windows, refer to the Python plugin section in Building Optional Features of Building and Installing from Source Code (Windows).
How to Use¶
For the details of the Choreonoid Python modules (Python bindings) that can be used for writing scripts, you can import each module on the Python console and check them with the help() function, and the sample scripts ( sample/python/ ) are also good references.