Tutorial 9: How to Use the New Data Types in V2

Video Captions: Hello and welcome to our next Python tutorial for VRED Pro. My name is Christopher and today I will introduce the new data types in the API version 2, talk about their background and show you how you can work with them.

When we look at the Python API version 1, there aren’t really any data types to work with. All the parameters are either passed by their single values or as a list, like the components of a vector or a color. Also, the functions return values most of the time are either a single value, a tuple or a list.

From a Python point of view, this is ok. This is called Pythonic, so the way this is done in Python. But this way of working has its disadvantages. For example, when we are working with vectors, we always have to convert the Pythonic representation in a more convenient representation to perform mathematical operations.

The Python API version 2, therefore, introduces new data types that tackle the previous issues. It introduces an object-oriented way of working with the data. That means that values like the components of a vector are combined in a single object rather than being treated individually. For example, input parameters and return values for geometrical functions that deal with vectors now use the new data types. These data types have been borrowed from the Qt Framework that VRED uses internally and each data type comes with exactly the functions you would expect from it. For 3D graphics programming, we have the new types “Q-Vector-2D”, “3D” and “4D”, and also a Matrix data type. We have a new color type that can create colors from hex values, RGB or other color formats. And, we have some types that help us building a graphical user interface like QIcon, QSize or QImage.

When you want to work with these types, you do not have to import them by hand. VRED already added them for you and you can just start typing a “large Q” in the Script Editor, hit “SPACE” while holding the “Control” key, and you get a list of all the new data types you can use. So with that said, let’s look at some operations we can do with the new data types. In the first example, we create a new annotation and set its color. For this, we can use the new “Q Color” type that allows us to create colors for example from RGB values, but also from HSV or other color spaces. In the next step, we can move the annotation a bit higher to actually place it onto the hood of the car. To do this, we simply create a new 3D Vector and put it in the “set position” method of our annotation.

For our next example, we want to calculate a vector that points to the right from our current camera. So, actually, we want the vector that is described by the cross-product of the camera viewing direction and the up vector. Calculating a cross-product or a dot product are basic operations when doing 3D programming, but with the new data types, it's finally really easy to do this.

In the script, we first get the “up”, “from”, and “at” values from the current camera that basically describes the up direction, the from direction from where the camera is looking, and the at direction where the camera is looking at. With these values, we can basically calculate the cross-product in one line by calculating a vector from the camera to the target and the up vector. In the last set, we just normalize the result and then we are done. This is the advantage of these new data types. We have all the functionality without having to import any external modules or implementing our own types.

Another example: We want to calculate the distance from the camera to the origin and the distance to the z-axis of the coordinate system. This is also very easy because the vector classes already offer such methods. In this case, it's the method distance to point and distance to line that we are using here. So you see, there is really no need to use an external library or write your own vector implementation. The data types should contain most of the functions you will ever need when doing 3D programming.

There are so much more useful data types we could talk about, like the “Q Time” data type for measuring times or the “Q Size” for representing areas, but the vector types are definitely the most useful ones. To learn about all the other types, I can really recommend the official Qt documentation. They also have some great examples here. Just remember to use the auto-complete feature of the Script Editor with “Control”, “Space” that shows you available functions and types and use online search to find the documentation of the Qt types.

Okay. That’s it for today about all the new data types in VRED. I hope you enjoyed it. Thank you for joining me and see you next time.