Python scripting tutorial/zh-cn

Python是一门非常简单易学的编程语言. 它集开源、多平台于一身，且可以摆脱其他各种工具独立使用，借助简单的shell脚本编程即可实现非常复杂的程序. 但是其最广泛的用处是作为一种脚本语言，因为它易于嵌入其他的应用之中. 这便是在FreeCAD中用这种语言的原因. 您可以通过python控制台或自定义脚本的方式来使用FreeCAD，这也是在非图形用户界面工具下执行非常复杂动作的方法.

例如，通过python脚本您可以：
 * 创建新的对象
 * 修改已存在的对象
 * 修改那些对象的3D表示
 * 修改FreeCAD接口

在FreeCAD中有以下几种使用python的不同方式：
 * 在FreeCAD的python解释器中使用脚本. 在此，您可以通过类似于“命令行”样式的界面来发出简单的命令
 * 在宏中使用脚本. 这是一种将缺失的工具快速添加至FreeCAD界面的便捷方法
 * 借助外部脚本. 这可用来编写更复杂的程序. 比如编写整个工作台.

在本教程中，我们将通过若干简单的示例来令您入门，除此之外，本wiki中还存在更多关于python脚本的文档. 如果您是一位python新手，希望理解它的工作原理，我们也为您提供了较为基础的Python简介.

重要提示! 在用Python脚本进行处理之前，前往窗口并选中两个选择框： 再去往并选中： 这将把您从大量恼人的事情之中解救出来！
 * Redirect internal Python output to report view
 * Redirect internal Python errors to report view
 * Report view

编写python代码
FreeCAD提供了两种环境供用户方便地编写python代码：python控制台(可从View → Panels → Python console菜单开启)或宏编辑器(Tools → Macros). 在控制台中，您可以逐行地编写python命令，按下回车键后即刻执行. 而宏中则可容纳更复杂的多行脚本，只有在执行宏时才会执行相应代码.



在此教程中，您可以使用下列两种方式编辑代码：通过在python控制台中单行复制/粘贴代码并按下来逐行执行，或在新的宏窗口中复制/粘贴全部代码一次性执行.

探索FreeCAD
让我们首先来创建一个新的空文档：

如果您在FreeCAD的python控制台中输入这些内容，会发现仅需敲入“FreeCAD.”就会弹出一个窗口，让您快速地自动补齐剩下的代码. 更强大的是，自动补齐列表中的每一项都有对应的工具提示来解释其具体使用细节. 这便于用户更轻松地浏览可用的各种函数功能. 在选择"newDocument"之前，您可以顺便查看其它存在的可选项.



现在我们就会创建一个新文档. 这就类似于按下工具栏上的"new document"按钮. 事实上，FreeCAD中的大部分按钮实现的功能也就相当于执行一、两行python代码. 更妙的是，您可以通过设置中的"show script commands in python console"选项，在控制台中查看按下每个按钮时所执行的python代码. 这对于学习如何用python复现FreeCAD的各种动作是极为有益的.

现在我们把视线重归文档本身. 来看看可以对它进行哪些操作：

借此即可阅览各种与文档有关的可选项. 通常以大写字母开头为名的是属性，而已小写字母开头的是函数（或称方法），函数会执行“某些操作”. 以一个下划线开头的名称通常为模块的内部函数，无需在上面花太多心思. 现在，让我们来使用特定方法为刚刚新建的文档添加一个新对象：

什么都没有发生. 喂神马？这其实是FreeCAD为整体大局而定的策略. 在一天里，它将处理数百复杂的对象，而所有的对象又彼此依赖. 仅做出一点儿小的改动就可能牵一发而动全身，您也许只想对整个文档重新计算一次，但可能却需要花费很长的时间……出于这个原因，基本上没有任何命令会自动更新场景. 因此，您必须手动来实现这件事：

看到了吗？我们创建的立方体现在粗线惹！FreeCAD中用于添加对象的大多按钮实际上都做了两件事：添加对象，并重新进行计算. 如果您按前文所述开启了"show script commands in python console"选项，并试着用GUI按钮添加一个球体，您将看到也执行了上述python代码.

您是否有关于"Part::Box"的问题？比如，我怎样才能知道还有哪些类型的对象可以添加至此文档中？可添加的对象全在这里：

现在让我们来查阅一下所创立方体的有关信息：

您将立刻看到一些有趣的东西，例如：

这将打印当前所创立方体的高度. 现在，让我们来尝试更改此属性：

如果用鼠标选中此立方体，您将在属性面板->“Data”选项卡->“Height”属性中看到此数据. FreeCAD对象的所有属性都将呈现于此(以及后面要提到的"View"选项卡中的属性)，利用属性名（例如前面的属性"Height"）通过python也可直接访问它们. 请尝试改变此立方体的其他规格.

向量与方位
向量是任何3D应用中最基础的一个概念. 它由三个数值构成(x、y与z)，用于描述3D空间中的一个点或一个位置. 向量可参与大量不同种类的运算，如加法、减法、投影等等等等. 在FreeCAD中，是这样运用向量的：

