Python scripting tutorial/es

Introducción
Python es un lenguaje de programación relativamente fácil de aprender y comprender. Es de código abierto y multiplataforma, y puede utilizarse para muchos fines: desde simples scripts de shell hasta programas muy complejos. Pero su uso más extendido es como lenguaje de scripting incrustado en otras aplicaciones. Así es como se utiliza dentro de FreeCAD. Desde la Consola de Python, o desde scripts personalizados, puedes controlar FreeCAD y hacer que realice operaciones muy complejas.

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 Ambientes de trabajo completos.

En este tutorial, trabajaremos en varios ejemplos básicos para que puedas iniciarte, pero existe mucha más documentación sobre los documentación sobre guionización en 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.

Antes de proceder con la escritura en Python, vaya a y marque dos casillas: Luego vaya a y compruebe:

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 se pueden utilizar ambos métodos. Puede copiar-pegar cada línea en la consola Python y luego presionar, o copiar-pegar todo el código en una nueva ventana de Macro.

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

Si escribe esto en la consola de FreeCAD Python, notará que en cuanto teclee aparece una ventana que le permite autocompletar rápidamente el resto de su línea. Mejor aún, cada entrada de la lista de autocompletar tiene un tooltip que explica lo que hace. Esto facilita la exploración de la funcionalidad disponible. Antes de elegir, eche un vistazo a las otras opciones.



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.

Ahora volvamos a nuestro documento y veamos qué podemos hacer con él:

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

No pasa nada. ¿Por qué? Porque FreeCAD está hecho para la gran imagen. Un día, trabajará con cientos de objetos complejos, todos dependiendo unos de otros. Hacer un pequeño cambio en algún lugar puede tener un gran impacto, puede necesitar recalcular todo el documento, lo que puede llevar mucho tiempo. Por esa razón casi ningún comando actualiza la escena automáticamente. Debes hacerlo manualmente:

Ahora nuestra caja apareció. Muchos de los botones que añaden objetos en FreeCAD en realidad hacen dos cosas: añadir el objeto, y volver a calcular. Si activaste la opción de arriba, intenta añadir una esfera con el botón de la GUI, verás las dos líneas de código Python ejecutándose una tras otra.

Ahora vamos a explorar el contenido de nuestro cubo:

Verás automáticamente varias cosas interesantes como:

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

Si seleccionas tu caja con el ratón, verás que en el Editor de propiedades, en la pestaña, aparece nuestra propiedad. Todas las propiedades de un objeto de FreeCAD que aparecen ahí (y también en la pestaña, más adelante), son directamente accesibles por Python también, por sus nombres, como hicimos con la propiedad. Prueba a cambiar las otras dimensiones de la caja.

Traducción realizada con la versión gratuita del traductor www.DeepL.com/Translator

Vectores y ubicaciones
Los vectores son un concepto muy fundamental en cualquier aplicación 3D. Son una lista de 3 números (X, Y y Z), describiendo un punto o posición en el espacio 3D. Un montón de cosas se pueden hacer con los vectores, como sumas, restas, proyecciones y mucho más. En FreeCAD los vectores funcionan así:

Otra característica común de los objetos de FreeCAD es su Ubicación. Cada objeto tiene una propiedad, que contiene la (posición) y  (orientación) del objeto. Es fácil de manipular, por ejemplo para mover nuestro objeto:

Ahora deberías comprender varios conceptos importantes antes de continuar avanzando.

App y Gui
FreeCAD ha sido diseñado para que también pueda ser utilizado sin su interfaz de usuario, como una aplicación de línea de comandos. Por lo tanto, casi todos los objetos de FreeCAD constan de dos partes: un, su componente de "geometría", y un , su componente "visual". Cuando trabajas en modo línea de comandos, la parte de geometría está presente, pero la parte visual está desactivada.

Para ilustrar el concepto, veamos nuestro objeto cubo. Las propiedades geométricas del cubo, como sus dimensiones, posición, etc. se almacenan en el. Mientras que sus propiedades visuales, como su color, grosor de línea, etc. se almacenan en el. Esto se corresponde con las pestañas Datos y Vista' del Editor de propiedades. El objeto vista de un objeto se accede así:

Ahora también puedes cambiar las propiedades en la pestaña Vista':

Cuando se inicia FreeCAD, la consola de Python ya carga dos módulos base: y  (a los que también se puede acceder por sus accesos directos  y ). Contienen todo tipo de funcionalidades genéricas para trabajar con documentos y sus objetos. Para ilustrar nuestro concepto, veamos que tanto como  contienen un atributo, que es el documento actualmente abierto. y no son el mismo objeto. Son los dos componentes de un documento de FreeCAD, y contienen diferentes atributos y métodos. Por ejemplo, contiene, que es la Vista 3D actualmente abierta.

Módulos
El verdadero poder de FreeCAD reside en sus fieles módulos, con sus respectivos bancos de trabajo. La aplicación base de FreeCAD es más o menos un contenedor vacío. Sin sus módulos no puede hacer mucho más que crear nuevos documentos vacíos. Cada módulo no sólo añade nuevos ambientes de trabajo a la interfaz, sino también nuevos comandos de Python y nuevos tipos de objetos. Como resultado, varios tipos de objetos diferentes, e incluso totalmente incompatibles, pueden coexistir en el mismo documento. Los módulos más importantes de FreeCAD que veremos en este tutorial son:Piezas, Mallas, Croquizador o Borrador.

Croquizador y Borrador ambos utilizan el módulo Piezas para crear y manejar sus geometrías. Mientras que Malla es totalmente independiente, y maneja sus propios objetos. Más sobre esto a continuación.

