VRED Python API v2

This is the documentation for the new VRED Python API v2 based on Qt for Python (also known as PySide). View VRED Python API v1 documentation here.

Since VRED 2024, VRED uses Qt 6 (PySide6 and shiboken6). Release notes: What’s new in VRED Python API v2

Types

Some functions of the new interface use Qt types for parameters or as return type. Those types are imported automatically into the python namespace and can be used without the need to import them from the PySide6 module.

Additional Qt classes can be imported like this:

from PySide6.QtCore import QLine
from PySide6.QtGui import QBrush

line = QLine(0,0,100,100)
brush = QBrush()

Objects

Scene objects in the new interface are derived from vrdObject. Class names for these objects start with the prefix “vrd”, for example vrdNode for node objects or vrdMaterial for material objects.

Whenever those objects are returned from an API function or method, their class type will be determined dynamically. That means they will be either of the base class type as specified by the documentation, or a descendant class. For example, when retrieving the default environment switch via vrMaterialService.findMaterial(“Environments”), the returned object will be of vrdEnvironmentSwitchMaterial type instead of the documented base type vrdMaterial.

Thus, users do not need to upcast the returned objects as they already exhibit their most specific type. Users should however check the type of the returned object via vrdObject.isType(type) before accessing methods or properties of a particular type in order to prevent runtime errors. For example, when the user wants to access the choice property of the material returned by the call to findMaterial() above, the material type should be checked via material.isType(vrdSwitchMaterial) before invoking material.getChoice(). If only methods or properties of the documented base type are about to be accessed, this is of course not necessary.

Services

While the objects have many functions to query and change properties, the main entry point is through the services to get the objects you want to work with.

Use services to find existing scene objects, create new objects, delete objects, or access other functions that are available in the related VRED modules.

Call service functions through an object that has the same name as the service class. For example:

camNode = vrCameraService.createCamera("new camera")

Function calls

In VRED API v2, only optional parameters can be passed as keyword arguments (named arguments) in a function call. Optional parameters are displayed with their default value in the function signature in this documentation.

All mandatory parameters must be passed as positional arguments, i.e. without their name, in the order as specified in the signature.

For example, vrNodeService.findNode has one mandatory parameter (name) and the rest is optional. That means, this function call works (omitting the second and third parameter):

trackNode = vrNodeService.findNode("track1", root=vrCameraService.getCameraRoot())

while this function call would give an error:

trackNode = vrNodeService.findNode(name="track1", root=vrCameraService.getCameraRoot())

Installing 3rd party modules

Since VRED moved to Python 3 you can easily install 3rd party modules. You can find a complete Python installation in the installation folder under lib/python. You can use pip to install from the official Python repository. If you want to install ‘numpy’ you can do it like this:

python.exe -m pip install numpy

Pip is developed independent from Python. If you want to upgrade pip to a newer version, use this:

python.exe -m pip install --upgrade pip

If the included pip should stop working you can use Pythons boostrap mechanism to restore it:

python.exe -m ensurepip

You can also manually install modules to Lib/site-packages. If you want to compile your own C or C++ extensions using the Python API be sure to use a compatible compiler. We are using the official Python 3 binaries for VRED without recompiling. So anything, that compiles against the Python distribution from python.org with the same version number as the one shipping with VRED, should work.

Querying versions

VRED’s Python version can be printed from within VRED with:

print(sys.version)

VRED’s Qt version can be printed from within VRED with:

print(PySide6.QtCore.qVersion())

Using the python API via the Web Interface

This interface can be used via python or via the web interface. The access is done via JavaScript. Function calls are executed asynchronously. The following example shows how such a call could look like from a web page. All parameter and return types are mapped to JavaScript types. QVector3D and QMatrix4x4 for example will be mapped to arrays of 3 or 16 numbers.

<script type="module">
  import {api} from '/api.js';

  // reacting on a signal
  api.vrClusterService.started.connect(() => {console.log('Started')});
  // calling a function
  api.vrClusterService.start();
  // changing the position of the camera
  api.vrNodeService.findNode("Perspective")
      .then((node) => node.setTranslation([10,20,30]));
</script>

Using API v1 and v2 together

You might use functions from both API v1 and API v2 in the same script.

In API v1 the node object type is vrNodePtr. You can use vrdNode objects in functions from API v1 that take vrNodePtr as parameter, and vice versa, use vrNodePtr objects in functions from API v2 that take vrdNode as parameter. They’re converted automatically.

To explicitly convert a vrdNode to a vrNodePtr object:

oldNodePtr = toNode(newVRDObject.getObjectId())

You can also convert a vrNodePtr to vrdNode:

newVRDObject = vrNodeService.getNodeFromId(oldNodePtr.getID())

To convert a vrdMaterial to a vrMaterialPtr object:

oldMatPtr = toMaterial(newVRDMaterial.getObjectId())

To convert a vrMaterialPtr to vrdMaterial:

newVRDMaterial = vrMaterialService.getMaterialFromId(oldMatPtr.getID())

Graph terminology

See “Node graphs in VRED” for an introduction on how we refer to node graphs in this documentation.

Python example scripts

This is a collection of example scripts demonstrating various features of the VRED Python API.

VRED Python API v2

Indices and tables