Python scripting tutorial/es

Python es un lenguaje de programación, muy simple de utilizar y muy rápido de aprender. Es de código libre, multi plataforma, y puede utilizarse para una gran variedad de cosas, desde la programación de archivos de guión simples a programas muy complejos. Pero uno de sus usos más extendidos es como lenguaje de archivos de guión, ya que es sencillo de embeber en otras aplicaciones. Así es exactamente como se utiliza dentro de FreeCAD. Desde la consola de Python, o desde tus archivos de guión personalizados, puedes pilotar FreeCAD, y hacer que ejecute acciones muy complejas para las cuales aún no exista herramientas en la interfaz gráfica de usuario.

Por ejemplo, desde un archivo de guión de Python, puedes:
 * Crear nuevos objetos.
 * Modificar los objetos existentes.
 * Modificar la representación 3D de dichos objetos
 * Modificar la interfaz de FreeCAD

También existen diversas formas de utilizar Python en FreeCAD:
 * Desde el Interprete de Python de FreeCAD, donde puedes dictar comandos como en una interfaz del tipo de línea de comandos
 * Desde Macros, que son una forma conveniente de añadir una herramienta que no exista a la interfaz de FreeCAD
 * Desde archivos de guión externos, que pueden utilizarse para programar cosas mucho más complejas. Como Entornos completos.

En este tutorial, trabajaremos en varios ejemplos simples para que puedas iniciarte, pero existe mucha más documentación sobre los archivos de guión de Python disponible en esta wiki. Si eres totalmente nuevo en Python y quieres comprender cómo funciona, también tenemos una básica Introducción a Python.

Escribiendo código en Python
Existen dos modos sencillos de escribir código de Python en FreeCAD: Desde la consola de Python (disponible en el menú Vista -> Vistas -> Consola de Python) o desde el editor de macros (Herramientas -> Macros). En la consola, escribes comandos de Python uno a uno, que son ejecutados al presionar Enter, mientras que las macros pueden contener archivos de guión más completos formados por varias líneas, que se ejecutan sólo cuando la macro es ejecutada.



En este tutorial, serás capaz de utilizar ambos métodos, ya sea copiando y pegando cada línea una a una en la consola de Python y presionando después de cada línea, o copiando y pegando el código entero en una ventana de macro nueva.

Explorando FreeCAD
Vamos a empezar creando un nuevo documento vacío:

doc = FreeCAD.newDocument

Si escribes esto en la consola de Python de FreeCAD, notaras que en cuanto escribas "FreeCAD.", una ventana aparece, permitiendo rápidamente autocompletar el resto de la línea. Aún mejor, cada entrada en la lista de autocompletar tiene una ayuda explicando lo que hace. Esto hace muy sencillo explorar las funcionalidades disponibles. Antes de seleccionar "newDocument", mira las otras opciones disponibles.



Ahora nuestro nuevo documento se creará. Esto es similar a presionar el botón "Nuevo documento" en la barra de herramientas. En realidad, la mayoría de botones en FreeCAD no hacen nada más que ejecutar una línea o dos de código en Python. Aún mejor, puedes establecer una opción en Editar -> Preferencias -> General -> Macro para "mostrar los comandos de los archivos de guión en la consola de Python". Esto mostrará en la consola todo el código de Python ejecutado cuando presionas los botones. Muy útil para aprender como reproducir acciones en Python.

Volvamos ahora a nuestro documento. Vamos a ver que podemos hacer con él:

doc.

Explora las opciones disponibles. Normalmente los nombres que comienzan con una letra mayúscula son atributos, que contienen un valor, mientras que los nombres que empiezan con una letra minúscula son funciones (también llamados métodos), que hacen "algo". Los nombres que comienzan con un guión bajo están ahí normalmente para el funcionamiento interno del módulo, y no deberías preocuparte de ellos. Vamos a utilizar uno de los métodos para añadir un nuevo objeto a nuestro documento:

box = doc.addObject("Part::Box","myBox")

