Python 3 Scripting

Owned by Marc Lievin
Jul 24, 2023
21 min read



This section describes how to extend and add additional functionality by using the built in scripting tool.

Supported Use Case

The Dynamics Script Extension (Python 3) allows you to use the Python 3 programming language to modify the behaviour of dynamic elements of your simulation while it is running.

For example, if a mechanism consists of two parts that are constrained by a hinge, adding tension to that mechanism will not cause the hinge to break. However, a simple script that reads the tension and disables the constraint if it reaches a certain threshold will accurately simulate breaking the hinge.

A Dynamics Script is part of your content. The extension can be added to either a scene, mechanism or assembly document.

Basic Concepts

Python Interpreter Support

The Dynamics Script extension makes it easy to work with a Python 3 interpreter installed on your system. Vortex Studio comes bundled with a default interpreter but if you want to use third party packages or a different Python distribution you should point your Vortex application
towards an external interpreter that you previously installed.

The only restriction is that the supported Python version is Python 3.8. The default interpreter currently bundled with Vortex Studio is 3.8.6.



Workflow

  1. (Optional) Setting the Python Interpreter

  2. Adding a Dynamics Script extension to your content

  3. Adding Fields

  4. Writing a Dynamics Script's Code



Setting the Python Interpreter

Refer to the following documentation for additional information on a Vortex application's setup file and how to modify it.

Vortex provides a default Python Interpreter. If you need your own, you can specify it at the root level of a setup document, under the container Python 3.

See Python 3 Scripting - Python Usage and Environment Configuration



Adding a Dynamics Script extension to your content

Prerequisites: If you need to use another Python 3 interpreter than the one bundled with Vortex Studio, follow the steps labelled Setting the Python Interpreter above.

  1. Launch the Vortex Studio Editor.

  2. Open your content file or create a new assembly, mechanism or scene.

  3. In the Toolbox panel, under the Scripting category, add a Dynamics Script extension.

  4. In the Properties panel, set the path to the script you want to use to the parameter Script Path.

Your script will be automatically analyzed and any syntax error will be reported to you as warnings on the extension.
Every time, you edit and save your script in your code editor, it will be reimported into Vortex.

Adding Fields

The most direct way to communicate between Vortex and your Python script is to use fields (inputs, outputs and parameters) on the Dynamics Script extension. Both the Vortex application and the Python script can access those fields.
But before accessing fields you must first add them to the extension.

Using the Vortex Studio Editor

Right click on the dynamics script extension and select "Edit"

In the window that appears you can add inputs, outputs and parameters to your script.



There are 3 field containers on each scripts,

  • Inputs

  • Outputs

  • Parameters

in Python access the fields using the syntax

"extension.inputs.field_name"

"extension.outputs.field_name"

"extension.parameters.field_name"

See code below as an example accessing fields created earlier.

Accessing fields in Python 3
def pre_step(extension): # The boolean input field in the screenshot above is named "boolean input" # Notice that spaces are replaced by underscores my_field = extension.inputs.boolean_input # my_field is a boolean input, you can read its value like so bool_value_of_my_field = my_field.value if bool_value_of_my_field: extension.outputs.an_output_double.value = 3.1415 else: parameter_number = extension.parameters.number.value extension.outputs.an_output_double.value = parameter_number

Using Python Code only

Fields can be created directly from Python code if you prefer.  The following code is functionally the same as the previous example.

Creating fields from a script in python 3
import Vortex def on_simulation_start(extension): # Creating an input of type boolean extension.createInput("boolean input", Vortex.Types.Type_Bool) # Creating an output of type double extension.createOutput("an output double", Vortex.Types.Type_Double) # Creating a parameter of type double extension.createParameter("number", Vortex.Types.Type_Double) def pre_step(extension): # The boolean input field we created on simulation start is named "boolean input" # Notice that spaces are replaced by underscores my_field = extension.inputs.boolean_input # my_field is a boolean input, you can read its value like so bool_value_of_my_field = my_field.value if bool_value_of_my_field: extension.outputs.an_output_double.value = 3.14159265359 else: parameter_number = extension.parameters.number.value extension.outputs.an_output_double.value = parameter_number



More information on creating and getting fields in python

The functions createInput(), createOutput() and createParameter() are utility functions each encapsulating a frequent use case of this API. There is several things to mention about these functions.

  • The new functions have the following signatures

    create field functions signatures

    def createInput(name, type, defaultValue = None, description = None, physicalDimension = None) def createParameter(name, type, defaultValue = None, description = None, physicalDimension = None) def createOutput(name, type, defaultValue = None, description = None, physicalDimension = None)



  • The available types for the parameter type are in Vortex.Types enumeration. If this parameter is an invalid value, this function will fail. 

  • The available types for the parameter physicalDimension are in Vortex.VxPhysicalDimension enumeration. By default, Vortex will assign a value corresponding to VxSim.VxPhysicalDimension.kNone to fields whose physical dimension are not defined. This means the function getPhysicalDimension() will never return None even if explicitly declared in the call to createInput(), createOutput() or createParameter(). This behavior also is consistent with the addInput(), addParameter(), addOutput() functions.

  • The functions createInput() and createParameter() ignore the parameter defaultValue if the field already exists. This allows experimenting with different values in the editor's interface without having to change the script.

  • The function createOutput() reset the output field's value to defaultValue even if the field already exists. This behavior is different from createInput() and createParameter().

