Python scripting tutorial/pt-br

Other languages:
Introdução ao Python
Noções básicas de scripts do FreeCAD
Index

Introdução

O Python é uma linguagem de programação relativamente fácil de aprender e entender. É uma linguagem de código aberto e multiplataforma, podendo ser utilizada para diversas finalidades: desde simples scripts de shell até programas muito complexos. No entanto, seu uso mais difundido é como linguagem de script incorporada a outras aplicações. É dessa forma que ele é utilizado no FreeCAD. A partir do Console Python ou de scripts personalizados, você pode controlar o FreeCAD e fazê-lo realizar operações muito complexas.

Por exemplo, a partir de um script Python, você pode:

Existem várias maneiras de usar Python no FreeCAD:

Neste tutorial, trabalharemos em alguns exemplos básicos para você começar, mas há muito mais documentação sobre scripts em Python disponível nesta wiki. Se você é totalmente iniciante em Python e quer entender como a linguagem funciona, também temos uma introdução básica ao Python.

Antes de prosseguir com a criação de scripts em Python, vá para Editar → Preferências → Geral → Visualização de relatório e marque duas caixas:

Em seguida, vá para Exibir → Painéis e marque:

Escrevendo código Python

Existem duas maneiras de escrever código Python no FreeCAD: no Console Python (selecione Exibir → Painéis → Console Python no menu) ou no Editor de macros (selecione Macro → Macros no menu). No console, você escreve comandos Python um de cada vez, executando-os ao pressionar Enter, enquanto as macros podem conter códigos mais complexos compostos por várias linhas, executados apenas quando a macro é iniciada.

O Console Python do FreeCAD

Neste tutorial, você pode utilizar ambos os métodos. Você pode copiar e colar cada linha no console do Python e, em seguida, pressionar Enter, ou copiar e colar todo o código em uma nova janela de Macro.

Top

Explorando o FreeCAD

Vamos começar criando um novo documento vazio: 

doc = FreeCAD.newDocument()

Se você digitar isso no console Python do FreeCAD, notará que, assim que digitar FreeCAD., uma janela aparecerá, permitindo completar rapidamente o restante da linha. Melhor ainda: cada item da lista de preenchimento automático possui uma dica de ferramenta explicando sua função. Isso facilita a exploração das funcionalidades disponíveis. Antes de escolher newDocument, dê uma olhada nas outras opções.

O mecanismo de autocompletar do Console Python do FreeCAD

Agora, nosso novo documento será criado. Isso é semelhante a clicar no botão Novo na barra de ferramentas. Na verdade, a maioria dos botões no FreeCAD não faz nada além de executar uma ou mais linhas de código Python. Melhor ainda: você pode ativar uma opção em Editar → Preferências → Python → Macro para Mostrar comandos de script no console Python. Isso fará com que todo o código Python executado ao clicar nos botões seja exibido no console. É muito útil para aprender a reproduzir ações usando Python.

Agora, vamos voltar ao nosso documento e ver o que podemos fazer com ele: 

doc.

Explore as opções disponíveis. Normalmente, nomes que começam com letra maiúscula são atributos — eles contêm um valor —, enquanto nomes que começam com letra minúscula são funções (também chamadas de métodos) — eles "fazem algo". Nomes que começam com um sublinhado geralmente servem para o funcionamento interno do módulo, e você não precisa se preocupar com eles. Vamos usar um dos métodos para adicionar um novo objeto ao nosso documento: 

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

Nada acontece. Por quê? Porque o FreeCAD foi projetado para lidar com o panorama geral. Um dia, ele trabalhará com centenas de objetos complexos, todos interdependentes. Fazer uma pequena alteração em algum ponto pode ter um grande impacto; pode ser necessário recalcular todo o documento, o que pode levar muito tempo. Por esse motivo, quase nenhum comando atualiza a cena automaticamente. Você deve fazer isso manualmente: 

doc.recompute()

