View source for Python scripting tutorial

{{Docnav
|[[Introduction_to_Python|Introduction to Python]]
|[[LabRPS_Scripting_Basics|LabRPS Scripting Basics]]
}}

{{TOCright}}

==Introduction== 

[https://en.wikipedia.org/wiki/Python_%28programming_language%29 Python] is a programming language that it relatively easy to learn and understand. It is open-source and multi-platform, and can be used for many purposes: from simple shell scripts to very complex programs. But its most widespread use is as a scripting language embedded in other applications. That is how it is used inside LabRPS. From the [[Python_console|Python console]], or from custom scripts, you can control LabRPS and make it perform very complex operations.

For example, from a Python script, you can:
* Create new objects.
* Modify existing objects.
* Modify the 3D representation of those objects if it is a CAD object.
* Modify the LabRPS interface.

There are several ways to use Python in LabRPS:
* From the [[LabRPS Scripting Basics|LabRPS Python interpreter]], where you can issue commands in a "command line"-style interface.
* From [[macros|macros]], which are a convenient way to quickly add a missing tool to the LabRPS interface.
* From external scripts, which can used to create quite complex solutions, even entire [[Workbenches|Workbenches]].

In this tutorial, we'll work on a couple of basic examples to get you started, but there is much more [[Power users hub|documentation about Python scripting]] available on this wiki. If you are totally new to Python and want to understand how it works, we also have a basic [[introduction to Python|introduction to Python]].

Before proceeding with Python scripting, go to {{MenuCommand|Edit → Preferences → General → Report view}} and check two boxes:
* {{MenuCommand|Redirect internal Python output to report view}}.
* {{MenuCommand|Redirect internal Python errors to report view}}.
Then go to {{MenuCommand|View → Panels}} and check:
* {{MenuCommand|Report view}}.

==Writing Python code== 

There are two ways to write Python code in LabRPS. In the [[Python console|Python console]] (select {{MenuCommand|View → Panels → Python console}} from the menu) or in the [[Std_DlgMacroExecute|Macro editor]] (select {{MenuCommand|Macro → Macros...}} from the menu). In the console you write Python commands one by one, executing them by pressing {{KEY|Enter}}, while macros can contain more complex code made up of several lines, executed only when the macro is executed.

[[Image:Screenshot_pythoninterpreter.png]]

{{Caption|The LabRPS Python console}}

In this tutorial you can use both methods. You can copy-paste each line in the Python console and then press {{KEY|Enter}}, or copy-paste the entire code in a new Macro window.

{{Top}}

==Exploring LabRPS== 

Let's start by creating a new empty document:

{{Code|code=
doc = LabRPS.newDocument()
}}

If you type this in the LabRPS Python console, you will notice that as soon as you type {{incode|LabRPS.}} a window pops up, allowing to quickly autocomplete the rest of your line. Even better, each entry in the autocomplete list has a tooltip explaining what it does. This makes it easier to explore the available functionality. Before choosing {{incode|newDocument}}, have a look at the other options.

[[Image:Screenshot_classbrowser.jpg]]

{{Caption|The autocomplete mechanism of the LabRPS Python console}}

Now our new document will be created. This is similar to pressing the {{Button|[[Image:Std_New.svg|16px]] [[Std_New|New]]}} button on the toolbar. In fact most buttons in LabRPS do nothing more than execute one or more lines of Python code. Even better, you can set an option in {{MenuCommand|Edit → Preferences → Python → Macro}} to {{MenuCommand|Show script commands in python console}}. This will print in the console all Python code executed when you press buttons. Very useful for learning how to reproduce actions in Python.

Now let's get back to our document and see what we can do with it:

{{Code|code=
doc.
}}

Explore the available options. Usually names that begin with a capital letter are attributes, they contain a value, while 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 working of the module, and you shouldn't care about them. Let's use one of the methods to add a new object to our document:

{{Code|code=
box = doc.addObject("Part::Box", "myBox")
}}

Nothing happens. Why? Because LabRPS is made for the big picture. One day, it will work with hundreds of complex objects, all depending each other. Making a small change somewhere could have a big impact; you may need to recalculate the whole document which could take a long time. For that reason almost no command updates the scene automatically. You must do it manually:

{{Code|code=
doc.recompute()
}}

Now our box appeared. Many of the buttons that add objects in LabRPS actually do two things: add the object, and recompute. If you turned on the {{MenuCommand|Show script commands in python console}} option above, try adding a sphere with the GUI button; you'll see the two lines of Python code being executed one after the other.

Now let's explore the contents of our box:

{{Code|code=
box.
}}

You'll immediately see a couple of very interesting things such as:

{{Code|code=
box.Height
}}

This will print the current height of our box. Now let's try to change that:

{{Code|code=
box.Height = 5
}}

If you select your box with the mouse, you'll see that in the [[Property_editor|Property editor]], on the {{MenuCommand|Data}} tab, our {{PropertyData|Height}} property appears. All properties of a LabRPS object that appear there (and also on the {{MenuCommand|View}} tab, more about that later), are directly accessible in Python too, by their names, like we did with the {{PropertyData|Height}} property. Try changing the other dimensions of the box.

{{Top}}

==Vectors and placements== 

[https://en.wikipedia.org/wiki/Euclidean_vector Vectors] are a very fundamental concept in any 3D application. A vector is a list of 3 numbers (x, y and z), describing a point or position in 3D space. Many things can be done with vectors, such as additions, subtractions, projections and [https://en.wikipedia.org/wiki/Vector_space much more]. In LabRPS vectors work like this:

{{Code|code=
myvec = LabRPS.Vector(2, 0, 0)
myvec.x
myvec.y
othervec = LabRPS.Vector(0, 3, 0)
sumvec = myvec.add(othervec)
}}

Another common feature of LabRPS objects is their [[Placement|placement]]. Each object has a {{PropertyData|Placement}} property, which contains the {{PropertyData|Base}} (position) and {{PropertyData|Rotation}} (orientation) of the object. It is easy to manipulate, for example to move our object:

{{Code|code=
box.Placement
box.Placement.Base
box.Placement.Base = sumvec
 
otherpla = LabRPS.Placement()
box.Placement = otherpla
}}

Now you must understand a couple of important concepts before we get further.

{{Top}}

==App and Gui== 

LabRPS has been designed so that it can also be used without its user interface, as a command-line application. Almost every object in LabRPS therefore consists of two parts: an {{incode|Object}}, its "geometry" component, and a {{incode|ViewObject}}, its "visual" component. When you work in command-line mode, the geometry part is present, but the visual part is disabled.

To illustrate the concept let's look at our cube object. The geometric properties of the cube, such as its dimensions, position, etc. are stored in the {{incode|Object}}. While its visual properties, such as its color, line thickness, etc. are stored in the {{incode|ViewObject}}. This corresponds to the '''Data''' and '''View''' tabs in the [[Property_editor|Property editor]]. The view object of an object is accessed like this:

{{Code|code=
vo = box.ViewObject
}}


Now you can also change the properties on the '''View''' tab:

{{Code|code=
vo.Transparency = 80
vo.hide()
vo.show()
}}

When you start LabRPS, the Python console already loads two base modules: {{incode|LabRPS}} and {{incode|LabRPSGui}} (which can also be accessed by their shortcuts {{incode|App}} and {{incode|Gui}}). They contain all kinds of generic functionality to work with documents and their objects. To illustrate our concept, see that both {{incode|LabRPS}} and {{incode|LabRPSGui}} contain an {{incode|ActiveDocument}} attribute, which is the currently opened document. {{incode|LabRPS.ActiveDocument}} and {{incode|LabRPSGui.ActiveDocument}} are not the same object however. They are the two components of a LabRPS document, and they contain different attributes and methods. For example, {{incode|LabRPSGui.ActiveDocument}} contains {{incode|ActiveView}}, which is the currently opened [[3D_view|3D view]].

{{Top}}

==Modules== 

The true power of LabRPS lies in its faithful modules, with their respective workbenches. The LabRPS base application is more or less an empty container. Without its modules it can do little more than create new, empty documents. Each module not only adds new workbenches to the interface, but also new Python commands and new object types. As a result several different, and even totally incompatible, object types can coexist in the same document. The most important modules in LabRPS that we'll look at in this tutorial are: [[Part_Workbench|Part]] and [[WindLab_Workbench|WindLab]].

You can check all the available base object types for the current document like this:

{{Code|code=
doc.supportedTypes()
}}

The different LabRPS modules are not automatically loaded in the Python console. This is to avoid having a very slow startup. Modules are loaded only when you need them. So, for example, to explore what's inside the Part module:

{{Code|code=
import Part
Part.
}}

But we'll talk more about the Part module below.

{{Top}}

==WindLab module== 
The [[WindLab_Workbench|WindLab]] module allows you to create WindLab features such as wind spectrum, wind velocity profile, wind simulation method etc...
But before you create WindLab feature, you have to first create WindLab Simulation. Because before the feature can be really recognized by the WindLab framework, it has to belong to a WindLab simulation.
{{Code|code=

import WindLabObjects
doc = App.ActiveDocument
sim = WindLabObjects.makeSimulation(doc)
loc = WindLabObjects.makeFeature("SimulationPoints", sim.Label, "General Distribution", "Location Distribution")
doc.recompute()
}}

{{Top}}

==Part module== 

The [[Part_Workbench|Part]] module is a very important module in LabRPS. It allows you to create and manipulate [https://en.wikipedia.org/wiki/Boundary_representation BRep] objects. BREP stands for "Boundary Representation". A BREP object is defined by surfaces that enclose and define an inner volume. Unlike meshes, BREP objects can have a wide variety of components from planar faces to very complex NURBS surfaces.

The Part module is based on the powerful [https://en.wikipedia.org/wiki/Open_CASCADE_Technology OpenCasCade] library, which allows a wide range of complex operations to be performed on those objects, such as boolean operations, filleting, lofts, etc.

The Part module works the same way as the Mesh module: You create a LabRPS object, a Part object, then add the Part object to the LabRPS object:

{{Code|code=
import Part
myshape = Part.makeSphere(10)
myshape.Volume
myshape.Area

shapeobj = doc.addObject("Part::Feature", "MyShape")
shapeobj.Shape = myshape
doc.recompute()
}}

The Part module (like the Mesh module) also has a shortcut that automatically creates a LabRPS object and adds a shape to it, so you can shorten the last three lines to:

{{Code|code=
Part.show(myshape)
}}

By exploring the contents of myshape, you will notice many interesting subcomponents such as {{incode|Faces}}, {{incode|Edges}}, {{incode|Vertexes}}, {{incode|Solids}} and {{incode|Shells}}, and a wide range of geometry operations such as {{incode|cut}} (subtraction), {{incode|common}} (intersection) or {{incode|fuse}} (union). The [[Topological_data_scripting|Topological data scripting]] page explains all that in detail.

[[Topological_data_scripting|Read more about part scripting...]]

{{Top}}


==Interface== 

The LabRPS user interface is made with [https://en.wikipedia.org/wiki/Qt_(software) Qt], a powerful graphical interface system, responsible for drawing and handling all the controls, menus, toolbars and buttons around the [[3D_view|3D view]]. Qt provides a module, [[PySide]], which allows Python to access and modify Qt interfaces such as LabRPS's. Let's try to fiddle with the Qt interface and produce a simple dialog:

{{Code|code=
from PySide import QtGui
QtGui.QMessageBox.information(None, "Apollo program", "Houston, we have a problem")
}}

Notice that the dialog that appears has the LabRPS icon in its toolbar, meaning that Qt knows that the order has been issued from inside the LabRPS application. It is possible to manipulate any part of the LabRPS interface.

Qt is a very powerful interface system that allows you to do very complex things. It also has some easy-to-use tools such as the Qt Designer with which you can design dialogs graphically and then add them to the LabRPS interface with a few lines of Python code.

[[PySide|Read more about PySide here...]]

{{Top}}

==Macros== 

Now that you have a good understanding of the basics, where are we going to keep our Python scripts, and how are we going to launch them inside LabRPS? There is an easy mechanism for that, called [[Macros|Macros]]. A macro is a Python script that can be added to a toolbar and launched via a mouse click. LabRPS provides you with a simple text editor ({{MenuCommand|Macro → Macros... → Create}}) where you can write or paste scripts. Once the script is done, use {{MenuCommand|Tools → Customize... → Macros}} to define a button for it that can be added to toolbars.

==External scripts== 

An alternative method for creating, saving, and running your own Python scripts is to create them outside LabRPS, using an editor of your choice (for example, Vim). To run your Python script inside LabRPS, be sure to save it with the {{FileName|.py}} extension.

Then use {{MenuCommand|File → Open}} to open your script. It will load into a new tab in the [[Main_view_area|Main view area]]. You can run your script by clicking the {{Button|[[Image:Std_DlgMacroExecuteDirect.svg|16px]] [[Std_DlgMacroExecuteDirect|Execute macro]]}} button. Any errors or script output will be shown in the [[Report_view|Report view]].

When you make and save any modifications to your already-loaded script, a dialog box will appear asking whether you want to reload the modified script into LabRPS.

You can continue to the [[LabRPS_Scripting_Basics|LabRPS Scripting Basics]] page, or you can access that page and other relevant pages at the [[Power_users_hub|Power users hub]].

{{Top}}


{{Docnav
|[[Introduction_to_Python|Introduction to Python]]
|[[LabRPS_Scripting_Basics|LabRPS Scripting Basics]]
}}

{{Powerdocnavi}}
[[Category:Developer Documentation]]
[[Category:Python Code]]