Each function follows the pseudo code presented in the following code snippet.

create field functions pseudo-code

Writing a Dynamics Script's Code

The Dynamics Script extension supports the Python 3 programming language and gives the user access to all the rich features of this language.

Available Callbacks

Function

Description

Parameters

Function

Description

Parameters

on_simulation_start(extension)

Called when the application mode changes from editing to simulating.

extension: The DynamicsScript extension referring to this script.

on_simulation_stop(extension)

Called when the application mode changes from simulating to editing.

extension: The DynamicsScript extension referring to this script.

pre_step(extension)

Equivalent to IDynamics::preStep. Called before the collision detection and the dynamic solver.

extension: The DynamicsScript extension referring to this script.

post_step(extension)

Equivalent to IDynamics::postStep. Called after the collision detection and after the dynamic solver.

extension: The DynamicsScript extension referring to this script.

paused_update(extension)

Equivalent to IDynamics::pausedUpdate. Called at every update in editing mode and when the
simulation is paused.

extension: The DynamicsScript extension referring to this script.

on_keyframe_save(extension, data)

Equivalent to IExtension::onStateSave.

extension: The DynamicsScript extension referring to this script.

data: A dictionary object in which you can save additional arbitrary data.

on_keyframe_restore(extension, data)

Equivalent to IExtension::onStateRestore.

extension: The DynamicsScript extension referring to this script.

data: A dictionary object from which you can restore the additional arbitrary data
saved in the on_keyframe_save function.

Code template

Below is a sample code that can be used as a template for any dynamics script extension.

Template





Available helper functions to write scripts

The Application Context

To get information relative to the application context, use getApplicationContext(). The method is available via the extension in dynamics Python scripts extension. Application context API is relatively simple and can be used for time/frame based related logic.

The Application Context



VxMath::Transformation

A series of global helpers exists at the VxSim level to simplify matrix computation. They are the equivalent of the C++ Global helpers in namespace VxMath::Transformation.

Transformation Helpers

Accessing Contact Data 

With Python 3, contacts generated during the simulation can now be accessed in a Dynamics Script Extension. By calling the function getDynamicsContacts() as shown below, the DynamicsContactCollection is returned. This structure has two useful member functions, __len__(), which returns the number of contacts, and __iter__() which implements a Python iterator on the collection. This can be used as shown below to examine various properties of each contact that has been generated.

Accessing Contacts

Two sets of get functions are available, the first set returns information relevant to the contact interaction, allowing examination of the position and normal direction, as well as the primary and secondary friction directions at the contact point.

Contact Data

The second set returns information for each part involved in the contact interaction, allowing examination of the contact force and torque on each part. These functions take a partID as an argument, which is just an integer labeling each part involved.

Part Data

Getting the full Vortex.py documentation

If you wish to see more of the Vortex API you can generate the pydoc. Simply open a command-line tool in the bin folder of your vortex installation and run the following command:

python -m pydoc -w Vortex Vortex.html

The file Vortex.html will be generated in the bin folder and you can browse an up-to-date list of all the functions available in the Vortex API.

 Using the Python Output Window

In the editor, a new window was added to help you see what is happening in your Python scripts

The Python Output panel is a text box where the output of all of your scripts is written. Any print statement in your script will print in this window and any error in execution will also show.

Make sure that you turn on the listening mode:

Now if you introduce an error in your code

If you want to know which script is the culprit for the error, you can click the error message and then the "bulls-eye"  to locate the extension with the error in the explorer tree or click the open source script icon to open the text file directly.

You can also use the print statement:





Example: Writing a simple script to automatically change the gears of a car

For convenience, this example starts with the sample file that you can find in this location: C:\CM Labs\Vortex Studio Content <version>\Samples\Vehicles\Car - Sedan\Car - Sedan.vxmechanism

Add a Dynamics Script to the mechanism

  1. Next to the mechanism file, create an empty text file and name it control.py

  2. In the toolbox, locate the Dynamics Script extension and add it to the mechanism 





  3. In the properties panel, set the Script Path to the empty script you created at step 1. 

  4. Now to add inputs and outputs to the script extension. Find the extension in the explorer tab, right-click it → edit

    1. Add an input

      1. rpm - double

    2. Add 3 outputs,

      1. engine - boolean

      2. throttle - double

      3. gear - int

    3. Add a parameter

      1. redline - double

  5. You should have something like this:

  6. Press Ok to confirm your fields



