Manual:A gentle introduction
Python is a popular, open source programming language, very often embedded in applications as a scripting language, as is the case with LabRPS. It has a series of features that make it suitable for us LabRPS users: It is very easy to learn, especially for people who had never programmed before, and it is embedded in many other applications.
LabRPS makes extensive use of Python. With it, you can access and control almost any feature of LabRPS. For example, you can create new objects, modify their parameters, analyze their contents, or even create new interface controls, tools and panels. Some LabRPS workbenches and most of the addon workbenches are fully programmed in Python. LabRPS has an advanced Python console, available from menu View → Panels → Python console. It is often useful to perform operations for which there is no toolbar button yet, or to check shapes for problems, or to perform repetitive tasks:
But the Python console has another very important use: Every time you press a toolbar button, or perform other operations in LabRPS, some Python code is printed in the console (if the option to Show script commands in Python console is enabled in Edit → Preferences → Python → Macro) and executed. By leaving the Python console open, you can literally see the Python code unfold as you work, and in no time, almost without knowing it, you will find yourself learning some of the Python language.
LabRPS also has a macros system, which allows you to record actions to be replayed later. This system also uses the Python console, by simply recording everything that is done in it.
In this chapter, we will discover very generally the Python language. If you are interested in learning more, the LabRPS documentation wiki has an extensive section related to Python programming.
Writing Python code
There are two easy ways to write Python code in LabRPS: From the Python console (View → Panels → Python Console), or from the Macro editor (Tools → Macros → New). In the console, you write Python commands one by one, which are executed when you press return, while macros can contain a more complex script made of several lines, which is executed only when the macro is launched from the same Macros window.
In this chapter, you will be able to use both methods, but it is highly recommended to use the Python Console, since it will immediately inform you of any errors you make while typing.
If this is your first time using Python, consider reading this short introduction to Python programming before going any further, it will make the basic concepts of Python clearer.
Manipulating LabRPS objects
Let's start by creating a new empty document:
doc = LabRPS.newDocument()
If you type this in the LabRPS Python console, you will notice that as soon as you type "LabRPS." (the word LabRPS followed by a dot), a window pops up, allowing you to quickly autocomplete the rest of the line. Even better, each entry in the autocomplete list has a tooltip explaining what it does. This makes it very easy to explore the functionality available. Before choosing "newDocument", have a look at the other options available.
As soon as you press Enter our new document will be created. This is similar to pressing the "new document" button on the toolbar. In Python, the dot is used to indicate something that is contained inside something else (newDocument is a function that is inside the LabRPS module). The window that pops up therefore shows you everything that is contained inside "LabRPS". If you would add a dot after newDocument, instead of the parentheses, it would show you everything that is contained inside the newDocument function. The parentheses are mandatory when you are calling a Python function, such as this one. We will illustrate that better below.
Now let's get back to our document. Let's see what we can do with it. Type the following and explore the available options:
doc.
Usually names that begin with an upper-case letter are attributes: they contain a value. Names that begin with a lower-case letter are functions (also called methods): they "do something". Names that begin with an underscore are usually there for the internal use of the module, and you should ignore them. Let's use one of the methods to add a new object to our document:
simulation = doc.addObject("WindLab::WindLabSimulation","mySim")
Our simulation is added in the tree view, but nothing happens in the dependency graph view yet, because when working from Python, the document is never recomputed automatically. We must do that manually, whenever required:
doc.recompute()
Now our simulation has appeared in the dependency graph view. Many of the toolbar buttons that add objects in LabRPS actually do two things: add the object, and recompute.
You can get a list of all possible object types like WindLab::WindLabSimulation:
doc.supportedTypes()
Now let's explore the contents of our sim:
simulation.
You'll immediately see a couple of very interesting things such as:
simulation.TimeIncrement
This will print the current time increment of our simulation. Now let's try to change that:
simulation.TimeIncrement = 5
If you select your simulation with the mouse, you will see that in the properties panel, under the Data tab, our TimeIncrement property appears with the new value. All properties of a LabRPS object that appear in the Data and View tabs are directly accessible by Python too, by their names, like we did with the TimeIncrement property. Data properties are accessed directly from the object itself, for example:
simulation.NumberOfProcess
View properties are stored inside a ViewObject. Each LabRPS object possesses a ViewObject, which stores the visual properties of the object. When running LabRPS without its Graphical Interface (for example when launching it from a terminal with the -c command line option, or using it from another Python script), the ViewObject is not available, since there is no visual at all.
Try the following example to access the line color of our simulation:
simulation.ViewObject.ShowInTree
Vectors
Vector is a list of 3 numbers (x, y and z), describing a point or position in the 3D space. A lot of things can be done with vectors, such as additions, subtractions, projections and much more. In LabRPS vectors work like this:
myvec = LabRPS.Vector(2,0,0)
print(myvec) print(myvec.x) print(myvec.y) othervec = LabRPS.Vector(0,3,0) sumvec = myvec.add(othervec)
Read more
Power user documentation
- LabRPS scripting: Python, Introduction to Python, Python scripting tutorial, LabRPS Scripting Basics
- Modules: Units, Quantity
- Workbenches: Gui Commands, Commands
- Parametric objects: Scripted objects, Viewproviders
- Graphical interface: Interface creation, Interface creation completely in Python, PySide, PySide examples beginner, intermediate, advanced
- Macros: Macros, How to install macros
- Other: Expressions
- Hubs: User hub, Power users hub, Developer hub