FreeCAD对象的另一常用特性为它们的 方位（placement）. 每个对象都有一个方位属性，其中包括了相应对象的位置(基)与方向(旋转). 此属性易于操控，例如让我们来移动所创立方体：

现在，在我们进一步讨论之前，您一定了解了上述重要概念.

App 与 Gui
FreeCAD最开始是一种命令行应用程序，并不具有当前形式的用户接口. 因此，其中大多东西都可被划分为"几何" 组件与"可视"组件. 当您在命令行模式下工作时，展示的是几何部分，而把全部可视部分简单地关掉. 因此，FreeCAD中的几乎所有对象都由两部分组成：一个Object以及一个ViewObject.

为了详述此概念，再来看我们的立方体对象，它的几何属性，如规格、位置等等都存于object中，而它的可视属性，如颜色、线宽等等都存于viewobject中. 这两样属性集就对应于属性窗口中的"Data"与"View"选项卡. 对象的viewobject属性可这样来访问：

现在，您就可以更改"View"选项卡中的属性：

当您开启FreeCAD时，python控制台已加载了2个基础模块：FreeCAD 与 FreeCADGui (也可从它们的快捷方式App 与 Gui进行访问). 此二者内含文档及其对象工作时所需的一切通用功能. 为了阐明这些概念，我们来看FreeCAD 与 FreeCADGui均包括的ActiveDocument属性，它便是当前打开的文档. FreeCAD.ActiveDocument与 FreeCADGui.ActiveDocument并不是同一对象. 它们是FreeCAD文档的两种组件，并且其中各有不同的属性与方法. 举个栗子，FreeCADGui.ActiveDocument中有ActiveView，这是当前打开的3D视图. 而FreeCAD.ActiveDocument中却没有这一项.

模块
现在，您一定在想，若没有"Part::Box"我还能做什么呢？FreeCAD的基本应用程序或多或少来只讲是一个空容器. 若没有它的各种模块，充其量也就只能创建新的空文档而已. 令FreeCAD真正强大的其实是其各种可靠的模块. 它们不止是为界面增添新的工作台那么简单，还有新的python命令以及新的对象类型. 其结果是，令多种不同的、甚至完全不兼容的对象类型可以共存于同一文档之中. 我们将在本教程中检阅FreeCAD中最重要的几种模块，它们是零件模块, 网格模块, 草图模块 与 底图模块.

草图模块与底图模块均用零件模块来创建并处理它们的几何体，它们都采用BRep（边界表示法）且网格是完全独立的，另外，它们总是处理各自的对象. 更多细节请参考下文.

您可以通过下列语法来查询当前文本中可用的基础对象类型：

尽管不同的FreeCAD模块会向FreeCAD添加各自的对象类型，但是它们并不会在python控制台中自动加载. 这样就可避免开启速度过慢. 只有在需要特定模块的时候才会加载它们. 因此，例如为了浏览零件模块中的对象类型，可以这样做：

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 workbench modules (Part, Mesh, Sketcher). The other important modules are the 3d scene module (pivy) and the interface module (pyside), we'll talk about them too below.

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

网格
Meshes are a very simple kind of 3D object, 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. Of course, nothing prevents you from having a bigger plane face made of several coplanar triangles.

Meshes are simple, but because they are simple you can easily have millions of them in a single document. However, in FreeCAD they have less use and are mostly there so you can import objects in mesh formats (.stl, .obj) from other applications. The Mesh module was also used extensively as the main test module in the first month of FreeCAD's life.

Mesh objects and FreeCAD objects are different things. You can see the FreeCAD object as a container for a Mesh object (and as we'll see below, for Part objects also). 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:

This is a standard example that uses the createSphere method to automatically create a sphere, but you can also 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 in the whole of FreeCAD. It allows you to create and manipulate BRep objects. This kind of object, unlike meshes, can have a wide variety of components. Brep stands for Boundary Representation, which means that Brep objects are defined by their surfaces; those surfaces enclose and define an inner volume. A surface can be a variety of things such as plane faces or very complex NURBS surfaces.

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:

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

By exploring the contents of myshape, you will notice many interesting subcomponents such as Faces, Edges, Vertexes, Solids and 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 and Draft, which also create Part objects. These modules add additional parameters to the objects created, or even implement a whole new way to handle the Part geometry in them. Our box example above is a perfect example of a parametric object. All you need to define the box is to specify the parameters 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 2D parametric object 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:

Interface
The FreeCAD user interface is made with Qt, a powerful graphical interface system, responsible for drawing and handling all the controls, menus, toolbars and buttons around the 3D view. Qt provides a module, PySide, 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:

Notice 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. 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 FreeCAD interface with a few lines of python code.

Read more about PySide 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 be added to a toolbar and launched via a mouse click. FreeCAD provides you with a simple text editor (Macro → Macros → Create) where you can write or paste scripts. Once the script is done, use Tools → Customiz → Macros 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!