Beruflich Dokumente
Kultur Dokumente
version 0.15
user manual
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 write-
protected 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.
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.
Rotate View
Select Pan Zoom Rotate View
Alternate Method
2
1
Press the left mouse Click the middle Use the mouse wheel Click first with the Click first with the
button over an object mouse button and to zoom in and out. middle mouse button, middle mouse button,
you want to select. move the object hold it down, and then hold it down, and then
Holding down ctrl around to pan click the left mouse click the right mouse
allows the selection of button and drag the button and drag the
multiple objects. mouse in the desired mouse in the desired
direction. The cursor direction. This method
location at the middle works just like the
mouse button click previously described
determines the center Rotate View that uses
of rotation. Rotation Middle Mouse Button
works like spinning a + Left Mouse Button,
ball which rotates except that the middle
around its center. If mouse button may be
the buttons are released after the
released before you right mouse button is
stop the mouse pressed. Users who
motion, the object use the mouse with
continues spinning, if their right hand may
this is enabled. A find this Rotate View
double click with the method easier than
middle mouse button the previous method.
sets a new center of
rotation.
Press and hold Ctrl Once in Pan mode, Once in Pan mode,
key and click and press and release left click and momentary
release right mouse mouse button to hold left mouse button
button to pan (rev Zoom, to exit back to to rotate, to exit back
0.14) pan mode press and to pan mode press
release right mouse and release right
button (rev 0.14) 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.
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.
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:
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.
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.
Scripting
And finally, one of the most powerful features of FreeCAD is the scripting environment. From the integrated python console
(or from any other external Python script), you can gain access to almost any part of FreeCAD, create or modify geometry,
modify the representation of those objects in the 3D scene or access and modify the FreeCAD interface. Python scripting can
also be used in macros, which provide an easy method to create custom commands.
Workbenches
FreeCAD, like many modern design applications such as Revit or CATIA, is based on the concept of Workbench. A
workbench can be considered as a set of tools specially grouped for a certain task. In a traditional furniture workshop, you
would have a work table for the person who works with wood, another one for the one who works with metal pieces, and maybe
a third one for the guy who mounts all the pieces together.
In FreeCAD, the same concept applies. Tools are grouped into workbenches according to the tasks they are related to.
The Part Design Workbench for building Part shapes from sketches
The OpenSCAD M odule for interoperability with OpenSCAD and repairing CSG model history
The Assembly M odule for working with multiple shapes, multiple documents, multiple files, multiple relationships...
The Ship Workbench FreeCAD-Ship works over Ship entities, that must be created on top of provided geometry.
The Plot Workbench The Plot module allows to edit and save output plots created from other modules and tools.
When you switch from one workbench to another, the tools available on the interface change. Toolbars, command bars and
eventually other parts of the interface switch to the new workbench, but the contents of your scene doesn't change. You could,
for example, start drawing 2D shapes with the Draft Workbench, then work further on them with the Part Workbench.
Note that sometimes a Workbench is referred to as a Module. However, Workbenches and Modules are different entities. A
Module is any extension of FreeCAD, while a Workbench is a special GUI configuration that groups some toolbars and menus.
Usually every Module contains its own Workbench, hence the cross-use of the name.
Part Workbench
(Redirected from Part Workbench)
The CAD capabilities of FreeCAD are based on the OpenCasCade kernel. The Part module allows FreeCAD to access and
use the OpenCasCade objects and functions. OpenCascade is a professional-level CAD kernel, that features advanced 3D
geometry manipulation and objects. The Part objects, unlike M esh M odule objects, are much more complex, and therefore
permit much more advanced operations, like coherent boolean operations, modifications history and parametric behaviour.
The tools
The Part module tools are all located in the Part menu that appears when you load the Part module.
Primitives
Shapebuilder: A tool to create more complex shapes from various parametric geometric primitives
Modifying objects
These are tools for modifying existing objects. They will allow you to choose which object to modify.
Revolve: Creates a solid by revolving another object (not solid) around an axis
Cross sections...:
Ruled Surface:
Other tools
Import CAD
Export CAD
Refine shape
Check geometry
M easure
Boolean Operations
An example of union (Fuse), intersection (Common) and difference (Cut)
In OpenCasCade terminology, we distinguish between geometric primitives and (topological) shapes. A geometric primitive can
be a point, a line, a circle, a plane, etc. or even some more complex types like a B-Spline curve or surface. A shape can be a
vertex, an edge, a wire, a face, a solid or a compound of other shapes. The geometric primitives are not made to be directly
displayed on the 3D scene, but rather to be used as building geometry for shapes. For example, an edge can be constructed
from a line or from a portion of a circle.
We could say, to resume, that geometry primitive are "shapeless" building blocks, and shapes are the real spatial geometry
built on it.
To get a complete list of all of them refer to the OCC documentation (Alternative: sourcearchive.com) and search for
Geom_* (for geometry) and TopoDS_* (for shapes). There you can also read more about the differences between geometric
objects and shapes. Please note that unfortunately the official OCC documentation is not available online (you must download
an archive) and is mostly aimed at programmers, not at end-users. But hopefully you'll find enough information to get started
here.
The geometric types actually can be divided into two major groups: curves and surfaces. Out of the curves (line, circle, ...) you
can directly build an edge, out of the surfaces (plane, cylinder, ...) a face can be built. For example, the geometric primitive line
is unlimited, i.e. it is defined by a base vector and a direction vector while its shape representation must be something limited
by a start and end point. And a box -- a solid -- can be created by six limited planes.
From an edge or face you can also go back to its geometric primitive counter part.
Thus, out of shapes you can build very complex parts or, the other way round, extract all sub-shapes a more complex shape is
made of.
Scripting
The main data structure used in the Part module is the BRep data type from OpenCascade. Almost all contents and object
types of the Part module are now available to python scripting. This includes geometric primitives, such as Line and Circle (or
Arc), and the whole range of TopoShapes, like Vertexes, Edges, Wires, Faces, Solids and Compounds. For each of those
objects, several creation methods exist, and for some of them, especially the TopoShapes, advanced operations like boolean
union/difference/intersection are also available. Explore the contents of the Part module, as described in the FreeCAD
Scripting Basics page, to know more.
Examples
To create a line element switch to the Python console and type in:
import Part,PartGui
doc=App.newDocument()
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()
import Part,PartGui
doc=App.newDocument()
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()
This adds a Part object type to the document and assigns the shape representation of the line segment to the 'Shape' property
of the added object. It is important to understand here that we used a geometric primitive (the Part.Line) to create a TopoShape
out of it (the toShape() method). Only Shapes can be added to the document. In FreeCAD, geometry primitives are used as
"building structures" for Shapes.
doc.recompute()
Updates the document. This also prepares the visual representation of the new part object.
Note that a Line can be created by specifying its start and endpoint directly in the constructor, for example
Part.Line(point1,point2), or we can create a default line and set its properties afterwards, as we did here.
import Part
doc = App.activeDocument()
c = Part.Circle()
c.Radius=10.0
f = doc.addObject("Part::Feature", "Circle")
f.Shape = c.toShape()
doc.recompute()
Note again, we used the circle (geometry primitive) to construct a shape out of it. We can of course still access our construction
geometry afterwards, by doing:
s = f.Shape
e = s.Edges[0]
c = e.Curve
Here we take the shape of our object f, then we take its list of edges. In this case there will be only one because we made the
whole shape out of a single circle, so we take only the first item of the Edges list, and we takes its curve. Every Edge has a
Curve, which is the geometry primitive it is based on.
Head to the Topological data scripting page if you would like to know more.
Part Box
A parametric Rectangular cuboid primitive is available in the Part workbench from the M enu location
Part tool bar, Part menu (primitives sub-menu) and the Create Primitives dialogue. Part Box
Beginning in FreeCAD version 0.14, a Part Box is referred to in the GUI elements as a
Cube and the default label is "Cube". Workbenches
Part, Complete
See also
In the workbench Part click on the cube icon . A cube with standard dimension and Part CreatePrimitives
position will be created.
Options
The parametric rectangular cuboid is defined by the parameters
length,
width,
height,
as well as the standard set of Placement Parameters.
The default is a cube with parameter values for height, length and width being 10mm. The default placement values will locate
the cuboid's local origin at the global origin (the location where all axis are 0) and the orientation such that
Parameter
FreeCAD - Version
available in version 0.14
Beginning in FreeCAD version 0.14, a Part Box is referred to in the GUI elements as a Cube and the default label is "Cube".
Part Cone
A parametric truncated Part Cone primitive is available in the Part workbench from the Part M enu location
tool bar, Part menu (primitives sub-menu) and the Create Primitives dialogue. Part -> Cone
Workbenches
How to use Part, Complete
Default shortcut
None
In the workbench Part click on the cone icon .
See also
The default values create a truncated parametric cone, defined by radius1, radius2 height Part CreatePrimitives
and angle, parameters. The default cone will be positioned at origin (point 0,0,0) on
creation. The angle parameter permits the creation of a portion of cone (it is set to 360
by default), and the radius 1 and 2 correspond to base and top radius of the truncated
cone.
Options
Cone
Creates a simple parametric cylinder, with position, angle, radius and height parameters. M enu location
Part Cylinder
Default shortcut
In the workbench Part click on the cube icon . The default is for a full cylinder to be None
positioned, the centre of one circular face coincident with the global origin (point 0,0,0),
with a radius of 2mm and height of 10mm. See also
Part CreatePrimitives
Options
The properties can later be edited in the data tab for the cylinder:
Cylinder
Angle: The angle parameter permits the creation of a portion of cylinder (it is set to 360 by default)
Height: The height is the distance in the z-axis
Radius: The radius defines a plane in x-y.
Part Sphere
Part Sphere
Description
M enu location
Creates a simple parametric sphere, with position, angle1, angle2, angle3 and radius
Part -> Sphere
parameters.
Workbenches
Part M odule,Complete
Default shortcut
None
See also
Part CreatePrimitives
How to use
In the workbench Part click on the sphere icon . The sphere will be positioned at origin (point 0,0,0) on creation. The
angle parameters permit to make a portion of sphere instead of a full sphere (they are set to 360 by default).
Options
The parametric sphere is defined by the following parameters:
Radius
Angle 1
Angle 2
Angle 3
as well as the standard set of placement parameters
The picture below gives an overview of a parametric sphere with parameters different from the default value.
Parameter
Because it is quite difficult to explain the meaning of the parameters angle 1, angle 2, angle 3, the picture below gives an
explanation about these parameters with following values: angle 1 = -45, angle 2 = 45 and angle 3= 90.
Part Torus
Creates a simple parametric torus, with position, angle1, angle2, angle3, radius1 and M enu location
radius2 as parameters. Part Torus
Workbenches
Part, Complete
Default shortcut
None
See also
Part CreatePrimitives
How to use
In the Part workbench click on the torus icon . The torus will be positioned at origin (point 0,0,0) on creation. The angle
parameters (angle1, angle2, angle3), as well as the radius parameter ( radius1 , radius2) parameters permit to parametrize the
torus. The angle parameters permit to make a portion of torus instead of a full one (they are set to 360 by default), the radius
1 and 2 define respectively the size of the hole and the ring thickness of the torus.
Option
Property
Scripting
Part CreatePrimitives
Wedge
Helix
Spiral available in version 0.14
Circle
Ellipse
Line (Edge)
Point (Vertex)
Regular Polygon available in version 0.14
Part Plane
Description Part
CreatePrimitives
Create a simple parametric plane 10 x 10 mm, with the parameters of position, length, and
width. By default, the plane is positioned at the origin (0,0,0). M enu location
Part Create Primitives
Plane
Workbenches
Part, OpenSCAD
Default shortcut
None
See also
Create Primitives
How to use
The standard plane is created with its lower left corner at the origin point 0,0,0. To change these parameters, open the
Location section and enter the desired values in the respective input fields, or click on the 3D view and select a point, the
point coordinates are taken from the fields. In the Direction menu you can also define a standard vector (X, Y or Z) normal to
the plane, or click User Defined ... to open the dialog box that allows you to set a different carrier (eg direction 1.0 , -1 creates
a plane inclined 45 with respect to X and Z).
The properties can be changed later in the Combined View Data, after selecting the item.
Option
View
Data
DATA Length : Length is the dimension along the X axis The default
value is 10 mm
DATA Width : Width is the size of the Y-axis The default value is 10 mm
Part Prism
A Part Prism is available from the Create Primitives dialogue in the Part workbench. A Part M enu location
Prism is a solid defined by a regular polygon cross section and a height.
Part Create Primitives
Prism
The Create Primitives dialogue can be accessed via the CreatePrimitives icon
Workbenches
located in the Part menu or the Part toolbar, in the Part Workbench.
Part, OpenSCAD
Default shortcut
None
Parameters See also
Part Primitives Box
Polygon - the number of sides of the polygon which describes the cross section of
the Part Prism
cirumradius - the circumradius is the distance from the centre of the polygon to a vertex.
Height - the height of the Part Prism
available in version 0.14
Part Wedge
Create a parametric Wedge object. This Wedge defaults to a larger square base and a
smaller square top. Part Wedge
Top Face:
X : 2-8 mm
Z : 2-8 mm
Parametric Inputs
Part Helix
Parameter
Location
Once you have created the helix you have the possibility to edit its parameters.
Part Spiral
See also
Create Primitives
Part Circle
Alternatively a Part Circle can be initially defined from three points. Once created the circle
will only contain the standard Part Circle properties and will no longer contain a reference to the creation points.
Properties
Part Ellipse
Properties
M ajor radius: the major radius of the ellipse, the default value is 4
M inor radius: the minor radius of the ellipse, the default value is 2
Angle 1: start of the edge of the ellipse or elliptical curved edge, (degrees anti-clockwise), the default value is 0
Angle 2: end of the edge of the ellipse or elliptical curved edge, (degrees anti-clockwise), the default value is 360
Part Line
Part Line
Geometric Primitives
M enu location
Part Create Primitives
Line
Workbenches
Part, OpenSCAD
Default shortcut
Line None
See also
Parameter
..
Start point
End point
Location
Property
View
..
Data
Base
DATA Label:
DATA Placement: placement
Vertex 1 Start
DATA X1 :
DATA X1 :
DATA X1 :
Vertex 2 Finish
DATA X2 :
DATA X2 :
DATA X2 :
Part Point
Part Point
See also
Geometric Primitives ..
Point
Parameter
X
Y
Z
Location
Property
View
..
Data
Base
Dati Label:
Dati Placement: placement
Dati X :
Dati Y :
Dati Z :
Part RegularPolygon
Description Part
RegularPolygon
Default shortcut
Parameters None
See also
Polygon - the number of sides of the polygon which describes the cross section of ..
the Part Prism
cirumradius - the circumradius is the distance from the centre of the polygon to a
vertex.
This command is a generic all-in-one boolean tool. It allows you to specify what operation
to perform and what parameters to use via the dialog below. For quicker boolean Part Booleans
operations, see also Part Fuse, Part Common and Part Cut.
M enu location
Part Booleans
Workbenches
Part,Complete
Default shortcut
None
See also
Part Fuse, Part Common
and Part Cut
Fuses (unions) selected Part objects into one. This operation is fully parametric and the
components can be modified and the result recomputed. Part Fuse
Items can be added and removed from the Fuse, by dragging them in or out of the Fuse See also
feature in the treeview, with the mouse. A manual recompute (press F5 key or click on the Part Cut, Part Common
recompute icon) is required to see the results.
After this operation may be necessary to clean the shape with RefineShape
Part Extrude
Part Extrude extends a shape by a specified distance, in a specified direction. The output M enu location
shape type will vary depending on the input shape type and the options selected. Part Extrude
In most common scenarios, the following lists the expected output shape type from a given Workbenches
input shape type, Part, Complete
Extrude a Vertex (point), will produce a lineal Edge (Line) Default shortcut
Extrude a open edge (e.g. line, arc), will produce a open face (e.g. plane) None
Extrude a closed edge (e.g. circle), will optionally produce a closed face (e.g. an See also
open ended cylinder) or if the parameter "solid" is "true" will produce a solid (e.g. a
closed solid cylinder)
Extrude a open Wire (e.g. a Draft Wire), will produce a open shell (several joined faces)
Extrude a closed Wire (e.g. a Draft Wire), will optionally produce a shell (several joined faces) or if the parameter "solid"
is "true" will produce a solid
Extrude a face (e.g. plane), will produce a solid (e.g. Cuboid)
Extrude a Draft Shape String, will produce a compound of solids (the string is a compound of the letters which are each
a solid)
How to use
1. Select the shape(s) in the 3D view or in the Model tree
2. Click on the Extrude icon in the toolbar, or go to the Part Extrude menu
3. Set the direction and length and optionally other parameters (see the following Parameters section for more details).
4. Click OK.
Alternatively, the selection can be done after launching the tool, by selecting one or more shape from the list in the Tasks
panel.
The Model tree will list as many Extrude objects as there were selected shapes. Each input shape is placed underneath its
Extrude object.
Parameters
The Extrude shape is defined by the following parameters, which can be edited after its creation in the Data tab.
Base: the input shape (the shape upon which the Part Extrude was applied)
Dir: the direction and distance to extend the shape, as defined by a specified distance in each of the X, Y and Z axis.
Solid (true or false): toggles between a surface or a solid where not otherwise defined by the nature of the extrusion
Taper Angle: applies an angle to the extrusion, with the end face of the extrusion being smaller or bigger than the
original shape depending on if the angle has a positive or negative value.
Placement: the standard placement parameters
Label: label to be shown in the Model tree (not available on Extrude creation)
Part Fillet
Description
Part Fillet
This tool creates a fillet (round) on the selected edges of an object. A dialog allows you to
choose which objects and which edges to work on. M enu location
Part Fillet
Usage
Workbenches
Start the tool from the Part toolbar or from the menu. You can either select the Part, Complete
object before or after starting the tool.
Default shortcut
If the shape was not selected prior to starting the tool, select it in the Shape drop
down list in the TaskPanel. None
Select the fillet type, either constant radius (default) or variable radius. See also
Select the edges either in the 3D model view, or by ticking them in the edge list in Part Chamfer
TaskPanel.
Set the radius value.
Click OK to validate.
There is another fillet tool in the PartDesign workbench. Please note that their operation is quite different. Check out the
PartDesign Fillet reference page for more details on their differences.
Part Revolve
Revolves the selected object around a given axis. The following shape types are allowed, Part Revolve
and lead to the listed output shapes (See Notes for exceptions):
Solids or compound solids are not allowed as input shapes. Normal compounds are See also
currently not allowed, too. Future versions will check the actual shape type of compound
objects.
The Angle argument specifies how far the object is to be turned. The coordinates move the origin of the axis of revolving,
relative to the origin of the coordinate system.
If you select a user defined axis, the numbers define the direction of the revolving axis with respect to the coordinate system: If
the Z coordinate is 0 and the Y and X coordinate are non-zero, then the axis will lie in the X-Y-plane. Its angle is such that its
tangent is the ratio of the given X and Y coordinates.
Notes
If your version of FreeCAD has a check box for Solid in the Revolve dialog, you can make Solids from closed Wires and
Edges.
Part SectionCross
Part
SectionCross
M enu location
Part SectionCross
Workbenches
Part,Complete
Default shortcut
None
See also
Part Chamfer
Chamfers the selected edges of an object. A dialog allows you to choose which objects
and which edges to work on. Part Chamfer
M enu location
Part -> Chamfer
Workbenches
Part, Complete
Default shortcut
None
See also
Part Mirror
'Mirror Object' - This tool creates a new object (image) which is a reflection of the original M enu location
object (source). The image object is created behind a mirror plane. The mirror plane may Part -> Mirror
be standard plane (XY, YZ, or XZ), or any plane parallel to a standard plane.
Workbenches
An example: Part, Complete
Default shortcut
None
See also
Before
Usage
Select the source object from the list. Select a standard M irror plane from the dropbox. Press OK to create the image object.
Options
The Base point boxes can be used to move the mirror plane parallel to the selected standard miror plane. Only one of the X,
Y, or Z boxes is effective for a given standard plane.
Limitations
Arbitrary mirror planes (ie not parallel to a standard plane) are not supported (as of FC version 0.13).
Part RuledSurface
Description Part
RuledSurface
M enu location
Part RuledSurface
Workbenches
Part, Complete
Default shortcut
None
See also
How to use
Part Sweep
See Draft ShapeString for good documented Command. Gui Command gives an
overview over commands. And see List of Commands for other commands.
The FreeCAD Part Sweep tool (Part Workbench), is used to create a face, shell or a solid M enu location
shape from one or more profiles, projected along a path. Part Sweep...
The Part Sweep tool is similar to Part Loft with the addition of a path to define the Workbenches
projection between profiles. Part
The profiles can be a point (vertex), line (Edge), wire or face. Edges and wires may be Default shortcut
either open or closed. There are various profile limitations and complications, see None
below, however the profiles may come from the Part Workbench primitives, Draft
Workbench features and a Sketch. See also
The path can be a line (Edge) or series of connecting lines, wire or various Part Part Loft
Workbench primitives, Draft Workbench features or a Sketch. The path is often selected
directly from the main model window, however it can also be selected from the Tree View
(Model Tab of Combo View). The path can either be an entire appropriate shape or an appropriate sub-component of a more
advance shape (for example, an edge of a Part Cube could be selected as the path). The path may be either open or closed
and will thus create either an open or closed Sweep. A closed path such as a Part Circle will result in a closed Sweep. For
example a Sweep of a smaller circle around a path of a larger circle will create a torus.
Properties
Solid
If "Solid" is "true" FreeCAD creates a solid if the profiles are of closed geometry, if "false" FreeCAD creates a face or (if more
than one face) a shell for either open or closed profiles.
Frenet
The "Frenet" property controls how the profile orientation changes as it follows along the sweep path. If "Frenet" is "false", the
orientation of the profile is kept consistent from point to point. The resulting shape has the minimum possible twisting.
Unintuitively, when a profile is swept along a helix, this results in the orientation of the profile slowly creep (rotate) as it follows
the helix. Setting "Frenet" to true prevents such a creep.
If "Frenet" is "true" the orientation of the profile is computed basing on local curvature and tangency vectors of the path. This
keeps the orientation of the profile consistent when sweeping along a helix (because curvature vector of a straight helix is
always pointing to its axis). However, when path is not a helix, the resulting shape can have strange looking twists sometimes.
For more information, see Frenet Serret formulas.
Transition
"Transition" sets the transition style of the Sweep at a joint in the path, if the path does not define the corner transition (for
example where the path is a wire). The property is not exposed in Task dialog and can be found in properties after the Sweep
has been created.
FreeCAD - Version
0.13
0.14 some of the above is extended functionality added in 0.14
Part Loft
See Draft ShapeString for good documented Command. Gui Command gives an
overview over commands. And see List of Commands for other commands.
Part Loft
If "Solid" is "true" FreeCAD creates a solid if the profiles are of closed geometry, if "false"
FreeCAD creates a face or (if more than one face) a shell for either open or closed profiles.
If "Closed" is "true" FreeCAD attempts to loft the last profile to the first profile to create a closed figure.
For more info on how the profiles are joined together, refer Part Loft Technical Details page.
Part_Loft. From three profiles which are two Part_Circles and one Part_Ellipse. Parameters are Solid "True"
and Ruled "True"
Closed Lofts
The results of closed lofts may be unexpected - the loft may develop twists or kinks. Lofting is very sensitive to the
Placement of the profiles and the complexity of the curves required to connect the corresponding Vertices in all the
profiles.
An example Loft
The Loft tool is in the Part Workbench, menu Part -> Loft... or via the icon in the tool bar.
In the "Tasks" will be two lists: "node / wire" and "free form".
In the "node / wire" the available items are displayed. Two elements must be selected one after the first in this list.
Thereafter, with the blue arrow that item is added to the list of "free form".
Tip: the active / selected items in the list are displayed in the 3D area as active / selected.
Command complete
If both elements are selected, the command can be completed with "OK".
Result
From closed lines arise surfaces which might be taken at a superficial look for solids / solids.
If indeed a solid / solid to be created, can be used either when you create the button "Create Solid" or after creating the field
properties tab data created the free-form surface of the switch "Solid" by pop be set to "true" / set properly.
FreeCAD Version
added Version 0.13
"closed" property added Version 0.14
Ability to use a face as a profile added Version 0.14
Part Offset
See Draft ShapeString for good documented Command. Gui Command gives an
overview over commands. And see List of Commands for other commands.
Part Offset
Part Thickness
Default shortcut
Use None
See also
1. Create a solid
Offset
2. Select one or more faces
Options
Thickness: Wall thickness of the resulting object, set the desired value
A positive value will offset the faces outward
A negative value will offset the faces inward
Mode
Skin: Select this option if you want to get an item like a vase, headless but with the bottom
Pipe: Select this option if you want to get an object like a pipe, headless and bottomless. In this case it may be
convenient to select the faces to be deleted before you start the tool. Helping with predefined views buttons or use
the numeric keys.
RectoVerso:
Join Type
Arc: removes the outer edges and create a fillet with a radius equal to the thickness defined
Tangent:
Intersection:
Intersection:
Self-intersection: Enables self-intersection
Face / Done: Select the faces to be removed, then click Done
Update view: Automatically updates the view in real time
Limitations
Sometimes, on some shape produce bizarre results. Save your work before applying Thickness on complex objects
Links
A good example on how to use this tool on the forum: Re: Help designing a simple enclosure
Examples
Part RefineShape
Part RefineShape
Default shortcut
None
See also
Use
1. Select the shape to be cleaned.
2. Click the Part Refine shape menu.
A copy of the object is created and totally cleaned, the original object is rendered hiden.
The newly created copy is independent of the original.
Scripting
The Phyton command for refining a shape is the following:
shape.removeSplitter()
Note that the function does not modify the existing shape, but returns a new shape.
Part CheckGeometry
Introduction Part
CheckGeometry
The check geometry tool allows you to verify if you have a valid solid
M enu location
Part Check geometry
Usage Workbenches
Part
From the Part or Part Design WB
Default shortcut
Tools > Edit Parameters > Preferences > Mod > Part > CheckGeometry then in the right
None
pane double click under Value for the RunBOPCheck parameter and set to true
See also
PartDesign Workbench
The Part Design Workbench provides tools for modelling complex solid parts and is based on a Feature editing
methodology to produce a single contiguous solid. It is intricately linked with the Sketcher Workbench.
Basic Workflow
The sketch is the building block for creating and editing solid parts. The workflow can be summarized by this: a sketch
containing 2D geometry is created first, then a solid creation tool is used on the sketch. At the moment the available tools are:
A very important concept in the PartDesign workbench is the sketch support. Sketches can be created on standard planes
(XY, XZ, YZ and planes parallel to them) or on the face of an existing solid. For this last case, the existing solid becomes the
support of the sketch. Several tools will only work with sketches that have a support, for example, Pocket - without a support
there would be nothing to remove material from!
After solid geometry has been created it can be modified with chamfers and fillets or transformed, e.g. mirrored or patterned.
The Partdesign workbench is meant to create a single, connected solid. Multiple solids will be possible with the Assembly
workbench.
The Tools
The Part Design tools are all located in the Part Design menu that appears when you load the Part Design module.
They include the Sketcher Workbench tools, since the Part Design module is so dependent on them.
Sketcher Geometries
Arc: Draws an arc segment from center, radius, start angle and end angle.
Arc by 3 Point: Draws an arc segment from two endpoints and another point on the circumference.
Conic sections:
Ellipse by center : Draws an ellipse by center point, major radius point and minor radius point. (v0.15)
Ellipse by 3 points : Draws an ellipse by major diameter (2 points) and minor radius point. (v0.15)
Arc of ellipse : Draws an arc of ellipse by center point, major radius point, starting point and ending point.
(v0.15)
Polyline (multiple-point line): Draws a line made of multiple line segments. Pressing the M key while drawing a
Polyline toggles between the different polyline modes.
Slot: Draws an oval by selecting the center of one semicircle and an endpoint of the other semicircle.
Fillet: Makes a fillet between two lines joined at one point. Select both lines or click on the corner point, then
activate the tool.
Trimming: Trims a line, circle or arc with respect to the clicked point.
Construction M ode: Toggles an element to/from construction mode. A construction object will not be used in a 3D
geometry operation and is only visible while editing the Sketch that contains it.
Sketcher Constraints
Constraints are used to define lengths, set rules between sketch elements, and to lock the sketch along the vertical and
horizontal axes.
Coincident: Affixes a point onto (coincident with) one or more other points.
Point On Object: Affixes a point onto another object such as a line, arc, or axis.
Vertical: Constrains the selected lines or polyline elements to a true vertical orientation. More than one object can
be selected before applying this constraint.
Horizontal: Constrains the selected lines or polyline elements to a true horizontal orientation. More than one
object can be selected before applying this constraint.
Perpendicular: Constrains two lines perpendicular to one another, or constrains a line perpendicular to an arc
endpoint.
Tangent: Creates a tangent constraint between two selected entities, or a co-linear constraint between two line
segments. A line segment does not have to lie directly on an arc or circle to be constrained tangent to that arc or circle.
Equal Length: Constrains two selected entities equal to one another. If used on circles or arcs their radii will be set
equal.
Symmetric: Constrains two points symmetrically about a line, or constrains the first two selected points
symmetrically about a third selected point.
Lock: Constrains the selected item by setting vertical and horizontal distances relative to the origin, thereby locking
the location of that item. (These constraint distances can be edited later.)
Horizontal Distance: Fixes the horizontal distance between two points or line endpoints. If only one item is
selected, the distance is set to the origin.
Vertical Distance: Fixes the vertical distance between 2 points or line endpoints. If only one item is selected, the
distance is set to the origin.
Length: Defines the distance of a selected line by constraining its length, or defines the distance between two
points by constraining the distance between them.
Radius: Defines the radius of a selected arc or circle by constraining the radius.
Internal Angle: Defines the internal angle between two selected lines.
Snell's Law: Constrains two lines to obey a refraction law to simulate the light going through an interface. (v 0.15)
Internal Alignment: Aligns selected elements to selected shape (e.g. a line to become major axis of an ellipse).
Other
New sketch: Creates a new sketch on a selected face or plane. If no face is selected while this tool is executed
the user is prompted to select a plane from a pop-up window.
View sketch: Sets the model view perpendicular to the sketch plane.
Validate sketch: It allows you to check if there are in the tolerance of different points and to match them.
Show/Hide internal geometry: Recreates missing/deletes unneeded geometry aligned to internal geometry of a
selected element (applicable only to ellipse so far). v 0.15
Construction tools
These are tools for creating solid objects or removing material from an existing solid object.
Pocket: Creates a pocket from a selected sketch. The sketch must be mapped to an existing solid object's face.
Revolution: Creates a solid by revolving a sketch around an axis. The sketch must be a closed profile to get a
solid object.
Groove: Creates a groove by revolving a sketch around an axis. The sketch must be mapped to an existing solid
object's face.
M odification tools
These are tools for modifying existing objects. They will allow you to choose which object to modify.
Transformation tools
These are tools for transforming existing features. They will allow you to choose which features to transform.
M ultiTransform: Allows creating a pattern with any combination of the other transformations.
Extras
Extras
Some optional functionality that has been created for the PartDesign Workbench:
Shaft design wizard: Generates a shaft from a table of values and allows to analyze forces and moments
There are two types of feature properties, accessible through tabs at the bottom of the Property editor:
View
Base
VIEWBounding Box : To view the occupation, and, overall, of the object dimensions in space. Value False, or True
(Default, False).
VIEW Deviation : Sets the accuracy of the polygonal representation of the model in 3d view (tessellation). Lower values =
better quality. The value is in percent of object's size.
VIEWDisplay M ode :Display mode of the form, Flat lines, Shaded, Wireframe, Points . (Default, Flat
lines).
VIEW Lighting : Lighting One side, Two side . (Default, Two side).
VIEW Line Color : Gives the color of the line (edges) (Default, 25, 25, 25).
VIEW Line Width : Gives the thickness of the line (edges) (Default, 2).
VIEW Point Color : Gives the color of the points (ends of the form) (Default, 25, 25, 25).
VIEW Point Size : Gives the size of the points (Default, 2).
VIEW Selectable : Allows the selection of the form. Value False, ou True (Default, True).
VIEW Shape Color : Give the color shape (default, 204, 204, 204).
VIEW Transparency : Sets the degree of transparency in the form of 0 to 100 (Default, 0).
VIEW Visibility : Determines the visibility of the form (like the bar SPACE ). Value False, or True (Default, True).
Data
Base DATA Angle : The argument Angle, indicates the angle that will be used with the option Axis (below). Here, an angle is
defined. The angle on the axis is set with the option Axis.
The object takes the specified angle around the specified axis.
An example, if you create an object with a required revolution should be rotate functionality of a certain amount, in order to
enable it to take the same angle that another element existing.
DATA Axis : This option specifies the axis/axes to rotate the created object. The exact value of rotation comes from the angle
(see above) option.
This option takes three arguments, these arguments, are transmitted in the form of numbers, x, y or z. Adding a value, more of
an axis, will the rotation to each specified axis angle.
For example, with a Angle of 15 : specifying, 1.0 for x and 2.0 for y, will rotate 15 and 30 in the y-axis and the x-axis
(final position),
DATA Base : This option specifies the offset in either axes x, y, or z, and accept any number as the argument for each field.
DATA Label : The Label is the name given to the operation, this name can be changed at convenience.
DATA Placement : [(0.00 0.00 1.00);0.00;(0.00 0.00 0.00)] Summary below data. Every feature has a placement that can be
controlled through the Data Properties table. It controls the placement of the part with respect to the coordinate system. NOTE:
The placement options do not affect the physical dimensions of the feature, but merely its position in space!
If you select the title Placement , a button with three small points appears, clicking
this button ... , you have access to the options window Tasks_Placement.
DATA Angle : The Angle argument specifies the angle to be used with the axis option (below). An angle is set here, and the axis
that the angle acts upon is set with the axis option. The feature is rotated by the specified angle, about the specified axis. A
usage example might be if you created a revolution feature as required, but then needed to rotate the whole feature by some
amount, in order to allow it to line-up with another pre-existing feature.
DATA Axis : This option specifies the axis/axes about which the created feature is to be rotated. The exact value of rotation
comes from the angle option (above). This option takes three arguments, which are passed as numbers to either the x, y, or z
boxes in the tool. Adding a value to more than one of the axes will cause the part to be rotated by the angle in each axis. For
example, with an angle of 15 set, specifying a value of 1.0 for x, and 2.0 for y will cause the finished part to be rotated 15 in
the x-axis AND 30 in the y-axis.
DATA Position : This option specifies the base point to which all dimensions refer. This option takes three arguments, which are
passed as numbers to either the x, y, or z boxes in the tool. Adding a value to more than one of the boxes will cause the part to
be translated by the number of units along the corresponding axis.
PS: The displayed properties can vary, depending on the tool used.
Tutorials
Only for a development version of FreeCAD that is not currently available as a binary or installer:
The Pad tool takes a selected sketch as its input and from it produces a "pad" feature. A M enu location
pad is essentially an extrusion of a sketch into a solid. For example, if a sketch were made PartDesign Pad
of two concentric circles, and the pad tool were subsequently used on this sketch, the
result would be a cylinder: Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
If the selected sketch is mapped to the face of an existing solid or another Part Design feature, the pad will be fused to it.
How to use
1. Select the sketch to be padded.
Options
When creating a pad, the Combo view automatically switches to the Tasks pane, showing the Pad parameters dialogue.
Type
Type offers five different ways of specifying the length to which the pad will be extruded.
Dimension
Enter a numeric value for the length of the pad. The default direction for extrusion is away (outside of) the support, but it can
be changed by ticking the Reversed option. Extrusions occur normal to the defining sketch plane. With the option Symmetric
to plane the pad will extend half of the given length to either side of the sketch plane. Negative dimensions are not possible.
Use the Reversed option instead.
Two dimensions
This allows to enter a second length in which the pad should extend in the opposite direction (into the support). Again can be
changed by ticking the Reversed option.
To last
The pad will extrude up to the last face of the support in the extrusion direction. If there is no support, an error message will
appear.
To first
The pad will extrude up to the first face of the support in the extrusion direction. If there is no support, an error message will
appear.
Up to face
The pad will extrude up to a face in the support that can be chosen by clicking on it. If there is no support, no selections will be
accepted.
Length
Defines the length of the pad. Multiple units can be used independently of the user's units preferences (m, cm, mm, nm, ft or ',
in or ").
Symmetric to plane
Tick the checkbox to extend half of the given length to either side of the sketch plane.
Reversed
Limitations
Like all Part Design features, Pad creates a solid, thus the sketch must include a closed profile or it will fail. There can be
multiple enclosed profiles inside a larger one, provided none intersect each other (for example, a rectangle with two
circles inside it).
The algorithm used for To First and To Last is:
Create a line through the centre of gravity of the sketch
Find all faces of the support cut by this line
Choose the face where the intersection point is nearest/furthest from the sketch
This means that the face that is found might not always be what you expected. If you run into this problem, use the Up to
face type instead, and pick the face you want.
For the very special case of extrusion to a concave surface, where the sketch is larger than this surface, extrusion will
fail. This is a unresolved bug.
There is no automatic cleanup, e.g. of adjacent planar surfaces into a single surface. You can fix this manually in the
Part workbench with Refine shape (which creates an unlinked, non-parametric solid) or with the "Refine shape feature"
(which creates a parametric feature) from the OpenSCAD Workbench.
PartDesign Pocket
Introduction PartDesign
Pocket
'Create a pocket with the selected sketch' - This tool takes a selected sketch as its input,
and produces with it a pocket. A pocket being essentially an extrusion of a sketch that M enu location
subtracts from the geometry it protrudes into. For example, if a sketch were made simply PartDesign Pocket
of one circle on one face of a cube, then the pocket formed by that sketch would manifest
as a hole 'drilled' into the cube: Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
How to use
1. Select the sketch to be pocketed. This sketch must be mapped to the face of an existing solid or Part Design feature, or
an error message will appear.
Options
When creating a pocket, the 'pocket parameters' dialogue offers four different ways of specifying the length (depth) to which
the pocket will be extruded:
Dimension
Enter a numeric value for the depth of the pocket. The default direction for extrusion is into the support. Extrusions occur
normal to the defining sketch plane. Negative dimensions are not possible.
To first
The pocket will extrude up to the first face of the support in the extrusion direction. In other words, it will cut through all material
until it reaches an empty space.
Through all
The pocket will cut through all material in the extrusion direction. With the option Symmetric to plane the pad will cut through
all material in both directions.
Up to face
The pocket will extrude up to a face in the support that can be chosen by clicking on it.
Limitations
Use the type Dimension or Through All wherever possible because the other types sometimes give trouble when they
are being patterned
Otherwise, the pocket feature has the same limitations as the pad feature.
Useful links
An example with the practice on the forum.
PartDesign Revolution
Introduction PartDesign
Revolution
This tool revolves a selected sketch or 2D object about a given axis. For all the following
explanations of this command the example sketch below will be used: M enu location
PartDesign Revolution
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Options
When creating a revolution, the 'revolution parameters' dialogue offers several parameters specifying how the sketch should
be revolved.
Axis
This option specifies the axis about which the sketch is to be revolved. Currently, by default only the horizontal or
vertical sketch axis can be selected here. However if the sketch which defines the feature to be Revolved also
contains a construction line (or lines), then the drop down list will contain one custom sketch axis for each
construction line. The first construction line will be labelled 'Sketch axis 0'. After creation an arbitrary axis can be
defined in the Properties table. Base is a point through which the axis goes. The axis option itself takes three
arguments, which are passed as numbers to either the x, y, or z boxes in the tool. Adding a value of 1.0 to only
one of the boxes will cause the tool to make the revolution about that axis. Example revolutions 1, 2 and 3 in the
examples section demonstrate scenarios where the example sketch is revolved about either the x or the y axis.
Adding a non-zero value to more than one of the axes will cause the part to be revolved by a weighted amount
in each axis. e.g. an x value of 1 and a y value of 2 will mean that the revolution about the y-axis is twice as
strong as that about the x. This is fairly difficult to comprehend, Example Revolution 4 shows an example where
more than one of the boxes has a non-zero value.
Angle
This controls the angle through which the revolution is to be formed, e.g. 360 would be a full, contiguous
revolution. The images in the examples section demonstrate some of the possibilities with specifying different
angles. It is not possible to specify negative angles (use the Reversed option instead) or angles greater than
360.
Symmetric to plane
The revolution will extend half of the specified angle in both directions from the sketch plane.
Reversed
The direction of revolution will be reversed.
Examples
Example revolution using a construction line as the Revolution axis: In this image the angle is
75, revolution is about the construction line (Sketch axis 0)
Note: Unlike the above, all these examples below refer to Base, Axis and Placement being edited directly through the feature
properties table.
Example revolution 1: In this image the angle has been set to 70, revolution is about the x-axis and
there is a y-offset of 100mm. The sketch is the face not shown in the image (i.e. the 'back' face).
Example revolution 2: In this image the angle is 70, revolution is about the y-axis and there is a y-offset of 100mm.
Example revolution 3: In this image the angle is 270, revolution is about the x-axis and there are 0 offsets
Example revolution 4: In this image the angle is 270, revolution is about the x-axis (value 1.00) and the y-axis (value 2.00) and there is a y-offset of 100mm
Useful links
An example with the practice on the forum.
PartDesign Groove
Introduction PartDesign
Groove
This tool revolves a selected sketch or 2D object about a given axis, cutting out material
from the support. For example, the picture shows a groove cut out of a shaft. M enu location
PartDesign Groove
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Options
When creating a groove, the 'groove parameters' dialogue offers several parameters specifying how the sketch should be
revolved. They have exactly the same meaning as for the revolution feature.
Sketcher Point
The tools Point create a point in the current sheet of "Sketcher". M enu location
Sketch Sketcher
geometries Create point
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
None
Use
Click the Point, to activate the function.
Must be pressed each time the command Point, to create a new Point.
Press the key CTRL while drawing, force the snap, your point to the nearest location of the snap, regardless of the
distance.
Press on ESC to cancel the operation, and exit the function.
Sketcher Line
Description
Sketcher Line
This tool draws a line by picking two points in the 3D view. When starting the tool, the
mouse pointer changes to a white cross with a red line icon. Besides are coordinates M enu location
shown in real time.
Sketch Sketcher
geometries Create line
Workbenches
Sketcher, Part Design
Default shortcut
L
See also
Sketcher Polyline
Usage
Pick points on an empty area of the 3d view, or on an existing object (auto constraints must be active in TaskView).
Pressing ESC or clicking the right mouse button cancels the function.
Sketcher Arc
Description
Sketcher Arc
This tool draws an arc by picking three points: the center, the start angle along the radius,
and the end angle. M enu location
When starting the tool, the mouse pointer changes to a white cross with a red arc icon. Sketch Sketcher
The coordinates of the pointer are shown beside it in blue in real time. geometries Create arc
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Circle
Usage
Pick points on an empty area of the 3D view, or on an existing object (auto constraints must be active in TaskView).
Pressing ESC or clicking the right mouse button cancels the function.
Sketcher Circle
Description
Sketcher Circle
This tool draws a circle by picking two points: the center, and a point along the radius.
When starting the tool, the mouse pointer changes to a white cross with a red circle icon. M enu location
Besides are coordinates shown in real time.
Sketch Sketcher
geometries Create circle
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Arc
Usage
Pick points on an empty area of the 3D view, or on an existing object (auto constraints must be active in TaskView).
Pressing ESC or clicking the right mouse button cancels the function.
Sketcher Ellipse
Description Sketcher
CreateEllipse
This tool draws an ellipse by picking three points: the center, the end of major radius, the
minor radius. When starting the tool, the mouse pointer changes to a white cross with a
red ellipse icon. Besides are coordinates shown in real time. M enu location
Sketch Sketcher
geometries Create ellipse
by center
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Ellipse by 3
Points, Sketcher Circle,
Sketcher Arc of Ellipse
The sequence of clicks is indicated by yellow arrows with numbers. C is the
center, a - major diameter, b - minor diameter, F1, F2 are foci.
Usage
Invoke the command by clicking a toolbar button, picking the menu item, or by using keyboard shortcut (needs to be
assigned first in Interface Customization).
First click in 3D view sets ellipse center. Second click sets the first radius and orientation of the ellipse. Third click sets
the other radius (the distance from the line defined by first two clicks is the second radius).
After the third click, the ellipse is created, together with a set of construction geometry aligned to it (major diameter,
minor diameter, two foci). The construction geometry can be manually deleted if not needed, and recreated later. See
Internal Alignment Constraint and Sketcher Show Hide Internal Geometry.
Pressing ESC or clicking the right mouse button cancels the function.
Peculiarities
Major and minor axes of ellipses are strict and cannot be swapped by resizing the ellipse. This is a consequence of the
solver parametrization used (center (x,y), focus1 (x,y) and minor radius length (b)) and the same strict behavior of
OpenCascade. The ellipse must be rotated to swap the axes.
Ellipse can function as a circle when its major and minor diameter lines are deleted, and one of the foci is constrained to
coincide with the center. But radius constraint won't work on such a circle.
Moving the ellipse by edge is the same as moving ellipse's center.
Version
Description
Sketcher
CreateArcOfEllipse
This tool draws an arc of ellipse by picking four points: the center, the end of major radius,
the start point and the end point. When starting the tool, the mouse pointer changes to a
white cross with a red ellipse arc icon. Besides are coordinates shown in real time. M enu location
Sketch Sketcher
geometries Create an arc
of ellipse
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Ellipse, Sketcher
Arc
Usage
Invoke the command by clicking a toolbar button, picking the menu item, or by using keyboard shortcut (needs to be
assigned first in Interface Customization).
First click in 3D view sets ellipse center. Second click sets the first radius and orientation of the ellipse. Third click sets
the other radius and the start of the arc. The fourth click sets the end of the arc.
After the fourth click, the arc of ellipse is created, together with a set of construction geometry aligned to it (major
diameter, minor diameter, two foci). The construction geometry can be manually deleted if not needed, and recreated
later. See Internal Alignment Constraint and Sketcher Show Hide Internal Geometry.
Pressing ESC or clicking the right mouse button cancels the function.
Peculiarities
Major and minor axes of underlying ellipse are strict and cannot be swapped by resizing. The underlying ellipse must be
rotated to swap the axes.
Unlike ellipse that can be constrained to become a circle, ellipse arc cannot represent an arc of circle.
Moving the arc of ellipse by edge is the same as moving ellipse's center.
Version
Description
Sketcher
CreatePolyline
This tool works like the Sketcher Line tool, but creates continuous line segments
connected by their vertices. When starting the tool, the mouse pointer changes to a white
cross with a red polyline icon. The coordinates of the pointer are shown beside it in blue in M enu location
real time.
Sketch Sketcher
geometries Create polyline
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Sketcher Line
Usage
The Sketcher polyline tool has multiple modes that can be toggled with the letter M . For example you can draw tangent or
perpendicular arcs following a line or arc segment. Just repeatedly hit M to toggle through the different modes.
Pick points on an empty area of the 3D view, or on an existing object (auto constraints must be active in TaskView).
Pressing ESC or clicking the right mouse button cancels or finishes the function.
Sketcher Rectangle
Description
Sketcher
CreateRectangle
This tool draws a rectangle by picking two opposite points. When starting the tool, the
mouse pointer changes to a white cross with a red rectangle icon. The coordinates of the
pointer are shown beside it in blue in real time. M enu location
Sketch Sketcher
geometries Create
rectangle
Workbenches
Sketcher, PartDesign
Default shortcut
R
See also
Sketcher Polyline
Usage
After pressing the 'Create Rectangle' button, click once to set the first corner, then move the mouse and click a second
time to set the opposite corner.
Pressing ESC or clicking the right mouse button cancels the function.
Sketcher Triangle
Description Sketcher
CreateTriangle
Draws a equilateral triangle inscribed in a construction geometry circle. When starting the
tool, the mouse pointer changes to a white cross with a red hexagon icon. The coordinates
of the pointer are shown beside it in blue in real time. M enu location
Sketch Sketcher
File:SketcherCreateTriangleExample.png geometries Create
equilateral triangle
Workbenches
Usage Sketcher, PartDesign
Default shortcut
Press the Create equilateral triangle button,
Click once to set the center, See also
Move the mouse and click a second time to set one of the vertices.
Pressing ESC or clicking the right mouse button cancels the function.
When editing the sketch the circumscribed circle is visible, when you close the sketch is hidden.
Sketcher Square
Description Sketcher
CreateSquare
Draws a square inscribed in a construction geometry circle. When starting the tool, the
mouse pointer changes to a white cross with a red hexagon icon. The coordinates of the
pointer are shown beside it in blue in real time. M enu location
Sketch Sketcher
File:SketcherCreateSquareExample.png geometries Create square
Workbenches
Sketcher, PartDesign
Usage
Default shortcut
After pressing the Create square button, click once to set the center, then
See also
move the mouse and click a second time to set one of the vertices.
Pressing ESC or clicking the right mouse button cancels the function.
When editing the sketch the circumscribed circle is visible, when you close the sketch is hidden.
Sketcher Pentagon
Description Sketcher
CreatePentagon
Draws a pentagon inscribed in a construction geometry circle. When starting the tool, the
mouse pointer changes to a white cross with a red hexagon icon. The coordinates of the
pointer are shown beside it in blue in real time. M enu location
Sketch Sketcher
File:SketcherCreatePentagonExample.png geometries Create
pentagon
Workbenches
Usage Sketcher, PartDesign
Default shortcut
After pressing the Create pentagon button, click once to set the center, then
move the mouse and click a second time to set one of the vertices. See also
Pressing ESC or clicking the right mouse button cancels the function.
When editing the sketch the circumscribed circle is visible, when you close the sketch is
hidden.
Sketcher Hexagon
Description
Sketcher
Draws an hexagon inscribed in a construction geometry circle. When starting the tool, the CreateHexagon
mouse pointer changes to a white cross with a red hexagon icon. The coordinates of the
pointer are shown beside it in blue in real time.
M enu location
Sketch Sketcher
File:SketcherCreateHexagonExample.png geometries Create
hexagon
Workbenches
Usage Sketcher, PartDesign
Default shortcut
After pressing the Create hexagon button, click once to set the center, then
move the mouse and click a second time to set one of the vertices.
See also
Pressing ESC or clicking the right mouse button cancels the function.
When editing the sketch the circumscribed circle is visible, when you close the sketch is
hidden.
Sketcher Heptagon
Description
Sketcher
CreateHeptagon
Draws an heptagon inscribed in a construction geometry circle. When starting the tool, the
mouse pointer changes to a white cross with a red hexagon icon. The coordinates of the
pointer are shown beside it in blue in real time. M enu location
Sketch Sketcher
File:SketcherCreateHeptagonExample.png geometries Create
heptagon
Workbenches
Usage Sketcher, PartDesign
Default shortcut
After pressing the Create heptagon button, click once to set the center, then
move the mouse and click a second time to set one of the vertices.
See also
Pressing ESC or clicking the right mouse button cancels the function.
When editing the sketch the circumscribed circle is visible, when you close the sketch is
hidden.
Sketcher Octagon
Description
Sketcher
CreateOctagon
Draws an octagon inscribed in a construction geometry circle. When starting the tool, the
mouse pointer changes to a white cross with a red hexagon icon. The coordinates of the
pointer are shown beside it in blue in real time. M enu location
Sketch Sketcher
File:SketcherCreateOctagonExample.png geometries Create octagon
Workbenches
Sketcher, PartDesign
Usage
Default shortcut
After pressing the Create octagon button, click once to set the center, then
See also
move the mouse and click a second time to set one of the vertices.
Pressing ESC or clicking the right mouse button cancels the function.
When editing the sketch the circumscribed circle is visible, when you close the sketch is hidden.
Sketcher Slot
Sketcher
Description CreateSlot
Draws a slot by selecting the center of one semicircle and an endpoint of the other
M enu location
semicircle. When starting the tool, the mouse pointer changes to a white cross with a red
slot icon. The coordinates of the pointer are shown beside it in blue in real time. Sketch Sketcher
geometries Create slot
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Usage
After pressing the Create slot button, click once to set the center of one semicircle, then move the mouse and click
a second time to set endpoint of the other semicircle.
Pressing ESC or clicking the right mouse button cancels the function.
Sketcher Fillet
Description
Sketcher
CreateFillet
This tool creates a fillet between two lines joined at one point. Activate the tool, then select
both lines or click on the corner point.
M enu location
When starting the tool, the mouse pointer changes to a white cross with a red fillet icon. It
stays active so you can do multiple fillets. Sketch Sketcher
geometries Create fillet
Workbenches
Sketcher, PartDesign
Default shortcut
F
See also
None
Usage
Pick a vertex connecting two lines; or click on two connected lines, the distance you click from the vertex will set the fillet
radius.
Pressing ESC or clicking the right mouse button cancels or terminates the function.
Sketcher Trimming
Description
Sketcher
Trimming
This tool trims a line or circle to the nearest overlapping line.
M enu location
Sketch Sketcher
geometries Trim edge
Workbenches
Sketcher, PartDesign
Default shortcut
T
See also
None
Use
To use the tool click the 'Trim Edge' button, then click on the line segment that you want to trim. The line segment will be
trimmed to the nearest overlapping line(s).
Constraint PointOnPoint
This constraint tool takes two points as its argument and serves to make the two points
M enu location
coincident. (Meaning to make them as-one-point). In practical terms this constraint tool is
useful when there is a break in a profile for example - where two lines end near each other Sketch Sketcher
and need to be joined - a coincident constraint on their end-points will close the gap. constraints Constrain
coincident
Usage
Workbenches
Sketcher, PartDesign
As stated above, this tool takes two arguments - both are points.
1. Firstly it is necessary to highlight two distinct points. (Note this will not work if, for Default shortcut
example, you attempt to select the start and end point of the same line). None
2. Highlighting of a drawing item is achieved by moving the mouse over the item and See also
clicking the left-mouse-button. Constraint Lock,
3. A highlighted item will change colour to green. Constraint Point onto
Object
4. Subsequent items can be highlighted by repeating the above procedure(s) NOTE:
There is no-need to hold-down any special key like Ctrl to achieve multiple item
selection in a drawing.
5. Once you have two points highlighted, left-clicking on the 'PointOnPoint' constraint will cause the two points to become
coincident and be replaced by a single point.
NOTE: In order to make two points coincident, FreeCAD must necessarily move one, or both, of the original points.
Constraint Vertical
Description
Constraint
Vertical
Creates a vertical constraint to the selected lines or polylines elements. More than one
object can be selected.
M enu location
Usage
Sketch Sketcher
constraints Constrain
See Constraint Horizontal vertically
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Horizontal
Constraint Horizontal
Description
Constraint
Horizontal
The Horizontal Constraint forces a selected line or lines in the image to be parallel to the
horizontal axis of the sketch.
M enu location
Operation
Sketch Sketcher
constraints Constrain
horizontally
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Vertical
Apply the Horizontal Constraint by clicking on the Horizontal Constraint icon in the Sketcher Constraints toolbar or by
selecting the Constrain horizontally menu item in the Sketcher constraints sub menu of the Sketcher menu item in the Sketcher
work bench (or the Part Design menu item of the Part Design work bench). The selected line is constrained to be parallel to the
horizontal axis of the sketch.
Description
Constraint
Parallel
The Constrain Parallel constraint forces two selected straight lines or edges to be parallel
to each other.
M enu location
Operation
Sketch Sketcher
constraints Constrain
The sketch contains two randomly oriented lines. parallel
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Vertical,
Constraint Horizontal
Apply the Constrain Parallel constraint by selecting the Constrain Parallel icon from the Sketcher constraints toolbar or by
selecting the Constraint Parallel menu item from the Sketcher constraints sub menu of the Sketcher (Sketcher workbench
selected) or Part Design (Part Design workbench selected) menu item.
The selected lines are forced to be parallel to each other. Changing the orientation of one line will change the orientation of the
other to be the same.
Constraint Perpendicular
Description Constraint
Perpendicular
Perpendicular Constraint makes two lines to be perpendicular to each other, or two curves
to be perpendicular at their intersection. Lines are treated infinite, and arcs are treated as M enu location
full circles/ellipses. The constraint is also capable of connecting two curves, forcing them Sketch Sketcher
perpendicular at the joint, similarly to Tangent Constraint. constraints Constrain
perpendicular
Two curves will be made perpendicular at point of their intersection (either real, or of curves' extensions), and the point of
intersection will be implicit. This mode is applied if two curves were selected.
Accepted selection:
If direct perpendicularity between selected curves is not supported (e.g. between a line and an ellipse), a helper point will be
added to sketch automatically, and perpendicular-via-point will be applied.
Unlike for tangency, it is perfectly fine to reconstruct the point of perpendicularity by creating a point and constraining it to lie on
both curves (thus constraining the point to the intersection).
Accepted selection:
endpoint of line/arc/arc-of-ellipse + endpoint of line/arc/arc-of-ellipse (i.e., two endpoints of any two curves)
In this mode, an endpoint of one curve is constrained to lie on the other curve, and the curves are forced perpendicular at the
point. This mode is applied when a curve and an endpoint of another curve were selected.
Accepted selection:
line, circle, arc, ellipse, arc-of-ellipse + endpoint of line/arc/arc-of-ellipse (i.e., any curve + endpoint of any curve)
In this mode, two curves are made perpendicular, and the point of perpendicularity is tracked. This mode is applied when two
curves and a point were selected.
Accepted selection:
"Any point" can be a lone point, or a point of something, e.g. a center of a circle, an endpoint of an arc, or the origin.
For the constraint to work correctly, the point must be on both curves. So, as the constraint is invoked, the point will be
automatically constrained onto both curves (helper constraints will be added, if necessary), and the curves will be forced
perpendicular at the point. These helper constraints are plain regular constraints. They can be added manually, or deleted.
Compared to direct perpendicular, this constraint is slower, because there are mode degrees of freedom involved, but it
supports ellipses.
The placement of the point before the constraint is applied is a hint for the solver for where the perpendicularity should be.
Scripting
Perpendicular Constraint can be created from macros and from the python console by using the following:
# direct perpendicularity
Sketch.addConstraint(Sketcher.Constraint('Perpendicular',icurve1,icurve2))
# point-to-point perpendicularity
Sketch.addConstraint(Sketcher.Constraint('Perpendicular',icurve1,pointpos1,icurve2,pointpos2))
# point-to-curve perpendicularity
Sketch.addConstraint(Sketcher.Constraint('Perpendicular',icurve1,pointpos1,icurve2))
# perpendicular-via-point (plain constraint, helpers are not added automatically)
Sketch.addConstraint(Sketcher.Constraint('PerpendicularViaPoint',icurve1,icurve2,geoidpoint,pointpos))
where:
Description Constraint
Tangent
Tangent Constraint makes two curves to touch each other (be tangent). Lines are treated
infinite, and arcs are treated as full circles/ellipses. The constraint is also capable of M enu location
connecting two curves, forcing them tangent at the joint, thus making the joint smooth. Sketch Sketcher
constraints Constrain
tangent
How to use Workbenches
Sketcher, PartDesign
There are four different ways the constraint can be applied:
Default shortcut
1. between two curves (available not for all curves)
None
2. between two endpoints of a curve, making a smooth joint
See also
3. between a curve and an endpoint of another curve
Constraint point on object
4. between two curves at user-defined point
Two curves will be made tangent, and the point of tangency will be implicit. This mode is applied if two curves were selected.
Accepted selection:
If direct tangency between selected curves is not supported (e.g. between a circle and an ellipse), a helper point will be added
to sketch automatically, and tangency-via-point will be applied.
It is not recommended to reconstruct the point of tangency by creating a point and constraining it to lie on both curves. It will
work, but the convergence will be seriously slower, jumpier, and will require about twice as many iterations to converge than
normal. Use other modes of this constraint if the point of tangency is needed.
Accepted selection:
endpoint of line/arc/arc-of-ellipse + endpoint of line/arc/arc-of-ellipse (i.e., two endpoints of any two curves)
In this mode, an endpoint of one curve is constrained to lie on the other curve, and the curves are forced tangent at the point.
This mode is applied when a curve and an endpoint of another curve were selected.
Accepted selection:
line, circle, arc, ellipse, arc-of-ellipse + endpoint of line/arc/arc-of-ellipse (i.e., any curve + endpoint of any curve)
In this mode, two curves are made tangent, and the point of tangency is tracked. This mode is applied when two curves and a
point were selected.
Accepted selection:
"Any point" can be a lone point, or a point of something, e.g. a center of a circle, an endpoint of an arc, or the origin.
For the constraint to work correctly, the point must be on both curves. So, as the constraint is invoked, the point will be
automatically constrained onto both curves (helper constraints will be added, if necessary), and the curves will be forced
tangent at the point. These helper constraints are plain regular constraints. They can be added manually, or deleted.
Compared to direct tangency, this constraint is slower, because there are mode degrees of freedom involved, but if the point of
tangency is needed, it is the recommended mode because it offers better convergence compared to direct tangency + point on
two curves.
The placement of the point before the constraint is applied is a hint for the solver for where the tangency should be. With this
constraint, one can constrain two ellipses to touch each other in two places.
Scripting
Tangent Constraint can be created from macros and from the python console by using the following:
# direct tangency
Sketch.addConstraint(Sketcher.Constraint('Tangent',icurve1,icurve2))
# point-to-point tangency
Sketch.addConstraint(Sketcher.Constraint('Tangent',icurve1,pointpos1,icurve2,pointpos2))
# point-to-curve tangency
Sketch.addConstraint(Sketcher.Constraint('Tangent',icurve1,pointpos1,icurve2))
where:
Description
Constraint
EqualLength
The Constrain Equal constraint forces two or more line segments in a line , poly-line or
rectangle to have equal length. If applied to arcs or circles the radii are constrained to be
equal. It cannot be applied to geometry primitives which are not of the same type (e.g. line M enu location
segments and arcs).
Sketch Sketcher
constraints Constrain
Operation
equal
The example sketch below contains a number of sketch primitives ( line,poly-line, Workbenches
rectangle, arc and circle). Sketcher, PartDesign
Default shortcut
None
See also
Constraint Radius
Select two or more line segments (e.g. line and one side of the rectangle).
Click on the Constrain Equal icon in the Sketcher toolbar (in either the Sketcher or Part Design workbenches) or select the
Constrain Equal menu item from the Sketcher constraints sub menu item in either the Sketch or Part Design menu item
depending upon which workbench is selected (Sketcher or Part Design) to apply the constraint to the selected items.
and apply the Constrain Equal constraint as before. A pop-up message indicates that the constrained items have to be of
the same geometrical type (lines of zero curvature or lines of non-zero curvature).
Constraint Symmetric
Description
Constraint
Symmetric
The symmetrical constraint constrains two selected points to be symmetrical around a
given line, i.e., both selected points are constrained to lie on a normal to the line through
both points and are constrained to be equidistant from the line. Alternatively it can M enu location
constrain two points to be symmetric with respect to a third one.
Sketch Sketcher
constraints Constrain
Operation
symmetrical
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Parallel
Select two points (vertexes) in the sketch and a line in the sketch. The selected points and the line will be dark green.
Click on the SymmetricalConstraint icon in the Sketcher toolbar or select the Constrain Symmetrical menu item from the
Sketcher Constraints sub menu of the Sketcher (or Part Design) menu item. This will apply the constraint to the selected items.
See also
Operation Constraint Coincident
1. Firstly it is necessary to highlight an item you wish to constrain. For reasons alluded-to above it is wise to only highlight a
point.
2. Highlighting of a drawing item is achieved by moving the mouse over the item and clicking the left-mouse-button. A
highlighted item will change colour to green.
3. Once an item is highlighted, left-clicking on the lock constraint serves to lock the highlighted item in-place. This usually
manifests as two constraints: a horizontal distance constraint from the drawing axis origin, and a vertical constraint from
the drawing axis origin. These are set by default to the current co-ordinates of the point.
4. The vertical and horizontal constraints forming the lock can be edited by double clicking on the appropriate constraint to
be edited either in the drawing itself or in the Constraint tab of the Combo View pane. This will open a dialog box to edit
the constraint. Clicking on the horizontal constraint component produces:
.
5. Enter the desired value into the dialog box and click OK.
6. The new value of the constraint is applied to the drawing.
7. The vertical constraint may be similarly edited to constrain the point to the desired location.
Constraint HorizontalDistance
Description
Constraint
HorizontalDistance
Fixes the horizontal distance between 2 points or line ends. If only one item is selected,
the distance is set to the origin.
M enu location
Sketch Sketcher
constraints Constrain
horizontal distance
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Length,
Constraint VerticalDistance
Usage
Description
Constraint
VerticalDistance
Fixes the vertical distance between 2 points or line ends. If only one item is selected, the
distance is set to the origin.
M enu location
Usage
Sketch Sketcher
geometries Constrain
1. Pick one or two points vertical distance
2. Activate the constraint
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint
HorizontalDistance,
Constraint Length
Constraint Length
Description
Constraint
Length
Constraint Length constrains the length of a line, the perpendicular distance between a
point and a line or the distance between two points to have a specified value.
M enu location
Hint
Sketch Sketcher
constraints Constrain
If applicable please consider using the Horizontal Distance or Vertical Distance distance
constraints instead. These constraints are more robust and faster to calculate than the
here documented length constraint. Workbenches
Sketcher, PartDesign
Operation
Default shortcut
Select a line in the sketch, None
See also
Constraint
HorizontalDistance,
Constraint VerticalDistance
Apply the Length Constraint by selecting the icon from the Sketcher Constraints toolbar or selecting the Constrain distance
menu item from the Sketcher Constraints sub-menu of the Sketcher menu item in the Sketcher workbench (or Part Design in
the Part Design workbench).
The length of the line is constrained to its current value.Double clicking on the constraint in the 3D view or in the Tasks tab of
the Combo View will bring up a dialog box to allow the constraint value to be edited.
Enter the required value and click OK to set the constraint length.
The Length Constraint also constrains the distance between a line and a point.
The constraint may also be applied to two points, selected here at either end of a poly-line.
Applying the constraint as before, the distance between the two selected points is constrained. As described above it may be
edited to set a desired value.
Constraint Radius
Description
Constraint
Radius
This constraint constrains the value of the radius of a circle or arc to have a specific value.
Only one arc or circle can be constrained at a time.
M enu location
Sketch Sketcher
Operation constraints Constrain
radius
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Distance,
Constraint Horizontal,
Constraint Vertical
Select an arc or circle in the sketch by clicking on is ( turns dark green to indicate
selection).
Apply the constraint by clicking on the Constrain Radius icon in the Sketcher toolbar or selecting the Constrain radius menu
item from the Sketcher constraints sub menu of the the Sketcher (or Part Design) menu item (depending upon which
workbench is selected).
The radius is constrained to have its current value when the constraint is applied.
To change the constraint value either double click on the constraint in the 3D display (turning red indicates the constraint is
currently selected) or by double clicking on the constraint in the Constraints panel of the Tasks tab of the Combo View.
This will bring up a pop-up window.
Enter the desired value for the radius into the pop-up window and click OK to set the value of the constraint.
The constraint value is set to the value entered in the pop-up window.
Constraint InternalAngle
Description Constraint
InternalAngle
Select one, two or three entities in the sketch. The mode will be chosen depending on the selection.
Invoke the constraint by clicking its icon on the toolbar, or selecting the menu item, or using keyboard shortcut. A datum
edit dialog box pops up.
Modify the angle if necessary. The angle can be entered as an expression that will be evaluated and the result will be
stored. Click OK.
As with any datum constraint, it is possible to change the angle value later by double-clicking the constraint in constraint list or
3d view. Entering a negative value will cause the angle direction to flip.
Constraint modes
line slope angle
The constraint sets the polar angle of line's direction. It is the angle between the line and X axis of the sketch.
between lines
Accepted selection: line + line
In this mode, the constraint sets the angle between two lines. It is not required that the lines intersect.
In this mode, angle between two curves is constrained at the point of their intersection. The intersection point can be on curves'
extensions. The point should be specified explicitly, since curves typically intersect in more than one point.
For the constraint to work correctly, the point must be on both curves. So, as the constraint is invoked, the point will be
automatically constrained onto both curves (helper constraints will be added, if necessary), and the angle between curves
will be constrained at the point. These helper constraints are plain regular constraints. They can be added manually, or
deleted. There are no helper constraints on the example picture above, because the point selected is already the intersection
of curves.
Scripting
Angle Constraint can be created from macros and from the python console by using the following:
# angle-via-point (no helper constraints are added automatically when from python)
Sketch.addConstraint(Sketcher.Constraint('AngleViaPoint',icurve1,icurve2,geoidpoint,pointpos,angle))
where:
Constraint
Description SnellsLaw
Constrains two lines to follow the law of refraction of light as it penetrates through an
interface, where two materials of different refraction indices meet. See Snell's law on M enu location
Wikipedia for more info. Sketch Sketcher
Constraints Constrain
refraction (Snell's law)
P
normal
Workbenches
Sketcher, PartDesign
1
Default shortcut
None
See also
n1 v1 None
interface O
n2 v2
Q
Snell's law
How to use
The sequence of clicks is indicated by yellow arrows with numbers. n1, n2 are
labeles on this picture to show where the indices of refraction are.
You'll need two lines that are to follow a beam of light, and a curve to act as an interface. The lines should be on different
sides of the interface.
Select the endpoint of one line, an endpoint of another line, and the interface edge. The interface can be a line,
circle/arc, ellipse/arc of ellipse. Note the order you've selected the endpoints.
Invoke the constraint. A dialog will appear asking for a ratio of indices of refraction n2/n1. n2 corresponds to the medium
where the second selected endpoint's line resides, n1 is for the first line.
The endpoints will be made coincident (if needed), constrained onto the interface (if needed), and the Snell's law will
become constrained.
Note that there are several helper constraints smart-added (point-on-object, coincident), and they can be deleted if they
cause redundancy, or added manually if they were not added automatically. For the actual Snell's law constraint, the endpoints
of lines must coincide and lie on the interface, otherwise the behavior is undefined.
Using polyline tool, it is possible to speedup drawing of rays of light. In this case, one can select two coincident endpoints by
box selection.
Remarks
The actual Snell's law constraint enforces the plain law equation n1*sin(theta1) = n2*sin(theta2). It needs the line ends to
be made coincident and on the interface by other constraints. The necessary helper constraints are added automatically
based on the current coordinates of the elements.
Python routine does not add the helper constraints. These must be added manually by the script (see example in
Scripting section).
These helper constraints can be temporarily deleted and the endpoints dragged apart, which can be useful in case one
wants to construct a reflected ray or birefringence rays.
Unlike the reality, refraction indices are associated with rays of light, but not according to the sides of the boundary. This
is useful to emulate birefringence, construct paths of different wavelengths due to refraction, and easily construct angle
of onset of total internal reflection.
Both rays can be on the same side of the interface, satisfying the constraint equation. This is physical nonsense, unless
the ratio n2/n1 is 1.0, in which case the constraint emulates a reflection.
Arcs of circle and ellipse are also accepted as rays (physical nonsense).
Scripting
The constraints can be created from macros and from the python console by using the following function:
Sketch.addConstraint(Sketcher.Constraint('SnellsLaw',line1,pointpos1,line2,pointpos2,interface,n2byn1))
where:
Example:
StartPoint = 1
EndPoint = 2
MiddlePoint = 3
f = App.activeDocument().addObject("Sketcher::SketchObject","Sketch")
App.ActiveDocument.recompute()
Version
The constraint was introduced in FreeCAD v0.15.4387
Constraint Internal Alignment
Description
Constraint
InternalAlignment
This constraint aligns lines and points to particular places of a complex sketcher element
(there is just one "complex" element so far, the Ellipse).
M enu location
For Ellipse and its Arc, it supports constraining lines to become major and minor
diameters, and constraining points to positions of ellipse's foci. Sketch Sketcher
constraints Constrain
The constraint requires a lot of effort to use in the way other constraints are. It is hidden in InternalAlignment
the menu, and not exposed on any toolbars by default. There is a helper tool called
Show/Hide Internal Geometry which is exposed on workbenches' toolbars and aimed to Workbenches
completely remove the need to invoke the constraint manually. Sketcher, PartDesign
The first line that was selected gets aligned to become ellipse's major diameter (but if it is
not occupied already by another line, otherwise it will become minor diameter). The second line is aligned to become minor
radius. The lines are automatically switched to construction.
Likewise, the first point is constrained to become the first unoccupied focus, and the second point goes to the other focus.
Scripting
Sketch.addConstraint(Sketcher.Constraint('InternalAlignment:EllipseMajorDiameter',
index_of_line, index_of_ellipse))
Sketch.addConstraint(Sketcher.Constraint('InternalAlignment:EllipseMinorDiameter',
index_of_line, index_of_ellipse))
Sketch.addConstraint(Sketcher.Constraint('InternalAlignment:EllipseFocus1', index_of_point, 1,
index_of_ellipse))
Sketch.addConstraint(Sketcher.Constraint('InternalAlignment:EllipseFocus2', index_of_point, 1,
index_of_ellipse))
Remarks:
Version
Description Sketcher
MapSketch
This tool maps an existing sketch on the face of a shape. PartDesign features created
from this sketch will be fused with the underlying solid for additive features (Pad, M enu location
Revolution) or be subtracted from the underlying solid in case of subtractive features Part Design/Sketch Map
(Pocket, Groove). sketch to face...
Please note that this tool is not to be used to create new sketches. It only maps, or remaps Workbenches
an existing sketch to the face of a solid or a PartDesign feature. Typical use cases are: Sketcher, PartDesign
The sketch was created on a standard plane (XY, XZ, YZ) and you want to map it to Default shortcut
the face of a solid in order to build a feature upon it.
None
The sketch was mapped on a specific face of a solid but you need to map it to a
different face. See also
Create a new sketch
Repairing a broken model.
How to use
Select the face of a PartDesign feature or a solid.
Click on the M ap sketch to face icon in the toolbar (or go to the PartDesign or Sketch menu depending on which
workbench is active)
In the Select sketch dialog window that opens, select from the list the sketch to map to the face and click OK.
The sketch is automatically opened in edit mode.
Sketcher Reorient
Description
Sketcher
Use Reorient
1. M enu location
2. Part design Reorient
sketch
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
M ap sketch, New Sketch
Piano XY
Piano XZ
Piano YZ
Offset
1.
2.
3.
4.
Note
Sketcher Validate
32px Sketcher
Validate
M enu location
Sketcher Validate sketch
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
None
Sketcher Show Hide Internal Geometry
Description Sketcher
RestoreInternalAlignmentGeometry
The command deletes unused elements aligned to internal geometry, or
recreates the missing ones.
M enu location
Usage Sketch Sketcher tools Show/hide
internal geometry
Select an element of a sketch that supports internal alignment
(currently only Ellipse/Arc). Workbenches
Invoke the command by clicking a toolbar button, picking the menu Sketcher, PartDesign
item or using the keyboard shortcut.
Default shortcut
If there are free alignment places for the selected element, new Ctrl+Shift+E
construction geometry is created and aligned to the available places. If all
alignment places are occupied, the unused internal geometry is deleted See also
(the element is treated as unused if it is not constrained to anything else). Ellipse, Internal Alignment Constraint
Example
Create a new ellipse. New ellipses are always fully-packed. You'll see an ellipse and a bunch of construction geometry: major
diameter, minor diameter, foci.
Select minor diameter line and hit DEL . The diameter is gone, but the ellipse remains. How do we get the diameter back?
Select the ellipse and invoke the Sketcher_RestoreInternalAlignmentGeometry command. The diameter is restored.
Now, constrain the major diameter of the ellipse to some length. Select the ellipse and invoke the
Sketcher_RestoreInternalAlignmentGeometry command. Minor diameter and foci are deleted, but the major diameter is kept,
because it participates in other constraints. Ellipse's center remains too, because it is inherent, like center of a circle.
PartDesign Fillet
Description
PartDesign Fillet
This tool creates fillets (rounds) on the selected edges of an object. A new separate Fillet
entry (followed by a sequential number if there are already existing fillets in the document) M enu location
is created in the Project tree.
PartDesign Fillet
Workbenches
PartDesign, Complete
Default shortcut
None
See also
Select edges on the object Part Fillet
before starting the tool.
Usage
Select a single or multiple edges on an object, then start the tool either by clicking its icon or going into the menu.
In Fillet parameters in the TaskPanel, set the fillet radius either by entering the value, or by clicking on the up/down
arrows. The applied fillet is shown in real time.
Click OK to validate.
For a chain of edges tangential to one another, one single edge can be selected; the fillet will propagate along the chain.
To edit the fillet after the function has been validated, either double-click on the Fillet label in the Project tree, or right-
click on it and select Edit Fillet.
The PartDesign Fillet is not to be confused with its Part workbench counterpart. Although they share the same icon,
they are not the same, and are not used the same way. Here is how they differ from each other:
The PartDesign Fillet is parametric. After a fillet has been applied, its radius can be edited; this is not possible with the
Part Fillet.
Edges must be selected on an object before activating the PartDesign Fillet. WIth the Part Fillet, the tool can be started,
then a solid is selected, then edges.
The PartDesign Fillet creates a separate Fillet entry (followed by a sequential number if there are already existing fillets)
in the Project tree. The Part Fillet becomes the parent of the object it was applied to.
The PartDesign Fillet offers a live preview of the fillet applied to the object before validating the function.
The Part Fillet supports variable radii (with a start radius and an end radius). The PartDesign fillet doesn't.
Scripting
The tool Fillet can be used in a macro, and, from the Python console using the following function :
Example :
import PartDesign
from FreeCAD import Base
Box = Part.makeBox(10,10,10)
Box = Box.makeFillet(3,[Box.Edges[0]]) # pour 1 Fillet
Box = Box.makeFillet(3,[Box.Edges[1],Box.Edges[2],Box.Edges[3],Box.Edges[4]]) # for several Fillets
Part.show(Box)
PartDesign Chamfer
Description
PartDesign
Chamfer
M enu location
Part Design Chamfer
Workbenches
PartDesign, Complete
Slection des artes
avant de dmarrer la Usage Default shortcut
commande. None
1.
See also
2.
Chamfer Part
3.
Description
PartDesign Draft
This tool creates angular draft on the selected faces of an object. A new separate Draft
entry (followed by a sequential number if there are already existing drafts in the document)
M enu location
is created in the Project tree.
Part Design Draft
Workbenches
Part Design
Default shortcut
None
2 faces have been added, Click Add Face or Remove Face, then select a single
and a 10 deg. draft face to update the list of active faces. Repeat as
applied. The bottom plane needed.
has remained
dimensionally stable, Draft Angle
while the draft has made
the top plane smaller. Set the Draft Angle by entering a value or by clicking
on the up/down arrows. The applied draft angle is
shown in real time.
Neutral Plane
Click Neutral Plane, then select the plane that must not
The Neutral Plane has change dimensionally. The change is made in real
been changed to the Top time.
Surface. Now, the top
plane has stayed Pull Direction
dimensionally stable,
while the draft has made Click Pull Direction, then select an edge. Pull Direction
the bottom plane larger. is only effective if the Neutral Plane has been set.
Results can be unpredictable.
Introduction PartDesign
Mirrored
'Mirror features' - This tool takes a set of one selected features as its input (the 'original'),
and produces with it a second set of features mirrored on a plane. For example: M enu location
PartDesign Mirrored
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Use
Mirror Plane Selection
When creating a mirrored feature, the 'Mirrored parameters' dialogue offers four different ways of
specifying the mirror line or plane.
Select reference...
Allows you to select a plane (such as a face of an object) to use as a mirror plane.
If the sketch which defines the feature to be mirrored also contains a construction line (or lines),
then the drop down list will contain one custom sketch axis for each construction line. The first
construction line will be labelled 'Sketch axis 0'.
Preview
The mirror result can be previewed in real time before clicking OK by checking "Update view".
Limitations
Currently, only the last feature in the feature tree can be chosen as the 'original' therefore,
it is not possible to choose more than one feature to be mirrored
it is not possible to select more features to add to the list view of 'originals'
Once the Mirrored feature has been started or been completed, it is not possible to replace the original feature for a
different one.
PartDesign LinearPattern
Introduction PartDesign_LinearPattern
'Make a linear pattern of features' - This tool takes a set of one or more selected
features as its input (the 'originals'), and produces with it a second set of features M enu location
translated in a given direction. For example: PartDesign -> LinearPattern
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Options
When creating a linear pattern feature, the 'linear pattern parameters' dialog offers two different
ways of specifying the pattern direction.
Standard axis
One of the standard axes X, Y or Z can be chosen with the radio buttons. The pattern direction can
be reversed by ticking 'Reverse direction'.
Select a face
Pressing the button labeled 'Direction' allows to select a face or an edge from a pre-existing solid to
specify the direction. The pattern direction will be normal to the face if a face is selected. Note that
the button must be pressed again every time to select a new face or edge.
Select originals
The list view shows the 'originals', the features that are to be patterned. Clicking on any feature will
add it to the list.
Length and Occurrences
Specifies the length to be covered by the pattern, and the total number of pattern shapes (including
the original feature). For example, six occurrences in a length of 150 would give a spacing of 30
between patterns (150 divided by 5, since there are 5 'gaps' between a total of six occurrences!).
Limitations
Pattern shapes may not overlap one another except for the special case of only two occurrences (original plus one copy)
Any pattern shapes that do not overlap the original's support will be excluded. This ensures that a PartDesign feature
always consists of a single, connected solid
For further limitations, see the mirrored feature
PartDesign PolarPattern
Introduction PartDesign
PolarPattern
'Make a polar pattern of features' - This tool takes a set of one or more selected features
as its input (the 'originals'), and produces with it a second set of features rotated around a M enu location
given axis. For example: PartDesign -> PolarPattern
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Options
When creating a polar pattern feature, the 'polar pattern parameters' dialogue offers two different ways
of specifying the pattern rotation axis.
Standard axis
One of the standard axes X, Y or Z can be chosen with the radio buttons. The pattern direction can be
reversed by ticking 'Reverse direction'.
Select a face
Pressing the button labeled 'Direction' allows to select an edge from a pre-existing solid to specify the
direction. Note that the button must be pressed again every time to select a new edge.
Select originals
The list view shows the 'originals', the features that are to be patterned. Clicking on any feature will add
it to the list.
Limitations
See linear pattern feature
Examples
PartDesign Scaled
Introduction PartDesign
Scaled
'Scale features' - This tool takes a set of one or more selected features as its input (the
'originals'), and scales them by a given factor. Since the scaling takes place around the M enu location
centre of gravity of the selected features, they usually disappear inside the scaled PartDesign Scaled
versions. Therefore, normally it is only useful to use scaling as part of the MultiTransform
feature. Workbenches
PartDesign, Complete
See also
None
Select originals
The list view shows the 'originals', the features that are to be
scaled. Clicking on any feature will add it to the list.
Limitations
Scaling always happens with the centre of gravity of the feature as the base point.
See linear pattern feature for other limitations
PartDesign MultiTransform
Introduction PartDesign
MultiTransform
'Make a pattern from combinations of transformations' - This tool takes a set of one or
more selected features as its input (the 'originals'), and allows to apply several M enu location
transformations in sequence to them. For example, to produce a flange with a double row PartDesign -> MultiTransform
of holes, the hole (the 'original') is first patterned in a linear pattern in the X direction, and
then patterned eight times in a polar pattern around the Y axis. Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Options
When creating a multitransform feature, the 'multitransform parameters' dialogue offers two
different list views.
Select originals
The list view shows the 'originals', the features that are to be patterned. Clicking on any feature
will add it to the list.
Select transformations
This list can be filled with a combination of the simple transformations mirrored, linear pattern,
polar pattern and scaled. The transformations will be applied one after the other. The context
menu offers the following entries:
Edit
Allows editing the parameters of a transformation in the list (double-clicking will have the same
effect)
Delete
Add transformation
Move Up/Down
Limitations
A scaled transformation should not be the first in the list
The scaled transformation must have the same number of occurrences as the transformation immediately preceding it in
the list
For further limitations, see the linear pattern feature
Examples
The smallest pad was first patterned three times in X direction and then scaled to factor two (so the three occurrences have
scaling factor 1.0, 1.5 and 2.0). Then a polar pattern was applied with 8 occurrences.
The pocket was first mirrored on the YZ plane and then patterned with two linear patterns to give a rectangular pattern.
PartDesign WizardShaft
Introduction PartDesign
WizardShaft
This tool allows you to create a shaft from a table of values, and to analyse forces and
moments. You can start the wizard from the Part Design menu or by typing M enu location
Part Design Shaft design
wizard...
Gui.runCommand('PartDesign_WizardShaft')
Workbenches
PartDesign, Complete
into the Python console of FreeCAD. The wizard will start and show a default table, the Default shortcut
corresponding shaft part and force/moment graphs.
None
See also
None
The top of the window is taken up by the table. It is organized into numbered columns which correspond to segments of the
shaft. A shaft segment is characterized by having certain length and diameter. The main window shows two tabs. One is the
shaft part itself (a revolution feature), shown in the image above. The second tab shows graphs of the shear forces and
moments created by the loads defined in the table.
Prerequisites
The shaft design wizard depends on the matplotlib library to create and display the graphs of shear force and bending
moment. On Debian/Ubuntu-based systems, it is available through the python-matplotlib package.
Parameters
For each shaft segment, the following parameters can be defined
(Other rows and load types exist but no functionality has been implemented yet)
Menus
To add a new shaft segment, right-click into the empty space to the right of the table, and choose "Add column".
Limitations
It is not possible to have adjacent shaft segments with the same diameter.
Planned functionality
Table-driven chamfers and rounds on the shaft edges
Recognize a previously created shaft wizard part and initialize the table values from it
Shaft stress calculation
Visualization of loads on the shaft (can use the same functionality as for FEM module)
Definition of loads as a Document Object (can use the same functionality as for FEM module)
Material database
Allow loads in the Z-direction as well as in Y-direction (requires definition of loads as a Document Object, otherwise the
table will become very long)
PartDesign InvoluteGear
Description PartDesign
InvoluteGear
This tool allows you to create a 2D profile of an involute gear. This 2D profile is fully
parametric, and can be padded with the PartDesign Pad feature. M enu location
Part Design Involute gear...
Workbenches
PartDesign
Default shortcut
None
See also
None
How to use
1. Go to the Part Design Involute gear... menu.
2. Set the Involute parameters
3. Click OK.
Parameters
Number of teeth
Modules
Pressure angle
Acute angle between the line of action and a normal to the line connecting the gear centers. Default is 20 degrees. (M ore
info)
True or false
True or false
Bugs
In v0.14.3700/3702/3703, the 3D view does not resize automatically upon creation of the involute gear. Click on the
Fit all icon to display the involute gear on screen.
Sketcher Tutorial
Introduction
The Sketcher is a tool to generate 2D-objects for usage in parts design. The sketcher is different to traditional drawing tools. A
way to show the difference is the construction of a triangle. A triangle is fully defined by 3 values, which can be any from the
following list: side length, angle, height, area. The one exception is three angles, which will not define the size.
In order to construct a triangle from 3 lengths in the traditional way, the following has to be done:
The wikipedia:Triangle page shows a collection of formulas to calculate the missing information in order to draw a triangle
from the minimum specification. Those are needed, if the triangle has to be defined by pre-calculated coordinates.
The Sketcher is different. The formulas and the above helper constructions are not needed. In order to understand the
difference, it is best to construct a triangle by yourself.
A new sketch will be created by clicking at . A dialog appears, where the orientation of the new sketch in the 3D-space can
be selected. It doesn't matter in this case, so the xy-plane can be confirmed. A new empty sketch will be created and opened in
edit mode. A grid with a coordinate system will be shown with a red point at the origin.
In the Sketcher it is ok to draw an arbitrary triangle with the polyline tool and define its properties in a later step. Each click
in the drawing plane sets a vertex. The triangle needs to be closed. So for the last line a click is needed on the first created
vertex. A red point should be visible near the mouse pointer before clicking.
This will make sure that the last vertex is identical to the first one and the profile is closed. Those symbols that appear beneath
the drawing pointer do indicate auto-constraints. They are set automatically at clicking at this location. The red dot beneath the
drawing pointer indicates a coincidence constraint between two vertices, i.e. the vertices of this different drawing elements are
constrained to an identical location.
The created triangle is flexible. A vertex can be touched with the mouse and dragged around. The sides of the triangle follow
the vertex. The same can be done with a line.
Each length of the side is now easily defined by selecting it with the mouse: selected item turns into green. When clicking on
the length tool, a dialog opens and the desired length can be put in. The picture below shows a triangle with side lengths set
to 35 mm, 27 mm and 25 mm. The baseline was set horizontally by selecting it and clicking on the horizontal constraint tool .
These length-definitions are called constraints. Constraints are used to define a fixed design from the flexible geometric input.
The sketcher provides all constraints needed to define any kind of triangle. Only the area can not be used to define one. So
the created triangle can be redefined by changing the value of a constraint or by deleting constraints and add other ones. Here
comes a list of triangles with other given properties. It is no problem to turn the just created triangle into one of these.
One or two angles given: Two sides of the triangle needs to be selected. A click on opens a dialog to define the
angle.
Right triangle: Two sides of the triangle needs to be selected. A click on sets a right angle between the two sides.
Equilateral: One side has to be set to a defined length. Then all sides needs to be selected. A click on defines two
equal length constrains in order to give all sides the same length.
Isosceles triangle (two identical length) with given height: Select first the two sides with the equal length. A click on
sets a equality between the two sides. Then select the base line and the top vertex and click the length tool.
Constraints can be selected by clicking on the symbol or by clicking in the constraint-list. They can be deleted or in case of
constraints with a value edited after a double click. A given triangle can be later changed into another type of triangle by editing
or changing the constraints. The sketcher is a part of the parametric FreeCAD-modelling approach. What you have created,
can be easily changed at a later time, if for example a variant of the design is needed.
The above shown triangles have white lines. This is an indication that the sketch has some degrees of freedom left. It can be
tested by dragging on some lines or points. If the line or point moves, this item is not fully defined. A sketch with no degrees of
freedom left turns green.
The isoscele triangle is missing the length setting for the base line and it can move and rotate freely in the sketcher drawing
plane.
If the triangle properties are defined, it still needed to be fixed in the drawing plane. The sketcher drawing plane has a
coordinate system. The origin of the coordinate system is visible as the red dot in the center of the pink x-axis and light-green
y-axis. The easiest way to fix it, is selecting a vertex and clicking at . This adds a horizontal and a vertical distance from the
vertex to the origin of the coordinate system. The triangle may still have an degree of freedom for rotation. So one sides needs
a horizontal or vertical constraint or an defined angle to one of the coordinate system axes. The next picture shows a fully
constraint sketch. All lines and vertices have now a green color.
In this way a wide variety of geometric problem can be solved. But there is also a disadvantage. If the set of equations has
multiple solutions, we may get something totally different from what we expect. This is especially annoying, if the same design
should be used for different dimensions. The typical symptom is, that after a change of a length constraint, the sketch flips to
something totally different. A simple example is the division of a distance into three equal partitions. The following picture shows
three lines in a row with equality and parallel constraint set. The total distance is set to 10 mm.
This works well, as long as only larger distances are put in. When the distance is reduced above a certain ratio, the lines are
folding together. So we do not get any more a third of the given distance but the distance itself or two third of it. Some lines of
our row have changed their orientation. This gives still a valid solution for the set of constraints, but is not what was intended.
So following image of the same sketch shows this. The length constraint was set to 1000 mm and then reduced to 5 mm.
The solution is to define an angle of 180 between the partition lines as replacement of the parallel constraint. The 180-
constraint has only one solution. The sketch is now robust against large changes of the distance. It has to be said, that also a
0-constraint serves for the same purpose, where appropriate.
The 180-constraint is a solution for a lot of problems. Some older versions of FreeCAD have problems to show the 180-
constraint in the sketcher plane. In most of the cases the 180-arc is not shown as expected in the sketcher drawing plane.
This is a known issue for FreeCAD before version 14.3613.
In case of several incremental dimensions in a straight line, it may be advisable to draw a zig-zag-line first and then set the
180-constraints. This helps, not forgetting one, or setting one twice.
The following table shows some constraints combinations for the definition of a simple elbow. The combination was tested by
enlarging the 10 mm length horizontal dimension to greater values until the elbow flips its orientation. The table documents for
each shown constraint combination the changed length where the flipping occurs.
Flips at 51 mm
Flips at 52 mm
Definition of length: Equality constraint for definition of length
Flips at 51 mm
Flips at 82 mm
The horizontal line does not flip at a test of 10 km, but the vertical line
was flipped!
Recommendation: Use angle constraints and horizontal and vertical dimension constraints at critical places in order
to make a sketch robust against dimension changes.
What happens, if those two lines already have an equality constraint and a parallel constraint and the symmetry constraint is
added too? Now the parallel property is defined by two constraints and the equal length is also defined by two constraints. In
principle the underlying system of equations should have a solution. But there may be numerical problems. This can be tested
by trying to move the lines. In most cases the lines are frozen, even if the sketcher still reports several degrees of freedom.
The above case shows a problem that seems to be difficult to solve for the sketcher programmers. So the user has to take
care, to avoid such situations. Sketches with redundant constraints do behave unexpected and problematic. Symptoms of
those redundant constraints are the above frozen state or reported redundant constraints after modifying a different object in
the sketch.
In general the sketcher gives a warning, when redundant constraints are detected. But this detection mechanism seems not to
work in all cases. When the problem is recognized, it can be avoided by just deleting the redundant constraints. Sometimes it is
necessary to choose a different combination of constraints.
A different problematic case are parallels with an intersection point in infinity. It is possible to set a 180-constraint for two
parallel lines without an intersection point. This is not recommended. An angle to an other line or axis should be used instead.
A different problem is the change of orientation of angles. This can happen if, angle changes above 180 are made. Doing this
in smaller steps avoid the problem.
Giving the task to make a rectangle with the side length having the golden ratio. Wikipedia shows how to construct two lines
with a length ratio of the golden ratio.
Goldener Schnitt Konstr beliebt.svg
The sketcher is a perfect tool to construct a rectangle with the golden ratio for the side length. The size of the rectangle can be
later changed without making a new construction. The construction steps for the golden ratio according to Wikipedia are:
1. Having a line segment AB, construct a perpendicular BC at point B, with BC half the length of AB. Draw the hypotenuse
AC.
2. Draw an arc with center C and radius BC. This arc intersects the hypotenuse AC at point D.
3. Draw an arc with center A and radius AD. This arc intersects the original line segment AB at point S. Point S divides the
original segment AB into line segments AS and SB with lengths in the golden ratio.
Draw a rectangle in the sketch. Use the button The following picture shows the rectangle. FreeCAD did add
horizontal and vertical constraints to the rectangle. This rectangle can not be rotated.
The rectangle should stay in the center of the coordinate system. To achieve this, a symmetry constraint is added to a
horizontal line. This is done by selecting first the two vertices of the horizontal line and then the vertical axis of the coordinate
system. The symmetry constraint is added by clicking on the button . The same is done for a vertical line, but instead now
the horizontal axis is selected as symmetry axis. The picture below shows the result. The rectangle stays now at the center and
can only be resized but not moved.
This was the preparation for the rectangle. The top horizontal line should be the distance AS of the golden ration construction.
An additional line is needed to represent the SB-distance. It is drawn a little bit skewed as shown below. This avoids the auto-
constraining to horizontal. This line should instead be constrained later with a 180-angle, in order to avoid the existence of
multiple solutions to the constructed constrain-combination. If the line is drawn with an horizontal constrained, the sketcher will
complain later at adding the 180-angle constrained. The horizontal constrained has to be removed in such a case. The picture
shows how to add an angle-constraint by selecting two lines and clicking at . After adding a line, it is often advisable to drag
at the line with the mouse. This will easily show, if a line is not attached to the other drawn elements. If a line is not connected
right to the other lines, problems may arise in later steps of the part construction.
The last line is not part of the rectangle. It is therefore necessary to convert it into a construction line. Selecting the line and
clicking at the button does the conversion.
The line has now a blue color as visible below. The recipe from Wikipedia for the golden ratio requires a line half of the
distance AB. In order to get a reference point for this, an additional vertex is set at the line with the tool. This is shown
below.
The reference point should stay at the center of the distance AB. This will be achieved by selecting first the two endpoints of
the distance AB and third selecting the center point. When all three points are selected in the right sequence, the symmetry
constraint can be set at clicking at the button, as shown below.
The Picture below shows already the second side BC of the construction triangle. This line was drawn as described above and
converted to a construction line. This line must have a vertical constraint as visible in the picture. This can be easily achieved
by drawing the line nearly vertical. If the line is nearly vertical a vertical constraint symbol is shown and set by the Sketcher
when finishing the line at this state.
The line BC must have half of the length of AB. There is only a reference point available for this purpose, so the equality
constraint can not be used. The equality constraint would need a line with this length as reference, which is not available in the
construction. Therefore the classical arc is used to define the length BC. The picture below shows the drawing of the arc. The
arc-tool [[Image:|24px]] is used. First the center point is set at B. The point should be visible beneath the arc-tool at clicking at
B. Often the arc-tool has not has to be not directly over the target point but a little beneath, in order to get the coincidence
point visible. Second the radius of the arc is defined by setting the next point at the reference point. The last point of the arc is
set in the neighborhood of the point C. It is important, that the first two points are fixed to C and the center point. This should
be tested with dragging at the arc after finishing it.
In order to define the length of BC, the line must end at the arc. This will be done by setting a coincidence constraint between
the last arc point and the C point as shown below. Both points have to be selected and the create a coincidence button
has to be clicked.
The next picture shows the ready triangle. The hypotenuse AC is already drawn and converted to a construction line.
Now step 2 of the Wikipedia recipe has to be constructed. A second arc has to be drawn with the center point at C and the
starting point at B. The last point should be end at the hypotenuse as shown in the picture below.
The drawn arc was converted to a construction line. Now step 3 of the Wikipedia recipe starts with drawing the last arc as
shown in the picture below. The radius of this arc has to be defined with the above constructed point on the hypotenuse. The
last point will usually not end at a corner of the rectangle. But this is not a problem, as it will be fixed later. The last point may
set as shown below.
Now the final step has to be made, in order to made the horizontal line of the rectangle equal to the distance AS. This is shown
below by setting a coincidence constraint between the end of the last arc and the corner of the rectangle.
Now the vertical line has to be made the length of the distance SC. Setting an equality constraint by selecting the button as
shown below, will do this.
The next picture shows the rectangle with a side length ratio equal to the golden ratio. The rectangle should have only left one
degree of freedom. So at dragging at it, it should only change its size but not move. If a certain size of one side is needed, a
length constraint can be added to this side. Other wise the sketch is ready and can be closed. Only a rectangle should than be
visible in the FreeCAD window.
There should be only three dimensions needed to define the frame. In order to make changing dimensions easier, the
constraints can be renamed to something memorable. Just select the constraint in the list view and press <F2>. The constraint
can be named for example to "Thickness". The drawing below shows the dimensions. The peak at the right side should have
two times the wall thickness.
The sketch should look as intended also after changing the key dimensions for example to 2000 mm and back to 30. You may
need to use angle constraints at certain places to reach this goal. The picture below shows a sketch, which was not robust
against such changes. It is unusable now. In order to get the original state back, the undo-button can be used.
The above sketch is unusable for the Part-Design Workbench. Only Profile without intersecting lines are allowed. Construction
lines may intersect. Those are not used for making solids.
One of the main usage of the Sketcher is the construction of parts in the Part-Design-workbench. The already existing
geometry can be used similar to construction lines. As this tutorial takes its focus more on the basic sketcher functionality, have
a look here for usage of external geometry: Sketcher External
Draft Workbench
(Redirected from Draft Workbench)
The Draft workbench allows to quickly draw simple 2D objects in the current document, and offers several tools to modify them
afterwards. Some of these tools also work on all other FreeCAD objects, not only those created with the Draft workbench. It
also provides a complete snapping system, and several utilities to manage objects and settings.
Drawing objects
Arc: Draws an arc segment from center, radius, start angle and end angle
ShapeString: The ShapeString tool inserts a compound shape representing a text string at a given point in the
current document
Modifying objects
These are tools for modifying existing objects. They work on selected objects, but if no object is selected, you will be invited to
select one.
Path Array: Creates an array of objects by placing the copies along a path
Utility tools
Additional tools available via right-click context menu, depending on the selected objects.
Set working plane: Sets a working plane from a standard view or a selected face
Finish line: Ends the drawing of the current wire or bspline, without closing it
Close line: Ends the drawing of the current wire or bspline, and closes it
Apply style: Applies the current style and color to selected objects
Toggle display mode: Switches the display mode of selected objects between "flat lines" and "wireframe"
File formats
The Draft module provides FreeCAD with importers and exporters for the following file formats:
Autodesk .DXF: Imports and exports Drawing Exchange Format files created with 2D CAD applications
SVG (as geometry): Imports and exports Scalable Vector Graphics files created with vector drawing applications
Open Cad format .OCA: Imports and exports OCA/GCAD files, a potentially new open CAD file format
Airfoil Data Format .DAT: Imports DAT files describing Airfoil profiles
Autodesk .DWG: Import and exports DWG files via the DXF importer, when the Teigha Converter utility is installed.
FreeCAD and DWG Import: Import and exports DWG files
Additional features
Preference settings
Scripting
The Draft module features a complete Draft API so you can use its functions in scripts and macros
Tutorials
Draft tutorial
Draft Line
The Line tool creates a straight, two-points line in the current work plane. It takes the M enu location
linewidth and color previously set on the Tasks tab. The Line tool behaves exactly like Draft Line
the Draft Wire tool, except that it stops after two points.
Workbenches
Draft, Arch
Default shortcut
L I
See also
Draft Wire
How to use
1. Press the Draft Line button, or press L 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 type a coordinate
Options
Press X , Y or Z after the first point to constrain the second 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
second point are relative to the first 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 Line tool will restart
after you give the second point, allowing you to draw another line segment without pressing the Line 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 CTRL + Z or press the Undo button to undo the last point.
Press ESC or the Cancel button to abort the current Line command.
Properties
DATA Start: The start point
DATA End: The end point
Scripting
The Line tool can by used in macros and from the python console by using the following function:
Creates a line between the two given vectors. The current draft linewidth and color will be used.
Returns the newly created object.
Example:
The Wire tool creates a polyline (sequence of lines made of several segments) in the M enu location
current work plane. It takes the linewidth and color previously set on the Tasks tab. Draft Wire
The Wire tool behaves like the Draft Line tool, except that it doesn't stop after two points.
Workbenches
Draft, Arch
Default shortcut
W I
See also
Draft Line, Draft BSpline
How to use
1. Press the Draft Wire button, or press W then I 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 wire. If the wire is closed, it
will also be a face, even if it appears as wireframe.
Options
Press F or the Finish button to finish the wire, leaving it open
Press C or the Close button or click on the first point to finish the wire, 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 Wire tool will restart
after you finish or close it, allowing you to draw another one without pressing the Wire 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 wire 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 wire 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 Line command.
Closed wires, when in "Flat Lines" display mode, can display a hatch pattern, by setting their "Pattern" property below.
Properties
DATA Closed: Specifies if the wire is closed or not
DATA Chamfer Size: Specifies the size of chamfered corners
DATA Fillet Radius: Specifies a curvature radius to give to the nodes of the wire
VIEW End Arrow: Shows an arrow symbol at the last point of the wire, so it can be used as an annotation leader line
VIEW Pattern: Specifies a hatch pattern to fill the wire with (Closed Wire)
VIEW Pattern Size: Specifies the size of the hatch pattern
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
The Circle tool creates a circle in the current work plane by entering two points, the M enu location
center and the radius, or by picking tangents, or any combination of those. It takes the Draft -> Circle
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. 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
Scripting
The Circle tool can by used in macros and from the python console by using the following function:
Example:
import Draft
myCircle = Draft.makeCircle(2)
Draft Arc
Draft Arc
Description
The Arc tool creates an arc in the current work plane by entering four points, the center, M enu location
the radius, the first point and the last point, or by picking tangents, or any combination of Draft Arc
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. 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])
Example:
import Draft
myArc = Draft.makeCircle(2,startangle=0,endangle=90)
Draft Ellipse
The Ellipse tool creates an ellipse in the current work plane by entering two points, M enu location
defining the corner of a rectangular box in which the ellipse will fit. It takes the linewidth Draft -> Ellipse
and color previously set on the Tasks tab.
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
Scripting
The Ellipse tool can by used in macros and from the python console by using the following function:
import Draft
myEllipse = Draft.makeEllipse(4,2)
Draft Polygon
The polygon tool creates a regular polygon by picking two points, the center and a second M enu location
point defining a radius. It takes the linewidth and color previously set on the Tasks tab. 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
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
Draft Rectangle
Description
M enu location
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
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
VIEW 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 Pattern: Specifies a hatch pattern to fill the wire with.
VIEW Pattern Size: Specifies the size of the hatch pattern
Scripting
The Rectangle tool can by used in macros and from the python console by using the following function:
makeRectangle (length, width, [placement], [facemode])
Example:
import FreeCAD,Draft
Draft.makeRectangle(10,4)
Draft Text
Draft Text
Description
M enu location
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. Draft 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
VIEW 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.
Scripting
The Text tool can by used in macros and from the python console by using the following function:
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
The dimension tool creates a dimension in the current document with two points defining M enu location
the distance to measure, and a third point specifying where the dimension line passes. Draft 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
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
VIEW
measurement value
VIEW 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 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:
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
M enu location
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 Draft BSpline
behaves exactly like the Draft Wire tool.
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])
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
The Point tool creates a simple point in the current work plane, handy to serve as M enu location
reference for placing other objects later. It takes the color previously set on the Tasks tab. 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 Draft
ShapeString
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. 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])
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
The facebinder a very simple object constructed from selected faces of other objects. It is M enu location
of parametric, you can modify the original object and the facebinder object updates Draft Facebinder
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 Workbenches
covers several pieces of walls. You can move and rotate the facebinder around after its Draft, Arch
creation, everything will stay linked to the original faces.
Default shortcut
F F
See also
None
How to use
1. Select faces on objects (use CTRL to select several faces)
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:
Limitations
Not available before version 0.14
Draft BezCurve
The BezCurve tool creates a Bezier Curve (or a piecewise Bezier Curve) from several M enu location
points in the current work plane. It takes the linewidth and color previously set on the Draft -> BezCurve
Tasks tab.
Workbenches
The object is created as a single Bezier Curve of degree (number_of_points - 1). This can Draft, Arch
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 . Default shortcut
B Z
See also
None
How to use
1. Press the Draft BezCurve button, or press B then Z 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 and close the curve.
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 .
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
The Move tool moves or copies the selected objects from one point to another on the M enu location
current work plane. If no object is selected, you will be invited to select one. Draft -> Move
Workbenches
Draft, Arch
Default shortcut
M V
See also
None
How to use
1. Select objects you wish to move or copy
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:
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
This tool rotates or copies the selected objects by a given angle around a point on the M enu location
current work plane. If no object is selected, you will be invited to select one. Draft -> Rotate
Workbenches
Draft, Arch
Default shortcut
R O
See also
None
How to use
1. Select objects you wish to rotate or copy
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:
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
The Offset tool offsets the selected object by a given distance on the current work plane. M enu location
If no object is selected, you will be invited to select one. Draft -> Offset
Workbenches
Draft, Arch
Default shortcut
O S
See also
None
How to use
1. Select objects you wish to offset
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
Draft Trimex
Description
M enu location
This tool trims/cuts and extends lines and polylines, and extrudes faces. 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
This tool upgrades selected objects in different ways. If no object is selected, you will be M enu location
invited to select one. Draft 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
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:
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
This tool downgrades selected objects in different ways. If no object is selected, you will be M enu location
invited to select one. 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
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
Scripting
The Downgrade tool can be used in python scripts and macros by using the following function:
downgrade (objects, [delete], [force])
Example:
import FreeCADGui,Draft
selection = FreeCADGui.Selection.getSelection()
Draft.downgrade(selection)
Draft Scale
This tool scales selected object(s) around a base point. If no object is selected, you will be M enu location
invited to select one. It can also be used to mirror objects. Draft Scale
Workbenches
Draft, Arch
Default shortcut
S C
See also
Draft Clone
How to use
1. Select objects you wish to scale
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
This tool allows you to edit graphically certain properties of the selected object, such as M enu location
the vertices of a Wire, or the length and width of a Rectangle, or the radius of a Circle. It Draft Edit
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. 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 Del point button allows you to remove points from Wires and BSplines by clicking on the points to
remove
Scripting
Not available. Each of the above object can be modified by changing its properties directly.
Draft WireToBSpline
Description Draft
WireToBSpline
Workbenches
Draft, Arch
Default shortcut
None
See also
None
How to use
1. Select a wire or a BSpline
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:
import FreeCAD,Draft
points = FreeCAD.ActiveDocument.ActiveObject.Points
Draft.makeBSpline(points)
import FreeCAD,Draft
points = FreeCAD.ActiveDocument.ActiveObject.Points
Draft.makeWire(points)
Draft AddPoint
This tools allows you to add additional points to Wires and BSplines. M enu location
Draft Add Point
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
Draft DelPoint
This tools allows you to remove points from Wires and BSplines. M enu location
Draft Remove Point
Options
This functionality is also available inside the Draft Edit tool
Scripting
Not available, but removing points from Wires and BSplines is easy, for example:
import FreeCAD,Draft
points = FreeCAD.ActiveDocument.ActiveObject.Points
points.pop(0)
FreeCAD.ActiveDocument.ActiveObjects.Points = points
Draft Shape2DView
Description Draft
Shape2DView
This tool places in the document a 2D object which is a flattened view of a selected
Shape-based object. M enu location
Draft Shape 2D View
Workbenches
Draft, Arch
Default shortcut
None
See also
None
How to use
1. Select the object you want to extract a 2D view from
Options
If the selected object is an Arch SectionPlane, the 2D projection will be of the contents of the Section plane, and the
projection vector will be taken from the section plane instead of the Projection property below.
The normal operating mode is Solid, which projects the whole shape, but, if you selected some faces of the base object
when creating the 2D view, you can also set the Individual Faces mode, which will project only the faces that were
selected.
If the selected object is an Arch SectionPlane, a cutlines projection mode is also available, which projects only the
edges being cut by the section plane.
Properties
DATA Projection: The direction of the projection.
DATA Projection M ode: The mode of the projection: solid, individual faces, or cutlines.
Scripting
The Draft Shape2DView tool can by used in macros and from the python console by using the following function:
makeShape2DView (object,[projection],[facenumbers])
import FreeCAD,Draft
Draft.makeShape2DView(FreeCAD.ActiveDocument.ActiveObject)
Draft Draft2Sketch
Description Draft
Draft2Sketch
Workbenches
Draft, Arch
Default shortcut
None
See also
None
How to use
1. Select a Draft object or a Sketch
Options
If you convert a Draft Wire, point constraints will be applied to the nodes
If you convert a Draft Rectangle, point constraints will be applied to the corners, and horizontal and vertical constraints
to the edges
Non-Draft objects that are totally planar will also get converted to sketches
The sketcher does support straight lines and circular arcs. The conversion of any element that can not be represented with
those will fail.
The conversion of any element that can not be represented with either a straight line or circular curve will just fail, i.e. the item
will not appear in the sketch.
Scripting
Not available, see the Sketcher M odule documentation for how to create sketches by scripting
Draft Array
The Array tool creates an orthogonal (3-axes) or polar array from a selected object. If no M enu location
object is selected, you will be invited to select one. Draft Array
Workbenches
Draft, Arch
Default shortcut
None
See also
PathArray
How to use
1. Select an object you wish to make an array with
Options
The array starts as orthogonal by default, you can then change its mode in the properties.
Properties
DATA Array Type: Specifies the type of the array, ortho or polar
DATA Interval X: The interval between each copy on the first axis
DATA Interval Y: The interval between each copy on the second axis
DATA Interval Z: The interval between each copy on the third axis
DATA Number X: The number of copies on the first axis
DATA Number Y: The number of copies on the second axis
DATA Number Z: The number of copies on the third axis
Scripting
The Array tool can by used in macros and from the python console by using one of the following functions, depending if you
wish to obtain simple, standalone copies of your base object, or a parametric array object, that stays linked to the original
object.
Simple array
array (objectslist,xvector,yvector,xnum,ynum,[zvector,znum])
array (objectslist,center,totalangle,totalnum)
Creates an array of the objects contained in list (that can be an object or a list of objects) with, in case of rectangular
array, xnum of iterations in the x direction at xvector distance between iterations, and same for y direction with yvector
and ynum. In case of polar array, center is a vector, totalangle is the angle to cover (in degrees) and totalnum is the
number of objects, including the original.
This function produces standalone copies of the base object(s)
Parametric array
makeArray (object,xvector,yvector,xnum,ynum)
makeArray (object,center,totalangle,totalnum)
Creates an array of the given object with, in case of rectangular array, xnum of iterations in the x direction at xvector
distance between iterations, and same for y direction with yvector and ynum. In case of polar array, center is a vector,
totalangle is the angle to cover (in degrees) and totalnum is the number of objects, including the original.
The result of this function is a parametric Draft Array object.
Example:
import FreeCAD,Draft
Draft.array(FreeCAD.ActiveDocument.ActiveObject,FreeCAD.Vector(2,0,0),FreeCAD.Vector(0,2,0),2,2)
Draft Clone
This tool produces a clone (a copy that is parametrically bound to the original object) of a M enu location
selected object. If the original object changes, the clone changes too, but keeps its Draft Clone
position, rotation and scale.
Workbenches
Draft, Arch
Default shortcut
None
See also
Draft Scale
How to use
1. Select objects you wish to clone
Properties
DATA Scale: Specifies an optional scale factor for the clone
The result of the Draft Scale tool is also a clone
Scripting
The Clone tool can by used in macros and from the python console by using the following function:
clone (obj,[delta])
Example:
import Draft
Draft.clone(FreeCAD.ActiveDocument.ActiveObject)
Draft SelectPlane
The Draft module features a working plane system, that allows you to specify a custom M enu location
plane in the 3D space on which next Draft command will occur. There are several methods Draft Utilities Select
to define the working plane: Plane
How to use
1. Press the SelectPlane button. If your button doesn't look like this, see this note.
Options
To set the workplane to an existing face: select a face of an existing object in the 3D view, then press the
SelectPlane button
Pressing the VIEW button will set the working plane as the view plane, perpendicular to the camera axis and passing
through the (0,0,0) origin point.
Pressing the NONE will unset any current working plane. The next 2D operations will be view-dependent.
You can also specify an offset value, which will set your working plane at a certain distance from the plane you select.
You can hide and show the grid with the shortcut G R
Scripting
Working plane objects can easily be created and manipulated in scripts and macros. You can create your own, and use them
independently of the current Draft working plane.
Example:
import WorkingPlane
myPlane = WorkingPlane.plane()
import FreeCAD
draftPlane = FreeCAD.DraftWorkingPlane
To move or rotate the Draft working plane (see the WorkingPlane API page for available methods):
import FreeCAD
from FreeCAD import Vector
FreeCAD.DraftWorkingPlane.alignToPointAndAxis(Vector(0,0,0), Vector(1,1,1).normalize(), 17)
(note: a Draft command must have been issued to make grid adopt changes)
The working plane has a complete scripting API on its own, with convenience functions to position it and convert to/from
placements.
Draft VisGroup
This command creates a special kind of FreeCAD group, with additional features: It allows M enu location
to control visual features of the objects placed inside the group, such as line width, line Draft -> Utilities -> VisGroup
color, shape color and transparency. By changing these properties on the VisGroup, the
changes are propagated to the objects contained in the group. Workbenches
Draft, Arch
The VisGroup can also be used on Drawing pages. You can then use it to control the
color and linewidth of some Drawing Views. In that case, though, not all options are Default shortcut
available, since, at the moment, Drawing Views don't support shape color or transparency. None
See also
How to use None
The Arch workbench provides modern BIM workflow to FreeCAD, with support for features like IFC support, fully parametric
architectural entities such as walls, structural elements or windows, and rich 2D document production. The Arch workbench
also feature all the tools from the Draft Workbench.
Tools
Construction tools
Structural element: Creates a structural element from scratch or using a selected object as a base
Modification tools
Utilities
Select non-solid meshes: Selects all non-solid meshes from the current selection or frm the document
Check: Check if the selected objects are solids and don't contain defects
File formats
API
The Arch module can be used in python scripts and macros using the Arch Python API functions.
Tutorials
Arch tutorial
Arch tutorial in Yorik's blog
Arch Wall
This tool builds a Wall object from scratch or on top of any other shape-based or mesh- M enu location
based object. A wall can be built without any base object, in which case it behaves as a Arch Wall
cubic volume, using length, width and height properties. When built on top of an existing
shape, a wall can be based on: Workbenches
Arch
A linear 2D object, such as lines, wires, arcs or sketches, in which case you can
change thickness, alignment(right, left or centered) and height. The length property Default shortcut
has no effect. W A
A flat face, in which case you can only change the height. Length and width
properties have no effect. If the base face is vertical, however, the wall will use the See also
width property instead of height, allowing you to build walls from space-like objects Arch Structure
or mass studies.
A solid, in which case length, width and height properties have no effect. The wall
simply uses the underlying solid as its shape.
A mesh, in which case the underlying mesh must be a closed, non-manifold solid.
Example of walls built from a line, a wire, a face, a solid and a sketch
Walls can also have additions or subtractions. Additions are other objects whose shapes are joined in this Wall's shape, while
subtractions are subtracted. Additions and subtractions can be added with the Arch Add and Arch Remove tools. Additions
and subtractions have no influence over wall parameters such as height and width, which can still be changed. Walls can also
have their height automatic, if they are included into a higher-level object such as floors. The height must be kept at 0, then
the wall will adopt the height specified in the parent object.
When several walls should intersect, you need to place them into a floor to have their geometry intersected.
How to use
Drawing a wall from scratch
1. Select one or more base geometry objects (Draft object, sketch, etc)
Options
The height, width and alignment of a wall can be set during drawing, via the task panel
When snapping a wall to an existing wall, both walls will be joined into one. The way the two walls are joined depends on
their properties: If they have the same width, height and alignment, and if the option "join base sketches" is enabled in
the Arch preferences, the resulting wall will be one object based on a sketch made of several segments. Otherwise, the
latter wall will be added to the first one as addition.
Press X , Y or Z after the first point to constrain the second 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
second point are relative to the first one. If not, they are absolute, taken from the (0,0,0) origin point.
Press SHIFT while drawing to constrain your second point horizontally or vertically in relation to the first one.
Press ESC or the Cancel button to abort the current command.
Double-clicking on the wall in the tree view after it is created allows you to enter edit mode and access and modify its
additions and subtractions
Multi-layer walls can be easily created by building several walls from the same baseline. By setting their Align property to
either left or right, and specifying an Offset value, you can effectively construct several wall layers. Placing a window in
such a wall layer will propagate the opening to the other wall layers based on the same baseline.
Snapping
Snapping works a bit differently with Arch walls than other Arch and Draft objects. If a wall has a baseline object, snapping will
anchor to the base object, instead of the wall geometry, allowing to easily align walls by their baseline. If, however, you
specifically want to snap to the wall geometry, pressing CTRL will switch snapping to the wall object.
Properties
Wall objects inherit the properties of Part objects, and also have the following extra properties:
DATA Align: The alignment of the wall on its baseline: Left, right or center
DATA Base: The base object this wall is built on
DATA Face: The index of the face from the base object to use. If the vaue is not set or 0, the whole object is used
DATAForce Wire: If True, and the wall is based on a face, only the border wire of the face is used, resulting in a wall
bordering the face
DATA Length: The length of the wall (not used when the wall is based on an object)
DATA Width: The width of the wall (not used when the wall is based on a face)
DATA Height: The height of the wall (not used when the wall is based on a solid). If no height is given, and the wall is
inside a floor object with its height defined, the wall will automatically take the value of the floor height.
DATA Normal: An extrusion direction for the wall. If set to (0,0,0), the extrusion direction is automatic.
DATA Offset: This specifies the distance between the wall and its baseline. Works only if the Align property is set to Right
or Left.
Scripting
The Wall tool can by used in macros and from the python console by using the following function:
makeWall ( [obj],[length],[width],[height],[align],[face],[name] )
Creates a wall based on the given object, which can be a sketch, a draft object, a face or a solid. align can be
"Center","Left" or "Right". If you provide no base object, then you can use numeric values for length, width and height.
Face can be used to give the index of a face from the underlying object, to build this wall on, instead of using the whole
object.
Returns the created wall, or None if the operation failed.
Example:
This tool allows you to build structural elements such as columns or beams, by specifying M enu location
their width, length and height, or by basing them on a 2D profile. Arch Structure
Workbenches
Arch
Default shortcut
S T
See also
Arch Wall
The above image shows a column based on a 2D base profile, a column and a beam based on no profile (defined by their
height, length and width dimensions) and a metallic profile based on a 2D contour (face, wire or sketch). Additionally, a certain
number of presets available during object creation, allow you to quickly build a structural element from a predefined standard
profile.
How to use
1. Select a 2D shape (draft object, face or sketch) (optional)
Options
If no object is selected, a default 3-dimension block is created
The height, width and length of a structure can be adjusted after creation
Press ESC or the Cancel button to abort the current command.
Double-clicking on the structure in the tree view after it is created allows you to enter edit mode and access and modify
its additions and subtractions
In edit mode, it is also possible to add axes systems to the structural element. When adding one axes system, the
structural element will be copied once on each axis of the system. When adding two axes systems, the structural element
will be copied once on each intersection of the two systems.
Properties
DATA Length: The length of the structure (only used if not based on a profile)
DATA Width: The width of the structure (only used if not based on a profile)
DATA Height: The height of the structure (or the extrusion length when based on a profile). If no height is given, and the
structure is inside a floor object with its height defined, the structure will automatically take the value of the floor height.
Scripting
The Structure tool can by used in macros and from the python console by using the following function:
makeStructure ([obj],[length],[width],[height],[name])
creates a structure element based on the given profile object and the given extrusion height. If no base object is given,
you can also specify length and width for a cubic object.
Example:
import Arch
Arch.makeStructure(0.5,1,3)
Arch Rebar
The Rebar tool allows you to place reinforcing bars inside Arch Structure objects. M enu location
Rebar objects are based on 2D profiles such as sketches or draft objects, that must be Arch Rebar
drawn on a face of a structure object. You can then adjust the configuration of the rebars,
such as the number and diameter of the bars, or the offset distance between the two ends Workbenches
of the structural element. Arch
Default shortcut
R B
See also
Arch Structure
The above image shows a structural object, where two sketches are drawn, defining two bar diagrams. These two sketches are
then turned into rebar objects.
How to use
1. Create a structure element
2. Switch to the Sketcher Workbench
3. Select one face of the structural element
4. Press the New Sketch button to start a new sketch on the selected face
5. Draw the diagram of your bar
Options
The rounding value is expressed in times the diameter. If your bar has a diameter of 5mm, a rounding value of 3 will
create rounding at angles with a radius of 15mm.
Default values for new rebars can be set in the Arch preferences settings.
If a direction vector is not specified, the direction and distance along which the bars will spread is calculated
automatically from the host structural object, by taking the normal direction of the base sketch, and taking its intersection
with the structural object. If you specify a direction vector, the length of that vector will also be taken into account.
The spacing value is calculated from the current amount of bars, and represents the distance between the axes of each
bar. You must therefore subtract the bar diameter to obtain the size of the free space between bars.
Properties
DATA Amount: The amount of bars.
DATA Diameter: The diameter of the bars.
DATA Direction: The direction (and length) along which the bars must spread. If the value is (0,0,0), the direction is
calculated automatically from the host structural object.
DATA Offset Start: The offset distance between the border of the structural object and the first bar.
DATA Offset End: The offset distance between the border of the structural object and the last bar.
DATA Rounding: A rounding value to be applied to the corners of the bars, expressed in times the diameter.
DATA Spacing: The distance between the axes of each bar.
Scripting
The Rebar tool can by used in macros and from the python console by using the following function:
makeRebar (structure,sketch,[diameter],[amount],[offset])
Adds a Reinforcing Bar object to the given structural object, using the given sketch as profile.
If no diameter, amount or offset value is given, the default values from the Arch preferences settings are applied.
Returns the new Rebar object.
Example:
The Arch Floor is a special type of FreeCAD group object that has a couple of additional M enu location
properties particularly suited for building floors. Particularly, they have a height property, Arch -> Floor
that its children objects (walls and structures) can use to set their own height
automatically. They are mostly used to organize your model. Workbenches
Arch
Options
After creating a floor, you can add more objects to it by drag and dropping them in the Tree View or by using the Arch
Add tool
You can remove objects from a floor by drag and dropping them out of it the Tree View or by using the Arch Remove
tool
Properties
DATA Height: The height of the floor, to be used by its child objects
Scripting
The Floor tool can by used in macros and from the python console by using the following function:
makeFloor ([objectslist])
Example:
import Arch
Arch.makeFloor()
Arch Building
The Arch Building is a special type of FreeCAD group object particularly suited for M enu location
representing a whole building unit. They are mostly used to organize your model, by Arch -> Building
containing floor objects.
Workbenches
Arch
How to use Default shortcut
B U
1. Optionally, select one or more objects to be included in your new building
See also
2. Press the Arch Building button, or press the B then U keys
Arch Floor, Arch Site
Options
After creating a building, you can add more objects to it by drag and dropping them in the Tree View or by using the
Arch Add tool
You can remove objects from a building by drag and dropping them out of it the Tree View or by using the Arch
Remove tool
Scripting
The Building tool can by used in macros and from the python console by using the following function:
makeBuilding ([objectslist])
Example:
import Arch
Arch.makeBuilding()
Arch Site
The Arch Site is a special type of FreeCAD group object particularly suited for M enu location
representing a whole project site, or terrain. They are mostly used to organize your model, Arch Site
by containing building objects.
Workbenches
Arch
How to use Default shortcut
S I
1. Optionally, select one or more objects to be included in your new site
See also
2. Press the Arch Site button, or press the S then I keys
Arch Floor, Arch Building
Options
After creating a site, you can add more objects to it by drag and dropping them in the Tree View or by using the Arch
Add tool
You can remove objects from a site by drag and dropping them out of it the Tree View or by using the Arch Remove
tool
Scripting
The Site tool can by used in macros and from the python console by using the following function:
makeSite ([objectslist])
Example:
import Arch
Arch.makeSite()
Arch Window
The Window is a base object for all kinds of "embeddable" objects, such as windows, M enu location
doors, etc... It is designed to be either independent, or "hosted" inside another component Arch Window
such as a wall. It has its own geometry, that can be made of several components (the
window frame, for example), and also defines a volume to be subtracted to host objects, in Workbenches
order to create an opening. Arch
Windows are based on closed 2D objects, such as Draft Rectangles or Sketches, that Default shortcut
are used to define their inner components. The base 2D object can therefore contain W I
several closed wires, that can be combined to form filled panels (one wire) or frames
(several wires). If the base 2D object was drawn on a support object, and that support See also
object is a wall, then the window gets automatically included in that wall.
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
1. If you are going to draw your window directly on a wall, select one face of a wall
):
H1
H2
HEIGHT
W2 O2
H3
W1 O1 WIDTH
Glass door
H1
HEIGHT
W2 O2
W1 O1 WIDTH
Simple door
H1
H2
HEIGHT
W2 O2
W1 O1 WIDTH
Double-opening window
H1
HEIGHT
W1 O1 WIDTH
Fixed window
H1
H2
HEIGHT
W2 O2
W1 O1 WIDTH
Single-opening window
H1
H2
HEIGHT
W2 O2
W1 O1 WIDTH
Sash-opening window
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:
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])
Example:
Description Arch
SectionPlane
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 M enu location
describes the 2D view you want to obtain. The Section plane object will only consider Arch -> Section Plane
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. Workbenches
Arch
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 Default shortcut
planes directly in the document, by using the Draft Shape2DView tool with a section
S P
plane selected.
See also
None
How to use
1. Select objects you want to be included in your section 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])
Example:
The Axis tool allows you to places an axes system in the current document. The distance M enu location
and the angle between axes is customizable, as well as the numbering style. The axes Arch -> Axis
serve mainly as references to snap objects onto, but can also be used together with
structures to create parametric arrays of beams or columns. 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.
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
The Roof tool allows you to create a sloped roof from a selected wire. The created roof M enu location
object is parametric, keeping its relationship with the base object. Please note that this tool Arch -> Roof
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). 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:
The Space tool allows you to define an empty volume, either by basing it on a solid shape, M enu location
or by defining its boundaries, or a mix of both. If it is based solely on boundaries, the Arch Space
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 Workbenches
volume. The floor area of a space object, calculated by intersecting a horizontal plane at Arch
the center of mass of the space volume, can also be displayed, by setting the display
mode of the space object to "detailed". 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
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)
Example:
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())
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
The stairs tool allows you to build automatically several types of stairs. At the moment, M enu location
only straight stairs (with or without a central landing) are supported. Stairs can be built Arch Stairs
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. Workbenches
Arch
See the Stairs entry in wikipedia for a definition of the different terms used to describe
parts of stairs. 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
Steps
Structure
Scripting
Stairs can be created from python scripts and macros by using the following function:
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
This tool allows you to build all kinds of panel-like elements, typically for panel M enu location
constructions like the WikiHouse project, but also for all kinds of objects that are based Arch Panel
on a flat profile.
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)
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
The Frame tool is used to build all kinds of frame objects based on a profile and a layout. M enu location
The profile is extruded along the edges of the layout, which can be any 2D object such as Arch -> Frame
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. 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
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:
The Equipment tool offers you a simple and convenient way to insert non-structural, M enu location
standalone elements such as pieces of furniture, hidro-sanitary equipments or electrical Arch Equipment
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 Workbenches
the internet. 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
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 )
Example:
The Cut Plane tool allows you to cut an Arch object according to a plan: M enu location
Arch Cut Plane
You can cut an Arch object with the selected face, normal or opposite of the face
plan. Workbenches
Arch
This add a substraction component CutVolume to the Arch object
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)
Scripting
The CutPlane tool can by used in macros and from the python console by using the following function:
cutComponentwithPlane (archObject,face,faceSide)
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)
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:
See also
Arch Add
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)
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:
The survey tool enters a special surveying mode, which allows you to quickly grab M enu location
measures and information from a model, and transfer that information to other Arch Survey
applications. Once you are in Survey mode, clicking on different subelements of 3D
objects gathers the following information, depending on what you click: Workbenches
Arch
If you click on an edge, you get its length
Default shortcut
If you click on a vertex, you get its height (coordinate on the Z axis)
None
If you click on a face, you get its area
See also
If you double-click anything, therefore select the whole object, you get its volume
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 Part-
based 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 Jrgen, 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".
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 So 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.
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.
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.
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"
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.
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:
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:
Right! All the hard work is now done, let's go on with the very hard work!
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.
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.
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.
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.
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:
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:
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 non-
BIM 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.
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 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
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
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:
Part.show(Part.makeBox(100,100,100).cut(Part.makeCylinder(80,100)).cut(Part.makeBox(90,40,100)).cut(Part.makeBox(20,85,100)))
Shape = App.ActiveDocument.Shape.Shape
[visibleG0,visibleG1,hiddenG0,hiddenG1] = Drawing.project(Shape)
print "visible edges:", len(visibleG0.Edges)
print "hidden edges:", len(hiddenG0.Edges)
[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
import FreeCAD
import Part
import Drawing
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
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()
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)
del file
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"
>
del ViewSVG
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
The ControlFrame function returns a type containing (svg string, overall width of control frame, overall height of control frame)
import gdtsvg
ourDimension = linearDimension(point1, point2, textpoint, dimensiontext,
linestyle=getStyle("visible"),
arrowstyle=getStyle("filled"), textstyle=getStyle("text")
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.
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 Drawing
Landscape template is available. Landscape A3
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. M enu location
Drawing Insert new drawing
To open the Drawing viewer to display the page, simply double-click on the Page object, A3 Landscape
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. Workbenches
Drawing, Complete
If the page does not display, click on the refresh icon in the main toolbar, or go to Edit
Refresh menu, or shortcut CTRL+R . 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 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.
Unfold the Page object in the Project tree, and select the View. Its parameters can be edited in the Property View Data tab.
Label: changes the view's label in the Project tree. You can also click on the View in the tree and right-click 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.
To generate a drawing sheet with standard views automatically, use the Automatic drawing M acro.
Drawing Annotation
Description Drawing
Annotation
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
This command allows you to place a clipping rectangle on a Drawing page. Drawing M enu location
View objects can then be added to that clipping rectangle, and their display will be Drawing Clip
truncated by the borders of the rectangle.
Workbenches
Drawing, Complete
How to use Default shortcut
none
1. Create a Drawing page
2. Refresh the view if a Drawing view wasn't opened See also
None
3. Press the 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 Drawing
Openbrowser
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 M enu location
rendering module, which only supports a tiny subset of the full SVG specification. As a Drawing Open Browser
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, Workbenches
which is one of the best SVG renderers available, and will correctly render your page with Drawing, Complete
all its features.
Default shortcut
none
How to use
See also
1. Create a Drawing page None
Limitations
A page opened in the web browser will not refresh automatically on changes. You must use right-click -> reload manually.
Drawing Symbol
This command allows you to add the contents of a SVG image on a selected Drawing M enu location
page. These contents can then be moved and rescaled on the page. The contents of the Drawing Symbol
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 Workbenches
file. Drawing, Complete
Default shortcut
How to use none
See also
1. Create a Drawing page
None
2. Refresh the view if a Drawing viewer wasn't opened
This tool allows you to put selected objects on a svg Drawing sheet. If no sheet exists in M enu location
the document, a default one will be created. This tool works similarly to the Drawing View Drafting Drawing
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 Workbenches
the Drawing View tool cannot handle. Draft, Arch
Default shortcut
None
See also
None
How to use
1. Select the objects you wish to put on a drawing sheet
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)
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 M enu location
their PC. Drawing Export page...
Workbenches
Drawing, Complete
Default shortcut
none
See also
Drawing Open SVG
Drawing ProjectShape
Workbenches
Drawing, Complete
Default shortcut
See also
Usage
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.
Base
DATA Label :
DATA Placement :
Projection
DATA 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 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
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
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
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
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
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/
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
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:
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.
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:
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
Simulate a trajectory: Opens the simulation dialog and let you simulate
Trajectories
Tools to creat and manipulate trajectories. There are two kinds, the parametric and non parametric ones.
non parametric
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
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:
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
rob.Axis1 = 5.0
print rob.Tcp
rob.Tcp = Start
print rob.Axis1
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"))
print t.Waypoints
del rob,Start,t,l,w
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"
App.activeDocument().Robot.Axis2 = -90
App.activeDocument().Robot.Axis3 = 90
pos = FreeCAD.getDocument("Unnamed").getObject("Robot").Tcp
pos.move(App.Vector(-10,0,0))
FreeCAD.getDocument("Unnamed").getObject("Robot").Tcp = pos
App.activeDocument().addObject("Robot::TrajectoryObject","Trajectory")
t = App.activeDocument().Trajectory.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"))
Simulation
To be done.....
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
ExportCompactSub(App.activeDocument().Robot,App.activeDocument().Trajectory,'D:/Temp/TestOut.src')
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 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.
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
Convert Edges To Faces: Convert Edges to Faces. Useful to prepare imported DXF geometry for extrusion.
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
OpenSCAD
AddOpenSCADElement
Add an OpenSCAD element by entering OpenSCAD code into the task panel and
executing the OpenSCAD binary (requires OpenSCAD)
M enu location
When 'as mesh' is selected, OpenSCAD renders a Mesh.
OpenSCAD -> Add OpenSCAD
Each time Add is pressed the OpenSCAD code is executed and elements are imported. Element
If OpenSCAD returns successfully, its messages are displayed as warnings in the report Workbenches
window. This will be the case if the path to imported, included and used files is broken. In OpenSCAD
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 Default shortcut
messages will be loged as errors. Libraries should be accessible as usual, whereas None
example can be reached as stated below
See also
None
include <../examples/example001.scad>;
would include the first examples also known as the OpenSCAD icon
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.
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.
[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.
A 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.
Define/create a nodes set: Creates/defines a node set. [0.14] Not implemented yet.
Create FEM force constraint: To define a force in [N] applied uniform to a selectable face in definable direction.
Import/Export
Python scripting
Creating FEM-meshes "by hand"
m.addNode(0.0,1.0,0.0,1)
m.addVolume([1,2,3,4,5,6,7,8,9,10],1)
Visual handling
Element Types
This description is based on the MED format as described here.
Segment element
Triangle element
Quadratic element
Tetrahedron element
Pyramid element
Hexahedron element
Hexahedron with eight or twenty
nodes
Edge Node 1 Node 2 Middle node
A1 N1 N2 N9
A2 N2 N3 N10
A3 N3 N4 N11
A4 N4 N1 N12
A5 N5 N6 N13
A6 N6 N7 N14
A7 N7 N7 N15
A8 N8 N5 N16
A9 N1 N5 N17
A10 N2 N6 N18
A11 N3 N7 N19
A12 N4 N8 N20
Hexahedron faces
Face Edge 1 Edge 2 Edge 3 Edge 4
F1 A1 A2 A3 A4
F2 -A8 -A7 -A6 -A5
F3 A9 A5 -A10 -A1
F4 A10 A6 -A11 -A2
F5 A11 A7 -A12 -A3
F6 A12 A8 -A9 -A4
Pentahedron element
Example
See FEM Analysis
FEM Analysis
FEM Analysis
Workbenches
FEM
Default shortcut
A
See also
Units
Length Time Mass Force Pressure Velocity Density Energy Gravity
m s kg kg m/s2 N/m2 m/s kg/m3 kgm2/s2 9.81
m s kg N Pa m/s m kg/l J 9.81
m s g mN mPa m/s micro kg/l mJ 9.81
m s Mg (ton) kN kPa m/s kg/l kJ 9.81
m ms kg MN MPa km/s m kg/l MJ 9.81e-6
m ms g kN kPa km/s micro kg/l kJ 9.81e-6
m ms Mg (ton) GN GPa km/s kg/l GJ 9.81e-6
mm s kg mN kPa mm/s M kg/l micro J 9.81e+3
mm s g micro N Pa mm/s g/mm3 nJ 9.81e+3
mm s Mg (ton) N MPa mm/s Mg/mm3 mJ 9.81e+3
mm ms kg kN GPa m/s M kg/l J 9.81e-3
mm ms g N MPa m/s k kg/l mJ 9.81e-3
mm ms Mg (ton) MN TPa m/s G kg/l kJ 9.81e-3
cm ms g daN 10^5 Pa (bar) dam/s kg/l dJ 9.81e-4
cm ms kg 10^4 N (kdaN) 10^8 Pa (kbar) dam/s k kg/l hJ 9.81e-4
cm ms Mg (ton) 10^7 N(MdaN) 10^11 Pa (Mbar) dam/s M kg/l 10^5 J 9.81e-4
Procedure
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
Tools
These are tools availables.
Save plot: Saves the plot in several formats. You can select the output size and resolution too.
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
Plot Save
Description
Plot save tool saves the active plot at desired location. With this tool you can also select M enu location
the size and resolution of output image. Plot 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.
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.
In previous image you can see the result that we aproximately will obtain. Following this tutorial you will learn:
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.
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:
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]
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.
You can repeat the action in order to hide it. Also you can show the legend with the tool provided.
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.
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:
Since matplotlib supports LaTeX you can set all the labels or titles that you want using it. Set the following label to second
serie:
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.
With the labels tool you can set labels associated to all created axes.
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.
In previous image you can see the result that we aproximately will obtain. Following this tutorial you will learn:
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.
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.
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.
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
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.
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:
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.
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).
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.
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:
Harmonize normals
Flip normals
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:
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: . On it you
have 4 buttons: Record, stop recording, edit and play the current macro.
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...
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:
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
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)
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:
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)
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:
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)
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:
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
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:
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:
Of course this will always print the first sentence, but try replacing the second line by:
if "Lucky" in alldaltons:
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)
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
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:
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)
dir()
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.
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:
Report view
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()
box.
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.
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.
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.
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.
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.
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:
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.
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:
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!
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
L1 = Part.Line(V1,V2)
# and the second one
L2 = Part.Line(V4,V3)
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
W = Part.Wire(S1.Edges)
P = W.extrude(Base.Vector(0,0,10))
Show it all
Part.show(P)
b = Part.makeBox(100,100,100)
Part.show(b)
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.
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
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)
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:
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
Creating a Circle
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 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:
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)
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:
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)])
Bzier 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
Part.Ellipse()
Creates an ellipse with major radius 2 and minor radius 1 with the center in (0,0,0)
Part.Ellipse(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
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)
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.
box = Part.makeBox(10,10,10)
len(box.Vertexes)
> 8
Creating a Sphere
sphere = Part.makeSphere(10)
hemisphere = Part.makeSphere(10,Base.Vector(0,0,0),Base.Vector(0,0,1),-90,90,180)
Creating a Cylinder
cylinder = Part.makeCylinder(5,20)
partCylinder = Part.makeCylinder(5,20,Base.Vector(20,0,0),Base.Vector(0,0,1),180)
Creating a Cone
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))
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.
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)
or
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
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.
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
import Part
import MakeBottle
bottle = MakeBottle.makeBottle()
Part.show(bottle)
Detailed explanation
We will need,of course, the Part module, but also the FreeCAD.Base module, which contains basic FreeCAD structures like
vectors and matrixes.
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
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.
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")
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
import Mesh
After that you have access to the Mesh module and the Mesh class which facilitate the functions of the FreeCAD C++ Mesh-
Kernel.
mesh = Mesh.Mesh()
mesh = Mesh.Mesh('D:/temp/Something.stl')
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:
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.
Finally, a full example that computes the intersection between a sphere and a cylinder that intersects the sphere.
Exporting
m.write("D:/Develop/Projekte/FreeCAD/FreeCAD_0.7/Mod/Mesh/SavedMesh.py")
import SavedMesh
m2 = Mesh.Mesh(SavedMesh.faces)
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.
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 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)
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:
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:
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:
FreeCAD has an easy way to access the root node of a 3D view scenegraph:
sg = FreeCADGui.ActiveDocument.ActiveView.getSceneGraph()
print sg
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)
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.
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.
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:
Import Statement
PySide is not loaded with Python by default, it must be requested prior to using it. The following command:
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:
Yes or No Query
The next most simple interaction is to ask for a yes/no answer:
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:
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.
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
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
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).
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
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
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 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.
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.
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.
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).
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.
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
# 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
There is only one line and it causes the GUI to be displayed after the setup.
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
onCheckbox1
onCheckbox2
onRadioButton1
onRadioButton2
onPushButton1
onPopMenuAction1
onPopMenuAction2
onPopMenuDivider
onPopMenuAction3
onCancel
onOk
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.
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".
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.
# 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.
# 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.
Import Statement
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.
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.
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.
# 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
#
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.
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.
mainWin.showMaximized() # show maximised within the screen, window edges and the menu bar will
be displayed
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()'
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:
import sys
from PySide import QtGui ,QtCore
app = QtGui.qApp
mw = FreeCADGui.getMainWindow()
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.
myWidget = QtGui.QDockWidget()
mw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myWidget)
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
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:
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()
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
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)
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
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
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")
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 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)
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.
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
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()
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.
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:
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.
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.
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:
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()
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
myViewer()
#!/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()
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...
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.
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.
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")
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:
Adding a line
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()
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
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
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()
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...
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 Python function that can be registered with addEventCallback() expects a dictionary. Depending on the watched event the
dictionary can contain different 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
State -- A string 'UP' if the button was up, 'DOWN' if it was down or 'UNKNOWN' for all other cases
It is also possible to get and change the scenegraph in Python, with the 'pivy' module -- a Python binding for Coin.
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):
sg.removeChild(no)
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
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
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.
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)
# 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
import WebGui
WebGui.openBrowser("http://www.example.com")
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")
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 = []
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))
detail()
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")
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)
Cartesian coordinates
Change the value of "numberOfPoints" if you want a different number of points (precision)
import Part
from FreeCAD import Base
# 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"
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
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
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)