Python Script Item

What is the Python Script Item

The Python script item (PythonScriptItem) is an item corresponding to a Python script file (.py). It allows you to manage script files as project items and execute them with GUI operations. Since the item is saved as part of the project, scripts related to a project can be managed together with the project.

Loading Scripts

A script file is loaded from the main menu with “File” - “Load” - “Python Script”. When loaded, an item corresponding to the script file is added to the item tree.

It is also possible to load a script as an item with a command line option when launching Choreonoid. Refer to Executing Scripts from the Command Line for this.

Executing Scripts

Scripts are executed from the context menu displayed by right-clicking the item on the item tree. 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.

The output of the script (the output of print, error messages, etc.) is displayed on the message view.

In addition, if you show the “ScriptBar” toolbar, you can execute all the checked script items at once by pressing its button. Toolbars can be shown from the main menu with “View” - “Show Toolbar”.

Automatic Execution when Loading a Project

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.

Background Execution

Scripts are normally executed on the main thread (the thread of the GUI). Therefore, when a script that takes a long time is executed, GUI operations are blocked during the execution. When the “Background execution” property is set to true, the script is executed on a thread separate from the main thread, and GUI operations remain possible during the execution.

However, note the following points about background execution.

Delegate GUI-related processes to the main thread

Directly manipulating GUI-related objects (items, views, widgets, etc.) from the background execution thread is not thread-safe and can cause crashes or other problems. Manipulating items also falls under this category, because it can trigger processes such as updating the display of views on the same thread via signals.

If you want to perform such processes in a script executed in the background, delegate the processes to the main thread using the callLater or callSynchronously function of the cnoid.Base module.

from cnoid.Base import *

def updateItems():
    ...  # write the GUI-related processes here

callLater(updateItems)

callLater requests the main thread to execute the process and returns immediately. On the other hand, callSynchronously waits until the process is completed on the main thread before returning.

Termination with “Terminate” is not always possible

A script running in the background can be interrupted with “Terminate” in the context menu. This termination is implemented by throwing an exception for termination into the thread executing the script. Since this exception is processed at the timing when the script is executing Python code, the termination may not be possible in cases such as when the script is blocking for a long time inside a call of a function implemented in C++ or other languages.

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 on 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.