Agora, nosso cubo apareceu. Muitos dos botões que adicionam objetos no FreeCAD, na verdade, realizam duas ações: adicionar o objeto e recomputar. Se você tiver ativado a opção Mostrar comandos de script no console Python mencionada anteriormente, tente adicionar uma esfera usando o botão da interface gráfica; você verá as duas linhas de código Python sendo executadas em sequência.

Agora, vamos explorar o conteúdo da nossa caixa: 

box.

Você verá imediatamente algumas coisas muito interessantes, como: 

box.Height

Isso imprimirá a altura atual da nossa caixa. Agora, vamos tentar alterar isso: 

box.Height = 5

Se você selecionar sua caixa com o mouse, verá que na Visualização de Propriedades, na aba Dados, aparece a nossa propriedade DadosHeight. Todas as propriedades de um objeto do FreeCAD que aparecem ali (e também na aba Visualização — falaremos mais sobre isso depois) também são diretamente acessíveis via Python, por meio de seus nomes, assim como fizemos com a propriedade DadosHeight. Tente alterar as outras dimensões da caixa.

Top

Vetores e posicionamentos

Vetores são um conceito fundamental em qualquer aplicação 3D. Um vetor é uma lista de 3 números (x, y e z) que descreve um ponto ou posição no espaço 3D. Muitas operações podem ser realizadas com vetores, como adições, subtrações, projeções e muito mais. No FreeCAD, os vetores funcionam da seguinte maneira: 

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

Outra característica comum dos objetos do FreeCAD é o seu posicionamento. Cada objeto possui uma propriedade DadosPlacement, que contém a DadosBase (posição) e a DadosRotation (orientação) do objeto. É fácil de manipular; por exemplo, para mover o nosso objeto: 

box.Placement
box.Placement.Base
box.Placement.Base = sumvec
 
otherpla = FreeCAD.Placement()
box.Placement = otherpla

Agora, você precisa entender alguns conceitos importantes antes de prosseguirmos.

Top

Aplicativo e Interface Gráfica

O FreeCAD foi projetado para também poder ser utilizado sem a sua interface de usuário, como uma aplicação de linha de comando. Por isso, quase todos os objetos no FreeCAD consistem em duas partes: um Object (seu componente de "geometria") e um ViewObject (seu componente "visual"). Ao trabalhar no modo de linha de comando, a parte geométrica está presente, mas a parte visual está desativada.

Para ilustrar o conceito, vamos analisar nosso objeto cubo. As propriedades geométricas do cubo, como suas dimensões, posição, etc., são armazenadas no Object, enquanto suas propriedades visuais, como cor, espessura da linha, etc., são armazenadas no ViewObject. Isso corresponde às abas Dados e Visualização no Editor de Propriedades. O objeto de visualização de um objeto é acessado da seguinte forma: 

vo = box.ViewObject

Agora você também pode alterar as propriedades na guia Exibir: 

vo.Transparency = 80
vo.hide()
vo.show()

Ao iniciar o FreeCAD, o console Python já carrega dois módulos básicos: FreeCAD e FreeCADGui (que também podem ser acessados ​​pelos seus atalhos App e Gui). Eles contêm diversas funcionalidades genéricas para trabalhar com documentos e seus objetos. Para ilustrar esse conceito, observe que tanto FreeCAD quanto FreeCADGui possuem um atributo ActiveDocument, que corresponde ao documento aberto no momento. No entanto, FreeCAD.ActiveDocument e FreeCADGui.ActiveDocument não são o mesmo objeto. Eles são os dois componentes de um documento do FreeCAD e contêm atributos e métodos diferentes. Por exemplo, FreeCADGui.ActiveDocument contém ActiveView, que é a Vista 3D aberta no momento.

Top

Módulos