No pasa nada. Por qué? Es debido a que FreeCAD está pensado para realizar trabajos complejos. Un día, trabajará con cientos de objetos complejos, todos dependiendo unos de otros. Hacer un pequeño cambio en cualquier parte podría tener un gran impacto,necesitaras recalcular el documento completo, que puede llevar bastante tiempo... Por ese motivo, casi ningún comando actualiza la escena automáticamente. Debes hacerlo manualmente:

doc.recompute

Ves? Ahora aparece nuestro cubo! Muchos de los botones que añaden objetos en FreeCAD en realidad hacen dos cosas: Añadir el objeto, y recalcular. Si activas la opción "mostrar los comandos de los archivos de guión en la consola de Python", prueba a añadir una esfera con el botón de la interfaz, verás las dos líneas de código de Python siendo ejecutadas una tras la otra.

Qué quieres saber sobre el "Part::Box"? Cómo puedo saber que otros tipos de objetos puedo añadir? Está todo aquí:

doc.supportedTypes

Ahora vamos a explorar el contenido de nuestro cubo:

box.

Verás automáticamente varias cosas interesantes como:

box.Height

Esto mostrará la altura actual de nuestro cubo. Ahora vamos a intentar cambiarla:

box.Height = 5

Si seleccionas tu cubo con el ratón, verás que en el panel de propiedades, en la pestaña de "Datos", nuestra propiedad "Height" aparece. Todas las propiedades de un objeto de FreeCAD que aparecen aquí (y también en la pestaña "Vista", de la que hablaremos más adelante), son directamente accesibles también desde Python, por sus nombres, como hicimos con la propiedad "Height". Prueba cambiando las otras dimensiones del cubo.

Vectores y ubicaciones
Vectors are a very fundamental concept in any 3D application. It 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 FreeCAD vectors work like this:

myvec = FreeCAD.Vector(2,0,0) myvec myvec.x myvec.y othervec = FreeCAD.Vector(0,3,0) sumvec = myvec.add(othervec)

Another common feature of FreeCAD objects is their placement. Each object has a Placement attributes, which contains the position (Base) and orientation (Rotation) of the object. It is easy to manipulate, for example to move our object:

box.PLacement. box.Placement.Base box.Placement.Base = sumvec otherpla = FreeCAD.Placement box.Placement = otherpla

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

App and Gui
FreeCAD is made from the beginning to work as a command-line application, without its user interface. As a result, almost everything is separated between a "geometry" component and a "visual" component. When you work in command-line mode, the geometry part is present, but all the visual part is simply disabled. Almost any object in FreeCAD therefore is made of two parts, an Object and a ViewObject.

To illustrate the concept, see our cube object, the geometric properties of the cube, such as its dimensions, position, etc... are stored in the object, while its visual properties, such as its color, line thickness, etc... are stored in the viewobject. This corresponds to the "Data" and "View" tabs in the property window. The view object of an object is accessed like this:

vo = box.ViewObject

Now you can also change the properties of the "View" tab:

vo.Transparency = 80 vo.hide vo.show

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

Modules
Now you must surely wonder, what else than "Part::Box" can I do? The FreeCAD base application is more or less an empty container. Without its modules, it can do little more than creating new, empty documents. The true power of FreeCAD is in its faithful modules. Each of them adds not only new workbenches to the interface, but also new python commands and new object types. As a result, several different or even totally incompatible object types can coexist in the same document. The most important modules in FreeCAD, that we'll look at in this tutorial, are Part, Mesh, Sketcher or Draft.

Sketcher and Draft both use the Part module to create and handle their geometry, which are BRep whileMesh is totally independent, and handles its own objects. More about that below.

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

doc.supportedTypes

The different FreeCAD modules, although they added their object types to FreeCAD, 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:

import Part Part.

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

By now, you know a bit more about the different modules of FreeCAD: The core modules (FreeCAD, FreeCADGui), and the workbenches modules (Part, Mesh, Sketcher). The other important modules are the 3d scene module (pivy) and the interface module (pyqt), we'll talk about them too below.

Now it's time to explore a bit deeper the important ones, which are the workbench modules.

