Professional Documents
Culture Documents
FreeCAD Manual 0 16 PDF
FreeCAD Manual 0 16 PDF
version 0.16
user manual
compiled from articles from
http://www.freecadweb.org/wiki
How to use
This document is divided into several sections: introduction, usage, scripting and development, the last
three address speci cally 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 FreeCAD wiki account to log
in. Ask on the forum or on the irc channel for wiki write permission (the wiki is write-protected to avoid
spamming) and we will create an account for you. Currently the wiki account is separate to the forum
account but we will create the wiki account with the same name as your forum account. 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 ts 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 MCAD, 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 Maya, 3ds Max, 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 eld 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
Feature list
This is an extensive, hence not complete, list of features FreeCAD implements. If you want to look into the
future see the Development roadmap for a quick overview of what's coming next. Also, the Screenshots are
a nice place to go.
Contents
1 Release notes
2 Key features
3 General features
4 In development
5 Extra Workbenches
Release notes
Release 0.11 - March 2011
Release 0.12 - December 2011
Release 0.13 - January 2013
Release 0.14 - March 2014
Release 0.15 - March 2015
Release 0.16 - Q1 2016
Key features
A full parametric model. All FreeCAD objects are natively parametric, which means their shape can be
based on properties or even depend on other objects, all changes being recalculated on demand, and
recorded by the undo/redo stack. New object types can be added easily, that can even be fully
programmed in Python
A modular architecture that allow plugins (modules) to add functionality to the core application.
Those extensions can be as complex as whole new applications programmed in C++ or as simple as
Python scripts or self-recorded macros. You have complete access from the Python built-in
interpreter, macros or external scripts to almost any part of FreeCAD, being geometry creation and
transformation, the 2D or 3D representation of that geometry (scenegraph) or even the FreeCAD
interface
Import/export to standard formats such as STEP, IGES, OBJ, STL, DXF, SVG, STL, DAE, IFC or OFF,
NASTRAN, VRML in addition to FreeCAD's native Fcstd le format. The level of compatibility between
FreeCAD and a given file format can vary, since it depends on the module that implements it.
A Robot simulation module that allows to study robot movements. The robot module already has an
extended graphical interface allowing GUI-only workflow.
A Drawing sheets module that permit to put 2D views of your 3D models on a sheet. This modules then
produces ready-to-export SVG or PDF sheets. The module is still sparse but already features a
powerful Python functionality.
A Rendering module that can export 3D objects for rendering with external renderers. Currently only
supports povray and LuxRender, but is expected to be extended to other renderers in the future.
An Architecture module that allows BIM-like work ow, with IFC compatibility. The making of the Arch
module is heavily discussed by the community here.
General features
FreeCAD is multi-platform. It runs and behaves exactly the same way on Windows Linux and Mac OSX
platforms.
FreeCAD is a full GUI application. FreeCAD has a complete Graphical User Interface based on the
famous Qt framework, with a 3D viewer based on Open Inventor, allowing fast rendering of 3D scenes
and a very accessible scene graph representation.
FreeCAD also runs as a command line application, with low memory footprint. In command line mode,
FreeCAD runs without its interface, but with all its geometry tools. It can be, for example, used as
server to produce content for other applications.
FreeCAD can be imported as a Python module, inside other applications that can run python scripts, or
in a python console. Like in console mode, the interface part of FreeCAD is unavailable, but all
geometry tools are accessible.
Workbench concept: In the FreeCAD interface, tools are grouped by workbenches. This allows to
display only the tools used to accomplish a certain task, keeping the workspace uncluttered and
responsive, and the application fast to load.
Plugin/Module framework for late loading of features/data-types. FreeCAD is divided into a core
application and modules, that are loaded only when needed. Almost all the tools and geometry types
are stored in modules. Modules behave like plugins, and can be added or removed to an existing
installation of FreeCAD.
Parametric associative document objects: All objects in a FreeCAD document can be de ned by
parameters. Those parameters can be modi ed on the y, and recomputed anytime. The relationship
between objects is also stored, so modifying one object also modifies its dependent objects.
Parametric primitive creation (box, sphere, cylinder, etc)
Graphical modication operations like translation, rotation, scaling, mirroring, offset (trivial or after
Jung/Shin/Choi) or shape conversion, in any plane of the 3D space
Boolean operations (union, difference, intersect)
Graphical creation of simple planar geometry like lines, wires, rectangles, arcs or circles in any plane
of the 3D space
Modeling with straight or revolution extrusions, sections and fillets.
Topological components like vertices, edges, wires and planes (via python scripting).
Testing and repairing tools for meshes: solid test, non-two-manifolds test, self-intersection test, hole
filling and uniform orientation.
Annotations like texts or dimensions
Undo/Redo framework: Everything is undo/redoable, with access to the undo stack, so multiple steps
can be undone at a time.
Transaction management: The undo/redo stack stores document transactions and not single actions,
allowing each tool to define exactly what must be undone or redone.
Built-in scripting framework: FreeCAD features a built-in Python interpreter, and an API that covers
almost any part of the application, the interface, the geometry and the representation of this
geometry in the 3D viewer. The interpreter can run single commands up to complex scripts, in fact
entire modules can even be programmed completely in Python.
Built-in Python console with syntax highlighting, autocomplete and class browser: Python commands
can be issued directly in FreeCAD and immediately return results, permitting scriptwriters to test
functionality on the fly, explore the contents of the modules and easily learn about FreeCAD internals.
User interaction mirroring on the console: Everything the user does in the FreeCAD interface executes
python code, which can be printed on the console and recorded in macros.
Full macro recording & editing: The python commands issued when the user manipulates the interface
can then be recorded, edited if needed, and saved to be reproduced later.
Compound (ZIP based) document save format: FreeCAD documents saved with .fcstd extension can
contain many different types of information, such as geometry, scripts or thumbnail icons. The .fcstd
file is itself a zip container, so a saved FreeCAD file has already been compressed.
Fully customizable/scriptable Graphical User Interface. The Qt-based interface of FreeCAD is entirely
accessible via the python interpreter. Aside from the simple functions that FreeCAD itself provides to
workbenches, the whole Qt framework is accessible too, allowing any operation on the GUI, such as
creating, adding, docking, modifying or removing widgets and toolbars.
Thumbnailer (Linux systems only at the moment): The FreeCAD document icons show the contents of
the file in most file manager applications such as gnome's nautilus.
A modular MSI installer allows
systems are also maintained.
In development
An Assembly module that allows to work with multiple projects, multiple shapes, multiple documents,
multiple files, multiple relationships...
A Cam Module dedicated to mechanical machining like milling, and will be able to output, display and
adjust G code. This module is currently in planning state.
Extra Workbenches
Power users have created various custom external workbenches.
Installing
Contents
1 Choose Your Operating System
2 Installing additional contents
2.1 The FreeCAD-addons repository
2.2 The pluginloader addon
2.3 Manual install
Install on
Windows
Install on
Linux/Unix
Install on
Mac
1. Restart FreeCAD. The addons installer will now be listed in menu Macro -> Macros and can be
launched by selecting it then clicking the Execute button:
Manual install
External workbenches, when they are fully programmed in python (which is the case of all of them at the
moment of writing) can always easily be installed manually, simply by downloading them (usually clicking
the **Download ZIP** button found on top of each addon page when they are hosted on github), and placing
them in your user's FreeCAD/Mod folder (or in the Macros folder if they are macros). Refer to the
instructions on each addon page for complete instructions.
Getting started
Contents
1 What's new
2 Foreword
3 Installing
4 Exploring FreeCAD
5 Navigating in the 3D space
6 First steps with FreeCAD
7 Working with the PartDesign and Sketcher workbenches
8 Working with the Draft and Arch workbenches
9 Scripting
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 nd
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 xed). 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
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 les, or see the latest news from the FreeCAD world. You can change the default workbench in the
preferences.
Select
Pan
Zoom
Rotate View
Rotate View
Alternate Method
Once in Pan
mode, press and
release left
mouse button to
Zoom, to exit
back to pan mode
press and release
right mouse
Once in Pan
mode, click and
momentary hold
left mouse button
to rotate, to exit
back to pan mode
press and release
right mouse
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.
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.
Scripting
And nally, 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.
Mouse Model
The FreeCAD mouse model consists of the commands used to visually navigate the 3D space and interact
with the objects displayed. FreeCAD supports multiple mouse model navigation styles. The default
navigation style is referred to as "CAD Navigation," and is very simple and practical, but FreeCAD also
provides alternative navigation styles, that you can choose according to your preferences.
Contents
1 Navigation
1.1 CAD Navigation (default)
1.2 Inventor Navigation
1.3 Blender Navigation
1.4 Touchpad Navigation
1.5 Gesture Navigation (v0.16)
2 Selecting objects
2.1 Simple selection
2.2 Preselection
3 Manipulating Objects
4 Hardware support
5 Mac OS X Issues
Navigation
The object handling is common to all workbenches. The following mouse gestures can be used to control the
object position and view according to which Navigation style is selected.
There are two ways to change the navigation style:
In the Preferences Editor, Display section, 3D View tab;
By right-clicking in empty space in the 3D view area, then selecting Navigation style in the contextual
menu.
Select
Pan
Zoom
Rotate View
Rotate View
Alternate Method
Once in Pan
mode, press and
release left
mouse button to
Zoom, to exit
back to pan mode
press and release
right mouse
button (rev 0.14)
Once in Pan
mode, click and
momentary hold
left mouse button
to rotate, to exit
back to pan mode
press and release
right mouse
button (rev 0.14)
Inventor Navigation
In Inventor Navigation, modeled after Open Inventor (not to be confused with Autodesk Inventor), there is no
mouse-only selection. In order to select objects, you must hold down the CTRL key.
Select
Pan
Zoom
Rotate View
ctrl +
or
Blender Navigation
In Blender Navigation, modeled after Blender, there is no mouse-only panning. In order to pan the view, you
must hold down the SHIFT key.
Select
Pan
Zoom
Rotate View
shift +
Press the left mouse
button over an object
you want to select.
Touchpad Navigation
In Touchpad Navigation, neither panning, nor zooming, nor rotating the view, are mouse-only (or touchpadonly) operations.
Select
Pan
Zoom
Rotate View
PgUp / PgDn
shift +
Press the left mouse
button over an object
you want to select.
alt +
or
shift + ctrl +
shift + ctrl +
Select
Pan
Zoom
Rotate View
Tilt View
with middle
mouse button;
the view will
center on that
point.
Alternatively, aim
the cursor at the
new point and
press H on
keyboard.
or
Tap to select.
Pinch to zoom
(i.e., drag two
fingers to each
other/apart).
Selecting objects
Simple selection
Objects can be selected by a click with the left mouse button either by clicking on the object in the 3D-view
or by selecting it in the tree view.
Preselection
There is also a Preselection mechanism that highlights objects and displays information before selection by
just hovering the mouse over the objects. If you don't like this behaviour or you have a slow machine, you
can switch preselection off in the preferences.
Manipulating Objects
FreeCAD offers manipulators that are handles that can be used to modify an object's appearance, shape, or
other parameters.
.
Obsolete
The clipping plane is a good example of an object with manipulators. A clipping plane can be activated with
the ViewClipping Plane menu. After activation the clipping plane object appears and shows seven obvious
manipulators as little boxes: One on each end of its three coordinate axes and one on the center of the
plane normal axis. There are four more that are not as obvious: The plane itself and the thin part of the
three axis objects.
Scaling
To scale the object click with the left mouse button on the box manipulators at the end of the axes
and pull them back and forth. Depending on the object the manipulators work independently or
synchronously.
Out of plane shifting
To shift the object along its normal vector, pull the long box on the center of an axis with the left
mouse button. For the clipping plane there is only one manipulator along the normal vector.
In plane shifting
To move the center of the clipping plane, click on the plane object and pull it to the desired location.
Rotation
Clicking on the thin part of the axes puts the manipulator in rotation mode.
Hardware support
FreeCAD also supports some 3D input devices.
Mac OS X Issues
Recently we got reports on the forum from Mac users that those mouse button and key combination do not
work as expected. Unfortunately, none of the developers owns a Mac, neither do the other regular
contributors. We need your help to determine which mouse buttons and key combination work so we can
update this wiki.
Document structure
A FreeCAD document contains all the objects of your scene. It can contain groups, and objects made with
any workbench. You can therefore switch between workbenches, and still work on the same document. The
document is what gets saved to disk when you save your work. You can also open several documents at the
same time in FreeCAD, and open several views of the same document.
Inside the document, the objects can be moved into groups, and have a unique name. Managing groups,
objects and object names is done mainly from the Tree view. It can also be done, of course, like everything
in FreeCAD, from the python interpreter. In the Tree view, you can create groups, move objects to groups,
delete objects or groups, by right-clicking in the tree view or on an object, rename objects by doubleclicking on their names, or possibly other operations, depending on the current workbench.
The objects inside a FreeCAD document can be of different types. Each workbench can create its own types
of objects, for example the Mesh Workbench creates mesh objects, the Part Workbench create Part objects,
the Draft Workbench also creates Part objects, etc.
If there is at least one document open in FreeCAD, there is always one and only one active document. That's
the document that appears in the current 3D view, the document you are currently working on.
Scripting
Documents can be easily created, accessed and modified from the python interpreter. For example:
FreeCAD.ActiveDocument
Will return the current (active) document
FreeCAD.ActiveDocument.Blob
Would access an object called "Blob" inside your document
FreeCADGui.ActiveDocument
Will return the view document associated to the current document
FreeCADGui.ActiveDocument.Blob
Would access the graphical representation (view) part of our Blob object
FreeCADGui.ActiveDocument.ActiveView
Will return the current view
Property editor
Contents
1 Overview
2 Property definition
3 Function
4 Example of Part object properties
4.1 Properties
4.2 View
4.3 Data
Overview
The Property Editor is one of the most important tools of FreeCAD and a main element while working with
FreeCAD. The Property Editor allows managing the properties of the objects in your document.
Generally the Property Editor is intended to deal with just one object at one time. The values shown in the
Property Editor belong to the active object of your active document (be careful of which document is really
active if you work on multiple documents). If you did not select any element (or there are no elements), the
Property Editor will be blank.
Not all the properties can be modi ed in any moment. Depending on the speci c status, some properties
will be shown as read-only.
The properties of an object are grouped in View properties and Data properties, and shown under different
tabs.
Different objects may have different properties. However, some properties are common among all objects,
for instance the position and the rotation of an object are Data properties that can be manipulated.
Property definition
A property is a piece of information like a number or a text string that is attached to a FreeCAD document or
an object in a document. Properties can be viewed and - if allowed - modified with the Property editor.
Properties play a very important part in FreeCAD, since it is from the beginning made to work with
parametric objects, which are objects defined only by their properties.
Custom scripted objects in FreeCAD can have properties of the following types:
Boolean
Float
FloatList
FloatConstraint
Angle
Distance
Integer
IntegerConstraint
Percent
Enumeration
IntegerList
String
StringList
Link
LinkList
Matrix
Vector
VectorList
Placement
PlacementLink
Color
ColorList
Material
Path
File
FileIncluded
PartShape
FilletContour
Circle
Function
The Property Editor has two tabs: the View tab and the Data tab.
The View tab provides access to the properties related to the visual display of the object
The Data tab allows modification of the physical parameters of an object.
DATA
View
Base
Bounding Box : To view the occupation, and, overall, of the object dimensions in space. Value
False, or True (Default, False).
VIEW
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 (deviation in mm =
(w+h+d)/3*valueInPercent/100, where w,h,d are sizes of bounding box).
VIEW
Display Mode :Display mode of the form, Flat lines, Shaded, Wireframe, Points
(Default, Flat lines).
VIEW
VIEW
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
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).
Visibility : Determines the visibility of the form (like the bar SPACE ). Value False, or True
(Default, True).
VIEW
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.
Axis : This option speci es 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 speci es the offset in either axes x, y, or z, and accept any number as the argument
for each field.
DATA
DATA
Label : The Label is the name given to the operation, this name can be changed at convenience.
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 speci es 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
speci ed angle, about the speci ed 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 speci es 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 speci es 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.
DATA
PS: The displayed properties can vary, depending on the tool used.
Import Export
This page gathers the different le formats that can be imported or exported from FreeCAD. Most of these
file formats are implemented by a specific module. This module doesn't need to be loaded in order to import
or export to that format, but must be loaded to display the corresponding preferences page.
Format
Description
Import Export
Module
Preferences
page
FCStd
yes
yes
Built-in
no
FCMat
yes
yes
Built-in
no
yes
yes
Built-in
no
yes
Part
yes
yes
Part
yes
yes
yes
Part
no
yes
yes
Draft
yes
yes
yes
Draft
yes
yes
yes
Draft /
Drawing
yes
yes
Draft
yes
yes
Arch
yes
yes
Arch
yes
BREP
DXF
DWG
SVG
OCA
IFC
DAE
OBJ
yes
yes
Arch / Mesh no
STL
yes
yes
Mesh
no
BMS
yes
yes
Mesh
no
AST
yes
yes
Mesh
no
OFF
yes
yes
Mesh
no
PLY
yes
yes
Mesh /
Points
no
INP
Abaqus format
yes
yes
FEM
no
POLY
Tetgen format
no
yes
FEM
no
UNV
yes
yes
FEM
no
MED
yes
yes
FEM
no
DAT
yes
yes
FEM / Draft no
BDF
yes
no
FEM
no
FRD
yes
no
FEM
no
NC
yes
yes
Path
no
GC
yes
yes
Path
no
NCC
yes
yes
Path
no
NGC
yes
yes
Path
no
CNC
yes
yes
Path
no
TAP
yes
yes
Path
no
GCODE
yes
yes
Path
no
EMN
IV
VRML
WebGL
(HTML)
yes
yes
yes
no
yes
yes
Idf
Built-in
Built-in
no
no
no
Web 3D format
no
yes
Arch
no
SCAD
yes
yes
OpenSCAD
no
CSG
yes
yes
OpenSCAD
no
ASC
yes
no
Points
no
POV
Povray format
no
yes
Raytracing
no
CSV
yes
yes
Spreadsheet no
no
yes
Built-in
no
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 following workbenches are available:
The Arch Module for working with architectural elements.
T h e Assembly Module for working with multiple shapes, multiple documents, multiple
multiple relationships...
les,
The Draft Workbench contains 2D tools and basic 2D and 3D CAD operations.
The Drawing workbench for displaying your 3D work on a 2D sheet.
The FEM Module provides Finite Element Analysis (FEA) workflow.
The Image Module for working with bitmap images.
The Inspection Module is made to give you speci c tools for examination of shapes. It is still in
development.
The Mesh Module for working with triangulated meshes.
The OpenSCAD Module for interoperability with OpenSCAD and repairing CSG model history.
The Part Module for working with CAD parts.
The Part Design Workbench for building Part shapes from sketches.
T h e Path Workbench is used to produce G-Code instructions. It is still in early stages of
development. Only v 0.16
The Plot Workbench The Plot module allows to edit and save output plots created from other
modules and tools.
The Points Module for working with point clouds.
The Raytracing Module for working with ray-tracing (rendering)
T h e Reverse Engineering Module is intended to give you speci c tools to convert
shapes/solids/meshes into parametric FreeCAD-compatible features. It is still in development.
The Robot Module for studying robot movements.
Th e Ship Workbench FreeCAD-Ship works over Ship entities, that must be created on top of
provided geometry.
The Sketcher Module for working with geometry-constrained sketches.
The Spreadsheet Workbench for creating and manipulating spreadsheet data.
The Start Center allows you to quickly jump to one of the most common workbenches.
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 Mesh Module
objects, are much more complex, and therefore permit much more advanced operations, like coherent
boolean operations, modifications history and parametric behaviour.
Contents
1 The tools
2 Primitives
3 Modifying objects
4 Other tools
5 Boolean Operations
6 Explaining the concepts
7 Scripting
8 Examples
The tools
The Part module tools are all located in the Part menu that appears when you load the Part module.
Primitives
These are tools for creating primitive objects.
Box: Draws a box by specifying its dimensions
Cone: Draws a cone by specifying its dimensions
Cylinder: Draws a cylinder by specifying its dimensions
Sphere: Draws a sphere by specifying its dimensions
Torus: Draws a torus (ring) by specifying its dimensions
CreatePrimitives: A tool to create various parametric geometric 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.
Booleans: Performs boolean operations on objects
Fuse: Fuses (unions) two objects
Common: Extracts the common (intersection) part of two objects
Cut: Cuts (subtracts) one object from another
Join features: smart booleans for walled objects (e.g., pipes) (v0.16)
Connect: Connects interiors of objects (v0.16)
Embed: Embeds a walled object into another walled object (v0.16)
Cutout: Ctretes a cutout in a wall of an object for another walled object (v0.16)
Extrude: Extrudes planar faces of an object
Fillet: Fillets (rounds) edges of an object
Revolve: Creates a solid by revolving another object (not solid) around an axis
Section: Creates a section by intersecting an object with a section plane
Cross sections...:
Chamfer: Chamfers edges of an object
Mirror: Mirrors the selected object on a given mirror plane
Ruled Surface:
Sweep: Sweeps one or more profiles along a path
Loft: Lofts from one profile to another
Offset: Creates a scaled copy of the original object.
Thickness: Assign a thickness to the faces of a shape.
Other tools
Import CAD
Export CAD
Shape from Mesh
Convert to solid
Reverse shapes
Create simple copy
Make compound
Refine shape
Check geometry
Measure
Boolean Operations
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()
Let's go through the above python example step by step:
import Part,PartGui
doc=App.newDocument()
loads the Part module and creates a new document
l=Part.Line()
l.StartPoint=(0.0,0.0,0.0)
l.EndPoint=(1.0,1.0,1.0)
Line is actually a line segment, hence the start and endpoint.
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.
A circle can be created in a similar way:
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 rst 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
Description
Part Box
The Box command from the Part Workbench inserts a parametric, rectangular cuboid,
geometric primitive into the active document. By default, the Box command will insert a
10x10x10 mm cube, positioned at the origin, with the label "cube". These parameters
may be modified after the object has been added.
Menu location
Part Box
Workbenches
Part, Complete
Default shortcut
None
See also
Part CreatePrimitives
Contents
1 Part Box
2 Description
3 How to Use
4 Options
5 Properties
6 Scripting
How to Use
Click the cube icon
7 FreeCAD - Version
Alternatively, you can select Part Primitives Cube from the menu bar.
Options
Via the Property Editor:
Length: Set the length distance for your Box object (default is 10 mm).
Width: Set the width distance for your Box object (default is 10 mm).
Height: Set the height distance for your Box object (default is 10 mm).
Placement: Speci es the orientation and position of the Box in the 3D space. See Placement. The reference
point is the left front lower corner of the box.
Label: The Label is the name given to the operation. This name can be changed at your convenience.
Properties
Base
Placement: Specifies the orientation and position of the Box in the 3D space. See Placement. The reference point
is the left front lower corner of the box.
DATA
DATA
Label: Label given to the Box object. Change to suit your needs.
DATA
DATA
DATA
Box
Scripting
The Box command can by used in macros and from the python console using the following function:
FreeCAD.ActiveDocument.addObject("Part::Box", "myBox")
FreeCAD.ActiveDocument.myBox.length = 25
FreeCAD.ActiveDocument.myBox.width = 15
FreeCAD.ActiveDocument.myBox.height = 30
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
Description
Part Cone
Menu location
Part -> Cone
Workbenches
How to use
Part, Complete
Options
Default shortcut
None
See also
Part CreatePrimitives
Contents
1 Part Cone
2 Description
3 How to use
4 Options
Cone
Radius 1 - radius of the arc or circle defining the
lower face
Radius 2 - radius of the arc or circle defining the
upper face
The image below shows a Part Cone with the parameter "Angle" set to 270 degrees and all other parameters
are at their default values.
Part Cylinder
Description
Creates a simple parametric cylinder, with position, angle, radius and
height parameters.
Part Cylinder
Menu location
Part Cylinder
How to use
Workbenches
Part, Complete
Options
The properties can later be edited in the data tab for the cylinder:
Default shortcut
None
See also
Part CreatePrimitives
Contents
1 Part Cylinder
2 Description
3 How to use
4 Options
4.1 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
Description
Creates a simple parametric sphere, with position, angle1, angle2,
angle3 and radius parameters.
Part Sphere
Menu location
Part -> Sphere
Workbenches
Part Module,Complete
Default shortcut
None
See also
Part CreatePrimitives
How to use
Contents
1 Part Sphere
2 Description
3 How to use
4 Options
4.1 Parameter
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
Radius: Radius of the sphere
Angle 1: 1nd angle to cut / define the sphere
Angle 2: 2nd angle to cut / define the sphere
Angle 3: 3rd angle to cut / define the sphere
Because it is quite dif cult 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
Description
Creates a simple parametric torus, with position, angle1, angle2, angle3,
radius1 and radius2 as parameters.
Part Torus
Menu location
Part Torus
Workbenches
Part, Complete
Default shortcut
None
See also
Part CreatePrimitives
Contents
How to use
1 Part Torus
2 Description
Option
3 How to use
4 Option
Parameter
A torus can be assimilated to a small disc that makes a circular orbit around an imaginary axe. Thus the
parametric torus is defined by the following parameters:
Radius1: Radius of the circle around which the disc circulate
Radius2: Radius of the disc defining the form of the torus
Angle1: 1st angle to cut / define the disc of the torus
Angle2: 2nd angle to cut / define the disc of the torus
Angle3: 3rd angle to define the circumference of the torus.
as well as the standard set of placement parameters. The pictures below give a visual overview of the
parameters antecedently mentioned:
Part CreatePrimitives
A tool to create various parametric geometric primitives.
Currently this tools can create a parametric
Part
CreatePrimitives
Plane
Menu location
Box
Cylinder
Workbenches
Cone
Sphere
Ellipsoid
Torus
Prism
Part
Default shortcut
None
See also
Wedge
Helix
Spiral available in version 0.14
Circle
Ellipse
Line (Edge)
Point (Vertex)
Regular Polygon available in version 0.14
Part Shapebuilder
Contents
1 Part CreatePrimitives
Part Plane
Description
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).
Part
CreatePrimitives
Menu location
Part Create Primitives
Plane
Workbenches
Part, OpenSCAD
Default shortcut
None
See also
Create Primitives
Contents
1 Part CreatePrimitives
2 Description
3 How to use
4 Option
4.1 View
4.2 Data
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 elds. In the Direction menu you
can also de ne a standard vector (X, Y or Z) normal to the plane, or click User De ned ... 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
You have the standard properties view.
Data
Base - Object placement data
Label : String name of the object, defaults to 'Plane'.
User may rename it.
DATA
DATA
DATA
Part Prism
Description
A Part Prism is available from the Create Primitives dialogue in the Part
workbench. A Part Prism is a solid de ned by a regular polygon cross
section and a height.
The Create Primitives dialogue can be accessed via the CreatePrimitives
icon
located in the Part menu or the Part toolbar, in the Part
Workbench.
Part Prism
Menu location
Part Create Primitives
Prism
Workbenches
Part, OpenSCAD
Default shortcut
Parameters
None
See also
Contents
1 Part Prism
2 Description
3 Parameters
Part Wedge
Create a parametric Wedge object. This Wedge defaults to a larger
square base and a smaller square top.
Part Wedge
Menu location
Placement: The default orientation places the base in the XZ plane and
the top outward in the Y axis direction. The default base corner is the
0,0,0 origin.
Base Face:
Part
Workbenches
X : 10 mm
Default shortcut
Z : 10 mm
None
Height:
Y : 0-10 mm
Top Face:
X : 2-8 mm
Z : 2-8 mm
See also
Part CreatePrimitives
Contents
1 Part Wedge
2 Default Size and Placement
3 Parametric Inputs
Parametric Inputs
DATA
DATA
DATA
DATA
Part Helix
Part Helix
Description
A Helix geometric primitive is available from the Create Primitives
dialogue in the Part workbench.
The Create Primitives dialogue can be accessed via the CreatePrimitives
Menu location
Part Create Primitives
Helix
Workbenches
icon
located in the Part menu or the Part toolbar, in the Part
Workbench.
Part, OpenSCAD
How to use
None
Default shortcut
See also
..
Contents
1 Part Helix
2 Description
3 How to use
3.1 Parameter
3.2 Location
4 Options
Parameter
Pitch:The pitch corresponds to the space
between two consecutive "turns" of the helix
measured along the main axis of the helix.
Height: The height corresponds to the overall
height of the helix measured along the main
axis of the helix.
Radius: The radius corresponds to the radius
of the circle built by the helix by viewing the
helix from the top / bottom.
Angle: Per default the helix is built on a
imaginary cylinder. With this option it is
possible to build the helix on a imaginay
conus. This angle corresponds to the angle of
the conus. The value must be comprised
between -90 deg and +90 deg.
4.1 Properties
Options
Properties
Once you have created the helix you have the possibility to edit its parameters.
Part Spiral
Part Spiral
Description
Menu location
Workbenches
icon
located in the Part menu or the Part toolbar, in the Part
Workbench.
Part, OpenSCAD
Default shortcut
None
See also
Create Primitives
Contents
1 Part Spiral
2 Description
Part Circle
Part Circle
Description
A Circle geometric primitive is available from the Create Primitives
dialogue in the Part workbench.
The Create Primitives dialogue can be accessed via the CreatePrimitives
icon
located in the Part menu or the Part toolbar, in the Part
Workbench.
This command will create a circular curved edge. With the default
values, the circular curved edge will be closed and therefore will be a
circle. If the properties Angle 0 or Angle 1 are changed from their default
values (0 and 360) the edge will be an open curve, an arc.
Alternatively a Part Circle can be initially de ned 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.
Menu location
Part Create Primitives
Circle
Workbenches
Part, OpenSCAD
Default shortcut
None
See also
..
Contents
1 Part Circle
Properties
2 Description
2.1 Properties
Part Ellipse
Part Ellipse
Description
Menu location
Workbenches
icon
located in the Part menu or the Part toolbar, in the Part
Workbench.
This command will create a elliptical curved edge. With the default
values, the elliptical curved edge will be closed and therefore will be an
ellipse. If the properties Angle 1 or Angle 2 are changed from their
default values (0 and 360) the edge will be an open curve.
Properties
Major radius: the major radius of the ellipse, the default value is 4
Minor 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
Part, OpenSCAD
Default shortcut
None
See also
..
Contents
1 Part Ellipse
2 Description
3 Properties
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
Menu location
Part Create Primitives
Line
Workbenches
Part, OpenSCAD
Line
Default shortcut
Parameter
Start point
End point
Location
None
See also
..
Contents
1 Part Line
2 Geometric Primitives
2.1 Parameter
2.2 Location
3 Property
3.1 View
3.2 Data
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
Description
Menu location
Geometric Primitives
See also
..
Contents
1 Part Point
Point
2 Description
Parameter
X
2.1.1
Parameter
2.1.2 Location
Z
Location
Property
View
2.1 Geometric
Primitives
2.2 Property
2.2.1 View
2.2.2 Data
View
..
Data
Base
Dati
Label:
Dati
Placement: placement
Dati
X:
Dati
Y:
Dati
Z:
Part RegularPolygon
Description
Part
RegularPolygon
Menu location
Part Create Primitives
Regular Polygon
Workbenches
Part, OpenSCAD
Parameters
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.
Default shortcut
None
See also
..
Contents
available in version 0.14
1 Part RegularPolygon
2 Description
3 Parameters
Part Booleans
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 operations, see also Part Fuse, Part
Common and Part Cut.
Part Booleans
Menu location
Part Booleans
Workbenches
Part,Complete
Default shortcut
None
See also
Part Fuse, Part Common and
Part Cut
Contents
1 Part Booleans
Part Fuse
Fuses (unions) selected Part objects into one. This operation is fully
parametric and the components can be modi ed and the result
recomputed.
This command allows you to perform quickly this Boolean operation.
How to use
Menu location
Part Fuse
Workbenches
Part Fuse
Supported inputs
Input objects must be OpenCascade shapes. Examples: stuff made with
Part, PartDesign, Sketcher workbenches. Not meshes (unless those were
converted to shapes) - for meshes, there are speci c Boolean tools in
MeshDesign workbench.
Solid + Solid: the result if a solid that occupies all the volume
covered by inputs
Shell + Shell, Shell + Face, Face + Face: the result is a shell. Where
faces intersect, they are split. Shells can be non-manifold. After
fusion, faces can be united by Refining the result.
Part, Complete
Default shortcut
None
See also
Part Cut, Part Common
Contents
1 Part Fuse
2 How to use
3 Supported inputs
4 Options
Wire + Wire, Edge + Wire, Edge + Edge: the result is a wire. Edges
are split where they intersect.
Compounds are supported; however, it is assumend that shapes packed into a compound do not touch or
intersect. If they actually do, Fusion will likely fail, or produce incorrect result.
Options
Items can be added and removed from the Fuse, by dragging them in or out of the Fuse feature in the
treeview, with the mouse. A manual recompute (press F5 key or click on the recompute icon) is required to
see the results.
After this operation may be necessary to clean the shape with RefineShape
Part Extrude
Description
Part Extrude
Menu location
Part Extrude
Workbenches
Part, Complete
Default shortcut
None
See also
Contents
1 Part Extrude
2 Description
3 How to use
4 Parameters
How to use
1. Select the shape(s) in the 3D view or in the Model tree
2. Click on the
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 de ned 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 de ned by a speci ed distance in each of the
X, Y and Z axis.
Solid (true or false): toggles between a surface or a solid where not otherwise de ned 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
Menu location
Part Fillet
Usage
Start the tool from the Part toolbar or from the menu. You can
either select the object before or after starting the tool.
If the shape was not selected prior to starting the tool, select it in
the Shape drop down list in the TaskPanel.
Select the
radius.
Workbenches
Part, Complete
Default shortcut
None
See also
Part Chamfer
Contents
1 Part Fillet
1.1 Description
1.2 Usage
2 Part Fillet VS. PartDesign
Fillet
3 Notes on application of Part
Fillet
Part Revolve
Revolves the selected object around a given axis. The following shape
types are allowed, and lead to the listed output shapes (See Notes for
exceptions):
Edge
Face
Shell
Solid
Compound solid
Part Revolve
Menu location
Part Revolve
Workbenches
Part, Complete
Default shortcut
None
See also
Contents
1 Part Revolve
2 Notes
The Angle argument speci es 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 de ned axis, the numbers de ne 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.
If Revolve is performed using an axis that intersects the face to rotate, and you want to create a solid,
the result might be invalid. This can happen for various reasons, self-intersection, direction, etc.
Part SectionCross
Part SectionCross
Menu location
Part SectionCross
Workbenches
Part,Complete
Default shortcut
None
See also
Contents
1 Part SectionCross
Part Chamfer
Description
Chamfers the selected edge(s) of an object. A dialog allows you to choose
which edge(s) to work on as well as modify various chamfer parameters.
Part Chamfer
Menu location
Part Chamfer
Workbenches
Part, Complete
Default shortcut
None
See also
Contents
1 Part Chamfer
2 Description
3 How to Use
4 Options
How to Use
5 Properties
6 Scripting
1. Press the
button from the Part Workbench. Alternatively, you can
select Part Chamfer.
2. Select the shape to chamfer from the dialog.
3. Select edges to chamfer by checking the corresponding box in the chamfer dialog or by selecting them on
the model directly.
4. Edit chamfer parameters.
5. Press OK to close the chamfer dialog and apply the chamfer.
Options
When selecting edges on the model, you have the option to select by edge or by face. Selecting by face will
select all bordering edges of that face.
Constant length chamfer or variable length chamfer.
A constant length chamfer will create a chamfer with edges equidistant to the original edge at the
distance specified.
A variable length chamfer will have edges that may be set to different distances from the original
edge, allowing you to create a chamfer at a variable angle.
Properties
Base
DATA
DATA
Placement: Specifies the orientation and position of the shape in the 3D space.
DATA
Scripting
The Chamfer tool can by used in macros and from the python console by adding a Chamfer object to the
document.
Example Script:
import Part
cube = FreeCAD.ActiveDocument.addObject("Part::Feature", "myCube")
cube.Shape = Part.makeBox(5, 5, 5)
chmfr = FreeCAD.ActiveDocument.addObject("Part::Chamfer", "myChamfer")
chmfr.Base = FreeCAD.ActiveDocument.myCube
myEdges = []
myEdges.append((1, 1.5, 1.25)) # (edge number, chamfer start length, chamfer end length)
myEdges.append((2, 1.5, 1.25))
myEdges.append((3, 1.5, 1.25))
myEdges.append((4, 1.5, 1.25))
myEdges.append((5, 1.5, 1.25))
myEdges.append((6, 1.5, 1.25))
myEdges.append((7, 1.5, 1.25))
myEdges.append((8, 1.5, 1.25))
myEdges.append((9, 1.5, 1.25))
myEdges.append((10, 1.5, 1.25))
myEdges.append((11, 1.5, 1.25))
myEdges.append((12, 1.5, 1.25))
chmfr.Edges = myEdges
FreeCADGui.ActiveDocument.myCube.Visibility = False
import Part
cube = FreeCAD.ActiveDocument.addObject("Part::Feature", "myCube")
cube.Shape = Part.makeBox(5, 5, 5)
Creates a 5 mm cube for us to apply chamfered edges to. See Part_API for an explanation of the makeBox
method.
Adds a new object to the document of type Chamfer (from the Part module) with label "myChamfer".
chmfr.Base = FreeCAD.ActiveDocument.myCube
Specifies that the base shape of the chamfer object should be "myCube".
myEdges = []
myEdges.append((1,
myEdges.append((2,
myEdges.append((3,
myEdges.append((4,
myEdges.append((5,
myEdges.append((6,
myEdges.append((7,
myEdges.append((8,
myEdges.append((9,
1.5,
1.5,
1.5,
1.5,
1.5,
1.5,
1.5,
1.5,
1.5,
Creates an empty array "myEdges" and then appends the array with each edge's chamfer parameters.
Syntax for each item should be (edge#, chamfer start length, chamfer end length)
chmfr.Edges = myEdges
Sets the Edges attribute of our Chamfer object equal to the array we just created.
FreeCADGui.ActiveDocument.myCube.Visibility = False
This line simply hides "myCube" so that our newly created "myChamfer" object is the only one visible.
Part Mirror
Introduction
'Mirror Object' - This tool creates a new object (image) which is a
re ection of the original object (source). The image object is created
behind a mirror plane. The mirror plane may be standard plane (XY, YZ,
or XZ), or any plane parallel to a standard plane.
An example:
Part Mirror
Menu location
Part -> Mirror
Workbenches
Part, Complete
Default shortcut
None
See also
Contents
1 Part Mirror
2 Introduction
3 Usage
Before
4 Options
5 Limitations
Usage
Select the source object from the list. Select a standard Mirror 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.
XY
X, Y
XZ
XZ
X, Z
YZ
YZ
Y, Z
Effect
Move mirror plane along Z axis.
No effect.
Move mirror plane along Y axis.
No effect.
Move mirror plane along X axis.
No effect.
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
Menu location
Part RuledSurface
Workbenches
Part, Complete
Default shortcut
None
See also
Contents
1 Part RuledSurface
2 Description
3 How to use
How to use
Part Sweep
This documentation is not finished. Please help and contribute
documentation.
See Draft ShapeString for good documented Command. Gui
Command gives an overview over commands. And see List of
Commands for other commands.
Go to Help FreeCAD to contribute.
Overview
Part Sweep
The FreeCAD Part Sweep tool (Part Workbench), is used to create a face,
shell or a solid shape from one or more profiles, projected along a path.
Menu location
The Part Sweep tool is similar to Part Loft with the addition of a path to
define the projection between profiles.
Workbenches
The pro les can be a point (vertex), line (Edge), wire or face. Edges and
wires may be either open or closed. There are various prole limitations
and complications, see below, however the pro les may come from the
Part Workbench primitives, Draft Workbench features and a Sketch.
The path can be a line (Edge) or series of connecting lines, wire or
various Part 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.
Part Sweep...
Part
Default shortcut
None
See also
Part Loft
Contents
1 Part Sweep
2 Overview
3 Properties
3.1 Solid
3.2 Frenet
3.3 Transition
4 Profile limitations and
complications
5 FreeCAD - Version
6 Links
Properties
Solid
If "Solid" is "true" FreeCAD creates a solid if the pro les 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 pro le orientation changes as it follows along the sweep path. If
"Frenet" is "false", the orientation of the pro le is kept consistent from point to point. The resulting shape
has the minimum possible twisting. Unintuitively, when a pro le is swept along a helix, this results in the
orientation of the pro le slowly creep (rotate) as it follows the helix. Setting "Frenet" to true prevents such
a creep.
If "Frenet" is "true" the orientation of the pro le is computed basing on local curvature and tangency
vectors of the path. This keeps the orientation of the pro le 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 de ne 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
Links
Since Sweep is often used to create threads for screws you should see Thread for Screw Tutorial
Part Loft
This documentation is not finished. Please help and contribute
documentation.
See Draft ShapeString for good documented Command. Gui
Command gives an overview over commands. And see List of
Commands for other commands.
Go to Help FreeCAD to contribute.
Part Loft
Overview
The FreeCAD Loft tool (Part Workbench), is used to create a face, shell or
a solid shape from two or more pro les. The pro les can be a point
(vertex), line (Edge), wire or face. Edges and wires may be either open or
closed. There are various limitations and complications, see below,
however the pro les may come from the Part Workbench primitives,
Draft Workbench features and a Sketch.
The Loft has three parameters, "Ruled","Solid" and "Closed" each with a
value of either "true" or "false".
If "Ruled" is "true" FreeCAD creates a face, faces or a solid from ruled
surfaces. Ruled surface page on Wikipedia.
If "Solid" is "true" FreeCAD creates a solid if the pro les 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 pro le to the rst
profile to create a closed figure.
For more info on how the pro les are joined together, refer Part Loft
Technical Details page.
Menu location
Part Loft...
Workbenches
Part
Default shortcut
None
See also
Part Sweep
Contents
1 Part Loft
2 Overview
3 Limitations and
complications
4 An example Loft
4.1 Selection of the
elements
4.2 Command
complete
5 Result
6 FreeCAD Version
Part_Loft. From three pro les which are two Part_Circles and one Part_Ellipse. Parameters are Solid "True"
and Ruled "True"
For example
FreeCAD can not Loft between one Part Circle and one default Part Line.
Draft Workbench features
Draft Workbench features can be directly used as a profile in FreeCAD 0.14 or later.
For example the following Draft features can be used as profiles in a Part Loft
Draft Polygon.
Draft Point, Line, wire,
Draft B-spline, Bezier Curve
Draft Circle, Ellipse, Rectangle
PartDesign Sketches
The pro le may be created with a sketch. However only a valid sketch will be shown in the list
to be available for selection.
The sketch must contain only one open or closed wire or line (can be multiple lines, if those
lines are all connected as they are then a single wire)
Part Workbench
the pro le can be a valid Part geometric primitive which can be created with the Part
CreatePrimitives tool
For example the following Part geometric primitives can be a valid profile
Point (Vertex), Line (Edge)
Helix, Spiral
Circle, Ellipse
Regular Polygon
Plane (Face)
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 pro les 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".
Thereafter, with the blue arrow that item is added to the list of "free form".
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 eld properties tab data created the free-form surface of the switch "Solid" by pop be set to
"true" / set properly.
The procedure is analogous open polylines.
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
This documentation is not finished. Please help and contribute
documentation.
See Draft ShapeString for good documented Command. Gui
Command gives an overview over commands. And see List of
Commands for other commands.
Go to Help FreeCAD to contribute.
Part Offset
Description
The Part Offset tool creates copies of a selected shape at a certain
distance from the base shape.
How to use
ToDo
Example
Menu location
Part Offset
Workbenches
Part, Complet
Default shortcut
None
See also
Thickness
Contents
1 Part Offset
2 Description
3 How to use
4 Example
Part Thickness
Part Thickness
Description
Menu location
Part Thickness
Use
Default shortcut
Workbenches
Part, Complete
None
1. Create a solid
2. Select one or more faces
3. Click on the
Options
See also
Offset
Contents
1 Part Thickness
2 Description
3 Use
4 Options
5 Limitations
6 Links
7 Examples
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
Description
Cleans unnecessary lines. After a Boolean operation some lines de ning
the previous form remain visible, this tool creates a copy of the totally
cleaned.
Menu location
Part Refine Shape
Workbenches
Part, OpenSCAD
Default shortcut
None
See also
Contents
1 Part RefineShape
2 Description
3 Use
4 Limitations
5 Scripting
Use
6 Notes
Limitations
The re nement algorithm only works on shells. Therefore it iterates over the shells of the input shape
and then for each shell it creates a new shell with joined faces wherever possible. This means if your
input shape is only a face, wire, edge or vertex then the algorithm does nothing.
Opposed to RefineShapeFeature in OpenSCAD workbench, this feature won't update when the
underlying shapes are changed
Scripting
The Phyton command for refining a shape is the following:
shape.removeSplitter()
Notes
the function does not modify the existing shape, but returns a new shape
the function is normally used as last step in the modelling history
the function can help to get difficult fillets to work
the function is intended to stop 3D printers from printing unwanted edges
Part CheckGeometry
Introduction
The check geometry tool allows you to verify if you have a valid solid
Part
CheckGeometry
Usage
Menu location
If you want to enable the extra BOP checks then go to the Tools menu ...
edit parameters...then navigate as per this screen shot below
Workbenches
Part
Default shortcut
None
See also
Contents
1 Part CheckGeometry
2 Introduction
3 Usage
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.
Contents
1 Basic Workflow
2 The Tools
2.1 The Sketcher Tools
2.1.1 Sketcher Geometries
2.1.2 Sketcher Constraints
2.1.3 Other
2.2 The Part Design Tools
2.2.1 Construction tools
2.2.2 Modification tools
2.2.3 Transformation tools
2.2.4 Extras
3 Feature properties
3.1 Properties
3.2 View
3.3 Data
4 Tutorials
Basic Workflow
The sketch is the building block for creating and editing solid parts. The work ow can be summarized by
this: a sketch containing 2D geometry is created rst, then a solid creation tool is used on the sketch. At the
moment the available tools are:
Pad which extrudes a sketch
Pocket which creates a pocket on an existing solid
Revolution which creates a solid by revolving a sketch along an axis
Groove which creates a groove in an existing solid
More tools are planned in future releases.
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 a planar 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 modi ed with chamfers and
mirrored or patterned.
The PartDesign Workbench is meant to create a single, connected solid. Multiple solids will be possible with
the Assembly workbench.
As we create a model in the Part Design Workbench, each feature takes the shape of the last one and adds
or removes something, creating linear dependencies from feature to feature as the model is created. Hence
a "Cut" feature is not only the cut hole itself, but the whole part with the cut. As a new feature is added to
the model, FreeCAD turns off visibility of the old features. The user usually should only have the newest item
(feature) in the model tree visible, because otherwise the other phases of the model overlay each other, and
holes are filled in by the earlier model features that didn't yet have those holes.
To toggle visibility of an object on or off, select it in the hierarchy tree and press the Spacebar. Usually
everything but the last item in the hierarchy tree should be greyed out and therefore not visible in the 3D
view.
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.
Fillet: Makes a llet 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.
External Geometry: Creates an edge linked to external geometry.
Construction Mode: 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.
This is the icon that was used through v0.15. Until FreeCAD v0.16 the user had to rst create regular
(white) geometry in Sketcher and then use this tool to change it to Construction Geometry (blue).
Construction Mode: In FreeCAD v0.16 the ability to create geometry directly in Construction Mode
was added, and so the icon was changed to this one. Selecting existing Sketcher geometry and then
clicking this tool toggles that geometry between regular and construction mode just as in previous
FreeCAD versions. Starting with FreeCAD v0.16, selecting this tool when no Sketcher geometry is
selected changes the mode (regular vs. construction) in which future objects will be created.
Sketcher Constraints
Constraints are used to de ne lengths, set rules between sketch elements, and to lock the sketch along the
vertical and horizontal axes.
Not associated with numeric data
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.
Parallel: Constrains two or more lines parallel to one another.
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 rst two selected
Toggle Constraint: Toggles the toolbar or the selected constraints to/from reference mode. v0.16
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.
Edit sketch: Edit the selected Sketch.
Leave sketch: Leave the Sketch editing mode.
View sketch: Sets the model view perpendicular to the sketch plane.
Map sketch to face: Maps a sketch to the previously selected face of a solid.
Reorient sketch : Allows you to change the position of a sketch
Validate sketch: It allows you to check if there are in the tolerance of different points and to match
them.
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
Involute gear: allows you to create gear
Feature properties
Properties
There are two types of feature properties, accessible through tabs at the bottom of the Property editor:
VIEW
DATA
View
Base
Bounding Box : To view the occupation, and, overall, of the object dimensions in space. Value
False, or True (Default, False).
VIEW
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 (deviation in mm =
(w+h+d)/3*valueInPercent/100, where w,h,d are sizes of bounding box).
VIEW
Display Mode :Display mode of the form, Flat lines, Shaded, Wireframe, Points
(Default, Flat lines).
VIEW
VIEW
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
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).
Visibility : Determines the visibility of the form (like the bar SPACE ). Value False, or True
(Default, True).
VIEW
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.
Axis : This option speci es 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 speci es the offset in either axes x, y, or z, and accept any number as the argument
for each field.
DATA
DATA
Label : The Label is the name given to the operation, this name can be changed at convenience.
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 speci es 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
DATA
speci ed angle, about the speci ed 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.
Axis : This option speci es 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 speci es 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.
DATA
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:
PartDesign Bearingholder Tutorial I
PartDesign Bearingholder Tutorial II
PartDesign tutorial
Basic Part Design Tutorial
Sketcher tutorial
PartDesign Pad
Description
The Pad tool takes a selected sketch as its input and from it produces a
"pad" feature. A pad is essentially an extrusion of a sketch into a solid.
For example, if a sketch were made of two concentric circles, and the
pad tool were subsequently used on this sketch, the result would be a
cylinder:
PartDesign Pad
Menu location
PartDesign Pad
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign Pad
2 Description
3 How to use
4 Options
4.1 Type
4.1.1
Dimension
4.1.2 Two
dimensions
4.1.3 To last
4.1.4 To first
4.1.5 Up to
face
4.2 Length
4.3 Symmetric to
plane
4.4 Reversed
5 Limitations
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.
2. Press the
Pad button.
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 de ning
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 rst 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
De nes 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
Reverses the direction of the pad.
Limitations
Like all Part Design features, Pad creates a solid, thus the sketch must include a closed pro le or it
will fail. There can be multiple enclosed pro les 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 x this
manually in the Part workbench with Rene shape (which creates an unlinked, non-parametric solid)
or with the "Re ne shape feature" (which creates a parametric feature) from the OpenSCAD
Workbench.
PartDesign Pocket
Introduction
'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 subtracts from the geometry it
protrudes into. For example, if a sketch were made simply 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:
PartDesign
Pocket
Menu location
PartDesign Pocket
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign Pocket
2 Introduction
3 How to use
4 Options
4.1 Dimension
4.2 To first
4.3 Through all
4.4 Up to face
5 Limitations
6 Useful links
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.
2. Press the
Pocket button.
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
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:
PartDesign
Revolution
Menu location
PartDesign Revolution
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign Revolution
2 Introduction
3 Options
3.1 Axis
3.2 Angle
3.3 Symmetric to
plane
3.4 Reversed
4 Examples
5 Useful links
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
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.
PartDesign
Groove
Menu location
PartDesign Groove
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign Groove
2 Introduction
3 Options
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
Description
The tools Point create a point in the current sheet of "Sketcher".
Sketcher Point
Menu location
Sketch Sketcher
geometries Create point
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
None
Contents
1 Sketcher Point
2 Description
3 Use
Use
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 shown in real time.
Menu location
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
function.
Contents
1 Sketcher Line
1.1 Description
1.2 Usage
Sketcher Arc
Description
This tool draws an arc by picking three points: the center, the start angle
along the radius, and the end angle.
When starting the tool, the mouse pointer changes to a white cross with
a red arc icon. The coordinates of the pointer are shown beside it in blue
in real time.
Sketcher Arc
Menu location
Sketch Sketcher
geometries Create arc
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Circle
Contents
1 Sketcher Arc
1.1 Description
1.2 Usage
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
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. Besides are coordinates shown in real
time.
Sketcher Circle
Menu location
Sketch Sketcher
geometries Create circle
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Arc
Contents
1 Sketcher Circle
1.1 Description
1.2 Usage
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
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.
Sketcher
CreateEllipse
Menu 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
Contents
1 Sketcher CreateEllipse
1.1 Description
1.2 Usage
1.3 Peculiarities
1.4 Version
Sketcher
CreateArcOfEllipse
Menu location
Sketch Sketcher
geometries Create an arc
of ellipse
Workbenches
Sketcher, Part Design
Default shortcut
None
See also
Sketcher Ellipse, Sketcher
Arc
Contents
1 Sketcher CreateArcOfEllipse
1.1 Description
1.2 Usage
1.3 Peculiarities
1.4 Version
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 rst 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
Introduced in FreeCAD v0.15.4309
Sketcher Polyline
Description
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 real time.
Sketcher
CreatePolyline
Menu location
Sketch Sketcher
geometries Create
polyline
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Usage
Sketcher Line
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.
Contents
1 Sketcher CreatePolyline
1.1 Description
1.2 Usage
Sketcher Rectangle
Description
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.
Sketcher
CreateRectangle
Menu 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
rst corner, then move the mouse and click a second time to set
the opposite corner.
Pressing ESC
function.
Contents
1 Sketcher CreateRectangle
1.1 Description
1.2 Usage
Sketcher Triangle
Description
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.
Sketcher
CreateTriangle
Menu location
Sketch Sketcher
geometries Create
equilateral triangle
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreateTriangle
1.1 Description
Usage
1.2 Usage
Press the
Sketcher Square
Description
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.
Sketcher
CreateSquare
Menu location
Sketch Sketcher
geometries Create square
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreateSquare
1.1 Description
1.2 Usage
Usage
After pressing the
Create square button, click once to set the center, then 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
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.
Sketcher
CreatePentagon
Menu location
Sketch Sketcher
geometries Create
pentagon
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreatePentagon
1.1 Description
1.2 Usage
Usage
Sketcher Hexagon
Description
Draws an hexagon 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.
Sketcher
CreateHexagon
Menu location
Sketch Sketcher
geometries Create
hexagon
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreateHexagon
1.1 Description
Usage
1.2 Usage
Sketcher Heptagon
Description
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.
Sketcher
CreateHeptagon
Menu location
Sketch Sketcher
geometries Create
heptagon
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreateHeptagon
1.1 Description
1.2 Usage
Usage
Sketcher Octagon
Description
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.
Sketcher
CreateOctagon
Menu location
Sketch Sketcher
geometries Create
octagon
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreateOctagon
1.1 Description
1.2 Usage
Usage
After pressing the
Create octagon button, click once to set the center, then 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
Description
Draws a slot by selecting the center of one semicircle and an endpoint
of the other 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.
Sketcher
CreateSlot
Menu location
Sketch Sketcher
geometries Create slot
Workbenches
Sketcher, PartDesign
Default shortcut
See also
Contents
1 Sketcher CreateSlot
2 Description
3 Usage
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 llet between two lines joined at one point. Activate
the tool, then select both lines or click on the corner point.
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.
Menu location
Sketch Sketcher
geometries Create fillet
Workbenches
Sketcher, PartDesign
Default shortcut
F
See also
None
Contents
Usage
Pick a vertex connecting two lines; or click on two connected
lines, the distance you click from the vertex will set the llet
radius.
Pressing ESC or clicking the right mouse button cancels or
terminates the function.
1 Sketcher CreateFillet
1.1 Description
1.2 Usage
Sketcher Trimming
Description
Sketcher
Trimming
Menu location
Sketch Sketcher
geometries Trim edge
Workbenches
Sketcher, PartDesign
Default shortcut
T
See also
None
Contents
1 Sketcher Trimming
1.1 Description
1.2 Use
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
"Create a coincident constraint on the selected item"
Description
This constraint tool takes two points as its argument and serves to make
the two points coincident. (Meaning to make them as-one-point). In
practical terms this constraint tool is useful when there is a break in a
pro le for example - where two lines end near each other and need to
be joined - a coincident constraint on their end-points will close the gap.
Usage
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 example, you attempt to select the start and
end point of the same line).
2. Highlighting of a drawing item is achieved by moving the mouse
over the item and clicking the left-mouse-button.
Constraint
PointOnPoint
Menu location
Sketch Sketcher
constraints Constrain
coincident
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Lock, Constraint
Point onto Object
Contents
1 Constraint PointOnPoint
1.1 Description
1.2 Usage
Constraint Vertical
Description
Creates a vertical constraint to the selected lines or polylines elements.
More than one object can be selected.
Usage
See Constraint Horizontal
Constraint
Vertical
Menu location
Sketch Sketcher
constraints Constrain
vertically
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Horizontal
Contents
1 Constraint Vertical
1.1 Description
1.2 Usage
Constraint Horizontal
Description
The Horizontal Constraint forces a selected line or lines in the image to
be parallel to the horizontal axis of the sketch.
Operation
Constraint
Horizontal
Menu location
Sketch Sketcher
constraints Constrain
horizontally
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Vertical
Contents
1 Constraint Horizontal
1.1 Description
1.2 Operation
and then applying the constraint as described above, they are constrained to be parallel to the sketch
horizontal axis.
Constraint Parallel
Description
The Constrain Parallel constraint forces two selected straight lines or
edges to be parallel to each other.
Operation
The sketch contains two randomly oriented lines.
Constraint
Parallel
Menu location
Sketch Sketcher
constraints Constrain
parallel
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Vertical,
Constraint Horizontal
Contents
1 Constraint Parallel
1.1 Description
1.2 Operation
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
Perpendicular Constraint makes two lines to be perpendicular to each other, or two
curves to be perpendicular at their intersection. Lines are treated in nite, and arcs are
treated as full circles/ellipses. The constraint is also capable of connecting two curves,
forcing them perpendicular at the joint, similarly to Tangent Constraint.
How to use
There are four different ways the constraint can be applied:
1. between two curves (available not for all curves)
2. between two endpoints of a curve
3. between a curve and an endpoint of another curve
4. between two curves at user-defined point
To apply perpendicular constraint, one should the follow the steps:
Select two or three entities in the sketch.
Invoke the constraint by clicking its icon on the toolbar, or selecting the menu
item, or using keyboard shortcut.
Constraint
Perpendicular
Menu location
Sketch Sketcher
constraints Constrain
perpendicular
Workbenches
Sketcher, PartDesign
Default shortcut
N
See also
Constraint Angle
Contents
1 Constraint Perpendicular
2 Description
3 How to use
3.1 Between two
curves (direct
perpendicularity)
3.2 Between two
endpoints (point-topoint
perpendicularity)
3.3 Between curve
and endpoint (pointto-curve
perpendicularity)
3.4 Between two
curves at point
(perpendicular-viapoint) (v0.15)
4 Scripting
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:
line + line, circle, arc
circle, arc + circle, arc
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 ne 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).
In this mode, the endpoints are made coincident, and the joint is made to be right angle. This mode is applied when two
endpoints of two curves were selected.
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 line/curve + any line/curve + any point
"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:
Sketch is a sketch object
icurve1, icurve2 are two integers identifying the curves to be made perpendicular. The integers are indexes
in the sketch (the value, returned by Sketch.addGeometry).
pointpos1, pointpos2 should be 1 for start point and 2 for end point.
geoidpoint and pointpos in PerpendicularViaPoint are the indexes specifying the point of perpendicularity.
Constraint Tangent
Description
Tangent Constraint makes two curves to touch each other (be tangent). Lines are
treated in nite, and arcs are treated as full circles/ellipses. The constraint is also
capable of connecting two curves, forcing them tangent at the joint, thus making the
joint smooth.
Constraint
Tangent
Menu location
How to use
Sketch Sketcher
constraints Constrain
tangent
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint point on object
Contents
1 Constraint Tangent
2 Description
3 How to use
3.1 Between two
curves (direct
tangency)
3.2 Between two
endpoints (point-topoint tangency)
3.3 Between curve
and endpoint (pointto-curve tangency)
3.4 Between two
curves at point
(tangent-via-point)
(v0.15)
4 Scripting
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:
line + line, circle, arc, ellipse, arc-of-ellipse
circle, arc + circle, arc
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.
In this mode, the endpoints are made coincident, and the joint is made tangent (C1-smooth, or "sharp", depending on
the placement of curves before the constraint is applied). This mode is applied when two endpoints of two curves were
selected.
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 line/curve + any line/curve + any point
"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 more 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))
# tangent-via-point (plain constraint, helpers are not added automatically)
Sketch.addConstraint(Sketcher.Constraint('TangentViaPoint',icurve1,icurve2,geoidpoint,pointpos))
where:
Sketch is a sketch object
icurve1, icurve2 are two integers identifying the curves to be made tangent. The integers are indexes in
the sketch (the value, returned by Sketch.addGeometry).
pointpos1, pointpos2 should be 1 for start point and 2 for end point.
geoidpoint and pointpos in TangentViaPoint are the indexes specifying the point of tangency.
Constraint EqualLength
Description
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 segments
and arcs).
Operation
The example sketch below contains a number of sketch primitives (
line,poly-line, rectangle, arc and circle).
Constraint
EqualLength
Menu location
Sketch Sketcher
constraints Constrain
equal
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Radius
Contents
1 Constraint EqualLength
Select two or more line segments (e.g. line and one side of the
rectangle).
1.1 Description
1.2 Operation
constraint as before.
Now select the line segment, all segments of the poly-line and one of the remaining unconstrained sides of
the rectangle
constraint as before.
Constraint Symmetric
Description
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 constrain
two points to be symmetric with respect to a third one.
Operation
Constraint
Symmetric
Menu location
Sketch Sketcher
constraints Constrain
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.
Contents
1 Constraint Symmetric
1.1 Description
1.2 Operation
Constraint Lock
Create a lock constraint on the selected item
Description
This constraint tool attempts to fully constrain any selected item.
NOTE: It is advised that this tool be exclusively used on points for the
time-being:
Owing to the fact that FreeCAD is still under development - this tool
exhibits strange behaviour when it attempts to 'lock' anything other
than a point. For example (as of V0.12 R4802), when locking a circle by
its circumferential line rather than its centre point, a horizontal
constraint and a vertical constraint appear in the constraints dialogue,
but they are both of value zero and do not appear in the graphics
window.
Operation
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.
Sketcher
ConstrainLock
Menu location
Sketch Sketcher
constraints Constrain lock
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Coincident
Contents
1 Sketcher ConstrainLock
2 Description
3 Operation
2. Highlighting of a drawing item is achieved by moving the mouse over the item and clicking the leftmouse-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 inplace. 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.
7. The vertical constraint may be similarly edited to constrain the point to the desired location.
Constraint HorizontalDistance
Description
Fixes the horizontal distance between 2 points or line ends. If only one
item is selected, the distance is set to the origin.
Constraint
HorizontalDistance
Menu location
Sketch Sketcher
constraints Constrain
horizontal distance
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Length, Constraint
VerticalDistance
Usage
1. Pick one or two points
2. Activate the constraint
Contents
1 Constraint
HorizontalDistance
1.1 Description
1.2 Usage
Constraint VerticalDistance
Description
Fixes the vertical distance between 2 points or line ends. If only one
item is selected, the distance is set to the origin.
Usage
1. Pick one or two points
2. Activate the constraint
Constraint
VerticalDistance
Menu location
Sketch Sketcher
geometries Constrain
vertical distance
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint
HorizontalDistance,
Constraint Length
Contents
1 Constraint VerticalDistance
1.1 Description
1.2 Usage
Constraint Length
Description
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.
Hint
If applicable please consider using the Horizontal Distance or Vertical
Distance constraints instead. These constraints are more robust and
faster to calculate than the here documented length constraint.
Operation
Select a line in the sketch,
Constraint Length
Menu location
Sketch Sketcher
constraints Constrain
distance
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint
HorizontalDistance,
Constraint VerticalDistance
Contents
1 Constraint Length
1.1 Description
1.2 Hint
1.3 Operation
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
This constraint constrains the value of the radius of a circle or arc to
have a speci c value. Only one arc or circle can be constrained at a
time.
Operation
Constraint Radius
Menu location
Sketch Sketcher
constraints Constrain
radius
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Constraint Distance,
Constraint Horizontal,
Constraint Vertical
Contents
1 Constraint Radius
1.1 Description
1.2 Operation
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
Angle constraint is a datum constraint intended to x angles in sketch. It is capable of
setting slopes of individual lines, angles between lines, angles of intersections of
curves, and angle spans of circular arcs.
Constraint
InternalAngle
Menu location
How to use
Sketch Sketcher
constraints Constrain
angle
Workbenches
1. to individual lines
Sketcher, PartDesign
2. between lines
Default shortcut
3. to intersections of curves
4. to arcs of circles
See also
Constraint modes
Contents
1 Constraint InternalAngle
2 Description
3 How to use
4 Constraint modes
4.1 line slope angle
4.2 arc span (v0.15)
4.3 between lines
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:
# line slope angle
Sketch.addConstraint(Sketcher.Constraint('Angle',iline,angle))
Constraint SnellsLaw
Description
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
Wikipedia for more info.
Menu location
Sketch Sketcher
Constraints Constrain
refraction (Snell's law)
normal
Constraint
SnellsLaw
Workbenches
Sketcher, PartDesign
Default shortcut
interface
n1
n2
v1
v2
None
See also
None
Contents
1 Constraint SnellsLaw
2 Description
Snell's law
3 How to use
4 Remarks
5 Scripting
6 Version
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:
Sketch is a sketch object
line1 and pointpos1 are two integers identifying the endpoint of the line in medium with refractive index of
n1. line1 is the line's index in the sketch (the value, returned by Sketch.addGeometry), and pointpos1 should
be 1 for start point and 2 for end point.
line2 and pointpos2 are the indexes specifying the endpoint of the second line (in medium n2)
n2byn1 is a floating-point number equal to the ratio of refractive indices n2/n1
Example:
from Sketcher import *
from Part import *
from FreeCAD import *
StartPoint = 1
EndPoint = 2
MiddlePoint = 3
f = App.activeDocument().addObject("Sketcher::SketchObject","Sketch")
# add geometry to the sketch
icir =
f.addGeometry(Part.Circle(App.Vector(-547.612366,227.479736,0),App.Vector(0,0,1),68.161979))
iline1 =
f.addGeometry(Part.Line(App.Vector(-667.331726,244.127090,0),App.Vector(-604.284241,269.275238,0)))
iline2 =
f.addGeometry(Part.Line(App.Vector(-604.284241,269.275238,0),App.Vector(-490.940491,256.878265,0)))
# add constraints
# helper constraints:
f.addConstraint(Sketcher.Constraint('Coincident',iline1,EndPoint,iline2,StartPoint))
f.addConstraint(Sketcher.Constraint('PointOnObject',iline1,EndPoint,icir))
# the Snell's law:
f.addConstraint(Sketcher.Constraint('SnellsLaw',iline1,EndPoint,iline2,StartPoint,icir,1.47))
App.ActiveDocument.recompute()
Version
The constraint was introduced in FreeCAD v0.15.4387
Menu location
Sketch Sketcher
constraints Constrain
InternalAlignment
Workbenches
Sketcher, PartDesign
Default shortcut
Ctrl+A
See also
Operation on Ellipse
1. Select elements to be aligned and an ellipse. The ellipse must be
selected last. Accepted are up to two lines and up to two points.
2. Invoke the constraint by picking the menu item (Sketch/Part
Design Sketcher constraints Constrain InternalAlignment).
The rst 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 rst point is constrained to become the
focus, and the second point goes to the other focus.
Constraint
InternalAlignment
rst unoccupied
Show/Hide Internal
Geometry, Ellipse
Contents
1 Constraint InternalAlignment
1.1 Description
1.2 Operation on
Ellipse
1.3 Scripting
1.4 Version
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:
Sketch is a sketch object.
Number 1 in the focus calls stands for starting point of a point element (it is ignored).
Version
Introduced in FreeCAD v0.15.4309
Sketcher MapSketch
Description
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, Revolution) or be subtracted from the
underlying solid in case of subtractive features (Pocket, Groove).
Please note that this tool is not to be used to create new sketches. It
only maps, or remaps an existing sketch to the face of a solid or a
PartDesign feature. Typical use cases are:
The sketch was created on a standard plane (XY, XZ, YZ) and you
want to map it to the face of a solid in order to build a feature
upon it.
Sketcher
MapSketch
Menu location
Part Design/Sketch Map
sketch to face...
Workbenches
Sketcher, PartDesign
Default shortcut
None
The sketch was mapped on a speci c face of a solid but you need
to map it to a different face.
See also
Contents
1 Sketcher MapSketch
2 Description
3 How to use
How to use
Select the face of a PartDesign feature or a solid.
Click on the
Map 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
Use
1.
Sketcher Reorient
Menu location
Part design Reorient
sketch
2.
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
Map sketch, New Sketch
Contents
1 Sketcher Reorient
2 Description
3 Use
4 Note
Piano XY
Piano XZ
Piano YZ
Offset
1.
2.
3.
4.
Note
Sketcher Validate
32px Sketcher Validate
Menu location
Sketcher Validate sketch
Workbenches
Sketcher, PartDesign
Default shortcut
None
See also
None
Contents
1 32px Sketcher Validate
Sketcher
RestoreInternalAlignmentGeometry
Menu location
Usage
Select an element of a sketch that supports internal
alignment (currently only Ellipse/Arc).
Invoke the command by clicking a toolbar button,
picking the menu item or using the keyboard
shortcut.
If there are free alignment places for the selected
element, new construction geometry is created and
aligned to the available places. If all alignment places are
occupied, the unused internal geometry is deleted (the
element is treated as unused if it is not constrained to
anything else).
Example
Contents
1 Sketcher RestoreInternalAlignmentGeometry
Create a new ellipse. New ellipses are always fullypacked. 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?
1.1 Description
1.2 Usage
1.3 Example
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.
Sketcher CloseShape
Description
This tool can be used to make a selected contour in sketcher closed by
making an endpoint of a sketcher element coincident with the endpoint
of the sketcher element selected next.
Sketcher
CloseShape
Menu location
Usage
While editing a sketch, multi-select your sketcher elements in the treeview or in the 3D-View and click on the icon or use "Sketch > Sketcher
Tools > Close Shape" from the FreeCAD-Menu or use <CTRL+Shift+S>.
Workbenches
Notes
Default shortcut
The tool will connect the elements in the order of their selection, so
make sure to click and select in the correct order.
See also
Limitations
Sketcher
Shift+Ctrl+S
Contents
1 Sketcher CloseShape
1.1 Description
1.2 Usage
1.3 Notes
1.4 Limitations
Sketcher ConnectLines
Description
A p p l i e s PointOnPoint-Constraints to
coordinates of the selected elements.
endpoints
with
the
same
Usage
Select the elements in the 3D-view or in the listbox on the left side of
the screen and click on the icon.
Notes
Before using this command make sure that obvious constraints
(horizontal, vertical, tangential) are already applied to the elements.
Selecting the elements in a counter-clock-wise order seems to produce
better results.
Sketcher
ConnectLines
Menu location
Sketch Sketcher tools
Connect Edges
Workbenches
Sketcher
Default shortcut
Ctrl+Shift+K
See also
Contents
1 Sketcher ConnectLines
1.1 Description
1.2 Usage
1.3 Notes
PartDesign Fillet
Description
This tool creates llets (rounds) on the selected edges of an object. A new separate
Fillet entry (followed by a sequential number if there are already existing llets in the
document) is created in the Project tree.
PartDesign Fillet
Menu location
PartDesign Fillet
Workbenches
PartDesign, Complete
Default shortcut
None
See also
Part Fillet
Contents
1 PartDesign Fillet
1.1 Description
1.2 Usage
1.3 PartDesign Fillet
VS. Part Fillet
2 Scripting
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 llet 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 :
3 = radius
Box.Edges[2] = Edge with its number
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
Menu location
Part Design Chamfer
Workbenches
PartDesign, Complete
Usage
Default shortcut
None
1.
See also
2.
Chamfer Part
3.
PartDesign
Chamfer VS.
Part Chamfer
Rglage de la dimension du chanfrein
dans les paramtres de chanfrein.
Contents
1 PartDesign Chamfer
2 Description
3 Usage
4 PartDesign Chamfer VS. Part
Chamfer
PartDesign Draft
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) is created in the Project tree.
Usage
Select one or
more faces on
an object, then
start the tool
either by
clicking its icon
or going into the
menu.
In Draft
Parameters on
the TaskPanel,
set the required
parameters
and/or options
as described
below.
Click OK to
validate.
Parameters and
Options
Showing Draft Parameter in TaskPanel.
Menu location
Part Design Draft
Workbenches
Part Design
Default shortcut
None
See also
None
Contents
1 PartDesign Draft
2 Description
3 Usage
4 Parameters and Options
4.1 Add Face /
Remove Face
4.2 Draft Angle
4.3 Neutral Plane
4.4 Pull Direction
4.5 Reverse Pull
Direction
5 Special Cases
Special Cases
outward.
PartDesign Mirrored
Introduction
'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:
PartDesign
Mirrored
Menu location
PartDesign Mirrored
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign Mirrored
2 Introduction
3 Use
3.1 Mirror Plane
Selection
3.1.1
Horizontal
sketch axis
3.1.2 Vertical
sketch axis
3.1.3 Select
reference...
3.1.4 Custom
Sketch Axis
3.2 Preview
4 Limitations
Use
Mirror Plane Selection
When creating a mirrored feature, the 'Mirrored parameters' dialogue offers four
different ways of specifying the mirror line or plane.
Horizontal sketch axis
Uses the horizontal axis of the sketch as the axis of symmetry.
Vertical sketch axis
Uses the vertical axis of the sketch as the axis of symmetry.
Select reference...
Allows you to select a plane (such as a face of an object) to use as a mirror plane.
Custom Sketch Axis
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
'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 translated in a given direction. For
example:
PartDesign_LinearPattern
Menu location
PartDesign -> LinearPattern
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign_LinearPattern
2 Introduction
3 Options
3.1 Standard axis
3.2 Select a face
3.3 Select originals
3.4 Length and
Occurrences
4 Limitations
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.
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
'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 given axis. For example:
PartDesign
PolarPattern
Menu location
PartDesign -> PolarPattern
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign PolarPattern
2 Introduction
3 Options
3.1 Standard axis
3.2 Select a face
3.3 Select originals
3.4 Angle and
Occurrences
4 Limitations
5 Examples
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
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
'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 centre of gravity of the selected
features, they usually disappear inside the scaled versions. Therefore,
normally it is only useful to use scaling as part of the MultiTransform
feature.
PartDesign
Scaled
Menu location
PartDesign Scaled
Workbenches
PartDesign, Complete
Options
Default shortcut
None
See also
Select originals
None
Contents
1 PartDesign Scaled
2 Introduction
3 Options
3.1 Select originals
3.2 Factor and
Occurrences
4 Limitations
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
'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 transformations in sequence to them. For
example, to produce a ange with a double row of holes, the hole (the
'original') is rst patterned in a linear pattern in the X direction, and
then patterned eight times in a polar pattern around the Y axis.
PartDesign
MultiTransform
Menu location
PartDesign -> MultiTransform
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign MultiTransform
2 Introduction
3 Options
3.1 Select originals
3.2 Select
transformations
3.2.1 Edit
3.2.2 Delete
3.2.3 Add
transformation
3.2.4 Move
Up/Down
4 Limitations
5 Examples
Options
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
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 rst 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 rst mirrored on the YZ plane and then patterned with two linear patterns to give a
rectangular pattern.
PartDesign WizardShaft
Introduction
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
Gui.runCommand('PartDesign_WizardShaft')
into the Python console of FreeCAD. The wizard will start and show a
default table, the corresponding shaft part and force/moment graphs.
PartDesign
WizardShaft
Menu location
Part Design Shaft design
wizard...
Workbenches
PartDesign, Complete
Default shortcut
None
See also
None
Contents
1 PartDesign WizardShaft
2 Introduction
3 Prerequisites
4 Parameters
5 Menus
6 Limitations
7 Planned functionality
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
Length of the segment
Diameter of the segment
Load type. Note that you have to click on the desired entry in the menu after scrolling to it, otherwise
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 de nition of loads as a Document
Object, otherwise the table will become very long)
PartDesign InvoluteGear
Description
This tool allows you to create a 2D pro le of an involute gear. This 2D
pro le is fully parametric, and can be padded with the PartDesign Pad
feature.
PartDesign
InvoluteGear
Menu location
Part Design Involute
gear...
Workbenches
PartDesign
Default shortcut
None
See also
None
Contents
1 PartDesign InvoluteGear
2 Description
3 How to use
4 Parameters
4.1 Number of teeth
4.2 Modules
4.3 Pressure angle
4.4 High precision (on
v0.15 development
version only)
4.5 External gear (on
v0.15 development
version only)
5 Bugs
How to use
1. Go to the Part Design
Parameters
Number of teeth
Sets the number of teeth.
Modules
Pitch diameter divided by the number of teeth.
Pressure angle
Acute angle between the line of action and a normal to the line connecting the gear centers. Default is 20
degrees. (More info)
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
Contents
1 Introduction
2 First sketch: a triangle
3 More about Constraints
4 Problematic combination of constraints
5 Construction Lines - Step by Step Example
6 Exercise: resilient sketch
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
de ned 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:
draw the base line
make two circles with a radius given by the other two side lengths, or alternatively calculate the
coordinates of the third vertex
draw the missing two sides from the endpoints of the base line to the crossing point of the two circles
or the calculated vertex.
The wikipedia:Triangle page shows a collection of formulas to calculate the missing information in order to
draw a triangle from the minimum speci cation. Those are needed, if the triangle has to be de ned by precalculated 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.
This will make sure that the last vertex is identical to the rst one and the pro le 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 exible. 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 de ned 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-de nitions are called constraints. Constraints are used to de ne a xed design from the
exible geometric input. The sketcher provides all constraints needed to de ne any kind of triangle. Only
the area can not be used to de ne one. So the created triangle can be rede ned 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
dialog to define the angle.
opens a
Equilateral: One side has to be set to a de ned 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 rst the two sides with the equal
length. A click on
vertex and click the
sets a equality between the two sides. Then select the base line and the top
length tool.
They can be
can be later
a part of the
later time, if
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 de ned, it still needed to be xed 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 x 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
de ned 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.
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 de ne 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 rst
and then set the 180-constraints. This helps, not forgetting one, or setting one twice.
The following table shows some constraints combinations for the de nition of a simple elbow. The
combination was tested by enlarging the 10 mm length horizontal dimension to greater values until the
elbow ips its orientation. The table documents for each shown constraint combination the changed length
where the flipping occurs.
Constraints Combination
Remarks
The test showed the following: larger changes of dimension constraints may cause a ipping of some lines
of the sketch due to multiple solutions of the underlying system of equations. The only constraints that do
preserve the orientation of the elements they are applied to, are the angle constraint and the horizontal and
vertical dimension constraints. The differences between the other constraints regarding maintaining
orientation are minor.
Recommendation: Use angle constraints and horizontal and vertical dimension constraints at critical places
in order to make a sketch robust against dimension changes.
C
D
2.
3.
A
1.
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.
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 rst 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 constraincombination. 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
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
The reference point should stay at the center of the distance AB. This will be achieved by selecting rst 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
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 de ne 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 de ned 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 rst two points are xed to C and the
center point. This should be tested with dragging at the arc after finishing it.
In order to de ne 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 de ned 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 nal 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
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.
are discussed. Here is an exercise to get some practice at working with the sketcher. The goal is to make a
sketch for something like a special frame as shown below.
There should be only three dimensions needed to de ne 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
can be used.
The above sketch is unusable for the Part-Design Workbench. Only Pro le 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
These are tools for creating objects.
Line: Draws a line segment between 2 points
Wire: Draws a line made of multiple line segments (polyline)
Circle: Draws a circle from center and radius
Arc: Draws an arc segment from center, radius, start angle and end angle
Ellipse: Draws an ellipse from two corner points
Polygon: Draws a regular polygon from a center and a radius
Rectangle: Draws a rectangle from 2 opposite points
Text: Draws a multi-line text annotation
Dimension: Draws a dimension annotation
BSpline: Draws a B-Spline from a series of points
Point: Inserts a point object
ShapeString: The ShapeString tool inserts a compound shape representing a text string at a
given point in the current document
Facebinder: Creates a new object from selected faces on existing objects
Bezier Curve: Draws a Bezier curve from a series of points
Modifying objects
These are tools for modifying existing objects. They work on selected objects, but if no object is selected,
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
Undo line: Undoes the last segment of a line
Toggle construction mode: Toggles the Draft construction mode on/off
Toggle continue mode: Toggles the Draft continue mode on/off
Apply style: Applies the current style and color to selected objects
Toggle display mode: Switches the display mode of selected objects between " at lines" and
"wireframe"
Add to group: Quickly adds selected objects to an existing group
Select group contents: Selects the contents of a selected group
Toggle snap: Toggles object snapping on/off
Toggle grid: Toggles the grid on/off
Show snap bar: Shows/hides the snapping toolbar
Heal: Heals problematic Draft objects found in very old files
Flip Dimension: Flips the orientation of the text of a dimension
VisGroup: Creates a VisGroup in the current document
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
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 les via the DXF importer, when the Teigha Converter utility
is installed.
Additional features
Snapping: Allows to place new points on special places on existing objects
Constraining: Allows to place new points horizontally or vertically in relation to previous points
Working with manual coordinates: Allows to enter manual coordinates instead of clicking on screen
Working plane: Allows you to define a plane in the 3D space, where next operations will take place
Preference settings
The Draft module has its preferences screen
Scripting
The Draft module features a complete Draft API so you can use its functions in scripts and macros
Tutorials
Draft tutorial
Draft tutorial Outdated
Draft Line
Description
Draft Line
The Line tool creates a straight, two-points line in the current work
plane. It takes the linewidth and color previously set on the Tasks tab.
The Line tool behaves exactly like the Draft Wire tool, except that it
stops after two points.
Menu location
Draft Line
Workbenches
Draft, Arch
Default shortcut
LI
See also
Draft Wire
Contents
1 Draft Line
2 Description
How to use
3 How to use
4 Options
1. Press the
5 Properties
6 Scripting
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 rst 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
Press ESC or the Cancel button to abort the current Line command.
Properties
DATA
DATA
DATA
Scripting
The Line tool can by used in macros and from the python console by using the following function:
makeLine (Vector, Vector)
Creates a line between the two given vectors. The current draft linewidth and color will be used.
Returns the newly created object.
Example:
import FreeCAD, Draft
Draft.makeLine(FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,0,0))
Draft Wire
Description
Draft Wire
Menu location
Draft Wire
Workbenches
Draft, Arch
Default shortcut
WI
See also
Draft Line, Draft BSpline
Contents
1 Draft Wire
How to use
1. Press the
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
Options
Press F or the
Press C or the
Close button or click on the rst point to nish 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 nish 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
last point.
Wipe button to remove the existing segments and start the wire from the
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
DATA
DATA
Fillet Radius: Specifies a curvature radius to give to the nodes of the wire
DATA
Subdivisions: Divides the segments of the wire with the given number of subdivisions
available in version
0.16
End Arrow: Shows an arrow symbol at the last point of the wire, so it can be used as an annotation
leader line
VIEW
VIEW
Pattern: Specifies a hatch pattern to fill the wire with (Closed Wire)
VIEW
Scripting
The Wire tool can by used in macros and from the python console by using the following function:
makeWire (list or Part.Wire, [closed], [placement], [facemode])
Creates a Wire object from the given list of vectors or from the given wire.
If closed is True or if first and last points are identical, the wire is closed.
If facemode is True (and the wire is closed), the wire will appear filled.
The current Draft linewidth and color will be used.
Returns the newly created object.
Example:
import FreeCAD,Draft
p1 = FreeCAD.Vector(0,0,0)
p2 = FreeCAD.Vector(1,1,0)
p3 = FreeCAD.Vector(2,0,0)
Draft.makeWire([p1,p2,p3],closed=True)
Draft Circle
Description
Draft Circle
The Circle tool creates a circle in the current work plane by entering two
points, the center and the radius, or by picking tangents, or any
combination of those. It takes the linewidth and color previously set on
the Tasks tab. This tool works the same way as the Draft Arc tool, except
that it stops after entering the radius.
Menu location
Draft -> Circle
Workbenches
Draft, Arch
Default shortcut
CI
See also
Draft Arc
Contents
1 Draft Circle
2 Description
3 How to use
4 Options
How to use
1. Press the
5 Properties
6 Scripting
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 rst 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
VIEW
VIEW
Scripting
The Circle tool can by used in macros and from the python console by using the following function:
makeCircle (radius, [placement], [facemode], [startangle], [endangle])
Creates a circle object with given radius.
If a placement is given, it is used.
If facemode is False, the circle is shown as a wireframe, otherwise as a face.
If startangle AND endangle are given (in degrees), they are used and the object appears as an arc.
Returns the newly created object.
Example:
import Draft
myCircle = Draft.makeCircle(2)
Draft Arc
Description
Draft Arc
The Arc tool creates an arc in the current work plane by entering four
points, the center, the radius, the rst point and the last point, or by
picking tangents, or any combination of those. It takes the linewidth and
color previously set on the Tasks tab. This tool works the same way as
the Draft Circle tool, but adds start and end angles.
Menu location
Draft Arc
Workbenches
Draft, Arch
Default shortcut
AR
See also
Draft Circle
Contents
1 Draft Arc
2 Description
3 How to use
4 Options
How to use
1. Press the
5 Properties
6 Scripting
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 de ne 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
Properties
DATA
DATA
DATA
Scripting
The Circle tool can also be used to create arcs in macros and from the python console by using the following
function, giving it additional arguments:
makeCircle (radius, [placement], [facemode], [startangle], [endangle])
Creates a circle object with given radius.
If a placement is given, it is used. If facemode is False, the circle is shown as a wireframe, otherwise
as a face.
If startangle AND endangle are given (in degrees), they are used and the object appears as an arc.
Returns the newly created object.
Example:
import Draft
myArc = Draft.makeCircle(2,startangle=0,endangle=90)
Draft Ellipse
Description
Draft Ellipse
The Ellipse tool creates an ellipse in the current work plane by entering
two points, de ning the corner of a rectangular box in which the ellipse
will fit. It takes the linewidth and color previously set on the Tasks tab.
Menu location
Draft -> Ellipse
Workbenches
Draft, Arch
Default shortcut
EL
See also
Draft Circle
Contents
1 Draft Ellipse
2 Description
How to use
1. Press the
3 How to use
4 Options
5 Properties
6 Scripting
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
DATA
VIEW
VIEW
Scripting
The Ellipse tool can by used in macros and from the python console by using the following function:
makeEllipse (majorradius, minorradius, [placement], [facemode])
Creates an ellipse object with given major and minor radius.
If a placement is given, it is used.
If facemode is False, the ellipse is shown as a wireframe, otherwise as a face.
Returns the newly created object.
Example:
import Draft
myEllipse = Draft.makeEllipse(4,2)
Draft Polygon
Description
Draft Polygon
The polygon tool creates a regular polygon by picking two points, the
center and a second point de ning a radius. It takes the linewidth and
color previously set on the Tasks tab.
Menu location
Draft -> Polygon
Workbenches
Draft, Arch
Default shortcut
PG
See also
None
Contents
1 Draft Polygon
2 Description
3 How to use
How to use
1. Press the
4 Options
5 Properties
6 Scripting
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 nish 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.
Properties
DATA
DATA
Draw Mode: Specifies if the polygon is inscribed or circumscribed around the defining circle
DATA
DATA
DATA
Fillet Radius: Specifies a curvature radius to give to the corners of the rectangle
VIEW
VIEW
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
The rectangle tool creates a rectangle by picking two opposite points. It
takes the linewidth and color previously set on the Tasks tab.
Menu location
Draft -> Rectangle
Workbenches
Draft, Arch
Default shortcut
RE
See also
Part Box
Contents
1 Draft Rectangle
How to use
1. Press the
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
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 nish 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
DATA
DATA
DATA
Fillet Radius: Specifies a curvature radius to give to the corners of the rectangle
DATA
DATA
Texture Image: Allows to give the path to an image le to be mapped on the rectangle. It is up to
you to give the rectangle the same proportion as the image if you want to avoid distortions. Blanking
this property will remove the image.
VIEW
VIEW
VIEW
Scripting
The Rectangle tool can by used in macros and from the python console by using the following function:
makeRectangle (length, width, [placement], [facemode])
Creates a Rectangle object with length in X direction and height in Y direction.
If a placement is given, it is used.
If facemode is False, the rectangle is shown as a wireframe, otherwise as a face.
The current Draft linewidth and color will be used.
Returns the newly created object.
Example:
import FreeCAD,Draft
Draft.makeRectangle(10,4)
Draft Text
Draft Text
Description
The Text tool inserts a piece of text at a given point in the current
document. It takes the text size and color previously set on the Tasks
tab.
Menu location
Draft Text
Workbenches
Draft, Arch
Default shortcut
TE
See also
None
Contents
1 Draft Text
How to use
1. Press the
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
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
DATA
VIEW
Display Mode: Specifies if the text is aligned to the scene axes or always faces the camera
VIEW
VIEW
Justification: Specifies if the text is aligned to the left, right or center of the base point.
VIEW
VIEW
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
Scripting
The Text tool can by used in macros and from the python console by using the following function:
makeText (string or list, [Vector], [screenmode])
Creates a Text object, at the given point if a vector is provided, containing the string or the strings
given in the list, one string by line.
The current Draft color and text height and font specified in preferences are used.
If screenmode is True, the text always faces the view direction, otherwise it lies on the XY plane.
Returns the newly created object.
Example:
import FreeCAD,Draft
Draft.makeText("This is a sample text",FreeCAD.Vector(1,1,0))
Draft Dimension
Description
Draft Dimension
Menu location
Draft Dimension
Workbenches
Draft, Arch
Default shortcut
DI
See also
FlipDimension
Contents
1 Draft Dimension
2 Description
How to use
1. Press the
3 How to use
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
DATA
DATA
VIEW
Display Mode: Specifies if the text is aligned to the dimension lines or always faces the camera
VIEW
Ext Lines: The size of the extension lines (between the measurement points and the dimension
line)
VIEW
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: Speci es a text to display instead of the measurement. Insert "$dim", inside that text,
to display the 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
VIEW
VIEW
VIEW
VIEW
Scripting
The Dimension tool can by used in macros and from the python console by using the following functions:
makeDimension (p1,p2,[p3])
or
makeDimension (object,i1,i2,p3)
or
makeDimension (objlist,indices,p3)
Creates a Dimension object with the dimension line passign through p3.
The Dimension object takes the Draft linewidth and color set in the command bar.
There are multiple ways to create a dimension, depending on the arguments you pass to it:
1. (p1,p2,p3): creates a standard dimension from p1 to p2.
2. (object,i1,i2,p3): creates a linked dimension to the given object, measuring the distance between its
vertices indexed i1 and i2.
3. (object,i1,mode,p3): creates a linked dimension to the given object, i1 is the index of the (curved)
edge to measure, and mode is either "radius" or "diameter". Returns the newly created object.
makeAngularDimension (center,[angle1,angle2],p3)
creates an angular Dimension from the given center, with the given list of angles, passing through p3.
Returns the newly created object.
Example:
import FreeCAD,Draft
p1 = FreeCAD.Vector(0,0,0)
p2 = FreeCAD.Vector(1,1,0)
p3 = FreeCAD.Vector(2,0,0)
Draft.makeDimension(p1,p2,p3)
Links
Tutorial: Projecting dimensions on a Drawing Page
Draft BSpline
Draft BSpline
Description
The BSpline tool creates a B-Spline curve from several points in the
current work plane. It takes the linewidth and color previously set on the
Tasks tab. The BSpline tool behaves exactly like the Draft Wire tool.
Menu location
Draft BSpline
Workbenches
Draft, Arch
Default shortcut
BS
See also
Draft Wire
Contents
1 Draft BSpline
2 Description
How to use
1. Press the
3 How to use
4 Options
5 Properties
6 Scripting
Options
Press F or the
Press C or the
Close button or click on the rst point to nish 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 nish 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
last point.
Wipe button to remove the existing segments and start the spline from the
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
End Arrow: Shows an arrow symbol at the last point of the spline, so it can be used as an
annotation leader line
VIEW
VIEW
VIEW
Scripting
The BSpline tool can by used in macros and from the python console by using the following function:
makeBSpline (pointslist,[closed],[placement])
Creates a B-Spline object from the given list of vectors.
If closed is True or first and last points are identical, the wire is closed.
If face is true (and the bspline is closed), the bspline will appear filled.
Instead of a list of points, you can also pass a Part Wire.
Returns the newly created object.
Example:
import FreeCAD,Draft
p1 = FreeCAD.Vector(0,0,0)
p2 = FreeCAD.Vector(1,1,0)
p3 = FreeCAD.Vector(2,0,0)
Draft.makeBSpline([p1,p2,p3],closed=True)
Draft Point
Description
Draft Point
The Point tool creates a simple point in the current work plane, handy to
serve as reference for placing other objects later. It takes the color
previously set on the Tasks tab.
Menu location
Draft -> Point
Workbenches
Draft, Arch
Default shortcut
PT
See also
None
Contents
1 Draft Point
2 Description
3 How to use
How to use
1. Press the
4 Options
5 Properties
6 Scripting
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
DATA
DATA
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
Menu location
Draft -> ShapeString
Workbenches
Draft, Arch
Default shortcut
SS
See also
None
Contents
How to use
1. Press the
keys
1 Draft ShapeString
Draft ShapeString
button, or press S
then S
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
7 Selecting A Font
8 Limitations
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
DATA
DATA
DATA
DATA
Font File: The font definition file used to draw the string
Scripting
The ShapeString tool can by used in macros and from the python console by using the following function:
makeShapeString(String,FontFile,[Size],[Tracking])
Turns a text string into a Compound Shape using a specified font.
Example:
import FreeCAD,Draft
Draft.makeShapeString("This is a sample text",
"/usr/share/fonts/truetype/msttcorefonts/Arial.ttf",
200.0,10)
Selecting A Font
ShapeString uses the internal geometry of a font to make FreeCAD shapes. To do this it must read the actual
font le (*.tff, etc). If the Font Selection box is empty, you must type the full path to the font le or use ...
to select a font file.
Limitations
This tool is not available in FreeCAD versions anterior to 0.14
TrueType(*.ttf), OpenType(*.otf) and Type1(*.pfb) font files are supported.
Very small text heights may result in deformed character glyphs due to loss of detail in scaling.
The current version is limited to left-to-right layouts on a horizontal baseline.
Draft Facebinder
Description
Draft Facebinder
Menu location
Draft Facebinder
Workbenches
Draft, Arch
Default shortcut
FF
See also
None
Contents
1 Draft Facebinder
2 Description
3 How to use
4 Scripting
5 Limitations
How to use
1. Select faces on objects (use CTRL to select several faces)
2. Press the
Scripting
The facebinder tool can be usedin scripts and macros by using the following function:
makeFacebinder ( selectionset )
Creates a facebinder object from the given selection set, which is a list of selection objects such as
returned by the FreeCADGui.Selection.getSelectionEx() method.
Only selected faces are taken into account
Returns the newly created object
Example:
import Draft, FreeCADGui
mySelection = FreeCADGui.Selection.getSelectionEx()
Draft.makeFacebinder(mySelection)
Limitations
Not available before version 0.14
Draft BezCurve
Description
Draft BezCurve
The BezCurve tool creates a Bezier Curve (or a piecewise Bezier Curve)
from several points in the current work plane. It takes the linewidth and
color previously set on the Tasks tab.
The object is created as a single Bezier Curve of degree
(number_of_points - 1). This can be changed to a piecewise Bezier Curve
of a speci ed degree after creation using the properties editor. Bezier
Curves can be edited using
Draft Edit .
Menu location
Draft -> BezCurve
Workbenches
Draft, Arch
Default shortcut
BZ
See also
None
Contents
1 Draft BezCurve
2 Description
3 How to use
4 Options
5 Properties
How to use
1. Press the
6 Scripting
7 Contraining Nodes
8 Limitations
Options
Press F or the
Press C or the
Close button or click on the rst point to nish 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
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
last point.
Wipe button to remove the existing segments and start the spline from the
Press ESC or the Cancel button to abort the current BezCurve command.
Properties
DATA
DATA
Scripting
The BezCurve tool can by used in macros and from the python console by using the following function:
makeBezCurve(pointslist,[closed],[placement],[support],[degree])
Create a Bezier Curve object from the given list of vectors. Instead of a pointslist, you can also pass a
Part Wire.
Example:
import FreeCAD,Draft
myFeature = Draft.makeBezCurve(Draft.makeBezCurve(points,False)
Contraining Nodes
The segment endpoints in a piecewise Bezier Curve can be constrained such that adjacent control points are
tangent or symmetric to the segments at the endpoint. This is done after object creation using
Draft
Edit .
Sharp - remove constraints
Tangent - force adjacent control points to be tangent
Symmetric - force adjacent control points to be tangent and equi-distant
Limitations
This tool is not available before FreeCAD version 0.14
The Points Property does not yet appear in the properties list.
OpenCascade does not support Bezier Curve with degree > 25. This should not be a problem in
practice.
Draft Move
Description
Draft Move
The Move tool moves or copies the selected objects from one point to
another on the current work plane. If no object is selected, you will be
invited to select one.
Menu location
Draft -> Move
Workbenches
Draft, Arch
Default shortcut
MV
See also
None
Contents
1 Draft Move
How to use
2 Description
3 How to use
By default the option "Always snap (disable snap mod)" is activated, which means that the snapping tools
will always be active (you don't need to press a key to activate them), note here what keys are assigned to
activate the different modes, by default:
SHIFT activate the Constrain mode (move along an axis vector only)
Ctl activate the SNAP mode (cursor will snap on specific points)
Alt activate the ALT
Snapping
If you have a point that you want to directly match on a solid, you can use snapping see the snapping page
on how to activate the snap. Select the rst point (using snap or not), and then hover to the second point
until you see it highlighted.
By default the snapping mode is activated, but you may have it deactivated in the preferences (see
preceding section), in that case, you will have to hold the Snapping key Ctrl by default.
Alt Mode
Alt mode allows you to copy and object instead of moving it only.
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 nish or close it, allowing you to move or copy the objects another
time without pressing the Move button again.
Pressing ALT or C or clicking the Copy button will make a copy of the objects, instead of moving
them. If you keep ALT pressed after clicking the second point, you will be able to place more copies,
until you release the ALT key.
Press CTRL while drawing to force snapping your point to the nearest snap location, independently
of the distance.
Press SHIFT while drawing to constrain your next point horizontally or vertically in relation to the last
one.
Press ESC or the Cancel button to abort the current command.
Scripting
The Move tool can by used in macros and from the python console by using the following function:
move (FreeCAD.Object or list, Vector, [copymode])
Moves the given object or the objects contained in the given list in the direction and distance
indicated by the given vector.
If copymode is True, the actual objects are not moved, but copies are created instead. Returns the
object(s) (or their copies if copymode was True)
A list of the moved object (or the copies) is returned
Example:
import FreeCAD,Draft
Draft.move(FreeCAD.ActiveDocument.ActiveObject,FreeCAD.Vector(2,2,0))
Limitations
When moving (or changing Placement of) a document object (eg: Pad, Revolution, etc) which is based
on a Sketch (from Sketcher/Part Design), you must move the original sketch. If you move the derived
object, it will just go back to the position defined by the sketch.
Draft Rotate
Description
Draft Rotate
This tool rotates or copies the selected objects by a given angle around
a point on the current work plane. If no object is selected, you will be
invited to select one.
Menu location
Draft -> Rotate
Workbenches
Draft, Arch
Default shortcut
RO
See also
None
Contents
1 Draft Rotate
2 Description
How to use
3 How to use
4 Options
5 Scripting
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 nish 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.
Scripting
The Rotate tool can by used in macros and from the python console by using the following function:
rotate (FreeCAD.Object or list, angle, [center], [axis] ,[copymode])
Rotates the given object or the objects contained in the given list with the given angle around the
given center if provided, using axis as a rotation axis.
If axis is omitted, the rotation will be around the vertical Z axis.
If copymode is True, the actual objects are not moved, but copies are created instead.
Returns the objects (or their copies is copymode was True).
Example:
import FreeCAD,Draft
Draft.rotate(FreeCAD.ActiveDocument.ActiveObject,45)
Draft Offset
Description
Draft Offset
The Offset tool offsets the selected object by a given distance on the
current work plane. If no object is selected, you will be invited to select
one.
Menu location
Draft -> Offset
Workbenches
Draft, Arch
Default shortcut
OS
See also
None
Contents
1 Draft Offset
How to use
2 Description
3 How to use
4 Options
5 Scripting
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 nish 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
This tool trims/cuts and extends lines and polylines, and extrudes faces.
Menu location
Draft -> Trim/Extend
Workbenches
Draft, Arch
Default shortcut
TR
See also
Part Extrude
Contents
1 Draft Trimex
How to use
2 Description
1. Select a wire you wish to trim or extend, or select a face you wish
to extrude
2. Press the
3 How to use
4 Options
5 Scripting
Options
trimming or extending is decided automatically from the position of your mouse
if you move the mouse cursor over another object, the trim/extend operation will snap to that object
or segment
pressing SHIFT will constrain you to the segment currently being trimmed or extended
pressing ALT will invert the direction of the trimming
When the selected object is a face, or a face is selected from an existing object, the trimex tool
switches to extrude mode. In extrude mode, pressing SHIFT frees the extrusion from the face normal
and allows to snap elsewhere.
Scripting
Not available. See the Part Extrude tool.
Draft Upgrade
Description
Draft Upgrade
Menu location
Draft Upgrade
Workbenches
Draft, Arch
Default shortcut
UP
See also
Draft Downgrade
How to use
1. Select one or more objects you wish to upgrade
2. Press the
Options
Contents
1 Draft Upgrade
2 Description
3 How to use
4 Options
5 Scripting
if there are more than one face in the selection, the faces are
merged (union)
if there is only one face in the selection, nothing is done
if there is only one open wire in the selection, it gets closed
if there are only edges in the selection, all edges are joined into a wire (closed if possible)
if none of the above is possible, a compound object is created
Scripting
The upgrade tool can be used from python scripts and macros like this:
Draft.upgrade(objects, delete=False, force=None)
Upgrades the given object(s) (can be an object or a list of objects).
If delete is True, old objects are deleted.
The force attribute can be used to force a certain way of upgrading. It can be: makeCompound,
closeGroupWires, makeSolid, closeWire, turnToParts, makeFusion, makeShell, makeFaces, draftify,
joinFaces, makeSketchFace, makeWires
Returns a dictionnary containing two lists, a list of new objects and a list of objects to be deleted
Some of the operations of the Upgrade tool can also be made with the Part Fuse or Draft Wire tools.
Example:
import Draft
mycircle = Draft.makeCircle(2)
face1 = Draft.upgrade([mycircle],True)
Draft Downgrade
Draft Downgrade
Description
This tool downgrades selected objects in different ways. If no object is
selected, you will be invited to select one.
Menu location
Draft -> Downgrade
Workbenches
Draft, Arch
Default shortcut
DN
See also
Draft Upgrade
How to use
1. Select one or more objects you want to downgrade
2. Press the
Contents
Options
1 Draft Downgrade
2 Description
3 How to use
Example
Complete shape
4 Options
5 Example
6 Scripting
Scripting
The Downgrade tool can be used in python scripts and macros by using the following function:
downgrade (objects, [delete], [force])
Downgrades the given object(s) (can be an object or a list of objects).
If delete is True, old objects are deleted.
The force attribute can be used to force a certain way of downgrading. It can be: explode, shapify,
subtr, splitFaces, cut2, getWire, splitWires.
Returns a dictionary containing two lists, a list of new objects and a list of objects to be deleted
Example:
import FreeCADGui,Draft
selection = FreeCADGui.Selection.getSelection()
Draft.downgrade(selection)
Draft Scale
Description
Draft Scale
Menu location
Draft Scale
Workbenches
Draft, Arch
Default shortcut
SC
See also
Draft Clone
Contents
1 Draft Scale
2 Description
3 How to use
How to use
4 Options
5 Scripting
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 de ne the scale factor. For example, (1,1,1) would do
nothing, (2,2,2) would scale 2x in all directions, (-1,1,1) would mirror in x direction.
Pressing ALT or C or clicking the Copy button will make a copy of the objects, instead of scaling
the original. If you keep ALT pressed after clicking the second point, you will be able to place more
copies, until you release the ALT key.
Press CTRL while drawing to force snapping your point to the nearest snap location, independently
of the distance.
Pressing SHIFT will lock x and y values together, so the shape is not deformed.
Press ESC or the Cancel button to abort the current command.
The resulting object is a Draft Clone, which allows you to change the scale values after it has been
created.
Mirroring objects works by inverting the sign of one of the directions. For example, (-1,1,1) mirrors
horizontally (on the X axis), and (1,-1,1) vertically (on the Y axis).
Scripting
The Scale tool can by used in macros and from the python console by using the following function:
scale (objects,vector,[center,copy,legacy])
Scales the objects contained in objects (that can be a list of objects or an object) of the given scale
factors defined by the given vector (in X, Y and Z directions) around the given center.
If legacy is True, direct (old) mode is used, otherwise a parametric copy is made.
If copy is True, the actual objects are not moved, but copies are created instead.
The objects (or their copies) are returned.
Example:
import FreeCAD,Draft
Draft.scale(FreeCAD.ActiveDocument.ActiveObject,FreeCAD.Vector(2,2,2))
Draft Edit
Description
This tool allows you to edit graphically certain properties of the selected
object, such as the vertices of a Wire, or the length and width of a
Rectangle, or the radius of a Circle. It does nothing more than enter the
object's edit mode, so other ways to enter edit mode (such as doubleclicking the object in the Tree view) give the same result.
Draft Edit
Menu location
Draft Edit
Workbenches
Draft, Arch
Default shortcut
None
See also
None
Contents
1 Draft Edit
2 Description
How to use
1. Select a wire, line, rectangle, bspline or circle
3 How to use
4 Options
5 Scripting
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 rst 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
Pressing the
segments
Add point button allows you to add points to Wires and BSplines by clicking on the
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
This tool converts Wires to BSplines, and vice-versa.
Draft
WireToBSpline
Menu location
Drafting Wire to BSpline
Workbenches
Draft, Arch
Default shortcut
None
See also
None
Contents
1 Draft WireToBSpline
How to use
2 Description
Options
3 How to use
4 Options
5 Scripting
The original object will not be deleted after the operation, you must delete it manually if you wish so.
Scripting
Not available, but creating a new object with the points from another one is easy, for example:
If the active object is a wire:
import FreeCAD,Draft
points = FreeCAD.ActiveDocument.ActiveObject.Points
Draft.makeBSpline(points)
if the active object is a bspline
import FreeCAD,Draft
points = FreeCAD.ActiveDocument.ActiveObject.Points
Draft.makeWire(points)
Draft AddPoint
Description
Draft AddPoint
This tools allows you to add additional points to Wires and BSplines.
How to use
Workbenches
Menu location
Draft, Arch
Default shortcut
See also
Options
This functionality is also available inside the
None
None
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
Contents
1 Draft AddPoint
2 Description
3 How to use
4 Options
5 Scripting
Draft DelPoint
Description
Draft DelPoint
This tools allows you to remove points from Wires and BSplines.
How to use
Workbenches
Menu location
Draft, Arch
Default shortcut
See also
Options
This functionality is also available inside the
Draft AddPoint
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
Contents
1 Draft DelPoint
2 Description
3 How to use
4 Options
5 Scripting
Draft Shape2DView
Description
This tool places in the document a 2D object which is a attened view of
a selected Shape-based object, projected along the current view
direction.
Draft
Shape2DView
Menu location
Draft Shape 2D View
Workbenches
Draft, Arch
Default shortcut
None
See also
None
Contents
1 Draft Shape2DView
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
How to use
1. Select the object you want to extract a 2D view from
2. Rotate the view (or use the view presets shortcuts) so it re ects the direction you want to project the
object to. For example, using a Top view will project the object on the XY plane, vertically along the Z
axis like on the image above.
3. Press the
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
DATA
Projection Mode: 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])
Adds a 2D shape to the document, which is a 2D projection of the given object.
A specific projection vector can also be given.
Returns the generated object.
You can also provide a list of face numbers to be considered.
Example:
import FreeCAD,Draft
Draft.makeShape2DView(FreeCAD.ActiveDocument.ActiveObject)
Draft Draft2Sketch
Description
This tool converts Draft objects to Sketcher objects, and vice-versa.
Draft
Draft2Sketch
Menu location
Drafting Draft to Sketch
Workbenches
Draft, Arch
Default shortcut
None
See also
None
Contents
1 Draft Draft2Sketch
2 Description
3 How to use
4 Options
5 Scripting
How to use
1. Select a Draft object or a Sketch
2. Press the
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 Module documentation for how to create sketches by scripting
Draft Array
Description
Draft Array
The Array tool creates an orthogonal (3-axes) or polar array from a selected object. If
no object is selected, you will be invited to select one.
Menu location
Draft Array
Workbenches
Draft, Arch
Default shortcut
None
See also
PathArray
How to use
Contents
Options
The array starts as orthogonal by default, you can then change its mode in the
properties.
Properties
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
DATA
Scripting
1 Draft Array
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
6.1 Simple array
6.2 Parametric array
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
For rectangular array:
array (objectslist,xvector,yvector,xnum,ynum,[zvector,znum])
For polar array:
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
For rectangular array:
makeArray (object,xvector,yvector,xnum,ynum)
For polar array:
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
Description
Draft Clone
Menu location
Draft Clone
Workbenches
Draft, Arch
Default shortcut
None
See also
Draft Scale
Contents
1 Draft Clone
How to use
2 Description
3 How to use
Options
4 Options
5 Properties
6 Scripting
Clones of 2D objects (Draft or Sketch) will also be 2D objects, and therefore can be used as such for
Part Design.
All Arch objects have the possibility to behave as a clone (using their CloneOf property). If you use the
Draft Clone tool on a selected Arch object, you will produce such an Arch cloned object instead of a
regular Draft clone.
Properties
DATA
Scripting
The Clone tool can by used in macros and from the python console by using the following function:
clone (obj,[delta])
Makes a clone of the given object(s).
Draft SelectPlane
Description
Draft SelectPlane
The Draft module features a working plane system, that allows you to
specify a custom plane in the 3D space on which next Draft command
will occur. There are several methods to define the working plane:
From a selected face
From the current view
From a preset: top, frontal or lateral
None, in which case the working plane is adapted automatically to
the current view when you start a command, or to a face if you
start drawing on an existing face.
Menu location
Draft Utilities Select
Plane
Workbenches
Draft, Arch
Default shortcut
WP
See also
None
Contents
1 Draft SelectPlane
2 Description
3 How to use
4 Options
5 Scripting
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 AUTO will unset any current working plane. The next 2D operations will be viewdependent.
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()
You can also access the current Draft working 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
Description
Draft VisGroup
How to use
1. Press the
Menu location
None
VisGroup button
Contents
1 Draft VisGroup
2 Description
3 How to use
Arch Workbench
(Redirected from Arch Workbench)
The Arch workbench provides modern BIM work ow 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
These are tools for creating architectural objects.
Wall: Creates a wall from scratch or using a selected object as a base
Structural element: Creates a structural element from scratch or using a selected object as a
base
Rebar: Creates a reinforcement bar in a selected structural element
Floor: Creates a floor including selected objects
Building: Creates a building including selected objects
Site: Creates a site including selected objects
Window: Creates a window using a selected object as a base
Section Plane: Adds a section plane object to the document
Axes system: Adds an axes system to the document
Roof: Creates a sloped roof from a selected face
Space: Creates a space object in the document
Stairs: Creates a stairs object in the document
Panel: Creates a panel object from a selected 2D object
Frame: Creates a frame object from a selected layout
Equipment: Creates an equipment or furniture object
Material: Attributes a material to selected objects
Schedule: Creates different types of schedules
Modification tools
These are tools for modifying architectural objects.
Cut with plane: Cut an object according to a plan.
Add component: Adds objects to a component
Remove component: Subtracts or removes objects from a component
Utilities
These are additional tools to help you in specific tasks.
Component: Creates a non-parametric Arch component
Split Mesh: Splits a selected mesh into separate components
Mesh To Shape: Converts a mesh into a shape, unifying coplanar faces
Select non-solid meshes: Selects all non-solid meshes from the current selection or frm the
document
Remove Shape: Turns cubic shape-based arch object fully parametric
Close Holes: Closes holes in a selected shape-based object
Merge Walls: Merge two or more walls
Check: Check if the selected objects are solids and don't contain defects
Ifc Explorer: Browse the contents of an IFC file
Toggle IFC Brep flag: Forces a selected object to be exported as an IfcFacetedBrep.
3 Views from mesh: Creates top, frontal and side views from a mesh.
BIM server: Opens a BimServer window.
Commit with Git: Commits the current file with GIT.
File formats
IFC : Industry foundation Classes (import only)
DAE : Collada mesh format
OBJ : Obj mesh format (export only)
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
Description
This tool builds a Wall object from scratch or on top of any other shapebased or mesh-based object. A wall can be built without any base
object, in which case it behaves as a cubic volume, using length, width
and height properties. When built on top of an existing shape, a wall can
be based on:
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 has no effect.
A at 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 width property instead of height,
allowing you to build walls from space-like objects 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, nonmanifold solid.
Arch Wall
Menu location
Arch Wall
Workbenches
Arch
Default shortcut
WA
See also
Arch Structure
Contents
1 Arch Wall
2 Description
3 How to use
3.1 Drawing a wall
from scratch
3.2 Drawing a wall on
top of a selected
object
4 Options
5 Snapping
6 Properties
7 Scripting
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 in uence 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. Press the
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 rst 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 rst 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 speci cally 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
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
DATA
Force 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
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)
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 de ned, the wall will automatically take the value
of the floor height.
DATA
DATA
Normal: An extrusion direction for the wall. If set to (0,0,0), the extrusion direction is automatic.
Offset: This speci es the distance between the wall and its baseline. Works only if the Align
property is set to Right or Left.
DATA
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:
import FreeCAD, Draft, Arch
baseline = Draft.makeLine(FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,0,0))
Arch.makeWall(baseline,None,0.1,2)
Arch Structure
Description
This tool allows you to build structural elements such as columns or
beams, by specifying their width, length and height, or by basing them
on a 2D profile.
Arch Structure
Menu location
Arch Structure
Workbenches
Arch
Default shortcut
ST
See also
Arch Wall
Contents
1 Arch Structure
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
The above image shows a column based on a 2D base pro le, a column and a beam based on no pro le
(de ned by their height, length and width dimensions) and a metallic pro le 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)
2. Press the
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)
Height: The height of the structure (or the extrusion length when based on a pro le). If no height
is given, and the structure is inside a floor object with its height de ned, the structure will
automatically take the value of the floor height.
DATA
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 pro le 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
Description
Arch Rebar
The Rebar tool allows you to place reinforcing bars inside Arch Structure
objects. Rebar objects are based on 2D pro les such as sketches or
draft objects, that must be drawn on a face of a structure object. You
can then adjust the con guration of the rebars, such as the number and
diameter of the bars, or the offset distance between the two ends of the
structural element.
Menu location
Arch Rebar
Workbenches
Arch
Default shortcut
RB
See also
Arch Structure
Contents
1 Arch Rebar
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
The above image shows a structural object, where two sketches are drawn, de ning 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
10. Adjust the desired properties (your rebar might not appear immediately, if some of the properties
create an impossible situation, such as the bar diameter being 0, or the offset distances being bigger
than the length of the structural element)
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 speci ed, 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
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
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.
Rounding: A rounding value to be applied to the corners of the bars, expressed in times the
diameter.
DATA
DATA
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:
import FreeCAD, Arch, Sketcher, PArt
struct = Arch.makeStructure(1,1,3)
sketch = FreeCAD.ActiveDocument.addObject('Sketcher::SketchObject','Sketch')
sketch.Support = (struct,["Face6"])
sketch.addGeometry(Part.Line(App.Vector(-0.4,0.4,0),App.Vector(0.4,0.4,0)))
Arch.makeRebar(structure,sketch)
Arch Floor
Description
Arch Floor
The Arch Floor is a special type of FreeCAD group object that has a
couple of additional properties particularly suited for building oors.
Particularly, they have a height property, that its children objects ( walls
and structures) can use to set their own height automatically. They are
mostly used to organize your model.
How to use
Menu location
Options
FL
See also
Arch Building, Arch Site
Contents
After creating a oor, you can add more objects to it by drag and
dropping them in the Tree View or by using the
Arch Add tool
1 Arch Floor
You can remove objects from a oor by drag and dropping them
out of it the Tree View or by using the
Arch Remove tool
3 How to use
2 Description
4 Options
Properties
DATA
5 Properties
6 Scripting
Scripting
The Floor tool can by used in macros and from the python console by using the following function:
makeFloor ([objectslist])
creates a floor including the objects from the given list.
Example:
import Arch
Arch.makeFloor()
Arch Building
Description
Arch Building
How to use
Arch
Menu location
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
Default shortcut
BU
See also
Arch Floor, Arch Site
Contents
1 Arch Building
2 Description
3 How to use
4 Options
5 Scripting
The Building tool can by used in macros and from the python console by
using the following function:
makeBuilding ([objectslist])
creates a building including the objects from the given list.
Example:
import Arch
Arch.makeBuilding()
Arch Site
Description
Arch Site
Arch Site
Workbenches
How to use
Arch
Menu location
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
Default shortcut
SI
See also
Arch Floor, Arch Building
Contents
1 Arch Site
2 Description
Scripting
3 How to use
The Site tool can by used in macros and from the python console by
using the following function:
5 Scripting
makeSite ([objectslist])
creates a site including the objects from the given list.
Example:
import Arch
Arch.makeSite()
4 Options
Arch Window
Arch Window
Description
The Window is a base object for all kinds of "embeddable" objects, such
as windows, doors, etc... It is designed to be either independent, or
"hosted" inside another component such as a wall. It has its own
geometry, that can be made of several solid components (the window
frame, or inner panels for example), and also de nes a volume to be
subtracted to host objects, in order to create an opening.
Menu location
Default shortcut
The window tool features several presets, 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. But windows can also be
created fro scratch, by drawing a base 2D object first.
Arch Window
Workbenches
Arch
WI
See also
Arch Wall
Contents
1 Arch Window
2 Description
3 How to use
3.1 Using a preset
3.2 Creating from
scratch
4 Presets
5 Building components
6 Options
7 Doors
8 Properties
9 Scripting
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. Optionally, select an Arch object. If no object is selected, the window will be inserted in the object
under the mouse when placing the window.
2. Press the
7. Press the
8. Enter Edit mode by double-clicking the window in the tree view, to adjust the window components
Presets
The following presets are available:
W2
HEIGHT
H1
H2
O2
H3
W1
O1
WIDTH
Glass door
W2
HEIGHT
H1
O2
W1
O1
WIDTH
Simple door
W2
W1
HEIGHT
H1
H2
O2
O1
WIDTH
Double-opening window
HEIGHT
H1
W1
O1
Fixed window
WIDTH
W2
W1
HEIGHT
H1
H2
O2
O1
WIDTH
Single-opening window
W2
W1
O2
O1
HEIGHT
H1
H2
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 extruded, then
the smaller ones are subtracted from the biggest one. You can access, create, modify and delete
components of a window in edit mode (double-click the window in the Tree view). The components have the
following properties:
Name: A name for the component
Type: The type of component. Can be "Frame", "Glass panel" or "Solid panel"
Wires: A comma-separated list of wires the component is based on
Thickness: The extrusion thickness of the component
Offset: The distance between the component and its base 2D wire(s)
Options
If the Auto-includecheckbox on the Window creation task panel is unchecked, the window won't be
inserted into any host object on creation.
Add a selected window to a wall by selecting both, then pressing the
Remove a selected window from a wall by selecting the window, then pressing the
button.
Arch Remove
When using presets, it is often convenient to turn the "Near" Draft Snap on, so you can snap your
window to an existing face.
Doors
Doors can be made easily with the window tool, you only need to draw the base of the inner wire touching
the exterior wire like in the image below.
Properties
DATA
Window Parts: A list of strings (5 strings per component, setting the component options above)
Scripting
The Window tool can by used in macros and from the python console by using the following function:
makeWindow (obj,[name])
creates a window based on the given object
Example:
import Draft, Arch
rect = Draft.makeRectangle(length=2,height=4)
Arch.makeWindow(rect)
Arch SectionPlane
Description
This tool places in the current Document a section plane gizmo, which
de nes a section or view plane. The gizmo take his placement according
to the current Draft Working Plane and can be relocated and reoriented
by moving and rotating it, until it describes the 2D view you want to
obtain. The Section plane object will only consider objects that were
selected when it got created. Objects can later be added or removed
from a SectionPlane object with the Arch Add and Arch Remove tools.
Upon creation, SectionPlane objects also insert a view of themselves
into the active Drawing page, or create a new page if none exist. You
can also add views of Section planes directly in the document, by using
the Draft Shape2DView tool with a section plane selected.
Arch SectionPlane
Menu location
Arch -> Section Plane
Workbenches
Arch
Default shortcut
SP
See also
None
Contents
1 Arch SectionPlane
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
How to use
1. Set the Draft Working Plane
2. Select objects you want to be included in your section view
3. Press the
Options
With a section plane object selected, use the Draft Shape2DView tool to create a shape object
representing the section view in the document
Create additional views of a section plane by selecting it, then using the Draft Drawing tool
Properties
VIEW
Display Size: The size of the section plane gizmo in the 3D view
Scripting
The Section Plane tool can by used in macros and from the python console by using the following function:
makeSectionPlane ([objectslist])
Creates a Section plane objects including the given objects.
Example:
import FreeCAD, Draft, Arch
trace = Draft.makeLine(FreeCAD.Vector (0, 0, 0),FreeCAD.Vector (2, 2, 0))
wall = Arch.makeWall(trace,width=0.1,height=1,align="Center")
Arch.makeSectionPlane([wall])
Arch Axis
Description
The Axis tool allows you to places an axes system in the current
document. The distance and the angle between axes is customizable, as
well as the numbering style. The axes serve mainly as references to
snap objects onto, but can also be used together with structures to
create parametric arrays of beams or columns.
Arch Axis
Menu location
Arch -> Axis
Workbenches
Arch
Default shortcut
AX
See also
None
Contents
1 Arch Axis
2 Description
3 How to use
4 Options
5 Structural systems
6 Properties
7 Scripting
How to use
1. Press the
Options
Each axis in an axes system has its own distance and angle in relation to the previous axis. This
allows to do very complex systems such as non-orthogonal systems, polar systems or any kind of
non-uniform system.
Axes length, size of the bubbles and numbering styles are customizable directly via the axes system's
properties
Structural systems
The main use of axes systems is simply to give you reference lines to snap to, but they can also be used to
automatically build structural arrays, such as columns grids and beam layouts:
To obtain that result, one or more axes systems must be added to a structural element, turning it into an
array. If one axes system is added, the element is copied once on each line of the system, like the beams
on the image above. If two systems are added, the element is copied once on each intersection of the two
systems, like the columns on the image above. The same axes systems can of course be used in several
structural objects.
1. Create an Arch Structure object
5. By entering the edit mode of the structure object (double-clicking it in the tree view), you can add or
remove axes systems from it.
Properties
DATA
VIEW
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
Arch Roof
Description
The Roof tool allows you to create a sloped roof from a selected wire.
The created roof object is parametric, keeping its relationship with the
base object. Please note that this tool is still in development, and might
fail with very complex shapes. The principle is that each edge is seen
allotting a profile of roof (slope, width, overhang, thickness).
Menu location
Arch Roof
Workbenches
Arch
Default shortcut
RF
See also
None
Contents
1 Arch Roof
2 Description
3 How to use
4 Properties
5 Scripting
How to use
1. Create a wire with following the conterclockwise direction and select it.
2. Press the
3. The default roof object could have a strange shape, it's because the tool have not all the needed
informations.
4. 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.
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 de ned 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
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 de ne 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:
Arch Space
Description
The Space tool allows you to de ne an empty volume, either by basing it
on a solid shape, or by de ning its boundaries, or a mix of both. If it is
based solely on boundaries, the volume is calculated by starting from
the bounding box of all the given boundaries, and subtracting the
spaces behind each boundary. The space object always de nes a solid
volume. The oor area of a space object, calculated by intersecting a
horizontal plane at the center of mass of the space volume, can also be
displayed, by setting the display mode of the space object to "detailed".
Arch Space
Menu location
Arch Space
Workbenches
Arch
Default shortcut
SP
See also
None
Contents
1 Arch Space
2 Description
3 How to use
4 Properties
5 Scripting
6 Limitations
In the above image, a space object is created from an existing solid object, then two wall faces are added
as boundaries, and the display mode is set to "detailed" to show the floor area.
How to use
1. Select an existing solid object, or faces on boundary objects
2. Press the
Properties
DATA
DATA
Scripting
The space tool can be used in python scripts and macros by using the following function:
makeSpace(objects)
Creates a space object from the given objects.
Objects can be one document object, in which case it becomes the base shape of the space object, or
a list of selection objects as returned by FreeCADGui.Selection.getSelectionEx(), or a list of tuples
(object, subobjectname).
Returns the newly created space object.
Example:
import FreeCAD, Arch, Part
b = Part.makeBox(2,2,2)
FreeCAD.ActiveDocument.addObject("Part::Feature","Box").Shape=b
sp = makeSpace([FreeCAD.ActiveDocument.Box])
After a space object is created, selected faces can be added to it with the following function:
import FreeCADGui
Arch.addSpaceBoundaries(sp, FreeCADGui.Selection.getSelectionEx())
Boundaries can also be removed with:
Arch.removeSpaceBoundaries(sp, FreeCADGui.Selection.getSelectionEx())
Limitations
Not available below FreeCAD version 0.14
The boundaries properties is currently not editable via GUI
See the forum announcement
Arch Stairs
Description
The stairs tool allows you to build automatically several types of stairs.
At the moment, only straight stairs (with or without a central landing)
are supported. Stairs can be built from scratch, or from a straight line, in
which case the stairs follow the line. If the line is not horizontal but has
a vertical inclination, the stairs will also follow its slope.
See the Stairs entry in wikipedia for a de nition of the different terms
used to describe parts of stairs.
Arch Stairs
Menu location
Arch Stairs
Workbenches
Arch
Default shortcut
SR
See also
None
Contents
1 Arch Stairs
2 Description
3 How to use
4 Properties
5 Scripting
6 Limitations
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
2. Adjust the desired properties. Some parts of the stairs, such as the structure, might not appear
immediately, if any of the properties makes it impossible, such as a structure thickness of 0.
Properties
Base
DATA
DATA
DATA
Height: The total height of these stairs, if not based on a baseline, or the baseline is horizontal.
DATA
DATA
DATA
DATA
DATA
DATA
DATA
Steps
Structure
DATA
DATA
Stringer Offset: The offset between the border of the stairs and the structure.
DATA
DATA
DATA
DATA
Scripting
Stairs can be created from python scripts and macros by using the following function:
makeStairs([base], [length], [width], [height], [steps])
Creates a stairs object with the given attributes.
Returns the new stairs object.
Example:
import Arch
makeStairs(length=5, width=1.2, height=3, steps=14)
Limitations
Not available before FreeCAD version 0.14
Only straight stairs are available at the moment
See the forum entry for circle stairs.
See the forum announcement.
Arch Panel
Description
This tool allows you to build all kinds of panel-like elements, typically
for panel constructions like the WikiHouse project, but also for all kinds
of objects that are based on a flat profile.
Arch Panel
Menu location
Arch Panel
Workbenches
Arch
Default shortcut
P,A
See also
Arch Structure
Contents
1 Arch Panel
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
7 Limitations
The above image shows a series of panel objects, simply made from imported 2D contours from a DXF le.
They can then be rotated and assembled to create structures.
How to use
1. Select a 2D shape (draft object, face or sketch)
2. Press the
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
DATA
Scripting
The Panel tool can by used in macros and from the python console by using the following function:
makePanel ([obj],[thickness],[name])
Example:
import Arch,Draft
base = Draft.makeRectangle(500,200)
Arch.makePanel(base,36)
Limitations
There is currently no automatic system to produce 2D cutting sheets from panel objects, but such
feature is in the plans and will be added in the future.
This tool is not available in FreeCAD versions prior to 0.15
Arch Frame
Description
The Frame tool is used to build all kinds of frame objects based on a
pro le and a layout. The pro le is extruded along the edges of the
layout, which can be any 2D object such as a sketch, or a draft object. It
is especially useful to create railings, or frame walls. Frame objects can
then easily be turned into wall or structure objects.
Arch Frame
Menu location
Arch -> Frame
Workbenches
Arch
Default shortcut
FR
See also
None
Contents
1 Arch Frame
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
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 pro le object, for example with the Draft Workbench or the Sketcher
Workbench
2. Select the layout object first, then, with CTRL pressed, select the profile object
3. Press the
Options
The frame object can be placed at a certain distance from the layout object, by setting its Offset
property
The pro le 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
DATA
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
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 pro le object
(an extrudable 2D object containing faces or closed wires)
Returns the new frame object, or None if the operation failed.
Example:
import Draft, Arch
layout = Draft.makeLine(FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,0,0))
profile = Draft.makeCircle(.2)
Arch.makeFrame(layout,profile)
Arch Equipment
Description
The Equipment tool offers you a simple and convenient way to insert
non-structural, standalone elements such as pieces of furniture, hidrosanitary equipments or electrical appliances to your projects.
Equipments can be based on a shape or a mesh, allowing to use either
precise solid models, or more easily available mesh models that you can
find on the internet.
Arch Equipment
Menu location
Arch Equipment
Workbenches
Arch
Default shortcut
EQ
See also
None
Contents
1 Arch Equipment
2 Description
3 How to use
4 Properties
5 Scripting
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 at, lled, orthogonal projections
(top, front and side), which can then be used in 2D projections.
How to use
1. Select a Part shape or Mesh object
2. Press the
Properties
DATA
DATA
Url: An URL of the product page where more information about this equipment can be found.
Scripting
The Equipment tool can by used in macros and from the python console by using the following function:
makeEquipment ( baseObject )
Creates an equipment object from a base object (Mesh or Part)
Returns the new equipment object, or None if the operation failed.
Example:
import Part, Arch
box = Part.makeBox(2,2,2)
base = FreeCAD.ActiveDocument.addObject("Part::Feature","Box")
base.Shape = box
Arch.makeEquipment(base)
Arch CutPlane
Description
Arch CutPlane
The Cut Plane tool allows you to cut an Arch object according to a plan:
You can cut an Arch object with the selected face, normal or
opposite of the face plan.
This add a substraction component CutVolume to the Arch object
Menu location
Arch Cut Plane
Workbenches
Arch
Default shortcut
None
See also
Arch Remove
Contents
1 Arch CutPlane
2 Description
3 How to use
4 Scripting
In the above image, two Arch Structure are cut with respective plane.
How to use
1. Select the object to be cut, then the face (the face must be the last one you selected)
2. Press the
3. Choose if the object is cut behind the normale face or front of the normale face
4. Click the Ok button
Scripting
The CutPlane tool can by used in macros and from the python console by using the following function:
cutComponentwithPlane (archObject,face,faceSide)
archObject is the object to cut
face is the face of an object that come the plan from
faceSide is the side of the face to cut. 0 = Behind, 1 = Front
Arch Add
Description
Arch Add
Menu location
Arch -> Add
Workbenches
Arch
Default shortcut
None
See also
Arch Remove
Contents
1 Arch Add
2 Description
3 How to use
4 Scripting
How to use
1. Select the object(s) to be added, then the "host" object (the host object must be the last one you
selected)
2. Press the
Add button
Scripting
The Add tool can by used in macros and from the python console by using the following function:
addComponents (objectsList,hostObject)
Adds the given object or the objects from the given list as components to the given host Object. Use
this for example to add windows to a wall, or to add walls to a floor.
Returns nothing.
Example:
import FreeCAD, Arch, Draft, Part
line = Draft.makeWire([FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,2,0)])
wall = Arch.makeWall(line)
box = Part.makeBox(1,1,1)
Arch.addComponents(box,wall)
Arch Remove
Description
Arch Remove
Menu location
Arch -> Remove
Workbenches
Arch
Default shortcut
None
See also
Arch Add
Contents
1 Arch Remove
2 Description
3 How to use
4 Scripting
How to use
1. Select a subcomponent inside an Arch object, or:
2. Select object(s) to be subtracted, then the Arch component from which they must be subtracted (the
arch component must be the last thing you selected)
3. Press the
Scripting
Remove button
The Remove tool can by used in macros and from the python console by using the following function:
removeComponents (objectsList,[hostObject])
removes the given component or the components from the given list from their parents. If a host
object is specified, this function will try adding the components as holes to the host object instead.
Example:
import FreeCAD, Arch, Draft, Part
line = Draft.makeWire([FreeCAD.Vector(0,0,0),FreeCAD.Vector(2,2,0)])
wall = Arch.makeWall(line)
box = Part.makeBox(1,1,1)
Arch.addComponents(box,wall)
Arch.removeComponents(box)
Arch Survey
Description
The survey tool enters a special surveying mode, which allows you to
quickly grab measures and information from a model, and transfer that
information to other applications. Once you are in Survey mode, clicking
on different subelements of 3D objects gathers the following
information, depending on what you click:
If you click on an edge, you get its length
If you click on a vertex, you get its height (coordinate on the Z
axis)
If you click on a face, you get its area
If you double-click anything, therefore select the whole object,
you get its volume
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
Arch Survey
Menu location
Arch Survey
Workbenches
Arch
Default shortcut
None
See also
FCInfo (macro)
Contents
1 Arch Survey
2 Description
3 How to use
4 Scripting
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
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
Tutorial
Class
Modeling
Level
Intermediate
Time to complete
Author
Yorik
FreeCAD version
0.14
Example File(s)
Contents
1 Tutorial
2 Introduction
3 Typical workflows
4 Preparation
5 Building the walls
6 Raising the structure
7 Subtractions
8 Making the roofs
9 Floors, stairs and chimney
9.1 The chimney
9.2 The floors
9.3 The stairs
10 Doors and windows
10.1 Using presets
10.2 Organizing your
model
10.3 Creating custom
windows
10.4 Editing windows
11 Working without 2D
support
12 Edits and fixes
13 Output
13.1 Preparations
13.2 Exporting to IFC
and other
applications
13.3 Rendering
13.4 2D drawings
13.5 Quantities
extraction
14 Conclusion
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 work ow inside FreeCAD. As it is still under
development, don't expect to nd 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 bene ts 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 nd
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 work ow,
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 de ne in other BIM applications, like a oor 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 ngertips. 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 meshbased 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 les. You can usually successfully import 2D les, 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 Material system, able to de ne 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 les, quite reliably, provided IfcOpenShell is
installed on your system, but exporting is still not of cially 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 of cially 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".
Typical workflows
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 on the above site to
download, but it's free, or grab directly a dxf version here) as a base to build our model. So the rst thing
you'll want to do is to download the le, unzip it, and open the DWG le 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 les directly. But since these les 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 le can be opened quite ef ciently 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 le looks after being opened in FreeCAD. I also changed the thickness of the walls (the
contents of the "muros" group), and ipped 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 les, since when importing DWG les, they are simpl
converted to DXF rst), 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 les, but don't have speci c properties,
like AutoCAD layers, that apply to their contents. But they can be placed inside other groups, which is very
handy. The rst 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.
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
xed. Fortunately, all Arch objects have a great feature: you can add one to another. Doing that will unite
their geometries, but they are still editable independently after. To add one of our crossing walls to the
other, just select one, CTRL + select the other, and press the Arch Add tool:
On the left is are the two intersecting walls, on the right the result after adding one to the other.
An important note about parametric objects
Something is important to consider already. As you can see, in FreeCAD, everything is parametric: Our new
"united" wall is made from two walls, each based on a baseline. When you expand them in the tree view,
you can see all that chain of dependencies. As you can imagine, this little game can quickly become very
complex. Furthermore, if you already know how to work with the sketcher, you might have wanted to draw
the baselines with constrained sketches. This whole complexity has a cost: it raises exponentially the
number of calculations that FreeCAD has to perform to keep your model geometry up to date. So, think
about it, don't add unnecessary complexity when you don't need it. Keep a good balance between simple
and complex objects, and keep these for the cases where you really need them.
For example, I could have drawn all my baselines above without caring about what crosses what, and x
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-onface" 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 oor 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 Move button, select a rst 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
de nes 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 Move 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.
On the image above, you can see two columns that are still as they were in the DWG le, 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 pro le 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 pro le 90 degrees up, in the right
position to be extruded. To do that, we must rst 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 pro le, 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 pro le, 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 pro le a bit closer to the model (set the working plane to XY if
needed), and extrude it. This can be done either with the Part Extrude tool, or Draft Trimex, which also has
the special hidden power to extrude faces. Make sure your extrusion is larger than all the walls it will be
subtracted from, to avoid face-on-face situations:
Now, here comes into action the contrary of the Arch Add tool: Arch Remove. As you might have guessed, it
also makes an object a child of another, but its shape is subtracted from the host object, instead of being
united. So now things are simple: Select the volume to subtract (I renamed it as "Roof volume to subtract"
in the tree view so it is easy to spot), CTRL + select a wall, and press the Arch Remove button. You'll see
that, after the subtraction happened, the volume to subtract disappeared from both the 3D view and the tree
view. That is because it has been marked as child of the wall, and "swallowed" by that wall. Select the wall,
expand it in the tree view, there is our volume.
Now, select the volume in the tree vieew, CTRL + select the next wall, press Arch Remove. Repeat for the
next walls until you have everything properly cut:
Remember that for both Arch Add and Arch Remove, the order you select the objects is important. The host
is always the last one, like in "Remove X from Y" or "Add X to Y"
A note about additions and subtractions
Arch objects that support such additions and subtractions (all of them except the "visual" helper objects
such as the axes) keep track of such objects by having two properties, respectively "Additions" and
"Subtractions", that contains a list of links to other objects to be subtracted or added. A same object can be
in thr lists of several other objects, as it is the case of our subtraction volume here. Each of the fathers will
want to swallow it in the tree view, though, so it will usually "live" in the last one. But you can always edit
those lists for any object, by double-clicking it in the tree view, which in FreeCAD enters edit mode. Pressing
the escape key exits edit mode.
Then, we must repeat the rotation operation above, to rotate the objects in a vertical position, then move
them at their correct places, and copy some of them that will need to be extruded twice, with the Draft Move
tool, with the ALT key pressed, which creates copies instead of moving the actual object. I also added two
more profiles for the side walls of the bathroom opening.
When everything is in place, it's just a matter of using the Draft Trimex tool to extrude, then convert them to
Arch Structure objects.
After that, we can see some problems arising: two of the columns on the right are too short (they should go
up to the roof), and there is a gap between the slab and the walls of the studio on the far right (the 2.60
level symbol on the section view was obviously wrong). Thanks to the parametric objects, all this is very
easy to solve: For the columns, just change their height to 6m, sh 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 xed, there is a small slab in the bathroom, that intersects some walls. Let's x
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 Move 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 oors are not well represented in the base drawings. When looking at the sections, you cannot know
where and how thick the oor slabs are. So I will suppose that the walls are sitting on top of foundation
blocks, at level 0.00, and that there are oor slabs, also sitting on those blocks, 15cm thick. So the oor
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 at
oor 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
rst 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:
Don't forget also to cut the column that crosses the stairs, because in BIM it's always bad to have
intersecting objects. We are building like in the real world, remember, where solid objects cannot intersect.
Here, I didn't want to subtract the column directly from the stairs (otherwise the column object would be
swallowed by the stairs object in the tree view, and I didn't like that), so I took the face on which the column
was built, and extruded it again. This new extrusion was then subtracted from the stairs.
Right! All the hard work is now done, let's go on with the very hard work!
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 Move 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 Move 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) oor, 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 oor objects to Wireframe (or use the Draft ToggleDisplayMode tool) so we can still snap to
them, but we can see the plan view underneath. But you can also turn off the oors completely, then place
your doors at level 0, then raise them of 15cm with the Draft Move 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 x: Remove the window from the
"Subtraction" group of the host wall in edit mode, as we saw above, then add it to the "Subtraction" group
of the correct wall, by the same method, or, simply, using the Arch Remove tool.
A little work later, all our doors are there:
After a closer look at the elevation view, I now detected another error: The top of the brick walls is not as
2.60m, but 17.5cm lower, that is, 2.425m. Fortunately, windows based on presets have a facility: You can alter
their general dimensions (width and height) from their properties. So let's change their height to 2.425 0.15, that is, 2.275. The second window, as it is a clone of the rst 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.
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 con guration: 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 rst. 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 x 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 sh 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 x 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.
wish!
One thing we can already do: duplicate the complicated stairs window with the Draft Move tool, because it is
equal on both sides:
Note that here, I preferred to duplicate with the Draft Move 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
nal 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 de nition,
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 dif culties
with overlapping wires, that's why I preferred to keep them separated like this:
We still need some corner piece there. A little useful trick with the Draft SelectPlane tool, if you have a face
selected when you press the button, the working plane matches this face (at least its position, and if the
face is rectangular, it also tries to match its axes). This is useful to draw 2D objects directly on the model,
such as here, we can draw a rectangle to be extruded directly at its correct position:
Then let's do the two remaining pieces. One is easy, it is a copy of what's on the other side, so we can
simply use the 2D drawing:
The other one is a bit tricky, by looking at the pictures, we see that it has many vertical divisions, like the
stairs windows. By chance (or very good design from Vilanova Artigas), the width of our window, of 4.50m, is
exactly the same as the stairs window, so we can use the exact same division: 15 pieces of 30cm. Here I
used the Draft Array tool to copy over the two lines 15 times,and drew rectangles on top of them:
Once this is done, we can create our window with the same method we already know. Another small useful
trick, in case you haven't found it yourself already: When editing a window, if you change the name of a
component, it actually creates a duplicate of it. So to create the 15 inner glass panels, instead of clicking 15
times the "add" button and ll 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:
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 oors. 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 x 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 nal
shape. When reimporting that STEP le into FreeCAD, you will get a model that has no relationship, and a
much smaller le size. Think of it as an "output" le, 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
les. This is still a work in progress in FreeCAD. IFC format is already supported, and importing IFC les 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 les, by adding an Arch Building to your le, 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 le
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 oor 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 nal 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 speci c 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, lling them according to what you
specify. This, provided that you organized your model well, allows you to easily retrieve individual values:
Note that the spreadsheet workbench is still very new, and like everything very new, still contains many
bugs and limitations. But for simple summaries like this, it already works well. The resulting spreadsheet
can then be exported to a CSV file, which can be imported in any spreadsheet application.
The survey mode
Another way to survey your model and extract values, is to use the Arch Survey mode. In this mode, you can
click on points, edges, faces or double-click to select whole objects, and you get altitude, length, area or
volume values, shown on the model, printed on the FreeCAD output window, and copied to the clipboard, so
you can easily pick and paste values in another opened application
Conclusion
I hope this gives you a good overview of the available tools, be sure to refer to the Arch Workbench and
Draft Workbench documentation for more (there are more tools that I didn't mention here), and, more
generally, to the rest of the FreeCAD documentation. Pay a visit to the forum too, many problems can
usually be solved there in no time, and follow my blog for news about he Arch workbench development.
The file created during this tutorial can be found here
Drawing Workbench
(Redirected from Drawing Workbench)
The Drawing module allows you to put your 3D work on paper. That is, to put views of your models in a 2D window and to
insert that window in a drawing, for example a sheet with a border, a title and your logo and nally print that sheet. The
Drawing module is currently under construction and more or less a technology preview!
Contents
1 GUI Tools
2 Scripting
2.1 Simple example
2.2 The parametric way
2.3 Accessing the bits and pieces
2.4 General Dimensioning and Tolerancing
3 Templates
4 Extending the Drawing Module
5 Tutorials
GUI Tools
These are tools for creating, configuring and exporting 2D drawing sheets
Open scalable vector graphic: Opens a drawing sheet previously saved as an SVG file
New A3 landscape drawing: Creates a new drawing sheet from FreeCAD's default A3 template
Insert a view: Inserts a view of the selected object in the active drawing sheet
Annotation: Adds an annotation to the current drawing sheet
Clip: Adds a clip group to the current drawing sheet
Open Browser: Opens a preview of the current sheet in the browser
Ortho Views: Automatically creates orthographic views of an object on the current drawing sheet
Symbol: Adds the contents of a SVG file as a symbol on the current drawing sheet
Draft View: Inserts a special Draft view of the selected object in the current drawing sheet
Spreadsheet View: Inserts a view of a selected spreadsheet in the current drawing sheet
Save sheet: Saves the current sheet as a SVG file
Project Shape: Creates a projection of the selected object (Source) in the 3D view. .
Note The Draft View tool is used mainly 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) work ow 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 Macro_CartoucheFC leaf FreeCAD A3_Landscape.
Simple example
First of all you need the Part and the Drawing module:
import FreeCAD, Part, Drawing
Create a small sample part
Part.show(Part.makeBox(100,100,100).cut(Part.makeCylinder(80,100)).cut(Part.makeBox(90,40,100)).cut(Part.makeBox(20,85,100)))
Direct projection. The G0 means hard edge, the G1 is tangent continuous.
Shape = App.ActiveDocument.Shape.Shape
[visibleG0,visibleG1,hiddenG0,hiddenG1] = Drawing.project(Shape)
print "visible edges:", len(visibleG0.Edges)
print "hidden edges:", len(hiddenG0.Edges)
Everything was projected on the Z-plane:
print "Bnd Box shape: X=",Shape.BoundBox.XLength," Y=",Shape.BoundBox.YLength,"
Z=",Shape.BoundBox.ZLength
print "Bnd Box project: X=",visibleG0.BoundBox.XLength," Y=",visibleG0.BoundBox.YLength,"
Z=",visibleG0.BoundBox.ZLength
Different projection vector
[visibleG0,visibleG1,hiddenG0,hiddenG1] = Drawing.project(Shape,App.Vector(1,1,1))
Project to SVG
resultSVG = Drawing.projectToSVG(Shape,App.Vector(1,1,1))
print resultSVG
App.ActiveDocument.addObject("Part::Box","Box")
App.ActiveDocument.Box.Length=100.00
App.ActiveDocument.Box.Width=100.00
App.ActiveDocument.Box.Height=100.00
App.ActiveDocument.addObject("Part::Box","Box1")
App.ActiveDocument.Box1.Length=90.00
App.ActiveDocument.Box1.Width=40.00
App.ActiveDocument.Box1.Height=100.00
App.ActiveDocument.addObject("Part::Box","Box2")
App.ActiveDocument.Box2.Length=20.00
App.ActiveDocument.Box2.Width=85.00
App.ActiveDocument.Box2.Height=100.00
App.ActiveDocument.addObject("Part::Cylinder","Cylinder")
App.ActiveDocument.Cylinder.Radius=80.00
App.ActiveDocument.Cylinder.Height=100.00
App.ActiveDocument.Cylinder.Angle=360.00
# Fuse two boxes and the cylinder
App.ActiveDocument.addObject("Part::Fuse","Fusion")
App.ActiveDocument.Fusion.Base = App.ActiveDocument.Cylinder
App.ActiveDocument.Fusion.Tool = App.ActiveDocument.Box1
App.ActiveDocument.addObject("Part::Fuse","Fusion1")
App.ActiveDocument.Fusion1.Base = App.ActiveDocument.Box2
App.ActiveDocument.Fusion1.Tool = App.ActiveDocument.Fusion
# Cut the fused shapes from the first box
App.ActiveDocument.addObject("Part::Cut","Shape")
App.ActiveDocument.Shape.Base = App.ActiveDocument.Box
App.ActiveDocument.Shape.Tool = App.ActiveDocument.Fusion1
# Hide all the intermediate shapes
Gui.ActiveDocument.Box.Visibility=False
Gui.ActiveDocument.Box1.Visibility=False
Gui.ActiveDocument.Box2.Visibility=False
Gui.ActiveDocument.Cylinder.Visibility=False
Gui.ActiveDocument.Fusion.Visibility=False
Gui.ActiveDocument.Fusion1.Visibility=False
Insert a Page object and assign a template
App.ActiveDocument.addObject('Drawing::FeaturePage','Page')
App.ActiveDocument.Page.Template = App.getResourceDir()+'Mod/Drawing/Templates/A3_Landscape.svg'
Create a view on the "Shape" object, define the position and scale and assign it to a Page
App.ActiveDocument.addObject('Drawing::FeatureViewPart','View')
App.ActiveDocument.View.Source = App.ActiveDocument.Shape
App.ActiveDocument.View.Direction = (0.0,0.0,1.0)
App.ActiveDocument.View.X = 10.0
App.ActiveDocument.View.Y = 10.0
App.ActiveDocument.Page.addObject(App.ActiveDocument.View)
Create a second view on the same object but this time the view will be rotated by 90 degrees.
App.ActiveDocument.addObject('Drawing::FeatureViewPart','ViewRot')
App.ActiveDocument.ViewRot.Source = App.ActiveDocument.Shape
App.ActiveDocument.ViewRot.Direction = (0.0,0.0,1.0)
App.ActiveDocument.ViewRot.X = 290.0
App.ActiveDocument.ViewRot.Y = 30.0
App.ActiveDocument.ViewRot.Scale = 1.0
App.ActiveDocument.ViewRot.Rotation = 90.0
App.ActiveDocument.Page.addObject(App.ActiveDocument.ViewRot)
Create a third view on the same object but with an isometric view direction. The hidden lines are activated too.
App.ActiveDocument.addObject('Drawing::FeatureViewPart','ViewIso')
App.ActiveDocument.ViewIso.Source = App.ActiveDocument.Shape
App.ActiveDocument.ViewIso.Direction = (1.0,1.0,1.0)
App.ActiveDocument.ViewIso.X = 335.0
App.ActiveDocument.ViewIso.Y = 140.0
App.ActiveDocument.ViewIso.ShowHiddenLines = True
App.ActiveDocument.Page.addObject(App.ActiveDocument.ViewIso)
Change something and update. The update process changes the view and the page.
App.ActiveDocument.View.X = 30.0
App.ActiveDocument.View.Y = 30.0
App.ActiveDocument.View.Scale = 1.5
App.ActiveDocument.recompute()
Get the whole result page (it's a file in the document's temporary directory, only read permission)
print "Resulting SVG document: ",App.ActiveDocument.Page.PageResult
file = open(App.ActiveDocument.Page.PageResult,"r")
print "Result page is ",len(file.readlines())," lines long"
Important: free the file!
del file
Insert a view with your own content:
App.ActiveDocument.addObject('Drawing::FeatureView','ViewSelf')
App.ActiveDocument.ViewSelf.ViewResult = """<g id="ViewSelf"
stroke="rgb(0, 0, 0)"
stroke-width="0.35"
stroke-linecap="butt"
stroke-linejoin="miter"
transform="translate(30,30)"
fill="#00cc00"
>
<ellipse cx="40" cy="40" rx="30" ry="15"/>
</g>"""
App.ActiveDocument.Page.addObject(App.ActiveDocument.ViewSelf)
App.ActiveDocument.recompute()
del ViewSVG
That leads to the following result:
Templates
FreeCAD comes bundled with a set of default templates, but you can find more on the Drawing templates page.
Tutorials
Drawing tutorial
Drawing Landscape A3
This tool creates a new drawing sheet from already installed templates.
Currently, even though the menu and the toolbar allow for A0 to A4
landscape formats, only an A3 Landscape template is available.
Drawing
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.
Menu location
Workbenches
Drawing, Complete
Default shortcut
none
See also
None
Contents
1 Drawing Landscape A3
2 Options
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
Menu location
Drawing Insert view in
drawing
Workbenches
Drawing, Complete
Default shortcut
none
See also
Drawing Landscape A3
Contents
1 Drawing View
2 How to use
3 Modify an existing view
4 Drawing View Wizard
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
Drawing Annotation
Description
This command allows you to place a block of text on a Drawing page.
Drawing
Annotation
Menu location
How to use
Drawing Annotation
Workbenches
Drawing, Complete
3. Press the
4. Adjust the desired properties, such as text contents, font, size and
position.
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.
Default shortcut
none
See also
None
Contents
1 Drawing Annotation
2 Description
3 How to use
4 Limitations
Drawing Clip
Description
Drawing Clip
Drawing Clip
Workbenches
Drawing, Complete
How to use
1. Create a Drawing page
2. Refresh the view if a Drawing view wasn't opened
3. Press the
Menu location
Default shortcut
none
See also
None
Options
A property allows you to show or hide the clipping rectangle itself.
Limitations
Contents
1 Drawing Clip
2 Description
3 How to use
4 Options
5 Limitations
Clipping objects are not displayed properly by the internal Qt-based Svg viewer, but the Open Browser
command shows them correctly.
Drawing Openbrowser
Description
This command allows you to display a selected Drawing page using
FreeCAD's internal web browser. The normal Drawing page viewer of
FreeCAD is based on Qt's built-in SVG rendering module, which only
supports a tiny subset of the full SVG speci cation. As a result, some
more advanced SVG features, such as pattern lls or multiline texts are
not supported by this viewer. The FreeCAD internal web browser,
however, is built on webkit, which is one of the best SVG renderers
available, and will correctly render your page with all its features.
Menu location
Drawing Open Browser
Workbenches
Drawing, Complete
Default shortcut
How to use
none
Drawing
Openbrowser
Limitations
See also
None
Contents
1 Drawing Openbrowser
2 Description
3 How to use
4 Limitations
Drawing Symbol
Description
Drawing Symbol
Menu location
Drawing Symbol
Workbenches
Drawing, Complete
How to use
Default shortcut
none
See also
3. Press the
None
Contents
1 Drawing Symbol
2 Description
3 How to use
Drawing DraftView
(Redirected from Drawing DraftView)
Description
Draft Drawing
This tool allows you to put selected objects on a svg Drawing sheet. If no
sheet exists in the document, a default one will be created. This tool
works similarly to the Drawing View tool, but is optimized for Draft
objects, and can render at 2D objects with a face lling. It can also
handle a couple of speci c Draft objects, such as dimensions and texts,
that the Drawing View tool cannot handle.
Menu location
Drafting Drawing
Workbenches
Draft, Arch
Default shortcut
None
See also
None
Contents
1 Draft Drawing
2 Description
3 How to use
4 Options
5 Properties
6 Scripting
How to use
1. Select the objects you wish to put on a drawing sheet
2. Press the
Options
Select objects you want to put on the drawing sheet. The tool will work best with at 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
Fill Style: For closed shapes, allows to specify one of the Default Draft ll styles, or use the shape
color.
DATA
DATA
Font Size: Allows you to specify the font size of texts and dimensions.
DATA
Line Width: Allows you to specify the line width of viewed objects.
Scripting
The Draft Drawing tool can by used in macros and from the python console by using the following function:
makeDrawingView (object,page)
Adds a view of the given object to the given page.
Returns the created view object.
Example:
import FreeCAD,Draft
obj = FreeCAD.ActiveDocument.ActiveObject
page = FreeCAD.ActiveDocument.Page
Draft.makeDrawingView(obj,page)
Drawing Save
This tool saves the current Drawing sheet as an SVG (scalable vector
graphics) le. Such a le can then be edited in a scalable vector
graphics program such as Inkscape.
SVG les are common and can be viewed in most modern browsers and
image viewers. It can be a useful way to share a design with people who
don't have FreeCAD installed on their PC.
Drawing Save
Menu location
Drawing Export page...
Workbenches
Drawing, Complete
Default shortcut
none
See also
Drawing Open SVG
Contents
1 Drawing Save
Drawing ProjectShape
32px Project Shape
Description
This tool creates a projection of the selected object (Source) in the 3D
view.
Menu location
Drawing Project shape
Workbenches
Drawing, Complete
Default shortcut
See also
Contents
1 32px Project Shape
2 Description
3 Usage
3.1 Edit an existing
projection
Usage
Label :
DATA
Placement :
Projection
Direction : defines the direction of the projection. This is the normal
vector of the projection plane. For example, to project the object onto the
xy plane, use (0,0,1). To reverse the projection, use negative values.
DATA
DATA
HCompound :
DATA
DATA
DATA
DATA
DATA
DATA
DATA
Rg NLine HCompound :
DATA
Rg NLine VCompound :
DATA
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 con gured in the FreeCAD Raytracing preferences.
Without any renderer installed, though, you are still able to export a scene le that can be used in any of those renderers
later, or on another machine.
The raytracing workbench works with templates, which are complete scene les for the given external renderer, including
lights and possibly additional geometry such as ground planes. These scene les 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.
Contents
1 Tools
1.1 Raytracing project tools
1.2 Utilities
2 Typical workflow
3 Creating a povray file manually
4 Scripting
4.1 Outputting render files
4.2 Creating a custom render object
5 Links
5.1 POVRay
5.2 Luxrender
5.3 Future possible renderers to implement
6 Templates
6.1 Povray
6.2 Luxrender
7 Exporting to Kerkythea
8 Links
Tools
Raytracing project tools
These are the main tools for exporting your 3D work to external renderers
New PovRay project: Insert new PovRay project in the document
New LuxRender project: Insert new LuxRender project in the document
Insert part: Insert a view of a Part in a raytracing project
Reset camera: Matches the camera position of a raytracing project to the current view
Export project: Exports a raytracing project to a scene file for rendering in an external renderer
Render: Renders a raytracing project with an external renderer
Utilities
These are helper tools to perform specific tasks manually
Export view to povray: Write the active 3D view with camera and all its content to a povray file
Export camera to povray: Export the camera position of the active 3D view in POV-Ray format to a file
Export part to povray: Write the selected Part (object) as a povray file
Typical workflow
1. Create or open a FreeCAD project, add some Part-based objects (meshes are currently not supported)
2. Create a Raytracing project (luxrender or povray)
3. Select the objects you wish to add to the raytracing project and add them to the project with the "Insert Part" tool
4. Export or render directly
You will be asked for a location to save the resulting *.pov file. After that you can open it in Povray and render:
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 de nition, and RaytracingGui.povViewCamera() and RaytracinGui.luxViewCamera() to get the current
point of view of the FreeCAD 3D window into povray or luxrender format.
Here is how to write a povray file from python, assuming your document contains a "Box" object:
import Raytracing,RaytracingGui
OutFile = open('C:/Documents and Settings/jriegel/Desktop/test.pov','w')
OutFile.write(open(App.getResourceDir()+'Mod/Raytracing/Templates/ProjectStd.pov').read())
OutFile.write(RaytracingGui.povViewCamera())
OutFile.write(Raytracing.getPartAsPovray('Box',App.activeDocument().Box.Shape,0.800000,0.800000,0.800000))
OutFile.close()
del OutFile
And the same for luxrender:
import Raytracing,RaytracingGui
OutFile = open('C:/Documents and Settings/jriegel/Desktop/test.lxs','w')
OutFile.write(open(App.getResourceDir()+'Mod/Raytracing/Templates/LuxClassic.lxs').read())
OutFile.write(RaytracingGui.luxViewCamera())
OutFile.write(Raytracing.getPartAsLux('Box',App.activeDocument().Box.Shape,0.800000,0.800000,0.800000))
OutFile.close()
del OutFile
Links
POVRay
http://www.spiritone.com/~english/cyclopedia/
http://www.povray.org/
http://en.wikipedia.org/wiki/POV-Ray
Luxrender
http://www.luxrender.net/
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 le 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 les (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 nd
further information and a list of applications able to produce .pov files.
When you have a .pov file ready, you need to open it with a text editor, and do two operations:
1. Strip out the camera information, because FreeCAD will place its own camera data. To do so, locate a text block like
this: camera { ... }, which describes the camera parameters, and delete it (or put "//" in front of each line to
comment them out).
2. Insert the following line somewhere: //RaytracingContent. This is where FreeCAD will insert its contents (camera
and objects data). You can, for example, put this line at the very end of the file.
Note that FreeCAD will also add some declarations, that you can use in your template, after the //RaytracingContent tag.
These are:
cam_location: the location of the camera
cam_look_at: the location of the target point of the camera
cam_sky: the up vector of the camera.
cam_angle: the angle of the camera
If you want, for example, to place a lamp above the camera, you can use this:
light_source {
cam_location + cam_angle * 100
color rgb <10, 10, 10>
}
Luxrender
Luxrender scene les (with extension.lxs) can either be single les, or a master .lxs le that includes world de nition
(.lxw), material de nition (.lxm) and geometry de nition (.lxo) les. You can work with both styles, but it is also easy to
transform a group of 4 les in a single .lxs le, by copying the contents of each .lxw, .lxm and .lxo le and pasting it at the
point where that file is inserted in the master .lxs file.
Luxrender scene les 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 les, beware that the nal .lxs exported by FreeCAD might be at a
different location than the template le, and therefore these les 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 le from blender, and wish to merge everything into one single le, you will need to perform
one step before exporting: By default, the luxrender exporter in blender exports all mesh geometry as separate .ply les,
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 de nition, before the geometry information, or at
the very end, just before the nal 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 le can de ne 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 le, 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 .objfiles
If your mesh-export resulted in errors (flip of normals, holes ...) you may try your luck with netfabb studio basic
Free for personal use, available for Windows, Linux and Mac OSX.
It has standard repair tools which will repair you model in most cases.
another good program for mesh analysing/repairing is Meshlab
Open Source, available for Windows, Linux and Mac OSX.
It has standard repair tools which will repair you model in most cases (fill holes, re-orient normals, etc.)
you can use "make compound" and then "make single copy" or you can fuse solids to group them before converting
to meshes
remember to set in Kerkythea an import-factor of 0.001 for obj-modeler, since Kerkythea expects the obj- le 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 do that each time you start Kerkythea
if importing multiple objects in Kerkythea you can use the "File > Merge" command in Kerkythea
Links
Render project
Raytracing tutorial
Robot Workbench
The robot workbench is a tool to simulate industrial grade 6-Axis Robots, like e.g. Kuka. You can do the following tasks:
set up a simulation environment with a robot and work pieces
create and fill up trajectories
decompose features of an CAD part to a trajectory
simulate the robot movement and reachability
export the trajectory to a robot program file
You can find an example here: Example files or try the Robot tutorial.
Contents
1 Tools
1.1 Robots
1.2 Trajectories
1.2.1 non parametric
1.2.2 parametric
2 Scripting
2.1 Basic robot stuff
2.2 Working with the document objects
2.3 Simulation
2.4 Exporting the trajectory
3 Tutorials
Tools
Here the principal commands you can use to create a robot set-up.
Robots
The tools to create and manage the 6-Axis robots
Create a robot: Insert a new robot into the scene
Simulate a trajectory: Opens the simulation dialog and let you simulate
Trajectories
Tools to creat and manipulate trajectories. There are two kinds, the parametric and non parametric ones.
non parametric
Create a trajectory: Insert a new robot into the scene
Set the default orientation: Set the orientation way-points gets created by default
Set the default speed parameter: set the defaults for way-point creation
Insert a waypoint: Insert a way-point from the current robot position into a trajectory
Insert a waypoint: Insert a way-point from the current mouse position into a trajectory
parametric
Create a trajectory out of edges: Insert a new object which decompose edges to a trajectory
Dress-up a trajectory: Let you override one or more properties of a trajectory
Trajectory compound: create a compound out of some single trajectories
Scripting
This
section
is
generated
out
https://github.com/FreeCAD/FreeCAD_sf_master/blob/master/src/Mod/Robot/RobotExample.py You can use this
directly if you want.
of:
le
Example how to use the basic robot class Robot6Axis which represents a 6-axis industrial robot. The Robot module is
dependent on Part but not on other modules. It works mostly with the basic types Placement, Vector and Matrix. So we need
only:
from Robot import *
from Part import *
from FreeCAD import *
App.activeDocument().addObject("Robot::TrajectoryObject","Trajectory")
get the Trajectory
t = App.activeDocument().Trajectory.Trajectory
add the actual TCP position of the robot to the trajectory
StartTcp = App.activeDocument().Robot.Tcp
t.insertWaypoints(StartTcp)
App.activeDocument().Trajectory.Trajectory = t
print App.activeDocument().Trajectory.Trajectory
insert some more Waypoints and the start point at the end again:
for i in range(7):
t.insertWaypoints(Waypoint(Placement(Vector(0,1000,i*100+500),Vector(1,0,0),i),"LIN","Pt"))
t.insertWaypoints(StartTcp) # end point of the trajectory
App.activeDocument().Trajectory.Trajectory = t
print App.activeDocument().Trajectory.Trajectory
Simulation
To be done.....
Tutorials
6-Axis_Robot
VRML Preparation for Robot Simulation
OpenSCAD Workbench
(Redirected from OpenSCAD Workbench)
The OpenSCAD module is in an early stage of development.
The OpenSCAD module offers interoperability with the open source software OpenSCAD.
It contains an importer which allows you to open the .csg output from OpenSCAD in FreeCAD.
The exporter outputs a CSG based (sub-)tree to .csg. Geometry which is not based on CSG operations and is
exported as a mesh. The OpenSCAD module contains a toolbox with functions to modify the feature tree and
repair models.
Contents
1 OpenSCAD language and file format
2 GUI Commands
3 Limitations
4 Hints
5 Links
GUI Commands
Color Code Shape: Change the Color of selected or all Shapes based on their validity
Replace Object: Replace an object in the Feature Tree. Please select old, new and parent object
Remove Subtree: Removes the selected objects and all children that are not referenced from
other objects
Refine Shape Feature: Create Refine Shape Feature
Increase Tolerance Feature:
Convert Edges To Faces: Convert Edges to Faces. Useful to prepare imported DXF geometry for
extrusion.
Expand Placements: Expand all placements downwards the FeatureTree
Explode Group:
Add OpenSCAD Element: Add an OpenSCAD element by entering OpenSCAD code into the task
panel and executing the OpenSCAD binary (requires OpenSCAD to be installed on your computer) Note:
This icon will initially not appear (even if OpenSCAD is installed on your computer), you must also
configure FreeCAD. [See here for more details]
Mesh Boolean...:
Hull:
Minkowski:
Limitations
OpenSCAD creates constructive solid geometry as well as importing mesh les and extruding 2d geometry
(from dxf les). 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
Menu location
OpenSCAD -> Add OpenSCAD
Element
Workbenches
OpenSCAD
Default shortcut
None
See also
None
include <../examples/example001.scad>;
Contents
would include the first examples also known as the OpenSCAD icon
1 OpenSCAD
AddOpenSCADElement
1.1 Description
1.2 Initial set up from
within FreeCAD
Fem Workbench
(Redirected from Fem Workbench)
The Fem Workbench provides modern Finite Element Analysis (FEA) work ow for FreeCAD. Mainly this means
all tools to make an Finite Element Analysis are combined in one GUI.
As of FreeCAD version 0.15 and 0,16dev the FEM-Module can be used on Windows, Mac OSX and Linux
platforms. Since FEM Workbench makes use of external software, the amount of manual intervention until
the FEM workbench is ready to use will depend on the OS that you are using. Check out FEM Install.
Tools
New mechanical analysis: Creates a new container for a mechanical analysis. If a solid is
selected in the tree view before clicking on it, the meshing dialog will be opened next.
olver Create FEM solver: Creates a new solver for this analysis. In most cases the solver is created
Purge results: Clears the current Results in the tree view. [0.16]
Show result: Used to display the result of the study (Von Mises Stress or Displacement)
Tutorials
Tutorial 1 FEM CalculiX Cantilever 3D
Tutorial 2 FEM Tutorial
Links
FEM Install for a detailed description how to set up a working FEM Module.
FEM Mesh for further Information about the FEM Mesh in FreeCAD
FEM CalculiX for further Information about the interface between FEM Module and the current Solver CalculiX
FEM Project for more detailed informations about the Units, Limitations and the Development of FEM Module.
FEM Analysis
Description
The FEM Analysis could be seen as a Container that holds all objects of a
Finite Element Analysis. It is mandatory to have a analysis container
which holds all the needed objects. At least one of the following objects
is needed for a mechanical analysis:
FEM Analysis
Menu location
FEM New mechanical
analysis
material
Workbenches
fixed constraint
FEM
Default shortcut
N,A
How to use
1. Press the A FEM Analysis button, or press N then A keys. A
new Analysis is created and set to active.
See also
FEM tutorial
Contents
1 FEM Analysis
3 How to use
2 Description
4 Options
5 Properties
Options
Up to date there is no option to choose.
A frequency analysis in in development. See [1] for more informations.
Properties
DATA
Scripting
new analysis
MechanicalAnalysis.makeMechanicalAnalysis( name )
add object to the analysis
App.ActiveDocument.MechanicalAnalysis.Member =
6 Scripting
App.ActiveDocument.MechanicalAnalysis.Member + [ (object) ]
remove object from the analysis
member = App.ActiveDocument.MechanicalAnalysis.Member
member.remove( documentobject )
App.ActiveDocument.MechanicalAnalysis.Member = member
Examples:
import MechanicalAnalysis
analysis = MechanicalAnalysis.makeMechanicalAnalysis("MechanicalAnalysis")
FemGui.setActiveAnalysis(analysis)
addobj = App.ActiveDocument.getObject("MechanicalMaterial")
App.ActiveDocument.MechanicalAnalysis.Member =
App.ActiveDocument.MechanicalAnalysis.Member + [addobj]
removeobj = App.ActiveDocument.getObject("MechanicalMaterial")
member = App.ActiveDocument.MechanicalAnalysis.Member
member.remove(removeobj)
App.ActiveDocument.MechanicalAnalysis.Member = member
Plot Module
The Plot module allows to edit and save output plots created from other modules and tools. With plot
module you can edit easily the working area, the axes, labels, titles, styles, etc. Plot module is an
abstraction of matplotlib conveniently addapted to FreeCAD.
Tools
These are tools availables.
Save plot: Saves the plot in several formats. You can select the output size and resolution too.
Axes: Add, remove or edit plot axes.
Series: Edit series title and styling.
Grid: Show/hide grid.
Legend: Show/hide legend.
Labels: Edit labels.
Positions: Set elements positions.
Scripting
Since Plot module is a layer over matplotlib, you are free to use all matplotlib commands over plot
instances. See scripting examples section to see examples.
Tutorial
Plot Basic tutorial
Plot MultiAxes tutorial
Plot Save
Description
Plot save tool saves the active plot at desired location. With this tool
you can also select the size and resolution of output image.
Plot Save
Menu location
Plot Save plot
Workbenches
Plot
Default shortcut
None
See also
None
Contents
1 Plot Save
2 Description
3 How to use
4 Options
5 Scripting
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 le
dialog where you can choose the output image place and format.
Path selection button
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, (oat, oat), oat) : Saves the plot at path, width the size speci ed 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.
Contents
1 Plotting data
1.1 Creating plot document
1.2 Drawing functions
2 Configuring plot
2.1 Showing grid and legend
2.2 Setting series labels
2.3 Setting series style
2.4 Setting axes labels
3 Saving plot
Plotting data
In order to plot data you don't need to create a new FreeCAD document, simply show the Python console and
start sending commands, or use macros.
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.
Since matplotlib supports LaTeX you can set all the labels or titles that you want using it. Set the following
label to second serie:
Saving plot
With saving plot tool you can save your plot as image file in several formats.
(Dots per inch) will control the image resolution, for example using 100 dpi you will get an image of 1170x830
pixels.
Contents
1 Plotting data
1.1 Creating plot data
1.2 Drawing functions, adding new axes
2 Configuring plot
2.1 Configuring axes
2.2 Configuring series
2.3 Showing grid and legend
2.4 Setting axes labels
2.5 Setting elements position
3 Saving plot
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.
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]
A s 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.
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 pre x 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.
Configuring series
Set series properties as we did in previous tutorial.
X Label = $x$
Y Label = $\mathrm{f} \left( x \right)$
Axes 1:
X Label = $t$
Y Label = $\mathrm{f} \left( t \right)$
Set also 20 to fontsize for all but title, that uses a fontsize of 24. As happens with legend, title is bad placed,
interseting with second axes set, so we need to solve both problems.
Saving plot
Now you can save your work. See previous tutorial if you don't remeber how to do it.
Mesh Workbench
Th e Mesh 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).
Regular solid... Create mesh primitives, like cubes, cylinders, cones, or spheres:
Create a mesh cube
Create a mesh cylinder
Create a mesh cone
Create a mesh sphere
Create a mesh ellipsoid
Create a mesh torus
Interface Customization
Since FreeCAD interface is based on the modern Qt toolkit, it has a state-of-the-art organization. Widgets,
menus, toolbars and other tools can be modi ed, moved, shared between workbenches, keyboard shortcuts
can be set, modi ed, and macros can be recorded and played. The customization window is accessed from
the Tools -> Customize menu:
The Commands tab lets you browse all available FreeCAD commands, organized by their category.
In Keyboard, you can see the keyboard shortcuts associated with every FreeCAD command, and if you want,
modify or assign new shortcut to any command. This is where to come if you use a particular workbench
often, and would like to speed up its use by using the keyboard.
The Toolbars and Toolbox bars tabs let you modify existing toolbars, or create your own custom toolbars.
The Macros tab lets you manage your saved Macros.
Create your ToolBars for your macro Customize ToolsBar
In 0.16 version is available a new tool that lets you manage your workbenches
Preferences Editor
The preferences system of FreeCAD is located in the Edit menu -> Preferences.
FreeCAD functionality is divided into different modules, each module being responsible for the working of a
speci c workbench. FreeCAD also uses a concept called late loading, which means that components are
loaded only when they are needed. You may have noticed that when you select a workbench on the FreeCAD
toolbar, that workbench and all its components get loaded at that moment. This includes its preferences
settings.
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.
Contents
1 How it works
2 Example
3 Customizing
4 Creating macros without recording
5 Macros repository
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:
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...
Macros repository
Visit the Macros 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 nd errors in your code, because you go slowly, step-bystep.
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.
Contents
1 The interpreter
2 Variables
3 Numbers
4 Lists
5 Indentation
6 Functions
7 Modules
8 Starting with FreeCAD
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
(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 noti ed 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 nd for you. That's where the concept of variable comes in. A variable is simply a value that you
store under a name. For example, type this:
a = "hello"
print a
I guess you understood what happened, we "saved" the string "hello" under the name a. Now, a is not an
unknown name anymore! We can use it anywhere, for example in the print command. We can use any name
we want, just respecting simple rules, like not using spaces or punctuation. For example, we could very well
write:
hello = "my own version of hello"
print hello
See? now hello is not an unde ned 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 modi ed. But our own variables can be modi ed anytime, that's exactly why they are called
variables, the contents can vary. For example:
myVariable = "hello"
print myVariable
myVariable = "good bye"
print myVariable
We changed the value of myVariable. We can also copy variables:
var1 = "hello"
var2 = var1
print var2
Note that it is interesting to give good names to your variables, because when you'll write long programs,
after a while you won't remember what your variable named "a" is for. But if you named it for example
myWelcomeMessage, you'll remember easily what it is used for when you'll see it.
Numbers
Of course you must know that programming is useful to treat all kind of data, and especially numbers, not
only text strings. One thing is important, Python must know what kind of data it is dealing with. We saw in
our print hello example, that the print command recognized our "hello" string. That is because by using the
", we told specifically the print command that what it would come next is a text string.
We can always check what data type is the contents of a variable with the special Python keyword type:
myVar = "hello"
type(myVar)
It will tell us the contents of myVar is 'str', or string in Python jargon. We have also other basic types of
data, such as integer and float numbers:
firstNumber = 10
secondNumber = 20
print firstNumber + secondNumber
type(firstNumber)
This is already much more interesting, isn't it? Now we already have a powerful calculator! Look well at how
it worked, Python knows that 10 and 20 are integer numbers. So they are stored as "int", and Python can do
with them everything it can do with integers. Look at the results of this:
firstNumber = "10"
secondNumber = "20"
print firstNumber + secondNumber
See? We forced Python to consider that our two variables are not numbers but mere pieces of text. Python
can add two pieces of text together, but it won't try to nd out any sum. But we were talking about integer
numbers. There are also oat numbers. The difference is that integer numbers don't have decimal part,
while foat numbers can have a decimal part:
var1 = 13
var2 = 15.65
print "var1 is of type ", type(var1)
print "var2 is of type ", type(var2)
Int and Floats can be mixed together without problem:
total = var1 + var2
print total
print type(total)
Of course the total has decimals, right? Then Python automatically decided that the result is a oat. In
several cases such as this one, Python automatically decides what type to give to something. In other cases
it doesn't. For example:
varA = "hello 123"
varB = 456
print varA + varB
This will give us an error, varA is a string and varB is an int, and Python doesn't know what to do. But we can
force Python to convert between types:
varA = "hello"
varB = 123
print varA + str(varB)
Now both are strings, the operation works! Note that we "stringi ed" varB at the time of printing, but we
didn't change varB itself. If we wanted to turn varB permanently into a string, we would need to do this:
varB = str(varB)
We can also use int() and float() to convert to int and float if we want:
varA = "123"
print int(varA)
print float(varA)
Note on Python commands
You must have noticed that in this section we used the print command in several ways. We printed
variables, sums, several things separated by commas, and even the result of other Python command such as
type(). Maybe you also saw that doing those two commands:
type(varA)
print type(varA)
have exactly the same result. That is because we are in the interpreter, and everything is automatically
printed on screen. When we'll write more complex programs that run outside the interpreter, they won't print
automatically everything on screen, so we'll need to use the print command. But from now on, let's stop
using it here, it'll go faster. So we can simply write:
myVar = "hello friends"
myVar
You must also have seen that most of the Python commands (or keywords) we already know have
parenthesis used to tell them on what contents the command must work: type(), int(), str(), etc. Only
exception is the print command, which in fact is not an exception, it also works normally like this:
print("hello"), but, since it is used often, the Python programmers made a simplified version.
Lists
Another interesting data type is lists. A list is simply a list of other data. The same way as we de ne a text
string by using " ", we define lists by using [ ]:
myList = [1,2,3]
type(myList)
myOtherList = ["Bart", "Frank", "Bob"]
myMixedList = ["hello", 345, 34.567]
You see that it can contain any type of data. Lists are very useful because you can group variables together.
You can then do all kind of things within that groups, for example counting them:
len(myOtherList)
or retrieving one item of a list:
myName = myOtherList[0]
myFriendsName = myOtherList[1]
You see that while the len() command returns the total number of items in a list, their "position" in the list
begins with 0. The rst 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, oats and lists, there are more built-in data types, such as dictionnaries, or you can
even create your own data types with classes.
Indentation
One big cool use of lists is also browsing through them and do something with each item. For example look
at this:
alldaltons = ["Joe", "William", "Jack", "Averell"]
for dalton in alldaltons:
print dalton + " Dalton"
We iterated (programming jargon again!) through our list with the "for ... in ..." command and did something
with each of the items. Note the special syntax: the for command terminates with : which indicates that
what will comes after will be a block of one of more commands. Immediately after you enter the command
line ending with :, the command prompt will change to ... which means Python knows that a :-ended line has
happened and that what will come next will be part of it.
How will Python know how many of the next lines will be to be executed inside the for...in operation? For
that, Python uses indentation. That is, your next lines won't begin immediately. You will begin them with a
blank space, or several blank spaces, or a tab, or several tabs. Other programming languages use other
methods, like putting everythin inside parenthesis, etc. As long as you write your next lines with the same
indentation, they will be considered part of the for-in block. If you begin one line with 2 spaces and the next
one with 4, there will be an error. When you nished, just write another line without indentation, or simply
press Enter to come back from the for-in block
Indentation is cool because if you make big ones (for example use tabs instead of spaces because it's
larger), when you write a big program you'll have a clear view of what is executed inside what. We'll see that
many other commands than for-in can have indented blocks of code too.
For-in commands can be used for many things that must be done more than once. It can for example be
combined with the range() command:
serie = range(1,11)
total = 0
print "sum"
for number in serie:
print number
total = total + number
print "----"
print total
Or more complex things like this:
alldaltons = ["Joe", "William", "Jack", "Averell"]
for n in range(4):
print alldaltons[n], " is Dalton number ", n
You see that the range() command also has that strange particularity that it begins with 0 (if you don't
specify the starting number) and that its last number will be one less than the ending number you specify.
That is, of course, so it works well with other Python commands. For example:
alldaltons = ["Joe", "William", "Jack", "Averell"]
total = len(alldaltons)
for n in range(total):
print alldaltons[n]
Another interesting use of indented blocks is with the if command. If executes a code block only if a certain
condition is met, for example:
alldaltons = ["Joe", "William", "Jack", "Averell"]
if "Joe" in alldaltons:
print "We found that Dalton!!!"
Of course this will always print the first sentence, but try replacing the second line by:
if "Lucky" in alldaltons:
Then nothing is printed. We can also specify an else: statement:
alldaltons = ["Joe", "William", "Jack", "Averell"]
if "Lucky" in alldaltons:
print "We found that Dalton!!!"
else:
print "Such Dalton doesn't exist!"
Functions
The standard Python commands are not many. In current version of Python there are about 30, and we
already know several of them. But imagine if we could invent our own commands? Well, we can, and it's
extremely easy. In fact, most the additional modules that you can plug into your Python installation do just
that, they add commands that you can use. A custom command in Python is called a function and is made
like this:
def printsqm(myValue):
print str(myValue)+" square meters"
printsqm(45)
Extremely simple: the def() command de nes a new function. You give it a name, and inside the parenthesis
you de ne arguments that we'll use in our function. Arguments are data that will be passed to the function.
For example, look at the len() command. If you just write len() alone, Python will tell you it needs an
argument. That is, you want len() of something, right? Then, for example, you'll write len(myList) and you'll
get the length of myList. Well, myList is an argument that you pass to the len() function. The len() function is
defined in such a way that it knows what to do with what is passed to it. Same as we did here.
The "myValue" name can be anything, and it will be used only inside the function. It is just a name you give
to the argument so you can do something with it, but it also serves so the function knows how many
arguments to expect. For example, if you do this:
printsqm(45,34)
There will be an error. Our function was programmed to receive just one argument, but it received two, 45
and 34. We could instead do something like this:
def sum(val1,val2):
total = val1 + val2
return total
sum(45,34)
myTotal = sum(45,34)
We made a function that receives two arguments, sums them, and returns that value. Returning something
is very useful, because we can do something with the result, such as store it in the myTotal variable. Of
course, since we are in the interpreter and everything is printed, doing:
sum(45,34)
will print the result on the screen, but outside the interpreter, since there is no more print command inside
the function, nothing would appear on the screen. You would need to do:
print sum(45,34)
to have something printed. Read more about functions here.
Modules
Now that we have a good idea of how Python works, we'll need one last thing: How to work with les 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 le 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 le,
open it with Python, and execute it. But you can also execute it from the Python interpreter itself. For this,
the interpreter must know where your .py program is. In FreeCAD, the easiest way is to place your program in
a place that FreeCAD's Python interpreter knows by default, such as FreeCAD's bin folder, or any of the Mod
folders. Suppose we write a file like this:
def sum(a,b):
return a + b
print "test.py succesfully loaded"
and we save it as test.py in our FreeCAD/bin directory. Now, let's start FreeCAD, and in the interpreter
window, write:
import test
without the .py extension. This will simply execute the contents of the le, 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 les, like ours, but also
to load the functions inside, so they become available in the interpreter. Files containing functions, like
ours, are called modules.
Normally when we write a sum() function in the interpreter, we execute it simply like that:
sum(14,45)
Like we did earlier. When we import a module containing our sum() function, the syntax is a bit different. We
do:
test.sum(14,45)
That is, the module is imported as a "container", and all its functions are inside. This is extremely useful,
because we can import a lot of modules, and keep everything well organized. So, basically, everywhere you
see something.somethingElse, with a dot in between, that means somethingElse is inside something.
We can also throw out the test part, and import our sum() function directly into the main interpreter space,
like this:
from test import *
sum(12,54)
Basically all modules behave like that. You import a module, then you can use its functions like that:
module.function(argument). Almost all modules do that: they de ne 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__, __ le__,
__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 nally 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 modi y it.
Then, instead of closing and reopening the python interpreter, we can simply update the module like this:
reload(myModule)
Contents
1 Writing python code
2 Exploring FreeCAD
3 Vectors and Placements
4 App and Gui
5 Modules
6 Mesh
7 Part
8 Draft
9 Interface
10 Macros
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.
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.
Modules
Now, you must be wondering, what, other 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 create 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, Mesh, Sketcher or Draft.
Sketcher and Draft both use the Part module to create and handle their geometry, which are BRep while
Mesh is totally independent, and handles its own objects. More about that below.
You can check all the available base object types for the current document like this:
doc.supportedTypes()
The different FreeCAD modules, although they added their object types to FreeCAD, are not automatically
loaded in the python console. This is to avoid having a very slow startup. Modules are loaded only when you
need them. So, for example, to explore what's inside the Part module:
import Part
Part.
But we'll talk more about the Part module below.
By now, you know a bit more about the different modules of FreeCAD: The core modules (FreeCAD,
FreeCADGui), and the workbenches modules (Part, Mesh, Sketcher). The other important modules are the 3d
scene module (pivy) and the interface module (pyside), we'll talk about them too below.
Now it's time to explore a bit deeper the important ones, which are the workbench modules.
Mesh
Meshes are a very simple kind of 3D objects, used for example by Sketchup, Blender or 3D studio Max. They
are composed of 3 elements: points (also called vertices), lines (also called edges) and faces. In many
applications, FreeCAD included, faces can have only 3 vertices. 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 mentioned 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 used extensively as the main test module in the rst
month of FreeCAD's life.
Mesh objects and FreeCAD objects are different things. You can see the FreeCAD object as a container for a
Mesh object (like, we'll see below, for Part objects too). So in order to add a mesh object to FreeCAD, we
must first create a FreeCAD object and a Mesh object, then add the Mesh object to the FreeCAD object:
import Mesh
mymesh = Mesh.createSphere()
mymesh.
mymesh.Facets
mymesh.Points
meshobj = doc.addObject("Mesh::Feature","MyMesh")
meshobj.Mesh = mymesh
doc.recompute()
This is a standard example, that uses the createSphere() method to automatically create a sphere, but you
can very well create custom meshes from scratch, by defining their vertices and faces.
Read more about mesh scripting...
Part
The Part Module 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 de ned by their surfaces, which enclose and
de ne an inner volume. These surface can be a variety of things, such as plane faces or very complex
NURBS surfaces. They also carry the concept of volume.
The Part module is based on the powerful OpenCasCade library, which allows a wide range of complex
operations to be easily performed on those objects, such as boolean operations, filleting, lofts, etc...
The Part module works the same way as the Mesh module: You create a FreeCAD object, a Part object, then
add the Part object to the FreeCAD object:
import Part
myshape = Part.makeSphere(10)
myshape.
myshape.Volume
myshape.Area
shapeobj = doc.addObject("Part::Feature","MyShape")
shapeobj.Shape = myshape
doc.recompute()
The Part module (like the Mesh module) also has a shortcut that automatically creates a FreeCAD object and
add a shape to it, so you can skip the 3 last lines above:
Part.show(myshape)
By exploring the contents of myshape, you will notice many interesting available subcomponents such as
Faces, Edges, Vertexes, Solids or Shells, and a wide range of geometry operations such as cut (subtraction),
common (intersection) or fuse (union). The Topological data scripting page explains all that in detail.
Read more about part scripting...
Draft
FreeCAD features many more modules, such as Sketcher or Draft, which also create Part objects, but add
parameters to it, or even carry a whole new way to handle the Part geometry in them. Our box example
above, is a perfect example of parametric object. All you need, to de ne 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 Module 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 ddle with the
Qt interface and produce a simple dialog:
from PySide import QtGui
QtGui.QMessageBox.information(None,"Apollo program","Houston, we have a problem")
See that the dialog that appears has the FreeCAD icon in its toolbar, meaning that Qt knows that the order
has been issued from inside the FreeCAD application. We can therefore easily directly manipulate any part
of the FreeCAD interface.
Qt is a very powerful interface system, that allows you to do very complex things, but also has a couple of
very easy-to use tools such as the Qt Designer with which you can design dialogs graphically and then add
them to the FreeCAD interface with a couple of lines of python.
Read more about PySide here...
Macros
Now that you have a good understanding of the basics, where are we going to keep our python scripts, and
how are we going to launch them easily from FreeCAD? There is an easy mechanism for that, called Macros.
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 de ne 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!
Contents
1 Introduction
1.1 Class Diagram
1.2 Geometry
1.3 Topology
1.4 Quick example : Creating simple topology
1.4.1 Creating Geometry
1.4.2 Arc
1.4.3 Line
1.4.4 Putting all together
1.4.5 Make a prism
1.4.6 Show it all
2 Creating basic shapes
2.1 Importing the needed modules
2.2 Creating a Vector
2.3 Creating an Edge
2.4 Putting the shape on screen
2.5 Creating a Wire
2.6 Creating a Face
2.7 Creating a Circle
2.8 Creating an Arc along points
2.9 Creating a polygon
2.10 Creating a Bezier curve
2.11 Creating a Plane
2.12 Creating an ellipse
2.13 Creating a Torus
2.14 Creating a box or cuboid
2.15 Creating a Sphere
2.16 Creating a Cylinder
2.17 Creating a Cone
3 Modifying shapes
3.1 Transform operations
3.1.1 Translating a shape
3.1.2 Rotating a shape
3.1.3 Generic transformations with matrixes
3.1.4 Scaling a shape
3.2 Boolean Operations
3.2.1 Subtraction
3.2.2 Intersection
3.2.3 Union
3.2.4 Section
3.2.5 Extrusion
4 Exploring shapes
4.1 Edge analysis
4.2 Using the selection
5 Complete example: The OCC bottle
5.1 The complete script
5.2 Detailed explanation
6 Box pierced
7 Loading and Saving
Introduction
We will here explain you how to control the Part Module directly from the FreeCAD python interpreter, or from any external
script. The basics about Topological data scripting are described in Part Module 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 Modeling Language (UML) overview of the most important classes of the Part module:
Geometry
The geometric objects are the building block of all topological objects:
Geom Base class of the geometric objects
Line A straight line in 3D, defined by starting point and end point
Circle Circle or circle segment defined by a center point and start and end point
...... And soon some more
Topology
We will now create a topology by constructing it out of simpler geometry. As a case study we use a part as seen in the
picture which consists of four vertexes, two circles and two lines.
Creating Geometry
First we have to create the distinct geometric parts of this wire. And we have to take care that the vertexes of the
geometric parts are at the same position. Otherwise later on we might not be able to connect the geometric parts to a
topology!
So we create first the points:
from
V1 =
V2 =
V3 =
V4 =
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)
S1 = Part.Shape([C1,C2,L1,L2])
Make a prism
Now extrude the wire in a direction and make an actual 3D shape:
W = Part.Wire(S1.Edges)
P = W.extrude(Base.Vector(0,0,10))
Show it all
Part.show(P)
b = Part.makeBox(100,100,100)
Part.show(b)
import Part
Creating a Vector
Vectors are one of the most important pieces of information when building shapes. They contain a 3 numbers usually (but
not necessarily always) the x, y and z cartesian coordinates. You create a vector like this:
myVector = Base.Vector(3,2,0)
We just created a vector at coordinates x=3, y=2, z=0. In the Part module, vectors are used everywhere. Part shapes also use
another kind of point representation, called Vertex, which is acually nothing else than a container for a vector. You access
the vector of a vertex like this:
myVertex = myShape.Vertexes[0]
print myVertex.Point
> Vector (3, 2, 0)
Creating an Edge
An edge is nothing but a line with two vertexes:
vec1
vec2
line
edge
=
=
=
=
Base.Vector(0,0,0)
Base.Vector(10,0,0)
Part.Line(vec1,vec2)
line.toShape()
You can find the length and center of an edge like this:
edge.Length
> 10.0
edge.CenterOfMass
> Vector (5, 0, 0)
Part.show(edge)
An object will be created in our FreeCAD document, and our "edge" shape will be attributed to it. Use this whenever it's
time to display your creation on screen.
Creating a Wire
A wire is a multi-edge line and can be created from a list of edges or even a list of wires:
edge1
edge2
wire1
edge3
edge4
wire2
=
=
=
=
=
=
Part.makeLine((0,0,0), (10,0,0))
Part.makeLine((10,0,0), (10,10,0))
Part.Wire([edge1,edge2])
Part.makeLine((10,10,0), (0,10,0))
Part.makeLine((0,10,0), (0,0,0))
Part.Wire([edge3,edge4])
wire3 = Part.Wire([wire1,wire2])
wire3.Edges
> [<Edge object at 016695F8>, <Edge object at 0197AED8>, <Edge object at 01828B20>, <Edge object at 0190A788>]
Part.show(wire3)
Part.show(wire3) will display the 4 edges that compose our wire. Other useful information can be easily retrieved:
wire3.Length
> 40.0
wire3.CenterOfMass
> Vector (5, 5, 0)
wire3.isClosed()
> True
wire2.isClosed()
> False
Creating a Face
Only faces created from closed wires will be valid. In this example, wire3 is a closed wire but wire2 is not a closed wire (see
above)
face = Part.Face(wire3)
face.Area
> 99.999999999999972
face.CenterOfMass
> Vector (5, 5, 0)
face.Length
> 40.0
face.isValid()
> True
sface = Part.Face(wire2)
face.isValid()
> False
circle = Part.makeCircle(10)
circle.Curve
> Circle (Radius : 10, Position : (0, 0, 0), Direction : (0, 0, 1))
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)
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)])
def makeBCurveEdge(Points):
geomCurve = Part.BezierCurve()
geomCurve.setPoles(Points)
edge = Part.Edge(geomCurve)
return(edge)
Creating a Plane
A Plane is simply a at rectangular surface. The method used to create one is t h i s : makePlane(length,width,
[start_pnt,dir_normal]). By default start_pnt = Vector(0,0,0) and dir_normal = Vector(0,0,1). Using dir_normal = Vector(0,0,1)
will create the plane facing z axis, while dir_normal = Vector(1,0,0) will create the plane facing x axis:
plane = Part.makePlane(2,2)
plane
><Face object at 028AF990>
plane = Part.makePlane(2,2, Base.Vector(3,0,0), Base.Vector(0,1,0))
plane.BoundBox
> BoundBox (3, 0, 0, 5, 0, 2)
BoundBox is a cuboid enclosing the plane with a diagonal starting at (3,0,0) and ending at (5,0,2). Here the BoundBox
thickness in y axis is zero, since our shape is totally flat.
Note: makePlane only accepts Base.Vector() for start_pnt and dir_normal but not tuples
Creating an ellipse
To create an ellipse there are several ways:
Part.Ellipse()
Creates an ellipse with major radius 2 and minor radius 1 with the center in (0,0,0)
Part.Ellipse(Ellipse)
Part.Ellipse(S1,S2,Center)
Creates an ellipse centered on the point Center, where the plane of the ellipse is de ned 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 de ned by Center and
the normal (0,0,1)
eli = Part.Ellipse(Base.Vector(10,0,0),Base.Vector(0,5,0),Base.Vector(0,0,0))
Part.show(eli.toShape())
In the above code we have passed S1, S2 and center. Similarly to Arc, Ellipse also creates an ellipse object but not edge, so
we need to convert it into edge using toShape() to display.
Note: Arc only accepts Base.Vector() for points but not tuples
eli = Part.Ellipse(Base.Vector(0,0,0),10,5)
Part.show(eli.toShape())
for the above Ellipse constructor we have passed center, MajorRadius and MinorRadius
Creating a Torus
Using
the
method makeTorus(radius1,radius2,[pnt,dir,angle1,angle2,angle]).
By default
pnt=Vector(0,0,0),dir=Vector(0,0,1),angle1=0,angle2=360 and angle=360. Consider a torus as small circle sweeping along a
big circle. Radius1 is the radius of big cirlce, radius2 is the radius of small circle, pnt is the center of torus and dir is the
normal direction. angle1 and angle2 are angles in radians for the small circle, the last parameter angle is to make a section
of the torus:
torus = Part.makeTorus(10, 2)
The above code will create a torus with diameter 20(radius 10) and thickness 4 (small cirlce radius 2)
tor=Part.makeTorus(10,5,Base.Vector(0,0,0),Base.Vector(0,0,1),0,180)
tor=Part.makeTorus(10,5,Base.Vector(0,0,0),Base.Vector(0,0,1),0,360,180)
The above code will create a semi torus, only the last parameter is changed i.e the angle and remaining angles are
defaults. Giving the angle 180 will create the torus from 0 to 180, that is, a half torus.
Creating a box or cuboid
Using makeBox(length,width,height,[pnt,dir]). By default pnt=Vector(0,0,0) and dir=Vector(0,0,1)
box = Part.makeBox(10,10,10)
len(box.Vertexes)
> 8
Creating a Sphere
Us ing makeSphere(radius,[pnt, dir, angle1,angle2,angle3]) . By default pnt=Vector(0,0,0), dir=Vector(0,0,1), angle1=-90,
angle2=90 and angle3=360. angle1 and angle2 are the vertical minimum and maximum of the sphere, angle3 is the sphere
diameter itself.
sphere = Part.makeSphere(10)
hemisphere = Part.makeSphere(10,Base.Vector(0,0,0),Base.Vector(0,0,1),-90,90,180)
Creating a Cylinder
Using makeCylinder(radius,height,[pnt,dir,angle]). By default pnt=Vector(0,0,0),dir=Vector(0,0,1) and angle=360
cylinder = Part.makeCylinder(5,20)
partCylinder = Part.makeCylinder(5,20,Base.Vector(20,0,0),Base.Vector(0,0,1),180)
Creating a Cone
Using makeCone(radius1,radius2,height,[pnt,dir,angle]). By default pnt=Vector(0,0,0), dir=Vector(0,0,1) and angle=360
cone = Part.makeCone(10,0,20)
semicone = Part.makeCone(10,0,20,Base.Vector(20,0,0),Base.Vector(0,0,1),180)
Modifying shapes
There are several ways to modify shapes. Some are simple transformation operations such as moving or rotating shapes,
other are more complex, such as unioning and subtracting one shape from another. Be aware that
Transform operations
Translating a shape
Translating is the act of moving a shape from one place to another. Any shape (edge, face, cube, etc...) can be translated
the same way:
myShape = Part.makeBox(2,2,2)
myShape.translate(Base.Vector(2,0,0))
myShape.rotate(Vector(0,0,0),Vector(0,0,1),180)
The above code will rotate the shape 180 degrees around the Z Axis.
Generic transformations with matrixes
A matrix is a very convenient way to store transformations in the 3D world. In a single matrix, you can set translation,
rotation and scaling values to be applied to an object. For example:
myMat = Base.Matrix()
myMat.move(Base.Vector(2,0,0))
myMat.rotateZ(math.pi/2)
Note: FreeCAD matrixes work in radians. Also, almost all matrix operations that take a vector can also take 3 numbers, so
those 2 lines do the same thing:
myMat.move(2,0,0)
myMat.move(Base.Vector(2,0,0))
When our matrix is set, we can apply it to our shape. FreeCAD provides 2 methods to do that: transformShape() and
transformGeometry(). The difference is that with the rst 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
Union is called "fuse" and works the same way:
cylinder1 = Part.makeCylinder(3,10,Base.Vector(0,0,0),Base.Vector(1,0,0))
cylinder2 = Part.makeCylinder(3,10,Base.Vector(5,0,-5),Base.Vector(0,0,1))
fuse = cylinder1.fuse(cylinder2)
Section
A Section is the intersection between a solid shape and a plane shape. It will return an intersection curve, a compound with
edges
cylinder1 = Part.makeCylinder(3,10,Base.Vector(0,0,0),Base.Vector(1,0,0))
cylinder2 = Part.makeCylinder(3,10,Base.Vector(5,0,-5),Base.Vector(0,0,1))
section = cylinder1.section(cylinder2)
section.Wires
> []
section.Edges
> [<Edge object at 0D87CFE8>, <Edge object at 019564F8>, <Edge object at 0D998458>,
<Edge object at 0D86DE18>, <Edge object at 0D9B8E80>, <Edge object at 012A3640>,
<Edge object at 0D8F4BB0>]
Extrusion
Extrusion is the act of "pushing" a
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 lled face, you will obtain a solid
cylinder:
wire = Part.Wire(circle)
disc = Part.Face(wire)
cylinder = disc.extrude(Base.Vector(0,0,2))
Exploring shapes
You can easily explore the topological data structure:
import Part
b = Part.makeBox(100,100,100)
b.Wires
w = b.Wires[0]
w
w.Wires
w.Vertexes
Part.show(w)
w.Edges
e = w.Edges[0]
e.Vertexes
v = e.Vertexes[0]
v.Point
By typing the lines above in the python interpreter, you will gain a good understanding of the structure of Part objects.
Here, our makeBox() command created a solid shape. This solid, like all Part solids, contains faces. Faces always contain
wires, which are lists of edges that border the face. Each face has at least one closed wire (it can have more if the face has
a hole). In the wire, we can look at each edge separately, and inside each edge, we can see the vertexes. Straight edges
have only two vertexes, obviously.
Edge analysis
In case of an edge, which is an arbitrary curve, it's most likely you want to do a discretization. In FreeCAD the edges are
parametrized by their lengths. That means you can walk an edge/curve by its length:
import Part
box = Part.makeBox(100,100,100)
anEdge = box.Edges[0]
print anEdge.Length
Now you can access a lot of properties of the edge by using the length as a position. That means if the edge is 100mm long
the start position is 0 and the end position 100.
anEdge.tangentAt(0.0)
# tangent direction at the beginning
anEdge.valueAt(0.0)
# Point at the beginning
anEdge.valueAt(100.0)
# Point at the end of the edge
anEdge.derivative1At(50.0) # first derivative of the curve in the middle
anEdge.derivative2At(50.0) # second derivative of the curve in the middle
anEdge.derivative3At(50.0) # third derivative of the curve in the middle
anEdge.centerOfCurvatureAt(50) # center of the curvature for that position
anEdge.curvatureAt(50.0)
# the curvature
anEdge.normalAt(50)
# normal vector at that position (if defined)
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
print
for s
print
for s
print
in Gui.Selection.getSelectionEx():
o.ObjectName
in o.SubElementNames:
"name: ",s
in o.SubObjects:
"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)
aEdge1=aSegment1.toShape()
aEdge2=aArcOfCircle.toShape()
aEdge3=aSegment2.toShape()
aWire=Part.Wire([aEdge1,aEdge2,aEdge3])
aTrsf=Base.Matrix()
aTrsf.rotateZ(math.pi) # rotate around the z-axis
aMirroredWire=aWire.transformGeometry(aTrsf)
myWireProfile=Part.Wire([aWire,aMirroredWire])
myFaceProfile=Part.Face(myWireProfile)
aPrismVec=Base.Vector(0,0,myHeight)
myBody=myFaceProfile.extrude(aPrismVec)
myBody=myBody.makeFillet(myThickness/12.0,myBody.Edges)
neckLocation=Base.Vector(0,0,myHeight)
neckNormal=Base.Vector(0,0,1)
myNeckRadius = myThickness / 4.
myNeckHeight = myHeight / 10
myNeck = Part.makeCylinder(myNeckRadius,myNeckHeight,neckLocation,neckNormal)
myBody = myBody.fuse(myNeck)
faceToRemove = 0
zMax = -1.0
for xp in myBody.Faces:
try:
surf = xp.Surface
if type(surf) == Part.Plane:
z = surf.Position.z
if z > zMax:
zMax = z
faceToRemove = xp
except:
continue
myBody = myBody.makeThickness([faceToRemove],-myThickness/50 , 1.e-3)
return myBody
Detailed explanation
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 de ne 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 pro le. Easier than building the whole pro le 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.
face1
face2
face3
face4
face5
face6
=
=
=
=
=
=
Part.Face(poly)
Part.Face(poly)
Part.Face(poly)
Part.Face(poly)
Part.Face(poly)
Part.Face(poly)
myMat = FreeCAD.Matrix()
myMat.rotateZ(math.pi/2)
face2.transformShape(myMat)
face2.translate(FreeCAD.Vector(size, 0, 0))
myMat.rotateZ(math.pi/2)
face3.transformShape(myMat)
face3.translate(FreeCAD.Vector(size, size, 0))
myMat.rotateZ(math.pi/2)
face4.transformShape(myMat)
face4.translate(FreeCAD.Vector(0, size, 0))
myMat = FreeCAD.Matrix()
myMat.rotateX(-math.pi/2)
face5.transformShape(myMat)
face6.transformShape(myMat)
face6.translate(FreeCAD.Vector(0,0,size))
myShell = Part.makeShell([face1,face2,face3,face4,face5,face6])
mySolid = Part.makeSolid(myShell)
mySolidRev = mySolid.copy()
mySolidRev.reverse()
myCyl = Part.makeCylinder(2,20)
myCyl.translate(FreeCAD.Vector(size/2, size/2, 0))
cut_part = mySolidRev.cut(myCyl)
Part.show(cut_part)
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 les can also be done directly from the File -> Open or File -> Import
menu, while exporting is with File -> Export
Mesh Scripting
Contents
1 Introduction
2 Creation and Loading
3 Modeling
4 Examining and Testing
5 Write your own Algorithms
6 Exporting
7 Gui related stuff
8 Odds and Ends
Introduction
First of all you have to import the Mesh module:
import Mesh
After that you have access to the Mesh module and the Mesh class which facilitate the functions of the FreeCAD
C++ 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 de ne 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 rst two parameters de ne the radiuses of the toroid and the third parameter is a sub-sampling factor for
how many triangles are created. The higher this value the smoother and the lower the coarser the body is. The
Mesh class provides a set of boolean functions that can be used for modeling purposes. It provides union,
intersection and difference of two mesh objects.
m1, m2
m3 = Mesh.Mesh(m1)
m3.unite(m2)
m4 = Mesh.Mesh(m1)
m4.intersect(m2)
m5 = Mesh.Mesh(m1)
m5.difference(m2)
m6 = Mesh.Mesh(m2)
m6.difference(m1)
Finally, a full example that computes the intersection between a sphere and a cylinder that intersects the sphere.
m.write("D:/Develop/Projekte/FreeCAD/FreeCAD_0.7/Mod/Mesh/SavedMesh.py")
import SavedMesh
m2 = Mesh.Mesh(SavedMesh.faces)
Mesh to Part
Converting Part objects to Meshes
Converting higher-level objects such as Part shapes into simpler objects such as meshes is a pretty simple
operation, where all faces of a Part object get triangulated. The result of that triangulation (tessellation) is
then used to construct a mesh: (let's assume our document contains one part object)
#let's assume our document contains one part object
import Mesh
faces = []
shape = FreeCAD.ActiveDocument.ActiveObject.Shape
triangles = shape.tessellate(1) # the number represents the precision of the
tessellation)
for tri in triangles[1]:
face = []
for i in range(3):
vindex = tri[i]
face.append(triangles[0][vindex])
faces.append(face)
m = Mesh.Mesh(faces)
Mesh.show(m)
Sometimes the triangulation of certain faces offered by OpenCascade is quite ugly. If the face has a
rectangular parameter space and doesn't contain any holes or other trimming curves you can also create a
mesh on your own:
import Mesh
def makeMeshFromFace(u,v,face):
(a,b,c,d)=face.ParameterRange
pts=[]
for j in range(v):
for i in range(u):
s=1.0/(u-1)*(i*b+(u-1-i)*a)
t=1.0/(v-1)*(j*d+(v-1-j)*c)
pts.append(face.valueAt(s,t))
mesh=Mesh.Mesh()
for j in range(v-1):
for i in range(u-1):
mesh.addFacet(pts[u*j+i],pts[u*j+i+1],pts[u*(j+1)+i])
mesh.addFacet(pts[u*(j+1)+i],pts[u*j+i+1],pts[u*(j+1)+i+1])
return mesh
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 Mentor.
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:
Pivy
Pivy is a python binding library for Coin3d, the 3D-rendering library used FreeCAD. When imported in a
running python interpreter, it allows to dialog directly with any running Coin3d scenegraphs, such as the
FreeCAD 3D views, or even to create new ones. Pivy is bundled in standard FreeCAD installation.
The coin library is divided into several pieces, coin itself, for manipulating scenegraphs and bindings for
several GUI systems, such as windows or, like in our case, qt. Those modules are available to pivy too,
depending if they are present on the system. The coin module is always present, and it is what we will use
anyway, since we won't need to care about anchoring our 3D display in any interface, it is already done by
FreeCAD itself. All we need to do is this:
from pivy import coin
recomputed by FreeCAD on le 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)
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 exibility and power. For it's user interaction Python with FreeCAD
uses PySide, which is what is documented on this page.
Python offers the 'print' statement which gives the code:
print 'Hello World'
With Python's print statement you have only limited control of the appearance and behaviour. PySide
supplies the missing control and also handles environments (such as the FreeCAD macro le environment)
where the built-in facilities of Python are not enough.
PySide's abilities range from:
to:
PySide is described in the following 3 pages which should follow on one from each other:
Beginner PySide Examples (Hello World, announcements, enter text, enter number)
Medium 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 rst 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.
Introduction
The purpose of this page is to cover beginner level examples of the PySide GUI manager (there are
accompanying pages Medium PySide Examples and Advanced PySide Examples).
Newcomers to GUI programming may stumble over the word "widget". It's meaning outside of computing is
usually given as
"a small gadget or mechanical device, especially one whose name is unknown or unspecified"
For GUI work such as PySide the term "widget" is most often used to refer to the visible elements of the GUI
- windows, dialogs, and input/output features. All visible elements of PySide are called widgets, and, for
those who are interested, they all descend from a common parent class, QWidget. In addition to the visible
elements PySide also offers widgets for networking, XML, multimedia, and database integration.
A widget that is not embedded in a parent widget is called a window and usually windows have a frame and
a title bar. The most common types of windows are the "main window" (from the Class QMainWindow) and
the various subclasses of the dialog (from the Class QDialog). One big difference is that QDialog is modal
(i.e. the user can not do anything outside of the Dialog window while it is open) and the QMainWindow is
non-modal which allows the user to interact with other windows in parallel.
This guide is a shortcut list for getting a PySide program working quickly under FreeCAD, it isn't intended to
teach Python or PySide. Some sites that do that are:
PySide tutorial at zetcode.com
PySide/PyQt Tutorial at PythonCentral.io
PySide 1.0.7 Reference at Srinikom.github.io (note this is a reference, not a tutorial)
Import Statement
PySide is not loaded with Python by default, it must be requested prior to using it. The following command:
from PySide import QtGui, QtCore
causes the 2 parts of PySide to be loaded - QtGui holds classes for managing the Graphic User Interface
while QtCore contains classes that do not directly relate to management of the GUI (e.g. timers and
geometry). Although it is possible to only import the one that is needed, generally they are both needed and
both imported.
Note: the 'import' statement is not repeated in each code snippet below, it is assumed that it is already in
the Python file.
Simplest Example
The simplest interaction with PySide is to present a message to the user which they can only accept:
reply = QtGui.QMessageBox.information(None,"","Houston, we have a problem")
Yes or No Query
The next most simple interaction is to ask for a yes/no answer:
reply = QtGui.QMessageBox.question(None, "", "This is your chance to answer, what do
you think?",
QtGui.QMessageBox.Yes | QtGui.QMessageBox.No, QtGui.QMessageBox.No)
if reply == QtGui.QMessageBox.Yes:
# this is where the code relevant to a 'Yes' answer goes
pass
if reply == QtGui.QMessageBox.No:
# this is where the code relevant to a 'No' answer goes
pass
Remember that even if the user enters only digits, "1234" for example, they are strings and must be
converted to number representation with either of the following:
anInteger = int(userInput) # to convert to an integer from a string representation
aFloat = float(userInput) # to convert to a float from a string representation
def
def
def
def
def
self.setGeometry(
250, 250, 0, 50)
self.setWindowTitle("Pick a Button")
self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
onOption1(self):
self.retStatus = 1
self.close()
onOption2(self):
self.retStatus = 2
self.close()
onOption3(self):
self.retStatus = 3
self.close()
onOption4(self):
self.retStatus = 4
self.close()
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 t 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.
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
Most of the remainder of this section will describe the contents of the Class de nition which appears at the end of
this section. First we will cover the declarative elements that de ne how things operate and how the GUI is
assembled, then we will cover the operative sections (i.e. the code that will execute when user interactions occur).
This window is based on the class QDialog and so is modal - which means no activities can be made outside of the
window while it is open.
Import Statement
The mandatory Import statement
from PySide import QtGui, QtCore
This is best placed at the top of the Python file.
Class Definition
class ExampleModalGuiClass(QtGui.QDialog):
""""""
def __init__(self):
super(ExampleModalGuiClass, self).__init__()
self.initUI()
def initUI(self):
This code is best copied out verbatim and altered. The gist of the code is that we are sub-classing the QDialog Class
of PySide. In adapting this code you will want to change the class name "ExampleModalGuiClass" - make sure to
change it in both locations (e.g. lines 1 & 4).
Window Creation
# create our window
# define window
xLoc,yLoc,xDim,yDim
self.setGeometry(
250, 250, 400, 350)
self.setWindowTitle("Our Example Program Window")
self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
Remembering that screen dimensions are measured from the upper-left corner, on the 3rd line the values refer to:
the number of pixels the upper-left corner will be to the right of the lefthand screen edge (250)
the number of pixels the upper-left corner will be below the upper screen edge (250)
the width of the screen in pixels (400)
the height of the screen in pixels (350)
The title of the window is set and the nal line simply means that this window will never be obscured by another
window - if this is not desired then simply place a Python comment character ('#') as the first character of the line.
Label Creation
# create some Labels
self.label1 = QtGui.QLabel("
", self)
self.label1.setFont('Courier') # set to a non-proportional font
self.label1.move(20, 20)
self.label2 = QtGui.QLabel("sample string number two", self)
self.label2.move(20, 70)
self.label3 = QtGui.QLabel("
", self)
self.label3.setFont('Courier') # set to a non-proportional font
self.label3.move(20, 120)
self.label4 = QtGui.QLabel("can you see this?", self)
self.label4.move(20, 170)
In PySide labels serve two purposes, static labels (as the name implies) as well as read-only (i.e. display-only) text
elds. 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 speci es the font, any font (on the system) can be speci ed, if not
speci ed the default font is used. In this case the font is speci ed 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 speci es 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 rst character, then it would
be executed and it would mark the checkbox as checked. Finally the 5th line moves the Checkbox into position.
Window Display
# now make the window visible
self.show()
There is only one line and it causes the GUI to be displayed after the setup.
Generic Handler
In this code example, generic handlers handle the following events:
onCheckbox1
onCheckbox2
onRadioButton1
onRadioButton2
onPushButton1
onPopMenuAction1
onPopMenuAction2
onPopMenuDivider
onPopMenuAction3
onCancel
onOk
The general form for the handlers is:
def handlerName(self):
lineOfCode1
lineOfCode2
The rst 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 nal colon character. Once the rst line is nished then there are no requirements of the
following code, it is purely application specific.
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 de nitions 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 eld 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
The mandatory Import statement
from PySide import QtGui, QtCore
This is best placed at the top of the Python file.
Class Definition
class ExampleNonmodalGuiClass(QtGui.QMainWindow):
""""""
def __init__(self):
super(ExampleNonmodalGuiClass, self).__init__()
self.initUI()
def initUI(self):
This code is best copied out verbatim and altered. The gist of the code is that we are sub-classing the
QMainWindow Class of PySide. In adapting this code you will want to change the class name
"ExampleNonmodalGuiClass" - make sure to change it in both locations (e.g. lines 1 & 4).
Window Creation
# create our window
# define window xLoc,yLoc,xDim,yDim
self.setGeometry(
250, 250, 400, 150)
self.setWindowTitle("Our Example Nonmodal Program Window")
self.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
self.setMouseTracking(True)
Obviously our window dimensions and title are different. The main point to note is the last line which lets PySide
know that it is to send out mouse position events as they happen. Note that these events will not be sent out when
the mouse is over a widget like a button as the widget will capture the events.
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
#
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 Medium PySide Examples).
By using the PySide module from inside FreeCAD, you have full control over its interface. You can for
example:
Add your own panels, widgets and toolbars
Add or hide elements to existing panels
Change, redirect or add connections between all those elements
myWidget = QtGui.QDockWidget()
mw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myWidget)
You could then add stuff directly to your widget:
myWidget.setObjectName("my Nice New Widget")
myWidget.resize(QtCore.QSize(300,100)) # sets size of the widget
label = QtGui.QLabel("Hello World", myWidget) # creates a label
label.setGeometry(QtCore.QRect(2,50,200,24)) # sets its size
label.setObjectName("myLabel") # sets its name, so it can be found by name
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 les with python's json
module. That module turns a python object as a string, allowing it to be added to the saved le. 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, de nes the geometry of our object, while its GUI part, the View Provider
Object, de nes 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 prede ned 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 de ne 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.
Contents
1 Basic example
2 Available properties
3 Property Type
4 Other more complex example
5 Making objects selectable
6 Working with simple shapes
7 Further informations
Basic example
The following sample can be found in the src/Mod/TemplatePyMod/FeaturePython.py
several other examples:
box").Width=1.0
obj.addProperty("App::PropertyLength","Height","Box", "Height of the
box").Height=1.0
obj.Proxy = self
def onChanged(self, fp, prop):
"'''Do something when a property has changed'''"
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
def execute(self, fp):
"'''Do something when doing a recomputation, this method is mandatory'''"
FreeCAD.Console.PrintMessage("Recompute Python Box feature\n")
class ViewProviderBox:
def __init__(self, obj):
"'''Set this object to the proxy object of the actual view provider'''"
obj.addProperty("App::PropertyColor","Color","Box","Color of the
box").Color=(1.0,0.0,0.0)
obj.Proxy = self
def attach(self, obj):
"'''Setup the scene sub-graph of the view provider, this method is
mandatory'''"
self.shaded = coin.SoGroup()
self.wireframe = coin.SoGroup()
self.scale = coin.SoScale()
self.color = coin.SoBaseColor()
data=coin.SoCube()
self.shaded.addChild(self.scale)
self.shaded.addChild(self.color)
self.shaded.addChild(data)
obj.addDisplayMode(self.shaded,"Shaded");
style=coin.SoDrawStyle()
style.style = coin.SoDrawStyle.LINES
self.wireframe.addChild(style)
self.wireframe.addChild(self.scale)
self.wireframe.addChild(self.color)
self.wireframe.addChild(data)
obj.addDisplayMode(self.wireframe,"Wireframe");
self.onChanged(obj,"Color")
def updateData(self, fp, prop):
"'''If a property of the handled feature has changed we have the chance to
handle this here'''"
# fp is the handled feature, prop is the name of the property that has
changed
l = fp.getPropertyByName("Length")
w = fp.getPropertyByName("Width")
h = fp.getPropertyByName("Height")
self.scale.scaleFactor.setValue(l,w,h)
pass
def getDisplayModes(self,obj):
"'''Return a list of display modes.'''"
modes=[]
modes.append("Shaded")
modes.append("Wireframe")
return modes
def getDefaultDisplayMode(self):
"'''Return the name of the default display mode. It must be defined in
getDisplayModes.'''"
return "Shaded"
def setDisplayMode(self,mode):
"'''Map the display mode defined in attach with those defined in
getDisplayModes.\'''
'''Since they have the same names nothing needs to be done. This
method is optional'''"
return mode
def onChanged(self, vp, prop):
"'''Here we can do something when a single property got changed'''"
FreeCAD.Console.PrintMessage("Change property: " + str(prop) + "\n")
if prop == "Color":
c = vp.getPropertyByName("Color")
self.color.rgb.setValue(c[0],c[1],c[2])
def getIcon(self):
"'''Return the icon in XPM format which will appear in the tree view. This
method is\'''
'''optional and if not defined a default icon is shown.'''"
return """
/* XPM */
static const char * ViewProviderBox_xpm[] = {
"16 16 6 1",
"
c None",
". c #141010",
"+ c #615BD2",
"@ c #C39D55",
"# c #000000",
"$ c #57C355",
"
........",
"
......++..+..",
"
.@@@@.++..++.",
"
.@@@@.++..++.",
"
.@@ .++++++.",
" ..@@ .++..++.",
"###@@@@ .++..++.",
"##$.@@$#.++++++.",
"#$#$.$$$........",
"#$$#######
",
"#$$#$$$$$#
",
"#$$#$$$$$#
",
"#$$#$$$$$#
",
" #$#$$$$$#
",
" ##$$$$$#
",
"
#######
"};
"""
def __getstate__(self):
"'''When saving the document this object gets stored using Python's json
module.\'''
'''Since we have some un-serializable parts here -- the Coin stuff - we must define this method\'''
'''to return a tuple of all serializable objects or None.'''"
return None
def __setstate__(self,state):
"'''When restoring the serialized object from document we have the chance to
set some internals here.\'''
'''Since no data were serialized nothing needs to be done here.'''"
return None
def makeBox():
FreeCAD.newDocument()
a=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box")
Box(a)
ViewProviderBox(a.ViewObject)
Available properties
Properties are the true building stones of FeaturePython objects. Through them, the user will be able to
interact and modify your object. After creating a new FeaturePython object in your document (
obj=FreeCAD.ActiveDocument.addObject("App::FeaturePython","Box") ), you can get a list of the available
properties by issuing:
obj.supportedProperties()
You will get a list of available properties:
App::PropertyBool
App::PropertyBoolList
App::PropertyFloat
App::PropertyFloatList
App::PropertyFloatConstraint
App::PropertyQuantity
App::PropertyQuantityConstraint
App::PropertyAngle
App::PropertyDistance
App::PropertyLength
App::PropertySpeed
App::PropertyAcceleration
App::PropertyForce
App::PropertyPressure
App::PropertyInteger
App::PropertyIntegerConstraint
App::PropertyPercent
App::PropertyEnumeration
App::PropertyIntegerList
App::PropertyIntegerSet
App::PropertyMap
App::PropertyString
App::PropertyUUID
App::PropertyFont
App::PropertyStringList
App::PropertyLink
App::PropertyLinkSub
App::PropertyLinkList
App::PropertyLinkSubList
App::PropertyMatrix
App::PropertyVector
App::PropertyVectorList
App::PropertyPlacement
App::PropertyPlacementLink
App::PropertyColor
App::PropertyColorList
App::PropertyMaterial
App::PropertyPath
App::PropertyFile
App::PropertyFileIncluded
App::PropertyPythonObject
Part::PropertyPartShape
Part::PropertyGeometryList
Part::PropertyShapeHistory
Part::PropertyFilletEdges
Sketcher::PropertyConstraintList
When adding properties to your custom objects, take care of this:
Do not use characters "<" or ">" in the properties descriptions (that would break the xml pieces in the
.fcstd file)
Properties are stored alphabetically in a .fcstd le. If you have a shape in your properties, any
property whose name comes after "Shape" in alphabetic order, will be loaded AFTER the shape, which
can cause strange behaviours.
Property Type
By default the properties can be updated. It is possible to make the properties read-only, for instance in the
case one wants to show the result of a method. It is also possible to hide the property. The property type
can be set using
obj.setEditorMode("MyPropertyName", mode)
where mode is a short int that can be set to:
0 -- default mode, read and write
1 -- read-only
2 -- hidden
The EditorModes are not set at FreeCAD le reload. This could to be done by the __setstate__ function. See
http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=10#p108072. By using the setEditorMode
the properties are only read only in PropertyEditor. They could still be changed from python. To really make
them read only the setting has to be passed directly inside the addProperty function. See
http://forum.freecadweb.org/viewtopic.php?f=18&t=13460&start=20#p109709 for an example.
v4 = FreeCAD.Vector(fp.Length,fp.Width,0)
v5 = FreeCAD.Vector(fp.Length/2,fp.Width/2,fp.Height/2)
v6 = FreeCAD.Vector(fp.Length/2,fp.Width/2,-fp.Height/2)
# Make the wires/faces
f1 = self.make_face(v1,v2,v5)
f2 = self.make_face(v2,v4,v5)
f3 = self.make_face(v4,v3,v5)
f4 = self.make_face(v3,v1,v5)
f5 = self.make_face(v2,v1,v6)
f6 = self.make_face(v4,v2,v6)
f7 = self.make_face(v3,v4,v6)
f8 = self.make_face(v1,v3,v6)
shell=Part.makeShell([f1,f2,f3,f4,f5,f6,f7,f8])
solid=Part.makeSolid(shell)
fp.Shape = solid
# helper mehod to create the faces
def make_face(self,v1,v2,v3):
wire = Part.makePolygon([v1,v2,v3,v1])
face = Part.Face(wire)
return face
Then, we have the view provider object, responsible for showing the object in the 3D scene:
class ViewProviderOctahedron:
def __init__(self, obj):
"Set this object to the proxy object of the actual view provider"
obj.addProperty("App::PropertyColor","Color","Octahedron","Color of the
octahedron").Color=(1.0,0.0,0.0)
obj.Proxy = self
def attach(self, obj):
"Setup the scene sub-graph of the view provider, this method is mandatory"
self.shaded = coin.SoGroup()
self.wireframe = coin.SoGroup()
self.scale = coin.SoScale()
self.color = coin.SoBaseColor()
self.data=coin.SoCoordinate3()
self.face=coin.SoIndexedLineSet()
self.shaded.addChild(self.scale)
self.shaded.addChild(self.color)
self.shaded.addChild(self.data)
self.shaded.addChild(self.face)
obj.addDisplayMode(self.shaded,"Shaded");
style=coin.SoDrawStyle()
style.style = coin.SoDrawStyle.LINES
self.wireframe.addChild(style)
self.wireframe.addChild(self.scale)
self.wireframe.addChild(self.color)
self.wireframe.addChild(self.data)
self.wireframe.addChild(self.face)
obj.addDisplayMode(self.wireframe,"Wireframe");
self.onChanged(obj,"Color")
def updateData(self, fp, prop):
"If a property of the handled feature has changed we have the chance to
handle this here"
# fp is the handled feature, prop is the name of the property that has
changed
if prop == "Shape":
s = fp.getPropertyByName("Shape")
self.data.point.setNum(6)
cnt=0
for i in s.Vertexes:
self.data.point.set1Value(cnt,i.X,i.Y,i.Z)
cnt=cnt+1
self.face.coordIndex.set1Value(0,0)
self.face.coordIndex.set1Value(1,1)
self.face.coordIndex.set1Value(2,2)
self.face.coordIndex.set1Value(3,-1)
self.face.coordIndex.set1Value(4,1)
self.face.coordIndex.set1Value(5,3)
self.face.coordIndex.set1Value(6,2)
self.face.coordIndex.set1Value(7,-1)
self.face.coordIndex.set1Value(8,3)
self.face.coordIndex.set1Value(9,4)
self.face.coordIndex.set1Value(10,2)
self.face.coordIndex.set1Value(11,-1)
self.face.coordIndex.set1Value(12,4)
self.face.coordIndex.set1Value(13,0)
self.face.coordIndex.set1Value(14,2)
self.face.coordIndex.set1Value(15,-1)
self.face.coordIndex.set1Value(16,1)
self.face.coordIndex.set1Value(17,0)
self.face.coordIndex.set1Value(18,5)
self.face.coordIndex.set1Value(19,-1)
self.face.coordIndex.set1Value(20,3)
self.face.coordIndex.set1Value(21,1)
self.face.coordIndex.set1Value(22,5)
self.face.coordIndex.set1Value(23,-1)
self.face.coordIndex.set1Value(24,4)
self.face.coordIndex.set1Value(25,3)
self.face.coordIndex.set1Value(26,5)
self.face.coordIndex.set1Value(27,-1)
self.face.coordIndex.set1Value(28,0)
self.face.coordIndex.set1Value(29,4)
self.face.coordIndex.set1Value(30,5)
self.face.coordIndex.set1Value(31,-1)
def getDisplayModes(self,obj):
"Return a list of display modes."
modes=[]
modes.append("Shaded")
modes.append("Wireframe")
return modes
def getDefaultDisplayMode(self):
"Return the name of the default display mode. It must be defined in
getDisplayModes."
return "Shaded"
def setDisplayMode(self,mode):
return mode
def onChanged(self, vp, prop):
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.
FreeCAD as App
FreeCADGui
FreeCAD
Part
class Line:
def __init__(self, obj):
'''"App two point properties" '''
obj.addProperty("App::PropertyVector","p1","Line","Start point")
obj.addProperty("App::PropertyVector","p2","Line","End
point").p2=FreeCAD.Vector(100,0,0)
obj.Proxy = self
def execute(self, fp):
'''"Print a short message when doing a recomputation, this method is
mandatory" '''
fp.Shape = Part.makeLine(fp.p1,fp.p2)
class ViewProviderLine:
def __init__(self, obj):
''' Set this object to the proxy object of the actual view provider '''
obj.Proxy = self
def getDefaultDisplayMode(self):
''' Return the name of the default display mode. It must be defined in
getDisplayModes. '''
Further informations
There are a few very interesting forum threads about scripted objects:
- http://forum.freecadweb.org/viewtopic.php?f=22&t=13740
- http://forum.freecadweb.org/viewtopic.php?t=12139
In addition to the examples presented here have
src/Mod/TemplatePyMod/FeaturePython.py for more examples.
look
at
FreeCAD
source
code
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.
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.
Contents
1 Using the FreeCAD 3D view widget directly
2 Creating a soGui Examiner Viewer
3 Using the quarter module
4 Without even firing up the FreeCAD Gui
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-le with QtDesigner , and converting it to python code with
the pyuic tool:
self.gridLayout.addWidget(self.mdiArea, 0, 0, 1, 1)
MainWindow.setCentralWidget(self.centralwidget)
self.menubar = QtGui.QMenuBar(MainWindow)
self.menubar.setGeometry(QtCore.QRect(0, 0, 508, 27))
self.menubar.setObjectName("menubar")
MainWindow.setMenuBar(self.menubar)
self.statusbar = QtGui.QStatusBar(MainWindow)
self.statusbar.setObjectName("statusbar")
MainWindow.setStatusBar(self.statusbar)
self.retranslateUi(MainWindow)
QtCore.QMetaObject.connectSlotsByName(MainWindow)
def retranslateUi(self, MainWindow):
MainWindow.setWindowTitle(QtGui.QApplication.translate("MainWindow", "MainWindow", None, QtGui.QApplication.UnicodeUTF8))
Then, create a main window that should be your application's main window, apply the UI setup above to it in order to add
an MDI area and "move" our 3d view to it
ui=Ui_MainWindow()
my_mw=QtGui.QMainWindow()
ui.setupUi(my_mw)
ui.mdiArea.addSubWindow(v)
my_mw.show()
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)
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...
Contents
1 A typical InitGui.py file
2 A typical module file
3 Import a new filetype
4 Adding a line
5 Adding a polygon
6 Adding and removing an object to a group
7 Adding a Mesh
8 Adding an arc or a circle
9 Accessing and changing representation of an object
10 Observing mouse events in the 3D viewer via Python
11 Display keys pressed and Events command
12 Manipulate the scenegraph in Python
13 Adding and removing objects to/from the scenegraph
14 Adding custom widgets to the interface
15 Adding a Tab to the Combo View
16 Enable or disable a window
17 Opening a custom webpage
18 Getting the HTML contents of an opened webpage
19 Retrieve and use the coordinates of 3 selected points or objects
20 List all objects
21 List the dimension give the name of object
22 Function resident with the mouse click action
23 List the components of an object
24 List the PropertiesList
25 Adding one Property "Comment"
26 Search and data extraction
27 Manual search of an element with label
28 Cartesian coordinates
29 Select all objects in the document
30 Selecting a face of an object
31 Create one object to the position of the Camera
Adding a line
A line simply has 2 points.
import Part,PartGui
doc=App.activeDocument()
# add a line element to the document and set its points
l=Part.Line()
l.StartPoint=(0.0,0.0,0.0)
l.EndPoint=(1.0,1.0,1.0)
doc.addObject("Part::Feature","Line").Shape=l.toShape()
doc.recompute()
Adding a polygon
A polygon is simply a set of connected line segments (a polyline in AutoCAD). It doesn't need to be closed.
import Part,PartGui
doc=App.activeDocument()
n=list()
# create a 3D vector, set its coordinates and add it to the list
v=App.Vector(0,0,0)
n.append(v)
v=App.Vector(10,0,0)
n.append(v)
#... repeat for all nodes
# Create a polygon object and set its nodes
p=doc.addObject("Part::Polygon","Polygon")
p.Nodes=n
doc.recompute()
Adding 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
v=gad.getObject("Cube")
# access the view representation to the Mesh feature 'Cube'
v.ShapeColor
# prints the color to the console
v.ShapeColor=(1.0,1.0,1.0) # sets the shape color to white
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
observation just call
nish the
v.removeEventCallback("SoMouseButtonEvent",c)
The following event types are supported
SoEvent -- all kind of events
SoButtonEvent -- all mouse button and key events
SoLocation2Event -- 2D movement events (normally mouse movements)
SoMotion3Event -- 3D movement events (normally spaceball)
SoKeyboardEvent -- key down and up events
SoMouseButtonEvent -- mouse button down and up events
SoSpaceballButtonEvent -- spaceball button down and up events
The Python function that can be registered with addEventCallback() expects a dictionary. Depending on the watched event
the dictionary can contain different keys.
For all events it has the keys:
Type -- the name of the event type i.e. SoMouseEvent, SoLocation2Event, ...
Time -- the current time as string
Position -- a tuple of two integers, mouse position
ShiftDown -- a boolean, true if Shift was pressed otherwise false
CtrlDown -- a boolean, true if Ctrl was pressed otherwise false
AltDown -- a boolean, true if Alt was pressed otherwise false
For all button events, i.e. keyboard, mouse or spaceball events
State -- A string 'UP' if the button was up, 'DOWN' if it was down or 'UNKNOWN' for all other cases
For keyboard events:
Key -- a character of the pressed key
For mouse button event
Button -- The pressed button, could be BUTTON1, ..., BUTTON5 or ANY
For spaceball events:
Button -- The pressed button, could be BUTTON1, ..., BUTTON7 or ANY
And finally motion events:
Translation -- a tuple of three floats
Rotation -- a quaternion for the rotation, i.e. a tuple of four floats
App.newDocument()
v=Gui.activeDocument().activeView()
class ViewObserver:
def logPosition(self, info):
try:
down = (info["Key"])
FreeCAD.Console.PrintMessage(str(down)+"\n") # here the character pressed
FreeCAD.Console.PrintMessage(str(info)+"\n") # list all events command
FreeCAD.Console.PrintMessage("_______________________________________"+"\n")
except Exception:
None
o = ViewObserver()
c = v.addEventCallback("SoEvent",o.logPosition)
#v.removeEventCallback("SoEvent",c) # remove ViewObserver
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()
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)
dw.setVisible(True)
# True or False
# True or False
+ "\n")
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 __init__(self, view):
self.view = view
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")
pnt = self.view.getPoint(pos)
FreeCAD.Console.PrintMessage("World coordinates: " + str(pnt) + "\n")
info = self.view.getObjectInfo(pos)
FreeCAD.Console.PrintMessage("Object info: " + str(info) + "\n")
o = ViewObserver(v)
c = v.addEventCallback("SoMouseButtonEvent",o.logPosition)
#
#
#
#
import Draft,Part
def detail():
sel = FreeCADGui.Selection.getSelection()
if len(sel) != 0:
Vertx=[]
Edges=[]
Faces=[]
compt_V=0
compt_E=0
compt_F=0
pas
=0
perimetre = 0.0
EdgesLong = []
# Select an object
# If there is a selection then
" + str(sel[0].Label)
for j in enumerate(sel[0].Shape.Edges):
"Edges" and their lengths
compt_E+=1
Edges.append("Edge%d" % (j[0]+1))
EdgesLong.append(str(sel[0].Shape.Edges[compt_E-1].Length))
perimetre += (sel[0].Shape.Edges[compt_E-1].Length)
the perimeter
# Search the
# calculates
: "+str(perimetre)+"\n")
App.Console.PrintMessage("\n")
FacesSurf = []
for j in enumerate(sel[0].Shape.Faces):
the "Faces" and their surface
compt_F+=1
Faces.append("Face%d" % (j[0]+1))
FacesSurf.append(str(sel[0].Shape.Faces[compt_F-1].Area))
# Displays 'Face' and its surface
App.Console.PrintMessage("Face"+str(compt_F)+" >
"+str(sel[0].Shape.Faces[compt_F-1].Area)+"\n")
Surface
Center
# Search
# Search
Coordinate"+str(FacesCoor)+"\n")
Volume
: "+str(sel[0].Shape.Area)+"\n")
: "+str(sel[0].Shape.Volume)+"\n")
detail()
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
object_Label = sel[0].Label
# Label of the object
(modifiable)
App.Console.PrintMessage("object_Label
: "+(object_Label)+"\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
App.Console.PrintMessage("sel
: "+str(sel[0])+"\n\n")
# sel[0] first object
selected
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
object_Name = sel[0].Name
# Name of the object
(not modifiable)
App.Console.PrintMessage("object_Name
: "+str(object_Name)+"\n\n")
##################################################################################
try:
SubElement = FreeCADGui.Selection.getSelectionEx()
# sub element name
with getSelectionEx()
element_ = SubElement[0].SubElementNames[0]
# name of 1 element
selected
App.Console.PrintMessage("elementSelec
: "+str(element_)+"\n\n")
except:
App.Console.PrintMessage("Oups"+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
App.Console.PrintMessage("sel
: "+str(sel[0])+"\n\n")
# sel[0] first object
selected
##################################################################################
SubElement = FreeCADGui.Selection.getSelectionEx()
# sub element name
with getSelectionEx()
App.Console.PrintMessage("SubElement
: "+str(SubElement[0])+"\n\n")
# name of sub element
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
i = 0
for j in enumerate(sel[0].Shape.Edges):
# list all Edges
i += 1
App.Console.PrintMessage("Edges n : "+str(i)+"\n")
a = sel[0].Shape.Edges[j[0]].Vertexes[0]
App.Console.PrintMessage("X1
: "+str(a.Point.x)+"\n")
# coordinate XYZ first
point
App.Console.PrintMessage("Y1
: "+str(a.Point.y)+"\n")
App.Console.PrintMessage("Z1
: "+str(a.Point.z)+"\n")
try:
a = sel[0].Shape.Edges[j[0]].Vertexes[1]
App.Console.PrintMessage("X2
: "+str(a.Point.x)+"\n") # coordinate XYZ
second point
App.Console.PrintMessage("Y2
: "+str(a.Point.y)+"\n")
App.Console.PrintMessage("Z2
: "+str(a.Point.z)+"\n")
except:
App.Console.PrintMessage("Oups"+"\n")
App.Console.PrintMessage("\n")
##################################################################################
try:
SubElement = FreeCADGui.Selection.getSelectionEx()
sub element name with getSelectionEx()
subElementName = Gui.Selection.getSelectionEx()[0].SubElementNames[0]
sub element name with getSelectionEx()
App.Console.PrintMessage("subElementName : "+str(subElementName)+"\n")
#
#
subObjectLength = Gui.Selection.getSelectionEx()[0].SubObjects[0].Length
sub element Length
App.Console.PrintMessage("subObjectLength: "+str(subObjectLength)+"\n\n")
subObjectX1 = Gui.Selection.getSelectionEx()[0].SubObjects[0].Vertexes[0].Point.x
sub element coordinate X1
App.Console.PrintMessage("subObject_X1
: "+str(subObjectX1)+"\n")
subObjectY1 = Gui.Selection.getSelectionEx()[0].SubObjects[0].Vertexes[0].Point.y
sub element coordinate Y1
App.Console.PrintMessage("subObject_Y1
: "+str(subObjectY1)+"\n")
subObjectZ1 = Gui.Selection.getSelectionEx()[0].SubObjects[0].Vertexes[0].Point.z
sub element coordinate Z1
App.Console.PrintMessage("subObject_Z1
: "+str(subObjectZ1)+"\n\n")
subObjectX2 = Gui.Selection.getSelectionEx()[0].SubObjects[0].Vertexes[1].Point.x
sub element coordinate X2
App.Console.PrintMessage("subObject_X2
: "+str(subObjectX2)+"\n")
subObjectY2 = Gui.Selection.getSelectionEx()[0].SubObjects[0].Vertexes[1].Point.y
sub element coordinate Y2
App.Console.PrintMessage("subObject_Y2
: "+str(subObjectY2)+"\n")
subObjectZ2 = Gui.Selection.getSelectionEx()[0].SubObjects[0].Vertexes[1].Point.z
sub element coordinate Z2
App.Console.PrintMessage("subObject_Z2
: "+str(subObjectZ2)+"\n\n")
subObjectBoundBox = Gui.Selection.getSelectionEx()[0].SubObjects[0].BoundBox
sub element BoundBox coordinates
App.Console.PrintMessage("subObjectBBox : "+str(subObjectBoundBox)+"\n")
#
#
subObjectBoundBoxCenter = Gui.Selection.getSelectionEx()[0].SubObjects[0].BoundBox.Center #
sub element BoundBoxCenter
App.Console.PrintMessage("subObjectBBoxCe: "+str(subObjectBoundBoxCenter)+"\n")
surfaceFace = Gui.Selection.getSelectionEx()[0].SubObjects[0].Area
Area of the face selected
App.Console.PrintMessage("surfaceFace
: "+str(surfaceFace)+"\n\n")
except:
App.Console.PrintMessage("Oups"+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
surface = sel[0].Shape.Area
# Area object complete
App.Console.PrintMessage("surfaceObjet
: "+str(surface)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
CenterOfMass = sel[0].Shape.CenterOfMass
# Center of Mass of
the object
App.Console.PrintMessage("CenterOfMass
: "+str(CenterOfMass)+"\n")
App.Console.PrintMessage("CenterOfMassX : "+str(CenterOfMass[0])+"\n")
# coordinates [0]=X
[1]=Y [2]=Z
App.Console.PrintMessage("CenterOfMassY : "+str(CenterOfMass[1])+"\n")
App.Console.PrintMessage("CenterOfMassZ : "+str(CenterOfMass[2])+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
for j in enumerate(sel[0].Shape.Faces):
# List alles faces of
the object
App.Console.PrintMessage("Face
: "+str("Face%d" % (j[0]+1))+"\n")
App.Console.PrintMessage("\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
volume_ = sel[0].Shape.Volume
# Volume of the object
App.Console.PrintMessage("volume_
: "+str(volume_)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
getSelection()
boundBox_= sel[0].Shape.BoundBox
object
App.Console.PrintMessage("boundBox_
: "+str(boundBox_)+"\n")
boundBoxLX = boundBox_.XLength
rectangle
boundBoxLY = boundBox_.YLength
rectangle
boundBoxLZ = boundBox_.ZLength
rectangle
boundBoxDiag= boundBox_.DiagonalLength
boundBox rectangle
# Length x boundBox
# BoundBox of the
# Length y boundBox
# Length z boundBox
# Diagonal Length
App.Console.PrintMessage("boundBoxLX
: "+str(boundBoxLX)+"\n")
App.Console.PrintMessage("boundBoxLY
: "+str(boundBoxLY)+"\n")
App.Console.PrintMessage("boundBoxLZ
: "+str(boundBoxLZ)+"\n")
App.Console.PrintMessage("boundBoxDiag
: "+str(boundBoxDiag)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
pl = sel[0].Shape.Placement
# Placement Vector XYZ
and Yaw-Pitch-Roll
App.Console.PrintMessage("Placement
: "+str(pl)+"\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
pl = sel[0].Shape.Placement.Base
# Placement Vector XYZ
App.Console.PrintMessage("PlacementBase : "+str(pl)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select
getSelection()
Yaw = sel[0].Shape.Placement.Rotation.toEuler()[0]
# decode
Yaw
App.Console.PrintMessage("Yaw
: "+str(Yaw)+"\n")
Pitch = sel[0].Shape.Placement.Rotation.toEuler()[1]
# decode
Pitch
App.Console.PrintMessage("Pitch
: "+str(Pitch)+"\n")
Roll = sel[0].Shape.Placement.Rotation.toEuler()[2]
# decode
Yaw
App.Console.PrintMessage("Roll
: "+str(Roll)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
getSelection()
oripl_X = sel[0].Placement.Base[0]
oripl_Y = sel[0].Placement.Base[1]
oripl_Z = sel[0].Placement.Base[2]
object with
angle Euler
angle Euler
angle Euler
App.Console.PrintMessage("oripl_X
: "+str(oripl_X)+"\n")
App.Console.PrintMessage("oripl_Y
: "+str(oripl_Y)+"\n")
App.Console.PrintMessage("oripl_Z
: "+str(oripl_Z)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
rotation = sel[0].Placement.Rotation
# decode Placement
Rotation
App.Console.PrintMessage("rotation
: "+str(rotation)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
pl = sel[0].Shape.Placement.Rotation
# decode Placement
Rotation other method
App.Console.PrintMessage("Placement Rot
: "+str(pl)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
# select object with
getSelection()
pl = sel[0].Shape.Placement.Rotation.Angle
# decode Placement
Rotation Angle
App.Console.PrintMessage("Placement Rot Angle
: "+str(pl)+"\n\n")
##################################################################################
sel = FreeCADGui.Selection.getSelection()
getSelection()
Rot_0 = sel[0].Placement.Rotation.Q[0]
Rotation 0
App.Console.PrintMessage("Rot_0
: "+str(Rot_0)+ " rad ,
deg "+"\n")
Rot_1 = sel[0].Placement.Rotation.Q[1]
Rotation 1
App.Console.PrintMessage("Rot_1
deg "+"\n")
Rot_2 = sel[0].Placement.Rotation.Q[2]
Rotation 2
App.Console.PrintMessage("Rot_2
deg "+"\n")
Rot_3 = sel[0].Placement.Rotation.Q[3]
# decode Placement
Rotation 3
App.Console.PrintMessage("Rot_3
: "+str(Rot_3)+"\n\n")
##################################################################################
Cartesian coordinates
This code displays the Cartesian coordinates of the selected item.
Change the value of "numberOfPoints" if you want a different number of points (precision)
numberOfPoints = 100
number (or precision you can change)
selectedEdge = FreeCADGui.Selection.getSelectionEx()[0].SubObjects[0].copy()
element
points = selectedEdge.discretize(numberOfPoints)
element
i=0
for p in points:
the coordinates
i+=1
print i, " X", p.x, " Y", p.y, " Z", p.z
# Decomposition
# select one
# discretize the
# list and display
# 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
print ii, ": X:", i.x, " Y:", i.y, " Z:", i.z
Draft.makeWire(p2,closed=False,face=False,support=None)
# Vector()
# Vector decode
# 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"
#
#
#
#
#
objet
face to selection
objet
clear all selection
select the face specified
a = a.split(" ")
####### extract data
#print
#print
#print
#print
#print
xP
yP
zP
qP
=
=
=
=
a
a[0]
a[1]
a[2]
a[3]
float(a[0])
float(a[1])
float(a[2])
float(a[3])
pl = FreeCAD.Placement()
pl.Rotation.Q = (xP,yP,zP,qP)
# rotation of object
pl.Base = FreeCAD.Vector(0.0,0.0,0.0) # here coordinates XYZ of Object
rec = Draft.makeRectangle(length=10.0,height=10.0,placement=pl,face=False,support=None) # create
rectangle
#rec = Draft.makeCircle(radius=5,placement=pl,face=False,support=None)
#
create circle
print rec.Name
here same code simplified
import Draft
pl = FreeCAD.Placement()
pl.Rotation = FreeCADGui.ActiveDocument.ActiveView.getCameraOrientation()
pl.Base = FreeCAD.Vector(0.0,0.0,0.0)
rec = Draft.makeRectangle(length=10.0,height=10.0,placement=pl,face=False,support=None)