O verdadeiro poder do FreeCAD reside em seus módulos dedicados, com suas respectivas bancadas de trabalho (*workbenches*). A aplicação base do FreeCAD é, mais ou menos, um recipiente vazio; sem seus módulos, ela pouco mais consegue fazer além de criar documentos novos e vazios. Cada módulo não apenas adiciona novas bancadas de trabalho à interface, mas também novos comandos Python e novos tipos de objeto. Como resultado, diversos tipos de objeto diferentes — e até mesmo totalmente incompatíveis entre si — podem coexistir no mesmo documento. Os módulos mais importantes do FreeCAD que abordaremos neste tutorial são: Part, Mesh, Sketcher e Draft.

Tanto o Sketcher quanto o Draft utilizam o módulo Part para criar e manipular suas geometrias, ao passo que o Mesh é totalmente independente e gerencia seus próprios objetos. Mais detalhes abaixo.

Você pode verificar todos os tipos de objeto base disponíveis para o documento atual da seguinte forma: 

doc.supportedTypes()

Os diferentes módulos do FreeCAD não são carregados automaticamente no console Python. Isso serve para evitar uma inicialização muito lenta. Os módulos são carregados apenas quando você precisa deles. Assim, por exemplo, para explorar o conteúdo do módulo Part: 

import Part
Part.

Mas falaremos mais sobre o módulo Part abaixo.

Top

Módulo de malha

Malhas são um tipo muito simples de objeto 3D, utilizadas, por exemplo, pelo SketchUp, Blender e 3D Studio Max. Elas são compostas por três elementos: pontos (também chamados de vértices), linhas (também chamadas de arestas) e faces. Em muitas aplicações, inclusive no FreeCAD, as faces podem ter apenas 3 vértices. Naturalmente, nada impede que você tenha uma face maior composta por vários triângulos coplanares.

Malhas são simples, mas, justamente por serem simples, é fácil ter milhões delas em um único documento. No entanto, no FreeCAD, elas têm menos utilidade e servem principalmente para permitir a importação de objetos em formatos de malha (.stl, .obj) provenientes de outros aplicativos. O módulo Mesh também foi amplamente utilizado como o principal módulo de testes durante o primeiro mês de existência do FreeCAD.

Objetos de malha e objetos do FreeCAD são coisas diferentes. Você pode encarar o objeto do FreeCAD como um contêiner para um objeto de malha (e, como veremos a seguir, também para objetos do tipo *Part*). Portanto, para adicionar um objeto de malha ao FreeCAD, devemos primeiro criar um objeto do FreeCAD e um objeto de malha e, em seguida, adicionar o objeto de malha ao objeto do FreeCAD: 

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

Este é um exemplo padrão que utiliza o método createSphere() para criar uma esfera, mas você também pode criar malhas personalizadas do zero, definindo seus vértices e faces.

Leia mais sobre scripting de malhas...

Top

Módulo Part

O módulo Part é o módulo mais poderoso de todo o FreeCAD. Ele permite criar e manipular objetos BRep. BREP significa "Boundary Representation" (Representação de Fronteira). Um objeto BREP é definido por superfícies que delimitam e definem um volume interno. Ao contrário das malhas, os objetos BREP podem apresentar uma grande variedade de componentes, desde faces planas até superfícies NURBS muito complexas.

O módulo Part baseia-se na poderosa biblioteca OpenCasCade, que permite realizar uma ampla gama de operações complexas nesses objetos, como operações booleanas, arredondamentos, *lofts*, etc.

O módulo Part funciona da mesma maneira que o módulo Mesh: você cria um objeto do FreeCAD — um objeto Part — e, em seguida, adiciona o objeto Part ao objeto do FreeCAD: 

import Part
myshape = Part.makeSphere(10)
myshape.Volume
myshape.Area

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

O módulo Part (assim como o módulo Mesh) também possui um atalho que cria automaticamente um objeto do FreeCAD e adiciona uma forma a ele; assim, você pode reduzir as três últimas linhas para: 

Part.show(myshape)