Mesh
Meshes are a very simple kind of 3D objects, used for example by Sketchup, Blender or 3D studio Max. They are composed of 3 elements: points (also called vertices), lines (also called edges) and faces. In many applications, FreeCAD included, faces can have only 3 vertices. But of course nothing prevents you from having a bigger plane face made of several coplanar triangles.

Meshes are simple, this can be a bad thing, but for many applications such as those above, it turns to be an advantage, because they are so simple that you can easily have millions of them in a single document. In FreeCAD, though, they have less use, and are mostly there so you can import objects in mesh formats (.stl, .obj) from other applications. It was also extensively used as the main test module in the first month of life of FreeCAD.

Mesh objects and FreeCAD objects are different things. You can see the FreeCAD object as a container for a Mesh object (like, we'll see below, for Part objects too). So in order to add a mesh object to FreeCAD, we must first create a FreeCAD object and a Mesh object, then add the Mesh object to the FreeCAD object:

import Mesh mymesh = Mesh.createSphere mymesh. mymesh.Facets mymesh.Points meshobj = doc.addObject("Mesh::Feature","MyMesh") meshobj.Mesh = mymesh doc.recompute

This is a standard example, that uses the createSphere method to automatically create a sphere, but you can very well create custom meshes from scratch, by defining their vertices and faces.

Read more about mesh scripting...

Part
The Part Module is the most powerful module of the whole FreeCAD. It allows to create and manipulate BRep objects. This kind of object, unlike meshes, can have a wide variety of components. To resume a bit, Brep means Boundary Representation. which means that they are defined by their surfaces, which enclose and define an inner volume. These surface can be a variety of things, such as plane faces or very complex NURBS surfaces. They also carry the concept of volume.

The Part module is based on the powerful OpenCasCade library, which allows a wide range of complex operations to be easily 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 FreeCAD object, a Part object, then add the Part object to the FreeCAD object:

import Part myshape = Part.makeSphere(10) myshape. 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 FreeCAD object and add a shape to it, so you can skip the 3 last lines above:

Part.show(myshape)

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

Read more about part scripting...

Draft
FreeCAD features many more modules, such as Sketcher or Draft, which also create Part objects, but add parameters to it, or even carry a whole new way to handle the Part geometry in them. Our box example above, is a perfect example of parametric object. All you need, to define the box, is to specify a couple of parameters, such as height, width and length. Based on those, the object will automatically calculate its Part shape. FreeCAD allows you to create such objects in python.

The Draft Module adds a couple of 2D parametric objects types (which are all Part objects) such as lines and circles, and also provides some generic functions that work not only on Draft-made objects, but on any Part object. To explore what is available, simply do:

import Draft Draft. rec = Draft.makeRectangle(5,2) mvec = FreeCAD.Vector(4,4,0) Draft.move(rec,mvec) Draft.move(box,mvec)

Interface
The FreeCAD user interface is made with Qt, a powerful graphical interface system, responsible for drawing and handling all the controls, menus, toolbars, buttons around the 3D view. Qt provides a module, called PyQt, which allows python to access and modify Qt interfaces, such as FreeCAD. Let's try to fiddle with the Qt interface and produce a simple dialog:

from PyQt4 import QtGui QtGui.QMessageBox.information(None,"Apollo program","Houston, we have a problem")

See that the dialog that appears has the FreeCAD icon in its toolbar, meaning that Qt knows that the order has been issued from inside the FreeCAD application. We can therefore easily directly manipulate any part of the FreeCAD interface.

Qt is a very powerful interface system, that allows you to do very complex things, but also has a couple of very easy-to use tools such as the Qt Designer with which you can design dialogs graphically and then add them to the FreeCAD interface with a couple of lines of python.

Read more about pyqt here...

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 easily from FreeCAD? There is an easy mechanism for that, called Macros. A macro is simply a python script, that can then be added to a toolbar and be launched from a simple mouse click. FreeCAD provides you with a simple text editor (Macro -> Macros -> Create) where you can write or paste scripts. Once it is done, the Tools -> Customize -> Macros allow you to define a button for it, that can be added to toolbars.

Now you are ready for more in-depth FreeCAD scripting. Head on to the Power users hub!