FreeCAD Scripting Basics/es

Archivos de guión de Python en FreeCAD
FreeCAD está construido desde cero para que sea totalmente controlado por archivos de guión (scripts) de Python. Casi todas las partes de FreeCAD como la interfaz, el contenido de la escena, e incluso la representación de ese contenido en las vistas 3D, son accesibles desde el intérprete de Python incorporado, o desde sus propios archivos de guión. Como resultado, FreeCAD es, probablemente, una de las aplicaciones de diseño para ingeniería más personalizables de las disponibles en la actualidad.

En su estado actual, sin embargo, FreeCAD tiene muy pocos comandos "nativos" para interactuar con los objetos 3D. Sobre todo porque se encuentra todavía en una fase temprana de desarrollo, pero también porque la filosofía que hay detrás es más la de proporcionar una plataforma para el desarrollo CAD que una aplicación para un uso específico. Pero la facilidad de usar archivos de guión de Python dentro de FreeCAD probablemente ayudará a que pronto veamos funcionalidades nuevas que desarrollen los "usuarios avanzados", o, como de costumbre, los usuarios que conocen un poco de programación en Python. Python es uno de los lenguajes interpretados más populares, y debido a que es generalmente considerado como sencillo de aprender, tu también puedes estar proto creando tus propias macros de "usuario avanzado" sobre FreeCAD.

Si no estás familiarizado con Python, te recomendamos buscar tutoriales en Internet, y echar un rápido vistazo a su estructura. Python es un lenguaje muy fácil de aprender, sobre todo porque se puede ejecutar dentro de un intérprete, donde tanto comandos simples como programas completos pueden ejecutarse sobre la marcha, sin necesidad de compilar nada. FreeCAD ha incorporado un intérprete de Python. Si no ves la ventana denominada 'Consola de Python' como se muestra más abajo, puedes activarla en el menú Vista -> Vistas -> Consola de Python para mostrar el interprete.

El intérprete
Desde el intérprete puedes acceder a todos los módulos de Python instalados en el sistema, así como a los módulos de FreeCAD incorporados, y a todos los módulos adicionales de FreeCAD que puedas instalar más tarde. La imagen siguiente muestra el intérprete de Python:



También, puedes ejecutar código Python y navegar a través de las clases y funciones disponibles. FreeCAD proporciona un navegador de clases muy útil para la exploración de su nuevo mundo FreeCAD. Cuando se escribe el nombre de una clase conocida seguido de un punto (.) (significando que quieres añadir algo de esa clase), se abre una ventana del navegador de clases, donde se puede navegar entre las subclases y métodos disponibles. Cuando se selecciona algo, se mostrará un texto de ayuda asociado (si existe):



Así que, comienza por esto escribiendo '''App.  o Gui. ''' y verás qué pasa. Otra forma más genérica de exploración del contenido de los módulos y las clases de Python es usar el comando print dir. Por ejemplo, escribiendo print dir listará todos los módulos cargados en FreeCAD. print Dir(App) te mostrará todo el interior del módulo App, etc.

Otra característica útil del intérprete es la posibilidad de volver atrás en el historial de comandos y recuperar una línea de código que ya has escrito antes. Para navegar en el historial de comandos, sólo tienes que utilizar CTRL + flecha arriba o CTRL + flecha abajo.

Al hacer clic derecho en la ventana del intérprete también tienes otras opciones, tales como copiar todo el historial (útil para experimentar con algo, y luego hacer un archivo de guión con todo ello), o insertar el nombre de un archivo con su ruta completa.

Ayuda de Python
En el menú Ayuda de FreeCAD, encontrarás una entrada llamada "Módulos de Python", que abrirá una ventana que contiene una documentación completa, generada en tiempo real, de todos los módulos de Python a disposición del intérprete de FreeCAD, incluyendo Python y los módulos propios de FreeCAD, los módulos instalados por el sistema, y los módulos de FreeCAD adicionales. La documentación disponible depende del esfuerzo que cada desarrollador de los módulos puso en documentar su código pero, en general, los módulos de Python tienen la reputación de estar bastante bien documentados. Tu ventana de FreeCAD debe permanecer abierta para que este sistema de documentación funcione.

Módulos incorporados (Built-in)
Como FreeCAD está diseñado para poder ser ejecutado sin interfaz gráfica de usuario, casi toda su funcionalidad se separa en dos grupos: las funciones principales, llamado App, y la funcionalidad de la interfaz gráfica de usuario, llamado Gui. Así, nuestros dos principales módulos incorporados en FreeCAD se llaman App y Gui. Estos dos módulos también son accesibles desde fuera de los archivos de guiones de comandos del intérprete, con los nombres respectivos de FreeCAD y FreeCADGui.


 * En el módulo App, encontrarás todo lo relacionado con la aplicación en sí, como los métodos para abrir o cerrar archivos, y lo relacionado con los documentos, como los ajustes del documento activo o listar su contenido.


 * En el módulo Gui, encontrarás herramientas para la gestión de la interfaz gráfica de usuario y el acceso a sus elementos, como los entornos (workbench) y sus barras de herramientas y, más interesante, la representación gráfica de todo el contenido de FreeCAD.