Ao explorar o conteúdo de `myshape`, você notará muitos subcomponentes interessantes, como `Faces`, `Edges` (arestas), `Vertexes` (vértices), `Solids` (sólidos) e `Shells` (cascas), além de uma ampla gama de operações geométricas, como `cut` (subtração), `common` (interseção) ou `fuse` (união). A página Topological data scripting explica tudo isso em detalhes.

Leia mais sobre a criação de scripts para peças...

Top

Módulo Draft

O FreeCAD conta com muitos outros módulos, como o Sketcher e o Draft, que também criam objetos do tipo Part. Esses módulos adicionam parâmetros extras aos objetos criados ou até mesmo implementam uma maneira totalmente nova de lidar com a geometria Part neles. O exemplo da caixa mencionado acima é um exemplo perfeito de objeto paramétrico. Para definir a caixa, basta especificar os parâmetros de altura, largura e comprimento. Com base neles, o objeto calculará automaticamente sua forma Part. O FreeCAD permite criar esses objetos usando Python.

O módulo Draft adiciona tipos de objetos paramétricos 2D (que são todos objetos Part), como linhas e círculos, e também fornece algumas funções genéricas que funcionam não apenas com objetos Draft, mas com qualquer objeto Part. Para explorar o que está disponível, basta fazer o seguinte: 

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

Top

Interface

A interface de usuário do FreeCAD é criada com o Qt, um poderoso sistema de interface gráfica responsável por desenhar e gerenciar todos os controles, menus, barras de ferramentas e botões ao redor da vista 3D. O Qt fornece um módulo, o PySide, que permite ao Python acessar e modificar interfaces Qt, como a do FreeCAD. Vamos experimentar manipular a interface Qt e criar uma caixa de diálogo simples: 

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

Observe que a caixa de diálogo exibida apresenta o ícone do FreeCAD em sua barra de ferramentas, o que significa que o Qt reconhece que a solicitação foi originada de dentro do aplicativo FreeCAD. É possível manipular qualquer parte da interface do FreeCAD.

O Qt é um sistema de interface muito poderoso que permite realizar tarefas complexas. Ele também conta com ferramentas fáceis de usar, como o Qt Designer, com o qual você pode projetar caixas de diálogo graficamente e, em seguida, adicioná-las à interface do FreeCAD com apenas algumas linhas de código Python.

Leia mais sobre o PySide aqui...

Top

Macros

Agora que você já compreende bem os conceitos básicos, onde vamos armazenar nossos scripts Python e como vamos executá-los no FreeCAD? Existe um mecanismo simples para isso, chamado Macros. Uma macro é um script Python que pode ser adicionado a uma barra de ferramentas e executado com um clique do mouse. O FreeCAD oferece um editor de texto simples (Macro → Macros → Criar) onde você pode escrever ou colar scripts. Assim que o script estiver pronto, use Ferramentas → Personalizar → Macros para definir um botão para ele, o qual poderá ser adicionado às barras de ferramentas.

Scripts externos

Um método alternativo para criar, salvar e executar seus próprios scripts Python é criá-los fora do FreeCAD, utilizando um editor de sua escolha (por exemplo, o Vim). Para executar seu script Python dentro do FreeCAD, certifique-se de salvá-lo com a extensão .py.

Em seguida, use Arquivo → Abrir para abrir seu script. Ele será carregado em uma nova aba na Área de visualização principal. Você pode executar seu script clicando no botão Executar macro. Quaisquer erros ou saídas do script serão exibidos na Visualização de relatório.

Ao fazer e salvar quaisquer modificações no seu script já carregado, uma caixa de diálogo aparecerá perguntando se você deseja recarregar o script modificado no FreeCAD.

Você pode prosseguir para a página Noções Básicas de Script no FreeCAD, ou pode acessar essa página e outras páginas relevantes na Central de Usuários Avançados.

Top

Introdução ao Python
Noções básicas de scripts do FreeCAD
Index
Power user documentation