Overview of Python Scripting

What You Can Do with Python Scripting

The Python scripting features of Choreonoid enable you to do things such as the following.

  • Automating project construction tasks such as creating, loading, and arranging items

  • Processes related to models, such as setting the joint angles and the positions and postures of body models and performing kinematics calculations

  • Controlling the start and stop of simulations and executing processes in conjunction with simulations

  • Interactive operations and state checking on the Python console

  • Timer processing and building your own GUI using the Qt classes

By taking advantage of these features, you can streamline your work by scripting repetitive tasks, or execute simulations in a batch manner.

Components of the Features

The Python scripting features consist of the following components.

Python Bindings

These are the Python modules that make the major classes and functions of the Choreonoid C++ libraries available from Python. They are provided as a package named cnoid, which includes the following modules.

Module

Contents

cnoid.Util

The module corresponding to the Util library. It contains fundamental classes for coordinate transformations, interpolation, scene graphs, tasks, and so on.

cnoid.Base

The module corresponding to the Base module, which is the framework of the GUI. It contains GUI-related classes for items, views, project management, and so on.

cnoid.Body

The module corresponding to the Body library. It contains classes related to robot models such as body models, links, and devices.

cnoid.BodyPlugin

The module corresponding to the Body plugin. It contains classes such as body items and simulator items.

cnoid.QtCore / cnoid.QtGui / cnoid.QtWidgets

The modules corresponding to the major classes of the Qt libraries. Timers, widgets, and so on are available with them.

In addition to these, some plugins provide their own corresponding Python modules (cnoid.ODEPlugin, cnoid.MediaPlugin, etc.).

Python Plugin

This is the plugin that provides the functions for executing Python scripts on Choreonoid. When this plugin is loaded, a Python interpreter is started inside Choreonoid and works in cooperation with the functions of Choreonoid. Specifically, the following functions are provided.

PythonSimScript Plugin

This is the plugin that provides the Python Simulation Script for executing Python scripts in conjunction with simulations. Scripts can be executed at timings such as the start and end of a simulation.

Preparation for Using Python Scripting

The Python scripting features correspond to the CMake option ENABLE_PYTHON, and they become available by building Choreonoid with this option turned on. This option is ON by default on Ubuntu. Python itself (including the development libraries) and NumPy are required for the build. For the details of the build options, refer to Optional Features.

For how to build on Windows, refer to the section on the Python plugin in Building Optional Features of Building and Installing from Source Code (Windows).

Note that when the above option is enabled, the Python plugin and the PythonSimScript plugin are built together with the Python bindings.

Using the Modules from Python Outside Choreonoid

Among the modules of the Python bindings, those that do not depend on the GUI, such as cnoid.Util and cnoid.Body, can also be used from a regular Python interpreter without launching Choreonoid. For example, you can write a process such as loading a body model file and performing kinematics calculations as an independent Python program.

In this case, the directory where the Python modules are installed

[Choreonoid installation destination]/lib/choreonoid-x.y/python

must be added to the PYTHONPATH environment variable (x.y is the version number of Choreonoid). When the installation destination is other than /usr or /usr/local, this setting can also be made by sourcing the setup.bash script generated directly under the installation destination.

Once the setting is made, you can use the Choreonoid modules from regular Python as follows.

from cnoid.Body import *

loader = BodyLoader()
body = loader.load("SR1.body")
print(body.numJoints)