Freecad 0 15 manual by Rodrigo Paludo

Fr e e C A D version 0.15

user manual compiled from articles from http://www.freecadweb.org/wiki

Online Help Startpage

Welcome to the FreeCAD on-line help This document has been automatically created from the contents of the official FreeCAD wiki documentation, which can be read online at http://www.freecadweb.org/wiki/index.php?title=M ain_Page. Since the wiki is actively maintained and continuously developed by the FreeCAD community of developers and users, you may find that the online version contains more or newer information than this document. There you will also find in-progress translations of this documentation in several languages. But nevertheless, we hope you will find here all information you need. In case you have questions you can't find answers for in this document, have a look on the FreeCAD forum, where you can maybe find your question answered, or someone able to help you.

How to use This document is divided into several sections: introduction, usage, scripting and development, the last three address specifically the three broad categories of users of FreeCAD: end-users, who simply want to use the program, power-users, who are interested by the scripting capabilities of FreeCAD and would like to customize some of its aspects, and developers, who consider FreeCAD as a base for developing their own applications. If you are completely new to FreeCAD, we suggest you to start simply from the introduction.

Contribute As you may have experienced sometimes, programmers are really bad help writers! For them it is all completely clear because they made it that way. Therefore it's vital that experienced users help us to write and revise the documentation. Yes, we mean you! How, you might ask? Just go to the Wiki at http://www.freecadweb.org/wiki/index.php in the User section. You will need a sourceforge account to log in, and then ask on the forum or on the irc channel for write permission (the wiki is writeprotected to avoid spamming). Then you can start editing! Also, check out the page at http://www.freecadweb.org/wiki/index.php?title=Help_FreeCAD for more ways you can help FreeCAD.

About FreeCAD

FreeCAD is a general purpose parametric 3D CAD modeler. The development is completely Open Source (LGPL License). FreeCAD is aimed directly at mechanical engineering and product design but also fits in a wider range of uses around engineering, such as architecture or other engineering specialties. FreeCAD features tools similar to Catia, SolidWorks or Solid Edge, and therefore also falls into the category of M CAD, PLM , CAx and CAE. It is a feature based parametric modeler with a modular software architecture which makes it easy to provide additional functionality without modifying the core system. As with many modern 3D CAD modelers it has many 2D components in order to sketch 2D shapes or extract design details from the 3D model to create 2D production drawings, but direct 2D drawing (like AutoCAD LT) is not the focus, neither are animation or organic shapes (like M aya, 3ds M ax, Blender or Cinema 4D), although, thanks to its wide adaptability, FreeCAD might become useful in a much broader area than its current focus. FreeCAD makes heavy use of all the great open-source libraries that exist out there in the field of Scientific Computing. Among them are OpenCascade, a powerful CAD kernel, Coin3D, an incarnation of Open Inventor, Qt, the world-famous UI framework, and Python, one of the best scripting languages available. FreeCAD itself can also be used as a library by other programs. FreeCAD is also fully multi-platform, and currently runs flawlessly on Windows and Linux/Unix and Mac OSX systems, with the exact same look and functionality on all platforms. For more information about FreeCAD's capabilities, take a look at the Feature list, the latest release notes or the Getting started articles.

About the FreeCAD project The FreeCAD project was started as far as 2001, as described in its history page. FreeCAD is maintained and developed by a community of enthusiastic developers and users (see the contributors page). They work on FreeCAD voluntarily, in their free time. They cannot guarantee that FreeCAD contains or will contain everything you might wish, but they will usually do their best! The community gathers on the FreeCAD forum, where most of the ideas and decisions are discussed. Feel free to join us there!

Getting started What's new Version 0.11 Release notes : Check what's new in the 0.11 release of FreeCAD Version 0.12 Release notes : Check what's new in the 0.12 release of FreeCAD Version 0.13 Release notes : Check what's new in the 0.13 release of FreeCAD Version 0.14 Release notes : Check what's new in the 0.14 release of FreeCAD Version 0.15 Release notes : Check what's new in the 0.15 release of FreeCAD

Foreword FreeCAD is a 3D CAD/CAE parametric modeling application. It is primarily made for mechanical design, but also serves all other uses where you need to model 3D objects with precision and control over modeling history. FreeCAD is still in the early stages of development, so, although it already offers you a large (and growing) list of features, much is still missing, specially comparing it to commercial solutions, and you might not find it developed enough yet for use in production environment. Still, there is a fast-growing community of enthusiastic users, and you can already find many examples of quality projects developed with FreeCAD. Like all open-source projects, the FreeCAD project is not a one-way work delivered to you by its developers. It depends much on its community to grow, gain features, and stabilize (get bugs fixed). So don't forget this when starting to use FreeCAD, if you like it, you can directly influence and help the project!

Installing First of all (if not done already) download and install FreeCAD. See the Download page for information about current versions and updates, and the Installing page for information about how to install FreeCAD. There are install packages ready for Windows (.msi), Ubuntu & Debian (.deb) openSUSE (.rpm) and Mac OSX. As FreeCAD is open-source, if you are adventurous, but want to have a look at the brand-new features being developed right now, you can also grab the source code and compile FreeCAD yourself.

Exploring FreeCAD

1. The 3D view, showing the contents of your document 2. The tree view, which shows the hierarchy and construction history of all the objects in your document 3. The properties editor, which allows you to view and modify properties of the selected object(s) 4. The output window, which is where FreeCAD prints messages, warnings and errors 5. The python console, where all the commands executed by FreeCAD are printed, and where you can enter python code 6. The workbench selector, where you select the active workbench The main concept behind the FreeCAD interface is that it is separated into workbenches. A workbench is a collection of tools suited for a specific task, such as working with meshes, or drawing 2D objects, or constrained sketches. You can switch the current workbench with the workbench selector (6). You can customize the tools included in each workbench, add tools from other workbenches or even self-created tools, that we call macros. There is also a generic workbench which gathers the most commonly used tools from other workbenches, called the complete workbench. When you start FreeCAD for the first time, you are presented with the start center:

The Start Center allows you to quickly jump to one of the most common workbenches, open one of the recent files, or see the latest news from the FreeCAD world. You can change the default workbench in the preferences.

Navigating in the 3D space FreeCAD has four different navigation modes available, that change the way you use your mouse to interact with the objects in the 3D view and the view itself. One of them is specifically made for touchpads, where the middle mouse button is not used. The following table describes the default mode, called CAD Navigation (You can quickly change the current navigation mode by right-clicking on an empty area of the 3D view):

Select

Pan

Zoom

Rotate View

Rotate View Alternate Method

Press the left mouse button over an object you want to select. Holding down ctrl allows the selection of multiple objects.

Click the middle mouse button and move the object around to pan

Use the mouse wheel Click first with the to zoom in and out. middle mouse button, hold it down, and then click the left mouse button and drag the mouse in the desired direction. The cursor location at the middle mouse button click determines the center of rotation. Rotation works like spinning a ball which rotates around its center. If the buttons are released before you stop the mouse motion, the object continues spinning, if this is enabled. A double click with the middle mouse button sets a new center of rotation.

Press and hold Ctrl key and click and release right mouse button to pan (rev 0.14)

Once in Pan mode, press and release left mouse button to Zoom, to exit back to pan mode press and release right mouse button (rev 0.14)

Click first with the middle mouse button, hold it down, and then click the right mouse button and drag the mouse in the desired direction. This method works just like the previously described Rotate View that uses Middle Mouse Button + Left Mouse Button, except that the middle mouse button may be released after the right mouse button is pressed. Users who use the mouse with their right hand may find this Rotate View method easier than the previous method.

Once in Pan mode, click and momentary hold left mouse button to rotate, to exit back to pan mode press and release right mouse button (rev 0.14)

You also have several view presets (top view, front view, etc) available in the View menu and on the View toolbar, and by numeric shortcuts ( 1 , 2 , etc...), and by right-clicking on an object or on an empty area of the 3D view, you have quick access to some common operations, such as setting a particular view, or locating an object in the Tree view.

First steps with FreeCAD FreeCAD's focus is to allow you to make high-precision 3D models, to keep tight control over those models (being able to go back into modelling history and change parameters), and eventually to build those models (via 3D printing, CNC machining or even construction worksite). It is therefore very different from some other 3D applications made for other purposes, such as animation film or gaming. Its learning curve can be steep, specially if this is your first contact with 3D modeling. If you are struck at some point, don't forget that the friendly community of users on the FreeCAD forum might be able to get you out in no time. The workbench you will start using in FreeCAD depends on the type of job you need to do: If you are going to work on mechanical models, or more generally any small-scale objects, you'll probably want to try the PartDesign Workbench. If you will work in 2D, then switch to the Draft Workbench, or the Sketcher Workbench if you need constraints. If you want to do BIM, launch the Arch Workbench. If you are working with ship design, there is a special Ship Workbench for you. And if you come from the OpenSCAD world, try the OpenSCAD Workbench. You can switch workbenches at any time, and also customize your favorite workbench to add tools from other workbenches.

Working with the PartDesign and Sketcher workbenches The PartDesign Workbench is specially made to build complex objects, starting from simple shapes, and adding or removing pieces (that we call "features"), until you get to your final object. All the features you applied during the modelling process are stored in a separate view called the tree view, which also contains the other objects in your document. You can think of a PartDesign object as a succession of operations, each one applied to the result of the preceding one, forming one big chain. In the tree view, you see your final object, but you can expand it and retrieve all preceding states, and change any of their parameter, which automatically updates the final object.

The PartDesign workbench makes heavy use of another workbench, the Sketcher Workbench. The sketcher allows you to draw 2D shapes, which are defined by applying Constraints to the 2D shape. For example, you might draw a rectangle and set the size of a side by applying a length constraint to one of the sides. That side then cannot be resized anymore (unless the constraint is changed). Those 2D shapes made with the sketcher are used a lot in the PartDesign workbench, for example to create 3D volumes, or to draw areas on the faces of your object that will then be hollowed from its main volume. This is a typical PartDesign workflow: 1. Create a new sketch 2. Draw a closed shape (make sure all points are joined) 3. Close the sketch 4. Expand the sketch into a 3D solid by using the pad tool 5. Select one face of the solid 6. Create a second sketch (this time it will be drawn on the selected face) 7. Draw a closed shape 8. Close the sketch 9. Create a pocket from the second sketch, on the first object Which gives you an object like this:

At any moment, you can select the original sketches and modify them, or change the extrusion parameters of the pad or pocket operations, which will update the final object.

Working with the Draft and Arch workbenches The Draft Workbench and Arch Workbench behave a bit differently than the other workbenches above, although they follow the same rules, which are common to all of FreeCAD. In short, while the Sketcher and PartDesign are made primarily to design single pieces, Draft and Arch are made to ease your work when working with several, simpler objects. The Draft Workbench offers you 2D tools a bit similar to what you can find in traditional 2D CAD applications such as AutoCAD. However, 2D drafting being far away from the scope of FreeCAD, don't expect to find there the full array of tools that these dedicated applications offer. Most of the Draft tools work not only in a 2D plane but also in the full 3D space, and benefit from special helper systems such as Work planes and object snapping. The Arch Workbench adds BIM tools to FreeCAD, allowing you to build architectural models with parametric objects. The Arch workbench relies much on other modules such as Draft and Sketcher. All the Draft tools are also present in the Arch workbench, and most Arch tools make use of the Draft helper systems. A typical workflow with Arch and Draft workbenches might be: 1. Draw a couple of lines with the Draft Line tool 2. Select each line and press the Wall tool to build a wall on each of them 3. Join the walls by selecting them and pressing the Arch Add tool 4. Create a floor object, and move your walls in it from the Tree view

5. Create a building object, and move your floor in it from the Tree view 6. Create a window by clicking the Window tool, select a preset in its panel, then click on a face of a wall 7. Add dimensions by first setting the working plane if necessary, then using the Draft Dimension tool Which will give you this:

See also Draft Pattern page.

Scripting The Wire tool can by used in macros and from the python console by using the following function: makeWire (list or Part.Wire, [closed], [placement], [facemode]) Creates a Wire object from the given list of vectors or from the given wire. If closed is True or if first and last points are identical, the wire is closed. If facemode is True (and the wire is closed), the wire will appear filled. The current Draft linewidth and color will be used. Returns the newly created object. Example: import FreeCAD,Draft p1 = FreeCAD.Vector(0,0,0) p2 = FreeCAD.Vector(1,1,0) p3 = FreeCAD.Vector(2,0,0) Draft.makeWire([p1,p2,p3],closed=True)

Draft Circle Description The Circle tool creates a circle in the current work plane by entering two points, the center and the radius, or by picking tangents, or any combination of those. It takes the linewidth and color previously set on the Tasks tab. This tool works the same way as the Draft Arc tool, except that it stops after entering the radius.

Draft Circle M enu location Draft -> Circle Workbenches Draft, Arch Default shortcut C I See also Draft Arc

How to use 1. Press the

Draft Circle button, or press C then I keys

2. Click a first point on the 3D view, or type a coordinate 3. Click a second point on the 3D view, or enter a radius value.

Options The primary use of the circle tool is by picking two points, the centre and a point on the circumference, defining the radius. By pressing ALT , you can select a tangent instead of picking a point. You can therefore construct several types of circles by selecting one, two or three tangents. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Circle tool will restart after you give the second point, allowing you to draw another circle without pressing the Circle button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your second point horizontally or vertically in relation to the first one. Press I or the Filled button to have the circle to appear as a face after it has been closed. This simply sets the View>Property of the Circle to "Flat lines" or "Wireframe", so it can easily be changed later. Press ESC or the Cancel button to abort the current Line command. The circle can be turned into an arc after creation, by setting its first angle and last angle properties to different values. Circles, when in "Flat Lines" display mode, can display a hatch pattern, by setting their "Pattern" property below.

Properties DATA

Radius: The radius of the circle

VIEW

Pattern: Specifies a hatch pattern to fill the wire with

VIEW

Pattern Size: Specifies the size of the hatch pattern

See also Draft Pattern page.

Scripting The Circle tool can by used in macros and from the python console by using the following function: makeCircle (radius, [placement], [facemode], [startangle], [endangle])

Creates a circle object with given radius. If a placement is given, it is used. If facemode is False, the circle is shown as a wireframe, otherwise as a face. If startangle AND endangle are given (in degrees), they are used and the object appears as an arc. Returns the newly created object. Example: import Draft myCircle = Draft.makeCircle(2)

Draft Arc Description The Arc tool creates an arc in the current work plane by entering four points, the center, the radius, the first point and the last point, or by picking tangents, or any combination of those. It takes the linewidth and color previously set on the Tasks tab. This tool works the same way as the Draft Circle tool, but adds start and end angles.

Draft Arc M enu location Draft â&#x2020;&#x2019; Arc Workbenches Draft, Arch Default shortcut A R See also Draft Circle

How to use 1. Press the

Draft Arc button, or press A then R keys

2. Click a first point on the 3D view, or type a coordinate 3. Click a second point on the 3D view, or enter a radius value 4. Click a third point in the 3D view, or enter a start angle 5. Click a fourth point in the 3D View, or enter an end ange

Options The primary use of the arc tool is by picking four points: the centre, a point on the circumference, defining the radius, a third point defining the start of the arc, and a fourth one defining its end. By pressing ALT , you can select a tangent instead of picking point, to define the base circle of the arc. You can therefore construct several types of circles by selecting one, two or three tangents. The direction of the arc depends on the movement you are doing with your mouse. If you start to move clockwise after the third point is entered, your arc will go clockwise. To go counter-clockwise, simply move your mouse back over the third point, until the arc starts drawing in the other direction. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Arc tool will restart after you give the fourth point, allowing you to draw another arc without pressing the Arc button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your point horizontally or vertically in relation to the center. Press ESC or the Cancel button to abort the current Line command. The arc can be turned into a circle after creation, by setting a same value to its first angle and last angle properties.

Properties DATA

Radius: The radius of the arc

DATA

First Angle: The angle of the first point of the arc

DATA

Last Angle: The angle of the last point of the arc

Scripting The Circle tool can also be used to create arcs in macros and from the python console by using the following function, giving it additional arguments:

makeCircle (radius, [placement], [facemode], [startangle], [endangle]) Creates a circle object with given radius. If a placement is given, it is used. If facemode is False, the circle is shown as a wireframe, otherwise as a face. If startangle AND endangle are given (in degrees), they are used and the object appears as an arc. Returns the newly created object. Example: import Draft myArc = Draft.makeCircle(2,startangle=0,endangle=90)

Draft Ellipse Description The Ellipse tool creates an ellipse in the current work plane by entering two points, defining the corner of a rectangular box in which the ellipse will fit. It takes the linewidth and color previously set on the Tasks tab.

Draft Ellipse M enu location Draft -> Ellipse Workbenches Draft, Arch Default shortcut E L See also Draft Circle

How to use 1. Press the

Draft Ellipse button, or press E then L keys

2. Click a first point on the 3D view, or type a coordinate 3. Click a second point on the 3D view, or type a coordinate

Options To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Ellipse tool will restart after you give the second point, allowing you to draw another ellipse without pressing the Ellipse button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your second point horizontally or vertically in relation to the first one. Press I or the Filled button to have the ellipse to appear as a face after it has been closed. This simply sets the View->Property of the ellipse to "Flat lines" or "Wireframe", so it can easily be changed later. Press ESC or the Cancel button to abort the command. Ellipses, when in "Flat Lines" display mode, can display a hatch pattern, by setting their "Pattern" property below.

Properties DATA

M ajor Radius: The major radius of the ellipse

DATA

M inor Radius: The minor radius of the ellipse

VIEW

Pattern: Specifies a hatch pattern to fill the ellipse with

VIEW

Pattern Size: Specifies the size of the hatch pattern

See also Draft Pattern page.

Scripting The Ellipse tool can by used in macros and from the python console by using the following function: makeEllipse (majorradius, minorradius, [placement], [facemode]) Creates an ellipse object with given major and minor radius. If a placement is given, it is used. If facemode is False, the ellipse is shown as a wireframe, otherwise as a face. Returns the newly created object.

Example: import Draft myEllipse = Draft.makeEllipse(4,2)

Draft Polygon Description The polygon tool creates a regular polygon by picking two points, the center and a second point defining a radius. It takes the linewidth and color previously set on the Tasks tab.

Draft Polygon M enu location Draft -> Polygon Workbenches Draft, Arch Default shortcut P G See also None

How to use 1. Press the

Draft Polygon button, or press P then G keys

2. Click a first point on the 3D view, or type a coordinate to indicate the center 3. Adjust the desired number of sides in the options dialog, 4. Click another point on the 3D view, or type a radius value to define the polygon radius. The polygon will also be a face, even if it appears as wireframe.

Options To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Polygon tool will restart after you finish or close it, allowing you to draw another one without pressing the Polygon button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last one. Press I or the Filled button to have the polygon to appear as a face after it has been closed. This simply sets the View->Property of the Rectangle to "Flat lines" or "Wireframe", so it can easily be changed later. Press ESC or the Cancel button to abort the current command. Polygons, when in "Flat Lines" display mode, can display a hatch pattern, by setting their "Pattern" property below.

Properties DATA

Radius: The radius of the defining circle

DATA

Draw M ode: Specifies if the polygon is inscribed or circumscribed around the defining circle

DATA

Faces Number: The number of sides of the polygon

DATA

Chamfer Size: Specifies the size of chamfered corners

DATA

Fillet Radius: Specifies a curvature radius to give to the corners of the rectangle

VIEW

Pattern: Specifies a hatch pattern to fill the wire with

VIEW

Pattern Size: Specifies the size of the hatch pattern

See also Draft Pattern page.

Scripting The Polygon tool can by used in macros and from the python console by using the following function: makePolygon(nfaces,[radius],[inscribed],[placement],[face])

Creates a polygon object with the given number of faces and the radius. If inscribed is False, the polygon is circumscribed around a circle with the given radius, otherwise it is inscribed. If face is True, the resulting shape is displayed as a face, otherwise as a wireframe. Returns the newly created object. Example: import Draft Draft.makePolygon(5,radius=3)

Draft Rectangle Description The rectangle tool creates a rectangle by picking two opposite points. It takes the linewidth and color previously set on the Tasks tab.

Draft Rectangle M enu location Draft -> Rectangle Workbenches Draft, Arch Default shortcut R E See also Part Box

How to use 1. Press the

Draft Rectangle button, or press R then E keys

2. Click a first corner point on the 3D view, or type a coordinate 3. Click another opposite point on the 3D view, or type a coordinate. The rectangle will also be a face, even if it appears as wireframe.

Options Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press R or click the checkbox to check/uncheck the Relative button. If relative mode is on, the coordinates of the next point are relative to the last one. If not, they are absolute, taken from the (0,0,0) origin point. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Rectangle tool will restart after you finish or close it, allowing you to draw another one without pressing the Rectangle button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last one. Press I or the Filled button to have the rectangle to appear as a face after it has been closed. This simply sets the View->Property of the Rectangle to "Flat lines" or "Wireframe", so it can easily be changed later. Press ESC or the Cancel button to abort the current Line command. Rectangles, when in "Flat Lines" display mode, can display a hatch pattern, by setting their "Pattern" property.

Properties DATA

Length: Specifies the length of the rectangle

DATA

Width: Specifies the width of the rectangle

DATA

Chamfer Size: Specifies the size of chamfered corners

DATA

Fillet Radius: Specifies a curvature radius to give to the corners of the rectangle

Texture Image: Allows to give the path to an image file to be mapped on the rectangle. It is up to you to give the rectangle the same proportion as the image if you want to avoid distortions. Blanking this property will remove the image. VIEW

VIEW

Pattern: Specifies a hatch pattern to fill the wire with.

VIEW

Pattern Size: Specifies the size of the hatch pattern

See also Draft Pattern page.

Scripting The Rectangle tool can by used in macros and from the python console by using the following function:

makeRectangle (length, width, [placement], [facemode]) Creates a Rectangle object with length in X direction and height in Y direction. If a placement is given, it is used. If facemode is False, the rectangle is shown as a wireframe, otherwise as a face. The current Draft linewidth and color will be used. Returns the newly created object. Example: import FreeCAD,Draft Draft.makeRectangle(10,4)

Draft Text Draft Text

Description The Text tool inserts a piece of text at a given point in the current document. It takes the text size and color previously set on the Tasks tab.

M enu location Draft â&#x2020;&#x2019; Text Workbenches Draft, Arch Default shortcut T E See also None

How to use 1. Press the

Draft Text button, or press T then E keys

2. Click a point on the 3D view, or type a coordinate 3. Enter the desired text, pressing ENTER between each line 4. Press ENTER twice to finish the operation.

Options Pressing CTRL will snap your point to available snap locations. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Pressing ESC will cancel the operation. When editing the text, pressing ENTER or DOWN ARROW allow you to enter or edit a next line of text. Pressing UP ARROW allows you to edit a previous line of text. Pressing ENTER twice (thus leaving the last line empty) adds the text to the document and closes the editor.

Properties DATA

Position: The base point of the text block

DATA

Label Text: The contents of the text block

VIEW

Display M ode: Specifies if the text is aligned to the scene axes or always faces the camera

VIEW

Font Size: The size of the letters

VIEW

Justification: Specifies if the text is aligned to the left, right or center of the base point.

VIEW

Line Spacing: Specifies the space between lines of text

VIEW

Rotation: Specifies a rotation to be applied to the text

VIEW

Rotation Axis: Specifies the axis to use for the rotation

Font Name: The font to use to draw the text. It can be a font name, such as "Arial", a default style such as "sans", "serif" or "mono", or a family such as "Arial,Helvetica,sans" or a name with a style such as "Arial:Bold". If the given font is not found on the system, a generic one is used instead. VIEW

Scripting The Text tool can by used in macros and from the python console by using the following function: makeText (string or list, [Vector], [screenmode]) Creates a Text object, at the given point if a vector is provided, containing the string or the strings given in the list, one string by line.

The current Draft color and text height and font specified in preferences are used. If screenmode is True, the text always faces the view direction, otherwise it lies on the XY plane. Returns the newly created object. Example: import FreeCAD,Draft Draft.makeText("This is a sample text",FreeCAD.Vector(1,1,0))

Draft Dimension Description The dimension tool creates a dimension in the current document with two points defining the distance to measure, and a third point specifying where the dimension line passes.

Draft Dimension M enu location Draft â&#x2020;&#x2019; Dimension Workbenches Draft, Arch Default shortcut D I See also FlipDimension

How to use 1. Press the

Draft Dimension button, or press D then I keys

2. Click a point on the 3D view, or type a coordinate 3. Click a second point on the 3D view, or type a coordinate 4. Click a third on the 3D view, or type a coordinate

Available dimension types Linear dimensions: by picking any 2 points or any straight edge with ALT pressed. Horizontal/vertical dimensions: by pressing SHIFT after the first point is selected. Diameter dimensions: by picking a curved edge with ALT pressed. Radius dimensions: by picking a curved edge with ALT pressed, then pressing SHIFT . Angular dimensions: by picking 2 straight edges with ALT pressed.

Options Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Pressing SHIFT will constrain the dimension horizontally or vertically, or, when working on a circular edge, switches between diameter and radius modes. Press R or click the checkbox to check/uncheck the Relative button. If relative mode is on, the coordinates of the next point are relative to the last one. If not, they are absolute, taken from the (0,0,0) origin point. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, you will be able to draw continued dimensions, one after the other, that share the same baseline. Press ESC or the Cancel button to abort the current Line command. By picking an existing edge with ALT , instead of entering measurement points, the dimension will become parametric and remember which edge it is bound to. If the endpoints of that edge move later on, the dimension will follow them. The direction of the dimension can be changed afterwards, by modifying its "Direction" property

Properties DATA

Start: The start point of the distance to measure

DATA

End: The end point of the distance to measure

DATA

Dimline: A point through which the dimension line must pass

VIEW

Display M ode: Specifies if the text is aligned to the dimension lines or always faces the camera

VIEW

Font Size: The size of the letters

VIEW

Ext Lines: The size of the extension lines (between the measurement points and the dimension line)

VIEW

Text Position: Can be used to force the text to be displayed at a certain position

VIEW

Text Spacing: Specifies the space between the text and the dimension line

Override: Specifies a text to display instead of the measurement. Insert "$dim", inside that text, to display the measurement value VIEW

VIEW

Arrow Type: The type of arrow to use

VIEW

Arrow Size: The size of the arrows

VIEW

Decimals: The number of decimal places to display on the dimension

VIEW

Flip Arrows: Reverse the orientation of arrows

Scripting The Dimension tool can by used in macros and from the python console by using the following functions: makeDimension (p1,p2,[p3]) or makeDimension (object,i1,i2,p3) or makeDimension (objlist,indices,p3) Creates a Dimension object with the dimension line passign through p3. The Dimension object takes the Draft linewidth and color set in the command bar. There are multiple ways to create a dimension, depending on the arguments you pass to it: 1. (p1,p2,p3): creates a standard dimension from p1 to p2. 2. (object,i1,i2,p3): creates a linked dimension to the given object, measuring the distance between its vertices indexed i1 and i2. 3. (object,i1,mode,p3): creates a linked dimension to the given object, i1 is the index of the (curved) edge to measure, and mode is either "radius" or "diameter". Returns the newly created object. makeAngularDimension (center,[angle1,angle2],p3) creates an angular Dimension from the given center, with the given list of angles, passing through p3. Returns the newly created object. Example: import FreeCAD,Draft p1 = FreeCAD.Vector(0,0,0) p2 = FreeCAD.Vector(1,1,0) p3 = FreeCAD.Vector(2,0,0) Draft.makeDimension(p1,p2,p3)

Links Tutorial: Projecting dimensions on a Drawing Page

Draft BSpline Draft BSpline

Description The BSpline tool creates a B-Spline curve from several points in the current work plane. It takes the linewidth and color previously set on the Tasks tab. The BSpline tool behaves exactly like the Draft Wire tool.

M enu location Draft â&#x2020;&#x2019; BSpline Workbenches Draft, Arch Default shortcut B S See also Draft Wire

How to use 1. Press the

Draft BSpline button, or press B then S keys

2. Click a first point on the 3D view, or type a coordinate 3. Click additional point on the 3D view, or type a coordinate 4. Press F or C , or double-click the last point, or click on the first point to finish or close the spline. If the spline is closed, it will also be a face, even if it appears as wireframe.

Options Press F or the

Finish button to finish the spline, leaving it open

Press C or the Close button or click on the first point to finish the spline, but making it closed by adding a last segment between the last point and the first one. Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press R or click the checkbox to check/uncheck the Relative button. If relative mode is on, the coordinates of the next point are relative to the last one. If not, they are absolute, taken from the (0,0,0) origin point. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the BSpline tool will restart after you finish or close it, allowing you to draw another one without pressing the BSpline button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last one. Press W or press the

Wipe button to remove the existing segments and start the spline from the last point.

Press CTRL + Z or press the

Undo button to undo the last point.

Press I or the Filled button to have the spline to appear as a face after it has been closed. This simply sets the View>Property of the Wire to "Flat lines" or "Wireframe", so it can easily be changed later. Press ESC or the Cancel button to abort the current BSpline command. BSplines, when in "Flat Lines" display mode, can display a hatch pattern, by setting their "Pattern" property below.

Properties DATA

Closed: Specifies if the spline is closed or not

VIEW

End Arrow: Shows an arrow symbol at the last point of the spline, so it can be used as an annotation leader line

VIEW

Pattern: Specifies a hatch pattern to fill the wire with

VIEW

Pattern Size: Specifies the size of the hatch pattern

Scripting

The BSpline tool can by used in macros and from the python console by using the following function: makeBSpline (pointslist,[closed],[placement]) Creates a B-Spline object from the given list of vectors. If closed is True or first and last points are identical, the wire is closed. If face is true (and the bspline is closed), the bspline will appear filled. Instead of a list of points, you can also pass a Part Wire. Returns the newly created object. Example: import FreeCAD,Draft p1 = FreeCAD.Vector(0,0,0) p2 = FreeCAD.Vector(1,1,0) p3 = FreeCAD.Vector(2,0,0) Draft.makeBSpline([p1,p2,p3],closed=True)

Draft Point Description The Point tool creates a simple point in the current work plane, handy to serve as reference for placing other objects later. It takes the color previously set on the Tasks tab.

Draft Point M enu location Draft -> Point Workbenches Draft, Arch Default shortcut P T See also None

How to use 1. Press the

Draft Point button, or press P then T keys

2. Click a point on the 3D view, or type a coordinate

Options To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press ESC or the Cancel button to abort the current Line command.

Properties DATA

X: The X coordinate of the point

DATA

Y: The Y coordinate of the point

DATA

Z: The Z coordinate of the point

Scripting The Point tool can by used in macros and from the python console by using the following function: makePoint([x],[y],[z]) makes a point at the given coordinates. If no X, Y and Z coordinates are given, the point is created at (0,0,0). Returns the newly created object. Example: import Draft Draft.makePoint(6,4,2)

Draft ShapeString Description The ShapeString tool inserts a compound shape representing a text string at a given point in the current document. Text height, tracking and font can be specified.

Draft ShapeString M enu location Draft -> ShapeString Workbenches Draft, Arch Default shortcut S S See also None

How to use 1. Press the

Draft ShapeString button, or press S then S keys

2. Click a point on the 3D view, or type a coordinate 3. Enter the desired text, press ENTER 4. Enter the desired size, press ENTER 5. Enter the desired tracking, press ENTER 6. Press ENTER to accept the displayed font file, or, 7. Press ... to select a font file.

Options To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Pressing ESC will cancel the operation. You can set a default font file in Draft/Prefences.

Properties DATA

Position: The base point of the compound shape

DATA

String: The contents of the text string

DATA

Size: The height of the letters in FC units

DATA

Tracking: The inter-character spacing in FC units

DATA

Font File: The font definition file used to draw the string

Scripting The ShapeString tool can by used in macros and from the python console by using the following function: makeShapeString(String,FontFile,[Size],[Tracking]) Turns a text string into a Compound Shape using a specified font. Example: import FreeCAD,Draft Draft.makeShapeString("This is a sample text", "/usr/share/fonts/truetype/msttcorefonts/Arial.ttf", 200.0,10)

Selecting A Font

ShapeString uses the internal geometry of a font to make FreeCAD shapes. To do this it must read the actual font file (*.tff, etc). If the Font Selection box is empty, you must type the full path to the font file or use ... to select a font file.

Limitations This tool is not available in FreeCAD versions anterior to 0.14 TrueType(*.ttf), OpenType(*.otf) and Type1(*.pfb) font files are supported. Very small text heights may result in deformed character glyphs due to loss of detail in scaling. The current version is limited to left-to-right layouts on a horizontal baseline.

Draft Facebinder Description The facebinder a very simple object constructed from selected faces of other objects. It is of parametric, you can modify the original object and the facebinder object updates accordingly. It can then be used for example for making an extrusion out of a collection of faces from other objects. A typical use is in architectural design, to build an object that covers several pieces of walls. You can move and rotate the facebinder around after its creation, everything will stay linked to the original faces.

Draft Facebinder M enu location Draft â&#x2020;&#x2019; Facebinder Workbenches Draft, Arch Default shortcut F F See also None

How to use 1. Select faces on objects (use CTRL to select several faces) 2. Press the

Facebinder , button, or press F , F keys

Scripting The facebinder tool can be usedin scripts and macros by using the following function: makeFacebinder ( selectionset ) Creates a facebinder object from the given selection set, which is a list of selection objects such as returned by the FreeCADGui.Selection.getSelectionEx() method. Only selected faces are taken into account Returns the newly created object Example: import Draft, FreeCADGui mySelection = FreeCADGui.Selection.getSelectionEx() Draft.makeFacebinder(mySelection)

Limitations Not available before version 0.14

Draft BezCurve Description

Draft BezCurve

The BezCurve tool creates a Bezier Curve (or a piecewise Bezier Curve) from several points in the current work plane. It takes the linewidth and color previously set on the Tasks tab. The object is created as a single Bezier Curve of degree (number_of_points - 1). This can be changed to a piecewise Bezier Curve of a specified degree after creation using the properties editor. Bezier Curves can be edited using Draft Edit .

M enu location Draft -> BezCurve Workbenches Draft, Arch Default shortcut B Z See also None

How to use 1. Press the

Draft BezCurve button, or press B then Z keys.

Options Press F or the

Finish button to finish the spline, leaving it open

Press C or the Close button or click on the first point to finish the spline, but making it closed by adding a last segment between the last point and the first one. Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press R or click the checkbox to check/uncheck the Relative button. If relative mode is on, the coordinates of the next point are relative to the last one. If not, they are absolute, taken from the (0,0,0) origin point. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the BezCurve tool will restart after you finish or close it, allowing you to draw another one without pressing the BezCurve button again. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last one. Press W or press the

Wipe button to remove the existing segments and start the spline from the last point.

Press CTRL + Z or press the

Undo button to undo the last point.

Press ESC or the Cancel button to abort the current BezCurve command.

Properties DATA

Closed: Specifies if the Bezier Curve is closed or not

DATA

Degree: Specifies the degree of the Bezier Curve (or segments)

Scripting The BezCurve tool can by used in macros and from the python console by using the following function: makeBezCurve(pointslist,[closed],[placement],[support],[degree])

Create a Bezier Curve object from the given list of vectors. Instead of a pointslist, you can also pass a Part Wire. Example: import FreeCAD,Draft myFeature = Draft.makeBezCurve(Draft.makeBezCurve(points,False)

Contraining Nodes The segment endpoints in a piecewise Bezier Curve can be constrained such that adjacent control points are tangent or symmetric to the segments at the endpoint. This is done after object creation using Draft Edit . Sharp - remove constraints Tangent - force adjacent control points to be tangent Symmetric - force adjacent control points to be tangent and equi-distant

Limitations This tool is not available before FreeCAD version 0.14 The Points Property does not yet appear in the properties list. OpenCascade does not support Bezier Curve with degree > 25. This should not be a problem in practice.

Draft Move Description The Move tool moves or copies the selected objects from one point to another on the current work plane. If no object is selected, you will be invited to select one.

Draft Move M enu location Draft -> Move Workbenches Draft, Arch Default shortcut M V See also None

How to use 1. Select objects you wish to move or copy 2. Press the

Draft M ove button, or press M then V keys

3. Click a first point on the 3D view, or type a coordinate 4. Click another point on the 3D view, or type a coordinate

Options Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press R or click the checkbox to check/uncheck the Relative button. If relative mode is on, the coordinates of the next point are relative to the last one. If not, they are absolute, taken from the (0,0,0) origin point. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Move tool will restart after you finish or close it, allowing you to move or copy the objects another time without pressing the Move button again. Pressing ALT or C or clicking the Copy button will make a copy of the objects, instead of moving them. If you keep ALT pressed after clicking the second point, you will be able to place more copies, until you release the ALT key. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last one. Press ESC or the Cancel button to abort the current command.

Scripting The Move tool can by used in macros and from the python console by using the following function: move (FreeCAD.Object or list, Vector, [copymode]) Moves the given object or the objects contained in the given list in the direction and distance indicated by the given vector. If copymode is True, the actual objects are not moved, but copies are created instead. Returns the object(s) (or their copies if copymode was True) A list of the moved object (or the copies) is returned Example: import FreeCAD,Draft Draft.move(FreeCAD.ActiveDocument.ActiveObject,FreeCAD.Vector(2,2,0))

Limitations

When moving (or changing Placement of) a document object (eg: Pad, Revolution, etc) which is based on a Sketch (from Sketcher/Part Design), you must move the original sketch. If you move the derived object, it will just go back to the position defined by the sketch.

Draft Rotate Description This tool rotates or copies the selected objects by a given angle around a point on the current work plane. If no object is selected, you will be invited to select one.

Draft Rotate M enu location Draft -> Rotate Workbenches Draft, Arch Default shortcut R O See also None

How to use 1. Select objects you wish to rotate or copy 2. Press the

Draft Rotate button, or press R then O keys

3. Click a center point on the 3D view, or type a coordinate 4. Click a second point on the 3D view, or give a reference angle 5. Click a third point on the 3D view, or give a rotation angle

Options Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Rotate tool will restart after you finish or close it, allowing you to rotate or copy the objects another time without pressing the Rotate button again. Pressing ALT or C or clicking the Copy button will make a copy of the objects, instead of rotating them. If you keep ALT pressed after clicking the third point, you will be able to place more copies, until you release the ALT key. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the rotation center. Press ESC or the Cancel button to abort the current command.

Scripting The Rotate tool can by used in macros and from the python console by using the following function: rotate (FreeCAD.Object or list, angle, [center], [axis] ,[copymode]) Rotates the given object or the objects contained in the given list with the given angle around the given center if provided, using axis as a rotation axis. If axis is omitted, the rotation will be around the vertical Z axis. If copymode is True, the actual objects are not moved, but copies are created instead. Returns the objects (or their copies is copymode was True). Example: import FreeCAD,Draft Draft.rotate(FreeCAD.ActiveDocument.ActiveObject,45)

Draft Offset Description The Offset tool offsets the selected object by a given distance on the current work plane. If no object is selected, you will be invited to select one.

Draft Offset M enu location Draft -> Offset Workbenches Draft, Arch Default shortcut O S See also None

How to use 1. Select objects you wish to offset 2. Press the

Draft Offset button, or press O then S keys

3. Click a point on the 3D view, or type a distance.

Options Press T or click the checkbox to check/uncheck the Continue button. If continue mode is on, the Offset tool will restart after you finish or close it, allowing you to offset or copy the objects another time without pressing the Offset button again. Pressing ALT or C or clicking the Copy button will make a copy of the objects, instead of moving them. If you keep ALT pressed after clicking the second point, you will be able to place more copies, until you release the ALT key. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Pressing SHIFT will constrain you to the current segment, instead of picking the closest one. Press ESC or the Cancel button to abort the current command.

Scripting The Offset tool can by used in macros and from the python console by using the following function: offset (object,Vector,[copymode],[bind],[sym]) Offsets the given wire by applying the given Vector to its first vertex. If copymode is True, another object is created, otherwise the same object gets offsetted. If bind is True, and provided the wire is open, the original and the offsetted wires will be bound by their endpoints, forming a face. If sym is True, the offset is made on both sides, the total width being the length of the given vector. Returns the offsetted object (or its copy if copymode as True). Example: import FreeCAD,Draft Draft.offset(FreeCAD.ActiveDocument.ActiveObject,FreeCAD.Vector(2,2,0))

Draft Trimex Description This tool trims/cuts and extends lines and polylines, and extrudes faces.

Draft Trimex M enu location Draft -> Trim/Extend Workbenches Draft, Arch Default shortcut T R See also Part Extrude

How to use 1. Select a wire you wish to trim or extend, or select a face you wish to extrude 2. Press the

Draft Trimex button, or press T then R keys

3. Click a point in the 3D view

Options trimming or extending is decided automatically from the position of your mouse if you move the mouse cursor over another object, the trim/extend operation will snap to that object or segment pressing SHIFT will constrain you to the segment currently being trimmed or extended pressing ALT will invert the direction of the trimming When the selected object is a face, or a face is selected from an existing object, the trimex tool switches to extrude mode. In extrude mode, pressing SHIFT frees the extrusion from the face normal and allows to snap elsewhere.

Scripting Not available. See the Part Extrude tool.

Draft Upgrade Description This tool upgrades selected objects in different ways. If no object is selected, you will be invited to select one.

Draft Upgrade M enu location Draft â&#x2020;&#x2019; Upgrade Workbenches Draft, Arch Default shortcut U P See also Draft Downgrade

How to use 1. Select one or more objects you wish to upgrade 2. Press the

Draft Upgrade button or press U then P keys

Options The selected objects are modified/upgraded according to the following conditions (in order): if there are more than one face in the selection, the faces are merged (union) if there is only one face in the selection, nothing is done if there is only one open wire in the selection, it gets closed if there are only edges in the selection, all edges are joined into a wire (closed if possible) if none of the above is possible, a compound object is created

Scripting The upgrade tool can be used from python scripts and macros like this: Draft.upgrade(objects, delete=False, force=None) Upgrades the given object(s) (can be an object or a list of objects). If delete is True, old objects are deleted. The force attribute can be used to force a certain way of upgrading. It can be: makeCompound, closeGroupWires, makeSolid, closeWire, turnToParts, makeFusion, makeShell, makeFaces, draftify, joinFaces, makeSketchFace, makeWires Returns a dictionnary containing two lists, a list of new objects and a list of objects to be deleted Some of the operations of the Upgrade tool can also be made with the Part Fuse or Draft Wire tools. Example: import Draft mycircle = Draft.makeCircle(2) face1 = Draft.upgrade([mycircle],True)

Draft Downgrade Description This tool downgrades selected objects in different ways. If no object is selected, you will be invited to select one.

Draft Downgrade M enu location Draft -> Downgrade Workbenches Draft, Arch Default shortcut D N See also Draft Upgrade

How to use 1. Select one or more objects you widh to downgrade 2. Press the

Draft Downgrade button or press D then N keys

Options The selected objects are modified/downgraded, according to the following conditions (in order): if only one object is selected and it contains more than one face, each face becomes a separate object if there are more than one face in the selection, the subsequent objects are subtracted from the first one if there is only one face in the selection, it gets converted into a wire otherwise all wires found in the selection are exploded into single edges

Example

Complete shape

Downgraded shape, with disconnected and split faces

Scripting The Downgrade tool can be used in python scripts and macros by using the following function:

downgrade (objects, [delete], [force]) Downgrades the given object(s) (can be an object or a list of objects). If delete is True, old objects are deleted. The force attribute can be used to force a certain way of downgrading. It can be: explode, shapify, subtr, splitFaces, cut2, getWire, splitWires. Returns a dictionary containing two lists, a list of new objects and a list of objects to be deleted Example: import FreeCADGui,Draft selection = FreeCADGui.Selection.getSelection() Draft.downgrade(selection)

Draft Scale Description This tool scales selected object(s) around a base point. If no object is selected, you will be invited to select one. It can also be used to mirror objects.

Draft Scale M enu location Draft â&#x2020;&#x2019; Scale Workbenches Draft, Arch Default shortcut S C See also Draft Clone

How to use 1. Select objects you wish to scale 2. Press the

Draft Scale button, or press S then C keys

3. Click a first point on the 3D view, or type a coordinate 4. Click another point on the 3D view, or type a coordinate

Options To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. The x, y and z components of the second point define the scale factor. For example, (1,1,1) would do nothing, (2,2,2) would scale 2x in all directions, (-1,1,1) would mirror in x direction. Pressing ALT or C or clicking the Copy button will make a copy of the objects, instead of scaling the original. If you keep ALT pressed after clicking the second point, you will be able to place more copies, until you release the ALT key. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Pressing SHIFT will lock x and y values together, so the shape is not deformed. Press ESC or the Cancel button to abort the current command. The resulting object is a Draft Clone, which allows you to change the scale values after it has been created. Mirroring objects works by inverting the sign of one of the directions. For example, (-1,1,1) mirrors horizontally (on the X axis), and (1,-1,1) vertically (on the Y axis).

Scripting The Scale tool can by used in macros and from the python console by using the following function: scale (objects,vector,[center,copy,legacy]) Scales the objects contained in objects (that can be a list of objects or an object) of the given scale factors defined by the given vector (in X, Y and Z directions) around the given center. If legacy is True, direct (old) mode is used, otherwise a parametric copy is made. If copy is True, the actual objects are not moved, but copies are created instead. The objects (or their copies) are returned. Example: import FreeCAD,Draft Draft.scale(FreeCAD.ActiveDocument.ActiveObject,FreeCAD.Vector(2,2,2))

Draft Edit Description

Draft Edit

This tool allows you to edit graphically certain properties of the selected object, such as the vertices of a Wire, or the length and width of a Rectangle, or the radius of a Circle. It does nothing more than enter the object's edit mode, so other ways to enter edit mode (such as double-clicking the object in the Tree view) give the same result.

M enu location Draft â&#x2020;&#x2019; Edit Workbenches Draft, Arch Default shortcut None See also None

How to use 1. Select a wire, line, rectangle, bspline or circle 2. Press the

Draft Edit button, or double-click the object in the Tree panel, or use the

Std Edit tool.

3. Click on a point you wish to move 4. Click another point on the 3D view, or type a coordinate 5. Press ESC or the Finish button

Options The Edit tool only works on one selected object at a time. The Edit tool only works on Draft Wires, Rectangles, Circles and Arcs. Other object types must first be converted to Draft objects. Click on an edit vertex to move it, click again to release it. Press X , Y or Z after a point to constrain the next point on the given axis. To enter coordinates manually, simply enter the numbers, then press ENTER between each X, Y and Z component. Press CTRL while drawing to force snapping your point to the nearest snap location, independently of the distance. Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last one. Press ESC or the Cancel button or the

Draft Edit button again to finish editing.

Pressing the

Add point button allows you to add points to Wires and BSplines by clicking on the segments

Pressing the remove

Del point button allows you to remove points from Wires and BSplines by clicking on the points to

Scripting Not available. Each of the above object can be modified by changing its properties directly.

Draft WireToBSpline Description This tool converts Wires to BSplines, and vice-versa.

Draft WireToBSpline M enu location Drafting â&#x2020;&#x2019; Wire to BSpline Workbenches Draft, Arch Default shortcut None See also None

How to use 1. Select a wire or a BSpline 2. Press the

Draft WireToBSpline button

Options The original object will not be deleted after the operation, you must delete it manually if you wish so.

Scripting Not available, but creating a new object with the points from another one is easy, for example: If the active object is a wire: import FreeCAD,Draft points = FreeCAD.ActiveDocument.ActiveObject.Points Draft.makeBSpline(points) if the active object is a bspline import FreeCAD,Draft points = FreeCAD.ActiveDocument.ActiveObject.Points Draft.makeWire(points)

Draft AddPoint Description

Draft AddPoint

This tools allows you to add additional points to Wires and BSplines.

M enu location Draft â&#x2020;&#x2019; Add Point

How to use

Workbenches Draft, Arch

1. Select a wire or a BSpline 2. Press the

Draft AddPoint button

3. Click a point on the 3D view, or type a coordinate

Options This functionality is also available inside the Draft Edit tool

Scripting Not available, but adding additional points to Wires and BSplines is easy, for example: import FreeCAD,Draft points = FreeCAD.ActiveDocument.ActiveObject.Points points.append(FreeCAD.Vector(2,2,0)) FreeCAD.ActiveDocument.ActiveObjects.Points = points

Default shortcut None See also None

Draft DelPoint Description

Draft DelPoint

This tools allows you to remove points from Wires and BSplines.

M enu location Draft â&#x2020;&#x2019; Remove Point

How to use

Workbenches Draft, Arch

1. Select a wire or a BSpline

Default shortcut

2. Press the

See also Arch Wall

The window tool also features several presets (available in version 014 ), that allow to create full doors or windows from a list of parameters, without the need to create the base 2D objects and components manually.

In the above image, a window is constructed on top of a Draft Rectangle, then inserted into a Wall. Adding a window to a wall automatically cuts a correct opening in the host wall.

The above image shows a more complex window being constructed on top of a sketch. When entering the window's edit mode, you can create different components, set their thickness, and select and assign wires from the sketch to them.

How to use Using a preset 1. Deselect everything. If a face is selected you will enter the "creating from scratch" mode automatically 2. Press the

Arch Window button, or press W then I keys

3. Select one of the presets in the list 4. Fill out the desired parameters

Creating from scratch 1. If you are going to draw your window directly on a wall, select one face of a wall 2. Press the

Arch Window button, or press W then I keys

3. A new sketch will be created (on the selected wall face if applicable). Draw one or more closed wires 4. Press the CLose button in the task panel to create the window 5. Enter Edit mode by double-clicking the window in the tree view, to adjust the window components

Presets The following presets are available (available in version 014 ):

HEIGHT

H1 H2

O2 H3

WIDTH

Glass door

HEIGHT

WIDTH

Simple door

HEIGHT

H1 H2

WIDTH

Double-opening window

HEIGHT

WIDTH

Fixed window

HEIGHT

H1 H2

WIDTH

Single-opening window

HEIGHT

H1 H2

Sash-opening window

WIDTH

Building components Windows can include 2 types of components: panels and frames. Panels are made from one closed wire, which gets extruded, while frames are made from 2 or more closed wire, where each one is extrudes, then the smaller ones are subtracted from the biggest one. You can access, create, modify and delete components of a window in edit mode (double-click the window in the Tree view). The components have the following properties: Name: A name for the component Type: The type of component. Can be "Frame", "Glass panel" or "Solid panel" Wires: A comma-separated list of wires the component is based on Thickness: The extrusion thickness of the component Offset: The distance between the component and its base 2D wire(s)

Options You can also create a closed 2D profile (for example with the Draft Workbench or Sketcher Workbench), then, with that 2D object selected, press the Arch Window button. Add a selected window to a wall by selecting both, then pressing the

Arch Add button.

Remove a selected window from a wall by selecting the window, then pressing the

Arch Remove button.

When using presets, it is often convenient to turn the "Near" Draft Snap on, so you can snap your window to an existing face.

Doors Doors can be made easily with the window tool, you only need to draw the base of the inner wire touching the exterior wire like in the image below.

Properties DATA

Window Parts: A list of strings (5 strings per component, setting the component options above)

Scripting The Window tool can by used in macros and from the python console by using the following function: makeWindow (obj,[name]) creates a window based on the given object Example: import Draft, Arch rect = Draft.makeRectangle(length=2,height=4) Arch.makeWindow(rect)

Arch SectionPlane Description This tool places in the current Document a section plane gizmo, which defines a section or view plane. The gizmo can be relocated and reoriented by moving and rotating it, until it describes the 2D view you want to obtain. The Section plane object will only consider objects that were selected when it got created. Objects can later be added or removed from a SectionPlane object with the Arch Add and Arch Remove tools. Upon creation, SectionPlane objects also insert a view of themselves into the active Drawing page, or create a new page if none exist. You can also add views of Section planes directly in the document, by using the Draft Shape2DView tool with a section plane selected.

Arch SectionPlane M enu location Arch -> Section Plane Workbenches Arch Default shortcut S P See also None

How to use 1. Select objects you want to be included in your section view 2. Press the

SectionPlane button or press S then P keys

3. M ove/rotate the Section Plane into correct position 4. Press the

Recompute button to update the view

Options With a section plane object selected, use the Draft Shape2DView tool to create a shape object representing the section view in the document

Create additional views of a section plane by selecting it, then using the Draft Drawing tool

Properties VIEW

Display Size: The size of the section plane gizmo in the 3D view

Scripting The Section Plane tool can by used in macros and from the python console by using the following function: makeSectionPlane ([objectslist]) Creates a Section plane objects including the given objects. Example: import FreeCAD, Draft, Arch trace = Draft.makeLine(FreeCAD.Vector (0, 0, 0),FreeCAD.Vector (2, 2, 0)) wall = Arch.makeWall(trace,width=0.1,height=1,align="Center") Arch.makeSectionPlane([wall])

Arch Axis Description The Axis tool allows you to places an axes system in the current document. The distance and the angle between axes is customizable, as well as the numbering style. The axes serve mainly as references to snap objects onto, but can also be used together with structures to create parametric arrays of beams or columns.

Arch Axis M enu location Arch -> Axis Workbenches Arch Default shortcut A X See also None

How to use 1. Press the

Arch Axis button, or press A then X keys

2. M ove/rotate the axes system to the desired position 3. Enter edit mode by double-clicking the axes system in the tree view to adjust its settings like number of axes, distances and angles between axes.

Options Each axis in an axes system has its own distance and angle in relation to the previous axis. This allows to do very complex systems such as non-orthogonal systems, polar systems or any kind of non-uniform system. Axes length, size of the bubbles and numbering styles are customizable directly via the axes system's properties

Structural systems The main use of axes systems is simply to give you reference lines to snap to, but they can also be used to automatically build structural arrays, such as columns grids and beam layouts:

To obtain that result, one or more axes systems must be added to a structural element, turning it into an array. If one axes system is added, the element is copied once on each line of the system, like the beams on the image above. If two systems are added, the element is copied once on each intersection of the two systems, like the columns on the image above. The same axes systems can of course be used in several structural objects. 1. Create an Arch Structure object 2. Create one or more axes systems 3. Select one or more axes systems, then the structure object 4. Press the

Arch Add button

5. By entering the edit mode of the structure object (double-clicking it in the tree view), you can add or remove axes systems from it.

Properties DATA

Length: The length of the axes

VIEW

Bubble Size: The size of the axis bubbles

VIEW

Numeration style: How the axes are numbered: 1,2,3, A,B,C, etc...

Scripting The Axis tool can by used in macros and from the python console by using the following function: makeAxis ([number],[interval]) makes an Axis System based on the given number of axes and interval distance Example: import Arch Arch.makeAxis(5,2)

Arch Roof Description The Roof tool allows you to create a sloped roof from a selected wire. The created roof object is parametric, keeping its relationship with the base object. Please note that this tool is still in development, and might fail with very complex shapes. The principle is that each edge is seen allotting a profile of roof (slope, width, overhang, thicknessâ&#x20AC;Ś).

Arch Roof M enu location Arch -> Roof Workbenches Arch Default shortcut R F See also None

How to use 1. Create a wire with following the conterclockwise direction and select it.

1. Press the

Arch Roof button, or press R then F keys

2. The default roof object could have a strange shape, it's because the tool have not all the needed informations. 3. After creating the default roof, double click on the object in the tree view to access and edit all the properties. Angle must be between 0 and 90.

4. 5. Each line correspond to a roof pane. So you can set properties you want for each roof pane. 6. To help you, you can set Angle or Run to 0 and defined a Relative Id, this make automatic calculs to find the data relative to the relative Id. 7. It work like this : 1. If Angle = 0 and Run = 0 then profile is identical to the relative profile. 2. If Angle = 0 then angle is calculated so that the height is the same one as the relative profile. 3. If Run = 0 then Run is calculated so that the height is the same one as the relative profile. 8. At the end, set an angle to 90째 to make a gable.

Properties DATA

Angles: List of the slope angle of the roof pane (an angle for each edge in the wire).

DATA

Runs: List of the width of the roof pane (a run for each edge in the wire).

DATA

IdRel: List of relation Id The slope angle of the roof

DATA

Thickness: List of thickness of the roof pane. (a thickness for each edge in the wire).

DATA

Overhang: List of the overhang of the roof pane (an overhang for each edge in the wire).

DATA

Face: The face index of the base object to be used #Not really used

Scripting The Roof tool can by used in macros and from the python console by using the following function:

makeRoof (baseobj,[facenr],[angles],[runs],[idrel],[thickness],[overhang],[name])

Makes a roof based on a closed wire. You can provide a list of angles, run, idrel, thickness, overhang for each edges in the wire to define the roof shape. The default for angle is 45 and the list is automatically complete to match with number of edges in the wire. Example:

import Arch, Draft rect = Draft.makeRectangle(30,40) Arch.makeRoof(rect,angles=[30.,])

Arch Space Description The Space tool allows you to define an empty volume, either by basing it on a solid shape, or by defining its boundaries, or a mix of both. If it is based solely on boundaries, the volume is calculated by starting from the bounding box of all the given boundaries, and subtracting the spaces behind each boundary. The space object always defines a solid volume. The floor area of a space object, calculated by intersecting a horizontal plane at the center of mass of the space volume, can also be displayed, by setting the display mode of the space object to "detailed".

Arch Space M enu location Arch â&#x2020;&#x2019; Space Workbenches Arch Default shortcut S P See also None

In the above image, a space object is created from an existing solid object, then two wall faces are added as boundaries, and the display mode is set to "detailed" to show the floor area.

How to use 1. Select an existing solid object, or faces on boundary objects 2. Press the

Arch Space button, or press S , P keys

Properties DATA

Base: The base object, if any (must be a solid)

DATA

Boundaries: A list of optional boundary elements

Scripting The space tool can be used in python scripts and macros by using the following function: makeSpace(objects) Creates a space object from the given objects. Objects can be one document object, in which case it becomes the base shape of the space object, or a list of selection objects as returned by FreeCADGui.Selection.getSelectionEx(), or a list of tuples (object, subobjectname). Returns the newly created space object. Example: import FreeCAD, Arch, Part b = Part.makeBox(2,2,2) FreeCAD.ActiveDocument.addObject("Part::Feature","Box").Shape=b

sp = makeSpace([FreeCAD.ActiveDocument.Box]) After a space object is created, selected faces can be added to it with the following function: import FreeCADGui Arch.addSpaceBoundaries(sp, FreeCADGui.Selection.getSelectionEx()) Boundaries can also be removed with: Arch.removeSpaceBoundaries(sp, FreeCADGui.Selection.getSelectionEx())

Limitations Not available below FreeCAD version 0.14 The boundaries properties is currently not editable via GUI See the forum announcement

Arch Stairs Description The stairs tool allows you to build automatically several types of stairs. At the moment, only straight stairs (with or without a central landing) are supported. Stairs can be built from scratch, or from a straight line, in which case the stairs follow the line. If the line is not horizontal but has a vertical inclination, the stairs will also follow its slope. See the Stairs entry in wikipedia for a definition of the different terms used to describe parts of stairs.

Arch Stairs M enu location Arch â&#x2020;&#x2019; Stairs Workbenches Arch Default shortcut S R See also None

On the above image, two stairs were created, one with a massive structure and a landing, and another one with a single stringer.

How to use 1. Press the

Arch Stairs button, or press S , R keys

2. Adjust the desired properties. Some parts of the stairs, such as the structure, might not appear immediately, if any of the properties makes it impossible, such as a structure thickness of 0.

Properties Base DATA

Align: The alignment of these stairs on their baseline, if applicable.

DATA

Base: The baseline of these stairs, if any.

DATA

Height: The total height of these stairs, if not based on a baseline, or the baseline is horizontal.

DATA

Length: The total length of these stairs if no baseline is defined.

DATA

Width: The width of these stairs.

DATA

Nosing: The size of the nosing.

DATA

Number of Steps: The numbers of steps (risers) in these stairs.

DATA

Riser Height: The height of the risers.

DATA

Tread Depth: The depth of the treads.

Steps

DATA

Tread Thickness: The thickness of the treads.

Structure DATA

Landings: The type of landings.

DATA

Stringer Offset: The offset between the border of the stairs and the structure.

DATA

Stringer Width: The width of the stringers.

DATA

Structure: The type of structure of these stairs.

DATA

Structure Thickness: The thickness of the structure.

DATA

Winders: The type of winders.

Scripting Stairs can be created from python scripts and macros by using the following function: makeStairs([base], [length], [width], [height], [steps]) Creates a stairs object with the given attributes. Returns the new stairs object. Example: import Arch makeStairs(length=5, width=1.2, height=3, steps=14)

Limitations Not available before FreeCAD version 0.14 Only straight stairs are available at the moment See the forum entry for circle stairs. See the forum announcement.

Arch Panel Description This tool allows you to build all kinds of panel-like elements, typically for panel constructions like the WikiHouse project, but also for all kinds of objects that are based on a flat profile.

Arch Panel M enu location Arch â&#x2020;&#x2019; Panel Workbenches Arch Default shortcut P,A See also Arch Structure

The above image shows a series of panel objects, simply made from imported 2D contours from a DXF file. They can then be rotated and assembled to create structures.

How to use 1. Select a 2D shape (draft object, face or sketch) 2. Press the

Arch Panel button, or press P then A keys

3. Adjust the desired properties

Options The thickness of a panel can be adjusted after creation Press ESC or the Cancel button to abort the current command. Double-clicking on the panel in the tree view after it is created allows you to enter edit mode and access and modify its additions and subtractions It is possible to automatically make panels composed of more than one sheet of a material, by raising its Sheets property.

Properties DATA

Thickness: The thickness of the panel

DATA

Sheets: The number of sheets of material the panel is made of

Scripting The Panel tool can by used in macros and from the python console by using the following function:

makePanel ([obj],[thickness],[name]) Example: import Arch,Draft base = Draft.makeRectangle(500,200) Arch.makePanel(base,36)

Limitations There is currently no automatic system to produce 2D cutting sheets from panel objects, but such feature is in the plans and will be added in the future. This tool is not available in FreeCAD versions prior to 0.15

Arch Frame Description The Frame tool is used to build all kinds of frame objects based on a profile and a layout. The profile is extruded along the edges of the layout, which can be any 2D object such as a sketch, or a draft object. It is especially useful to create railings, or frame walls. Frame objects can then easily be turned into wall or structure objects.

Arch Frame M enu location Arch -> Frame Workbenches Arch Default shortcut F R See also None

In the above image, a line has been turned into an array, and a frame object has been made using the array as layout, and a circle as profile.

How to use 1. Create a layout object and a profile object, for example with the Draft Workbench or the Sketcher Workbench 2. Select the layout object first, then, with CTRL pressed, select the profile object 3. Press the

Arch Frame button, or press F then R keys

Options The frame object can be placed at a certain distance from the layout object, by setting its Offset property The profile will be copied at the base of each edge of the layout object, then extruded along it. You can control how the profile is placed at the base of each edge with the Align and Rotation properties.

Properties DATA

Base: The layout this frame is based on.

DATA

Profile: The profile this frame is based on.

DATA

Align: Specifies if the profile must be rotated to have its normal axis aligned with each edge.

DATA

Offset: An optional distance between the layout object and the frame object.

DATA

Rotation: The rotation of the profile around its extrusion axis.

Scripting The Frame tool can by used in macros and from the python console by using the following function: makeFrame ( layout,profile )

Creates a frame object from a base sketch (or any other object containing wires) and a profile object (an extrudable 2D object containing faces or closed wires) Returns the new frame object, or None if the operation failed. Example: import Draft, Arch layout = Draft.makeLine(FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,0,0)) profile = Draft.makeCircle(.2) Arch.makeFrame(layout,profile)

Arch Equipment Description The Equipment tool offers you a simple and convenient way to insert non-structural, standalone elements such as pieces of furniture, hidro-sanitary equipments or electrical appliances to your projects. Equipments can be based on a shape or a mesh, allowing to use either precise solid models, or more easily available mesh models that you can find on the internet.

Arch Equipment M enu location Arch → Equipment Workbenches Arch Default shortcut E Q See also None

The above image shows examples of equipment objects made from shapes. As a result, projecting them in 2D gives perfect results. For mesh objects, which don't offer the same possibilities, a helper tool has been added to menu Arch → Utilities → 3 views from mesh allows to generate 3 flat, filled, orthogonal projections (top, front and side), which can then be used in 2D projections.

How to use

1. Select a Part shape or M esh object 2. Press the

Arch Equipment button, or press E then Q keys

Properties DATA

M odel: A description of the model of this equipment.

DATA

Url: An URL of the product page where more information about this equipment can be found.

Scripting The Equipment tool can by used in macros and from the python console by using the following function: makeEquipment ( baseObject ) Creates an equipment object from a base object (Mesh or Part) Returns the new equipment object, or None if the operation failed. Example: import Part, Arch box = Part.makeBox(2,2,2) base = FreeCAD.ActiveDocument.addObject("Part::Feature","Box") base.Shape = box Arch.makeEquipment(base)

Arch CutPlane Description The Cut Plane tool allows you to cut an Arch object according to a plan: You can cut an Arch object with the selected face, normal or opposite of the face plan. This add a substraction component CutVolume to the Arch object

Arch CutPlane M enu location Arch â&#x2020;&#x2019; Cut Plane Workbenches Arch Default shortcut None See also Arch Remove

In the above image, two Arch Structure are cut with respective plane.

How to use 1. Select the object to be cut, then the face (the face must be the last one you selected) 2. Press the

Cut Plane button

3. Choose if the object is cut behind the normale face or front of the normale face 4. Click the Ok button

Scripting The CutPlane tool can by used in macros and from the python console by using the following function: cutComponentwithPlane (archObject,face,faceSide) archObject is the object to cut face is the face of an object that come the plan from faceSide is the side of the face to cut. 0 = Behind, 1 = Front

Arch Add Description The Add tool allows you to do 4 kinds of operations: Add shape-based objects to an Arch component, such as a wall or structure. These objects make then part of the Arch component, and allow you to modify its shape but keeping its base properties such as width and height Add Arch components, such as a walls or structures, to a group-based arch object such as floors. Add axis systems to structural objects Add objects to section planes

Arch Add M enu location Arch -> Add Workbenches Arch Default shortcut None See also Arch Remove

In the above image, a box is being added to a wall.

How to use 1. Select the object(s) to be added, then the "host" object (the host object must be the last one you selected) 2. Press the

Add button

Scripting The Add tool can by used in macros and from the python console by using the following function: addComponents (objectsList,hostObject) Adds the given object or the objects from the given list as components to the given host Object. Use this for example to add windows to a wall, or to add walls to a floor. Returns nothing. Example: import FreeCAD, Arch, Draft, Part line = Draft.makeWire([FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,2,0)]) wall = Arch.makeWall(line) box = Part.makeBox(1,1,1) Arch.addComponents(box,wall)

Arch Remove Description The Remove tools allows you to do 2 kinds of operations: Remove a subcomponent from an Arch object, for example remove a box that has been added to a wall, like in the Arch Add example Subtract a shape-based object from an Arch component such as a wall or structure

Arch Remove M enu location Arch -> Remove Workbenches Arch Default shortcut None See also Arch Add

In the above image, a box is being subtracted from a wall

How to use 1. Select a subcomponent inside an Arch object, or: 2. Select object(s) to be subtracted, then the Arch component from which they must be subtracted (the arch component must be the last thing you selected) 3. Press the

Remove button

Scripting The Remove tool can by used in macros and from the python console by using the following function: removeComponents (objectsList,[hostObject]) removes the given component or the components from the given list from their parents. If a host object is specified, this function will try adding the components as holes to the host object instead. Example: import FreeCAD, Arch, Draft, Part line = Draft.makeWire([FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,2,0)]) wall = Arch.makeWall(line) box = Part.makeBox(1,1,1) Arch.addComponents(box,wall) Arch.removeComponents(box)

Arch Survey Description The survey tool enters a special surveying mode, which allows you to quickly grab measures and information from a model, and transfer that information to other applications. Once you are in Survey mode, clicking on different subelements of 3D objects gathers the following information, depending on what you click: If you click on an edge, you get its length If you click on a vertex, you get its height (coordinate on the Z axis) If you click on a face, you get its area If you double-click anything, therefore select the whole object, you get its volume

Arch Survey M enu location Arch â&#x2020;&#x2019; Survey Workbenches Arch Default shortcut None See also FCInfo (macro)

When such a piece of information is gathered, three things happen: A label is placed on top of the element you clicked, that displays the value (with "a" for area, "l" for length, "z" for height, or "v" for volume) The numeric value is copied to the clipboard, so you can paste it in another application A line is printed on the FreeCAD output window. After you exit the survey mode, those lines can be copied and pasted in another application (the values are comma-separated, making it easy to convert to spreadsheet data)

The above image shows what happens when running the survey mode.

How to use 1. Press the

Arch Survey button

2. Click on vertices, edges, faces or double-click to select whole objects 3. Press ESC or the Cancel button to exit survey mode and remove all the labels.

Scripting The Survey mode cannot be used directly from python scripts, but gathering the same information from any selected Partbased object is easy reproduced with the following script: import FreeCADGui selection = FreeCADGui.Selection.getSelectionEx() for obj in selection: for element in obj.SubObjects: print "Area: ", element.Area print "Length: ", element.Length print "Volume: ", element.Volume print "Center of Mass: ", element.CenterOfMass

Arch tutorial

Introduction This tutorial aims at giving you the basics to work with the Arch Workbench. I will try to make it simple enough so you don't need any previous experience with FreeCAD, but having some experience with 3D or BIM applications will be useful. In any case, you should be prepared to look for yourself for further information about how FreeCAD works on the FreeCAD documentation wiki. The Getting started page is a must read, if you have no previous experience with FreeCAD. Also check our tutorials section, and on youtube you will also find a lot more of FreeCAD tutorials. The purpose of the Arch Workbench is to offer a complete BIM workflow inside FreeCAD. As it is still under development, don't expect to find here the same tools and level of completion as grown-up commercial alternatives such as Revit or ArchiCAD, but on the other hand, FreeCAD being used in a much bigger scope than these applications, the Arch Workbench greatly benefits from the other disciplines FreeCAD caters to, and offers some features rarely seen in traditional BIM applications. Here are, for example, a couple of interesting features of FreeCAD's Arch Workbench that you'll hardly find in other BIM apps: Architectural objects are always solids. From FreeCAD's strong mechanical background, we learned the importance of always working with solid objects. This ensures a much more error-free workflow, and very reliable boolean operations. Since cutting through 3D objects with a 2D plane, in order to extract sections, is also a boolean operation, you can immediately see the importance of this point. Architectural objects can always have any shape. No restrictions. Walls don't need to be vertical, slabs don't need to look like slab. Any solid object can always become any architectural object. Very complex things, usually hard to define in other BIM applications, like a floor slab curving up and becoming a wall (yes Zaha Hadid, it's you we're talking about), present no particular problem at all in FreeCAD. The whole power of FreeCAD is at your fingertips. You can design architectural objects with any other tool of FreeCAD, such as the PartDesign Workbench, and when they are ready, convert them to architectural objects. They will still retain their full modeling history, and continue totally editable. The Arch Workbench also inherits much of the Draft Workbench functionality, such as snapping and working planes. The Arch Workbench is very mesh-friendly. You can easily design an architectural model in a mesh-based application such as Blender or SketchUp and import it in FreeCAD. If you took care of the quality of your model and its objects are non-manifold solid shapes, turning them into architectural objects only requires the press of a button. At the time I'm writing this, though, the Arch Workbench, as the rest of FreeCAD, suffers some limitations. Most are being worked on, though, and will disappear in the future. FreeCAD is no 2D application. It is made for 3D. There is a reasonable set of tools for drawing and editing 2D objects with the Draft Workbench and Sketcher Workbench, but it is not made for handling very large (and sometimes badly drawn) 2D CAD files. You can usually successfully import 2D files, but don't expect very high performance if you want to keep working on them in 2D. You have been warned. No materials support. FreeCAD will have a complete M aterial system, able to define very complex materials, with all the

goodies you can expect (custom properties, material families, rendering and visual aspect properties, etc), and the Arch Workbench will of course use it when it is ready. Very preliminary IFC support. You can already import IFC files, quite reliably, provided IfcOpenShell is installed on your system, but exporting is still not officially supported. This is worked on both by the FreeCAD and IfcOpenShell developers, and in the future we can expect full-powered IFC support. Most Arch tools are still in development. That means that automatic "wizard" tools that create complex geometry automatically, such as Arch Roof or Arch Stairs can only produce certain types of objects, and other tools that have presets, such as Arch Structure or Arch Window only have a couple of basic presets. This will of course grow over time. Relations between objects in FreeCAD are still not officially available. These, for example the relation between a window and its host wall, are currently implemented in the Arch Workbench with temporary (and therefore somewhat limited) methods. Many new possibilities will arise when this feature will be fully available. Units are being implemented in FreeCAD, which will allow you to work with any unit you wish (even imperial units, you guys from the USA can be eternally grateful for this to J端rgen, FreeCAD's godfather and dictator). But at the moment the implementation is not complete, and the Arch workbench still doesn't support them. You must consider it "unit-less".

FreeCAD version 0.14 required This tutorial was written using FreeCAD version 0.14. You will need at least this version number in order to follow it. Earlier versions might not contain all the needed tools,or they could lack options presented here.

Typical workflows The Arch Workbench is mainly made for two kinds of workflows: Build your model with a faster, mesh-based application such as Blender or SketchUp, and import them in FreeCAD in order to extract plans and section views. FreeCAD being made for precision modeling, at a much higher level than what we usually need in architectural modeling, building your models directly in FreeCAD can be heavy and slow. For this reason, such a workflow has big advantages. I described it in this article on my blog. If you care to model correctly and precisely (clean, solid, non-manifold meshes), this workflow gives you the same performance and precision level as the other. Build your model directly in FreeCAD. That is what I will showcase in this tutorial. We will use mostly three workbenches: Arch, of course, but also Draft, whose tools are all included in Arch, so there is no need to switch workbenches, and Sketcher. Conveniently, you can do as I usually so, which is to create a custom toolbar in your Arch workbench, with Tools -> Customize, and add the tools from the sketcher that you use often. This is my "customized" Arch workbench:

In this tutorial, we will model the house in 3D, based on the 2D drawings we'll download from the net, and extract from it 2D documents, such as plans, elevations and sections.

Preparation Instead of creating a project from scratch, Let's take an example project to model, it will save us time. I chose this wonderful house by the famous architect Vilanova Artigas (see a series of pictures by Pedro Kok), because it is close to where I live, it is simple, it's a wonderful example of the amazing modernist architecture of S達o Paulo (it is even for sale if you have "a few" Reals to spend), and dwg drawings are easily available. We will use the 2D DWG drawings obtained from the link above (you need to register to download, but it's free) as a base to build our model. So the first thing you'll want to do is to download the file, unzip it, and open the DWG file inside with a dwg application such as DraftSight. Alternatively, you can convert it to DXF with a free autility such as the Teigha File Converter. If you have the Teigha converter installed (and its path set in the Arch preferences settings), FreeCAD is also able to import DWG files directly. But since these files can sometimes being of bad quality and very heavy, it's usually better open it first with a 2D CAD application and do some cleaning. Here, I removed all the detail drawings, all the titleblocks and page layouts, did a "clean" ("purge" in AutoCAD slang) to remove all unused entities, reorganized the sections at a logical location in relation to the plan view, and moved everything to the (0,0) point. After that, our file can be opened quite efficiently in FreeCAD. Check the different options available in Edit -> Preferences -> Draft -> Import/Export, they can affect how (and how quickly) DXF/DWG files are imported. This is how the file looks after being opened in FreeCAD. I also changed the thickness of the walls (the contents of the "muros" group), and flipped a couple of doors that were imported with wrong X scale, with the Draft Scale tool:

The DXF importer (which also takes care of DWG files, since when importing DWG files, they are simpl converted to DXF first), groups the imported objects by layer. There is no layer in FreeCAD, but there are groups. Groups offer a similar way to organize the objects of your files, but don't have specific properties, like AutoCAD layers, that apply to their contents. But they can be placed inside other groups, which is very handy. The first thing we might want to do here, is to create a new group in the tree view, right-click on the document icon, add a group, right click on it to rename it as "base 2D plans", and drag and drop all the other objects into it.

Building the walls Like most Arch objects, walls can be built upon a big variety of other objects: lines, wires (polylines), sketches, faces or solid (or even on nothing at all, in which case they are defined by height, width and length). The resulting geometry of the wall depends on that base geometry, and the properties you fill in, such as width and height. As you might guess, a wall based on a line will use that line as its alignment line, while a wall based on a face will use that face as its base footprint, and a wall based on a solid will simply adopt the shape of that solid. This allows about any shape imaginable to become a wall. There are different possible strategies to build walls in FreeCAD. One might want to build a complete "floor plan" with the sketcher, and build one, big, wall object from it. This technique works, but you can only give one thickness for all the walls of the project. Or, you can build each piece of wall from separate line segments. Or, this is what we will do here, a mix of both: We will build a couple of wires on top of the imported plan, one for each type of wall:

As you see, I've drawn in red the lines that will become concrete walls (a pictures search of the house can help you to see the different wall types), the green ones are the exterior brick walls, and the blue ones will become the inner walls. I passed the lines through the doors, because doors will be inserted in the walls later, and will create their openings automatically. Walls can also be aligned left, right or centrally on their baseline, so it doesn't matter which side you draw the baseline. I also took care on avoiding intersections as much as I could, because our model will be cleaner that way. But we'll take care of intersections later. When this is done, place all those lines in a new group if you want, select each line one by one, and press the Arch Wall tool to

build a wall from each of them. You can also select several lines at once. After doing that, and correcting widths (exterior walls are 25cm wide, inner walls are 15cm wide) and some alignments, we have our walls ready:

We could also have built our walls from scratch. If you press the Arch Wall button with no object selected, you will be able to click two points on the screen to draw a wall. But under the hood, the wall tool will actually draw a line and build a wall on it. In this case, I found it more didactic to show you how things work. Did you notice that I took great care not to cross the walls? this will save us some headache later, for example if we export our work to other applications, that might not like it. I have only one intersection, where I was too lazy to draw two small line segments, and drew one big wire crossing another. This must be fixed. Fortunately, all Arch objects have a great feature: you can add one to another. Doing that will unite their geometries, but they are still editable independently after. To add one of our crossing walls to the other, just select one, CTRL + select the other, and press the Arch Add tool:

On the left is are the two intersecting walls, on the right the result after adding one to the other. An important note about parametric objects Something is important to consider already. As you can see, in FreeCAD, everything is parametric: Our new "united" wall is made from two walls, each based on a baseline. When you expand them in the tree view, you can see all that chain of dependencies. As you can imagine, this little game can quickly become very complex. Furthermore, if you already know how to work with the sketcher, you might have wanted to draw the baselines with constrained sketches. This whole complexity has a cost: it raises exponentially the number of calculations that FreeCAD has to perform to keep your model geometry up to date. So, think about it, don't add unnecessary complexity when you don't need it. Keep a good balance between simple and complex objects, and keep these for the cases where you really need them. For example, I could have drawn all my baselines above without caring about what crosses what, and fix things with the Arch Add tool later. But I would have raised much the complexity of my model, for no gain at all. Better make them correct right from the start, and keeping them as very simple pieces of geometry. Now that our walls are okay, we need to raise their height, until they intersect the roof. Then, since the wall object still cannot be cut automatically by roofs (this will happen some day, though), we will build a "dummy" object, that follows the shape of the roof, to be subtracted from our walls.

First, by looking at our 2D drawings, we can see that the highest point of the roof is 5.6m above the ground. So let's give all our walls a height of 6m, so we make sure they will be cut by our dummy roof volume. Why 6m and not 5.6m? You may ask. Well, if you already worked with boolean operations (additions, subtractions, intersections), you must already know that these operations usually don't like much "face-on-face" situations. They prefer clearly, frankly intersecting objects. So by doing this, we keep on the safe side. To raise the height of our walls, simply select all of them (don't forget the one we added to the other) in the tree view, and change the value of their "height" property. Before making our roof and cutting the walls, let's make the remaining objects that will need to be cut: The walls of the above studio, and the columns. The walls of the studio are made the same way as we did, on the superior floor plan, but they will be raised up to level 2.6m. So we will give them the needed height so their top is at 6m too, that is, 3.4m. Once this is done, let's move our walls up by 2.6m: Select them both, put yourself in frontal view (View -> Standard Views -> Front), press the Draft M ove button, select a first point, then enter 0, 2.6, 0 as coordinates, and press enter. Your objects now have jumped 2.6m high:

About coordinates The Draft objects, and most Arch objects too, obey to a Draft system called working planes. This system defines a 2D plane where next operations will take place. If you don't specify any, that working plane adapts itself to the current view. This is why we switched to frontal view, and you see that we indicated a movement in X of 0 and in Y of 2.6. We could also have forced the working plane to stay on the ground, by using the Draft SelectPlane tool. Then, we would have entered a movement of X of 0, Y of 0 and Z of 2.6. Now let's move our walls horizontally, to their correct location. Since we have points to snap to, this is easier: Select both walls, press the Draft M ove tool, and move them from one point to the other:

Finally, I changed the color of some walls to a brick-like color (so it's easier to differentiate), and made a small correction: Some walls don't go up to the roof, but stop at a height of 2.60m. I corrected the height of those walls.

Raising the structure Now, since we'll have to cut our walls with a subtraction volume, we might as well see if there aren't other objects that will need to be cut that way. There are, some of the columns. This is a good opportunity to introduce a second arch object: the Arch Structure. Structure objects behave more or less like walls, but they aren't made to follow a baseline. Rather, their prefer to work from a profile, that gets extruded (along a profile line or not). Any flat object can be a profile for a structure, with only one requirement: they must form a closed shape. For our columns, we will use another strategy than with the walls. Instead of "drawing" on top of the 2D plans, we will directly use objects from it: the circles that represent the columns in the plan view. In theory, we could just select one of them, and press the Arch Structure button. However, if we do that, we produce an "empty" structural object. This is because you can never be too sure at how well objects were drawn in the DWG file, and often they are not closed shapes. So, before turning them into actual columns, let's turn them into faces, by using the Draft Upgrade tool twice on them. The first time to convert them into closed wires (polylines), the second time to convert those wires into faces. That second step is not mandatory, but, if you have a face, you are 100% sure that it is closed (otherwise a face cannot be made). After we have converted all our columns to faces, we can use the Arch Structure tool on them, and adjust the height (some have 6m, other only 2.25m height):

On the image above, you can see two columns that are still as they were in the DWG file, two that were upgraded to faces, and two that were turned into structural objects, and their height set to 6m and 2.25m. Note that those different Arch objects (walls, structures, and all the others we'll discover) all share a lot of things between them (for example all can be added one to another, like we already saw with walls, and any of them can be converted to another). So it's more a matter of taste, we could have made our columns with the wall tool too, and converted them if needed. In fact, some of our walls are concrete walls, we might want to convert them to structures later.

Subtractions Now it is time to build our subtraction volume. The easiest way will be to draw its profile on top of the section view. Then, we will rotate it and place it at its correct position. See why I placed the sections and elevations like that before beginning? It will be very handy for drawing stuff there, then moving it to its correct position on the model. Let's draw a volume, bigger than the roof, that will be subtracted from our walls. To do that, I drew two lines on top of the base of the roof, then extended them a bit further with the Draft Trimex tool. Then, I drew a wire, snapping on these lines, and going well above our 6 meters. I also drew a blue line on the ground level (0.00), that will be or rotation axis.

Now is the tricky part: We will use the Draft Rotate tool to rotate our profile 90 degrees up, in the right position to be extruded. To do that, we must first change the working plane to the YZ plane. Once this is done, the rotation will happen in that plane. But if we do like we did a bit earlier, and set our view to side view, it will be hard to see and select our profile, and to know where is the basepoint around which it must rotate, right? Then we must set the working plane manually: Press the Draft SelectPlane button (it is in the "tasks" tab of the tree view), and set it to YZ (which is the "side" plane). Once you set the working plane manually, like that, it won't change depending on your view. You can now rotate your view until you have a good view of all the things you must select. To switch the working plane back to "automatic" mode later, press the Draft SelectPlane button again and set it to "None". Now the rotation will be easy to do: Select the profile, press the Draft Rotate button, click on a point of the blue line, enter 0 as start angle, and 90 as rotation:

Now all we need to do it to move the profile a bit closer to the model (set the working plane to XY if needed), and extrude it. This can be done either with the Part Extrude tool, or Draft Trimex, which also has the special hidden power to extrude faces. Make sure your extrusion is larger than all the walls it will be subtracted from, to avoid face-on-face situations:

Now, here comes into action the contrary of the Arch Add tool: Arch Remove. As you might have guessed, it also makes an object a child of another, but its shape is subtracted from the host object, instead of being united. So now things are simple: Select the volume to subtract (I renamed it as "Roof volume to subtract" in the tree view so it is easy to spot), CTRL + select a wall, and press the Arch Remove button. You'll see that, after the subtraction happened, the volume to subtract disappeared from both the 3D view and the tree view. That is because it has been marked as child of the wall, and "swallowed" by that wall. Select the wall, expand it in the tree view, there is our volume. Now, select the volume in the tree vieew, CTRL + select the next wall, press Arch Remove. Repeat for the next walls until you have everything properly cut:

Remember that for both Arch Add and Arch Remove, the order you select the objects is important. The host is always the last one, like in "Remove X from Y" or "Add X to Y" A note about additions and subtractions Arch objects that support such additions and subtractions (all of them except the "visual" helper objects such as the axes) keep track of such objects by having two properties, respectively "Additions" and "Subtractions", that contains a list of links to other objects to be subtracted or added. A same object can be in thr lists of several other objects, as it is the case of our subtraction volume here. Each of the fathers will want to swallow it in the tree view, though, so it will usually "live" in the last one. But you can always edit those lists for any object, by double-clicking it in the tree view, which in FreeCAD enters edit mode. Pressing the escape key exits edit mode.

Making the roofs Now, all we have to do to complete the structure, is to make the roof and the smaller inner slabs. Again, the easiest way is to draw their profiles on top of the section, with the Draft Wire tool. Here I drew 3 profiles on top of each other (I moved them apart in the image below so you see better). The green one will be used for the lateral borders of the roof slab, then the blue one for the side parts, and the red ones for the central part, that sits above the bathroom block:

Then, we must repeat the rotation operation above, to rotate the objects in a vertical position, then move them at their correct places, and copy some of them that will need to be extruded twice, with the Draft M ove tool, with the ALT key pressed, which creates copies instead of moving the actual object. I also added two more profiles for the side walls of the bathroom opening.

When everything is in place, it's just a matter of using the Draft Trimex tool to extrude, then convert them to Arch Structure objects.

After that, we can see some problems arising: two of the columns on the right are too short (they should go up to the roof), and there is a gap between the slab and the walls of the studio on the far right (the 2.60 level symbol on the section view was obviously wrong). Thanks to the parametric objects, all this is very easy to solve: For the columns, just change their height to 6m, fish your roof subtraction volume from the tree view, and subtract it to the columns. For the walls, it's even easier: move them a bit down. Since the subtraction volume continues at the same place, the wall geometry will adapt automatically. Now one last thing must be fixed, there is a small slab in the bathroom, that intersects some walls. Let's fix that by creating a new subtraction volume, and subtract it from those walls. Another feature of the Draft Trimex tool, that we use to extrude stuff, is that it can also extrude one single face of an existing object. This creates a new, separate object, so there is no risk to "harm" the other object. So we can select the base face of the small slab (look at it from beneath the model, you'll see it), then press the Draft Trimex button, and extrude it up to well above the roofs. Then, subtract it from the two inner bathroom walls with the Arch Remove tool:

Floors, stairs and chimney Now, our structure is complete, we just have a couple of smaller objects to do.

The chimney Let's start with the chimney. Now you already know how it works, right? Draw a couple of closed wires, move them up at their correct height with the Draft M ove tool, extrude them with the Draft Trimex tool, turn the bigger one into a structure, and subtract the smaller ones. Notice how the chimney tube wasn't drawn on the plan view, but I found its position by dragging blue lines from the section views.

The floors The floors are not well represented in the base drawings. When looking at the sections, you cannot know where and how thick the floor slabs are. So I will suppose that the walls are sitting on top of foundation blocks, at level 0.00, and that there are floor slabs, also sitting on those blocks, 15cm thick. So the floor slabs don't run under the walls, but around them. We could do that by creating a big rectangular slab then subtracting the walls, but remember, subtraction operations cost us. Better do it in smaller pieces, it will be "cheaper" in terms of calculation, and also if we do it intelligently, room by room, these will also be useful to calculate floor areas later:

Once the wires are drawn, just turn them into structures, and give them a height of 0.15:

The stairs Now the stairs. Met the next of the Arch tools, the Arch Stairs. This tool is still in a very early stage of development, at the time I'm writing, so don't expect too much of it. But it is already pretty useful to make simple, straight stairs. One concept is important to know, the stairs tool is thought to build stairs from a flat floor up to a wall. In other words, when viewed from the top, the stairs object occupies exactly the space that it occupies on the plan view, so the last riser is not drawn (but it is of course taken into account when calculating heights). In this case, I preferred to build the stairs on the section view, because we'll need many measurements that are easier to get from that view. Here, I drew a couple of red guidelines, then two blue lines that will be the base of our two pieces of stairs, and two green closed wires, that will form the missing parts. Now select the first blue line, press the Arch Stairs tool, set the number of steps to 5, the height to 0.875,the width to 1.30, the structure type to "massive" and the structure thickness to 0.12. Repeat for the other piece. Then, extrude both green wires by 1.30, and rotate and move them to the right position:

On the elevation view, draw (then rotate) the border:

Then move everything into place:

Don't forget also to cut the column that crosses the stairs, because in BIM it's always bad to have intersecting objects. We are building like in the real world, remember, where solid objects cannot intersect. Here, I didn't want to subtract the column directly from the stairs (otherwise the column object would be swallowed by the stairs object in the tree view, and I didn't like that), so I took the face on which the column was built, and extruded it again. This new extrusion was then subtracted from the stairs. Right! All the hard work is now done, let's go on with the very hard work!

Doors and windows Arch Windows are pretty complex objects. They are used to make all kinds of "inserted" objects, such as windows or doors. Yes, in FreeCAD, doors are just a special kind of window. In real life too, if you think of it, no? The Arch Window tool can still be a bit hard to use today, but consider this as a tradeoff, as it was built for maximum power. Almost any kind of window your imagination can produce can be done with it. But as the tool will gain more presets, this situation will certainly become better in the future. The Arch Window object works like this: It is based on a 2D layout, any 2D object, but preferably a sketch, that contains closed wires (polylines). These wires define the different parts of the window: outer frames, inner frames, glass panels, solid panels, etc. The window objects then has a property that stores what to do with each of these wires: extrude it, place it at a certain offset, etc. Finally, a window can be inserted into a host object such as a wall or structure, and it will automatically create a hole in it. That hole will be calculated by extruding the biggest wire found in the 2D layout. There are two ways to create such objects in FreeCAD: By using a preset, or drawing the window layout from scratch. We'll look at both methods here. But remember that the preset method does nothing else than creating the layout object and defining the necessary extrusions for you.

Using presets When pressing the Arch Window tool with no object selected, you are invited either to pick a 2D layout, or to use one of the presets. Let's use the "Simple Door" preset to place the main entrance door of our model. Give it a width of 1m, a height of 2.45m, a W1 size of 0.15m, and leave the other parameters to 0.05m. Then click the lower left corner of the wall, and your new door is created:

You will notice that your new door won't appear in the tree view. That is because, by snapping to a wall, we indicated that wall as its host object. Consequently, it has been "swallowed" by the wall. But a right click on it -> Go to selection will find it in the tree. In this case, as our window is not inserted in any wall (the opening was there already), we might as well detach our window from its host wall. This is done by double-clicking the host wall in the tree view to enter its edit mode. There, you will see the window in its "Subtractions" group. Simply select the window there, press the "remove element" button, then "OK". Our window has now been removed from its host wall, and lies at the bottom of the tree view. We have a second door, exactly the same as this one, a bit on the left. Instead of creating a new door from scratch, we have two ways to make a copy of the previous one: By using the Draft M ove tool, with the ALT key pressed, which, as you already know, copies an object instead of moving it. Or, even better, we can use the Draft Clone tool. The clone tool produces a "clone" of a selected object, that you can move around, but that retains the shape of the original object. If the original object changes, the clone changes too. So all we need to do now is select the door, press the Draft Clone tool, then move the clone to its correct position with the Draft M ove tool.

Organizing your model

Now would be a good time to do a bit of housecleaning. Since we already have two windows, it is a good moment to do some cleaning in the tree view: Create a new group, rename it to "windows", and drop the 2 windows in it. I also recommend you to separate other elements that way, such as the walls and structures. Since you can also create groups inside groups, you can organize further, for example by placing all elements that form the roof into a separate group, so it is easy to turn on and off (turning a group visible or invisible does the same with all objects inside). The Arch Workbench has some additional tools to organize your model: the Arch Site, Arch Building and Arch Floor. Those 3 objects are based on the standard FreeCAD group, so they behave exactly like groups, but they have a couple of additional properties. For example, floors have the ability to set and manage the height of the contained walls and structure, and when they are moved, all their contents are moved too.

But here, since we have only one building with only one (and a half) floor, there is no real need to use such objects, so let's stick with simple groups. Now, let's get back to work. Turn off the roof group, so we can see better inside, and switch the Display Mode of the floor objects to Wireframe (or use the Draft ToggleDisplayM ode tool) so we can still snap to them, but we can see the plan view underneath. But you can also turn off the floors completely, then place your doors at level 0, then raise them of 15cm with the Draft M ove tool. Let's place the interior doors. Use the "Simple Door" preset again, make doors of 1.00m and 0.70m wide x 2.10m high, with W1 size of 0.1m. Make sure you snap to the correct wall when you place them, so they automatically create a hole in that wall. If it is hard to place them correctly, you can place them at an easier location, at the corner of the wall, for example, then move them. The "hole" will move together. If by mistake you hosted a window in the wrong wall, it is easy to fix: Remove the window from the "Subtraction" group of the host wall in edit mode, as we saw above, then add it to the "Subtraction" group of the correct wall, by the same method, or, simply, using the Arch Remove tool. A little work later, all our doors are there:

After a closer look at the elevation view, I now detected another error: The top of the brick walls is not as 2.60m, but 17.5cm lower, that is, 2.425m. Fortunately, windows based on presets have a facility: You can alter their general dimensions (width and height) from their properties. So let's change their height to 2.425 - 0.15, that is, 2.275. The second window, as it is a clone of the first one, will adapt too. This is basically where the true magic of parametric design appears. Now we can look at the really interesting stuff: How to design your own custom windows.

Creating custom windows As I explained above, Arch Window objects are created from 2D layouts, made of closed elements (wires (polylines), circles, rectangles, anything). Since Draft objects cannot hold more than one of these elements, the preferred tool to draw window layouts is the Sketcher. Unfortunately, with the sketcher, it is not possible to snap to external objects like with the Draft workbench, which would be useful here, since our elevations are drawn already. Fortunately, a tool exists to convert Draft objects to a sketch: The Draft To Sketch tool. So, let's start by building our first window layout. I drew it on the elevation, using several rectangles: One for the outer line, and 4 for the inner lines. I stopped before the door, because, remember, our door already has a frame there:

Then, select all the rectangles, and press the Draft To Sketch button (and delete the rectangles, because this tool doesn't delete the original objects, in case something goes wrong). Then, with the new sketch selected, press the Arch Window tool:

The tool will detect that the layout has one outer wire and several inner wires, and automatically proposes you a default configuration: One frame, made by subtracting the inner wires from the outer one, extruded by 1m. Let's change that, by entering the window's edit mode, by double-clicking on it in the tree view: You will see a "Default" component, that has been created automatically by the Window tool, that uses the 5 wires (always subtracting the other ones from the biggest one), and has an extrusion value of 1. Let's change its extrusion value to 0.1, to match what we used in the doors. Then, let's add 4 new glass panels, each using a single wire, and give them an extrusion of 0.01, and an offset of 0.05, so they are placed at the middle of the frame. This will be how your window looks like when you are finished:

I suppose now you must have understood the power of this system: Any combination of frames and panels of any shape is possible. If you can draw it in 2D, it can exist as a full valid 3D object. Now, let's draw the other pieces, then we'll move everything into place together. But first. we'll need to do some corrections to the base 2D drawing, because some lines are clearly missing, where the windows meet the stairs. We can fix that by offsetting the stairs line by 2.5cm with the Draft Offset tool (with ALT pressed of course, to copy our lines instead of moving them). Now we can draw our layout, with wires, then convert them to a sketch, then making a window of it. After doing that a couple of times (I made it in 4 separate pieces, but it's up to you to decide), we have our facade complete:

Now, as before, it's just a matter of rotating the pieces, and moving them to their correct position:

Last missing piece, there is a segment of wall that didn't appear on the plan view, that we need to add. We have several options for that, I chose to draw a line on the ground plane, then move it up to the correct height, then create a wall from it. Then, we also need to fish up our roof subtraction volume (it must have stayed in the last column), then subtract it. Now this side of the building is ready:

Ready? Not quite. Look at the image above, we did our doors with a 5cm frame, remember (it was the default from the preset). But the other windows have 2.5cm frames. This needs to be fixed.

Editing windows We already saw how to build and update window components, via the window's edit mode, but we can also edit the underlying sketch. Preset windows are not different than custom windows, the Arch Window tool only created the underlying sketch fo you. Select our door object (the original, not the copy, remember, we made a clone), and expand it in the tree view. There is our sketch. Double-click it to enter edit mode. the Sketcher Workbench is an extremely powerful tool. It doesn't have some of the Draft conveniences, such as snapping or working planes, but it has many other advantages. In FreeCAD you will frequently use one or another depending on the need. The most important feature of the sketcher is constraints. Constraints allow you to automatically fix the position of some elements relative to others. For example, you can force a segment to always be vertical, or to always be at a certain distance to another. When we edit our door sketch, we can see that it is made on a fully constrained sketch:

Now all we need to do is edit the 5cm distances between the outer line and the inner line, by double-clicking them, and changing their value to 2.5cm (Remember, the units are still not fully functional at the time I'm writing this). After clicking the "OK" button, our door (and its clone) have been updated.

Working without 2D support Until now our work has been relatively easy, because we had the underlying 2D drawings to base our work upon. But now, we must do the opposite facade and the glass atrium, and things are getting more complicated: The opposite facade drawing has a lot of wrong things, doesn't represent the atrium at all, and we have simply no drawing for the inner walls of the atrium. So we will need to invent a couple of things ourselves. Be sure to have a look at reference pictures to figure out how things are made. Or do it as you wish! One thing we can already do: duplicate the complicated stairs window with the Draft M ove tool, because it is equal on both sides:

Note that here, I preferred to duplicate with the Draft M ove tool instead of using a clone, because the clone currently doesn't support different colors inside objects. The difference is that the clone is a copy of the final shape of the original object, while if you copy an object, you create a new object and give it all the same properties as the original one (therefore, also its base sketch and its window components definition, which are both stored as properties). Now we must attack the parts that are not drawn anywhere. Let's start with the glass wall between the sitting room and the atrium. It'll be easier to draw it on the elevation view, because we'll get the correct height of the roof. Once you are in plan view,

you can rotate the view from the menu View -> Standard Views -> Rotate left or right, until you get a comfortable view to work, like this:

Note how on the image above, I made a line from the model to the left section, to get the exact width of the window. Then, I reproduced that width on the elevation view and divided it into 4 pieces. Then I built one main window piece, plus 4 additional windows for the sliding doors. The sketcher sometimes has difficulties with overlapping wires, that's why I preferred to keep them separated like this:

After the necessary rotations, everything clicks perfectly into place:

We still need some corner piece there. A little useful trick with the Draft SelectPlane tool, if you have a face selected when you press the button, the working plane matches this face (at least its position, and if the face is rectangular, it also tries to match its axes). This is useful to draw 2D objects directly on the model, such as here, we can draw a rectangle to be extruded directly at its correct position:

Then let's do the two remaining pieces. One is easy, it is a copy of what's on the other side, so we can simply use the 2D drawing:

The other one is a bit tricky, by looking at the pictures, we see that it has many vertical divisions, like the stairs windows. By chance (or very good design from Vilanova Artigas), the width of our window, of 4.50m, is exactly the same as the stairs window, so we can use the exact same division: 15 pieces of 30cm. Here I used the Draft Array tool to copy over the two lines 15 times,and drew rectangles on top of them:

Once this is done, we can create our window with the same method we already know. Another small useful trick, in case you haven't found it yourself already: When editing a window, if you change the name of a component, it actually creates a duplicate of it. So to create the 15 inner glass panels, instead of clicking 15 times the "add" button and fill 15 times the data, you can just keep editing one, and change its name and wire, it will create a copy each time. After the window is rotated and moved into place, the atrium is complete:

Edits and fixes Now when we look at our back elevation, and compare it with the plan, we see that there are some differences that need to be fixed. Namely, the bedroom windows are smaller than I first thought, and we'll need to add some more walls. In order to do that properly, some floors need to be cut:

We have of course several ways to do that, making a subtraction volume would be an easy way, but it would add unnecessary complexity to the model. Better to edit the base wire of each floors. This is where the Draft Edit mode comes into action. By expanding these floors in the tree view, then making their base wire visible, we can then double-click them to enter edit mode. There, we can move their points, or add or remove points. With this,editing our floor plates becomes easy.

After some more sweat (the person who made those drawings obviously became pretty lazy when did this last elevation, much is drawn wrong), we finally have our complete house:

Note the chimney tube, which is made from a circle I used to make a hole in the chimney block, that I extruded, then converted into a tube with the Part Offset tool. Problems in objects Sometimes an object you made can have problems. For example, the object it was based onto has been deleted, and the object can therefore not recalculate its shape. These are usually shown to you by a little red sign on their icon, and/or a warning in the output window. There is no generic recipe to fix these problems, because they can have many origins. But, the easiest way to solve them is often to delete them, and, if you didn't delete their base objects, recreate them.

Output Now, after all the hard work we passed through to build this model, comes the reward: What can we do with it? Basically, this is the big advantage of working with BIM, all our traditional architectural needs, such as 2d drawings (plans, sections, etc), renderings, and calculations (bills of quantities, etc) can all be extracted from the model. And, even better, regenerated every time the model changes. I'll show you here how to obtain these different documents.

Preparations Before starting to export stuff, one consideration is interesting to do: As you saw, our model is becoming increasingly complex,

with a lot of relationships between objects. This can make subsequent calculation operations, such as cutting through the model, heavy. One quick way to magically "simplify" drastically your model, is to remove all of this complexity, by exporting it to the STEP format. That format will preserve all your geometry, but will discard all the relationships and parametric constructions, keeping only the final shape. When reimporting that STEP file into FreeCAD, you will get a model that has no relationship, and a much smaller file size. Think of it as an "output" file, that you can regenerate anytime from your "master" file:

Exporting to IFC and other applications

One of the very fundamental things you need when working with BIM is to be able to import and export IFC files. This is still a work in progress in FreeCAD. IFC format is already supported, and importing IFC files into FreeCAD is already pretty reliable. Exporting is still experimental, though, and has currently many limitations. However, things are bettering and we should get proper IFC export very soon. IFC export requires very little setup, once the necessary software libraries are installed. You only need to recreate the building structure, which is needed in all IFC files, by adding an Arch Building to your file, then an Arch Floor, then moving all the groups of objects that compose your model in it. Make sure you leave your construction geometry (all the 2D stuff we've been drawing) out of it to avoid making your IFC file unnecessarily heavy. Another thing to set, is to check the "Role" property of structural elements. Since IFC has no "generic" structural element, like FreeCAD, we need to assign them roles (column, beam, etc...) so the exporter knows what element to create in the IFC file. In this case, we need our whole architectural system, so the IFC exporter can know if an object must be exported as a wall or a column, so we are using our "master" model, not our "output" model. Once this is done, simply select your building object, and choose the "Industry Foundation Classes" format. Exporting to nonBIM applications, such as Sketchup is also easy, you have several export formats at your disposal, such as Collada, STEP, IGES ou OBJ.

Rendering

FreeCAD also features a rendering module, the Raytracing Workbench. That workbench currently supports two render engines, PovRay and LuxRender. Since FreeCAD is not designed for image rendering, the features that the Raytracing workbench offer to you are somewhat limited. The best course of action when you want to do proper rendering, is to export your model to a mesh-based format such as OBJ or STL, and open it in an application more suited to rendering, such as blender. The image below has been rendered with blender's cycles engine:

But, for a quick rendering, the Raytracing workbench can already do a good job, with the advantage of being very easy to setup, thanks to its templates system. This is a rendering of our model fully made within FreeCAD, with the Luxrender engine, using the "indoor" template.

The Raytracing workbench still offers you very limited control over materials, but lighting and environments are defined in templates, so they can be fully customized.

2D drawings Certainly the most important use of BIM is to produce 2D drawings automatically. This is done in FreeCAD with the Arch

SectionPlane tool. This tool allows you to place a section plane object in the 3D view, that you can orient to produce plans, sections and elevations. Section planes must know what objects they must consider, so once you have created one, you must add objects to it with the Arch Add tool. You can add individual objects, or, more conveniently, a group, a floor or a whole building. This allows you to easily change the scope of a certain section plane later, by adding or removing objects to/from that group. Any change to these objects gets reflected in the views produced by the section plane. The section plane automatically produces cut views of the objects it intersects. In other words, to produce views instead of sections, you just need to place the section plane outside of your objects.

The section planes can produce two different outputs: shape objects, that live in the same document as your 3D model, or drawing views, that are made to use on a drawing sheet produced by the Drawing workbench. Each of these behave differently, and has its own advantages. Shape views This output is produced by using the Draft Shape2DView tool with a section plane selected. You produce a 2D view of the model directly in the 3D space, like on the image above. The main advantage here is that you can work on them using the Draft tools (or any other standard tool of FreeCAD), so you can add texts, dimensions, symbols, etc:

On the image above, two Shape2D views have been produced for each section, one showing everything, the other showing only the cut lines. This allows us to give it a different line weight, and turn hatching on. Then, dimensions, texts and symbols have been added, and a couple of DXF blocks have been imported to represent the furniture. These views are then easy to export to DXF or DWG, and open in your favorite 2D CAD application, such as LibreCAD or DraftSight, where you can work further on them:

Note that some features are still not supported by the DXF/DWG exporter so the result in your 2D application might differ a bit. For example, in the image above, I had to redo the hatching, and correct the position of some dimension texts. If you place your objects in different groups in FreeCAD, these become layers in your 2D CAD application. Drawing views The other kind of output that can be produced from section planes is a Drawing view. These are produced by using the Draft Drawing tool with a section plane selected. This method has one big limitation compared to the previous one: you have limited possibilities to edit the results, and at the moment, things like dimensioning or hatching are still not natively supported. On the other hand, the final output being easier to manipulate, and the graphical possibilities of the SVG format being huge, in the future, undoubtedly this will be the preferred method. At the moment, though, you'll get better results using the previous one.

On the image above, the geometry is the direct output of the section plane, but some other Draft objects have been added, such as dimensions and hatched polygons, and another view object with same scale and offset values has been produced from them with the Draft Drawing tool. In the future, such operations will be done directly on the Drawing page, leaving your model totally clean.

Quantities extraction This is another very important task to be performed on BIM models. In FreeCAD, things look good right from the start, since the OpenCasCade kernel of FreeCAD already takes care of calculating lengths, areas and volumes for all the shapes it produces. Since all Arch objects are solids, you are always guaranteed to be able to obtain a volume from them. Using spreadsheets There is a brand-new workbench in FreeCAD, the Spreadsheet Workbench, that is the perfect tool for collecting such information about our model. It can count objects of a certain name or a certain type, or display a specific properties of those objects. The spreadsheet workbench features two objects: The spreadsheet object is a simple spreadsheet container, that you can edit, and place values inside the cells, but has no automation. The cell controller, on the other hand, is an object that you must insert in a spreadsheet, that controls a series of cells of its host spreadsheet, filling them according to what you specify. This, provided that you organized your model well, allows you to easily retrieve individual values:

Note that the spreadsheet workbench is still very new, and like everything very new, still contains many bugs and limitations. But for simple summaries like this, it already works well. The resulting spreadsheet can then be exported to a CSV file, which can be imported in any spreadsheet application. The survey mode Another way to survey your model and extract values, is to use the Arch Survey mode. In this mode, you can click on points, edges, faces or double-click to select whole objects, and you get altitude, length, area or volume values, shown on the model, printed on the FreeCAD output window, and copied to the clipboard, so you can easily pick and paste values in another opened application

Conclusion I hope this gives you a good overview of the available tools, be sure to refer to the Arch Workbench and Draft Workbench documentation for more (there are more tools that I didn't mention here), and, more generally, to the rest of the FreeCAD documentation. Pay a visit to the forum too, many problems can usually be solved there in no time, and follow my blog for news about he Arch workbench development. The file created during this tutorial can be found here

Drawing Workbench (Redirected from Drawing Workbench) The Drawing module allows you to put your 3D work on paper. That is, to put views of your models in a 2D window and to insert that window in a drawing, for example a sheet with a border, a title and your logo and finally print that sheet. The Drawing module is currently under construction and more or less a technology preview!

GUI Tools These are tools for creating, configuring and exporting 2D drawing sheets Open scalable vector graphic: Opens a drawing sheet previously saved as an SVG file New A3 landscape drawing: Creates a new drawing sheet from FreeCAD's default A3 template Insert a view: Inserts a view of the selected object in the active drawing sheet Annotation: Adds an annotation to the current drawing sheet Clip: Adds a clip group to the current drawing sheet Open Browser: Opens a preview of the current sheet in the browser Ortho Views: Automatically creates orthographic views of an object on the current drawing sheet Symbol: Adds the contents of a SVG file as a symbol on the current drawing sheet Draft View: Inserts a special Draft view of the selected object in the current drawing sheet Save sheet: Saves the current sheet as a SVG file Project Shape: Creates a projection of the selected object (Source) in the 3D view. .

Note The Draft M odule has its own Draft Drawing tool to place Draft objects on paper. It has a couple of extra capabilities over the standard Drawing tools, and supports specific objects like Draft dimensions.

In the picture you see the main concepts of the Drawing module. The document contains a shape object (Schenkel) which we want to extract to a drawing. Therefore a "Page" is created. A page gets instantiated through a template, in this case the "A3_Landscape" template. The template is an SVG document which can hold your usual page frame, your logo or comply to your presentation standards. In this page we can insert one or more views. Each view has a position on the page (Properties X,Y), a scale factor (Property scale) and additional properties. Every time the page or the view or the referenced object changes the page gets regenerated and the page display updated.

Scripting At the moment the end user(GUI) workflow is very limited, so the scripting API is more interesting. Here follow examples on how to use the scripting API of the drawing module. Here a script that can easily fill the M acro_CartoucheFC leaf FreeCAD A3_Landscape.

Simple example First of all you need the Part and the Drawing module: import FreeCAD, Part, Drawing Create a small sample part Part.show(Part.makeBox(100,100,100).cut(Part.makeCylinder(80,100)).cut(Part.makeBox(90,40,100)).cut(Part.makeBox(20,85,100))) Direct projection. The G0 means hard edge, the G1 is tangent continuous. Shape = App.ActiveDocument.Shape.Shape [visibleG0,visibleG1,hiddenG0,hiddenG1] = Drawing.project(Shape) print "visible edges:", len(visibleG0.Edges) print "hidden edges:", len(hiddenG0.Edges) Everything was projected on the Z-plane: print "Bnd Box shape: X=",Shape.BoundBox.XLength," Y=",Shape.BoundBox.YLength," Z=",Shape.BoundBox.ZLength print "Bnd Box project: X=",visibleG0.BoundBox.XLength," Y=",visibleG0.BoundBox.YLength," Z=",visibleG0.BoundBox.ZLength Different projection vector [visibleG0,visibleG1,hiddenG0,hiddenG1] = Drawing.project(Shape,App.Vector(1,1,1)) Project to SVG resultSVG = Drawing.projectToSVG(Shape,App.Vector(1,1,1)) print resultSVG

The parametric way Create the body import FreeCAD import Part import Drawing # Create three boxes and a cylinder App.ActiveDocument.addObject("Part::Box","Box") App.ActiveDocument.Box.Length=100.00 App.ActiveDocument.Box.Width=100.00 App.ActiveDocument.Box.Height=100.00 App.ActiveDocument.addObject("Part::Box","Box1") App.ActiveDocument.Box1.Length=90.00 App.ActiveDocument.Box1.Width=40.00 App.ActiveDocument.Box1.Height=100.00 App.ActiveDocument.addObject("Part::Box","Box2") App.ActiveDocument.Box2.Length=20.00 App.ActiveDocument.Box2.Width=85.00 App.ActiveDocument.Box2.Height=100.00 App.ActiveDocument.addObject("Part::Cylinder","Cylinder") App.ActiveDocument.Cylinder.Radius=80.00 App.ActiveDocument.Cylinder.Height=100.00 App.ActiveDocument.Cylinder.Angle=360.00 # Fuse two boxes and the cylinder App.ActiveDocument.addObject("Part::Fuse","Fusion") App.ActiveDocument.Fusion.Base = App.ActiveDocument.Cylinder App.ActiveDocument.Fusion.Tool = App.ActiveDocument.Box1 App.ActiveDocument.addObject("Part::Fuse","Fusion1") App.ActiveDocument.Fusion1.Base = App.ActiveDocument.Box2 App.ActiveDocument.Fusion1.Tool = App.ActiveDocument.Fusion # Cut the fused shapes from the first box App.ActiveDocument.addObject("Part::Cut","Shape") App.ActiveDocument.Shape.Base = App.ActiveDocument.Box App.ActiveDocument.Shape.Tool = App.ActiveDocument.Fusion1 # Hide all the intermediate shapes Gui.ActiveDocument.Box.Visibility=False Gui.ActiveDocument.Box1.Visibility=False Gui.ActiveDocument.Box2.Visibility=False Gui.ActiveDocument.Cylinder.Visibility=False Gui.ActiveDocument.Fusion.Visibility=False Gui.ActiveDocument.Fusion1.Visibility=False Insert a Page object and assign a template App.ActiveDocument.addObject('Drawing::FeaturePage','Page') App.ActiveDocument.Page.Template = App.getResourceDir()+'Mod/Drawing/Templates/A3_Landscape.svg' Create a view on the "Shape" object, define the position and scale and assign it to a Page App.ActiveDocument.addObject('Drawing::FeatureViewPart','View') App.ActiveDocument.View.Source = App.ActiveDocument.Shape App.ActiveDocument.View.Direction = (0.0,0.0,1.0) App.ActiveDocument.View.X = 10.0 App.ActiveDocument.View.Y = 10.0 App.ActiveDocument.Page.addObject(App.ActiveDocument.View)

Create a second view on the same object but this time the view will be rotated by 90 degrees. App.ActiveDocument.addObject('Drawing::FeatureViewPart','ViewRot') App.ActiveDocument.ViewRot.Source = App.ActiveDocument.Shape App.ActiveDocument.ViewRot.Direction = (0.0,0.0,1.0) App.ActiveDocument.ViewRot.X = 290.0 App.ActiveDocument.ViewRot.Y = 30.0 App.ActiveDocument.ViewRot.Scale = 1.0 App.ActiveDocument.ViewRot.Rotation = 90.0 App.ActiveDocument.Page.addObject(App.ActiveDocument.ViewRot) Create a third view on the same object but with an isometric view direction. The hidden lines are activated too. App.ActiveDocument.addObject('Drawing::FeatureViewPart','ViewIso') App.ActiveDocument.ViewIso.Source = App.ActiveDocument.Shape App.ActiveDocument.ViewIso.Direction = (1.0,1.0,1.0) App.ActiveDocument.ViewIso.X = 335.0 App.ActiveDocument.ViewIso.Y = 140.0 App.ActiveDocument.ViewIso.ShowHiddenLines = True App.ActiveDocument.Page.addObject(App.ActiveDocument.ViewIso) Change something and update. The update process changes the view and the page. App.ActiveDocument.View.X = 30.0 App.ActiveDocument.View.Y = 30.0 App.ActiveDocument.View.Scale = 1.5 App.ActiveDocument.recompute()

Accessing the bits and pieces Get the SVG fragment of a single view ViewSVG = App.ActiveDocument.View.ViewResult print ViewSVG Get the whole result page (it's a file in the document's temporary directory, only read permission) print "Resulting SVG document: ",App.ActiveDocument.Page.PageResult file = open(App.ActiveDocument.Page.PageResult,"r") print "Result page is ",len(file.readlines())," lines long" Important: free the file! del file Insert a view with your own content: App.ActiveDocument.addObject('Drawing::FeatureView','ViewSelf') App.ActiveDocument.ViewSelf.ViewResult = """<g id="ViewSelf" stroke="rgb(0, 0, 0)" stroke-width="0.35" stroke-linecap="butt" stroke-linejoin="miter" transform="translate(30,30)" fill="#00cc00" > <ellipse cx="40" cy="40" rx="30" ry="15"/> </g>""" App.ActiveDocument.Page.addObject(App.ActiveDocument.ViewSelf) App.ActiveDocument.recompute() del ViewSVG That leads to the following result:

General Dimensioning and Tolerancing Drawing dimensions an tolerances are still under development but you can get some basic functionality with a bit of work. First you need to get the gdtsvg python module from here (WARNING: This could be broken at any time!): https://github.com/jcc242/FreeCAD To get a feature control frame, try out the following: import gdtsvg as g # Import the module, I like to give it an easy handle ourFrame = g.ControlFrame("0","0", g.Perpendicularity(), ".5", g.Diameter(), g.ModifyingSymbols("M"), "A", g.ModifyingSymbols("F"), "B", g.ModifyingSymbols("L"), "C", g.ModifyingSymbols("I")) Here is a good breakdown of the contents of a feature control frame: http://www.cadblog.net/adding-geometrictolerances.htm The parameters to pass to control frame are: 1. X-coordinate in SVG-coordinate system (type string) 2. Y-coordinate in SVG-coordinate system (type string) 3. The desired geometric characteristic symbol (tuple, svg string as first, width of symbol as second, height of symbol as third) 4. The tolerance (type string) 5. (optional) The diameter symbol (tuple, svg string as first, width of symbol as second, height of symbol as third) 6. (optional) The condition modifying material (tuple, svg string as first, width of symbol as second, height of symbol as third) 7. (optional) The first datum (type string) 8. (optional) The first datum's modifying condition (tuple, svg string as first, width of symbol as second, height of symbol as third) 9. (optional) The second datum (type string) 10. (optional) The second datum's modifying condition (tuple, svg string as first, width of symbol as second, height of symbol as third) 11. (optional) The third datum (type string) 12. (optional) The third datum's material condition (tuple, svg string as first, width of symbol as second, height of symbol as third) The ControlFrame function returns a type containing (svg string, overall width of control frame, overall height of control frame) To get a dimension, try out the following: import gdtsvg ourDimension = linearDimension(point1, point2, textpoint, dimensiontext, linestyle=getStyle("visible"), arrowstyle=getStyle("filled"), textstyle=getStyle("text") Inputs for linear dimension are: 1. point1, an (x,y) tuple with svg-coordinates, this is one of the points you would like to dimension between 2. point2, an (x,y) tuple with svg-coordinates, this is the second point you would like to dimension between 3. textpoint, an (x,y) tuple of svg-coordinates, this is where the text of your dimension will be 4. dimensiontext, a string containing the text you want the dimension to say 5. linestyle, a string containing svg (i.e. css) styles, using the getStyle function to retrieve a preset string, for styling the how the lines look 6. arrowstyle, a string containing svg (i.e. css) styles, using the getStyle function to retrieve a preset string, for styling how the arrows look

7. textstyle, a string containing svg (i.e. css) styles, using the getStyle function to retrieve a preset string, for styling how the text looks With those two, you can proceed as above for displaying them on the drawing page. This module is very buggy and can be broken at any given moment, bug reports are welcome on the github page for now, or contact jcc242 on the forums if you post a bug somewhere else.

Templates FreeCAD comes bundled with a set of default templates, but you can find more on the Drawing templates page.

Extending the Drawing Module Some notes on the programming side of the drawing module will be added to the Drawing Documentation page. This is to help quickly understand how the drawing module works, enabling programmers to rapidly start programming for it.

Drawing Landscape A3 This tool creates a new drawing sheet from already installed templates. Currently, even though the menu and the toolbar allow for A0 to A4 landscape formats, only an A3 Landscape template is available. A Page object will be added to the Project tree, taking the form of a folder icon. Views that will be created afterward will be placed underneath this folder. To open the Drawing viewer to display the page, simply double-click on the Page object, or right-click → Show drawing. The page will be opened in a new tab. You can close the tab and open it again at any time the same way. If the page does not display, click on the → Refresh menu, or shortcut CTRL+R .

refresh icon in the main toolbar, or go to Edit

Drawing Landscape A3 M enu location Drawing → Insert new drawing → A3 Landscape Workbenches Drawing, Complete Default shortcut none See also None

Options The template used by a Page can be changed through its Template property in Data view. Click on the value field, then on the "..." button and navigate to a suitable template. Then refresh the view.

Drawing View This tool creates a new view of the selected object in the active drawing sheet.

Drawing View M enu location Drawing â&#x2020;&#x2019; Insert view in drawing Workbenches Drawing, Complete Default shortcut none See also Drawing Landscape A3

How to use Select an object either in the 3D view or the Project tree, then click on the Drawing View tool. By default, a top view scaled at 1:1 (real scale) will be placed at the top left of the page. It may not be visible if it's too small or too big for the page. A View object is added to the Page object in the Project tree. For subsequent views, a three-digit number will be appended to the name. Click on the arrow in front of the Page object to unfold it and display the views it contains. If only the object is selected in the Project Tree, the view is added to the first page of the project. If you have multiple pages in your project please select the object and the page it should be added to. Then click on the icon to add the view to the selected page.

Modify an existing view Unfold the Page object in the Project tree, and select the View. Its parameters can be edited in the Property View Data tab.

Isometric view with smooth lines visibility off

Isometric view with smooth lines visibility on Label: changes the view's label in the Project tree. You can also click on the View in the tree and right-click â&#x2020;&#x2019; Rename, or press F2 . Rotation: rotates the view. For example, an isometric view will require a 60 degree rotation (see also Direction parameter below) Scale: sets the view scale. X: sets the view's horizontal position on the page in millimeters. Y: sets the view's vertical position on the page in millimeters. Please note that coordinate (0,0) is located at the top left of the page, so the higher the number, the lower in the page the view will be. Direction: changes the view direction. It is set by xyz values that define a vector normal to the page. Top view will be (0,0,1), and isometric will be (1,1,1). Values can be negative. Show Hidden Lines: toggles the hidden lines visibility on or off by selecting True or False. Show Smooth Lines: toggles the smooth lines visibility on or off by selecting True or False. Smooth lines are also called tangency edges. These edges indicate surface changes between tangent surfaces.

Drawing View Wizard To generate a drawing sheet with standard views automatically, use the Automatic drawing M acro.

Drawing Annotation Description This command allows you to place a block of text on a Drawing page.

How to use 1. Create a Drawing page 2. Refresh the view if a Drawing view wasn't opened 3. Press the

Drawing Annotation button

4. Adjust the desired properties, such as text contents, font, size and position.

Drawing Annotation M enu location Drawing â&#x2020;&#x2019; Annotation Workbenches Drawing, Complete Default shortcut none See also None

Limitations Texts spanned on multiple lines are not supported by the internal Qt-based Svg viewer, but the Open Browser command shows these texts correctly.

Drawing Clip Description This command allows you to place a clipping rectangle on a Drawing page. Drawing View objects can then be added to that clipping rectangle, and their display will be truncated by the borders of the rectangle.

How to use 1. Create a Drawing page 2. Refresh the view if a Drawing view wasn't opened 3. Press the

Drawing Clip M enu location Drawing â&#x2020;&#x2019; Clip Workbenches Drawing, Complete Default shortcut none See also None

Drawing Clip button

4. Adjust the desired properties, such as size and position. 5. Drag and Drop Drawing View objects on the Clip object in the Tree View

Options A property allows you to show or hide the clipping rectangle itself.

Limitations Clipping objects are not displayed properly by the internal Qt-based Svg viewer, but the Open Browser command shows them correctly.

Drawing Openbrowser Description This command allows you to display a selected Drawing page using FreeCAD's internal web browser. The normal Drawing page viewer of FreeCAD is based on Qt's built-in SVG rendering module, which only supports a tiny subset of the full SVG specification. As a result, some more advanced SVG features, such as pattern fills or multiline texts are not supported by this viewer. The FreeCAD internal web browser, however, is built on webkit, which is one of the best SVG renderers available, and will correctly render your page with all its features.

How to use 1. Create a Drawing page

Drawing Openbrowser M enu location Drawing â&#x2020;&#x2019; Open Browser Workbenches Drawing, Complete Default shortcut none See also None

2. Add some views or other content to your page 3. Refresh the view if a Drawing view wasn't opened 4. Press the

Drawing Openbrowser button

Limitations A page opened in the web browser will not refresh automatically on changes. You must use right-click -> reload manually.

Drawing Symbol Description This command allows you to add the contents of a SVG image on a selected Drawing page. These contents can then be moved and rescaled on the page. The contents of the SVG image are copied into the FreeCAD document, so it is independent from the original file, and will display the same way on another computer that doesn't have the original SVG file.

How to use 1. Create a Drawing page 2. Refresh the view if a Drawing viewer wasn't opened 3. Press the

Drawing Symbol button

4. Select a SVG file 5. Adjust the needed properties, like position and scale.

Drawing Symbol M enu location Drawing â&#x2020;&#x2019; Symbol Workbenches Drawing, Complete Default shortcut none See also None

Drawing DraftView (Redirected from Drawing DraftView)

Description This tool allows you to put selected objects on a svg Drawing sheet. If no sheet exists in the document, a default one will be created. This tool works similarly to the Drawing View tool, but is optimized for Draft objects, and can render flat 2D objects with a face filling. It can also handle a couple of specific Draft objects, such as dimensions and texts, that the Drawing View tool cannot handle.

Draft Drawing M enu location Drafting â&#x2020;&#x2019; Drawing Workbenches Draft, Arch Default shortcut None See also None

How to use 1. Select the objects you wish to put on a drawing sheet 2. Press the

Draft Drawing button

Options Select objects you want to put on the drawing sheet. The tool will work best with flat 2D objects from the Draft or Sketcher modules. If the selected object is an Arch SectionPlane, this tool will create an additional view of that section plane. In the same selection, add the page object you want to draw your objects to. If there is no existing page, a new one will be created. If you didn't select a page but there is at least one in the document, the first found one will be used to draw to. If you selected an existing sheet, and the objects in the selection that are already on that sheet (for ex. for a "Rectangle" object there is already a "ViewRectangle" object on the sheet), they will be substitued. This allows you to simply select all the objects and send them to an existing page, which will simply be updated.

Properties DATA

Fill Style: For closed shapes, allows to specify one of the Default Draft fill styles, or use the shape color.

DATA

Font Size: Allows you to specify the font size of texts and dimensions.

DATA

Line Width: Allows you to specify the line width of viewed objects.

Scripting The Draft Drawing tool can by used in macros and from the python console by using the following function: makeDrawingView (object,page) Adds a view of the given object to the given page. Returns the created view object.

Example: import FreeCAD,Draft obj = FreeCAD.ActiveDocument.ActiveObject page = FreeCAD.ActiveDocument.Page Draft.makeDrawingView(obj,page)

Drawing Save This tool saves the current Drawing sheet as an SVG (scalable vector graphics) file. Such a file can then be edited in a scalable vector graphics program such as Inkscape.

Drawing Save

SVG files are common and can be viewed in most modern browsers and image viewers. It can be a useful way to share a design with people who don't have FreeCAD installed on their PC.

M enu location Drawing â&#x2020;&#x2019; Export page... Workbenches Drawing, Complete Default shortcut none See also Drawing Open SVG

Drawing ProjectShape 32px Project Shape

Description This tool creates a projection of the selected object (Source) in the 3D view.

M enu location Drawing â&#x2020;&#x2019; Project shape Workbenches Drawing, Complete Default shortcut See also

Usage

1. Select an object in the 3D view or in the project tree 2. from the Drawing menu, click Project shape 3. set the desired options in the Task Dialog 4. click OK A projection object (objectname_proj) will be added to the project. For subsequent projections of the same Source object, the projection object will be named objectname_projXXX, where XXX is a three digit number.

Edit an existing projection

The projection parameters can be edited in the Property editor. Base DATA

Label :

DATA

Placement :

Projection Direction : defines the direction of the projection. This is the normal vector of the projection plane. For example, to project the object onto the xy plane, use (0,0,1). To reverse the projection, use negative values. DATA

DATA

HCompound :

DATA

Iso Line HCompound :

DATA

Iso Line VCompound :

DATA

Out Line HCompound :

DATA

Out Line VCompound :

DATA

Rg1 Line HCompound :

DATA

Rg1 Line VCompound :

DATA

Rg NLine HCompound :

DATA

Rg NLine VCompound :

DATA

Source : the object being projected

DATA

VCompound :

Raytracing Workbench (Redirected from Raytracing Workbench) The Raytracing module is used to generate photorealistic images of your models by rendering them with an external renderer. The Raytracing workbench works with templates, the same way as the Drawing workbench, by allowing you to create a Raytracing project in which you add views of your objects. The project can then be exported to a ready-to-render file, or be rendered directly.

Currenly, two renderers are supported: povray and luxrender. To be able to render directly from FreeCAD, at least one of those renderers must be installed on your system, and its path must be configured in the FreeCAD Raytracing preferences. Without any renderer installed, though, you are still able to export a scene file that can be used in any of those renderers later, or on another machine. The raytracing workbench works with templates, which are complete scene files for the given external renderer, including lights and possibly additional geometry such as ground planes. These scene files contain placeholders, where FreeCAD will insert the position of the camera, and geometry and materials information of each of the objects you insert in the project. That modified scene file is what is then exported to the external renderer.

Tools Raytracing project tools These are the main tools for exporting your 3D work to external renderers New PovRay project: Insert new PovRay project in the document New LuxRender project: Insert new LuxRender project in the document Insert part: Insert a view of a Part in a raytracing project Reset camera: Matches the camera position of a raytracing project to the current view Export project: Exports a raytracing project to a scene file for rendering in an external renderer Render: Renders a raytracing project with an external renderer

Utilities

These are helper tools to perform specific tasks manually Export view to povray: Write the active 3D view with camera and all its content to a povray file Export camera to povray: Export the camera position of the active 3D view in POV-Ray format to a file Export part to povray: Write the selected Part (object) as a povray file

Typical workflow 1. Create or open a FreeCAD project, add some Part-based objects (meshes are currently not supported) 2. Create a Raytracing project (luxrender or povray) 3. Select the objects you wish to add to the raytracing project and add them to the project with the "Insert Part" tool 4. Export or render directly

Creating a povray file manually The utility tools described above allow you to export the current 3D view and all of its content to a Povray file. First, you must load or create your CAD data and position the 3D View orientation as you wish. Then choose "Utilities->Export View..." from the raytracing menu.

You will be asked for a location to save the resulting *.pov file. After that you can open it in Povray and render:

As usual in a rendererer you can make big and nice pictures:

Scripting Outputting render files The Raytracing and RaytracingGui modules provide several methods to write scene contents as povray or luxrender data. The most useful are Raytracing.getPartAsPovray() and Raytracing.getPartAsLux() to render a FreeCAD Part object into a povray or luxrender definition, and RaytracingGui.povViewCamera() and RaytracinGui.luxViewCamera() to get the current point of view of the FreeCAD 3D window into povray or luxrender format. Here is how to write a povray file from python, assuming your document contains a "Box" object: import Raytracing,RaytracingGui OutFile = open('C:/Documents and Settings/jriegel/Desktop/test.pov','w') OutFile.write(open(App.getResourceDir()+'Mod/Raytracing/Templates/ProjectStd.pov').read()) OutFile.write(RaytracingGui.povViewCamera()) OutFile.write(Raytracing.getPartAsPovray('Box',App.activeDocument().Box.Shape,0.800000,0.800000,0.800000)) OutFile.close() del OutFile And the same for luxrender: import Raytracing,RaytracingGui OutFile = open('C:/Documents and Settings/jriegel/Desktop/test.lxs','w') OutFile.write(open(App.getResourceDir()+'Mod/Raytracing/Templates/LuxClassic.lxs').read()) OutFile.write(RaytracingGui.luxViewCamera()) OutFile.write(Raytracing.getPartAsLux('Box',App.activeDocument().Box.Shape,0.800000,0.800000,0.800000)) OutFile.close() del OutFile

Creating a custom render object

Apart from standard povray and luxrender view objects that provide a view of an existing Part object, and that can be inserted in povray and luxrender projects respectively, a third object exist, called RaySegment, that can be inserted either in povray or luxrender projects. That RaySegment object is not linked to any of the FreeCAD objects, and can contain custom povray or luxrender code, that you might wish to insert into your raytracing project. You can also use it, for example, to output your FreeCAD objects a certain way, if you are not happy with the standard way. You can create and use it like this from the python console: myRaytracingProject = FreeCAD.ActiveDocument.PovProject myCustomRenderObject = FreeCAD.ActiveDocument.addObject("Raytracing::RaySegment","myRenderObject") myRaytracingProject.addObject(myCustomRenderObject) myCustomRenderObject.Result = "// Hello from python!"

Links POVRay http://www.spiritone.com/~english/cyclopedia/ http://www.povray.org/ http://en.wikipedia.org/wiki/POV-Ray

Luxrender http://www.luxrender.net/

Future possible renderers to implement http://www.yafaray.org/ http://www.mitsuba-renderer.org/ http://www.kerkythea.net/ http://www.artofillusion.org/ Currently there is a new Renderer Workbench in development to support multiple back-ends such as Lux Renderer and Yafaray. Information for using the development version can be viewed at Render_project For Development status of the Render Module look here Raytracing_project

Templates FreeCAD comes with a couple of default templates for povray and luxrender, but you can easily create your own. All you need to do is to create a scene file for the given renderer, then edit it manually with a text editor to insert special tags that FreeCAD will recognize and where it will insert its contents (camera and objects data)

Povray Povray scene files (with extension .pov) can be created manually with a text editor (povray is made primarily to be used as a scripting language), but also with a wide range of 3D applications, such as blender. On the povray website you can find further information and a list of applications able to produce .pov files. When you have a .pov file ready, you need to open it with a text editor, and do two operations: 1. Strip out the camera information, because FreeCAD will place its own camera data. To do so, locate a text block like this: camera { ... }, which describes the camera parameters, and delete it (or put "//" in front of each line to comment them out). 2. Insert the following line somewhere: //RaytracingContent. This is where FreeCAD will insert its contents (camera and objects data). You can, for example, put this line at the very end of the file. Note that FreeCAD will also add some declarations, that you can use in your template, after the //RaytracingContent tag. These are: cam_location: the location of the camera cam_look_at: the location of the target point of the camera cam_sky: the up vector of the camera. cam_angle: the angle of the camera If you want, for example, to place a lamp above the camera, you can use this: light_source { cam_location + cam_angle * 100 color rgb <10, 10, 10> }

Luxrender

Luxrender scene files (with extension.lxs) can either be single files, or a master .lxs file that includes world definition (.lxw), material definition (.lxm) and geometry definition (.lxo) files. You can work with both styles, but it is also easy to transform a group of 4 files in a single .lxs file, by copying the contents of each .lxw, .lxm and .lxo file and pasting it at the point where that file is inserted in the master .lxs file. Luxrender scene files are hard to produce by hand, but are easy to produce with many 3D applications such as blender. On the luxrender website, you'll find more information and plugins for the main 3D applications out there. If you will work with separated .lxw, .lxm and .lxo files, beware that the final .lxs exported by FreeCAD might be at a different location than the template file, and therefore these files might not be found by Luxrender at render time. In this case you should or copy these files to the location of your final file, or edit their paths in the exported .lxs file. If you are exporting a scene file from blender, and wish to merge everything into one single file, you will need to perform one step before exporting: By default, the luxrender exporter in blender exports all mesh geometry as separate .ply files, instead of placing the mesh geometry directly inside the .lxo file. To change that behaviour, you need to select each of your meshes in blender, go to the "mesh" tab and set the option "export as" to "luxrender mesh" for each one of them. After you have your scene file ready, to turn it into a FreeCAD template, you need to perform the following steps: 1. Locate the camera position, a single line that begins with LookAt, and delete it (or place a "#" at the beginning of the line to comment it out) 2. At that place, insert the following line: #RaytracingCamera 3. At a desired point, for example just after the end of the materials definition, before the geometry information, or at the very end, just before the final WorldEnd line, insert the following line: #RaytracingContent. That is where FreeCAD will insert its own objects. Note that in luxrender, the objects stored in a scene file can define transformation matrixes, that perform location, rotation or scaling operations. These matrixes can stack and affect everything that come after them, so, by placing your #RaytracingContent tag at the end of the file, you might see your FreeCAD objects affected by a transformation matrix placed earlier in the template. To make sure that this doesn't happen, place your #RaytracingContent tag before any other geometry object present in the template. FreeCAD itself won't define any of those transformation matrixes.

Exporting to Kerkythea Although direct export to the Kerkythea XML-File-Format is not supported yet, you can export your Objects as Mesh-Files (.obj) and then import them in Kerkythea. if using Kerkythea for Linux, remember to install the WINE-Package (needed by Kerkythea for Linux to run) you can convert your models with the help of the mesh workbench to meshes and then export these meshes as .obj-files If your mesh-export resulted in errors (flip of normals, holes ...) you may try your luck with netfabb studio basic Free for personal use, available for Windows, Linux and Mac OSX. It has standard repair tools which will repair you model in most cases. another good program for mesh analysing/repairing is M eshlab Open Source, available for Windows, Linux and Mac OSX. It has standard repair tools which will repair you model in most cases (fill holes, re-orient normals, etc.) you can use "make compound" and then "make single copy" or you can fuse solids to group them before converting to meshes remember to set in Kerkythea an import-factor of 0.001 for obj-modeler, since Kerkythea expects the obj-file to be in m (but standard units-scheme in FreeCAD is mm) Within WIndows 7 64-bit Kerkythea does not seem to be able to save these settings. So remember to to that each time you start Kerkythea if importing multiple objects in Kerkythea you can use the "File > Merge" command in Kerkythea

Robot Workbench

The robot workbench is a tool to simulate industrial grade 6-Axis Robots, like e.g. Kuka. You can do the following tasks: set up a simulation environment with a robot and work pieces create and fill up trajectories decompose features of an CAD part to a trajectory simulate the robot movement and reachability export the trajectory to a robot program file You can find an example here: Example files or try the Robot tutorial.

Tools Here the principal commands you can use to create a robot set-up.

Robots The tools to create and manage the 6-Axis robots Create a robot: Insert a new robot into the scene Simulate a trajectory: Opens the simulation dialog and let you simulate Export a trajectory: Export a robot program file Set home positon: Set the home position of an robot Restore home positon: move the robot to its home position

Trajectories Tools to creat and manipulate trajectories. There are two kinds, the parametric and non parametric ones. non parametric

Create a trajectory: Insert a new robot into the scene Set the default orientation: Set the orientation way-points gets created by default Set the default speed parameter: set the defaults for way-point creation Insert a waypoint: Insert a way-point from the current robot position into a trajectory Insert a waypoint: Insert a way-point from the current mouse position into a trajectory parametric

Create a trajectory out of edges: Insert a new object which decompose edges to a trajectory

Dress-up a trajectory: Let you override one or more properties of a trajectory Trajectory compound: create a compound out of some single trajectories

Scripting This section is generated out of: https://github.com/FreeCAD/FreeCAD_sf_master/blob/master/src/M od/Robot/RobotExample.py You can use this file directly if you want. Example how to use the basic robot class Robot6Axis which represents a 6-axis industrial robot. The Robot module is dependent on Part but not on other modules. It works mostly with the basic types Placement, Vector and Matrix. So we need only: from Robot import * from Part import * from FreeCAD import *

Basic robot stuff create the robot. If you do not specify another kinematic it becomes a Puma 560 rob = Robot6Axis() print rob accessing the axis and the Tcp. Axes go from 1-6 and are in degree: Start = rob.Tcp print Start print rob.Axis1 move the first axis of the robot: rob.Axis1 = 5.0 the Tcp has changed (forward kinematic) print rob.Tcp move the robot back to start position (reverse kinematic): rob.Tcp = Start print rob.Axis1 the same with axis 2: rob.Axis2 = 5.0 print rob.Tcp rob.Tcp = Start print rob.Axis2 Waypoints: w = Waypoint(Placement(),name="Pt",type="LIN") print w.Name,w.Type,w.Pos,w.Cont,w.Velocity,w.Base,w.Tool generate more. The trajectory always finds automatically a unique name for the waypoints l = [w] for i in range(5): l.append(Waypoint(Placement(Vector(0,0,i*100),Vector(1,0,0),0),"LIN","Pt")) create a trajectory t = Trajectory(l) print t for i in range(7): t.insertWaypoints(Waypoint(Placement(Vector(0,0,i*100+500),Vector(1,0,0),0),"LIN","Pt")) see a list of all waypoints: print t.Waypoints del rob,Start,t,l,w

Working with the document objects

Working with the robot document objects: first create a robot in the active document if(App.activeDocument() == None):App.newDocument() App.activeDocument().addObject("Robot::RobotObject","Robot") Define the visual representation and the kinematic definition (see 6-Axis Robot and VRM L Preparation for Robot Simulation for details about that) App.activeDocument().Robot.RobotVrmlFile = App.getResourceDir()+"Mod/Robot/Lib/Kuka/kr500_1.wrl" App.activeDocument().Robot.RobotKinematicFile = App.getResourceDir()+"Mod/Robot/Lib/Kuka/kr500_1.csv" start positon of the Axis (only that which differ from 0) App.activeDocument().Robot.Axis2 = -90 App.activeDocument().Robot.Axis3 = 90 retrieve the Tcp position pos = FreeCAD.getDocument("Unnamed").getObject("Robot").Tcp move the robot pos.move(App.Vector(-10,0,0)) FreeCAD.getDocument("Unnamed").getObject("Robot").Tcp = pos create an empty Trajectory object in the active document App.activeDocument().addObject("Robot::TrajectoryObject","Trajectory") get the Trajectory t = App.activeDocument().Trajectory.Trajectory add the actual TCP position of the robot to the trajectory StartTcp = App.activeDocument().Robot.Tcp t.insertWaypoints(StartTcp) App.activeDocument().Trajectory.Trajectory = t print App.activeDocument().Trajectory.Trajectory insert some more Waypoints and the start point at the end again: for i in range(7): t.insertWaypoints(Waypoint(Placement(Vector(0,1000,i*100+500),Vector(1,0,0),i),"LIN","Pt")) t.insertWaypoints(StartTcp) # end point of the trajectory App.activeDocument().Trajectory.Trajectory = t print App.activeDocument().Trajectory.Trajectory

Simulation To be done.....

Exporting the trajectory The trajectory is exported by Python. That means for every control cabinet type there is a post-processor Python module. Here is in detail the Kuka post-processor described from KukaExporter import ExportCompactSub ExportCompactSub(App.activeDocument().Robot,App.activeDocument().Trajectory,'D:/Temp/TestOut.src') and that's kind of how it's done: for w in App.activeDocument().Trajectory.Trajectory.Waypoints: (A,B,C) = (w.Pos.Rotation.toEuler()) print ("LIN {X %.3f,Y %.3f,Z %.3f,A %.3f,B %.3f,C %.3f} ; %s"% (w.Pos.Base.x,w.Pos.Base.y,w.Pos.Base.z,A,B,C,w.Name))

Tutorials 6-Axis_Robot VRM L Preparation for Robot Simulation

OpenSCAD Workbench (Redirected from OpenSCAD Workbench) The OpenSCAD module is in an early stage of development. The OpenSCAD module offers interoperability with the open source software OpenSCAD.

It contains an importer which allows you to open the .csg output from OpenSCAD in FreeCAD. The exporter outputs a CSG based (sub-)tree to .csg. Geometry which is not based on CSG operations and is exported as a mesh. The OpenSCAD module contains a toolbox with functions to modify the feature tree and repair models.

OpenSCAD language and file format The OpenSCAD language allows the use of variables and loops. It allows you to specify submodules to reuse geometry and code. This high degree of flexibility makes parsing very complex. Currently the OpenSCAD module in FreeCAD can not handle the OpenSCAD language natively. Instead, if OpenSCAD is installed, it can be used to convert the input to an output format named 'CSG'. It is a subset of the OpenSCAD Language and can be used as the input to OpenSCAD for further processing. During conversion all parametric behavior is lost - all variable names are discarded, loops expanded and mathematical expressions evaluated.

GUI Commands Color Code Shape: Change the Color of selected or all Shapes based on their validity Replace Object: Replace an object in the Feature Tree. Please select old, new and parent object Remove Subtree: Removes the selected objects and all children that are not referenced from other objects Refine Shape Feature: Create Refine Shape Feature Increase Tolerance Feature: Convert Edges To Faces: Convert Edges to Faces. Useful to prepare imported DXF geometry for extrusion. Expand Placements: Expand all placements downwards the FeatureTree Explode Group: Add OpenSCAD Element: Add an OpenSCAD element by entering OpenSCAD code into the task panel and executing the OpenSCAD binary (requires OpenSCAD to be installed on your computer) Note: This icon will initially not appear (even if OpenSCAD is installed on your computer), you must also configure FreeCAD. [See here for more details] M esh Boolean...:

Hull: M inkowski:

Limitations OpenSCAD creates constructive solid geometry as well as importing mesh files and extruding 2d geometry (from dxf files). FreeCAD allows you to create CSG with primitives as well. The FreeCAD geometry kernel (OCCT) works using a boundary representation. Therefore conversion from CSG to BREP should, in theory, be possible whereas conversion from BREP to CSG is, in general, not. OpenSCAD works internaly on meshes. Some operations which are useful on meshes are not meaningful on a BREP model and can not be fully supported. Among these are convex hull, minkowski sum, glide and subdiv. Currently we run the OpenSCAD binary in order to perform hull and minkwoski operations and import the result. This means that the involved geometry will be triangulated. In OpenSCAD non-uniform scaling is often used, which does not impose any problems when using meshes. In our geometry kernel geometric primitives (lines, circular sections, etc) are converted to BSpline prior to performing such deformations. Those BSplines are known to cause trouble in later boolean operations. An automatic solution is not available at the moment. Please feel free to post to the forum if you encounter such problems. Often such problems can be solved be remodeling small parts. A deformation of a cylinder can substituted by an extrusion of an ellipses.

Hints When importing DXF set the Draft precision to a sensible amount as this will affect the detection of connected edges. If FreeCAD crashes when importing CSG, it is strongly recommended that you enable 'automatically check model after boolean operation' in Menu -> Edit -> Preferences -> Part Design -> Model setting

Links Things tagged with "Openscad" on Thingiverse

OpenSCAD AddOpenSCADElement Description Add an OpenSCAD element by entering OpenSCAD code into the task panel and executing the OpenSCAD binary (requires OpenSCAD) When 'as mesh' is selected, OpenSCAD renders a Mesh. Each time Add is pressed the OpenSCAD code is executed and elements are imported. If OpenSCAD returns successfully, its messages are displayed as warnings in the report window. This will be the case if the path to imported, included and used files is broken. In case of undesired results it is highly recommend to have a look at the report windows, as there might be a lot of other output, created by the importer. If OpenSCAD fails, its messages will be loged as errors. Libraries should be accessible as usual, whereas example can be reached as stated below

OpenSCAD AddOpenSCADElement M enu location OpenSCAD -> Add OpenSCAD Element Workbenches OpenSCAD Default shortcut None See also None

include <../examples/example001.scad>;

would include the first examples also known as the OpenSCAD icon Initial set up from within FreeCAD OpenSCAD needs to be installed on your computer before FreeCAD will have this functionality install OpenSCAD in the appropriate manner for your operating system. See the OpenSCAD web site for more information FreeCAD needs to be told where to find the OpenSCAD executable Switch to the OpenSCAD Workbench Menu -> View Workbench -> OpenSCAD Open the preferences dialog Menu -> Edit -> Preferences Click on "OpenSCAD" on the left plane Click on the button labled "..." in General Settings -> General OpenSCAD Settings -> OpenSCAD executable to browser the directory or enter the path (e.g. Ubuntu based Linux distributions /usr/bin/openscad) directly into the line input right to the button close and restart FreeCAD, a new OpenSCAD icon will appear on the tool bar, and in the OpenSCAD menu, in the FreeCAD OpenSCAD workbench It is also possible to add another optional Parameter which controls the maximum sides of a polygon before it is considered a circle (fn). Starting from FreeCAD Version 0.14, FreeCAD will search for the OpenSCAD executable if the setting mentioned above is empty.

Fem Workbench The Fem Workbench offers data structures and commands to work with Fem meshes.

[0.14] The FEM-Module is only available with the Windows-Versions of FreeCAD. Linux-Versions would need further work for implementation. The FEM-Module supports linear analysis of isotropic (uniformity in all directions) material. Mechanical analysis with calculation of resulting stress (v.-Mises) and displacement is supported. [0.14] The FEM-module supports analysis of single parts (solids). Multi-body analysis is not implemented yet.

Creating or importing meshes/parts [0.14] Only parts created within the Part M odule are suppported. Parts from Part Design-Workbench or imported parts or simple copies are not yet supported

GUI Tools Create FEM mesh: Opens the meshing dialog. Either select on of the predefined profiles or choose own values. M echanical material...: Lets you select a material from the database [0.14] Only PLA is accepted.

New mechanical analysis: Creates a new static mechanical analysis. If solid (in tree view) is selected before clicking on it the meshing dialog will be opened next. Start calculation: Opens Menu to start the Calculix-Solver. Define/create a nodes set: Creates/defines a node set. [0.14] Not implemented yet. Create FEM fixed constraint: To define a fixed constraint on point/edge/face(s) Create FEM force constraint: To define a force in [N] applied uniform to a selectable face in definable direction. Create FEM bearing constraint: To define a bearing constraint.

Create FEM gear constraint: To define a gear constraint. Create FEM pulley constraint: To define a pulley constraint. Show result: To display the result of the study (v.-Mises-Stress or displacement)

Import/Export Python scripting Creating FEM-meshes "by hand" creation of FEM -meshes Creating a mesh with one Tet-10 Elements:

import FreeCAD, Fem # create a empty mesh m = Fem.FemMesh() #create the nodes m.addNode(0,1,0) m.addNode(0,0,1) m.addNode(1,0,0) m.addNode(0,0,0) m.addNode(0,0.5,0.5) m.addNode(0.5,0.03,.5) m.addNode(0.5,0.5,0.03) m.addNode(0,0.5,0) m.addNode(0.03,0,0.5) m.addNode(0.5,0,0) # add the volume with the created nodes m.addVolume([1,2,3,4,5,6,7,8,9,10]) Fem.show(m)

If you want to have predefined element and node numbering:

m.addNode(0.0,1.0,0.0,1) m.addVolume([1,2,3,4,5,6,7,8,9,10],1)

Visual handling Highlight some nodes on the view:

import FreeCAD, Fem m = Fem.FemMesh() m.addNode(0,1,0) m.addNode(0,0,1) m.addNode(1,0,0) m.addNode(0,0,0) m.addNode(0,0.5,0.5) m.addNode(0.5,0.03,.5) m.addNode(0.5,0.5,0.03) m.addNode(0,0.5,0) m.addNode(0.03,0,0.5) m.addNode(0.5,0,0) m.addVolume([1,2,3,4,5,6,7,8,9,10]) Fem.show(m) Gui.ActiveDocument.ActiveObject.HighlightedNodes = [1,2,3]

Postprocessing colors and displacement: Highlight some nodes on the view:

# set the volume 1 to red Gui.ActiveDocument.ActiveObject.ElementColor= {1:(1,0,0)} # set the node 1 and 2 to a certain Color and interpolate the survace Gui.ActiveDocument.ActiveObject.NodeColor= {1:(1,0,0),2:(1,0,0)} # set the node 1 and 2 to a certain displacement Gui.ActiveDocument.ActiveObject.NodeDisplacement= {1:FreeCAD.Vector(1,0,0),2:FreeCAD.Vector(1,0,0)} # double the factor of the displacement shown Gui.ActiveDocument.ActiveObject.animate(2.0)

Element Types This description is based on the MED format as described here.

Segment element

Triangle element

Quadratic element

Tetrahedron element

Tetrahedron with four or ten nodes Edge Node 1 Node 2 Middle node A1

N10

Tetrahedron Faces

Tetrahedron Faces Face Edge 1 Edge 2 Edge 3 F1

-A5

-A1

-A6

-A2

-A4

-A3

Pyramid element

Hexahedron element

Hexahedron with eight or twenty nodes Edge Node 1 Node 2 Middle node A1

N10

N11

N12

N13

N14

N15

N16

N17

A10

N18

A11

N19

A12

N20

Hexahedron faces Face Edge 1 Edge 2 Edge 3 Edge 4 F1

-A8

-A7

-A6

-A5

-A10

-A1

A10

-A11

-A2

A11

-A12

-A3

A12

-A9

-A4

Pentahedron element

Example See FEM Analysis

FEM Analysis FEM Analysis

Basic Analysis

M enu location FEM → New mechanical analysis

Units

Workbenches FEM Default shortcut A See also

Units Length Time

Mass

Force

Pressure

Velocity

Density

Energy

Gravity

kg m/s2

N/m2

m/s

kg/m3

kgm2/s2 9.81

m/s

m kg/l

mPa

m/s

micro kg/l mJ

9.81

Mg (ton)

kPa

m/s

kg/l

9.81

MPa

km/s

m kg/l

9.81e-6

kPa

km/s

micro kg/l kJ

9.81e-6

Mg (ton)

GPa

km/s

kg/l

9.81e-6

kPa

mm/s

M kg/l

micro J

9.81e+3

micro N

mm/s

g/mm3

9.81e+3

Mg (ton)

MPa

mm/s

Mg/mm3

9.81e+3

GPa

m/s

kg/l J

9.81e-3

MPa

m/s

k kg/l

9.81e-3

Mg (ton)

TPa

m/s

G kg/l

9.81e-3

daN

10^5 Pa (bar)

dam/s

kg/l

9.81e-4

10^4 N (kdaN) 10^8 Pa (kbar)

dam/s

k kg/l

9.81e-4

Mg (ton) 10^7 N(MdaN)

M kg/l

10^5 J

9.81e-4

10^11 Pa (Mbar) dam/s

Procedure The following steps detail how to perform analysis on a basic cube. Select Part Workbench

9.81

FEM Analysis (1).png

Create a Cube FEM Analysis(2).png

Highlight the Cube in the selection tree and select the data tab to check the dimensions FEM Analysis(3).png

Switch to the FEM Workbench

FEM Analysis(4).png

Plot Module The Plot module allows to edit and save output plots created from other modules and tools. With plot module you can edit easily the working area, the axes, labels, titles, styles, etc. Plot module is an abstraction of matplotlib conveniently addapted to FreeCAD.

Tools These are tools availables. Save plot: Saves the plot in several formats. You can select the output size and resolution too. Axes: Add, remove or edit plot axes. Series: Edit series title and styling. Grid: Show/hide grid. Legend: Show/hide legend. Labels: Edit labels. Positions: Set elements positions.

Scripting Since Plot module is a layer over matplotlib, you are free to use all matplotlib commands over plot instances. See scripting examples section to see examples.

Tutorial Plot Basic tutorial Plot M ultiAxes tutorial

Plot Save Description Plot save tool saves the active plot at desired location. With this tool you can also select the size and resolution of output image.

Plot Save M enu location Plot â&#x2020;&#x2019; Save plot Workbenches Plot Default shortcut None See also None

How to use Select the plot tab that you want to save, and run this tool. Use path selector button in order to show a file dialog where you can choose the output image place and format. PAT H SELECT ION BUT T ON

Options File path: You can set the output image path (including format extension) inserting it at text line too. Size: You can specify output image width and height (inches). dpi: You can set the image resolution (Dots Per Inch). Final resolution (in pixels) will be the multiplication of width and height by dpi.

Scripting Plot save tool can be used in macros and from Python console by using the following function: save(str, (float, float), float) : Saves the plot at path, width the size specified in inches, and the resolution specified in Dots Per Inch. Example: import Plot Plot.save("~/example.pdf", (12.8, 9.6), 50) That will save a pdf image of 12.8x9.6 inches, with 640x480 pixels.

Plot Basic tutorial In this tutorial we will learn how to perform a basic plot using Plot module and Python console. You can learn more about Plot module here.

BASIC PLOT EXAMPLE . In previous image you can see the result that we aproximately will obtain. Following this tutorial you will learn: How to create a Plot from Python Console. How to plot some data from Python Console. How to show the grid lines. How to show the legend. How to edit series labels, introducing text in LaTeX. How to edit axes labels, introducing text in LaTeX. How to edit series styles. How to save your plot.

Plotting data In order to plot data you don't need to create a new FreeCAD document, simply show the Python console and start sending commands, or use macros.

Creating plot document Plots are special documents that can be created manually in order to add data later, or allow the module creates one authomatically when you start plotting data. Create your own plot documents have 2 advantages: You can set the document window label. You can control easily on wich document you plot your data. In order to create new plot document simply launch following commands:

import Plot Plot.figure("TrigonometricTest")

That will create a new tab on main windows called TrigonometricTest. The new created document already have a set of axes. Each plot document have at least one set of axes that can be removed without using fully matplotlib control.

Drawing functions You can start working here due to plot command will start a new document, but all plot commands that you execute will append series to created plot until you don't create a new document, so ussually is better options control the opened plot documents. First thing that we need to do is create the data for sine and cosine functions that we want to plot:

import math t = range(0,101) t = [tt/100.0 for tt in t] s = [math.sin(2.0*math.pi*tt) for tt in t] c = [math.cos(2.0*math.pi*tt) for tt in t]

That will create 3 arrays of data (with 101 points):

t = Time in seconds. s = Sine function. c = Cosine function. In order to plot both function we only need to launch next commands:

Plot.plot(t,s) Plot.plot(t,c)

That will plot our functions. plot command allows the series label as argument, but since we will edit it later using Plot module tools we don't pass this data yet.

Configuring plot Showing grid and legend Change FreeCAD workbench to Plot module in View/Workbench menu. When module has been loaded use grid tool in order to show it.

SHOW/HIDE GRID T OOL ICON. You can repeat the action in order to hide it. Also you can show the legend with the tool provided.

SHOW/HIDE LEGEND T OOL ICON. As you can see, legend is empty because we have not set any series label yet. In Plot module series without label are not represented at legend, in order to allow you to draw auxiliar lines.

Setting series labels With the series tool you can edit some series parameters.

SERIES CONFIGURAT ION T OOL ICON. First for all select the line that you want to edit, for example we will start with the first one. Uncheck No label and set this label:

$y = \sin \left( 2 \pi t \right)$

Since matplotlib supports LaTeX you can set all the labels or titles that you want using it. Set the following label to second serie:

$y = \cos \left( 2 \pi t \right)$

Setting series style Series allows you to set a lot of series properties. Try to set the properties shown at the example image, changing series colors and drawing style of the second one.

Setting axes labels With the labels tool you can set labels associated to all created axes.

LABELS T OOL ICON. Set this data: Title = Trigonometric functions example X Label = $t$ Y Label = $y = \mathrm{f} \left( t \right)$ Also change the size of all of them to 20.

Saving plot With saving plot tool you can save your plot as image file in several formats.

SAVE T OOL ICON. First for all select the path of the output file. You can use file selection dialog using the button at right of the path edition line. You can set the output image size in inches, for example we can set 11.7x8.3 that is a DIN A4 paper size. DPI (Dots per inch) will control the image resolution, for example using 100 dpi you will get an image of 1170x830 pixels.

Plot MultiAxes tutorial Ensure to visit basic tutorial before starting with this tutorial. In this tutorial we will learn how to create and edit a multiaxes plot. You can learn more about Plot module here.

MULT IAXES PLOT EXAMPLE . In previous image you can see the result that we aproximately will obtain. Following this tutorial you will learn: How to create a multiaxes Plot from Python Console. How to edit axes properties. How to control grid/legend when several axes is present. How to edit labels, titles and legend positions.

Plotting data As we did in previous tutorial we will use the Python console or macros in order to plot the data, with the difference that in this case we will plot the data in two different axes.

Creating plot data In this example we will plot 3 functions, the two ones used in previous tutorial, and another polynomial one. The fact is that the polynomial one will need new axes due to the variation range is different from all others. Next commands will create data arrays for us:

import math p = range(0,1001) x = [2.0*xx/1000.0 for xx in p] y = [xx**2.0 for xx in x] t = [tt/1000.0 for tt in p] s = [math.sin(math.pi*2.0*tt) for tt in t] c = [math.cos(math.pi*2.0*tt) for tt in t]

As x moves from 0 to 2, y function has a maximum value of 4, so if we try to plot this function with trigonometrical ones, at least one function will be truncated or bad scaled, then we need a multiaxes plot. Multiaxes plot in FreeCAD is oriented to get a plot with multiple axes, not to get multiple plots in same document.

Drawing functions, adding new axes We will draw polynomial function at main axes. If all your axes will have same size then is not relevant what function is ploted in what axes, but if your plot has axes with other size (as in this example), main axes must be the biggest one (because this axes have the white background). In order to do it we only need to launch a command

import Plot Plot.plot(x,y,r"$x^2$")

In this example we pass directly the series label for the legend. Note that the label string has the r prefix in order to avoid Python try to interpret special characters (\ symbol is used frecuently in LaTeX syntax). Now we can plot trigonometrical functions, creating new axes before. In FreeCAD Plot module when you create new axes this axes are selected as active ones, so new plots will be associated to this axes.

Plot.addNewAxes() Plot.plot(t,s,r"$\sin\left( 2 \pi t \right)$")

Plot.plot(t,c,r"$\cos\left( 2 \pi t \right)$")

As you can see you plot has gone crazy, with axes ticks overlaped, curves of same color, etc. Now we needs to use FreeCAD Plot module to fix this graph.

Configuring plot Configuring axes FreeCAD Plot module provides a tool in order to modify the properties of each axes.

AXES CONFIGURAT ION T OOL ICON. The first thing that you can find in axes tool is the active axes selector. Since the active axes are the last one, active axes is placed at one. The axes tool, as labels tool, allows to set the active axes, allowing you to plot more data in the axes that you want (including add/remove axes). For the moment we will work over the selected axes, that are the associated to trigonometrical functions. In the dimensions sliders, we will move left horizontal and bottom vertical sliders (try to emulate example) in order to reduce axes size. Then we can set the axes alignement, changing it to top and right, and setting and small offset of two units.

Configuring series Set series properties as we did in previous tutorial.

Showing grid and legend Grid and legend is shown and hide with the same tools that used in previous tutorial, but in this case the behaviour is a little bit different due to the presence of two different axes. Regarding grid lines, you can show lines for each axes set, for example, if you try to show grid now you will show only the grid of the trigonometrical functions, so in order to show the grid of polynomial function plot you needs to change active axes to 0 (using axes configuration tool) before using grid tool another time (Is possible that you need to press two times the tool). Regarding legend, the legend will be the same for both axes, so you can choose the axes that you want in order to show the legend, but is strongly recommended to use the biggest ones (0 in this example) because position will be refered to this axes coordinates. If you show the legend you can see that is really bad placed, we will fix this problem later.

Setting axes labels You can set axes labels with same tool used in previous tutorial, with the difference that now you have more axes. Since axes labels is ussually set as one per axis, is not a significant difference, but FreeCAD Plot module allow you to set a title by axes too. In this case we only wants to set title to main axes, so set: Axes 0: Title = Multiaxes example X Label = $x$ Y Label = $\mathrm{f} \left( x \right)$ Axes 1: X Label = $t$ Y Label = $\mathrm{f} \left( t \right)$ Set also 20 to fontsize for all but title, that uses a fontsize of 24. As happens with legend, title is bad placed, interseting with second axes set, so we need to solve both problems.

Setting elements position

FreeCAD Plot module provides a tool in order to set the position of several plot elements, as titles, labels or legend.

POSIT ION EDIT OR ICON. When you run the tool you see a list with all the editable elements. Title elements, as well as legend, can be moved in both directions, since axes labels can be moved only on the axes direction. Select title of axes 0 and move it to (0.24,1.01), then select legend and move it to a better position. You can increase legend labels fontsize too.

Saving plot Now you can save your work. See previous tutorial if you don't remeber how to do it.

Mesh Workbench The M esh Workbench handles triangle meshes. Meshes are a special type of 3D object, composed of triangles conected by their edges and their corners (also called vertices).

An example of a mesh object Many 3D applications use meshes as their primary type of 3D object, like sketchup, blender, maya or 3d studio max. Since meshes are very simple objects, containing only vertices (points), edges and (triangular) faces, they are very easy to create, modify, subdivide, stretch, and can easily be passed from one application to another without any loss. Besides, since they contain very simple data, 3D applications can usually manage very large quantities of them without any problem. For those reasons, meshes are often the 3D object type of choice for applications dealing with movies, animation, and image creation. In the field of engineering, however, meshes present one big limitation: They are very dumb objects, only composed of points,lines and faces. They are only made of surfaces, and have no mass information, so they don't behave as solids. In a mesh there is no automatic way to know if a point is inside or outside the object. This means that all solid-based operations, such as addition or subtraction, are always a bit difficult to perform on meshes, and return errors often. In FreeCAD, since it is an engineering application, we would obviously prefer to work with more intelligent types of 3D objects, that can carry more informations, such as mass, solid behaviour, or even custom parameters. The mesh module was first created to serve as a testbed, but to be able to read, manipulate and convert meshes is also highly important for FreeCAD. Very often, in your workflow, you will receive 3D data in mesh format. You will need to handle that data, analyse it to detect errors or other problems that prevent converting them to more intelligent objects, and finally, convert them to more intelligent objects, handled by the Part M odule.

Using the mesh module The mesh module has currently a very simple interface, all its functions are grouped in the M esh menu entry. The most important operations you can currently do with meshes are: Import meshes in several file formats Export meshes in several file formats Convert Part objects into meshes Harmonize normals Flip normals Close holes in meshes Remove components of meshes Cut meshes along a line Analyse curvature, faces, and check if a mesh can be safely converted into a solid

Regular solid... Create mesh primitives, like cubes, cylinders, cones, or spheres: Create a mesh cube Create a mesh cylinder Create a mesh cone Create a mesh sphere Create a mesh ellipsoid Create a mesh torus

Union, subtract and intersect meshes These are only some of the basic operations currently present in the Mesh module interface. But the FreeCAD meshes can also be handled in many more ways by scripting.

Macros Macros are a convenient way to create complex actions in FreeCAD. You simply record actions as you do them, then save that under a name, and replay them whenever you want. Since macros are in reality a list of python commands, you can also edit them, and create very complex scripts.

How it works If you enable console output (Menu Edit -> Preferences -> General -> Macros -> Show scripts commands in python console), you will see that in FreeCAD, every action you do, such as pressing a button, outputs a python command. Thos commands are what can be recorded in a macro. The main tool for making macros is the macros toolbar: have 4 buttons: Record, stop recording, edit and play the current macro.

. On it you

It is very simple to use: Press the record button, you will be asked to give a name to your macro, then perform some actions. When you are done, click the stop recording button, and your actions will be saved. You can now access the macro dialog with the edit button:

There you can manage your macros, delete, edit or create new ones from scratch. If you edit a macro, it will be opened in an editor window where you can make changes to its code.

Example Press the record button, give a name, let's say "cylinder 10x10", then, in the Part Workbench, create a cylinder with radius = 10 and height = 10. Then, press the "stop recording" button. In the edit macros dialog, you can see the python code that has been recorded, and, if you want, make alterations to it. To execute your macro, simply press the execute button on the toolbar while your macro is in the editor. You macro is always saved to disk, so any change you make, or any new macro you create, will always be available next time you start FreeCAD.

Customizing Of course it is not practical to load a macro in the editor in order to use it. FreeCAD provides much better ways to use your macro, such as assigning a keyboard shortcut to it or putting an entry in the menu. Once your macro is created, all this can be done via the Tools -> Customize menu:

Customize ToolsBar This way you can make your macro become a real tool, just like any standard FreeCAD tool. This, added to the power of python scripting within FreeCAD, makes it possible to easily add your own tools to the interface. Read on to the

Scripting page if you want to know more about python scripting...

Creating macros without recording You can also directly copy/paste python code into a macro, without recording GUI action. Simply create a new macro, edit it, and paste your code. You can then save your macro the same way as you save a FreeCAD document. Next time you start FreeCAD, the macro will appear under the "Installed Macros" item of the Macro menu.

Macros repository Visit the M acros recipes page to pick some useful macros to add to your FreeCAD installation.

Introduction to Python This is a short tutorial made for who is totally new to Python. Python is an open-source, multiplatform programming language. Python has several features that make it very different than other common programming languages, and very accessible to new users like yourself: It has been designed specially to be easy to read by human beings, and so it is very easy to learn and understand. It is interpreted, that is, unlike compiled languages like C, your program doesn't need to be compiled before it is executed. The code you write can be immediately executed, line by line if you want so. This makes it extremely easy to learn and to find errors in your code, because you go slowly, step-by-step. It can be embedded in other programs to be used as scripting language. FreeCAD has an embedded Python interpreter, so you can write Python code in FreeCAD, that will manipulate parts of FreeCAD, for example to create geometry. This is extremely powerful, because instead of just clicking a button labeled "create sphere", that a programmer has placed there for you, you have the freedom to create easily your own tool to create exactly the geometry you want. It is extensible, you can easily plug new modules in your Python installation and extend its functionality. For example, you have modules that allow Python to read and write jpg images, to communicate with twitter, to schedule tasks to be performed by your operating system, etc. So, hands on! Be aware that what will come next is a very simple introduction, by no means a complete tutorial. But my hope is that after that you'll get enough basics to explore deeper into the FreeCAD mechanisms.

The interpreter Usually, when writing computer programs, you simply open a text editor or your special programming environment which is in most case a text editor with several tools around it, write your program, then compile it and execute it. Most of the time you made errors while writing, so your program won't work, and you will get an error message telling you what went wrong. Then you go back to your text editor, correct the mistakes, run again, and so on until your program works fine. That whole process, in Python, can be done transparently inside the Python interpreter. The interpreter is a Python window with a command prompt, where you can simply type Python code. If you install Python on your computer (download it from the Python website if you are on Windows or Mac, install it from your package repository if you are on GNU/Linux), you will have a Python interpreter in your start menu. But FreeCAD also has a Python interpreter in its bottom part:

(If you don't have it, click on View ? Views ? Python console.) The interpreter shows the Python version, then a >>> symbol, which is the command prompt, that is, where you enter Python code. Writing code in the interpreter is simple: one line is one instruction. When you press Enter, your line of code will be executed (after being instantly and invisibly compiled). For example, try writing this: print "hello" print is a special Python keyword that means, obviously, to print something on the screen. When you press Enter, the operation is executed, and the message "hello" is printed. If you make an error, for example let's write: print hello Python will tell us that it doesn't know what hello is. The " characters specify that the content is a string, which is simply, in programming jargon, a piece of text. Without the ", the print command believed hello was not a piece of text but a special Python keyword. The important thing is, you immediately get notified that you made an error. By pressing the up arrow (or, in the FreeCAD interpreter, CTRL+up arrow), you can go back to the last command you wrote and correct it. The Python interpreter also has a built-in help system. Try typing: help or, for example, let's say we don't understand what went wrong with our print hello command above, we want specific information about the "print" command: help("print") You'll get a long and complete description of everything the print command can do. Now we dominate totally our interpreter, we can begin with serious stuff.

Variables Of course, printing "hello" is not very interesting. More interesting is printing stuff you don't know before, or let Python find for you. That's where the concept of variable comes in. A variable is simply a value that you store under a name. For example, type this: a = "hello" print a I guess you understood what happened, we "saved" the string "hello" under the name a. Now, a is not an unknown name anymore! We can use it anywhere, for example in the print command. We can use any name we want, just respecting simple rules, like not using spaces or punctuation. For example, we could very well write: hello = "my own version of hello" print hello See? now hello is not an undefined word anymore. What if, by terrible bad luck, we choosed a name that already exists in Python? Let's say we want to store our string under the name "print": print = "hello" Python is very intelligent and will tell us that this is not possible. It has some "reserved" keywords that cannot be modified. But our own variables can be modified anytime, that's exactly why they are called variables, the contents can vary. For example: myVariable = "hello" print myVariable myVariable = "good bye" print myVariable We changed the value of myVariable. We can also copy variables: var1 = "hello" var2 = var1 print var2 Note that it is interesting to give good names to your variables, because when you'll write long programs, after a while you won't remember what your variable named "a" is for. But if you named it for example myWelcomeMessage, you'll remember easily what it is used for when you'll see it.

Numbers Of course you must know that programming is useful to treat all kind of data, and especially numbers, not only text strings. One thing is important, Python must know what kind of data it is dealing with. We saw in our print hello example, that the print command recognized our "hello" string. That is because by using the ", we told specifically the print command that what it would come next is a text string. We can always check what data type is the contents of a variable with the special Python keyword type: myVar = "hello" type(myVar) It will tell us the contents of myVar is 'str', or string in Python jargon. We have also other basic types of data, such as integer and float numbers: firstNumber = 10 secondNumber = 20 print firstNumber + secondNumber type(firstNumber) This is already much more interesting, isn't it? Now we already have a powerful calculator! Look well at how it worked, Python knows that 10 and 20 are integer numbers. So they are stored as "int", and Python can do with them everything it can do with integers. Look at the results of this: firstNumber = "10" secondNumber = "20" print firstNumber + secondNumber See? We forced Python to consider that our two variables are not numbers but mere pieces of text. Python can add two pieces of text together, but it won't try to find out any sum. But we were talking about integer numbers. There are also float numbers. The difference is that integer numbers don't have decimal part, while foat numbers can have a decimal part: var1 = 13 var2 = 15.65 print "var1 is of type ", type(var1) print "var2 is of type ", type(var2) Int and Floats can be mixed together without problem:

total = var1 + var2 print total print type(total) Of course the total has decimals, right? Then Python automatically decided that the result is a float. In several cases such as this one, Python automatically decides what type to give to something. In other cases it doesn't. For example: varA = "hello 123" varB = 456 print varA + varB This will give us an error, varA is a string and varB is an int, and Python doesn't know what to do. But we can force Python to convert between types: varA = "hello" varB = 123 print varA + str(varB) Now both are strings, the operation works! Note that we "stringified" varB at the time of printing, but we didn't change varB itself. If we wanted to turn varB permanently into a string, we would need to do this: varB = str(varB) We can also use int() and float() to convert to int and float if we want: varA = "123" print int(varA) print float(varA) Note on Python commands You must have noticed that in this section we used the print command in several ways. We printed variables, sums, several things separated by commas, and even the result of other Python command such as type(). Maybe you also saw that doing those two commands: type(varA) print type(varA) have exactly the same result. That is because we are in the interpreter, and everything is automatically printed on screen. When we'll write more complex programs that run outside the interpreter, they won't print automatically everything on screen, so we'll need to use the print command. But from now on, let's stop using it here, it'll go faster. So we can simply write: myVar = "hello friends" myVar You must also have seen that most of the Python commands (or keywords) we already know have parenthesis used to tell them on what contents the command must work: type(), int(), str(), etc. Only exception is the print command, which in fact is not an exception, it also works normally like this: print("hello"), but, since it is used often, the Python programmers made a simplified version.

Lists Another interesting data type is lists. A list is simply a list of other data. The same way as we define a text string by using " ", we define lists by using [ ]: myList = [1,2,3] type(myList) myOtherList = ["Bart", "Frank", "Bob"] myMixedList = ["hello", 345, 34.567] You see that it can contain any type of data. Lists are very useful because you can group variables together. You can then do all kind of things within that groups, for example counting them: len(myOtherList) or retrieving one item of a list: myName = myOtherList[0] myFriendsName = myOtherList[1] You see that while the len() command returns the total number of items in a list, their "position" in the list begins with 0. The first item in a list is always at position 0, so in our myOtherList, "Bob" will be at position 2. We can do much more stuff with lists such as you can read here, such as sorting contents, removing or adding elements. A funny and interesting thing for you: a text string is very similar to a list of characters! Try doing this: myvar = "hello" len(myvar) myvar[2]

Usually all you can do with lists can also be done with strings. In fact both lists and strings are sequences. Outside strings, ints, floats and lists, there are more built-in data types, such as dictionnaries, or you can even create your own data types with classes.

Indentation One big cool use of lists is also browsing through them and do something with each item. For example look at this: alldaltons = ["Joe", "William", "Jack", "Averell"] for dalton in alldaltons: print dalton + " Dalton" We iterated (programming jargon again!) through our list with the "for ... in ..." command and did something with each of the items. Note the special syntax: the for command terminates with : which indicates that what will comes after will be a block of one of more commands. Immediately after you enter the command line ending with :, the command prompt will change to ... which means Python knows that a :-ended line has happened and that what will come next will be part of it. How will Python know how many of the next lines will be to be executed inside the for...in operation? For that, Python uses indentation. That is, your next lines won't begin immediately. You will begin them with a blank space, or several blank spaces, or a tab, or several tabs. Other programming languages use other methods, like putting everythin inside parenthesis, etc. As long as you write your next lines with the same indentation, they will be considered part of the for-in block. If you begin one line with 2 spaces and the next one with 4, there will be an error. When you finished, just write another line without indentation, or simply press Enter to come back from the for-in block Indentation is cool because if you make big ones (for example use tabs instead of spaces because it's larger), when you write a big program you'll have a clear view of what is executed inside what. We'll see that many other commands than for-in can have indented blocks of code too. For-in commands can be used for many things that must be done more than once. It can for example be combined with the range() command: serie = range(1,11) total = 0 print "sum" for number in serie: print number total = total + number print "----" print total Or more complex things like this: alldaltons = ["Joe", "William", "Jack", "Averell"] for n in range(4): print alldaltons[n], " is Dalton number ", n You see that the range() command also has that strange particularity that it begins with 0 (if you don't specify the starting number) and that its last number will be one less than the ending number you specify. That is, of course, so it works well with other Python commands. For example: alldaltons = ["Joe", "William", "Jack", "Averell"] total = len(alldaltons) for n in range(total): print alldaltons[n] Another interesting use of indented blocks is with the if command. If executes a code block only if a certain condition is met, for example: alldaltons = ["Joe", "William", "Jack", "Averell"] if "Joe" in alldaltons: print "We found that Dalton!!!" Of course this will always print the first sentence, but try replacing the second line by: if "Lucky" in alldaltons: Then nothing is printed. We can also specify an else: statement: alldaltons = ["Joe", "William", "Jack", "Averell"] if "Lucky" in alldaltons: print "We found that Dalton!!!" else: print "Such Dalton doesn't exist!"

Functions The standard Python commands are not many. In current version of Python there are about 30, and we already know several of them. But imagine if we could invent our own commands? Well, we can, and it's extremely easy. In fact, most the

additional modules that you can plug into your Python installation do just that, they add commands that you can use. A custom command in Python is called a function and is made like this: def printsqm(myValue): print str(myValue)+" square meters" printsqm(45) Extremely simple: the def() command defines a new function. You give it a name, and inside the parenthesis you define arguments that we'll use in our function. Arguments are data that will be passed to the function. For example, look at the len() command. If you just write len() alone, Python will tell you it needs an argument. That is, you want len() of something, right? Then, for example, you'll write len(myList) and you'll get the length of myList. Well, myList is an argument that you pass to the len() function. The len() function is defined in such a way that it knows what to do with what is passed to it. Same as we did here. The "myValue" name can be anything, and it will be used only inside the function. It is just a name you give to the argument so you can do something with it, but it also serves so the function knows how many arguments to expect. For example, if you do this: printsqm(45,34) There will be an error. Our function was programmed to receive just one argument, but it received two, 45 and 34. We could instead do something like this: def sum(val1,val2): total = val1 + val2 return total sum(45,34) myTotal = sum(45,34) We made a function that receives two arguments, sums them, and returns that value. Returning something is very useful, because we can do something with the result, such as store it in the myTotal variable. Of course, since we are in the interpreter and everything is printed, doing: sum(45,34) will print the result on the screen, but outside the interpreter, since there is no more print command inside the function, nothing would appear on the screen. You would need to do: print sum(45,34) to have something printed. Read more about functions here.

Modules Now that we have a good idea of how Python works, we'll need one last thing: How to work with files and modules. Until now, we wrote Python instructions line by line in the interpreter, right? What if we could write several lines together, and have them executed all at once? It would certainly be handier for doing more complex things. And we could save our work too. Well, that too, is extremely easy. Simply open a text editor (such as the windows notepad), and write all your Python lines, the same way as you write them in the interpreter, with indentations, etc. Then, save that file somewhere, preferably with a .py extension. That's it, you have a complete Python program. Of course, there are much better editors than notepad, but it is just to show you that a Python program is nothing else than a text file. To make Python execute that program, there are hundreds of ways. In windows, simply right-click your file, open it with Python, and execute it. But you can also execute it from the Python interpreter itself. For this, the interpreter must know where your .py program is. In FreeCAD, the easiest way is to place your program in a place that FreeCAD's Python interpreter knows by default, such as FreeCAD's bin folder, or any of the Mod folders. Suppose we write a file like this: def sum(a,b): return a + b print "test.py succesfully loaded" and we save it as test.py in our FreeCAD/bin directory. Now, let's start FreeCAD, and in the interpreter window, write: import test without the .py extension. This will simply execute the contents of the file, line by line, just as if we had written it in the interpreter. The sum function will be created, and the message will be printed. There is one big difference: the import command is made not only to execute programs written in files, like ours, but also to load the functions inside, so they become available in the interpreter. Files containing functions, like ours, are called modules. Normally when we write a sum() function in the interpreter, we execute it simply like that: sum(14,45) Like we did earlier. When we import a module containing our sum() function, the syntax is a bit different. We do:

test.sum(14,45) That is, the module is imported as a "container", and all its functions are inside. This is extremely useful, because we can import a lot of modules, and keep everything well organized. So, basically, everywhere you see something.somethingElse, with a dot in between, that means somethingElse is inside something. We can also throw out the test part, and import our sum() function directly into the main interpreter space, like this: from test import * sum(12,54) Basically all modules behave like that. You import a module, then you can use its functions like that: module.function(argument). Almost all modules do that: they define functions, new data types and classes that you can use in the interpreter or in your own Python modules, because nothing prevents you to import modules inside your module! One last extremely useful thing. How do we know what modules we have, what functions are inside and how to use them (that is, what kind of arguments they need)? We saw already that Python has a help() function. Doing: help() modules Will give us a list of all available modules. We can now type q to get out of the interactive help, and import any of them. We can even browse their content with the dir() command import math dir(math) We'll see all the functions contained in the math module, as well as strange stuff named __doc__, __file__, __name__. The __doc__ is extremely useful, it is a documentation text. Every function of (well-made) modules has a __doc__ that explains how to use it. For example, we see that there is a sin function in side the math module. Want to know how to use it? print math.sin.__doc__ And finally one last little goodie: When we work on programming a new module, we often want to test it. So once we wrote a little piece of module, in a python interpreter, we do something like this, to test our new code: import myModule myModule.myTestFunction() But what if we see that myTestFunction() doesn't work correctly? We go back to our editor and modifiy it. Then, instead of closing and reopening the python interpreter, we can simply update the module like this: reload(myModule)

Starting with FreeCAD Well, I think you must know have a good idea of how Python works, and you can start exploring what FreeCAD has to offer. FreeCAD's Python functions are all well organized in different modules. Some of them are already loaded (imported) when you start FreeCAD. So, just do dir() and read on to FreeCAD Scripting Basics... Of course, we saw here only a very small part of the Python world. There are many important concepts that we didn't mention here. There are three very important Python reference documents on the net: the official Python tutorial with way more information than this one the official Python reference the Dive into Python wikibook/ book. Be sure to bookmark them!

Python scripting tutorial Python is a programming language, very simple to use and very fast to learn. It is open-source, multi-platform, and can be used alone for a wide array of things, from programming simple shell scripts to very complex programs. But one of its most widespread uses is as a scripting language, since it is easy to embed in other applications. That's exactly how it is used inside FreeCAD. From the python console, or from your custom scripts, you can pilot FreeCAD, and make it perform very complex actions for which there is still no graphical user interface tool. For example, from a python script, you can: create new objects modify existing objects modify the 3D representation of those objects modify the FreeCAD interface There are also several different ways to use python in FreeCAD: From the FreeCAD python interpreter, where you can issue simple commands like in a "command line"-style interface From macros, which are a convenient way to quickly add a missing tool to the FreeCAD interface From external scripts, which can be used to program much more complex things. like entire Workbenches. In this tutorial, we'll work on a couple of simple examples to get you started, but there is also much more documentation about python scripting available on this wiki. If you are totally new to python and want to understand how it works, we also have a basic introduction to Python. Important! Before proceeding with Python scripting, go to Edit->Prefences->General->Output window and check 2 boxes: Redirect internal Python output to report view Redirect internal Python errors to report view Then go to View->Views and check: Report view This will save you a lot of aggravation!

Writing python code There are two easy ways to write python code in FreeCAD: From the python console (available from the View -> Views -> Python console menu) or from the Macro editor (Tools -> Macros). In the console, you write python commands one by one, which are executed when you press return, while the macros can contain a more complex script made of several lines, which is executed only when the macro is executed.

The FreeCAD python console In this tutorial, you will be able to use both methods, either by copying/pasting each line one by one in the python console and pressing Return after each line, or by copying/pasting the entire code in a new Macro window.

Exploring FreeCAD Let's start by creating a new empty document: doc = FreeCAD.newDocument() If you type this in the FreeCAD python console, you will notice that as soon as you type "FreeCAD.", a windows pops up, allowing to quickly autocomplete the rest of your line. Even better, each entry in the autocomplete list has a tooltip explaining what it does. This makes it very easy to explore the functionality available. Before choosing "newDocument", have a look at the other options available.

The autocomplete mechanism of the FreeCAD python console Now our new document will be created. This is similar to pressing the "new document" button on the toolbar. In fact, most buttons in FreeCAD do nothing else than executing a line or two of python code. Even better, you can set an option in Edit>Preferences->General->M acro to "show script commands in python console". This will print in the console all python code executed when you press buttons. Very useful to learn how to reproduce actions in python. Now let's get back to our document. Let's see what we can do with it: doc. Explore the available options. Usually names that begin with a capital letter are attributes, they contain a value, while names that begin with small letter are functions (also called methods), they "do something". Names that begin with an underscore are usually there for the internal working of the module, and you shouldn't care about them. Let's use one of the methods to add a new object to our document: box = doc.addObject("Part::Box","myBox") Nothing happens. Why? Because FreeCAD is made for the big picture. One day, it will work with hundreds of complex objects, all depending one from another. Making a small change somewhere could have a big impact, you may need to recalculate the whole document, which could take a long time... For that reason, almost no command updates the scene automatically. You must do it manually: doc.recompute() See? Now our box appeared! Many of the buttons that add objects in FreeCAD actually do 2 things: add the object, and recompute. If you turned on the "show script commands in python console" option above, try now adding a sphere with the GUI button, you'll see the two lines of python code being executed one after the other. What about the "Part::Box" will you ask? How can I know what other kind of objects can be added? It's all here: doc.supportedTypes() Now let's explore the contents of our box: box. You'll immediately see a couple of very interesting things such as: box.Height This will print the current height of our box. Now let's try to change that: box.Height = 5 If you select your box with the mouse, you'll see that in the properties panel, in the "Data" tab, our "Height" property appears. All properties of a FreeCAD object that appear there (and also in the "View" tab, more about that later), are directly accessible by python too, by their names, like we did with the "Height" property. Try changing the other dimensions of that box.

Vectors and Placements 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, M esh, Sketcher or Draft. Sketcher and Draft both use the Part module to create and handle their geometry, which are BRep while M esh 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 (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.

Mesh M eshes are a very simple kind of 3D objects, used for example by Sketchup, Blender or 3D studio M ax. 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 M odule 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 M odule 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 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: from PySide 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 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 M acros. 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!

Topological data scripting This page describes several methods for creating and modifying Part shapes from python. Before reading this page, if you are new to python, it is a good idea to read about python scripting and how python scripting works in FreeCAD.

Introduction We will here explain you how to control the Part M odule directly from the FreeCAD python interpreter, or from any external script. The basics about Topological data scripting are described in Part M odule Explaining the concepts. Be sure to browse the Scripting section and the FreeCAD Scripting Basics pages if you need more information about how python scripting works in FreeCAD.

Class Diagram This is a Unified M odeling Language (UM L) overview of the most important classes of the Part module:

Geometry The geometric objects are the building block of all topological objects: Geom Base class of the geometric objects Line A straight line in 3D, defined by starting point and end point Circle Circle or circle segment defined by a center point and start and end point ...... And soon some more

Topology The following topological data types are available: Compound A group of any type of topological object. Compsolid A composite solid is a set of solids connected by their faces. It expands the notions of WIRE and SHELL to solids. Solid A part of space limited by shells. It is three dimensional. Shell A set of faces connected by their edges. A shell can be open or closed. Face In 2D it is part of a plane; in 3D it is part of a surface. Its geometry is constrained (trimmed) by contours. It is two dimensional. Wire A set of edges connected by their vertices. It can be an open or closed contour depending on whether the edges are linked or not. Edge A topological element corresponding to a restrained curve. An edge is generally limited by vertices. It has one dimension. Vertex A topological element corresponding to a point. It has zero dimension. Shape A generic term covering all of the above.

Quick example : Creating simple topology

We will now create a topology by constructing it out of simpler geometry. As a case study we use a part as seen in the picture which consists of four vertexes, two circles and two lines. Creating Geometry First we have to create the distinct geometric parts of this wire. And we have to take care that the vertexes of the geometric parts are at the same position. Otherwise later on we might not be able to connect the geometric parts to a topology! So we create first the points:

from FreeCAD import Base V1 = Base.Vector(0,10,0) V2 = Base.Vector(30,10,0) V3 = Base.Vector(30,-10,0) V4 = Base.Vector(0,-10,0)

Arc

To create an arc of circle we make a helper point and create the arc of circle through three points:

VC1 = Base.Vector(-10,0,0) C1 = Part.Arc(V1,VC1,V4) # and the second one VC2 = Base.Vector(40,0,0) C2 = Part.Arc(V2,VC2,V3)

Line

The line can be created very simple out of the points:

L1 = Part.Line(V1,V2) # and the second one L2 = Part.Line(V4,V3)

Putting all together The last step is to put the geometric base elements together and bake a topological shape:

S1 = Part.Shape([C1,C2,L1,L2])

M ake a prism Now extrude the wire in a direction and make an actual 3D shape:

W = Part.Wire(S1.Edges) P = W.extrude(Base.Vector(0,0,10))

Show it all

Part.show(P)

Creating basic shapes You can easily create basic topological objects with the "make...()" methods from the Part Module:

b = Part.makeBox(100,100,100) Part.show(b)

A couple of other make...() methods available: makeBox(l,w,h): Makes a box located in p and pointing into the direction d with the dimensions (l,w,h) makeCircle(radius): Makes a circle with a given radius makeCone(radius1,radius2,height): Makes a cone with a given radii and height makeCylinder(radius,height): Makes a cylinder with a given radius and height. makeLine((x1,y1,z1),(x2,y2,z2)): Makes a line of two points makePlane(length,width): Makes a plane with length and width makePolygon(list): Makes a polygon of a list of points makeSphere(radius): Make a sphere with a given radius makeTorus(radius1,radius2): Makes a torus with a given radii See the Part API page for a complete list of available methods of the Part module. Importing the needed modules First we need to import the Part module so we can use its contents in python. We'll also import the Base module from inside the FreeCAD module:

import Part from FreeCAD import Base

Creating a Vector Vectors are one of the most important pieces of information when building shapes. They contain a 3 numbers usually (but not necessarily always) the x, y and z cartesian coordinates. You create a vector like this:

myVector = Base.Vector(3,2,0)

We just created a vector at coordinates x=3, y=2, z=0. In the Part module, vectors are used everywhere. Part shapes also use another kind of point representation, called Vertex, which is acually nothing else than a container for a vector. You access the vector of a vertex like this:

myVertex = myShape.Vertexes[0] print myVertex.Point > Vector (3, 2, 0)

Creating an Edge An edge is nothing but a line with two vertexes:

edge = Part.makeLine((0,0,0), (10,0,0)) edge.Vertexes > [<Vertex object at 01877430>, <Vertex object at 014888E0>]

Note: You can also create an edge by passing two vectors:

vec1 = Base.Vector(0,0,0) vec2 = Base.Vector(10,0,0) line = Part.Line(vec1,vec2) edge = line.toShape()

You can find the length and center of an edge like this:

edge.Length > 10.0 edge.CenterOfMass > Vector (5, 0, 0)

Putting the shape on screen So far we created an edge object, but it doesn't appear anywhere on screen. This is because we just manipulated python objects here. The FreeCAD 3D scene only displays what you tell it to display. To do that, we use this simple method:

Part.show(edge)

An object will be created in our FreeCAD document, and our "edge" shape will be attributed to it. Use this whenever it's time to display your creation on screen. Creating a Wire A wire is a multi-edge line and can be created from a list of edges or even a list of wires:

edge1 = Part.makeLine((0,0,0), (10,0,0)) edge2 = Part.makeLine((10,0,0), (10,10,0)) wire1 = Part.Wire([edge1,edge2]) edge3 = Part.makeLine((10,10,0), (0,10,0)) edge4 = Part.makeLine((0,10,0), (0,0,0)) wire2 = Part.Wire([edge3,edge4]) wire3 = Part.Wire([wire1,wire2]) wire3.Edges > [<Edge object at 016695F8>, <Edge object at 0197AED8>, <Edge object at 01828B20>, <Edge object at 0190A788>] Part.show(wire3)

Part.show(wire3) will display the 4 edges that compose our wire. Other useful information can be easily retrieved:

wire3.Length > 40.0 wire3.CenterOfMass > Vector (5, 5, 0) wire3.isClosed() > True wire2.isClosed() > False

Creating a Face Only faces created from closed wires will be valid. In this example, wire3 is a closed wire but wire2 is not a closed wire (see above)

face = Part.Face(wire3) face.Area > 99.999999999999972 face.CenterOfMass > Vector (5, 5, 0) face.Length > 40.0 face.isValid() > True sface = Part.Face(wire2) face.isValid() > False

Only faces will have an area, not wires nor edges. Creating a Circle A circle can be created as simply as this:

circle = Part.makeCircle(10) circle.Curve > Circle (Radius : 10, Position : (0, 0, 0), Direction : (0, 0, 1))

If you want to create it at certain position and with certain direction:

ccircle = Part.makeCircle(10, Base.Vector(10,0,0), Base.Vector(1,0,0)) ccircle.Curve > Circle (Radius : 10, Position : (10, 0, 0), Direction : (1, 0, 0))

ccircle will be created at distance 10 from origin on x and will be facing towards x axis. Note: makeCircle only accepts Base.Vector() for position and normal but not tuples. You can also create part of the circle by giving start angle and end angle as:

from math import pi arc1 = Part.makeCircle(10, Base.Vector(0,0,0), Base.Vector(0,0,1), 0, 180) arc2 = Part.makeCircle(10, Base.Vector(0,0,0), Base.Vector(0,0,1), 180, 360)

Both arc1 and arc2 jointly will make a circle. Angles should be provided in degrees, if you have radians simply convert them using formula: degrees = radians * 180/PI or using python's math module (after doing import math, of course):

degrees = math.degrees(radians)

Creating an Arc along points Unfortunately there is no makeArc function but we have Part.Arc function to create an arc along three points. Basically it can be supposed as an arc joining start point and end point along the middle point. Part.Arc creates an arc object on which .toShape() has to be called to get the edge object, the same way as when using Part.Line instead of Part.makeLine.

arc = Part.Arc(Base.Vector(0,0,0),Base.Vector(0,5,0),Base.Vector(5,5,0)) arc > <Arc object> arc_edge = arc.toShape()

Arc only accepts Base.Vector() for points but not tuples. arc_edge is what we want which we can display using Part.show(arc_edge). You can also obtain an arc by using a portion of a circle:

from math import pi circle = Part.Circle(Base.Vector(0,0,0),Base.Vector(0,0,1),10) arc = Part.Arc(c,0,pi)

Arcs are valid edges, like lines. So they can be used in wires too. Creating a polygon A polygon is simply a wire with multiple straight edges. The makePolygon function takes a list of points and creates a wire along those points:

lshape_wire = Part.makePolygon([Base.Vector(0,5,0),Base.Vector(0,0,0),Base.Vector(5,0,0)])

Creating a Bezier curve BĂŠzier curves are used to model smooth curves using a series of poles (points) and optional weights. The function below makes a Part.BezierCurve from a series of FreeCAD.Vector points. (Note: when "getting" and "setting" a single pole or weight indices start at 1, not 0.)

def makeBCurveEdge(Points): geomCurve = Part.BezierCurve() geomCurve.setPoles(Points) edge = Part.Edge(geomCurve) return(edge)

Creating a Plane A Plane is simply a flat rectangular surface. The method used to create one is this: makePlane(length,width, [start_pnt,dir_normal]). By default start_pnt = Vector(0,0,0) and dir_normal = Vector(0,0,1). Using dir_normal = Vector(0,0,1) will create the plane facing z axis, while dir_normal = Vector(1,0,0) will create the plane facing x axis:

plane = Part.makePlane(2,2) plane

><Face object at 028AF990> plane = Part.makePlane(2,2, Base.Vector(3,0,0), Base.Vector(0,1,0)) plane.BoundBox > BoundBox (3, 0, 0, 5, 0, 2)

BoundBox is a cuboid enclosing the plane with a diagonal starting at (3,0,0) and ending at (5,0,2). Here the BoundBox thickness in y axis is zero, since our shape is totally flat. Note: makePlane only accepts Base.Vector() for start_pnt and dir_normal but not tuples Creating an ellipse To create an ellipse there are several ways:

Part.Ellipse()

Creates an ellipse with major radius 2 and minor radius 1 with the center in (0,0,0)

Part.Ellipse(Ellipse)

Create a copy of the given ellipse

Part.Ellipse(S1,S2,Center)

Creates an ellipse centered on the point Center, where the plane of the ellipse is defined by Center, S1 and S2, its major axis is defined by Center and S1, its major radius is the distance between Center and S1, and its minor radius is the distance between S2 and the major axis.

Part.Ellipse(Center,MajorRadius,MinorRadius)

Creates an ellipse with major and minor radii MajorRadius and MinorRadius, and located in the plane defined by Center and the normal (0,0,1)

eli = Part.Ellipse(Base.Vector(10,0,0),Base.Vector(0,5,0),Base.Vector(0,0,0)) Part.show(eli.toShape())

In the above code we have passed S1, S2 and center. Similarly to Arc, Ellipse also creates an ellipse object but not edge, so we need to convert it into edge using toShape() to display. Note: Arc only accepts Base.Vector() for points but not tuples

eli = Part.Ellipse(Base.Vector(0,0,0),10,5) Part.show(eli.toShape())

for the above Ellipse constructor we have passed center, MajorRadius and MinorRadius Creating a Torus Using the method makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]). By default pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0,angle2=360 and angle=360. Consider a torus as small circle sweeping along a big circle. Radius1 is the radius of big cirlce, radius2 is the radius of small circle, pnt is the center of torus and dir is the normal direction. angle1 and angle2 are angles in radians for the small circle, the last parameter angle is to make a section of the torus:

torus = Part.makeTorus(10, 2)

The above code will create a torus with diameter 20(radius 10) and thickness 4 (small cirlce radius 2)

tor=Part.makeTorus(10,5,Base.Vector(0,0,0),Base.Vector(0,0,1),0,180)

The above code will create a slice of the torus

tor=Part.makeTorus(10,5,Base.Vector(0,0,0),Base.Vector(0,0,1),0,360,180)

The above code will create a semi torus, only the last parameter is changed i.e the angle and remaining angles are defaults. Giving the angle 180 will create the torus from 0 to 180, that is, a half torus. Creating a box or cuboid Using makeBox(length,width,height,[pnt,dir]). By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)

box = Part.makeBox(10,10,10) len(box.Vertexes) > 8

Creating a Sphere Using makeSphere(radius,[pnt, dir, angle1,angle2,angle3]). By default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=-90, angle2=90 and angle3=360. angle1 and angle2 are the vertical minimum and maximum of the sphere, angle3 is the sphere diameter itself.

sphere = Part.makeSphere(10) hemisphere = Part.makeSphere(10,Base.Vector(0,0,0),Base.Vector(0,0,1),-90,90,180)

Creating a Cylinder Using makeCylinder(radius,height,[pnt,dir,angle]). By default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360

cylinder = Part.makeCylinder(5,20) partCylinder = Part.makeCylinder(5,20,Base.Vector(20,0,0),Base.Vector(0,0,1),180)

Creating a Cone Using makeCone(radius1,radius2,height,[pnt,dir,angle]). By default pnt=Vector(0,0,0), dir=Vector(0,0,1) and angle=360

cone = Part.makeCone(10,0,20) semicone = Part.makeCone(10,0,20,Base.Vector(20,0,0),Base.Vector(0,0,1),180)

Modifying shapes There are several ways to modify shapes. Some are simple transformation operations such as moving or rotating shapes, other are more complex, such as unioning and subtracting one shape from another. Be aware that

Transform operations Translating a shape Translating is the act of moving a shape from one place to another. Any shape (edge, face, cube, etc...) can be translated the same way:

myShape = Part.makeBox(2,2,2) myShape.translate(Base.Vector(2,0,0))

This will move our shape "myShape" 2 units in the x direction. Rotating a shape To rotate a shape, you need to specify the rotation center, the axis, and the rotation angle:

myShape.rotate(Vector(0,0,0),Vector(0,0,1),180)

The above code will rotate the shape 180 degrees around the Z Axis. Generic transformations with matrixes A matrix is a very convenient way to store transformations in the 3D world. In a single matrix, you can set translation, rotation and scaling values to be applied to an object. For example:

myMat = Base.Matrix()

myMat.move(Base.Vector(2,0,0)) myMat.rotateZ(math.pi/2)

Note: FreeCAD matrixes work in radians. Also, almost all matrix operations that take a vector can also take 3 numbers, so those 2 lines do the same thing:

myMat.move(2,0,0) myMat.move(Base.Vector(2,0,0))

When our matrix is set, we can apply it to our shape. FreeCAD provides 2 methods to do that: transformShape() and transformGeometry(). The difference is that with the first one, you are sure that no deformations will occur (see "scaling a shape" below). So we can apply our transformation like this:

myShape.trasformShape(myMat)

myShape.transformGeometry(myMat)

Scaling a shape Scaling a shape is a more dangerous operation because, unlike translation or rotation, scaling non-uniformly (with different values for x, y and z) can modify the structure of the shape. For example, scaling a circle with a higher value horizontally than vertically will transform it into an ellipse, which behaves mathematically very differenty. For scaling, we can't use the transformShape, we must use transformGeometry():

myMat = Base.Matrix() myMat.scale(2,1,1) myShape=myShape.transformGeometry(myMat)

Boolean Operations Subtraction Subtracting a shape from another one is called "cut" in OCC/FreeCAD jargon and is done like this:

cylinder = Part.makeCylinder(3,10,Base.Vector(0,0,0),Base.Vector(1,0,0)) sphere = Part.makeSphere(5,Base.Vector(5,0,0)) diff = cylinder.cut(sphere)

Intersection The same way, the intersection between 2 shapes is called "common" and is done this way:

cylinder1 = Part.makeCylinder(3,10,Base.Vector(0,0,0),Base.Vector(1,0,0)) cylinder2 = Part.makeCylinder(3,10,Base.Vector(5,0,-5),Base.Vector(0,0,1)) common = cylinder1.common(cylinder2)

Union Union is called "fuse" and works the same way:

cylinder1 = Part.makeCylinder(3,10,Base.Vector(0,0,0),Base.Vector(1,0,0)) cylinder2 = Part.makeCylinder(3,10,Base.Vector(5,0,-5),Base.Vector(0,0,1)) fuse = cylinder1.fuse(cylinder2)

Section A Section is the intersection between a solid shape and a plane shape. It will return an intersection curve, a compound with edges

cylinder1 = Part.makeCylinder(3,10,Base.Vector(0,0,0),Base.Vector(1,0,0)) cylinder2 = Part.makeCylinder(3,10,Base.Vector(5,0,-5),Base.Vector(0,0,1)) section = cylinder1.section(cylinder2)

section.Wires > [] section.Edges > [<Edge object at 0D87CFE8>, <Edge object at 019564F8>, <Edge object at 0D998458>, <Edge object at 0D86DE18>, <Edge object at 0D9B8E80>, <Edge object at 012A3640>, <Edge object at 0D8F4BB0>]

Extrusion Extrusion is the act of "pushing" a flat shape in a certain direction resulting in a solid body. Think of a circle becoming a tube by "pushing it out":

circle = Part.makeCircle(10) tube = circle.extrude(Base.Vector(0,0,2))

If your circle is hollow, you will obtain a hollow tube. If your circle is actually a disc, with a filled face, you will obtain a solid cylinder:

wire = Part.Wire(circle) disc = Part.makeFace(wire) cylinder = disc.extrude(Base.Vector(0,0,2))

Exploring shapes You can easily explore the topological data structure:

import Part b = Part.makeBox(100,100,100) b.Wires w = b.Wires[0] w w.Wires w.Vertexes Part.show(w) w.Edges e = w.Edges[0] e.Vertexes v = e.Vertexes[0] v.Point

By typing the lines above in the python interpreter, you will gain a good understanding of the structure of Part objects. Here, our makeBox() command created a solid shape. This solid, like all Part solids, contains faces. Faces always contain wires, which are lists of edges that border the face. Each face has at least one closed wire (it can have more if the face has a hole). In the wire, we can look at each edge separately, and inside each edge, we can see the vertexes. Straight edges have only two vertexes, obviously.

Edge analysis In case of an edge, which is an arbitrary curve, it's most likely you want to do a discretization. In FreeCAD the edges are parametrized by their lengths. That means you can walk an edge/curve by its length:

import Part box = Part.makeBox(100,100,100) anEdge = box.Edges[0] print anEdge.Length

Now you can access a lot of properties of the edge by using the length as a position. That means if the edge is 100mm long the start position is 0 and the end position 100.

anEdge.tangentAt(0.0) # tangent direction at the beginning anEdge.valueAt(0.0) # Point at the beginning anEdge.valueAt(100.0) # Point at the end of the edge anEdge.derivative1At(50.0) # first derivative of the curve in the middle anEdge.derivative2At(50.0) # second derivative of the curve in the middle anEdge.derivative3At(50.0) # third derivative of the curve in the middle anEdge.centerOfCurvatureAt(50) # center of the curvature for that position anEdge.curvatureAt(50.0) # the curvature anEdge.normalAt(50) # normal vector at that position (if defined)

Using the selection

Here we see now how we can use the selection the user did in the viewer. First of all we create a box and shows it in the viewer

import Part Part.show(Part.makeBox(100,100,100)) Gui.SendMsgToActiveView("ViewFit")

Select now some faces or edges. With this script you can iterate all selected objects and their sub elements:

for o in Gui.Selection.getSelectionEx(): print o.ObjectName for s in o.SubElementNames: print "name: ",s for s in o.SubObjects: print "object: ",s

Select some edges and this script will calculate the length:

length = 0.0 for o in Gui.Selection.getSelectionEx(): for s in o.SubObjects: length += s.Length print "Length of the selected edges:" ,length

Complete example: The OCC bottle A typical example found on the OpenCasCade Getting Started Page is how to build a bottle. This is a good exercise for FreeCAD too. In fact, you can follow our example below and the OCC page simultaneously, you will understand well how OCC structures are implemented in FreeCAD. The complete script below is also included in FreeCAD installation (inside the Mod/Part folder) and can be called from the python interpreter by typing:

import Part import MakeBottle bottle = MakeBottle.makeBottle() Part.show(bottle)

The complete script Here is the complete MakeBottle script:

import Part, FreeCAD, math from FreeCAD import Base def makeBottle(myWidth=50.0, myHeight=70.0, myThickness=30.0): aPnt1=Base.Vector(-myWidth/2.,0,0) aPnt2=Base.Vector(-myWidth/2.,-myThickness/4.,0) aPnt3=Base.Vector(0,-myThickness/2.,0) aPnt4=Base.Vector(myWidth/2.,-myThickness/4.,0) aPnt5=Base.Vector(myWidth/2.,0,0) aArcOfCircle = Part.Arc(aPnt2,aPnt3,aPnt4) aSegment1=Part.Line(aPnt1,aPnt2) aSegment2=Part.Line(aPnt4,aPnt5) aEdge1=aSegment1.toShape() aEdge2=aArcOfCircle.toShape() aEdge3=aSegment2.toShape() aWire=Part.Wire([aEdge1,aEdge2,aEdge3]) aTrsf=Base.Matrix() aTrsf.rotateZ(math.pi) # rotate around the z-axis aMirroredWire=aWire.transformGeometry(aTrsf) myWireProfile=Part.Wire([aWire,aMirroredWire]) myFaceProfile=Part.Face(myWireProfile) aPrismVec=Base.Vector(0,0,myHeight) myBody=myFaceProfile.extrude(aPrismVec) myBody=myBody.makeFillet(myThickness/12.0,myBody.Edges) neckLocation=Base.Vector(0,0,myHeight) neckNormal=Base.Vector(0,0,1) myNeckRadius = myThickness / 4. myNeckHeight = myHeight / 10 myNeck = Part.makeCylinder(myNeckRadius,myNeckHeight,neckLocation,neckNormal) myBody = myBody.fuse(myNeck) faceToRemove = 0

zMax = -1.0 for xp in myBody.Faces: try: surf = xp.Surface if type(surf) == Part.Plane: z = surf.Position.z if z > zMax: zMax = z faceToRemove = xp except: continue myBody = myBody.makeThickness([faceToRemove],-myThickness/50 , 1.e-3) return myBody

Detailed explanation

import Part, FreeCAD, math from FreeCAD import Base

We will need,of course, the Part module, but also the FreeCAD.Base module, which contains basic FreeCAD structures like vectors and matrixes.

def makeBottle(myWidth=50.0, myHeight=70.0, myThickness=30.0): aPnt1=Base.Vector(-myWidth/2.,0,0) aPnt2=Base.Vector(-myWidth/2.,-myThickness/4.,0) aPnt3=Base.Vector(0,-myThickness/2.,0) aPnt4=Base.Vector(myWidth/2.,-myThickness/4.,0) aPnt5=Base.Vector(myWidth/2.,0,0)

Here we define our makeBottle function. This function can be called without arguments, like we did above, in which case default values for width, height, and thickness will be used. Then, we define a couple of points that will be used for building our base profile.

aArcOfCircle = Part.Arc(aPnt2,aPnt3,aPnt4) aSegment1=Part.Line(aPnt1,aPnt2) aSegment2=Part.Line(aPnt4,aPnt5)

Here we actually define the geometry: an arc, made of 3 points, and two line segments, made of 2 points.

aEdge1=aSegment1.toShape() aEdge2=aArcOfCircle.toShape() aEdge3=aSegment2.toShape() aWire=Part.Wire([aEdge1,aEdge2,aEdge3])

Remember the difference between geometry and shapes? Here we build shapes out of our construction geometry. 3 edges (edges can be straight or curved), then a wire made of those three edges.

aTrsf=Base.Matrix() aTrsf.rotateZ(math.pi) # rotate around the z-axis aMirroredWire=aWire.transformGeometry(aTrsf) myWireProfile=Part.Wire([aWire,aMirroredWire])

Until now we built only a half profile. Easier than building the whole profile the same way, we can just mirror what we did, and glue both halfs together. So we first create a matrix. A matrix is a very common way to apply transformations to objects in the 3D world, since it can contain in one structure all basic transformations that 3D objects can suffer (move, rotate and scale). Here, after we create the matrix, we mirror it, and we create a copy of our wire with that transformation matrix applied to it. We now have two wires, and we can make a third wire out of them, since wires are actually lists of edges.

myFaceProfile=Part.Face(myWireProfile) aPrismVec=Base.Vector(0,0,myHeight) myBody=myFaceProfile.extrude(aPrismVec) myBody=myBody.makeFillet(myThickness/12.0,myBody.Edges)

Now that we have a closed wire, it can be turned into a face. Once we have a face, we can extrude it. Doing so, we actually made a solid. Then we apply a nice little fillet to our object because we care about good design, don't we?

neckLocation=Base.Vector(0,0,myHeight) neckNormal=Base.Vector(0,0,1) myNeckRadius = myThickness / 4. myNeckHeight = myHeight / 10 myNeck = Part.makeCylinder(myNeckRadius,myNeckHeight,neckLocation,neckNormal)

Then, the body of our bottle is made, we still need to create a neck. So we make a new solid, with a cylinder.

myBody = myBody.fuse(myNeck)

The fuse operation, which in other apps is sometimes called union, is very powerful. It will take care of gluing what needs to be glued and remove parts that need to be removed.

return myBody

Then, we return our Part solid as the result of our function. That Part solid, like any other Part shape, can be attributed to an object in a FreeCAD document, with:

myObject = FreeCAD.ActiveDocument.addObject("Part::Feature","myObject") myObject.Shape = bottle

or, more simple:

Part.show(bottle)

Box pierced Here a complete example of building a box pierced. The construction is done side by side and when the cube is finished, it is hollowed out of a cylinder through.

import Draft, Part, FreeCAD, math, PartGui, FreeCADGui, PyQt4 from math import sqrt, pi, sin, cos, asin from FreeCAD import Base size = 10 poly = Part.makePolygon( [ (0,0,0), (size, 0, 0), (size, 0, size), (0, 0, size), (0, 0, 0)]) face1 = Part.Face(poly) face2 = Part.Face(poly) face3 = Part.Face(poly) face4 = Part.Face(poly) face5 = Part.Face(poly) face6 = Part.Face(poly) myMat = FreeCAD.Matrix() myMat.rotateZ(math.pi/2) face2.transformShape(myMat) face2.translate(FreeCAD.Vector(size, 0, 0)) myMat.rotateZ(math.pi/2) face3.transformShape(myMat) face3.translate(FreeCAD.Vector(size, size, 0)) myMat.rotateZ(math.pi/2) face4.transformShape(myMat) face4.translate(FreeCAD.Vector(0, size, 0)) myMat = FreeCAD.Matrix() myMat.rotateX(-math.pi/2) face5.transformShape(myMat) face6.transformShape(myMat) face6.translate(FreeCAD.Vector(0,0,size)) myShell = Part.makeShell([face1,face2,face3,face4,face5,face6]) mySolid = Part.makeSolid(myShell) mySolidRev = mySolid.copy() mySolidRev.reverse() myCyl = Part.makeCylinder(2,20)

myCyl.translate(FreeCAD.Vector(size/2, size/2, 0)) cut_part = mySolidRev.cut(myCyl) Part.show(cut_part)

Loading and Saving There are several ways to save your work in the Part module. You can of course save your FreeCAD document, but you can also save Part objects directly to common CAD formats, such as BREP, IGS, STEP and STL. Saving a shape to a file is easy. There are exportBrep(), exportIges(), exportStl() and exportStep() methods availables for all shape objects. So, doing:

import Part s = Part.makeBox(0,0,0,10,10,10) s.exportStep("test.stp")

this will save our box into a STEP file. To load a BREP, IGES or STEP file, simply do the contrary:

import Part s = Part.Shape() s.read("test.stp")

To convert an .stp in .igs file simply :

import Part s = Part.Shape() s.read("file.stp") # incoming file igs, stp, stl, brep s.exportIges("file.igs") # outbound file igs

Note that importing or opening BREP, IGES or STEP files can also be done directly from the File -> Open or File -> Import menu, while exporting is with File -> Export

Mesh Scripting Introduction First of all you have to import the Mesh module:

import Mesh

After that you have access to the Mesh module and the Mesh class which facilitate the functions of the FreeCAD C++ MeshKernel.

Creation and Loading To create an empty mesh object just use the standard constructor:

mesh = Mesh.Mesh()

You can also create an object from a file

mesh = Mesh.Mesh('D:/temp/Something.stl')

(A list of compatible filetypes can be found under 'Meshes' here.) Or create it out of a set of triangles described by their corner points:

planarMesh = [ # triangle 1 [-0.5000,-0.5000,0.0000],[0.5000,0.5000,0.0000],[-0.5000,0.5000,0.0000], #triangle 2 [-0.5000,-0.5000,0.0000],[0.5000,-0.5000,0.0000],[0.5000,0.5000,0.0000], ] planarMeshObject = Mesh.Mesh(planarMesh) Mesh.show(planarMeshObject)

The Mesh-Kernel takes care about creating a topological correct data structure by sorting coincident points and edges together. Later on you will see how you can test and examine mesh data.

Modeling To create regular geometries you can use the Python script BuildRegularGeoms.py.

import BuildRegularGeoms

This script provides methods to define simple rotation bodies like spheres, ellipsoids, cylinders, toroids and cones. And it also has a method to create a simple cube. To create a toroid, for instance, can be done as follows:

t = BuildRegularGeoms.Toroid(8.0, 2.0, 50) # list with several thousands triangles m = Mesh.Mesh(t)

The first two parameters define the radiuses of the toroid and the third parameter is a sub-sampling factor for how many triangles are created. The higher this value the smoother and the lower the coarser the body is. The Mesh class provides a set of boolean functions that can be used for modeling purposes. It provides union, intersection and difference of two mesh objects.

m1, m2 # are the input mesh objects m3 = Mesh.Mesh(m1) # create a copy of m1 m3.unite(m2) # union of m1 and m2, the result is stored in m3 m4 = Mesh.Mesh(m1) m4.intersect(m2) # intersection of m1 and m2 m5 = Mesh.Mesh(m1) m5.difference(m2) # the difference of m1 and m2 m6 = Mesh.Mesh(m2)

m6.difference(m1) # the difference of m2 and m1, usually the result is different to m5

Finally, a full example that computes the intersection between a sphere and a cylinder that intersects the sphere.

import Mesh, BuildRegularGeoms sphere = Mesh.Mesh( BuildRegularGeoms.Sphere(5.0, 50) ) cylinder = Mesh.Mesh( BuildRegularGeoms.Cylinder(2.0, 10.0, True, 1.0, 50) ) diff = sphere diff = diff.difference&040;cylinder) d = FreeCAD.newDocument() d.addObject("Mesh::Feature","Diff_Sphere_Cylinder").Mesh=diff d.recompute()

Examining and Testing Write your own Algorithms Exporting You can even write the mesh to a python module:

m.write("D:/Develop/Projekte/FreeCAD/FreeCAD_0.7/Mod/Mesh/SavedMesh.py") import SavedMesh m2 = Mesh.Mesh(SavedMesh.faces)

Gui related stuff Odds and Ends An extensive (though hard to use) source of Mesh related scripting are the unit test scripts of the Mesh-Module. In this unit tests literally all methods are called and all properties/attributes are tweaked. So if you are bold enough, take a look at the Unit Test module. See also M esh API

Mesh to Part Converting Part objects to Meshes Converting higher-level objects such as Part shapes into simpler objects such as meshes is a pretty simple operation, where all faces of a Part object get triangulated. The result of that triangulation (tessellation) is then used to construct a mesh: (let's assume our document contains one part object) #let's assume our document contains one part object import Mesh faces = [] shape = FreeCAD.ActiveDocument.ActiveObject.Shape triangles = shape.tessellate(1) # the number represents the precision of the tessellation) for tri in triangles[1]: face = [] for i in range(3): vindex = tri[i] face.append(triangles[0][vindex]) faces.append(face) m = Mesh.Mesh(faces) Mesh.show(m) Sometimes the triangulation of certain faces offered by OpenCascade is quite ugly. If the face has a rectangular parameter space and doesn't contain any holes or other trimming curves you can also create a mesh on your own: import Mesh def makeMeshFromFace(u,v,face): (a,b,c,d)=face.ParameterRange pts=[] for j in range(v): for i in range(u): s=1.0/(u-1)*(i*b+(u-1-i)*a) t=1.0/(v-1)*(j*d+(v-1-j)*c) pts.append(face.valueAt(s,t)) mesh=Mesh.Mesh() for j in range(v-1): for i in range(u-1): mesh.addFacet(pts[u*j+i],pts[u*j+i+1],pts[u*(j+1)+i]) mesh.addFacet(pts[u*(j+1)+i],pts[u*j+i+1],pts[u*(j+1)+i+1]) return mesh

Converting Meshes to Part objects Converting Meshes to Part objects is an extremely important operation in CAD work, because very often you receive 3D data in mesh format from other people or outputted from other applications. Meshes are very practical to represent free-form geometry and big visual scenes, as it is very lightweight, but for CAD we generally prefer higher-level objects that carry much more information, such as the idea of solid, or faces made of curves instead of triangles. Converting meshes to those higher-level objects (handled by the Part M odule in FreeCAD) is not an easy operation. Meshes can be made of thousands of triangles (for example when generated by a 3D scanner), and having solids made of the same number of faces would be extremely heavy to manipulate. So you generally want to optimize the object when converting. FreeCAD currently offers two methods to convert Meshes to Part objects. The first method is a simple, direct conversion, without any optimization: import Mesh,Part mesh = Mesh.createTorus() shape = Part.Shape() shape.makeShapeFromMesh(mesh.Topology,0.05) # the second arg is the tolerance for sewing solid = Part.makeSolid(shape) Part.show(solid) The second method offers the possibility to consider mesh facets coplanar when the angle between them is under a certain value. This allows to build much simpler shapes: (let's assume our document contains one Mesh object) # let's assume our document contains one Mesh object import Mesh,Part,MeshPart faces = [] mesh = App.ActiveDocument.ActiveObject.Mesh segments = mesh.getPlanes(0.00001) # use rather strict tolerance here for i in segments: if len(i) > 0: # a segment can have inner holes wires = MeshPart.wireFromSegment(mesh, i)

# we assume that the exterior boundary is that one with the biggest bounding box if len(wires) > 0: ext=None max_length=0 for i in wires: if i.BoundBox.DiagonalLength > max_length: max_length = i.BoundBox.DiagonalLength ext = i wires.remove(ext) # all interior wires mark a hole and must reverse their orientation, otherwise Part.Face fails for i in wires: i.reverse() # make sure that the exterior wires comes as first in the lsit wires.insert(0, ext) faces.append(Part.Face(wires)) shell=Part.Compound(faces) Part.show(shell) #solid = Part.Solid(Part.Shell(faces)) #Part.show(solid)

Scenegraph FreeCAD is basically a collage of different powerful libraries, the most important being openCascade, for managing and constructing geometry, Coin3d to display that geometry, and Qt to put all this in a nice Graphical User Interface. The geometry that appears in the 3D views of FreeCAD are rendered by the Coin3D library. Coin3D is an implementation of the OpenInventor standard. The openCascade software also provides the same functionality, but it was decided, at the very beginnings of FreeCAD, not to use the built-in openCascade viewer and rather switch to the more performant coin3D software. A good way to learn about that library is the book Open Inventor M entor. OpenInventor is actually a 3D scene description language. The scene described in openInventor is then rendered in OpenGL on your screen. Coin3D takes care of doing this, so the programmer doesn't need to deal with complex openGL calls, he just has to provide it with valid OpenInventor code. The big advantage is that openInventor is a very well-known and well documented standard. One of the big jobs FreeCAD does for you is basically to translate openCascade geometry information into openInventor language. OpenInventor describes a 3D scene in the form of a scenegraph, like the one below:

image from Inventor mentor An openInventor scenegraph describes everything that makes part of a 3D scene, such as geometry, colors, materials, lights, etc, and organizes all that data in a convenient and clear structure. Everything can be grouped into sub-structures, allowing you to organize your scene contents pretty much the way you like. Here is an example of an openInventor file: #Inventor V2.0 ascii Separator { RotationXYZ { axis Z angle 0 } Transform { translation 0 0 0.5 } Separator { Material { diffuseColor 0.05 0.05 0.05 } Transform { rotation 1 0 0 1.5708 scaleFactor 0.2 0.5 0.2 } Cylinder { } } } As you can see, the structure is very simple. You use separators to organize your data into blocks, a bit like you would organize your files into folders. Each statement affects what comes next, for example the first two items of our root separator are a rotation and a translation, both will affect the next item, which is a separator. In that separator, a material is defined, and

another transformation. Our cylinder will therefore be affected by both transformations, the one who was applied directly to it and the one that was applied to its parent separator. We also have many other types of elements to organize our scene, such as groups, switches or annotations. We can define very complex materials for our objects, with color, textures, shading modes and transparency. We can also define lights, cameras, and even movement. It is even possible to embed pieces of scripting in openInventor files, to define more complex behaviours. If you are interested in learning more about openInventor, head directly to its most famous reference, the Inventor mentor. In FreeCAD, normally, we don't need to interact directly with the openInventor scenegraph. Every object in a FreeCAD document, being a mesh, a part shape or anything else, gets automatically converted to openInventor code and inserted in the main scenegraph that you see in a 3D view. That scenegraph gets updated continuously when you do modifications, add or remove objects to the document. In fact, every object (in App space) has a view provider (a corresponding object in Gui space), responsible for issuing openInventor code. But there are many advantages to be able to access the scenegraph directly. For example, we can temporarily change the appearence of an object, or we can add objects to the scene that have no real existence in the FreeCAD document, such as construction geometry, helpers, graphical hints or tools such as manipulators or on-screen information. FreeCAD itself features several tools to see or modify openInventor code. For example, the following python code will show the openInventor representation of a selected object: obj = FreeCAD.ActiveDocument.ActiveObject viewprovider = obj.ViewObject print viewprovider.toString() But we also have a python module that allows complete access to anything managed by Coin3D, such as our FreeCAD scenegraph. So, read on to Pivy.

Pivy Pivy is a python binding library for Coin3d, the 3D-rendering library used FreeCAD. When imported in a running python interpreter, it allows to dialog directly with any running Coin3d scenegraphs, such as the FreeCAD 3D views, or even to create new ones. Pivy is bundled in standard FreeCAD installation. The coin library is divided into several pieces, coin itself, for manipulating scenegraphs and bindings for several GUI systems, such as windows or, like in our case, qt. Those modules are available to pivy too, depending if they are present on the system. The coin module is always present, and it is what we will use anyway, since we won't need to care about anchoring our 3D display in any interface, it is already done by FreeCAD itself. All we need to do is this: from pivy import coin

Accessing and modifying the scenegraph We saw in the Scenegraph page how a typical Coin scene is organized. Everything that appears in a FreeCAD 3D view is a coin scenegraph, organized the same way. We have one root node, and all objects on the screen are its children. FreeCAD has an easy way to access the root node of a 3D view scenegraph: sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph() print sg This will return the root node: <pivy.coin.SoSelection; proxy of <Swig Object of type 'SoSelection *' at 0x360cb60> > We can inspect the immediate children of our scene: for node in sg.getChildren(): print node Some of those nodes, such as SoSeparators or SoGroups, can have children themselves. The complete list of the available coin objects can be found in the official coin documentation. Let's try to add something to our scenegraph now. We'll add a nice red cube: col = coin.SoBaseColor() col.rgb=(1,0,0) cub = coin.SoCube() myCustomNode = coin.SoSeparator() myCustomNode.addChild(col) myCustomNode.addChild(cub) sg.addChild(myCustomNode) and here is our (nice) red cube. Now, let's try this: col.rgb=(1,1,0) See? everything is still accessible and modifiable on-the-fly. No need to recompute or redraw anything, coin takes care of everything. You can add stuff to your scenegraph, change properties, hide stuff, show temporary objects, anything. Of course, this only concerns the display in the 3D view. That display gets recomputed by FreeCAD on file open, and when an object needs recomputing. So, if you change the aspect of an existing FreeCAD object, those changes will be lost if the object gets recomputed or when you reopen the file. A key to work with scenegraphs in your scripts is to be able to access certain properties of the nodes you added when needed. For example, if we wanted to move our cube, we would have added a SoTranslation node to our custom node, and it would have looked like this: col = coin.SoBaseColor() col.rgb=(1,0,0) trans = coin.SoTranslation() trans.translation.setValue([0,0,0]) cub = coin.SoCube() myCustomNode = coin.SoSeparator() myCustomNode.addChild(col) mtCustomNode.addChild(trans) myCustomNode.addChild(cub) sg.addChild(myCustomNode) Remember that in an openInventor scenegraph, the order is important. A node affects what comes next, so you can say something like: color red, cube, color yellow, sphere, and you will get a red cube and a yellow sphere. If we added the translation now to our existing custom node, it would come after the cube, and not affect it. If we had inserted it when creating it, like here above, we could now do: trans.translation.setValue([2,0,0]) And our cube would jump 2 units to the right. Finally, removing something is done with:

sg.removeChild(myCustomNode)

Using callback mechanisms A callback mechanism is a system that permits a library that you are using, such as our coin library, to call you back, that is, to call a certain function from your currently running python object. This is extremely useful, because that way coin can notify you if some specific event occurs in the scene. Coin can watch very different things, such as mouse position, clicks of a mouse button, keyboard keys being pressed, and many other things. FreeCAD features an easy way to use such callbacks: class ButtonTest: def __init__(self): self.view = FreeCADGui.ActiveDocument.ActiveView self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(),self.getMouseClick) def getMouseClick(self,event_cb): event = event_cb.getEvent() if event.getState() == SoMouseButtonEvent.DOWN: print "Alert!!! A mouse button has been improperly clicked!!!" self.view.removeEventCallbackSWIG(SoMouseButtonEvent.getClassTypeId(),self.callback) ButtonTest() The callback has to be initiated from an object, because that object must still be running when the callback will occur. See also a complete list of possible events and their parameters, or the official coin documentation.

Documentation Unfortunately pivy itself still doesn't have a proper documentation, but since it is an accurate translation of coin, you can safely use the coin documentation as reference, and use python style instead of c++ style (for example SoFile::getClassTypeId() would in pivy be SoFile.getClassId())

PySide PySide PySide is a Python binding of the cross-platform GUI toolkit Qt. FreeCAD uses PySide for all GUI (Graphic User Intercase) purposes. PySide evolved from the PyQt package which was previously used by FreeCAD for it's GUI. See Differences Between PySide and PyQt for more information on the differences. Users of FreeCAD often achieve everything using the built-in interface. But for users who want to customise their operations then the Python interface exists which is documented in the Python Scripting Tutorial. The Python interface for FreeCAD had great flexibility and power. For it's user interaction Python with FreeCAD uses PySide, which is what is documented on this page. Python offers the 'print' statement which gives the code: print 'Hello World' With Python's print statement you have only limited control of the appearance and behaviour. PySide supplies the missing control and also handles environments (such as the FreeCAD macro file environment) where the built-in facilities of Python are not enough. PySide's abilities range from:

to:

PySide is described in the following 3 pages which should follow on one from each other: Beginner PySide Examples (Hello World, announcements, enter text, enter number) M edium PySide Examples (window sizing, hiding widgets, popup menus, mouse position, mouse events) Advanced PySide Examples (widgets etc.) They divide the subject matter into 3 parts, differentiated by level of exposure to PySide, Python and the FreeCAD internals. The first page has overview and background material giving a description of PySide and how it is put together while the second and third pages are mostly code examples at different levels. The intention is that the associated pages will provide simple Python code to run PySide so that the user working on a problem can easily copy the code, paste it into their own work, adapt it as necessary and return to their problem solving with FreeCAD. Hopefully they don't have to go chasing off across the internet looking for answers to PySide questions. At the same time this page is not intended to replace the various comprehensive PySide tutorials and reference sites available on the web.

PySide Beginner Examples Introduction The purpose of this page is to cover beginner level examples of the PySide GUI manager (there are accompanying pages M edium PySide Examples and Advanced PySide Examples). Newcomers to GUI programming may stumble over the word "widget". It's meaning outside of computing is usually given as "a small gadget or mechanical device, especially one whose name is unknown or unspecified" For GUI work such as PySide the term "widget" is most often used to refer to the visible elements of the GUI - windows, dialogs, and input/output features. All visible elements of PySide are called widgets, and, for those who are interested, they all descend from a common parent class, QWidget. In addition to the visible elements PySide also offers widgets for networking, XML, multimedia, and database integration. A widget that is not embedded in a parent widget is called a window and usually windows have a frame and a title bar. The most common types of windows are the "main window" (from the Class QMainWindow) and the various subclasses of the dialog (from the Class QDialog). One big difference is that QDialog is modal (i.e. the user can not do anything outside of the Dialog window while it is open) and the QMainWindow is non-modal which allows the user to interact with other windows in parallel. This guide is a shortcut list for getting a PySide program working quickly under FreeCAD, it isn't intended to teach Python or PySide. Some sites that do that are: PySide tutorial at zetcode.com PySide/PyQt Tutorial at PythonCentral.io PySide 1.0.7 Reference at Srinikom.github.io (note this is a reference, not a tutorial)

Import Statement PySide is not loaded with Python by default, it must be requested prior to using it. The following command: from PySide import QtGui, QtCore causes the 2 parts of PySide to be loaded - QtGui holds classes for managing the Graphic User Interface while QtCore contains classes that do not directly relate to management of the GUI (e.g. timers and geometry). Although it is possible to only import the one that is needed, generally they are both needed and both imported. Note: the 'import' statement is not repeated in each code snippet below, it is assumed that it is already in the Python file.

Simplest Example The simplest interaction with PySide is to present a message to the user which they can only accept: reply = QtGui.QMessageBox.information(None,"","Houston, we have a problem")

Yes or No Query The next most simple interaction is to ask for a yes/no answer: reply = QtGui.QMessageBox.question(None, "", "This is your chance to answer, what do you think?", QtGui.QMessageBox.Yes | QtGui.QMessageBox.No, QtGui.QMessageBox.No) if reply == QtGui.QMessageBox.Yes: # this is where the code relevant to a 'Yes' answer goes pass if reply == QtGui.QMessageBox.No: # this is where the code relevant to a 'No' answer goes pass

Enter Text Query The next code snippet asks the user for a piece of text - note this can be any key on the keyboard really: reply = QtGui.QInputDialog.getText(None, "Ouija Central","Enter your thoughts for the day:") if reply[1]: # user clicked OK replyText = reply[0] else: # user clicked Cancel replyText = reply[0] # which will be "" if they clicked Cancel

Remember that even if the user enters only digits, "1234" for example, they are strings and must be converted to number representation with either of the following: anInteger = int(userInput) # to convert to an integer from a string representation aFloat = float(userInput) # to convert to a float from a string representation

More Than 2 Buttons The final Beginner Level example is of how to build a dialog with an arbitrary number of buttons. This example is programmatically too complex to be invoked from a single Python statement so in some ways it should be on the next page which is PySide Medium examples. But on the other hand this is often all that is needed without getting into complex GUI definitions, so the code is placed at the end of the page of this Beginner PySide page rather than the beginning of the following Medium PySide page. from PySide import QtGui, QtCore class MyButtons(QtGui.QDialog): """""" def __init__(self): super(MyButtons, self).__init__() self.initUI() def initUI(self): option1Button = QtGui.QPushButton("Option 1") option1Button.clicked.connect(self.onOption1) option2Button = QtGui.QPushButton("Option 2") option2Button.clicked.connect(self.onOption2) option3Button = QtGui.QPushButton("Option 3") option3Button.clicked.connect(self.onOption3) option4Button = QtGui.QPushButton("Option 4") option4Button.clicked.connect(self.onOption4) option5Button = QtGui.QPushButton("Option 5") option5Button.clicked.connect(self.onOption5) # buttonBox = QtGui.QDialogButtonBox() buttonBox = QtGui.QDialogButtonBox(QtCore.Qt.Horizontal) buttonBox.addButton(option1Button, QtGui.QDialogButtonBox.ActionRole) buttonBox.addButton(option2Button, QtGui.QDialogButtonBox.ActionRole) buttonBox.addButton(option3Button, QtGui.QDialogButtonBox.ActionRole) buttonBox.addButton(option4Button, QtGui.QDialogButtonBox.ActionRole) buttonBox.addButton(option5Button, QtGui.QDialogButtonBox.ActionRole) # mainLayout = QtGui.QVBoxLayout() mainLayout.addWidget(buttonBox) self.setLayout(mainLayout) # define window xLoc,yLoc,xDim,yDim self.setGeometry( 250, 250, 0, 50)

self.setWindowTitle("Pick a Button") self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint) def onOption1(self): self.retStatus = 1 self.close() def onOption2(self): self.retStatus = 2 self.close() def onOption3(self): self.retStatus = 3 self.close() def onOption4(self): self.retStatus = 4 self.close() def onOption5(self): self.retStatus = 5 self.close() def routine1(): print 'routine 1' form = MyButtons() form.exec_() if form.retStatus==1: routine1() elif form.retStatus==2: routine2() elif form.retStatus==3: routine3() elif form.retStatus==4: routine4() elif form.retStatus==5: routine5() Each piece of code under test would be in a function with the name 'routine1()', 'routine2()', etc. As many buttons as you can fit on the screen may be used. Follow the patterns in the code sample and add extra buttons as needed - the Dialog box will set it's width accordingly, up to the width of the screen.

There is a line of code: buttonBox = QtGui.QDialogButtonBox(QtCore.Qt.Horizontal) which causes the buttons to be in a horizontal line. To put them into a vertical line, change the line of code to read: buttonBox = QtGui.QDialogButtonBox(QtCore.Qt.Vertical)

PySide Medium Examples Introduction This page covers medium level examples of the PySide GUI manager (accompanying pages cover aspects that are both less or more advanced, Beginner PySide Examples and Advanced PySide Examples). In this page an example program is used to cover the different PySide topics. The intention is to present some functional PySide code so anyone who needs to use PySide can copy out the relevant section, modify and adapt it to their own purposes.

Notes This page is not intended to cover the Python language or to serve as an instruction in Python. The variable names are not descriptive but have been kept in sequence to better organise the explanations There are numerous naming conventions for GUI components, none of which are "right" or "wrong" There are a variety of different sequencings of the declarations for the widgets, the signals, the methods, once again none are "right" or "wrong" It is worth keeping in mind that PySide operates with strings when dealing with user input, what appears on the screen as a number is actually a text representation of a number

Code Based Discussion - Declarative Portion The "example program" is actually a large Class definition, the definition of a PySide GUI class, and has over 150 lines of code (including comments). There is no functional purpose to the Class or it's behaviour, the sole purpose is to demonstrate possible GUI actions and present some code that hopefully can be used by other FreeCAD users. The Class definition and the small number of lines of code that invoke are described in the order the occur in the file. This order is based on the screen layout which is rather arbitrary and solely intended to demonstrate features. This is the modal GUI screen the PySide Class generates:

Most of the remainder of this section will describe the contents of the Class definition which appears at the end of this section. First we will cover the declarative elements that define how things operate and how the GUI is assembled, then we will cover the operative sections (i.e. the code that will execute when user interactions occur). This window is based on the class QDialog and so is modal - which means no activities can be made outside of the window while it is open.

Import Statement The mandatory Import statement from PySide import QtGui, QtCore This is best placed at the top of the Python file.

Class Definition class ExampleModalGuiClass(QtGui.QDialog): """""" def __init__(self): super(ExampleModalGuiClass, self).__init__() self.initUI() def initUI(self):

This code is best copied out verbatim and altered. The gist of the code is that we are sub-classing the QDialog Class of PySide. In adapting this code you will want to change the class name "ExampleModalGuiClass" - make sure to change it in both locations (e.g. lines 1 & 4).

Window Return Status self.result = userCancelled This is not mandatory but rather a good programming practice, this sets a default return status for the window which will be there regardless of what the user does. Later in the code this may be changed by the Python code to indicate different options the user may have selected.

Window Creation # create our window # define window xLoc,yLoc,xDim,yDim self.setGeometry( 250, 250, 400, 350) self.setWindowTitle("Our Example Program Window") self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint) Remembering that screen dimensions are measured from the upper-left corner, on the 3rd line the values refer to: the number of pixels the upper-left corner will be to the right of the lefthand screen edge (250) the number of pixels the upper-left corner will be below the upper screen edge (250) the width of the screen in pixels (400) the height of the screen in pixels (350) The title of the window is set and the final line simply means that this window will never be obscured by another window - if this is not desired then simply place a Python comment character ('#') as the first character of the line.

Label Creation # create some Labels self.label1 = QtGui.QLabel(" ", self) self.label1.setFont('Courier') # set to a non-proportional font self.label1.move(20, 20) self.label2 = QtGui.QLabel("sample string number two", self) self.label2.move(20, 70) self.label3 = QtGui.QLabel(" ", self) self.label3.setFont('Courier') # set to a non-proportional font self.label3.move(20, 120) self.label4 = QtGui.QLabel("can you see this?", self) self.label4.move(20, 170) In PySide labels serve two purposes, static labels (as the name implies) as well as read-only (i.e. display-only) text fields. So unchanging instructions to the user such as "Don't push the red button" as well as dynamic calculation results such as "42" can be communicated to the user. The 2nd line declares a Label and sets it's initial value (which is blank in this case). The 3rd line specifies the font, any font (on the system) can be specified, if not specified the default font is used. In this case the font is specified as a non-proportional one. The label is moved to it's location in the window - it's coordinates specify it's position with respect to the window (not the screen).

Checkbox Creation # checkboxes self.checkbox1 = QtGui.QCheckBox("Left side", self) self.checkbox1.clicked.connect(self.onCheckbox1) #self.checkbox1.toggle() # will set an initial value if executed self.checkbox1.move(210,10) # self.checkbox2 = QtGui.QCheckBox("Right side", self) self.checkbox2.clicked.connect(self.onCheckbox2) self.checkbox2.move(210,30) Checkboxes can be off and on in any combination (unlike radio buttons). Line 2 declares one and set's it initial Value. Line 3 specifies which method will be executed when the Checkbox is clicked (in this case the method 'onCheckBox1'). If the 4th line did not have the Python comment character ('#') as the first character, then it would be executed and it would mark the checkbox as checked. Finally the 5th line moves the Checkbox into position.

Radio Button Creation # radio buttons self.radioButton1 = QtGui.QRadioButton("random string one",self) self.radioButton1.clicked.connect(self.onRadioButton1) self.radioButton1.move(210,60) # self.radioButton2 = QtGui.QRadioButton("owt gnirts modnar",self) self.radioButton2.clicked.connect(self.onRadioButton2) self.radioButton2.move(210,80) The creation of the Radio BUttons is very similar to the Checkboxes. The only difference really is the behaviour of the Radio

Buttons in that only one of them can be 'on' at a time.

Pop-Up Menu Creation # set up lists for pop-ups self.popupItems1 = ("pizza","apples","candy","cake","potatoes") # set up pop-up menu self.popup1 = QtGui.QComboBox(self) self.popup1.addItems(self.popupItems1) self.popup1.setCurrentIndex(self.popupItems1.index("candy")) self.popup1.activated[str].connect(self.onPopup1) self.popup1.move(210, 115) In line 2 a list is built up of what will be the user choices. An alternative is to build up a Dictionary but only use the Keys for the list of menu choices. Line 4 creates the pop-up menu (known as a ComboBox to PySide), the user options are added in line 5. As a side note, if the Dictionary was used then the lines would appear as: self.popupItems1 = OrderedDict([("2","widget"),("pink","foobar"),("4","galopsis")]) self.popup1.addItems(self.popupItems1.keys()) Returning to the main code sample for this section, line 6 sets the default choice, this line may be omitted, also the value of the default choice could be loaded into the corresponding Label (once again if appropriate). And finally the move into position at line 8.

Button Creation Part 1 # toggle visibility button pushButton1 = QtGui.QPushButton('Toggle visibility', self) pushButton1.clicked.connect(self.onPushButton1) pushButton1.setAutoDefault(False) pushButton1.move(210, 165) The button is created in line 2 with it's name, the handler for it's signal when clicked is specified in line 3. Line 4 is there to prevent the button from becoming the 'default button' - the button that will be clicked if the user simply presses the Return key. And a move to position finished up the code segment.

Text Input Creation # text input field self.textInput = QtGui.QLineEdit(self) self.textInput.setText("cats & dogs") self.textInput.setFixedWidth(190) self.textInput.move(20, 220) The QLineEdit widget is probably the most common for user textual input, in this example the code section after this one will set up a contextual menu to operate on it. This code section creates (line 2), sets an initial value (line 3), sets a width to the field (line 4) and moves the widget into place (line 5).

Contextual Menu Creation # set contextual menu options for text editing widget # set text field to some dogerel popMenuAction1 = QtGui.QAction(self) popMenuAction1.setText("load some text") popMenuAction1.triggered.connect(self.onPopMenuAction1) # make text uppercase popMenuAction2 = QtGui.QAction(self) popMenuAction2.setText("uppercase") popMenuAction2.triggered.connect(self.onPopMenuAction2) # menu dividers popMenuDivider = QtGui.QAction(self) popMenuDivider.setText('---------') popMenuDivider.triggered.connect(self.onPopMenuDivider) # remove all text popMenuAction3 = QtGui.QAction(self) popMenuAction3.setText("clear") popMenuAction3.triggered.connect(self.onPopMenuAction3) # define menu and add options self.textInput.setContextMenuPolicy(QtCore.Qt.ActionsContextMenu) self.textInput.addAction(popMenuAction1) self.textInput.addAction(popMenuAction2) self.textInput.addAction(popMenuDivider) self.textInput.addAction(popMenuAction3) This code has numerous repetitions as the same action is performed with different values - this is part of what makes GUI code so lengthy (no matter what the system). First a QAction is created - it is a pairing (or linkage) of the text that the user will see as their selectable option along with the method that will execute if they select that option. It is basically a pairing of a user choice with a piece of code. Line 3 creates it, line 4 defines the user option (as they will see it) and line 5 specifies which piece of Python code will execute.

Skipping to line 19 (the line with "self.textInput.setContextMenuPolicy") a ActionsContextMenu is created which is holder for all the separate QAction linkages between user choice and code to execute. Each widget can only have a single Contextual Menu (i.e. the menu associated with the right-click) so line 19 defines that menu. The following 4 lines add the linkages created at the beginning of this code section. Order is significant here, the user will see the menu options in the order they are added. Notice that the 3rd menu option is really a bit of nothing, it's code is null but it serves to separate 2 groups of options on the Contextual Menu.

Numeric Input Creation # numeric input field self.numericInput = QtGui.QLineEdit(self) self.numericInput.setInputMask("999") self.numericInput.setText("000") self.numericInput.setFixedWidth(50) self.numericInput.move(250, 220) The creation of the field for numeric input really follows that for Text Input earlier. In fact the code is identical with exception of the 3rd and 4th lines. The 3rd line sets the Mask as defined by PySide, which in this case specifies up to 3 digits (which may include 0). A full list of the InputMask codes can be found at QLineEdit InputM ask

Button Creation Part 2 # cancel button cancelButton = QtGui.QPushButton('Cancel', self) cancelButton.clicked.connect(self.onCancel) cancelButton.setAutoDefault(True) cancelButton.move(150, 280) # OK button okButton = QtGui.QPushButton('OK', self) okButton.clicked.connect(self.onOk) okButton.move(260, 280) Both buttons are created with a name (which will appear as their label), associated with a method which will execute when they are clicked, and moved into position. The one exception is line 4 which specifies the 'Cancel' button as the default button - that means it will be "clicked" if the user preses the Return key.

Window Display # now make the window visible self.show() There is only one line and it causes the GUI to be displayed after the setup.

Code Based Discussion - Operative Portion We now move onto the operative portion of the GUI definition which is the code that executes in response to user interactions with the GUI. The order of statement groups is not very relevant - with the caveat that something must be declared before it can be referenced. Some people put all the handlers of a certain type (e.g. handlers for buttons) in one group, others list the handlers alphabetically. For specific application there may be a problem related reason that all handlers relating to a specific aspect be gathered together There is a high degree of similarity between the handlers. Most do not receive a parameter, the fact they are executing is realy the only parameter (or signal) they get. Others like "onPopup1" and "mousePressEvent" accept a parameter. There must be a one to one correspondance between the handlers specified in the declarative section and the handler declared in this, the operative section. There may be extra handlers declared which are never invoked but there may not be any missing.

Generic Handler In this code example, generic handlers handle the following events: onCheckbox1 onCheckbox2 onRadioButton1 onRadioButton2 onPushButton1 onPopMenuAction1 onPopMenuAction2 onPopMenuDivider onPopMenuAction3 onCancel onOk The general form for the handlers is:

def handlerName(self): lineOfCode1 lineOfCode2 The first line has the keyword "def" followed by the handler name. The handler name must match the name from the earlier declarative section exactly. The parameter "self" is part of the standard syntax as are the enclosing parenthesis and the final colon character. Once the first line is finished then there are no requirements of the following code, it is purely application specific.

Pop-Up Menu Handler def onPopup1(self, selectedText): The Pop-Up menu handler is the same as the generic handler with exception that a second parameter, the text selected by the user, is passed in. Remember that everything is text coming from the Pop-Up menu and even if the user has selected the number 3, it will be passed in as the string "3".

Mouse Event Handler def mousePressEvent(self, event): # print mouse position, X & Y print "X = ", event.pos().x() print "Y = ", event.pos().y() # if event.button() == QtCore.Qt.LeftButton: print "left mouse button" if self.label1.underMouse(): print "over the text '"+self.label1.text()+"'" The Mouse Event handler is the same as the generic handler with exception that a second parameter, the mouse event (e.g. left-click, right-click) from the user is passed in. The name of the handler, "mousePressEvent", is reserved and if it is changed then the handler will no longer receive the event from the mouse presses. The X and Y coordinates of the mouse press are given by the reference "event.pos().x()" and "event.pos().y()". The constants "QtCore.Qt.LeftButton" and "QtCore.Qt.RightButton" are used to determine which mouse button was pressed. A reference to a widget can be made of the form "self.widgetName.underMouse()" which will return TRUE or FALSE as to whether the mouse cursor is over the widget "widgetName". Although presented in the same code excerpt the "underMouse()" handler is not tied to the "mousePressEvent" handler and can be used at any time.

Code Based Discussion - Main Routine Most of the volume of code is in the GUI Class definition, there is not much in the main procedure. # Constant definitions global userCancelled, userOK userCancelled = "Cancelled" userOK = "OK" Lines 2,3 & 4 deal with coordinating the status of the user interaction with the GUI - e.g. Cancelled, OK, or any other application defined status. The handler routines On Cancel and OnOk earlier also set these statuses. form = ExampleGuiClass() form.exec_() if form.result==userCancelled: pass # steps to handle user clicking Cancel if form.result==userOK: # steps to handle user clicking OK localVariable1 = form.label1.text() localVariable2 = form.label2.text() localVariable3 = form.label3.text() localVariable4 = form.label4.text() Lines 1 and 2 show the method for invoking the GUI. There may be multiple GUI definitions for a program and also the GUI need not be invoked as the first thing in the Python file, it may be invoked at any point. The Name of the GUI Class is specified in line 1 ("ExampleGuiClass" in this case) but the rest of the 2 lines are to be copied verbatim. Lines 4 and 6 use the result field to determine the appropriate action. The last 4 lines simply show the copying of the data in the GUI object to variables local to the executing main procedure.

Complete Modal Code Example This is the complete code example (developed on FreeCAD v0.14):

# import statements from PySide import QtGui, QtCore

# UI Class definitions class ExampleModalGuiClass(QtGui.QDialog): """""" def __init__(self): super(ExampleModalGuiClass, self).__init__() self.initUI() def initUI(self): self.result = userCancelled # create our window # define windowxLoc,yLoc,xDim,yDim self.setGeometry(250, 250, 400, 350) self.setWindowTitle("Our Example Modal Program Window") self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint) # create some Labels self.label1 = QtGui.QLabel(" ", self) self.label1.setFont('Courier') # set to a non-proportional font self.label1.move(20, 20) self.label2 = QtGui.QLabel("sample string number two", self) self.label2.move(20, 70) self.label3 = QtGui.QLabel(" ", self) self.label3.setFont('Courier') # set to a non-proportional font self.label3.move(20, 120) self.label4 = QtGui.QLabel("can you see this?", self) self.label4.move(20, 170) # checkboxes self.checkbox1 = QtGui.QCheckBox("Left side", self) self.checkbox1.clicked.connect(self.onCheckbox1) #self.checkbox1.toggle() # will set an initial value if executed self.checkbox1.move(210,10) # self.checkbox2 = QtGui.QCheckBox("Right side", self) self.checkbox2.clicked.connect(self.onCheckbox2) self.checkbox2.move(210,30) # radio buttons self.radioButton1 = QtGui.QRadioButton("random string one",self) self.radioButton1.clicked.connect(self.onRadioButton1) self.radioButton1.move(210,60) # self.radioButton2 = QtGui.QRadioButton("owt gnirts modnar",self) self.radioButton2.clicked.connect(self.onRadioButton2) self.radioButton2.move(210,80) # set up lists for pop-ups self.popupItems1 = ("pizza","apples","candy","cake","potatoes") # set up pop-up menu self.popup1 = QtGui.QComboBox(self) self.popup1.addItems(self.popupItems1) self.popup1.setCurrentIndex(self.popupItems1.index("candy")) self.popup1.activated[str].connect(self.onPopup1) self.popup1.move(210, 115) # toggle visibility button pushButton1 = QtGui.QPushButton('Toggle visibility', self) pushButton1.clicked.connect(self.onPushButton1) pushButton1.setAutoDefault(False) pushButton1.move(210, 165) # text input field self.textInput = QtGui.QLineEdit(self) self.textInput.setText("cats & dogs") self.textInput.setFixedWidth(190) self.textInput.move(20, 220) # set contextual menu options for text editing widget # set text field to some dogerel popMenuAction1 = QtGui.QAction(self) popMenuAction1.setText("load some text") popMenuAction1.triggered.connect(self.onPopMenuAction1) # make text uppercase popMenuAction2 = QtGui.QAction(self) popMenuAction2.setText("uppercase") popMenuAction2.triggered.connect(self.onPopMenuAction2) # menu dividers popMenuDivider = QtGui.QAction(self) popMenuDivider.setText('---------') popMenuDivider.triggered.connect(self.onPopMenuDivider) # remove all text popMenuAction3 = QtGui.QAction(self) popMenuAction3.setText("clear") popMenuAction3.triggered.connect(self.onPopMenuAction3) # define menu and add options self.textInput.setContextMenuPolicy(QtCore.Qt.ActionsContextMenu) self.textInput.addAction(popMenuAction1) self.textInput.addAction(popMenuAction2) self.textInput.addAction(popMenuDivider) self.textInput.addAction(popMenuAction3) # numeric input field

self.numericInput = QtGui.QLineEdit(self) self.numericInput.setInputMask("999") self.numericInput.setText("000") self.numericInput.setFixedWidth(50) self.numericInput.move(250, 220) # cancel button cancelButton = QtGui.QPushButton('Cancel', self) cancelButton.clicked.connect(self.onCancel) cancelButton.setAutoDefault(True) cancelButton.move(150, 280) # OK button okButton = QtGui.QPushButton('OK', self) okButton.clicked.connect(self.onOk) okButton.move(260, 280) # now make the window visible self.show() # def onCheckbox1(self): text = self.label1.text() if text[0]==' ': self.label1.setText('left'+text[4:]) else: self.label1.setText(' '+text[4:]) def onCheckbox2(self): text = self.label1.text() if text[-1]==' ': self.label1.setText(text[:-5]+'right') else: self.label1.setText(text[:-5]+' ') def onRadioButton1(self): self.label2.setText(self.radioButton1.text()) def onRadioButton2(self): self.label2.setText(self.radioButton2.text()) def onPopup1(self, selectedText): if self.label3.text().isspace(): self.label3.setText(selectedText) else: self.label3.setText(self.label3.text()+","+selectedText) def onPushButton1(self): if self.label4.isVisible(): self.label4.hide() else: self.label4.show() def onPopMenuAction1(self): # load some text into field self.textInput.setText("Lorem ipsum dolor sit amet") def onPopMenuAction2(self): # set text in field to uppercase self.textInput.setText(self.textInput.text().upper()) def onPopMenuDivider(self): # this option is the divider and is really there as a spacer on the menu list # consequently it has no functional code to execute if user selects it pass def onPopMenuAction3(self): # clear the text from the field self.textInput.setText('') def onCancel(self): self.result= userCancelled self.close() def onOk(self): self.result= userOK self.close() def mousePressEvent(self, event): # print mouse position, X & Y print "X = ", event.pos().x() print "Y = ", event.pos().y() # if event.button() == QtCore.Qt.LeftButton: print "left mouse button" if self.label1.underMouse(): print "over the text '"+self.label1.text()+"'" if self.label2.underMouse(): print "over the text '"+self.label2.text()+"'" if self.label3.underMouse(): print "over the text '"+self.label3.text()+"'" if self.label4.underMouse(): print "over the text '"+self.label4.text()+"'" if self.textInput.underMouse(): print "over the text '"+self.textInput.text()+"'" if event.button() == QtCore.Qt.RightButton: print "right mouse button" # Class definitions # Function definitions

# Constant definitions userCancelled= "Cancelled" userOK= "OK" # code *********************************************************************************** form = ExampleModalGuiClass() form.exec_() if form.result==userCancelled: pass # steps to handle user clicking Cancel if form.result==userOK: # steps to handle user clicking OK localVariable1 = form.label1.text() localVariable2 = form.label2.text() localVariable3 = form.label3.text() localVariable4 = form.label4.text() print localVariable1 print localVariable2 print localVariable3 print localVariable4 # #OS: Mac OS X #Word size: 64-bit #Version: 0.14.3703 (Git) #Branch: releases/FreeCAD-0-14 #Hash: c6edd47334a3e6f209e493773093db2b9b4f0e40 #Python version: 2.7.5 #Qt version: 4.8.6 #Coin version: 3.1.3 #SoQt version: 1.5.0 #OCC version: 6.7.0 #

The best way to use this code is to copy it into an editor or FreeCAD macro file and play around with it.

Code Based Discussion - Nonmodal Code Example All of the widget specific from the previous modal example transfer to use in a nonmodal window. The main difference is that the nonmodal window does not restrict the user from interacting with other windows. Basically, a nonmodal window is one that can be opened and left open for as long as needed without it placing any restrictions on other application windows. There are a small number of code differences between the two which will be highlighted, consequently this code example is quite brief. Anything that is the same as the previous modal example will be left out in the interests of keeping this overview brief. This is the nonmodal GUI screen the PySide Class generates:

Import Statement The mandatory Import statement from PySide import QtGui, QtCore This is best placed at the top of the Python file.

Class Definition class ExampleNonmodalGuiClass(QtGui.QMainWindow): """""" def __init__(self): super(ExampleNonmodalGuiClass, self).__init__() self.initUI() def initUI(self): This code is best copied out verbatim and altered. The gist of the code is that we are sub-classing the QMainWindow Class of PySide. In adapting this code you will want to change the class name "ExampleNonmodalGuiClass" - make sure to change it in both locations (e.g. lines 1 & 4).

Window Creation

# create our window # define window xLoc,yLoc,xDim,yDim self.setGeometry( 250, 250, 400, 150) self.setWindowTitle("Our Example Nonmodal Program Window") self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint) self.setMouseTracking(True) Obviously our window dimensions and title are different. The main point to note is the last line which lets PySide know that it is to send out mouse position events as they happen. Note that these events will not be sent out when the mouse is over a widget like a button as the widget will capture the events.

Mouse Move Event Handler def mouseMoveEvent(self,event): self.label6.setText("X: "+str(event.x()) + " Y: "+str(event.y())) This handler receives the event of a Mouse Move and displays the formatted form of it. Test what happens when it is over widgets or outside of the window.

Invoking the Window form = ExampleNonmodalGuiClass() Invoking the window is another area of difference from the previous example. This time only 1 line is needed for invoking the GUI.

Complete Nonmodal Code Example # import statements from PySide import QtGui, QtCore # UI Class definitions class ExampleNonmodalGuiClass(QtGui.QMainWindow): """""" def __init__(self): super(ExampleNonmodalGuiClass, self).__init__() self.initUI() def initUI(self): self.result = userCancelled # create our window # define windowxLoc,yLoc,xDim,yDim self.setGeometry(250, 250, 400, 150) self.setWindowTitle("Our Example Nonmodal Program Window") self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint) self.setMouseTracking(True) # create Labels self.label4 = QtGui.QLabel("can you see this?", self) self.label4.move(20, 20) self.label5 = QtGui.QLabel("Mouse position:", self) self.label5.move(20, 70) self.label6 = QtGui.QLabel(" ", self) self.label6.move(135, 70) # toggle visibility button pushButton1 = QtGui.QPushButton('Toggle visibility', self) pushButton1.clicked.connect(self.onPushButton1) pushButton1.setMinimumWidth(150) #pushButton1.setAutoDefault(False) pushButton1.move(210, 20) # cancel button cancelButton = QtGui.QPushButton('Cancel', self) cancelButton.clicked.connect(self.onCancel) cancelButton.setAutoDefault(True) cancelButton.move(150, 110) # OK button okButton = QtGui.QPushButton('OK', self) okButton.clicked.connect(self.onOk) okButton.move(260, 110) # now make the window visible self.show() # def onPushButton1(self): if self.label4.isVisible(): self.label4.hide() else: self.label4.show() def onCancel(self): self.result= userCancelled self.close()

def onOk(self): self.result= userOK self.close() def mouseMoveEvent(self,event): self.label6.setText("X: "+str(event.x()) + " Y: "+str(event.y())) # Class definitions # Function definitions # Constant definitions global userCancelled, userOK userCancelled= "Cancelled" userOK= "OK" # code *********************************************************************************** form = ExampleNonmodalGuiClass() # #OS: Mac OS X #Word size: 64-bit #Version: 0.14.3703 (Git) #Branch: releases/FreeCAD-0-14 #Hash: c6edd47334a3e6f209e493773093db2b9b4f0e40 #Python version: 2.7.5 #Qt version: 4.8.6 #Coin version: 3.1.3 #SoQt version: 1.5.0 #OCC version: 6.7.0 #

Misc Additional Topics There are 3 concepts to the screen real estate in a GUI environment: physical space on the screen frame geometry Within the software all are measured in pixels. PySide has function to measure in real world units but these are undependable as the manufacturers have no standard for pixel size or aspect ratio. The Frame is the size of a window including it's side bars, top bar (possibly with a menu in it) and bottom bar. The Geometry is the space lying within the Frame and so is always less than or equal to the Frame. In turn the Frame is always less than or equal to the available screen size.

Available Screen Size # get screen dimensions (Available Screen Size) screenWidth = QtGui.QDesktopWidget().screenGeometry().width() screenHeight = QtGui.QDesktopWidget().screenGeometry().height() # get dimensions for available space on screen availableWidth = QtGui.QDesktopWidget().availableGeometry().width() availableHeight = QtGui.QDesktopWidget().availableGeometry().height() Generally the "availableHeight" should be less than the "screenHeight" by the height of the menu bar. These 4 values are based on the hardware environment and will change from computer to computer. They are not dependent on any application window size.

Frame Size and Geometry # set up a variable to hold the Main Window to save some typing... mainWin = FreeCAD.Gui.getMainWindow() mainWin.showFullScreen() # no menu bars, every last pixel is given over to FreeCAD mainWin.geometry() mainWin.frameSize() mainWin.frameGeometry() mainWin.showMaximized() # show maximised within the screen, window edges and the menu bar will be displayed mainWin.geometry() mainWin.frameSize() mainWin.frameGeometry() mainWin.showNormal() # show at the last non-maximised or non-minimised size (and location) mainWin.geometry() mainWin.frameSize() mainWin.frameGeometry() mainWin.setGeometry(50, 50, 800, 800) # specifically set FreeCAD main window's size and

location, this will become the new setting for 'showNormal()' mainWin.showMinimized() # FreeCAD will disappear from view after this command... mainWin.geometry() mainWin.frameSize() mainWin.frameGeometry() These same commands can be executed on a user generated window, the syntax does not change.

PySide Advanced Examples Introduction The purpose of this page is to cover advanced level examples of the PySide GUI manager (there are accompanying pages Beginner PySide Examples and M edium PySide Examples). By using the PySide module from inside FreeCAD, you have full control over its interface. You can for example: Add your own panels, widgets and toolbars Add or hide elements to existing panels Change, redirect or add connections between all those elements

Create Reference for the Main Window If you want to work on the FreeCAD interface, the very first thing to do is create a reference to the FreeCAD main window: import sys from PySide import QtGui ,QtCore app = QtGui.qApp mw = FreeCADGui.getMainWindow()

Browse the Children of the Main Window Then, you can for example browse through all the widgets of the interface: for child in mw.children(): print 'widget name = ', child.objectName(), ', widget type = ', child The widgets in a Qt interface are usually nested into "container" widgets, so the children of our main window can themselves contain other children. Depending on the widget type, there are a lot of things you can do. Check the API documentation to see what is possible.

Add New Widget Manually Adding a new widget, for example a dockWidget (which can be placed in one of FreeCAD's side panels) is easy: myWidget = QtGui.QDockWidget() mw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myWidget) You could then add stuff directly to your widget: myWidget.setObjectName("my Nice New Widget") myWidget.resize(QtCore.QSize(300,100)) # sets size of the widget label = QtGui.QLabel("Hello World", myWidget) # creates a label label.setGeometry(QtCore.QRect(2,50,200,24)) # sets its size label.setObjectName("myLabel") # sets its name, so it can be found by name

Add New Widget by Creating UI Object But a preferred method is to create a UI object which will do all of the setup of your widget at once. The big advantage is that such an UI object can be created graphically with the Qt Designer program. A typical object generated by Qt Designer is like this: class myWidget_Ui(object): def setupUi(self, myWidget): myWidget.setObjectName("my Nice New Widget") myWidget.resize(QtCore.QSize(300,100).expandedTo(myWidget.minimumSizeHint())) # sets size of the widget self.label = QtGui.QLabel(myWidget) # creates a label self.label.setGeometry(QtCore.QRect(50,50,200,24)) # sets its size self.label.setObjectName("label") # sets its name, so it can be found by name def retranslateUi(self, draftToolbar): # built-in QT function that manages translations of widgets myWidget.setWindowTitle(QtGui.QApplication.translate("myWidget", "My Widget", None, QtGui.QApplication.UnicodeUTF8)) self.label.setText(QtGui.QApplication.translate("myWidget", "Welcome to my new widget!", None, QtGui.QApplication.UnicodeUTF8))

To use it, you just need to apply it to your freshly created widget like this: app = QtGui.qApp FCmw = app.activeWindow() myNewFreeCADWidget = QtGui.QDockWidget() # create a new dckwidget myNewFreeCADWidget.ui = myWidget_Ui() # load the Ui script myNewFreeCADWidget.ui.setupUi(myNewFreeCADWidget) # setup the ui FCmw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myNewFreeCADWidget) # add the widget to the main window

Scripted objects Besides the standard object types such as annotations, meshes and parts objects, FreeCAD also offers the amazing possibility to build 100% python-scripted objects, called Python Features. Those objects will behave exactly as any other FreeCAD object, and are saved and restored automatically on file save/load. One particularity must be understood, those objects are saved in FreeCAD FcStd files with python's json module. That module turns a python object as a string, allowing it to be added to the saved file. On load, the json module uses that string to recreate the original object, provided it has access to the source code that created the object. This means that if you save such a custom object and open it on a machine where the python code that generated the object is not present, the object won't be recreated. If you distribute such objects to others, you will need to distribute the python script that created it together. Python Features follow the same rule as all FreeCAD features: they are separated into App and GUI parts. The app part, the Document Object, defines the geometry of our object, while its GUI part, the View Provider Object, defines how the object will be drawn on screen. The View Provider Object, as any other FreeCAD feature, is only available when you run FreeCAD in its own GUI. There are several properties and methods available to build your object. Properties must be of any of the predefined properties types that FreeCAD offers, and will appear in the property view window, so they can be edited by the user. This way, FeaturePython objects are truly and totally parametric. you can define properties for the Object and its ViewObject separately. Hint: In former versions we used Python's cPickle module. However, this module executes arbitrary code and thus causes a security problem. Thus, we moved to Python's json module.

Basic example The following sample can be found in the src/M od/TemplatePyM od/FeaturePython.py file, together with several other examples: "Examples for a feature class and its view provider." import FreeCAD, FreeCADGui from pivy import coin class Box: def __init__(self, obj): "'''Add some custom properties to our box feature'''" obj.addProperty("App::PropertyLength","Length","Box","Length of the box").Length=1.0 obj.addProperty("App::PropertyLength","Width","Box","Width of the box").Width=1.0 obj.addProperty("App::PropertyLength","Height","Box", "Height of the box").Height=1.0 obj.Proxy = self def onChanged(self, fp, prop): "'''Do something when a property has changed'''" FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n") def execute(self, fp): "'''Do something when doing a recomputation, this method is mandatory'''" FreeCAD.Console.PrintMessage("Recompute Python Box feature\n") class ViewProviderBox: def __init__(self, obj): "'''Set this object to the proxy object of the actual view provider'''" obj.addProperty("App::PropertyColor","Color","Box","Color of the box").Color= (1.0,0.0,0.0) obj.Proxy = self def attach(self, obj): "'''Setup the scene sub-graph of the view provider, this method is mandatory'''" self.shaded = coin.SoGroup() self.wireframe = coin.SoGroup() self.scale = coin.SoScale() self.color = coin.SoBaseColor() data=coin.SoCube() self.shaded.addChild(self.scale) self.shaded.addChild(self.color) self.shaded.addChild(data) obj.addDisplayMode(self.shaded,"Shaded"); style=coin.SoDrawStyle() style.style = coin.SoDrawStyle.LINES self.wireframe.addChild(style) self.wireframe.addChild(self.scale) self.wireframe.addChild(self.color) self.wireframe.addChild(data) obj.addDisplayMode(self.wireframe,"Wireframe"); self.onChanged(obj,"Color") def updateData(self, fp, prop): "'''If a property of the handled feature has changed we have the chance to handle this here'''" # fp is the handled feature, prop is the name of the property that has changed

l = fp.getPropertyByName("Length") w = fp.getPropertyByName("Width") h = fp.getPropertyByName("Height") self.scale.scaleFactor.setValue(l,w,h) pass def getDisplayModes(self,obj): "'''Return a list of display modes.'''" modes=[] modes.append("Shaded") modes.append("Wireframe") return modes def getDefaultDisplayMode(self): "'''Return the name of the default display mode. It must be defined in getDisplayModes.'''" return "Shaded" def setDisplayMode(self,mode): "'''Map the display mode defined in attach with those defined in getDisplayModes.\''' '''Since they have the same names nothing needs to be done. This method is optional'''" return mode def onChanged(self, vp, prop): "'''Here we can do something when a single property got changed'''" FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n") if prop == "Color": c = vp.getPropertyByName("Color") self.color.rgb.setValue(c[0],c[1],c[2]) def getIcon(self): "'''Return the icon in XPM format which will appear in the tree view. This method is\''' '''optional and if not defined a default icon is shown.'''" return """ /* XPM */ static const char * ViewProviderBox_xpm[] = { "16 16 6 1", " c None", ". c #141010", "+ c #615BD2", "@ c #C39D55", "# c #000000", "$ c #57C355", " ........", " ......++..+..", " .@@@@.++..++.", " .@@@@.++..++.", " .@@ .++++++.", " ..@@ .++..++.", "###@@@@ .++..++.", "##$.@@$#.++++++.", "#$#$.$$$........", "#$$####### ", "#$$#$$$$$# ", "#$$#$$$$$# ", "#$$#$$$$$# ", " #$#$$$$$# ", " ##$$$$$# ", " ####### "}; """ def __getstate__(self): "'''When saving the document this object gets stored using Python's json module.\''' '''Since we have some un-serializable parts here -- the Coin stuff -- we must define this method\''' '''to return a tuple of all serializable objects or None.'''" return None def __setstate__(self,state): "'''When restoring the serialized object from document we have the chance to set some internals here.\''' '''Since no data were serialized nothing needs to be done here.'''" return None def makeBox(): FreeCAD.newDocument() a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") Box(a) ViewProviderBox(a.ViewObject)

Available properties

Properties are the true building stones of FeaturePython objects. Through them, the user will be able to interact and modify your object. After creating a new FeaturePython object in your document ( obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), you can get a list of the available properties by issuing: obj.supportedProperties() You will get a list of available properties: App::PropertyBool App::PropertyBoolList App::PropertyFloat App::PropertyFloatList App::PropertyFloatConstraint App::PropertyQuantity App::PropertyQuantityConstraint App::PropertyAngle App::PropertyDistance App::PropertyLength App::PropertySpeed App::PropertyAcceleration App::PropertyForce App::PropertyPressure App::PropertyInteger App::PropertyIntegerConstraint App::PropertyPercent App::PropertyEnumeration App::PropertyIntegerList App::PropertyIntegerSet App::PropertyMap App::PropertyString App::PropertyUUID App::PropertyFont App::PropertyStringList App::PropertyLink App::PropertyLinkSub App::PropertyLinkList App::PropertyLinkSubList App::PropertyMatrix App::PropertyVector App::PropertyVectorList App::PropertyPlacement App::PropertyPlacementLink App::PropertyColor App::PropertyColorList App::PropertyMaterial App::PropertyPath App::PropertyFile App::PropertyFileIncluded App::PropertyPythonObject Part::PropertyPartShape Part::PropertyGeometryList Part::PropertyShapeHistory Part::PropertyFilletEdges Sketcher::PropertyConstraintList When adding properties to your custom objects, take care of this: Do not use characters "<" or ">" in the properties descriptions (that would break the xml pieces in the .fcstd file) Properties are stored alphabetically in a .fcstd file. If you have a shape in your properties, any property whose name comes after "Shape" in alphabetic order, will be loaded AFTER the shape, which can cause strange behaviours.

Property Type By default the properties can be updated. It is possible to make the properties read-only, for instance in the case one wants to show the result of a method. It is also possible to hide the property. The property type can be set using obj.setEditorMode("MyPropertyName", mode) where mode is a short int that can be set to: 0 -- default mode, read and write 1 -- read-only 2 -- hidden

Other more complex example This example makes use of the Part M odule to create an octahedron, then creates its coin representation with pivy.

First is the Document object itself: import FreeCAD, FreeCADGui, Part class Octahedron: def __init__(self, obj): "Add some custom properties to our box feature" obj.addProperty("App::PropertyLength","Length","Octahedron","Length of the octahedron").Length=1.0 obj.addProperty("App::PropertyLength","Width","Octahedron","Width of the octahedron").Width=1.0 obj.addProperty("App::PropertyLength","Height","Octahedron", "Height of the octahedron").Height=1.0 obj.addProperty("Part::PropertyPartShape","Shape","Octahedron", "Shape of the octahedron") obj.Proxy = self def execute(self, fp): # Define six vetices for the shape v1 = FreeCAD.Vector(0,0,0) v2 = FreeCAD.Vector(fp.Length,0,0) v3 = FreeCAD.Vector(0,fp.Width,0) v4 = FreeCAD.Vector(fp.Length,fp.Width,0) v5 = FreeCAD.Vector(fp.Length/2,fp.Width/2,fp.Height/2) v6 = FreeCAD.Vector(fp.Length/2,fp.Width/2,-fp.Height/2) # Make the wires/faces f1 = self.make_face(v1,v2,v5) f2 = self.make_face(v2,v4,v5) f3 = self.make_face(v4,v3,v5) f4 = self.make_face(v3,v1,v5) f5 = self.make_face(v2,v1,v6) f6 = self.make_face(v4,v2,v6) f7 = self.make_face(v3,v4,v6) f8 = self.make_face(v1,v3,v6) shell=Part.makeShell([f1,f2,f3,f4,f5,f6,f7,f8]) solid=Part.makeSolid(shell) fp.Shape = solid # helper mehod to create the faces def make_face(self,v1,v2,v3): wire = Part.makePolygon([v1,v2,v3,v1]) face = Part.Face(wire) return face Then, we have the view provider object, responsible for showing the object in the 3D scene: class ViewProviderOctahedron: def __init__(self, obj): "Set this object to the proxy object of the actual view provider" obj.addProperty("App::PropertyColor","Color","Octahedron","Color of the octahedron").Color=(1.0,0.0,0.0) obj.Proxy = self def attach(self, obj): "Setup the scene sub-graph of the view provider, this method is mandatory" self.shaded = coin.SoGroup() self.wireframe = coin.SoGroup() self.scale = coin.SoScale() self.color = coin.SoBaseColor() self.data=coin.SoCoordinate3() self.face=coin.SoIndexedLineSet() self.shaded.addChild(self.scale) self.shaded.addChild(self.color) self.shaded.addChild(self.data) self.shaded.addChild(self.face) obj.addDisplayMode(self.shaded,"Shaded"); style=coin.SoDrawStyle() style.style = coin.SoDrawStyle.LINES self.wireframe.addChild(style) self.wireframe.addChild(self.scale) self.wireframe.addChild(self.color) self.wireframe.addChild(self.data) self.wireframe.addChild(self.face) obj.addDisplayMode(self.wireframe,"Wireframe"); self.onChanged(obj,"Color") def updateData&440;self, fp, prop): "If a property of the handled feature has changed we have the chance to handle this here" # fp is the handled feature, prop is the name of the property that has changed if prop == "Shape":

s = fp.getPropertyByName("Shape") self.data.point.setNum(6) cnt=0 for i in s.Vertexes: self.data.point.set1Value(cnt,i.X,i.Y,i.Z) cnt=cnt+1 self.face.coordIndex.set1Value(0,0) self.face.coordIndex.set1Value(1,1) self.face.coordIndex.set1Value(2,2) self.face.coordIndex.set1Value(3,-1) self.face.coordIndex.set1Value(4,1) self.face.coordIndex.set1Value(5,3) self.face.coordIndex.set1Value(6,2) self.face.coordIndex.set1Value(7,-1) self.face.coordIndex.set1Value(8,3) self.face.coordIndex.set1Value(9,4) self.face.coordIndex.set1Value(10,2) self.face.coordIndex.set1Value(11,-1) self.face.coordIndex.set1Value(12,4) self.face.coordIndex.set1Value(13,0) self.face.coordIndex.set1Value(14,2) self.face.coordIndex.set1Value(15,-1) self.face.coordIndex.set1Value(16,1) self.face.coordIndex.set1Value(17,0) self.face.coordIndex.set1Value(18,5) self.face.coordIndex.set1Value(19,-1) self.face.coordIndex.set1Value(20,3) self.face.coordIndex.set1Value(21,1) self.face.coordIndex.set1Value(22,5) self.face.coordIndex.set1Value(23,-1) self.face.coordIndex.set1Value(24,4) self.face.coordIndex.set1Value(25,3) self.face.coordIndex.set1Value(26,5) self.face.coordIndex.set1Value(27,-1) self.face.coordIndex.set1Value(28,0) self.face.coordIndex.set1Value(29,4) self.face.coordIndex.set1Value(30,5) self.face.coordIndex.set1Value(31,-1) def getDisplayModes(self,obj): "Return a list of display modes." modes=[] modes.append("Shaded") modes.append("Wireframe") return modes def getDefaultDisplayMode(self): "Return the name of the default display mode. It must be defined in getDisplayModes." return "Shaded" def setDisplayMode(self,mode): return mode def onChanged(self, vp, prop): "Here we can do something when a single property got changed" FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n") if prop == "Color": c = vp.getPropertyByName("Color") self.color.rgb.setValue(c[0],c[1],c[2]) def getIcon(self): return """ /* XPM */ static const char * ViewProviderBox_xpm[] = { "16 16 6 1", " c None", ". c #141010", "+ c #615BD2", "@ c #C39D55", "# c #000000", &6160; "$ c #57C355", " ........", " ......++..+..", " .@@@@.++..++.", " .@@@@.++..++.", " .@@ .++++++.", " ..@@ .++..++.",

"###@@@@ .++..++.", "##$.@@$#.++++++.", "#$#$.$$$........", "#$$####### ", "#$$#$$$$$# ", "#$$#$$$$$# ", "#$$#$$$$$# ", " #$#$$$$$# ", " ##$$$$$# ", " ####### "}; """ def __getstate__(self): return None def __setstate__(self,state): return None Finally, once our object and its viewobject are defined, we just need to call them: FreeCAD.newDocument() a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Octahedron") Octahedron(a) ViewProviderOctahedron(a.ViewObject)

Making objects selectable If you want to make your object selectable, or at least part of it, by clicking on it in the viewport, you must include its coin geometry inside a SoFCSelection node. If your object has complex representation, with widgets, annotations, etc, you might want to include only a part of it in a SoFCSelection. Everything that is a SoFCSelection is constantly scanned by FreeCAD to detect selection/preselection, so it makes sense try not to overload it with unneeded scanning. This is what you would do to include a self.face from the example above: selectionNode = coin.SoType.fromName("SoFCSelection").createInstance() selectionNode.documentName.setValue(FreeCAD.ActiveDocument.Name) selectionNode.objectName.setValue(obj.Object.Name) # here obj is the ViewObject, we need its associated App Object selectionNode.subElementName.setValue("Face") selectNode.addChild(self.face) ... self.shaded.addChild(selectionNode) self.wireframe.addChild(selectionNode) Simply, you create a SoFCSelection node, then you add your geometry nodes to it, then you add it to your main node, instead of adding your geometry nodes directly.

Working with simple shapes If your parametric object simply outputs a shape, you don't need to use a view provider object. The shape will be displayed using FreeCAD's standard shape representation: class Line: def __init__(self, obj): '''"App two point properties" ''' obj.addProperty("App::PropertyVector","p1","Line","Start point") obj.addProperty("App::PropertyVector","p2","Line","End point").p2=FreeCAD.Vector(1,0,0) obj.Proxy = self def execute(self, fp): '''"Print a short message when doing a recomputation, this method is mandatory" ''' fp.Shape = Part.makeLine(fp.p1,fp.p2) a=FreeCAD.ActiveDocument.addObject("Part::FeaturePython","Line") Line(a) a.ViewObject.Proxy=0 # just set it to something different from None (this assignment is needed to run an internal notification) FreeCAD.ActiveDocument.recompute() Same code with use ViewProviderLine import FreeCAD as App import FreeCADGui import FreeCAD import Part class Line: def __init__(self, obj): '''"App two point properties" ''' obj.addProperty("App::PropertyVector","p1","Line","Start point") obj.addProperty("App::PropertyVector","p2","Line","End

point").p2=FreeCAD.Vector(100,0,0) obj.Proxy = self def execute(self, fp): '''"Print a short message when doing a recomputation, this method is mandatory" ''' fp.Shape = Part.makeLine(fp.p1,fp.p2) class ViewProviderLine: def __init__(self, obj): ''' Set this object to the proxy object of the actual view provider ''' obj.Proxy = self def getDefaultDisplayMode(self): ''' Return the name of the default display mode. It must be defined in getDisplayModes. ''' return "Flat Lines" a=FreeCAD.ActiveDocument.addObject("Part::FeaturePython","Line") Line(a) ViewProviderLine(a.ViewObject) App.ActiveDocument.recompute()

Embedding FreeCAD FreeCAD has the amazing ability to be importable as a python module in other programs or in a standalone python console, together with all its modules and components. It's even possible to import the FreeCAD GUI as python module -- with some restrictions, however.

Using FreeCAD without GUI One first, direct, easy and useful application you can make of this is to import FreeCAD documents into your program. In the following example, we'll import the Part geometry of a FreeCAD document into blender. Here is the complete script. I hope you'll be impressed by its simplicity: FREECADPATH = '/opt/FreeCAD/lib' # path to your FreeCAD.so or FreeCAD.dll file import Blender, sys sys.path.append(FREECADPATH) def import_fcstd(filename): try: import FreeCAD except ValueError: Blender.Draw.PupMenu('Error%t|FreeCAD library not found. Please check the FREECADPATH variable in the import script is correct') else: scene = Blender.Scene.GetCurrent() import Part doc = FreeCAD.open(filename) objects = doc.Objects for ob in objects: if ob.Type[:4] == 'Part': shape = ob.Shape if shape.Faces: mesh = Blender.Mesh.New() rawdata = shape.tessellate(1) for v in rawdata[0]: mesh.verts.append((v.x,v.y,v.z)) for f in rawdata[1]: mesh.faces.append.append(f) scene.objects.new(mesh,ob.Name) Blender.Redraw() def main(): Blender.Window.FileSelector(import_fcstd, 'IMPORT FCSTD', Blender.sys.makename(ext='.fcstd')) # This lets you import the script without running it if __name__=='__main__': main() The first, important part is to make sure python will find our FreeCAD library. Once it finds it, all FreeCAD modules such as Part, that we'll use too, will be available automatically. So we simply take the sys.path variable, which is where python searches for modules, and we append the FreeCAD lib path. This modification is only temporary, and will be lost when we'll close our python interpreter. Another way could be making a link to your FreeCAD library in one of the python search paths. I kept the path in a constant (FREECADPATH) so it'll be easier for another user of the script to configure it to his own system. Once we are sure the library is loaded (the try/except sequence), we can now work with FreeCAD, the same way as we would inside FreeCAD's own python interpreter. We open the FreeCAD document that is passed to us by the main() function, and we make a list of its objects. Then, as we choosed only to care about Part geometry, we check if the Type property of each object contains "Part", then we tesselate it. The tesselation produce a list of vertices and a list of faces defined by vertices indexes. This is perfect, since it is exactly the same way as blender defines meshes. So, our task is ridiculously simple, we just add both lists contents to the verts and faces of a blender mesh. When everything is done, we just redraw the screen, and that's it! Of course this script is very simple (in fact I made a more advanced here), you might want to extend it, for example importing mesh objects too, or importing Part geometry that has no faces, or import other file formats that FreeCAD can read. You might also want to export geometry to a FreeCAD document, which can be done the same way. You might also want to build a dialog, so the user can choose what to import, etc... The beauty of all this actually lies in the fact that you let FreeCAD do the ground work while presenting its results in the program of your choice.

Using FreeCAD with GUI From version 4.2 on Qt has the intriguing ability to embed Qt-GUI-dependent plugins into non-Qt host applications and share the host's event loop. Especially, for FreeCAD this means that it can be imported from within another application with its whole user interface where the host application has full control over FreeCAD, then. The whole python code to achieve that has only two lines import FreeCADGui FreeCADGui.showMainWindow()

If the host application is based on Qt then this solution should work on all platforms which Qt supports. However, the host should link the same Qt version as FreeCAD because otherwise you could run into unexpected runtime errors. For non-Qt applications, however, there are a few limitations you must be aware of. This solution probably doesn't work together with all other toolkits. For Windows it works as long as the host application is directly based on Win32 or any other toolkit that internally uses the Win32 API such as wxWidgets, MFC or WinForms. In order to get it working under X11 the host application must link the "glib" library. Note, for any console application this solution of course doesn't work because there is no event loop running.

Embedding FreeCADGui You already know that you can import the FreeCAD module into a python application, and use all its tools from the host application. But the FreeCAD User Interface (GUI) can also be imported as a python module. Normally you can only import the complete interface as a whole, not pieces of it. That is because the FreeCAD interface system is not only made of independent widgets and toolbars, but is a complex construction where several invisible components (such as the selection system, etc) are needed for the main 3D view to be able to function. But, with a bit of hacking, it is possible to import the whole FreeCAD interface, then move the 3D view from it to your own Qt application. We show here 3 different methods.

Using the FreeCAD 3D view widget directly Be aware that there are a lot of problems with this approach. The Qt event handling doesn't seem to work (no idea why) and if you use the 3d view's context-menu the application crashes. A better way could be to create your own 3d view SoQtExaminerViewer or SoQtViewer and "push" the content of FreeCAD's 3d view to your view, as shown in the other sections below. First, get the main window via PyQt:

from PySide import QtGui from PySide import QtCore def getMainWindow(): toplevel = QtGui.qApp.topLevelWidgets() for i in toplevel: if i.metaObject().className() == "Gui::MainWindow": return i raise Exception("No main window found") mw=getMainWindow()

Then get the View3DInventor view the same way:

def get3dview(mw): childs=mw.findChildren(QtGui.QMainWindow) for i in childs: if i.metaObject().className()=="Gui::View3DInventor": return i return None v=get3dview(mw)

The following code is generated automatically, by creating a Ui-file with QtDesigner, and converting it to python code with the pyuic tool:

# -*- coding: utf-8 -* # Form implementation generated from reading ui file 'mainwindow.ui' # # Created: Sun Dec 27 11:18:56 2009 # by: PySide UI code generator 4.6 # # Modify for PySide 11/02/2015 # Python version: 2.7.8 # Qt version: 4.8.6 # # WARNING! All changes made in this file will be lost! from PySide import QtCore, QtGui class Ui_MainWindow(object): def setupUi(self, MainWindow): MainWindow.setObjectName("MainWindow") MainWindow.resize(508, 436) self.centralwidget = QtGui.QWidget(MainWindow) self.centralwidget.setObjectName("centralwidget") self.gridLayout = QtGui.QGridLayout(self.centralwidget) self.gridLayout.setObjectName("gridLayout") self.mdiArea = QtGui.QMdiArea(self.centralwidget) self.mdiArea.setViewMode(QtGui.QMdiArea.TabbedView) self.mdiArea.setTabPosition(QtGui.QTabWidget.South) self.mdiArea.setObjectName("mdiArea") self.gridLayout.addWidget(self.mdiArea, 0, 0, 1, 1) MainWindow.setCentralWidget(self.centralwidget) self.menubar = QtGui.QMenuBar(MainWindow) self.menubar.setGeometry(QtCore.QRect(0, 0, 508, 27)) self.menubar.setObjectName("menubar") MainWindow.setMenuBar(self.menubar) self.statusbar = QtGui.QStatusBar(MainWindow) self.statusbar.setObjectName("statusbar") MainWindow.setStatusBar(self.statusbar) self.retranslateUi(MainWindow) QtCore.QMetaObject.connectSlotsByName(MainWindow) def retranslateUi(self, MainWindow): MainWindow.setWindowTitle(QtGui.QApplication.translate("MainWindow", "MainWindow", None, QtGui.QApplication.UnicodeUTF8))

Then, create a main window that should be your application's main window, apply the UI setup above to it in order to add an

MDI area and "move" our 3d view to it

ui=Ui_MainWindow() my_mw=QtGui.QMainWindow() ui.setupUi(my_mw) ui.mdiArea.addSubWindow(v) my_mw.show()

Creating a soGui Examiner Viewer Alternatively, you can also use the FreeCADGui module to extract a coin/openInventor representation of the objects of your scene, then use that coin data in an external viewer (your application). Here is an easy way to get the 3d representation of an object:

FreeCAD.activeDocument().addObject("Part::Box","myBox") s=FreeCADGui.activeDocument().getObject("myBox").toString() # store as string from pivy import coin inp.setBuffer(s) myNode=coin.SoDB.readAll(inp) # restore from string

Then, create a standalone viewer with pivy:

from pivy.sogui import * from pivy.coin import * import sys def myViewer(): # Initialize Coin. This returns a main window to use. # If unsuccessful, exit. myWindow = SoGui.init(sys.argv[0]) if myWindow == None: sys.exit(1) # Make an empty scene and add our node to it scene = SoSeparator() scene.addChild(myNode) # Create a viewer in which to see our scene graph. viewer = SoGuiExaminerViewer(myWindow) # Put our scene into viewer, change the title viewer.setSceneGraph(scene) viewer.setTitle("FreeCAD Object Viewer") viewer.show() SoGui.show(myWindow) # Display main window SoGui.mainLoop() # Main Coin event loop

Then you just need to run your viewer:

myViewer()

Using the quarter module Instead of using the sogui viewer, you can also use the more modern quarter module. This is probably the best solution of the 3.

#!/usr/bin/env python ### # Copyright (c) 2002-2008 Kongsberg SIM # # Permission to use, copy, modify, and distribute this software for any # purpose with or without fee is hereby granted, provided that the above # copyright notice and this permission notice appear in all copies. # # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. # import os import sys from PyQt4 import QtCore, QtGui from PyQt4.QtGui import QMainWindow, QWorkspace, QAction, QFileDialog, QApplication from pivy.coin import SoInput, SoDB from pivy.quarter import QuarterWidget import FreeCAD, FreeCADGui def getMainWindow():

toplevel = QtGui.qApp.topLevelWidgets() for i in toplevel: if i.metaObject().className() == "Gui::MainWindow": return i raise Exception("No main window found") class MdiQuarterWidget(QuarterWidget): def __init__(self, parent, sharewidget): QuarterWidget.__init__(self, parent=parent, sharewidget=sharewidget) def loadFile(self, filename): in_ = SoInput() if (in_.openFile(str(filename.toLatin1()))): root = SoDB.readAll(in_) if (root): self.setSceneGraph(root) self.currentfile = filename self.setWindowTitle(filename) return True return False def currentFile(self): return self.currentfile def minimumSizeHint(self): return QtCore.QSize(640, 480) class MdiMainWindow(QMainWindow): def __init__(self, qApp): QMainWindow.__init__(self) self._firstwidget = None self._workspace = QWorkspace() self.setCentralWidget(self._workspace) self.setAcceptDrops(True) self.setWindowTitle("Pivy Quarter MDI example") filemenu = self.menuBar().addMenu("&File") windowmenu = self.menuBar().addMenu("&Windows") fileopenaction = QAction("&Create Box", self) fileexitaction = QAction("E&xit", self) tileaction = QAction("Tile", self) cascadeaction = QAction("Cascade", self) filemenu.addAction(fileopenaction) filemenu.addAction(fileexitaction) windowmenu.addAction(tileaction) windowmenu.addAction(cascadeaction) self.connect(fileopenaction, QtCore.SIGNAL("triggered()"), self.createBoxInFreeCAD) self.connect(fileexitaction, QtCore.SIGNAL("triggered()"), QtGui.qApp.closeAllWindows) self.connect(tileaction, QtCore.SIGNAL("triggered()"), self._workspace.tile) self.connect(cascadeaction, QtCore.SIGNAL("triggered()"), self._workspace.cascade) windowmapper = QtCore.QSignalMapper(self) self.connect(windowmapper, QtCore.SIGNAL("mapped(QWidget *)"), self._workspace.setActiveWindow) self.dirname = os.curdir def dragEnterEvent(self, event): # just accept anything... event.acceptProposedAction() def dropEvent(self, event): mimedata = event.mimeData() if mimedata.hasUrls(): path = mimedata.urls().takeFirst().path() self.open_path(path) def closeEvent(self, event): self._workspace.closeAllWindows() def open(self): self.open_path(QFileDialog.getOpenFileName(self, "", self.dirname)) def open_path(self, filename): self.dirname = os.path.dirname(str(filename.toLatin1())) if not filename.isEmpty(): existing = self.findMdiChild(filename) if existing: self._workspace.setActiveWindow(existing) return child = self.createMdiChild() if (child.loadFile(filename)): self.statusBar().showMessage("File loaded", 2000) child.show() else: child.close() def findMdiChild(self, filename): canonicalpath = QtCore.QFileInfo(filename).canonicalFilePath() for window in self._workspace.windowList(): mdiwidget = window if mdiwidget.currentFile() == canonicalpath: return mdiwidget return 0; def createMdiChild(self): widget = MdiQuarterWidget(None, self._firstwidget) self._workspace.addWindow(widget) if not self._firstwidget: self._firstwidget = widget

return widget def createBoxInFreeCAD(self): widget = MdiQuarterWidget(None, self._firstwidget) self._workspace.addWindow(widget) if not self._firstwidget: self._firstwidget = widget widget.show() doc = FreeCAD.newDocument() doc.addObject("Part::Box","myBox") iv_=FreeCADGui.getDocument(doc.Name).getObject("myBox").toString() in_ = SoInput() in_.setBuffer(iv_) root = SoDB.readAll(in_) if (root): widget.setSceneGraph(root) def main(): app = QApplication(sys.argv) mdi = MdiMainWindow(app) mdi.show() FreeCADGui.showMainWindow() # setup the GUI stuff of FreeCAD mw=getMainWindow() mw.hide() # hide all if len(sys.argv)==2: mdi.open_path(QtCore.QString(sys.argv[1])) sys.exit(app.exec_()) def show(): mdi = MdiMainWindow(QtGui.qApp) mdi.show() mw=getMainWindow() #mw.hide() # hide all if __name__ == '__main__': main()

Without even firing up the FreeCAD Gui Starting from FreeCAD rev2760, it is now possible to obtain the coin representation of any FreeCAD object without opening the main window. This makes it extremely easy to implement your own viewer and transparently have FreeCAD updating it. After importing the FreeCADGui module, you need to fire it up with the setupWithoutGUI() method, after which you can use all of FreeCAD's view providers to obtain coin/openInventor nodes.

import os, sys, FreeCAD, FreeCADGui from PyQt4 import QtCore, QtGui from PyQt4.QtGui import QMainWindow, QWorkspace, QAction, QFileDialog, QApplication from pivy.coin import SoInput, SoDB, sogui class MdiMainWindow(QMainWindow): def __init__(self, qApp): QMainWindow.__init__(self) self._firstwidget = None self._workspace = QWorkspace() self.setCentralWidget(self._workspace) self.setAcceptDrops(True) self.setWindowTitle("Pivy Quarter MDI example") self.viewers=[] filemenu = self.menuBar().addMenu("&File") windowmenu = self.menuBar().addMenu("&Windows") fileopenaction = QAction("&Create Box", self) fileexitaction = QAction("E&xit", self) tileaction = QAction("Tile", self) cascadeaction = QAction("Cascade", self) filemenu.addAction(fileopenaction) filemenu.addAction(fileexitaction) windowmenu.addAction(tileaction) windowmenu.addAction(cascadeaction) self.connect(fileopenaction, QtCore.SIGNAL("triggered()"), self.createBoxInFreeCAD) self.connect(fileexitaction, QtCore.SIGNAL("triggered()"), QtGui.qApp.closeAllWindows) self.connect(tileaction, QtCore.SIGNAL("triggered()"), self._workspace.tile) self.connect(cascadeaction, QtCore.SIGNAL("triggered()"), self._workspace.cascade) windowmapper = QtCore.QSignalMapper(self) self.connect(windowmapper, QtCore.SIGNAL("mapped(QWidget *)"), self._workspace.setActiveWindow) def closeEvent(self, event): self._workspace.closeAllWindows() def createBoxInFreeCAD(self): widget = QtGui.QWidget(self._firstwidget) viewer = sogui.SoGuiExaminerViewer(widget) self._workspace.addWindow(widget) if not self._firstwidget: self._firstwidget = widget widget.show() self.viewers.append(viewer) doc = FreeCAD.newDocument() obj=doc.addObject("Part::Box","myBox") doc.recompute() root=FreeCADGui.subgraphFromObject(obj) viewer.setSceneGraph(root)

def main(): app = QApplication(sys.argv) mdi = MdiMainWindow(app) mdi.show() FreeCADGui.setupWithoutGUI() sys.exit(app.exec_()) if __name__ == '__main__': main()

Or, if using pivy's sogui module doesn't work for you (the sogui module is becoming obsoleted and the coin developers are now favoring the new quarter library, which has much better interaction with qt), this is the same script but with using quarter:

#!/usr/bin/env python import os import sys from PyQt4 import QtCore, QtGui from PyQt4.QtGui import QMainWindow, QWorkspace, QAction, QApplication from pivy.coin import SoInput, SoDB from pivy.quarter import QuarterWidget import FreeCADGui class MdiQuarterWidget(QuarterWidget): def __init__(self, parent, sharewidget): QuarterWidget.__init__(self, parent=parent, sharewidget=sharewidget) def minimumSizeHint(self): return QtCore.QSize(640, 480) class MdiMainWindow(QMainWindow): def __init__(self, qApp): QMainWindow.__init__(self) self._firstwidget = None self._workspace = QWorkspace() self.setCentralWidget(self._workspace) self.setAcceptDrops(True) self.setWindowTitle("Pivy Quarter MDI example") filemenu = self.menuBar().addMenu("&File") windowmenu = self.menuBar().addMenu("&Windows") fileopenaction = QAction("&Create Box", self) fileexitaction = QAction("E&xit", self) tileaction = QAction("Tile", self) cascadeaction = QAction("Cascade", self) filemenu.addAction(fileopenaction) filemenu.addAction(fileexitaction) windowmenu.addAction(tileaction) windowmenu.addAction(cascadeaction) self.connect(fileopenaction, QtCore.SIGNAL("triggered()"), self.createBoxInFreeCAD) self.connect(fileexitaction, QtCore.SIGNAL("triggered()"), QtGui.qApp.closeAllWindows) self.connect(tileaction, QtCore.SIGNAL("triggered()"), self._workspace.tile) self.connect(cascadeaction, QtCore.SIGNAL("triggered()"), self._workspace.cascade) windowmapper = QtCore.QSignalMapper(self) self.connect(windowmapper, QtCore.SIGNAL("mapped(QWidget *)"), self._workspace.setActiveWindow) self.dirname = os.curdir def closeEvent(self, event): self._workspace.closeAllWindows() def createBoxInFreeCAD(self): d=FreeCAD.newDocument() o=d.addObject("Part::Box") d.recompute() s=FreeCADGui.subgraphFromObject(o) child = self.createMdiChild() child.show() child.setSceneGraph(s) def createMdiChild(self): widget = MdiQuarterWidget(None, self._firstwidget) self._workspace.addWindow(widget) if not self._firstwidget: self._firstwidget = widget return widget def main(): FreeCADGui.setupWithoutGUI() app = QApplication(sys.argv) mdi = MdiMainWindow(app) mdi.show() sys.exit(app.exec_()) if __name__ == '__main__': main()

Code snippets This page contains examples, pieces, chunks of FreeCAD python code collected from users experiences and discussions on the forums. Read and use it as a start for your own scripts...

A typical InitGui.py file Every module must contain, besides your main module file, an InitGui.py file, responsible for inserting the module in the main Gui. This is an example of a simple one. class ScriptWorkbench (Workbench): MenuText = "Scripts" def Initialize(self): import Scripts # assuming Scripts.py is your module list = ["Script_Cmd"] # That list must contain command names, that can be defined in Scripts.py self.appendToolbar("My Scripts",list) Gui.addWorkbench(ScriptWorkbench())

A typical module file This is an example of a main module file, containing everything your module does. It is the Scripts.py file invoked by the previous example. You can have all your custom commands here. import FreeCAD, FreeCADGui class ScriptCmd: def Activated(self): # Here your write what your ScriptCmd does... FreeCAD.Console.PrintMessage('Hello, World!') def GetResources(self): return {'Pixmap' : 'path_to_an_icon/myicon.png', 'MenuText': 'Short text', 'ToolTip': 'More detailed text'} FreeCADGui.addCommand('Script_Cmd', ScriptCmd())

Import a new filetype Making an importer for a new filetype in FreeCAD is easy. FreeCAD doesn't consider that you import data in an opened document, but rather that you simply can directly open the new filetype. So what you need to do is to add the new file extension to FreeCAD's list of known extensions, and write the code that will read the file and create the FreeCAD objects you want: This line must be added to the InitGui.py file to add the new file extension to the list: # Assumes Import_Ext.py is the file that has the code for opening and reading .ext files FreeCAD.addImportType("Your new File Type (*.ext)","Import_Ext") Then in the Import_Ext.py file: def open(filename): doc=App.newDocument() # here you do all what is needed with filename, read, classify data, create corresponding FreeCAD objects doc.recompute() To export your document to some new filetype works the same way, except that you use: FreeCAD.addExportType("Your new File Type (*.ext)","Export_Ext")

Adding a line A line simply has 2 points. import Part,PartGui doc=App.activeDocument() # add a line element to the document and set its points l=Part.Line() l.StartPoint=(0.0,0.0,0.0) l.EndPoint=(1.0,1.0,1.0) doc.addObject("Part::Feature","Line").Shape=l.toShape() doc.recompute()

Adding a polygon A polygon is simply a set of connected line segments (a polyline in AutoCAD). It doesn't need to be closed.

import Part,PartGui doc=App.activeDocument() n=list() # create a 3D vector, set its coordinates and add it to the list v=App.Vector(0,0,0) n.append(v) v=App.Vector(10,0,0) n.append(v) #... repeat for all nodes # Create a polygon object and set its nodes p=doc.addObject("Part::Polygon","Polygon") p.Nodes=n doc.recompute()

Adding and removing an object to a group doc=App.activeDocument() grp=doc.addObject("App::DocumentObjectGroup", "Group") lin=doc.addObject("Part::Feature", "Line") grp.addObject(lin) # adds the lin object to the group grp grp.removeObject(lin) # removes the lin object from the group grp Note: You can even add other groups to a group...

Adding a Mesh import Mesh doc=App.activeDocument() # create a new empty mesh m = Mesh.Mesh() # build up box out of 12 facets m.addFacet(0.0,0.0,0.0, 0.0,0.0,1.0, 0.0,1.0,1.0) m.addFacet(0.0,0.0,0.0, 0.0,1.0,1.0, 0.0,1.0,0.0) m.addFacet(0.0,0.0,0.0, 1.0,0.0,0.0, 1.0,0.0,1.0) m.addFacet(0.0,0.0,0.0, 1.0,0.0,1.0, 0.0,0.0,1.0) m.addFacet(0.0,0.0,0.0, 0.0,1.0,0.0, 1.0,1.0,0.0) m.addFacet(0.0,0.0,0.0, 1.0,1.0,0.0, 1.0,0.0,0.0) m.addFacet(0.0,1.0,0.0, 0.0,1.0,1.0, 1.0,1.0,1.0) m.addFacet(0.0,1.0,0.0, 1.0,1.0,1.0, 1.0,1.0,0.0) m.addFacet(0.0,1.0,1.0, 0.0,0.0,1.0, 1.0,0.0,1.0) m.addFacet(0.0,1.0,1.0, 1.0,0.0,1.0, 1.0,1.0,1.0) m.addFacet(1.0,1.0,0.0, 1.0,1.0,1.0, 1.0,0.0,1.0) m.addFacet(1.0,1.0,0.0, 1.0,0.0,1.0, 1.0,0.0,0.0) # scale to a edge langth of 100 m.scale(100.0) # add the mesh to the active document me=doc.addObject("Mesh::Feature","Cube") me.Mesh=m

Adding an arc or a circle import Part doc = App.activeDocument() c = Part.Circle() c.Radius=10.0 f = doc.addObject("Part::Feature", "Circle") # create a document with a circle feature f.Shape = c.toShape() # Assign the circle shape to the shape property doc.recompute()

Accessing and changing representation of an object Each object in a FreeCAD document has an associated view representation object that stores all the parameters that define how the object appear, like color, linewidth, etc... gad=Gui.activeDocument() # access the active document containing all # view representations of the features in the # corresponding App document v=gad.getObject("Cube") # access the view representation to the Mesh feature 'Cube' v.ShapeColor # prints the color to the console v.ShapeColor=(1.0,1.0,1.0) # sets the shape color to white

Observing mouse events in the 3D viewer via Python The Inventor framework allows to add one or more callback nodes to the scenegraph of the viewer. By default in FreeCAD one callback node is installed per viewer which allows to add global or static C++ functions. In the appropriate Python binding some methods are provided to make use of this technique from within Python code. App.newDocument() v=Gui.activeDocument().activeView()

#This class logs any mouse button events. As the registered callback function fires twice for 'down' and #'up' events we need a boolean flag to handle this. class ViewObserver: def logPosition(self, info): down = (info["State"] == "DOWN") pos = info["Position"] if (down): FreeCAD.Console.PrintMessage("Clicked on position: ("+str(pos[0])+", "+str(pos[1])+")\n") o = ViewObserver() c = v.addEventCallback("SoMouseButtonEvent",o.logPosition) Now, pick somewhere on the area in the 3D viewer and observe the messages in the output window. To finish the observation just call v.removeEventCallback("SoMouseButtonEvent",c) The following event types are supported SoEvent -- all kind of events SoButtonEvent -- all mouse button and key events SoLocation2Event -- 2D movement events (normally mouse movements) SoMotion3Event -- 3D movement events (normally spaceball) SoKeyboardEvent -- key down and up events SoMouseButtonEvent -- mouse button down and up events SoSpaceballButtonEvent -- spaceball button down and up events The Python function that can be registered with addEventCallback() expects a dictionary. Depending on the watched event the dictionary can contain different keys. For all events it has the keys: Type -- the name of the event type i.e. SoMouseEvent, SoLocation2Event, ... Time -- the current time as string Position -- a tuple of two integers, mouse position ShiftDown -- a boolean, true if Shift was pressed otherwise false CtrlDown -- a boolean, true if Ctrl was pressed otherwise false AltDown -- a boolean, true if Alt was pressed otherwise false For all button events, i.e. keyboard, mouse or spaceball events State -- A string 'UP' if the button was up, 'DOWN' if it was down or 'UNKNOWN' for all other cases For keyboard events: Key -- a character of the pressed key For mouse button event Button -- The pressed button, could be BUTTON1, ..., BUTTON5 or ANY For spaceball events: Button -- The pressed button, could be BUTTON1, ..., BUTTON7 or ANY And finally motion events: Translation -- a tuple of three floats Rotation -- a quaternion for the rotation, i.e. a tuple of four floats

Manipulate the scenegraph in Python It is also possible to get and change the scenegraph in Python, with the 'pivy' module -- a Python binding for Coin. from pivy.coin import * # load the pivy module view = Gui.ActiveDocument.ActiveView # get the active viewer root = view.getSceneGraph() # the root is an SoSeparator node root.addChild(SoCube()) view.fitAll() The Python API of pivy is created by using the tool SWIG. As we use in FreeCAD some self-written nodes you cannot create them directly in Python. However, it is possible to create a node by its internal name. An instance of the type 'SoFCSelection' can be created with type = SoType.fromName("SoFCSelection") node = type.createInstance()

Adding and removing objects to/from the scenegraph Adding new nodes to the scenegraph can be done this way. Take care of always adding a SoSeparator to contain the geometry, coordinates and material info of a same object. The following example adds a red line from (0,0,0) to (10,0,0): from pivy import coin sg = Gui.ActiveDocument.ActiveView.getSceneGraph() co = coin.SoCoordinate3() pts = [[0,0,0],[10,0,0]] co.point.setValues(0,len(pts),pts) ma = coin.SoBaseColor() ma.rgb = (1,0,0) li = coin.SoLineSet() li.numVertices.setValue(2) no = coin.SoSeparator() no.addChild(co) no.addChild(ma) no.addChild(li) sg.addChild(no) To remove it, simply issue: sg.removeChild(no)

Adding custom widgets to the interface You can create custom widgets with Qt designer, transform them into a python script, and then load them into the FreeCAD interface with PyQt4. The python code produced by the Ui python compiler (the tool that converts qt-designer .ui files into python code) generally looks like this (it is simple, you can also code it directly in python): class myWidget_Ui(object): def setupUi(self, myWidget): myWidget.setObjectName("my Nice New Widget") myWidget.resize(QtCore.QSize(QtCore.QRect(0,0,300,100).size()).expandedTo(myWidget.minimumSizeHint())) # sets size of the widget self.label = QtGui.QLabel(myWidget) # creates a label self.label.setGeometry(QtCore.QRect(50,50,200,24)) # sets its size self.label.setObjectName("label") # sets its name, so it can be found by name def retranslateUi(self, draftToolbar): # built-in QT function that manages translations of widgets myWidget.setWindowTitle(QtGui.QApplication.translate("myWidget", "My Widget", None, QtGui.QApplication.UnicodeUTF8)) self.label.setText(QtGui.QApplication.translate("myWidget", "Welcome to my new widget!", None, QtGui.QApplication.UnicodeUTF8)) Then, all you need to do is to create a reference to the FreeCAD Qt window, insert a custom widget into it, and "transform" this widget into yours with the Ui code we just made: app = QtGui.qApp FCmw = app.activeWindow() # the active qt window, = the freecad window since we are inside it myNewFreeCADWidget = QtGui.QDockWidget() # create a new dckwidget myNewFreeCADWidget.ui = myWidget_Ui() # load the Ui script myNewFreeCADWidget.ui.setupUi(myNewFreeCADWidget) # setup the ui FCmw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myNewFreeCADWidget) # add the widget to the main window

Adding a Tab to the Combo View The following code allows you to add a tab to the FreeCAD ComboView, besides the "Project" and "Tasks" tabs. It also uses the uic module to load an ui file directly in that tab. # create new Tab in ComboView from PySide import QtGui,QtCore #from PySide import uic def getMainWindow(): "returns the main window" # using QtGui.qApp.activeWindow() isn't very reliable because if another # widget than the mainwindow is active (e.g. a dialog) the wrong widget is # returned toplevel = QtGui.qApp.topLevelWidgets() for i in toplevel: if i.metaObject().className() == "Gui::MainWindow": return i raise Exception("No main window found") def getComboView(mw): dw=mw.findChildren(QtGui.QDockWidget)

for i in dw: if str(i.objectName()) == "Combo View": return i.findChild(QtGui.QTabWidget) elif str(i.objectName()) == "Python Console": return i.findChild(QtGui.QTabWidget) raise Exception ("No tab widget found") mw = getMainWindow() tab = getComboView(getMainWindow()) tab2=QtGui.QDialog() tab.addTab(tab2,"A Special Tab") #uic.loadUi("/myTaskPanelforTabs.ui",tab2) tab2.show() #tab.removeTab(2)

Enable or disable a window from PySide import QtGui mw=FreeCADGui.getMainWindow() dws=mw.findChildren(QtGui.QDockWidget) # objectName may be : # "Report view" # "Tree view" # "Property view" # "Selection view" # "Combo View" # "Python console" # "draftToolbar" for i in dws: if i.objectName() == "Report view": dw=i break va=dw.toggleViewAction() va.setChecked(True) # True or False dw.setVisible(True) # True or False

Opening a custom webpage import WebGui WebGui.openBrowser("http://www.example.com")

Getting the HTML contents of an opened webpage from PyQt4 import QtGui,QtWebKit a = QtGui.qApp mw = a.activeWindow() v = mw.findChild(QtWebKit.QWebFrame) html = unicode(v.toHtml()) print html

Retrieve and use the coordinates of 3 selected points or objects # -*- coding: utf-8 -*# the line above to put the accentuated in the remarks # If this line is missing, an error will be returned # extract and use the coordinates of 3 objects selected import Part, FreeCAD, math, PartGui, FreeCADGui from FreeCAD import Base, Console sel = FreeCADGui.Selection.getSelection() # " sel " contains the items selected if len(sel)!=3 : # If there are no 3 objects selected, an error is displayed in the report view # The \r and \n at the end of line mean return and the newline CR + LF. Console.PrintError("Select 3 points exactly\r\n") else : points=[] for obj in sel: points.append(obj.Shape.BoundBox.Center) for pt in points: # display of the coordinates in the report view Console.PrintMessage(str(pt.x)+"\r\n") Console.PrintMessage(str(pt.y)+"\r\n") Console.PrintMessage(str(pt.z)+"\r\n") Console.PrintMessage(str(pt[1]) + "\r\n")

List all objects

# -*- coding: utf-8 -*import FreeCAD,Draft # List all objects of the document doc = FreeCAD.ActiveDocument objs = FreeCAD.ActiveDocument.Objects #App.Console.PrintMessage(str(objs) + "\n") #App.Console.PrintMessage(str(len(FreeCAD.ActiveDocument.Objects)) + " Objects" + "\n") for obj in objs: a = obj.Name # list the Name of the object (not modifiable) b = obj.Label # list the Label of the object (modifiable) try: c = obj.LabelText # list the LabeText of the text (modifiable) App.Console.PrintMessage(str(a) +" "+ str(b) +" "+ str(c) + "\n") # Displays the Name the Label and the text except: App.Console.PrintMessage(str(a) +" "+ str(b) + "\n") # Displays the Name and the Label of the object #doc.removeObject("Box") # Clears the designated object

Function resident with the mouse click action # -*- coding: utf-8 -*# causes an action to the mouse click on an object # This function remains resident (in memory) with the function "addObserver(s)" # "removeObserver(s) # Uninstalls the resident function class SelObserver: def addSelection(self,doc,obj,sub,pnt): # Selection object #def setPreselection(self,doc,obj,sub): # Preselection object App.Console.PrintMessage("addSelection"+ "\n") App.Console.PrintMessage(str(doc)+ "\n") # Name of the document App.Console.PrintMessage(str(obj)+ "\n") # Name of the object App.Console.PrintMessage(str(sub)+ "\n") # The part of the object name App.Console.PrintMessage(str(pnt)+ "\n") # Coordinates of the object App.Console.PrintMessage("______"+ "\n") def removeSelection(self,doc,obj,sub): # Delete the selected object App.Console.PrintMessage("removeSelection"+ "\n") def setSelection(self,doc): # Selection in ComboView App.Console.PrintMessage("setSelection"+ "\n") def clearSelection(self,doc): # If click on the screen, clear the selection App.Console.PrintMessage("clearSelection"+ "\n") # If click on another object, clear the previous object s =SelObserver() FreeCADGui.Selection.addObserver(s) # install the function mode resident #FreeCADGui.Selection.removeObserver(s) # Uninstall the resident function

List the components of an object # -*- coding: utf-8 -*# This function list the components of an object # and extract this object its XYZ coordinates, # its edges and their lengths center of mass and coordinates # its faces and their center of mass # its faces and their surfaces and coordinates # 8/05/2014 import Draft,Part def detail(): sel = FreeCADGui.Selection.getSelection() # Select an object if len(sel) != 0: # If there is a selection then Vertx=[] Edges=[] Faces=[] compt_V=0 compt_E=0 compt_F=0 pas =0 perimetre = 0.0 EdgesLong = [] # Displays the "Name" and the "Label" of the selection App.Console.PrintMessage("Selection > " + str(sel[0].Name) + " " + str(sel[0].Label) +"\n"+"\n") for j in enumerate(sel[0].Shape.Edges): # Search the "Edges" and their lengths compt_E+=1

Edges.append("Edge%d" % (j[0]+1)) EdgesLong.append(str(sel[0].Shape.Edges[compt_E-1].Length)) perimetre += (sel[0].Shape.Edges[compt_E-1].Length) # calculates the perimeter # Displays the "Edge" and its length App.Console.PrintMessage("Edge"+str(compt_E)+" Length > "+str&040;sel[0].Shape.Edges[compt_E-1].Length)+"\n") # Displays the "Edge" and its center mass App.Console.PrintMessage("Edge"+str(compt_E)+" Center > "+str(sel[0].Shape.Edges[compt_E-1].CenterOfMass)+"\n") num = sel[0].Shape.Edges[compt_E-1].Vertexes[0] Vertx.append("X1: "+str(num.Point.x)) Vertx.append("Y1: "+str(num.Point.y)) Vertx.append("Z1: "+str(num.Point.z)) # Displays the coordinates 1 App.Console.PrintMessage("X1: "+str(num.Point[0])+" Y1: "+str(num.Point[1])+" Z1: "+str(num.Point[2])+"\n") try: num = sel[0].Shape.Edges[compt_E-1].Vertexes[1] Vertx.append("X2: "+str(num.Point.x)) Vertx.append("Y2: "+str(num.Point.y)) Vertx.append("Z2: "+str(num.Point.z)) except: Vertx.append("-") Vertx.append("-") Vertx.append("-") # Displays the coordinates 2 App.Console.PrintMessage("X2: "+str(num.Point[0])+" Y2: "+str(num.Point[1])+" Z2: "+str(num.Point[2])+"\n") App.Console.PrintMessage("\n") App.Console.PrintMessage("Perimeter of the form : "+str(perimetre)+"\n") App.Console.PrintMessage("\n") FacesSurf = [] for j in enumerate(sel[0].Shape.Faces): # Search the "Faces" and their surface compt_F+=1 Faces.append("Face%d" % (j[0]+1)) FacesSurf.append(str(sel[0].Shape.Faces[compt_F-1].Area)) # Displays 'Face' and its surface App.Console.PrintMessage("Face"+str(compt_F)+" > Surface "+str(sel[0].Shape.Faces[compt_F-1].Area)+"\n") # Displays 'Face' and its CenterOfMass App.Console.PrintMessage("Face"+str(compt_F)+" > Center "+str(sel[0].Shape.Faces[compt_F-1].CenterOfMass)+"\n") # Displays 'Face' and its Coordinates FacesCoor = [] fco = 0 for f0 in sel[0].Shape.Faces[compt_F-1].Vertexes: # Search the Vertexes of the face fco += 1 FacesCoor.append("X"+str(fco)+": "+str(f0.Point.x)) FacesCoor.append("Y"+str(fco)+": "+str(f0.Point.y)) FacesCoor.append("Z"+str(fco)+": "+str(f0.Point.z)) # Displays 'Face' and its Coordinates App.Console.PrintMessage("Face"+str(compt_F)+" > Coordinate"+str(FacesCoor)+"\n") # Displays 'Face' and its Volume App.Console.PrintMessage("Face"+str(compt_F)+" > Volume "+str(sel[0].Shape.Faces[compt_F-1].Volume)+"\n") App.Console.PrintMessage("\n") # Displays the total surface of the form App.Console.PrintMessage("Surface of the form : "+str(sel[0].Shape.Area)+"\n") # Displays the total Volume of the form App.Console.PrintMessage("Volume of the form : "+str(sel[0].Shape.Volume)+"\n") detail()

List the PropertiesList import FreeCADGui from FreeCAD import Console o = App.ActiveDocument.ActiveObject

op = o.PropertiesList for p in op: Console.PrintMessage("Property: "+ str(p)+ " Value: " + str(o.getPropertyByName(p))+"\r\n")

Search and data extraction Examples of research and decoding information on an object. Each section is independently and is separated by "############" can be copied directly into the Python console, or in a macro or use this macro. The description of the macro in the commentary. Displaying it in the "View Report" window (View > Views > View report) # -*- coding: utf-8 -*from __future__ import unicode_literals # Exemples de recherche et de decodage d'informations sur un objet # Chaque section peut etre copiee directement dans la console Python ou dans une macro ou utilisez la macro tel quel # certaines commandes se repetent seul l'approche est differente # # Examples of research and decoding information on an object # Each section can be copied directly into the Python console, or in a macro or uses this macro # Certain commands as repeat alone approach is different # # rev:29/09/2014 from FreeCAD import Base import DraftVecUtils, Draft, Part mydoc = FreeCAD.activeDocument().Name # Name of active Document App.Console.PrintMessage("Active docu : "+str(mydoc)+"\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() object_Label = sel[0].Label # Label of the object (modifiable) App.Console.PrintMessage("object_Label : "+str(object_Label)+"\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() App.Console.PrintMessage("sel : "+str(sel[0])+"\n\n") # sel[0] first object selected ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() object_Name = sel[0].Name # Name of the object (not modifiable) App.Console.PrintMessage("object_Name : "+str(object_Name)+"\n\n") ################################################################################## try: SubElement = FreeCADGui.Selection.getSelectionEx() # sub element name with getSelectionEx() element_ = SubElement[0].SubElementNames[0] # name of 1 element selected App.Console.PrintMessage("elementSelec : "+str(element_)+"\n\n") except: App.Console.PrintMessage("Oups"+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() App.Console.PrintMessage("sel : "+str(sel[0])+"\n\n") # sel[0] first object selected ################################################################################## SubElement = FreeCADGui.Selection.getSelectionEx() # sub element name with getSelectionEx() App.Console.PrintMessage("SubElement : "+str(SubElement[0])+"\n\n") # name of sub element ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() i = 0 for j in enumerate(sel[0].Shape.Edges): # list all Edges i += 1 App.Console.PrintMessage("Edges n : "+str(i)+"\n") a = sel[0].Shape.Edges[j[0]].Vertexes[0] App.Console.PrintMessage("X1 : "+str(a.Point.x)+"\n") # coordinate XYZ first

point App.Console.PrintMessage("Y1 : "+str(a.Point.y)+"\n") App.Console.PrintMessage("Z1 : "+str(a.Point.z)+"\n") try: a = sel[0].Shape.Edges[j[0]].Vertexes[1] App.Console.PrintMessage("X2 : "+str(a.Point.x)+"\n") # coordinate XYZ second point App.Console.PrintMessage("Y2 : "+str(a.Point.y)+"\n") App.Console.PrintMessage("Z2 : "+str(a.Point.z)+"\n") except: App.Console.PrintMessage("Oups"+"\n") App.Console.PrintMessage("\n") ################################################################################## try: SubElement = FreeCADGui.Selection.getSelectionEx() # sub element name with getSelectionEx() subElementName = Gui.Selection.getSelectionEx()[0].SubElementNames[0] # sub element name with getSelectionEx() App.Console.PrintMessage("subElementName : "+str(subElementName)+"\n") subObjectX = Gui.Selection.getSelectionEx()[0].SubObjects[0].Point.x # sub element coordinate X App.Console.PrintMessage("subObject_X : "+str(subObjectX)+"\n") subObjectY = Gui.Selection.getSelectionEx()[0].SubObjects[0].Point.y # sub element coordinate Y App.Console.PrintMessage("subObject_Y : "+str(subObjectY)+"\n") subObjectZ = Gui.Selection.getSelectionEx()[0].SubObjects[0].Point.z # sub element coordinate Z App.Console.PrintMessage("subObject_Z : "+str(subObjectZ)+"\n") subObjectLength = Gui.Selection.getSelectionEx()[0].SubObjects[0].Length # sub element Length App.Console.PrintMessage("subObjectLength: "+str(subObjectLength)+"\n") surfaceFace = Gui.Selection.getSelectionEx()[0].SubObjects[0].Area # Area of the 1 face App.Console.PrintMessage("surfaceFace : "+str(surfaceFace)+"\n\n") except: App.Console.PrintMessage("Oups"+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() surface = sel[0].Shape.Area # Area object complete App.Console.PrintMessage("surfaceObjet : "+str(surface)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() CenterOfMass = sel[0].Shape.CenterOfMass # Center of Mass of the object App.Console.PrintMessage("CenterOfMass : "+str(CenterOfMass)+"\n") App.Console.PrintMessage("CenterOfMassX : "+str(CenterOfMass[0])+"\n") # coordinates [0]=X [1]=Y [2]=Z App.Console.PrintMessage("CenterOfMassY : "+str(CenterOfMass[1])+"\n") App.Console.PrintMessage("CenterOfMassZ : "+str(CenterOfMass[2])+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() for j in enumerate(sel[0].Shape.Faces): # List alles faces of the object App.Console.PrintMessage("Face : "+str("Face%d" % (j[0]+1))+"\n") App.Console.PrintMessage("\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() volume_ = sel[0].Shape.Volume # Volume of the object App.Console.PrintMessage("volume_ : "+str(volume_)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() boundBox_= sel[0].Shape.BoundBox # BoundBox of the object App.Console.PrintMessage("boundBox_ : "+str(boundBox_)+"\n") boundBoxLX = boundBox_.XLength # Length x boundBox rectangle boundBoxLY = boundBox_.YLength # Length y boundBox rectangle boundBoxLZ = boundBox_.ZLength # Length z boundBox rectangle App.Console.PrintMessage("boundBoxLX : "+str(boundBoxLX)+"\n")

App.Console.PrintMessage("boundBoxLY : "+str(boundBoxLY)+"\n") App.Console.PrintMessage("boundBoxLZ : "+str(boundBoxLZ)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() pl = sel[0].Shape.Placement # Placement Vector XYZ and Yaw-Pitch-Roll App.Console.PrintMessage("Placement : "+str(pl)+"\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() pl = sel[0].Shape.Placement.Base # Placement Vector XYZ App.Console.PrintMessage("PlacementBase : "+str(pl)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() Yaw = sel[0].Shape.Placement.Rotation.toEuler()[0] # decode angle Euler Yaw App.Console.PrintMessage("Yaw : "+str(Yaw)+"\n") Pitch = sel[0].Shape.Placement.Rotation.toEuler()[1] # decode angle Euler Pitch App.Console.PrintMessage("Pitch : "+str(Pitch)+"\n") Roll = sel[0].Shape.Placement.Rotation.toEuler()[2] # decode angle Euler Yaw App.Console.PrintMessage("Yaw : "+str(Roll)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() oripl_X = sel[0].Placement.Base[0] # decode Placement X oripl_Y = sel[0].Placement.Base[1] # decode Placement Y oripl_Z = sel[0].Placement.Base[2] # decode Placement Z App.Console.PrintMessage("oripl_X : "+str(oripl_X)+"\n") App.Console.PrintMessage("oripl_Y : "+str(oripl_Y)+"\n") App.Console.PrintMessage("oripl_Z : "+str(oripl_Z)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() rotation = sel[0].Placement.Rotation # decode Placement Rotation App.Console.PrintMessage("rotation : "+str(rotation)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() pl = sel[0].Shape.Placement.Rotation # decode Placement Rotation other method App.Console.PrintMessage("Placement Rot : "+str(pl)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() pl = sel[0].Shape.Placement.Rotation.Angle # decode Placement Rotation Angle App.Console.PrintMessage("Placement Rot Angle : "+str(pl)+"\n\n") ################################################################################## sel = FreeCADGui.Selection.getSelection() # select object with getSelection() Rot_0 = sel[0].Placement.Rotation.Q[0] # decode Placement Rotation 0 App.Console.PrintMessage("Rot_0 : "+str(Rot_0)+ " rad , "+str(180 * Rot_0 / 3.1416)+" deg "+"\n") Rot_1 = sel[0].Placement.Rotation.Q[1] # decode Placement Rotation 1 App.Console.PrintMessage("Rot_1 : "+str(Rot_1)+ " rad , "+str(180 * Rot_1 / 3.1416)+" deg "+"\n") Rot_2 = sel[0].Placement.Rotation.Q[2] # decode Placement Rotation 2 App.Console.PrintMessage("Rot_2 : "+str(Rot_2)+ " rad , "+str(180 * Rot_2 / 3.1416)+" deg "+"\n") Rot_3 = sel[0].Placement.Rotation.Q[3] # decode Placement Rotation 3 App.Console.PrintMessage("Rot_3 : "+str(Rot_3)+"\n\n") ################################################################################## Manual search of an element with label

# Extract the coordinate X,Y,Z and Angle giving the label App.Console.PrintMessage("Base.x : "+str(FreeCAD.ActiveDocument.getObjectsByLabel("Cylindre")[0].Placement.Base.x)+"\n") App.Console.PrintMessage("Base.y : "+str(FreeCAD.ActiveDocument.getObjectsByLabel("Cylindre")[0].Placement.Base.y)+"\n") App.Console.PrintMessage("Base.z : "+str(FreeCAD.ActiveDocument.getObjectsByLabel("Cylindre")[0].Placement.Base.z)+"\n") App.Console.PrintMessage("Base.Angle : "+str(FreeCAD.ActiveDocument.getObjectsByLabel("Cylindre")[0].Placement.Rotation.Angle)+"\n\n") ################################################################################## PS: Usually the angles are given in Radian to convert : 1. angle in Degrees to Radians : Angle in radian = pi * (angle in degree) / 180 Angle in radian = math.radians(angle in degree) 2. angle in Radians to Degrees : Angle in degree = 180 * (angle in radian) / pi Angle in degree = math.degrees(angle in radian)

Cartesian coordinates This code displays the Cartesian coordinates of the selected item. Change the value of "numberOfPoints" if you want a different number of points (precision) numberOfPoints = 100 # Decomposition number (or precision you can change) selectedEdge = FreeCADGui.Selection.getSelectionEx()[0].SubObjects[0].copy() # select one element points = selectedEdge.discretize(numberOfPoints) # discretize the element i=0 for p in points: # list and display the coordinates i+=1 print i, " X", p.x, " Y", p.y, " Z", p.z Other method display on "Int" and "Float" import Part from FreeCAD import Base c=Part.makeCylinder(2,10) # create the circle Part.show(c) # display the shape # slice accepts two arguments: #+ the normal of the cross section plane #+ the distance from the origin to the cross section plane. Here you have to find a value so that the plane intersects your object s=c.slice(Base.Vector(0,1,0),0) # # here the result is a single wire # depending on the source object this can be several wires s=s[0] # if you only need the vertexes of the shape you can use v=[] for i in s.Vertexes: v.append(i.Point) # but you can also sub-sample the section to have a certain number of points (int) ... p1=s.discretize(20) ii=0 for i in p1: ii+=1 print i # Vector() print ii, ": X:", i.x, " Y:", i.y, " Z:", i.z # Vector decode Draft.makeWire(p1,closed=False,face=False,support=None) # to see the difference accuracy (20) ## uncomment to use #import Draft #Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # first transform the DWire in Wire "downgrade" #Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # second split the Wire in single objects "downgrade" # ##Draft.upgrade(FreeCADGui.Selection.getSelection(),delete=True) # to attach lines contiguous SELECTED use "upgrade"

# ... or define a sampling distance (float) p2=s.discretize(0.5) ii=0 for i in p2: ii+=1 print i # Vector() print ii, ": X:", i.x, " Y:", i.y, " Z:", i.z # Vector decode Draft.makeWire(p2,closed=False,face=False,support=None) # to see the difference accuracy (0.5) ## uncomment to use #import Draft #Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # first transform the DWire in Wire "downgrade" #Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # second split the Wire in single objects "downgrade" # ##Draft.upgrade(FreeCADGui.Selection.getSelection(),delete=True) # to attach lines contiguous SELECTED use "upgrade"

Select all objects in the document import FreeCAD for obj in FreeCAD.ActiveDocument.Objects: print obj.Name # display the object Name objName = obj.Name obj = App.ActiveDocument.getObject(objName) Gui.Selection.addSelection(obj) # select the object

Selecting a face of an object # select one face of the object import FreeCAD, Draft App=FreeCAD nameObject = "Box" # objet faceSelect = "Face3" # face to selection loch=App.ActiveDocument.getObject(nameObject) # objet Gui.Selection.clearSelection() # clear all selection Gui.Selection.addSelection(loch,faceSelect) # select the face specified s = Gui.Selection.getSelectionEx() #Draft.makeFacebinder(s) #

Create one object to the position of the Camera # create one object of the position to camera with "getCameraOrientation()" # the object is still facing the screen import Draft plan = FreeCADGui.ActiveDocument.ActiveView.getCameraOrientation() plan = str(plan) ###### extract data a = "" for i in plan: if i in ("0123456789e.- "): a+=i a = a.strip(" ") a = a.split(" ") ####### extract data #print a #print a[0] #print a[1] #print a[2] #print a[3] xP = float(a[0]) yP = float(a[1]) zP = float(a[2]) qP = float(a[3]) pl = FreeCAD.Placement() pl.Rotation.Q = (xP,yP,zP,qP) # rotation of object pl.Base = FreeCAD.Vector(0.0,0.0,0.0) # here coordinates XYZ of Object rec = Draft.makeRectangle(length=10.0,height=10.0,placement=pl,face=False,support=None) # create rectangle #rec = Draft.makeCircle(radius=5,placement=pl,face=False,support=None) # create circle print rec.Name here same code simplified import Draft pl = FreeCAD.Placement()

pl.Rotation = FreeCADGui.ActiveDocument.ActiveView.getCameraOrientation() pl.Base = FreeCAD.Vector(0.0,0.0,0.0) rec = Draft.makeRectangle(length=10.0,height=10.0,placement=pl,face=False,support=None)