Listar los contenidos de todos esos módulos es una tarea poco "productiva" ya que crecen muy rápido a lo largo del desarrollo de FreeCAD. Pero las dos herramientas de navegación (el navegador de clases y la ayuda de Python) te debería dar, en cualquier momento, una documentación actualizada y completa de estos módulos.

Los objetos App y los objetos GUI
Como hemos dicho, en FreeCAD, todo esta repartido entre el núcleo y la representación. Esto incluye también los objetos en 3D. Puedes acceder a la definición de propiedades de los objetos (llamadas características de FreeCAD) a través del módulo de la aplicación, y cambiar la forma en que están representados en la pantalla a través del módulo GUI. Por ejemplo, un cubo tiene propiedades que lo definen, como anchura, longitud, altura, que se almacenan en un objeto App, y las propiedades de la representación, como el color de las caras, modo de dibujo, que se almacenan en su correspondiente objeto GUI.

Esta forma de hacer las cosas permite una amplia gama de usos, como los algoritmos que sólo funcionan en la parte definitoria de características, sin la necesidad de ocuparse de ningun aspecto visual, o incluso redirigir el contenido del documento con la aplicación no-gráfica, como listas, hojas de cálculo o análisis de elementos.

Por cada objeto App de tu documento, existe su correspondiente objeto GUI. El documento en sí mismo, en realidad, también tiene objetos App y GUI. Esto, por supuesto, sólo es válido cuando se ejecuta FreeCAD con su interfaz completo. En la versión de línea de comandos, no existe interfaz gráfica de usuario, por lo que sólo habrá objetos App. Ten en cuenta que la parte de interfaz gráfica de usuario de los objetos se genera nuevamente cada vez que un objeto App se marca como "que se vuelven a calcular" (por ejemplo, cuando uno de sus parámetros ha cambiado), por lo que los cambios que podría haber hecho al objeto Gui directamente podrían perderse.

para acceder a la parte App de algo, escribe: donde "ObjectName" es el nombre de tu objeto. Tambien puedes poner: para acceder la la parte GUI del mismo objeto, escribe: donde "ObjectName" es el nombre de tu objeto. También puedes escribir: Si no tenemos GUI (por ejemplo en el modo de línea de comandos), la última línea no devolverá nada.

The Document objects
In FreeCAD all your work resides inside Documents. A document contains your geometry and can be saved to a file. Several documents can be opened at the same time. The document, like the geometry contained inside, has App and Gui objects. App object contains your actual geometry definitions, while the Gui object contains the different views of your document. You can open several windows, each one viewing your work with a different zoom factor or point of view. These views are all part of your document's Gui object.

To access the App part the currently open (active) document, you type: To create a new document, type: To access the Gui part the currently open (active) document, you type: To access the current view, you type:

Using additional modules
The FreeCAD and FreeCADGui modules are solely responsibles for creating and managing objects in the FreeCAD document. They don't actually do anything such as creating or modifying geometry. That is because that geometry can be of several types, and so it is managed by additional modules, each responsible for managing a certain geometry type. For example, the Part Module uses the OpenCascade kernel, and therefore is able to create and manipulate B-rep type geometry, which is what OpenCascade is built for. The Mesh Module is able to build and modify mesh objects. That way, FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types could be added easily in the future.

Creating objects
Each module has its own way to treat its geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules: will list you all the possible objects you can create. For example, let's create a mesh (treated by the mesh module) and a part (treated by the part module): The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with dir(myMesh) and dir(myPart). Except for one, myMesh has a "Mesh" property and "Part" has a "Shape" property. That is where the Mesh and Part data are stored. For example, let's create a Part cube and store it in our myPart object: You could try storing the cube inside the Mesh property of the myMesh object, it will return an error complaining of the wrong type. That is because those properties are made to store only a certain type. In the myMesh's Mesh property, you can only save stuff created with the Mesh module. Note that most modules also have a shortcut to add their geometry to the document:

Modifying objects
Modifying an object is done the same way: Now let's change the shape by a bigger one:

Querying objects
You can always look at the type of an object like this: or know if an object is derived from one of the basic ones (Part Feature, Mesh Feature, etc): Now you can really start playing with FreeCAD! To look at what you can do with the Part Module, read the Part scripting page, or the Mesh Scripting page for working with the Mesh Module. Note that, although the Part and Mesh modules are the most complete and widely used, other modules such as the Draft Module also have scripting APIs that can be useful to you. For a complete list of each modules and their available tools, visit the Category:API section.