Puedes comprobar todos los tipos de objeto base disponibles para el documento actual así:

Los diferentes módulos de FreeCAD no se cargan automáticamente en la consola de Python. Esto es para evitar tener un arranque muy lento. Los módulos se cargan sólo cuando los necesitas. Así, por ejemplo, para explorar lo que hay dentro del módulo Pieza:

Pero ya hablaremos más adelante del módulo de Piezas.

Malla
Las Mallas son un tipo de objeto 3D muy simple, utilizado por ejemplo por Sketchup, Blender y 3D Studio Max. Están compuestos por 3 elementos: puntos (también llamados vértices), líneas (también llamadas aristas) y caras. En muchas aplicaciones, incluido FreeCAD, las caras sólo pueden tener 3 vértices. Por supuesto, nada te impide tener una cara más grande formada por varios triángulos coplanares.

Las mallas son simples, pero como son simples puedes tener fácilmente millones de ellas en un solo documento. Sin embargo, en FreeCAD tienen menos uso y están principalmente ahí para que puedas importar objetos en formatos de malla desde otras aplicaciones. El módulo de malla también se utilizó ampliamente como el principal módulo de prueba en el primer mes de vida de FreeCAD.

Los objetos de malla y los objetos de FreeCAD son cosas diferentes. Puedes ver el objeto FreeCAD como un contenedor para un objeto Malla (y como veremos más adelante, para los objetos Pieza también). Así que para añadir un objeto malla a FreeCAD, primero debemos crear un objeto FreeCAD y un objeto Malla, y luego añadir el objeto Malla al objeto FreeCAD:

Este es un ejemplo estándar que utiliza el método para crear una esfera, pero también puedes crear mallas personalizadas desde cero definiendo sus vértices y caras.

Leer más sobre guionización de malla...

Piezas
El Pieza módulo es el módulo más potente de todo FreeCAD. Te permite crear y manipular objetos BREP. BREP significa "Representación de Límites". Un objeto BREP está definido por superficies que encierran y definen un volumen interior. A diferencia de las mallas, los objetos BREP pueden tener una gran variedad de componentes, desde caras planas hasta superficies NURBS muy complejas.

El módulo de Piezas está basado en la potente librería OpenCasCade, que permite realizar una amplia gama de operaciones complejas sobre estos objetos, como operaciones booleanas, fileteado, lofts, etc.

El módulo de Piezas funciona del mismo modo que el módulo de mallas: Se crea un objeto de FreeCAD, un objeto de Pieza, luego añadir el objeto de pieza al objeto de FreeCAD:

El módulo Pieza (como el módulo de Mallas) también tiene un atajo que automáticamente crea un objeto de FreeCAD y le añade una forma, por lo que puede acortar las tres últimas líneas a:

Al explorar el contenido de myshape, notarás muchos subcomponentes interesantes como, , , y , y una amplia gama de operaciones de geometría como  (sustracción),  (intersección) o  (unión). En la página Guionización de topología de datos se explica todo esto en detalle.

Leer más sobre guionización pieza...

Borrador
FreeCAD proporciona varios módulos, como el Croquizador o Borrador, que también crean objetos de piezas, pero le añade parámetros, o incluso un nuevo modo de manejar la geometría de las piezas. Nuestro cubo de ejemplo de arriba, es un perfecto ejemplo de objeto paramétrico. Todo lo que necesitas, para definir el cubo, es especificar un conjunto de parámetros, como las altura, ancho y longitud. Basados en los cuales, el objeto calculará automáticamente su forma de Pieza. FreeCAD te permite crear dichos objetos en Python.

El Borrador Módulo añade tipos de objetos paramétricos 2D (que son todos objetos Pieza) como líneas y círculos, y también proporciona algunas funciones genéricas que no sólo funcionan con objetos Borrador, sino con cualquier objeto Pieza. Para explorar lo que está disponible, simplemente haga:

Interfaz
La interfaz de usuario de FreeCAD está creada con Qt, un poderoso sistema de interfaces gráficas, responsable de dibujar y manejar todos los controles, menús, barras de herramientas y botones en toda la vista 3D. Qt proporciona un módulo, denominado PyQt, que permite a Python acceder y modificar interfaces Qt, como la de FreeCAD. Vamos a tratar de lidiar con la interfaz de Qt y producir un letrero de diálogo simple:

Observa que el diálogo que aparece tiene el icono de FreeCAD en su barra de herramientas, lo que significa que Qt sabe que la orden ha sido emitida desde dentro de la aplicación FreeCAD. Es posible manipular cualquier parte de la interfaz de FreeCAD.

Qt es un sistema de interfaz muy potente que permite hacer cosas muy complejas. También tiene algunas herramientas fáciles de usar como el Qt Designer con el que puedes diseñar diálogos gráficamente y luego añadirlos a la interfaz de FreeCAD con unas pocas líneas de código Python.

Lee más sobre PySide aquí...

Macros
Ahora que tienes una buena comprensión de los conceptos básicos, a dónde vamos para mantener nuestros archivos de guión en Python, y cómo vamos a ejecutarlos fácilmente desde FreeCAD? Existe un sencillo mecanismo para ello, denominado Macros. Una macro es simplemente un archivo de guión en Python, que puede ser añadida a una barra de herramientas y lanzada desde un simple clic de ratón. FreeCAD proporciona un simple editor de textos (Macro -> Macros -> Crear) donde puedes escribir o pegar archivos de guión. Una vez esté terminado, Herramientas -> Personalizar -> Macros te permite definir un botón para ella, que se puede añadir a las barras de herramientas.

Ahora estás listo para profundizar en guionización FreeCAD. Así que dirígete al Centro usuarios avanzados!