Executing Scripts from the Command Line

Executing Scripts at Startup

You can have a Python script specified on the command line executed when Choreonoid starts up. When a file with the .py extension is specified on the command line, the script is executed at startup.

choreonoid sample/python/SR1Walk.py

In the above example, SR1Walk.py is executed on the launched Choreonoid, and the simulation of the project constructed by the script starts.

You can also specify a script file explicitly with the --python option (or its short form -p).

choreonoid --python script.py

Combining with Project Files

It is also possible to specify a script together with a project file.

choreonoid project.cnoid script.py

In this case, the script is executed after the project is loaded, so you can execute a script that manipulates the items contained in the project.

Using this, for example with the sample StartSimulationAndQuitWhenFinished.py introduced in Writing Python Scripts, you can execute a simulation in a batch manner as follows.

choreonoid project.cnoid sample/python/StartSimulationAndQuitWhenFinished.py

This command starts the simulation of the project, and Choreonoid also exits when the simulation finishes.

Headless Execution without Showing the Window

With the --no-window option, Choreonoid starts without showing the main window (for the basics of this mode, refer to Launch Mode without Showing the Window ). In this mode, the output to the message view is put to the standard output, so the execution status, such as the output of scripts and error messages, can be checked on the terminal. Combined with the execution of scripts, this makes it possible to use Choreonoid like a command line tool.

choreonoid --no-window project.cnoid script.py

Such headless execution can be utilized for purposes such as the following.

  • Batch execution of simulations

A series of processes — loading a project, executing a simulation, saving the results as log or motion data files, and exiting — can be performed fully automatically. Since no GUI rendering is performed, the execution overhead is also reduced.

  • Repeated execution under many conditions

By repeatedly launching Choreonoid from a shell script or the like, you can automatically execute many simulations while changing the parameters of the models and controllers, and collect the results. Environment variables and other means can be used to pass the execution conditions.

  • Automating processes on models and projects

Processes such as loading a model file and inspecting or converting its contents or performing kinematics calculations can be scripted and executed like a regular command.

  • Execution in remote environments without a GUI

Simulations can be executed in environments without a window system, such as computing servers and CI environments.

As described in Launch Mode without Showing the Window, in an environment where no window system is available, this mode is automatically enabled even if --no-window is not specified. Even in that case, the vision sensor simulation by GLVisionSimulator can be executed without a window system by the rendering using EGL, and the hardware acceleration by the GPU is also enabled. This means that simulations using camera images and range images can be executed as they are in an environment without a GUI.

Also keep the following points in mind for headless execution.

  • Rendering on the GUI, such as that of the scene view, is not performed. If you want to automate processes involving GUI rendering (such as obtaining the rendering results of the scene view) without showing windows, there is a way to use a virtual display. Refer to Running the GUI without Showing Windows Using a Virtual Display for this.

  • The following options can also be used together.

  • --start-simulation … Automatically starts the simulation at startup.

  • --test-mode … Exits Choreonoid at the point when an error occurs. This is useful for batch processing and test automation.

For example, the following command executes the simulation of the project without showing the window, and Choreonoid also exits when the simulation finishes.

choreonoid --no-window project.cnoid sample/python/StartSimulationAndQuitWhenFinished.py

Option to Load a Script as an Item

When the --python-item option is used, the script is not executed at startup but is loaded into the item tree as a Python script item.

choreonoid --python-item script.py

Since the loaded item is in the checked state, you can execute it by pressing the button of the ScriptBar. Refer to Python Script Item for the details.