Now, your script extension should appear as follow:

Writing the code to start the car

  1. Open the file control.py, that you created, with any code editor of your choice

  2. Start by adding code that will be run when we start the simulation 



    1. control.py



  3. Run the simulation, see the output fields values change

  4. Nothing happens to the car!

  5. We have to connect the outputs of the script to the vehicle interface

    1. Add a connection container

    2. connect all the fields of the dynamics script to the corresponding fields of the vehicle interface

Run the simulation again, the car moves and starts driving forward but it doesn't change gear, see the rpm maxed out at 6500:

Changing gears at runtime whenever we hit the rpm redline

  1. Set the dynamics script redline parameter value to 6000

  2. We will add the pre_step method, this callback is called every before every physics update of the simulation

    control.py



  3.  Press play and look at what happens

    1. We gear up a lot as soon as we hit 6000rpm, the pre_step method is called 60 times per second by default, sometimes its too quick for our needs. Something needs to be corrected so we don't shift up more than once before the rpm drops.





  4. We want to add two things, first our car has only 6 gears, we should never gear up above this, second, we want to add a minimum time delay between each gear change

    control.py



  5. The final script should look like this:

    control.py



Now, if you play the simulation, you will have a car that accelerates and gears up gradually, also you will find out that this sedan is very very fast easily reaching over 300km/h!



Accessing an Extension's Fields via Python

In some cases you may want to access a field, or a nested field of an extension via a Python script. An extension's inputs, outputs, and parameters can be accessed by passing their name (as a string) into one of the following functions:

  • extension.getInput('Example Name')

  • extension.getOutput('Example Name')

  • extension.getParameter('Example Name')

The value of that field can then be read or written-to by accessing it like so:

  • extension.getInput('Example Name').value

In some cases, the field that you would like to access may be nested inside of another field. Fields function as containers, and you can access fields within them via an integer-based index or a string-based key that represents the field's name.

For example, here the "Number Of Cables" field is contained within the "Cables" output:

It can be accessed via the following syntax:

control.py



Converting Python 2 scripts to Python 3 Dynamics Script

If you had existing Python 2 scripts in your content you can easily convert it to a Dynamics Script in a few steps.

This action does not convert the code itself, it only replaces the extension in the content. It ensures that the new extension has the same fields and that references are maintained. The code must be upgraded manually. There are some tips below.



Convert the extension to Dynamics Script

The first thing you will want to do is use the "Convert to Dynamics Script" action in the editor.

To do so, right-click on the desired script:

The "Convert to Dynamics Script" action will change the extension type of the Python 2 script to the Python 3 dynamics script extension.

Doing this will keep all the fields, connections, and references of the extension.



The Convert to Dynamics Script action will have created a duplicate version of your script file with the suffix _DynamicsScript or if the script was embedded there will be a new .py file in the folder next to the current document.

Converting multiples scripts

The editor API does not permit converting multiple scripts at once. It can be done using the Python API. For more information, see Python 3 API: Upgrading Vortex Files

Converting Python 2 code to Python 3

Here is an example code conversion that covers most cases for Vortex scripts, all changes are highlighted



Python 2 script

Python 3 conversion

Python 2 script

Python 3 conversion

























Converting Vortex script code

  1. Change import VxSim to import Vortex

    1. Change all uses of VxSim in the code to Vortex

  2. Change the callbacks to their new names

















  3. (optional) Replace the self identifier with extension

We recommend changing self to extension, because self refers to the current instance of a class. However, in the case of Vortex scripts, what you receive in each callback is really the Vortex extension.

We also recommend not using global variables. It is generally bad practice and might not be supported in future versions. Instead you should store all data in the extension that is given as a parameter in each callback.
This means replacing all uses of "global my_var" to "extension.my_var".

Note that we removed access to the "universe" parameter in the new script callbacks. This parameter was only used for rare cases such as creation of Intersection Sensors and Sensor Triggers. In the Python 3 API, the universe is no longer required in this case. For more information and python code examples refer to the Sensors documentation.

Converting generic Python code

This part is trickier, it depends on the complexity of your code, if your scripts are not too complex you probably do not require any code changes.

Here are two simple examples that you might see in your code:

  1. The print statement requires parentheses in Python 3.









  2. Integer division returns a float in Python 3, whereas it would always return an integer in Python 2

    1. 3/2 = 1 in Python 2

    2. 3/2 = 1.5 in Python 3

There are more differences between Python 2 and Python 3, but there are better resources online for this information.

Reference Information

See https://www.python.org/ for help getting started if you are new to Python.

See Integrating Vortex Studio using Python 3 for more documentation about scripting with Vortex