This is the FreeCAD manual. It includes the essential parts out of the FreeCAD documentation wiki. It is made primarily to be printed as one big document, so, if you are reading this online, you might prefer to head directly to the Online help version, which is easier to browse.
The FreeCAD help system is hosted on a wiki built, maintained and developed by the FreeCAD community of users and developers. It contains general information about FreeCAD, tutorials, precise documentation about each FreeCAD command, and programming documentation for Python and C++. It also contains translations of this documentation in several languages. We hope you will find here all the information you need. In case you have questions you can't find answers to in this documentation, have a look at the FreeCAD forum, where you might find your question answered already, or find someone able to help you.
Python scripting, for power-users who are interested by the scripting capabilities of FreeCAD and would like to customize some of its aspects.
Development guidelines, for developers who consider FreeCAD as a base for developing their own applications.
Many pages of this wiki are also grouped into an easier to read Manual. If you are new to FreeCAD, we suggest you start reading the manual.
Contribute
As you may have experienced sometimes, programmers are sometimes bad documentation writers! It is therefore vital that experienced users help to write, update, fix and revise the documentation. Yes, we mean you! Editing the wiki is easy. As this wiki is write-protected to reduce spamming, you will need a FreeCAD wiki account to log in. Ask on the forum and we will create an account for you. Currently, the wiki account is separate from the forum account but we will create you a wiki account with the same name as your forum account. Then you can start editing! Also, check out this page for more ways you can help FreeCAD.
FreeCAD is a general purpose open source parametric 3D CAD modeler licensed under the LGPL License. FreeCAD is aimed directly at mechanical engineering and product design but, being very generic, also fits in a wider range of uses around engineering, such as architecture, finite element analysis, 3D printing, and other tasks.
FreeCAD features tools similar to CATIA, SolidWorks, Solid Edge or Revit, and therefore also falls into the category of CAD, PLM, CAx, CAE and BIM. It is a feature based parametric modeler with a modular software architecture making it possible to provide additional functionality without modifying the core system.
As with other CAD modelers it has many 2D components in order to sketch planar shapes or create production drawings. However, direct 2D drawing (like Inkscape or AutoCAD LT) is not the focus, neither are animation or mesh editing (like Blender, Maya, 3ds Max, or Cinema 4D). Nevertheless, thanks to its wide adaptability, FreeCAD is useful in a much broader area around its base feature set.
FreeCAD makes heavy use of open-source libraries that exist in the field of scientific computing. Among them are Open Cascade Technology (OCCT), a powerful CAD kernel; Coin3D, a toolkit for 3D graphics development compatible with Open Inventor; Qt, the world-famous user interface framework; and Python, a modern scripting language. FreeCAD itself can also be used as a library by other programs.
FreeCAD is also multi-platform, and currently runs on Linux/Unix, Windows, and macOS systems with the same look and functionality on all platforms.
The FreeCAD project was started as far back as 2001, as described on the history page.
FreeCAD is maintained and developed by a community of enthusiastic developers and users and is built through the patient work of hundreds of contributors, some regular, some occasional. Most work on FreeCAD as volunteers. The FreeCAD forum is where most of the ideas and decisions are discussed, and the GitHub repository is where the code is being kept, shared, discussed and worked on. Anybody is welcome to participate.
About the FPA
The FreeCAD project is also supported by a non-profit organization, the FreeCAD project association (FPA). The FPA is an independent body created by some FreeCAD veterans in 2021 to collect donations and other resources to support the project and its community, to help protect that community and allow it to continue developing in the best conditions, and to represent the project against other bodies such as companies and institutions.
A full parametric model. All FreeCAD objects are natively parametric, meaning their shape can be based on properties or even depend on other objects. All changes are recalculated on demand, and recorded by an undo/redo stack. New object types can be added easily, and can even be fully programmed in Python.
A modular architecture that allows plugin extensions (modules) to add functionality to the core application. An extension can be as complex as a whole new application programmed in C++ or as simple as a Python script or self-recorded macro. You have complete access to almost any part of FreeCAD from the built-in Python interpreter, macros or external scripts, be it 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, DAE, IFC or OFF, NASTRAN, VRML in addition to FreeCAD's native FCStd file format. The level of compatibility between FreeCAD and a given file format can vary, since it depends on the module that implements it.
A Sketcher with integrated constraint-solver, allowing you to sketch geometry-constrained 2D shapes. The constrained 2D shapes built with Sketcher may then be used as a base to build other objects throughout FreeCAD.
A technical drawing module with options for detail views, cross sectional views, dimensioning and others, allowing you to generate 2D views of existing 3D models. The module then produces ready-to-export SVG or PDF files.
A Path module dedicated to mechanical machining for Computer Aided Manufacturing (CAM). Using the Path module you may output, display and adjust the G code used to control the target machine.
multi-platform. FreeCAD runs and behaves exactly the same way on Windows, Linux, macOS and other platforms.
full GUI application. FreeCAD has a complete Graphical User Interface based on the Qt framework, with a 3D viewer based on Open Inventor; allowing fast rendering of 3D scenes and a very accessible scene graph representation.
runs as a command line application. In command line mode, FreeCAD runs without its interface but with all its geometry tools. In this mode it has a relatively low memory footprint and can be used, for example, as a server to produce content for other applications.
can be imported as a Python module. FreeCAD can be imported into any application that can run Python scripts. As in command line 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 you to display only the tools used to accomplish a certain task, keeping the workspace uncluttered and responsive, and allowing the application to load rapidly.
plugin/module framework for late loading of features/data-types. FreeCAD is divided into a core application with modules that are loaded only when needed. Almost all tools and geometry types are stored in modules. Modules behave like plugins; in addition to delayed loading, individual modules can be added to or removed from an existing installation of FreeCAD.
parametric associative document objects. All objects in a FreeCAD document can be defined by parameters. Those parameters can be modified and recomputed at any time. Since object relationships are maintained, the modification of one object will automatically propagate to any dependent objects.
parametric primitive creation. Primitive objects such as box, sphere, cylinder, etc. can be created by specifying their geometry constraints.
graphical modification operations. FreeCAD can perform translation, rotation, scaling, mirroring, offset (either trivial or as described in Jung/Shin/Choi) or shape conversion, in any plane of the 3D space.
Constructive solid geometry (boolean operations). FreeCAD can do constructive solid geometry operations (union, difference, intersect).
graphical creation of planar geometry. Lines, wires, rectangles, B-splines, and circular or elliptic arcs can be created graphically in any plane of the 3D space.
modeling with straight or revolvedextrusions, sections and fillets.
topological components like vertices, edges, wires and planes.
testing and repairing. FreeCAD has tools for testing meshes (solid test, non-two-manifolds test, self-intersection test) and for repairing meshes (hole filling, uniform orientation).
annotations. FreeCAD can insert annotations for text or dimensions.
Undo/Redo framework. Everything in FreeCAD is undo/redoable, with user access to the undo stack. Multiple steps can be undone at one time.
transaction oriented. The undo/redo stack stores document transactions, 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, with 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 complex scripts as well as single commands; entire modules can be programmed completely in Python.
built-in Python console. The Python interpreter includes a console with syntax highlighting, autocomplete and a class browser. Python commands can be issued directly in FreeCAD and immediately return results, permitting script writers to test functionality on the fly, explore the contents of FreeCAD's modules and easily learn about FreeCAD internals.
mirrors user interaction. 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 and editing capabilities. The Python commands issued when the user manipulates the interface can be recorded, edited if needed, and saved to be reproduced later.
compound (ZIP based) document save format. FreeCAD documents are saved with a .FCStd extension. The document can contain many different types of information such as geometry, scripts or thumbnail icons. The .FCStd file is itself a zip container; 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 simple functions FreeCAD itself provides to workbenches, the entire Qt framework is accessible. The user may perform any operation on the GUI such as creating, adding, docking, modifying or removing widgets and toolbars.
thumbnailer. (currently only Linux systems) FreeCAD document icons show the contents of the file in most file manager applications such as Gnome's Nautilus.
modular MSI installer. FreeCAD's installer allows flexible installations on Windows systems. Packages for Ubuntu systems are also maintained.
See FreeCAD's debian copyright file for more details about the licenses used by the different open-source components used in FreeCAD
Impact of the licenses
Below is a friendlier explanation of what the LGPL license means for you:
All users
Anybody can download, use and redistribute FreeCAD free of charge, without any restriction. Your copy of FreeCAD is truly yours, as are the files you produce with FreeCAD. You will not be forced to update FreeCAD after a certain time, nor change your usage of FreeCAD. Using FreeCAD doesn't bind you to any kind of contract or obligation. The FreeCAD source code is public and can be inspected, so it is possible to verify that it doesn't do things without your knowledge such as sending your private data somewhere.
Professional users
FreeCAD can be used freely for any kind of purpose, being private, commercial or institutional. Any version of FreeCAD can be deployed and installed anywhere, any number of times. You can also modify and adapt FreeCAD for your own purposes without any restriction. However, you cannot make the FreeCAD developers liable for possible damage or business loss that could occur from using FreeCAD.
Open-source software developers
You can use FreeCAD as a base to develop your own application, or simply extend it by creating new modules for it. If FreeCAD is embedded into your own application, you can choose either the GPL or the LGPL license, or any other license that is compatible with LGPL, to allow the use of your work in proprietary software or not. If you are developing a module to be used as an extension, and don't include any of the FreeCAD code in it, then you can choose any license you want. However, if you wish to see your module integrated into FreeCAD one day, it is a good idea to use the same LGPL license as FreeCAD itself, as FreeCAD will only accept code with LGPL, MIT or BSD licenses.
Closed-source software developers
The LGPL license allows you to use FreeCAD as a component for your own application, and you are not forced to make your application open source. You will get support from the FreeCAD developers as long as it is not a 'one way street'. The license states however two important conditions:
1) You must clearly inform your users that your application is using FreeCAD and that FreeCAD is LGPL.
2) The LGPL license also stipulate your users must be able to swap your modified FreeCAD component with the original FreeCAD equivalent. That is would be done by dynamically linking to the FreeCAD components, so users are allowed to change it. However, this is often hard to achieve by today's requirements. At FreeCAD, we understand that the important point here is to not restrict the freedom given to FreeCAD users by the LGPL license. So an equivalent to dynamic linking is to offer the choice to your users, by making your users aware of the possibility to use FreeCAD for free. This can be done in a number of ways.
If any of the two conditions above are unacceptable to you or cannot be implemented, then you must make your FreeCAD component LGPL too and release the source code with all the modifications you made to it.
There is a special case called derivatives, which is when you publish basically a "rebranded" version of FreeCAD. Derivatives which are not open-source are prohibited by the LGPL license. The FreeCAD community is active and efficient in finding rebranded versions, reporting them to the platforms where they were found and exposing them until they are taken down.
Files
The models and other files produced with FreeCAD are not subject to any license stated above, nor bound to any kind of restriction or ownership. Your files are truly yours. You can set the owner of the file and specify your own license terms for the files you produce inside FreeCAD, via menu File → Project Information.
Logo
The FreeCAD logo is a trademark owned by the FPA (FreeCAD project association). This means the FPA is the sole body authorized to say who has the right to use the FreeCAD logo or not. The logo files, which are part of the FreeCAD source code or available elsewhere, for example on this wiki, are still all under the same licenses as the rest of FreeCAD (LGPL for the source code and Creative Commons for this wiki). You are still free to use the FreeCAD logo anywhere, on the same terms as the rest of FreeCAD, which means, basically, that you must use it to reference FreeCAD, and not use it, for example, for your own product, or any other way that is not referencing FreeCAD.
Statement of the main developer
I know that the discussion on the "right" license for open source occupied a significant portion of internet bandwidth and so is here the reason why, in my opinion, FreeCAD should have this one.
I chose the LGPL for the project and I know the pro and cons about the LGPL and will give you some reasons for that decision.
FreeCAD is a mixture of a library and an application, so the GPL would be a little bit strong for that. It would prevent writing commercial modules for FreeCAD because it would prevent linking with the FreeCAD base libs. You may ask why commercial modules at all? Therefore Linux is good example. Would Linux be so successful when the GNU C Library would be GPL and therefore prevent linking against non-GPL applications? And although I love the freedom of Linux, I also want to be able to use the very good NVIDIA 3D graphic driver. I understand and accept the reason NVIDIA does not wish to give away driver code. We all work for companies and need payment or at least food. So for me, a coexistence of open source and closed source software is not a bad thing, when it obeys the rules of the LGPL. I would like to see someone writing a Catia import/export processor for FreeCAD and distribute it for free or for some money. I don't like to force him to give away more than he wants to. That wouldn't be good neither for him nor for FreeCAD.
Nevertheless this decision is made only for the core system of FreeCAD. Every writer of an application module may make his own decision.
The easiest way to install the latest stable version of FreeCAD is to use the installer, see the Download page.
If you would like to download a development version, which may be unstable, see the Weekly builds download page.
After downloading the installer, double-click it to start the installation process.
Below is more information about some technical options. But most users don't need more than the installer. Head to Getting started once installation is complete.
Installation for all users of the Windows system
By default FreeCAD will be installed for the user that executes the installer. If this user only has user permissions, the default installation path is:
If the installer is executed by an admin user, or you execute it as admin, you can choose if FreeCAD should be installed for all users of the system or just for you. The default is for all users.
If installed for all users, the default installation path is:
C:\Program Files\FreeCAD X.YY
Silent Installation
To install FreeCAD silently, you can execute the installer from the command line:
</translate>
FreeCAD-~.exe /S
<translate>
Default settings will be used for all options. A custom installation path can be specified in this manner:
</translate>
FreeCAD-~.exe /S /D=A path to FreeCAD with spaces
<translate>
By default, even with silent installations, there will be a short popup when the installer is checked for corruption. This so-called cyclic redundancy check only takes a few seconds at most. To disable this corruption check:
</translate>
FreeCAD-~.exe /S /NCRC
<translate>
Note that this /NCRC flag is not recommended since the corruption check assures that the installer was e.g. completely downloaded.
Chocolatey
Using the Chocolatey package manager is currently not recommended as that repository is no longer kept up-to-date.
Uninstallation
To uninstall FreeCAD it is preferable to use the Windows tools for uninstalling software. Alternatively you can execute the uninstaller directly. This is the file:
Uninstall-FreeCAD.exe
You can find it in the folder where FreeCAD is installed.
The uninstaller can also be executed silently using the command line:
</translate>
Uninstall-FreeCAD.exe /S
<translate>
Note that (silent) uninstallation will fail if there is a running instance of FreeCAD, even if that instance is not the version being uninstalled.
The installation of FreeCAD on most well-known Linux systems is endorsed by the community, and FreeCAD is available via the package manager on those systems. The FreeCAD team also provides some:
Experimental or 'bleeding edge' builds available via PPA daily repository, AppImages, Ubuntu Snaps.
</translate>
<translate>
Ubuntu and Ubuntu-based systems
Many Linux distributions are based on Ubuntu and share its repositories. Besides official variants (Kubuntu, Lubuntu and Xubuntu), there are non official derivatives like Linux Mint, Voyager and others. The installation options below (Expand) should be compatible with these systems.
</translate>
<translate>
Official version
FreeCAD is available from the Ubuntu Universe repository, and can be installed via the Software Center or from the terminal:
</translate>
sudoaptinstallfreecad
<translate>
Note: the Ubuntu Universe package may be outdated as the packaging may lag behind the latest stable source code. In this case, it is suggested to install the package from the -stable PPA below. In addition, installing the -daily package can be done to test the development branch.
Stable PPA version
Warning: The FreeCAD PPA is currently unmaintained and looking for volunteers. Please use an alternative (snap, appimage) until the issue is fixed!
Personal Package Archive (PPA) for the stable FreeCAD release is maintained by the FreeCAD community on Launchpad. The Launchpad repository is called FreeCAD Stable Releases .
GUI
Install the stable PPA via the Graphical User Interface (GUI):
1. Navigate to Ubuntu Software → Software & Updates → Software Sources → Other Software
2. Click on Add, then copy and paste the following line
</translate>
ppa:freecad-maintainers/freecad-stable
<translate>
3. Add the source, close the dialog, and reload your software sources, if asked.
Now you can find and install the last stable FreeCAD version from the Ubuntu Software Center.
CLI
Install the stable PPA via the Command Line Interface (CLI):
3. Then install FreeCAD along with its offline documentation:
</translate>
sudoaptinstallfreecadfreecad-doc
<translate>
Note: due to packaging problems, in certain versions of Ubuntu the freecad-doc package has collided with the installation of FreeCAD or one of its dependencies; if this is the case, remove the freecad-doc package, and only install the freecad package. If the freecad-doc package doesn't exist, then ignore it.
Checking Installation
4. Once you have the stable PPA added to your sources using one of the above methods, the freecad package will install this PPA version over the one provided by the Ubuntu Universe repository. You can see the available versions with the following apt-cache command:
</translate>
apt-cachepolicyfreecad
<translate>
The output should look similar to the following (of course the version info will vary):
5. Invoke the stable (PPA) version of FreeCAD from the GUI or CLI. The latter method is as follows:
</translate>
./freecad
<translate>
Development PPA (Daily)
As FreeCAD is in constant development, you may wish to install the daily package to keep with the latest improvements and bug fixes. The repository is also hosted on Launchpad and is called freecad-daily.
This version is compiled daily from the official master repository. Please beware that although it will contain new features and bug fixes, it may also have newer bugs, and be unstable.
Add the daily PPA to your software sources, update the package lists, and install the daily package:
</translate>
Every day you can update to the latest daily:
</translate>
sudoapt-getupdatesudoapt-getinstallfreecad-daily
<translate>
Note: in some cases new code or dependencies added to FreeCAD will cause packaging errors; if this happens, a daily package may not be generated until the maintainers manually fix the problems. If you wish to continue testing the latest code, you should get the source code and compile FreeCAD directly; for instructions see compiling.
Run the daily (PPA) version of FreeCAD:
</translate>
freecad-daily
<translate>
Note: it is possible to install both the -stable and -daily packages in the same system. This is useful if you wish to work with a stable version, and still be able to test the latest features in development. Notice that the executable for the daily version is freecad-daily, but for the stable version it is just freecad.
</translate>
<translate>
Debian and other Debian-based systems
Since Debian Lenny, FreeCAD is available directly from the Debian software repositories and can be installed via synaptic or simply with:
</translate>
sudoapt-getinstallfreecad
<translate>
</translate>
<translate>
OpenSUSE
FreeCAD is typically installed with YAST (abbr. Yet another Setup Tool) the Linux operating system setup and configuration tool, or in any terminal/console (root rights required) with:
</translate>
zypperinstallFreeCAD
<translate>
Note: This procedure only covers the installation of officially released stable FreeCAD program versions, depending on the installed links to the program package repositories of your OS version. The openSUSE package may be outdated as the packaging may lag behind the latest stable source code. In this case, it is suggested to install the package manually from the below indicated (Expand) source repositories.
</translate>
<translate>
A vast release program for FreeCAD package builds are offered. Please visit for a survey:
Generally for selecting the correct openSUSE distribution needed it is necessary to click on the particular View button.
Stable
The stable package version: Stable repositories on openSUSE. The correct openSUSE distribution version must be selected in the lower part of the web page.
It is recommended to grab the binary packages directly. Then select the correct distribution for your installed openSUSE OS.
</translate>
<translate>
Gentoo
FreeCAD can be built/installed simply by issuing:
</translate>
emergefreecad
<translate>
</translate>
<translate>
Fedora
FreeCAD has been included in the official Fedora packages since Fedora 20. It can be installed from the command line with:
</translate>
sudodnfinstallfreecad
<translate>
</translate>
<translate>
On older Fedora releases, that was:
</translate>
sudoyuminstallfreecad
<translate>
The gui packages managers can also be used. Search for </translate>"freecad".<translate>
The official release package version tends to be well behind the FreeCAD releases. Package: freecad shows the versions included in the Fedora repositories over time and versions.
More current versions can be obtained by downloading one of the </translate>.AppImage<translate>
releases from the github repository. These work fine on Fedora.
If you want to keep up with the absolute latest daily builds, FreeCAD is also available on </translate>copr<translate>
. To install the build from there, in a terminal session, enter:
That leaves the </translate>copr<translate>
repository active, so
</translate>
sudodnfupgrade
<translate>
or equivalent, will update to the latest FreeCAD build, along with updates from any of the other active repos. If you want something a bit more stable, you can disable </translate>@freecad/nightly<translate> again after the initial install. The </translate>copr<translate>
repository only keeps builds from the past 2 weeks. This is not a solution if you want to pick a specific older version.
Instructions are also available on compile FreeCAD yourself, including a script specifically for Fedora. With a minor change, to checkout the specific commit from git, any version since about FreeCAD 0.15 can be built on any distribution since Fedora 21.
</translate>
<translate>
Arch
Installing FreeCAD on Arch Linux and derivatives (ex. Manjaro):
</translate>
pacman-Sfreecad
<translate>
Other
If you find out that your system features FreeCAD but is not documented in this page, please tell us on the forum!
Many alternative, non-official FreeCAD packages are available on the net, for example for systems like slackware or fedora. A search on the net can quickly give you some results.
Installing on other Linux/Unix systems
Many common Linux distros now include a precompiled FreeCAD as part of the standard packages. This is often out of date, but is a place to start. Check the standard package managers for your system. One of the following (partial) list of commands could install the official version of FreeCAD for your distro from the terminal. These probably need administrator privileges.
The package name is case sensitive, so try `FreeCAD` as well as `freecad`. If that does not work for you, either because your package manager does not have a precompiled FreeCAD version available, or because the available version is too old for your needs, you can try installing the Flatpak or Snap packages (these work on most x86_64 Linux distributions) or try downloading one of the </translate>.AppImage<translate>
releases from the github repository. These also tend to work on most x86_64 Linux distributions, without any special installation. Just make sure the downloaded file is marked as executable, then run it.
If that still is not good enough, and you cannot locate another source of a precompiled package for your situation, you will need to compile FreeCAD yourself.
FreeCAD is a 3D 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 has been under development since 2002, and it offers a large list of features. Capabilities are still missing but it is powerful enough for hobbyist use, and small workshops. There is a fast-growing community of enthusiastic users who participate in the FreeCAD forum, and you can find many examples of quality projects developed with FreeCAD there. See also, FreeCAD used in production.
Like all free software projects, FreeCAD depends on its community to grow, gain features, and fix bugs. Don't forget this when using FreeCAD; if you like it, you can donate and help FreeCAD in various ways, such as writing documentation and making translations.
First of all, download and install FreeCAD. See the Download page for information on current versions and updates, and the installation instructions for you operating system (Windows, Linux or macOS). FreeCAD is available from the package managers of many Linux distributions. As FreeCAD is open-source, you can also grab the source code and compile it yourself.
1. The main view area, which can contain different tabbed windows, principally the 3D view.
2. The 3D view, showing the geometrical objects in the document.
3. The tree view (part of the combo view), showing the hierarchy and construction history of objects in the document; it can also display the task panel for active commands.
4. The property editor (part of the combo view), which allows viewing and modifying properties of the selected objects.
5. The selection view, which indicates the objects or sub-elements of objects (vertices, edges, faces) that are selected.
6. The report view (or output window), where messages, warnings and errors are shown.
7. The Python console, where all the commands executed are printed, and where you can enter Python code.
8. The status bar, where some messages and tooltips appear.
9. The toolbar area, where the toolbars are docked.
11. The standard menu, which holds basic operations of the program.
The main concept behind the FreeCAD interface is that it is separated into workbenches. A workbench is a collection of tools suited for a specific task, such as working with meshes, or drawing 2D objects, or constrained sketches. You can switch the current workbench with the workbench selector. You can customize the tools included in each workbench, add tools from other workbenches or even self-created tools, that we call macros. Widely used starting points are the PartDesign Workbench and Part Workbench.
When you start FreeCAD for the first time, you are presented with the Start page. Here is what it looks like for version 0.19:
The Start page allows you to quickly jump to one of the most common workbenches, open one of the recent files, or see the latest news from the FreeCAD world. You can change the default workbench in the preferences.
Navigating in the 3D space
FreeCAD has several navigation modes available, that change the way you use your mouse to interact with the objects in the 3D view and the view itself. One of them is specifically made for touchpads, where the middle mouse button is not used. The default navigation mode is CAD navigation. You can quickly change the current navigation mode by using the button in the Status bar or by right-clicking an empty area of the 3D view.
You also have several view presets (top view, front view, etc) available in the View menu, on the View toolbar, and by numeric shortcuts (1, 2, etc...). By right-clicking on an object or on an empty area of the 3D view, you have quick access to some common operations, such as setting a particular view, or locating an object in the Tree view.
First steps with FreeCAD
FreeCAD's focus is to allow you to make high-precision 3D models, to keep tight control over those models (being able to go back into modelling history and change parameters), and eventually to build those models (via 3D printing, CNC machining or even construction worksite). It is therefore very different from some other 3D applications made for other purposes, such as animation film or gaming. Its learning curve can be steep, especially if this is your first contact with 3D modeling. If you are stuck at some point, don't forget that the friendly community of users on the FreeCAD forum might be able to get you out in no time.
The workbench you will start using in FreeCAD depends on the type of job you need to do: If you are going to work on mechanical models, or more generally any small-scale objects, you'll probably want to try the PartDesign Workbench. If you will work in 2D, then switch to the Draft Workbench, or the Sketcher Workbench if you need constraints. If you want to do BIM, launch the Arch Workbench. And if you come from the OpenSCAD world, try the OpenSCAD Workbench. There are also many community-developed external workbenches available.
You can switch workbenches at any time, and also customize your favorite workbench to add tools from other workbenches.
Working with the PartDesign and Sketcher workbenches
The PartDesign Workbench is made to build complex objects, starting from simple shapes, and adding or removing pieces (called "features"), until you get to your final object. All the features you applied during the modelling process are stored in a separate view called the tree view, which also contains the other objects in your document. You can think of a PartDesign object as a succession of operations, each one applied to the result of the preceding one, forming one big chain. In the tree view, you see your final object, but you can expand it and retrieve all preceding states, and change any of their parameter, which automatically updates the final object.
The PartDesign workbench makes heavy use of another workbench, the Sketcher Workbench. The sketcher allows you to draw 2D shapes, which are defined by applying Constraints to the 2D shape. For example, you might draw a rectangle and set the size of a side by applying a length constraint to one of the sides. That side then cannot be resized anymore (unless the constraint is changed).
Those 2D shapes made with the sketcher are used a lot in the PartDesign workbench, for example to create 3D volumes, or to draw areas on the faces of your object that will then be hollowed from its main volume. This is a typical PartDesign workflow:
Create a new sketch
Draw a closed shape (make sure all points are joined)
Close the sketch
Expand the sketch into a 3D solid by using the pad tool
Select one face of the solid
Create a second sketch (this time it will be drawn on the selected face)
Draw a closed shape
Close the sketch
Create a pocket from the second sketch, on the first object
Which gives you an object like this:
</translate>
<translate>
At any moment, you can select the original sketches and modify them, or change the extrusion parameters of the pad or pocket operations, which will update the final object.
Working with the Draft and Arch workbenches
The Draft Workbench and Arch Workbench behave a bit differently than the other workbenches above, although they follow the same rules, which are common to all of FreeCAD. In short, while the Sketcher and PartDesign are made primarily to design single pieces, Draft and Arch are made to ease your work when working with several, simpler objects.
The Draft Workbench offers you 2D tools somewhat similar to what you can find in traditional 2D CAD applications such as AutoCAD. However, 2D drafting being far away from the scope of FreeCAD, don't expect to find there the full array of tools that these dedicated applications offer. Most of the Draft tools work not only in a 2D plane but also in the full 3D space, and benefit from special helper systems such as Work planes and object snapping.
The Arch Workbench adds BIM tools to FreeCAD, allowing you to build architectural models with parametric objects. The Arch workbench relies extensively on other modules such as Draft and Sketcher. All the Draft tools are also present in the Arch workbench, and most Arch tools make use of the Draft helper systems.
A typical workflow with Arch and Draft workbenches might be:
Draw a couple of lines with the Draft Line tool
Select each line and press the Wall tool to build a wall on each of them
Join the walls by selecting them and pressing the Arch Add tool
Create a floor object, and in the Tree view drag your walls into the floor object
Create a building object, and in the Tree view drag your floor (which now includes the walls) into the building object
Create a window by clicking the Window tool, select a preset in its panel, then click on a face of a wall
Add dimensions by first setting the working plane if necessary, then using the Draft Dimension tool
Any user can develop their own new features for FreeCAD and make them available to the FreeCAD community as an addon.
There are three types of addons:
Macros: short snippet of Python code that provides a new tool or functionality in a single file ending with .FCMacro.
Workbenches: collections of Python files that provide related Gui Commands (tools) centered around a particular topic.
Preference Packs: distributable collections of user preferences.
Scripting
And finally, one of the most powerful features of FreeCAD is the scripting environment. From the integrated python console (or from any other external Python script), you can gain access to almost any part of FreeCAD, create or modify geometry, modify the representation of those objects in the 3D scene or access and modify the FreeCAD interface. Python scripting can also be used in macros, which provide an easy method to create custom commands.
What's new
See the release notes for the detailed list of features.
The FreeCAD mouse navigation consists of the commands used to visually navigate 3D space and interact with the displayed objects. FreeCAD supports multiple mouse navigation styles. The default navigation style is referred to as CAD Navigation, and is very simple and practical, but FreeCAD also provides several alternative navigation styles to choose from. The selected style is used for all workbenches.
If the CAD navigation style is selected: optionally change the Enable animation setting. See Preferences Editor.
Available navigation styles
With all navigation styles, unless selecting objects from a sketch in edit mode, you must hold Ctrl to select multiple objects.
Blender navigation
The Blender navigation style was modeled after Blender.
Select
Pan
Zoom
Rotate view
Shift+
Press the left mouse button over an object you want to select.
Hold Shift and the middle mouse button, then move the pointer.
Alternatively, hold both left and right mouse buttons, and then move the pointer.
Use the mouse wheel to zoom in and out.
Hold the middle mouse button, then move the pointer.
CAD navigation
This is the default navigation style. It allows the user a simple control of the view, and does not require the use of keyboard keys except to make multi-selections.
Select
Pan
Zoom
Rotate view First method
Rotate view Alternate method
Press the left mouse button over an object you want to select.
Hold the middle mouse button, then move the pointer.
Use the mouse wheel to zoom in and out.
Clicking the middle mouse button re-centers the view on the location of the cursor.
Hold the middle mouse button, then press and hold the left mouse button, then move the pointer.
If the buttons are released before you stop the mouse motion, the view continues spinning, if this is enabled.
A double click with the middle mouse button sets a new center of rotation.
Hold the middle mouse button, then press and hold the right mouse button, then move the pointer.
With this method the middle mouse button may be released after the right mouse button is held pressed.
Users who use the mouse with their right hand may find this method easier than the first method.
Ctrl+
Ctrl+Shift+
Shift+
Pan mode: hold the Ctrl key, press the right mouse button once, then move the pointer.
Zoom mode: hold the Ctrl and Shift keys, press the right mouse button once, then move the pointer.
Rotate mode: hold the Shift key, press the right mouse button once, then move the pointer.
Gesture navigation
This style was tailored for use with a touchscreen and pen. Nevertheless, it can also be used with a mouse, and is recommended for use when using a Mac with a trackpad.
Select
Pan
Zoom
Rotate view
Tilt view
Press the left mouse button over an object you want to select.
Hold the right mouse button, then move the pointer.
Use the mouse wheel to zoom in and out.
Hold the left mouse button, then move the pointer.
In Sketcher and other edit modes, this behavior is disabled. Hold Alt when pressing the mouse button to enter rotation mode.
To set the camera's focus point for rotation, click a point with the middle mouse button. Alternatively, aim the cursor at a point and press H on the keyboard.
Hold both left and right mouse buttons, then move the pointer sideways.
Tap to select.
Drag with two fingers.
Alternatively, tap and hold, then drag. This simulates the pan with the right mouse button.
Rotate the imaginary line formed by two touch points.
This method is disabled by default. To enable, go to Edit → Preferences → Display → Navigation, and uncheck the "Disable touchscreen tilt gesture" checkbox.
Maya-Gesture navigation
In Maya-Gesture Navigation, panning, zooming, and rotating the view require the Alt key together with a mouse button; therefore, a three-button mouse is required. It's also possible to use gestures as this style was developed over the Gesture navigation style.
Select
Pan
Zoom
Rotate view
Alt+
Alt+
Alt+
Press the left mouse button over an object you want to select.
Hold Alt and the middle mouse button, then move the pointer.
Hold Alt and the right mouse button, then move the pointer.
Alternatively, use the mouse wheel to zoom in and out.
Hold Alt and the left mouse button, then move the pointer.
OpenCascade navigation
The OpenCascade navigation style was modeled after OpenCascade.
Select
Pan
Zoom
Rotate view
Ctrl+
Ctrl+
Ctrl+
Press the left mouse button over an object you want to select.
Hold the middle mouse button, then move the pointer.
Use the mouse wheel to zoom in and out.
Alternatively, hold Ctrl and the left mouse button, then move the pointer.
Hold Ctrl and the right mouse button, then move the pointer.
OpenInventor navigation
OpenInventor navigation (formerly Inventor) was modeled after Open Inventor. In order to select objects, you must hold the Shift or Ctrl key.
This style is not based on Autodesk Inventor.
Select
Pan
Zoom
Rotate view
Shift+
Hold Shift, then press the left mouse button over an object you want to select.
Hold Ctrl instead to select multiple objects.
Hold the middle mouse button, then move the pointer.
Use the mouse wheel to zoom in and out.
Alternatively, hold the middle mouse button, then press and hold the left mouse button, then move the pointer.
Hold the left mouse button, then move the pointer.
OpenSCAD navigation
The OpenSCAD navigation style was modeled after OpenSCAD.
Press the left mouse button over an object you want to select.
Hold the middle mouse button, then move the pointer.
Use the mouse wheel to zoom in and out.
Press the right mouse button, then move the pointer.
Touchpad navigation
With the Touchpad navigation style, panning, zooming, and rotating the view require a modifier key together with the touchpad. This style can also be used with a mouse.
Select
Pan
Zoom
Rotate view
Shift+
PageUp, PageDown
Alt+
Press the left mouse button over an object you want to select.
Hold Shift, then move the pointer.
Use PageUp and PageDown to zoom in and out.
Hold Alt, then move the pointer.
Ctrl+Shift+
Shift+
Alternatively, hold Ctrl and Shift, then move the pointer.
Alternatively, hold Shift and the left button, then move the pointer.
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. Note: 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 double-clicking 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.
Application and User Interface
Like almost everything else in FreeCAD, the graphical user interface part (GUI) is separated from the base application part (App). This is also valid for documents. The documents are also made of two parts: the Application document, which contains our objects, and the View document, which contains the representation on screen of our objects.
Think of it as two spaces, where the objects are defined. Their constructive parameters (is it a cube? a cone? which size?) are stored in the Application document, while their graphical representation (is it drawn with black lines? with blue faces?) are stored in the View document. Why is that? Because FreeCAD can also be used without graphical interface, for example, inside other programs, and we must still be able to manipulate our objects, even if nothing is drawn on the screen.
Another thing that is contained inside the View document are 3D views. One document can have several views opened, so you can inspect your document from several points of view at the same time. Maybe you would want to see a top view and a front view of your work at the same time? Then, you will have two views of the same document, both stored in the View document. Creating new views or closing views can be done from the View menu or by right-clicking on a view tab.
Scripting
Documents can be easily created, accessed and modified from the Python interpreter. For example:
</translate>
FreeCAD.ActiveDocument
<translate>
Will return the current (active) document
</translate>
FreeCAD.ActiveDocument.Blob
<translate>
Would access an object called "Blob" inside your document
</translate>
FreeCADGui.ActiveDocument
<translate>
Will return the view document associated to the current document
</translate>
FreeCADGui.ActiveDocument.Blob
<translate>
Would access the graphical representation (view) part of our Blob object
</translate>
To start the Preferences editor select the Edit → Preferences... option from the menu. On macOS the Preferences... option appears in the FreeCAD menu instead (this is the default place for preferences on the Mac).
FreeCAD uses a workbench concept, where each workbench is responsible for specific tasks and functions. A workbench can have its own preferences. These will only appear in the Preferences editor, usually in a dedicated section, if the workbench has been loaded in the current FreeCAD session. Some workbenches add support for specific import and export formats. If there are any related preferences they will appear on one or more additional tabs in the Import-Export section of the Preferences editor.
To preserve resources, FreeCAD does not automatically load all available workbenches. See Workbenches for more information. For a list of workbench related preferences see Workbench related preferences.
If no workbench is loaded, six sections appear in the Preferences editor: General, Display, Workbenches, Python, Addon Manager and Import-Export. Any workbenches that have been loaded, and have their own preferences, will appear below these.
Pressing the Reset button in the lower left corner of the Preferences dialog opens a menu (introduced in version 0.22) with options to reset preferences to their default values. You can reset the current tab, the current group, or all preferences. In version 0.21 and below the button will reset all preferences.
Some advanced preferences can only be changed in the Parameter editor. The Fine-tuning page lists some of them.
General
This preferences section has seven tabs: General, Document, Selection, Cache, Notification Area, Report view and Help.
In version 0.21 and below the seventh tab, Help, is only available if the Help Addon has been installed.
If checked, the numerical keypad decimal separator will be substituted with the separator defined by the Number format setting. introduced in version 0.21: Notice that if this preference is enabled, using the numerical keypad decimal separator will always print a dot/period in the Python console and the Macro editor.
Theme
Specifies a theme to customize the appearance of the user interface.
Size of toolbar icons
Specifies the size of the toolbar icons. The options are:
Small (16px)
Medium (24px)
Large (32px)
Extra large (48px)
Tree view mode
Defines how the tree view is shown in the user interface (restart required). The options are:
Combo View: Combines the tree view and the property view into one panel.
TreeView and PropertyView: Splits the tree view and the property view into separate panels.
Both: Shows all three panels. version 0.21 and below
Size of recent file list
Specifies how many files should be listed in the recent files list.
Optionally, imported files can be excluded from this list, and exported files can be included. See Fine-tuning.
Enable tiled background
If checked, the background of FreeCAD's main window will by default consist of tiles of this image:
This option only has an effect if no Style sheet is selected.
The image can be changed by adding the folders Gui/Images in the folder:
Lists the available preference packs and also allows you to import, save, manage and revert them.
Document
On the Document tab you can specify the following:
Name
Description
Create new document at start up
If checked, FreeCAD will create a new document when started.
Document save compression level
Specifies the compression level for FCStd files. FCStd files are ZIP-compressed files. Therefore you can rename their suffix .FCStd to .zip and open them with a ZIP archive program.
Using Undo/Redo on documents
If checked, all changes in documents are stored so that they can be undone/redone.
Maximum Undo/Redo steps
Specifies how many Undo/Redo steps should be recorded.
Allow aborting recomputation
If checked, recomputations can be aborted by pressing Esc. This may slightly increase the recomputation time.
Run AutoRecovery at startup
If there is a recovery file available FreeCAD will automatically run a file recovery when it is started. This way files can be restored if a crash occurred.
Save AutoRecovery information every
Specifies how often a recovery file is written.
Save thumbnail into project file when saving document
If checked, a thumbnail will be stored when the document is saved. The thumbnail will for example be shown in the list of recent files in the Start Workbench. It is possible to select a Size between 128×128 and 512×512 pixels for the thumbnail. Common sizes are powers of two: 128, 256, 512.
Add the program logo to the generated thumbnail
If checked, the FreeCAD program logo will be added to the thumbnail.
Maximum number of backup files to keep when resaving document
If checked, backup files will be kept when saving the document. You can specify the number of backup files to keep. Backup files are previously saved versions of the document. The first backup file will have the file suffix .FCStd1, the second .FCStd2 and so on.
Use date and FCBak extension
If checked, backup files will get the extension .FCbak and their file names get a date suffix according to the specified Date format. For a description of the date format see Date & time formats cheatsheet.
With the default settings a backup file will for example get this name TD-Cube.20200315-215654.FCBak (original filename is TD-Cube.FCStd).
Allow duplicate object labels in one document
If checked, objects can have the same label.
Disable partial loading of external linked objects
If partial loading of external linked objects is enabled, only the referenced objects and their dependencies will be loaded when the linked document is auto opened together with the main document. Such a partially loaded document cannot be edited. Double click the document icon in the tree view to reload it in full. A more detailed explanation of this feature can be found on the Assembly3 documentation page.
Author name
All created documents will get the specified author name. Keep the author field blank if you do not want to include this information. If the option Set on save is checked, the field Last modified by will be set to the specified author when saving the file. This field can be viewed using the File → Project information menu option.
Company
All created documents will get the specified company name.
Default license
Specifies the license for new documents. For predefined licenses the License URL will automatically be set accordingly. Select Other for a custom license.
License URL
Specifies an URL describing the license selected in Default license.
Selection
On the Selection tab you can specify the following:
Name
Description
Auto switch to the 3D view containing the selected item
If checked, internal Python error messages will be redirected from the Python console to the Report view.
Help
On the Help tab you can specify the following:
Name
Description
Help location
Specifies the location of the Help files. The options are:
Online: Enter the URL or leave blank to use the automatic GitHub URL.
Translation suffix: If https://wiki.freecad.org/ is used, a language suffix can be specified. Use for example fr for the French translation. Must be blank for the GitHub URL.
From disk location: Enter the path where the downloaded FreeCAD documentation can be found. To download the documentation select the offline-documentation addon from the Workbenches list in the Addon Manager.
Display
Specifies where the documentation should be displayed. The options are:
In a new FreeCAD tab: The documentation is displayed on a new tab in the Main view area.
In your default web browser: The documentation is displayed in the default web browser.
In a separate, embeddable, dialog: The documentation is displayed in a separate dialog. This dialog can be docked on top of the Combo view for example.
Custom stylesheet
Specifies an optional custom stylesheet. Not used for the Wiki URL.
Display
This preferences section has three standard tabs: 3D View, Navigation and Colors. A fourth tab, Mesh view, is added if the Mesh Workbench has been loaded.
3D View
On the 3D View tab you can specify the following:
Name
Description
Show coordinate system in the corner
If checked, the main coordinate system will be shown in the lower right corner of the 3D view.
The Relative size (introduced in version 0.20) defines the size of the representation as a percentage of the view size (the minimum of its height and width).
Show axis cross by default
If checked, the axis cross will be shown by default in the 3D view.
Show counter of frames per second
If checked, the time needed for the last operation and the resulting frame rate will be shown in the lower left corner of the 3D view.
Use software OpenGL
If checked, OpenGL will use the CPU instead of the GPU. This option is useful for troubleshooting graphics card and driver problems. Changing this option requires a restart of the application.
Use OpenGL VBO (Vertex Buffer Object)
If checked, Vertex Buffer Objects (VBO) will be used. A VBO is an OpenGL feature that provides methods for uploading vertex data (position, normal vector, color, etc.) to the graphics card. VBOs offer substantial performance gains because the data resides in the graphics memory rather than the system memory and so it can be rendered directly by the GPU. For more background info see Understanding OpenGL Objects.
Distributed: Manually turn on cache for all view provider root nodes.
Centralized: Manually turn off cache in all nodes of all view providers, and only cache at the scene graph root node. This offers the fastest rendering speed, but slower response to any scene changes.
Specifies the render type of transparent objects. The options are:
One pass: Rendering is done in one pass (default). This can lead to triangular artifacts. If these occur the type Backface pass can be used to avoid them.
Backface pass: Rendering is done in two passes. Back-facing polygons are rendered in the first pass and front-facing polygons in the second pass.
Marker size
Specifies the size of vertices (points) in the Sketcher Workbench. The clickable area of points can be additionally enlarged by increasing the Pick radius.
Pick radius (px)
Sets the area for picking elements in the 3D view. Larger value makes it easier to pick things, but can make some small features impossible to select.
Eye to eye distance for stereo modes
Specifies the eye-to-eye distance used for stereo projections. The specified value is a factor that will be multiplied with the bounding box size of the 3D object that is currently displayed.
Backlight color
If checked, backlight is enabled with the defined color. Backlight is used for rendering the back sides of faces. Usually, you don't see them in solids, unless you slice one with a clipping plane, or if the faces aren't oriented correctly. It is only used for objects whose Lighting property (on the View tab) is set to One side. If disabled, the back side of the faces of those objects will be black.
The related Intensity setting specifies the intensity of the backlight.
Camera type
Specifies the camera projection type. The options are:
Steps by turn defines the number of steps required for a full rotation when using the Navigation cube rotation arrows.
If Rotate to nearest is checked, the 3D view is rotated to the nearest most logical position, based on the current orientation of the cube, when a cube face is clicked. Else clicking a face will always result in the same rotation. introduced in version 0.20
Specifies a mouse navigation style. To see the details of each style, select it and then press the Mouse... button.
Orbit style
Specifies the rotation orbit style used when in rotation mode. The options are:
Turntable: Moving the mouse will divide the rotation in steps, rotations around the different axes are performed sequentially.
Trackball: Rotations around the different axes are performed simultaneously.
Free Turntable: Like Trackball, but if possible the rotation axis is kept collinear with the global 3D view axis. introduced in version 0.21
Rotation mode
Defines the rotation center. The options are:
Window center
Drag at cursor
Object center
Default camera orientation
Specifies the camera orientation for new documents. This setting is also used by the Std ViewHome command.
Camera zoom
Affects the initial camera zoom level for new documents. The value you set is the diameter of a sphere that fits in 3D view. The default is 100 mm. It also sets the initial size of origin features (base planes in new PartDesign Bodies and Std Parts).
Enable animation
If checked, and 3D Navigation is set to CAD, rotations can be animated. If the mouse is moved while the scroll wheel and the right mouse button are pressed, the view is rotated. If one keeps the mouse moving while releasing the right mouse button, the rotation will continue. To end this animation left-click with the mouse.
Zoom at cursor
If checked, zoom operations will be performed at the position of the mouse pointer. Otherwise zoom operations will be performed at the center of the current view. The Zoom step defines how much will be zoomed. A zoom step of 1 means a factor of 7.5 for every zoom step.
Invert zoom
If checked, the direction of zoom operations will be inverted.
Disable touchscreen tilt gesture
If checked, and 3D Navigation is set to Gesture, the tilting gesture will be disabled for pinch-zooming (two-finger zooming).
If checked, preselection is turned on and the specified color will be used for it. Preselection means that for example edges of objects will be highlighted while hovering over them with the mouse to indicate they can be selected.
Enable selection highlighting
If checked, selection highlighting is turned on and the specified color will be used for it.
Simple color
If selected, the background of the 3D view will have the specified color.
Linear gradient
If selected, the background of the 3D view will have a vertical color gradient defined by the specified Top and Bottom colors. if enabled, a Middle color can also be specified. Press the button (introduced in version 0.21) to switch the top and bottom colors.
If selected, the background of the 3D view will have a radial color gradient defined by the specified Central and End colors. if enabled, a Midway color can also be specified. Press the button to switch the central and end colors.
Object being edited
Specifies the background color for objects in the tree view that are currently edited.
Active container
Specifies the background color for active containers in the tree view. For example an active PartDesign Body will get this color.
Mesh view
This tab is only available if the Mesh Workbench has been loaded.
On the Mesh view tab you can specify the following:
Name
Description
Default mesh color
Specifies the default face color.
Default line color
Specifies the default line color.
Mesh transparency
Specifies the default mesh transparency.
Line transparency
Specifies the default line transparency.
Two-side rendering
If checked, the default value for the ViewLighting property is Two side instead of One side. Two side means the color of the interior side of faces is the same as the color of the exterior side. One side means their color is either the backlight color, if enabled, or black.
Show bounding-box for highlighted or selected meshes
If checked, the default value for the ViewSelection Style property is BoundBox instead of Shape. BoundBox means a highlighted bounding box is displayed if meshes are highlighted or selected. Shape means the shape itself is then highlighted.
Define normal per vertex
If checked, Phong shading is used, otherwise flat shading. Shading defines the appearance of surfaces. With flat shading the surface normals are not defined per vertex. This leads to an unrealistic appearance for curved surfaces. While Phong shading leads to a more realistic, smoother appearance.
Crease angle
The crease angle is a threshold angle between two faces. It can only be set if the option Define normal per vertex is used.
If face angle ≥ crease angle, facet shading is used.
If face angle < crease angle, smooth shading is used.
Workbenches
This preferences section has a single tab: Available Workbenches.
Available Workbenches
These preferences control workbench loading.
On the Available Workbenches tab you can specify the following:
Name
Description
Workbench list
The list displays all installed workbenches. The list can be reordered by drag and drop (introduced in version 0.21) and sorted by right-clicking the list and selecting Sort alphabetically (introduced in version 0.22). The order of the list also determines the order of the Workbench selector.
introduced in version 0.21: First checkbox in each row: If checked, the workbench will be available in the Workbench selector in the next FreeCAD session. The start up workbench cannot be unchecked. Unchecked workbenches are moved to the bottom of the list.
Auto-load: If checked, the workbench will auto-load when FreeCAD starts. Loading more workbenches will make the start up slower, but switching between workbenches that have already been loaded is faster.
Load: Press this button to load the workbench in the current FreeCAD session.
Start up workbench
The workbench that is activated when FreeCAD starts.
If checked, variables defined by macros are created as local variables, otherwise as global Python variables.
Macro path
Specifies the path for macro files.
Record GUI commands
If checked, recorded macros will also contain user interface commands.
Record as comment
If checked, recorded macros will also contain user interface commands, but as comments. This is useful if you don't want to execute these commands when running the macro, but do want to see what has been done while recording.
Show script commands in python console
If checked, the commands executed by macro scripts are shown in the Python console. This console can be opened using the View → Panels → Python console menu option.
Size of recent macro list
Controls the number of recent macros to display in the menu.
Shortcut count
Controls the number of recent macros that get dynamically assigned shortcuts.
Keyboard Modifiers
Controls which keyboard modifiers are used for the shortcuts, example Ctrl+Shift+ creates shortcuts in the form of Ctrl+Shift+1, Ctrl+Shift+2, etc.
Python console
These preferences control the behavior of the Python console. This console can be opened using the View → Panels → Python console menu option.
Note that the color and font settings for the console are defined on the Editor tab.
If checked, words will be wrapped if they exceed the available horizontal space in the console.
Enable block cursor
If checked, the cursor will have a block shape.
Save history
If checked, Python history is saved across sessions.
Editor
These preferences control the behavior of the Macro editor. This editor can be opened using the Macro → Macros... → Edit or Create menu option.
The color and font settings are also used by the Python console.
On the Editor tab you can specify the following:
Name
Description
Enable line numbers
If checked, the code lines will be numbered.
Enable block cursor
If checked, the cursor will have a block shape.
Tab size
Specifies the tabulator raster (how many spaces). If it is for example set to 6, pressing Tab will jump to character 7 or 13 or 19 etc., depending on the current cursor position. This setting is only used if Keep tabs is selected.
Indent size
Specifies how many spaces will be inserted when pressing Tab. This setting is only used if Insert spaces is selected.
Keep tabs
If selected, pressing Tab will insert a tabulator with the raster defined by Tab size.
Insert spaces
If selected, pressing Tab will insert the amount of spaces defined by Indent size.
Display Items
Specifies the code type the color and font settings will be applied to. The result can be checked in the Preview field.
Family
Specifies the font family that should be used for the selected code type.
Size
Specifies the font size that should be used for the selected code type.
Color
Specifies the color that should be used for the selected code type.
Addon Manager
This preferences section has a single tab: Addon manager options.
Addon manager options
These preferences control the behavior of the Addon manager.
Automatically check for updates at start (requires git)
If checked, the Addon manager will check for updates when it is launched. Git must be installed for this to work.
Download Macro metadata (approximately 10MB)
If checked, macro metadata is downloaded for display in the Addon manager's main addon listing. This data is cached locally.
Cache update frequency
Controls the frequency with which the locally cached addon availability and metadata information is updated. The options are:
Manual (no automatic updates)
Daily
Weekly
Hide Addons marked Python 2 Only
If checked, addons marked as "Python 2 Only" are not included in the listing. These addons are unlikely to work in the current FreeCAD version.
Hide Addons marked Obsolete
If checked, addons marked as "Obsolete" are not included in the listing.
Hide Addons that require a newer version of FreeCAD
If checked, addons that require a newer FreeCAD version are not included in the listing.
Custom repositories
Custom repositories can be specified here.
To add a repository press the button. Both the Repository URL and the Branch, typically master or main, must be specifies in the dialog that opens. introduced in version 0.21
The Addon manager includes experimental support for proxies requiring authentication, set up as user-defined proxies.
Python executable (optional)
The Addon manager attempts to determine the Python executable that should be used for the automatic pip-based installation of Python dependencies. To override this selection, the path to the executable can be set here.
git executable (optional)
The Addon manager attempts to determine the git executable. To override this selection, the path to the executable can be set here. introduced in version 0.21
Show option to change branches (requires git)
If checked, the Addon manager provides an interface on the addon's details screen that allows switching which git branch is currently checked out. This is intended for advanced users only, as it is possible that a non-primary-branch version of an addon may result in instability and compatibility issues. Git must be installed for this to work. Use with caution.
The FreeCAD interface is based on the modern Qt toolkit and has a state-of-the-art organization. Some aspects of the interface can be customized. You can, for example, add custom toolbars, with tools from several workbenches or tools defined in macros, and you can create you own keyboard shortcuts. But the menus and default toolbars that come with FreeCAD and its workbenches cannot be changed.
The commands available in the Customize dialog box depend on the workbenches that have been loaded in the current FreeCAD session. So you should first load all workbenches whose commands you want to have access to.
In the Customize dialog box the following tabs are available:
Keyboard
</translate>
<translate>
The Keyboard tab
On this tab custom keyboard shortcuts can be defined. Shortcuts for macro commands can be defined on the Macros tab.
Search
You can search for commands by entering at least 3 characters of their menu text or name in the search field. The search is case-insensitive.
It is also possible to search for shortcuts:
In the search field special keys in shortcuts must be entered as strings. For example to search for commands that use Ctrl in their shortcut enter ctrl (4 letters).
Add parenthesis to search for single character shortcuts, for example: (c).
Add a comma and space between the characters of multi-character shortcuts, for example: g, b, b.
Add a shortcut
Select a command category from the Category dropdown list.
Select a command from the Commands panel.
Optionally click the Command, Shortcut or Default column headings to reorder the list.
Optionally drag the splitter to the right of the panel to resize it.
The Current shortcut box displays the current short cut, if available.
Enter a new shortcut in the New shortcut input box. Shortcuts can be up to 4 inputs long. Each input is either a single character, a combination of one or more special keys or a combination of one or more special keys and a character. Use Backspace to correct mistakes.
Other active commands (see Notes) that already use the shortcut will be listed in the Shortcut priority list.
Press the Assign button to assign the new shortcut.
If the Shortcut priority list contains more than one command: optionally change its order by selecting individual commands and pressing the Up button or the Down button. If active commands share the same shortcut, the shortcut will trigger the one that is highest in the list.
Remove a shortcut
Select a command category from the Category dropdown list.
Select a command from the Commands panel.
Press the Clear button.
Restore a default shortcut
Select a command category from the Category dropdown list.
Select a command from the Commands panel.
Press the Reset button.
Restore all default shortcuts
Press the Reset All button.
Notes
Shortcuts only work for active commands. Active commands are commands that appear in the standard menu, or in the menu of the active workbench, or commands that appear in a visible toolbar.
In the dropdown list on the right select the workbench whose custom toolbars you want to modify. The Global option is there for custom toolbars that should be available in all workbenches.
Create a toolbar
Press the New... button.
Enter a name in the dialog box that opens.
Press the OK button.
The new toolbar will appear in the panel on the right.
Rename a toolbar
Select a toolbar in the panel on the right.
Press the Rename... button.
Enter a new name in the dialog box that opens.
Press the OK button.
Delete a toolbar
Select a toolbar in the panel on the right.
Press the Delete button.
Disable a toolbar
Uncheck the checkbox in front of the toolbar name in the panel on the right.
A disabled toolbar will be invisible in the FreeCAD interface.
Select the correct toolbar in the panel on the right. If no toolbar is selected, the command will be added to the first toolbar in the list.
Select a command category from the Category dropdown list. Macro commands that have been set up on the Macros tab appear in the Macros category.
Select a command from the Commands panel, or select <Separator> to add a separator (a line between two toolbar buttons).
Optionally drag the splitter to the right of the panel to resize it.
Press button.
Remove a command
If required, expand the toolbar in the panel on the right.
Select a command.
Press button.
Change a command position
If required, expand the toolbar in the panel on the right.
Select a command.
Press the button or the button.
Optionally repeat this until the command is in the correct position.
Notes
Toolbars belonging to the current workbench are updated immediately, but after disabling/re-enabling a toolbar a workbench change is required (switch to a different workbench and then switch back).
To update global toolbars a workbench change (if commands have been added or removed) or a restart (if the order of a toolbar has changed or a toolbar was renamed) is required.
On this tab macro commands can be set up. Once set up, they can be added to custom toolbars. Macros installed with the Addon Manager are set up automatically, and added to a Global toolbar (see Toolbars), if you confirm the Add button popup during the installation process.
If you want to use a macro downloaded from a different source you will have to install it manually. See How to install macros for more information. Note that FreeCAD uses a dedicated folder for macros and only macros in that folder can be set up. Use the Std DlgMacroExecute command to find this folder on your system.
Add a macro command
In the Macro dropdown list select a macro.
Enter a Menu text. This will be the name used to identify the macro command and will also appear in the toolbar if there is no icon.
Optionally enter a Tool tip. This text will appear near the location of the mouse when you hover the toolbar icon.
Optionally enter a Status text. This text will appear in the status bar when you hover the toolbar icon.
Optionally enter the wiki page for the macro, if available, in the What's this input box. Enter the page name, not the full URL.
Optionally enter a shortcut in the Accelerator input box. See Keyboard for more information.
To add an icon:
Press the Pixmap... button.
The Choose Icon dialog box opens.
If required press the Icon folders... button to add an icon folder.
Select an icon from the panel. The Choose Icon dialog box closes automatically.
Press the Add button.
The macro command appears in the panel on the left.
The macro command can now be selected on the Toolbars tab.
Remove a macro command
Select the macro command in the panel on the left.
Press the Remove button.
Change a macro command
Double-click the macro command in the panel on the left.
Make the required changes. Note that you cannot remove the icon, you can only replace it.
FreeCAD supports complete theming of the interface, via .qss stylesheets. The qss format is very similar to the css format used in web pages, it basically adds methods to reference the different widgets and elements of the Qt interface. You can change the default theme (which simply takes the style defined by your desktop system) by selecting a style sheet in the FreeCAD preferences.
You can also create your own theme if you are not satisfied with the themes that are bundled with FreeCAD, for example by editing an existing style sheet. Your new style must be placed in a specific folder for it to be found by FreeCAD:
%APPDATA%/FreeCAD/Gui/Stylesheets (on Windows). The %APPDATA% folder can be retrieved by entering App.getUserAppDataDir() in the Python console.
$HOME/.FreeCAD/Gui/Stylesheets (on Linux).
$HOME/Library/Application Support/FreeCAD/Gui/Stylesheets (on macOS).
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. Public properties can be viewed and modified in the Property editor.
Properties play a very important role in FreeCAD. As objects in FreeCAD are "parametric", this means that their behavior is defined by their properties, and how these properties are used as input for their class methods. See also FeaturePython Custom Properties and PropertyLink: InList and OutList
All property types
Custom scripted objects can use any of the property types defined in the base system:
A scripted object is created first, and then properties are assigned.
</translate>
obj=App.ActiveDocument.addObject("Part::Feature","CustomObject")obj.addProperty("App::PropertyFloat","Velocity","Parameter","Body speed")obj.addProperty("App::PropertyBool","VelocityEnabled","Parameter","Enable body speed")
<translate>
In general, Data properties are assigned by using the object's addProperty() method. On the other hand, View properties are normally provided automatically by the parent object from which the scripted object is derived.
For example:
Deriving from App::FeaturePython provides only 4 View properties: "Display Mode", "On Top When Selected", "Show In Tree", and "Visibility".
Deriving from Part::Feature provides 17 View properties: the previous four, plus "Angular Deflection", "Bounding Box", "Deviation", "Draw Style", "Lighting", "Line Color", "Line Width", "Point Color", "Point Size", "Selectable", "Selection Style", "Shape Color", and "Transparency".
Nevertheless, View properties can also be assigned using the view provider object's addProperty() method.
</translate>
obj.ViewObject.addProperty("App::PropertyBool","SuperVisibility","Base","Make the object glow")
<translate>
Source code
In the source code, properties are located in various src/App/Property* files.
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.
When you switch from one workbench to another, the tools available on the interface change. Toolbars, command bars and possibly other parts of the interface switch to the new workbench, but the contents of your scene doesn't change. You could, for example, start drawing 2D shapes with the Draft Workbench, then work further on them with the Part Workbench.
Note that sometimes a Workbench is referred to as a Module. However, Workbenches and Modules are different entities. A Module is any extension of FreeCAD, while a Workbench is a special type of Module with a GUI configuration (toolbars and menus).
Built-in workbenches
Current
The following workbenches are bundled with every FreeCAD installation:
Std Base. This is not really a workbench, but rather a category of 'standard' commands and tools that can be used in all workbenches.
The Arch Workbench for working with architectural elements.
FreeCAD workbenches are easy to program in Python, there are therefore many people developing additional workbenches outside of the FreeCAD main development area.
The external workbenches page lists all that are known to this community. Most are easily installable from within FreeCAD, using the Addon Manager, found under menu Tools → Addon manager.
The Mesh Workbench handles triangle meshes. Meshes are a special type of 3D object, composed of triangular faces connected by their vertices and edges.
Many 3D applications, like Sketchup, Blender, Maya and 3D Studio Max, use meshes as their primary type of 3D object. Since meshes are very simple objects, containing only vertices (points), edges and triangular faces, they are very easy to create, modify, subdivide, stretch, and can easily be passed from one application to another without any loss of details. In addition, since meshes contain very simple data, 3D applications can usually manage very large quantities of them without using a lot of resources. For these reasons, meshes are often the 3D object type of choice for applications dealing with movies, animation, and image creation.
However, in the field of engineering meshes present a big limitation: they cannot accurately define curved surfaces. This is why FreeCAD relies on Brep instead. The Mesh Workbench offers some commands to directly manipulate meshes, but it is most often used to import 3D mesh data and convert it to a solid for use with the Part Workbench or PartDesign Workbench.
</translate>
<translate>
Tools
All Mesh Workbench tools can be accessed from the Meshes menu. Almost all are also available in one of the Mesh toolbars.
The solid modelling capabilities of FreeCAD are based on the OpenCASCADE Technology (OCCT) kernel, a professional-grade CAD system that features advanced 3D geometry creation and manipulation. The Part Workbench is a layer sitting on top of the OCCT libraries, that gives the user access to OCCT geometric primitives and functions. Essentially all 2D and 3D drawing functions in every workbench (Draft, Sketcher, PartDesign, etc.), are based on these functions exposed by the Part Workbench. Therefore, the Part Workbench is considered the core component of the modelling capabilities of FreeCAD.
A more detailed discussion of Part workbench versus Part Design workbench can be found here: Part and Part Design.
The objects created with the Part Workbench are relatively simple; they are intended to be used with boolean operations (unions and cuts) in order to build more complex shapes. This modeling paradigm is known as the constructive solid geometry (CSG) workflow, and it was the traditional methodology used in early CAD systems. On the other hand, the PartDesign Workbench provides a more modern workflow to constructing shapes: it uses a parametrically defined sketch, that is extruded to form a basic solid body, which is then modified by parametric transformations (feature editing), until the final object is obtained.
Part objects are more complex than mesh objects created with the Mesh Workbench, as they permit more advanced operations like coherent boolean operations, modifications history, and parametric behaviour.
</translate>
<translate>
The Part Workbench is the basic layer that exposes the OCCT drawing functions to all workbenches in FreeCAD.
Tools
The tools are located in the Part menu or the Measure menu.
The Drawing Workbench is no longer included after version 0.20.
The TechDraw Workbench is its more advanced replacement.
Drawing workbench icon
Introduction
The Drawing module allows you to put your 3D work on paper. That is, to put views of your models in a 2D window and to insert that window in a drawing, for example a sheet with a border, a title and your logo and finally print that sheet.
</translate>
<translate>
Tools
These are tools for creating, configuring and exporting 2D drawing sheets
Project Shape: Creates a projection of the selected object (Source) in the 3D view.
Note: the Draft Drawing tool is used with Draft objects. It has some additional capabilities over the Drawing tools, and supports specific objects like Draft dimensions.
Workflow
The document contains a 3D shape object (leg) from which we want to produce a drawing. Therefore a "Page" is created. A page it's instantiated from a template, for example, the "A3_Landscape" template. The template is an SVG document which can hold a page frame, a logo, and other elements.
In this page we can insert one or more views. Each view has a position on the page, a scale factor, and additional properties. Every time the page or the view or the referenced object changes, the page is regenerated and the page display updated.
Scripting
At the moment the graphical user interface workflow is very limited, so the scripting API is more interesting.
See the Drawing API example page for a description of the functions used to create drawing pages and views.
Templates
FreeCAD comes bundled with a set of default templates, but you can find more on the Drawing templates page.
Extending the Drawing Module
Some notes on the programming side of the drawing module will be added to the Drawing Documentation page. This is to help quickly understand how the drawing module works, enabling programmers to rapidly start programming for it.
Macro Automatic drawing: Allows the user to get the view of his object in a drawing with 4 different position (front,top,iso,right). Needs some modification to be perfectly effective.
Macro CartoucheFC: This GUI macro to fill simply all fields of the cartridge of the plan implementation worksheet FreeCAD, the format of the date and the symbol of the projection mode adapt to the EU region or US selected.
Macro CartoucheFC 2: This GUI macro to fill simply all fields of the cartridge model 2 of the plan implementation worksheet FreeCAD.
Macro CartoucheFC Full: This GUI macro to fill simply all fields of the cartridge Misc templates Full of the plan implementation worksheet FreeCAD, the format of the date and the symbol of the projection mode adapt to the EU region or US selected.
Macro Corner shapes wizard/update: Pops up a dialog asking for the dimensions of your corner piece, then creates the object in the document and creates a page view with top, front and lateral views of the piece.
The Raytracing Workbench is no longer included after version 0.20.
The external Render Workbench should be used instead.
Raytracing workbench icon
Introduction
</translate>
<translate>
The Raytracing Workbench is used to generate photorealistic images of your models by processing them with an external renderer.
The Raytracing Workbench works with templates, which are project files that define a scene for your 3D model. You can place lights and geometry such as ground planes, and it also contains placeholders for the position of the camera, and for the material information of the objects in the scene. The project can then be exported to a ready-to-render file, or be rendered directly within FreeCAD.
Currently, two renderers are supported: POV-Ray and LuxRender. To be able to render from within FreeCAD, at least one of these programs must be installed and configured in your system. However, if no renderer is installed, you will still be able to export a project file to be rendered at another time.
The Raytracing workbench is obsolete, the external Render Workbench is its replacement. Nevertheless, the information on this page is generally useful for the new workbench, as both basically work in the same way.
</translate>
<translate>
Typical workflow
Create or open a FreeCAD project, add some solid objects (Part-based or PartDesign-based); meshes are currently not supported.
Create a Raytracing project (povray or luxrender).
Select the objects that you wish to add to the Raytracing project and add them.
Export the project file or render it directly.
Workflow of the Raytracing Workbench; the workbench prepares a project file from a given template, and then calls an external program to produce the actual rendering of the scene. The external renderer can be used independently of FreeCAD.
Tools
Project tools
These are the main tools for exporting your 3D work to external renderers.
The utility tools described above allow you to export the current 3D view and all of its content to a Povray file. First, you must load or create your CAD data and position the 3D View orientation as you wish. Then choose "Utilities → Export View..." from the raytracing menu.
</translate>
<translate>
You will be asked for a location to save the resulting *.pov file. After that you can open it in Povray and render:
</translate>
<translate>
As usual in a renderer you can make big and nice pictures:
</translate>
Although direct export to the Kerkythea XML-File-Format is not supported yet, you can export your Objects as Mesh-Files (.obj) and then import them in Kerkythea.
if using Kerkythea for Linux, remember to install the WINE-Package (needed by Kerkythea for Linux to run)
you can convert your models with the help of the mesh workbench to meshes and then export these meshes as .obj-files
If your mesh-export resulted in errors (flip of normals, holes ...) you may try your luck with netfabb studio basic
Free for personal use, available for Windows, Linux and Mac OSX.
It has standard repair tools which will repair you model in most cases.
another good program for mesh analysing/repairing is 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-file to be in m (but standard units-scheme in FreeCAD is mm)
Within WIndows 7 64-bit Kerkythea does not seem to be able to save these settings.
So remember to do that each time you start Kerkythea
if importing multiple objects in Kerkythea you can use the "File → Merge" command in Kerkythea
Development
These pages refer to the new workbench, programmed in Python, meant to replace the current Raytracing Workbench.
Like a Sketch, an imported image can be attached to one of the main planes XY, XZ, or YZ, and given a positive or negative offset.
The image is imported with relation of 1 pixel to 1 millimeter.
The recommendation is to have the imported image at a reasonable resolution.
Workflow
A major use of this workbench is tracing over the image, with the Draft or Sketcher tools, in order to generate a solid body based on the contours of the image.
Tracing over an image works best if the image has a small negative offset, for example, -0.1 mm, from the working plane. This means that the image will be slightly behind the plane where you draw your 2D geometry, so you won't draw on the image itself.
The offset of the image can be set during import, or changed later through its properties.
The Draft Workbench is primarily focused on the creation and modification of 2D objects in FreeCAD. But it is not restricted to the XY plane of the global coordinate system. Its objects can have any orientation and position in 3D space, and some Draft objects can either be planar or non-planar.
Draft objects can be used for general drafting, similar to what can be done with Inkscape or AutoCAD. But they can also form the base for the creation of 3D objects in other workbenches. A Draft Wire may define the path of an Arch Wall, a Draft Polygon can be extruded with Part Extrude, etc. Many of the Draft modifier tools can be applied to 2D and 3D objects created with other workbenches as well. You can, for example, move a Sketch or create a Draft OrthoArray from a Part object.
The Draft Workbench also provides tools to define a working plane, a grid, and a snapping system to precisely control the position of geometry.
If your primary goal is the production of complex 2D drawings and DXF files, and you don't need 3D modelling, FreeCAD may not be the right choice for you. You may wish to consider a dedicated software program for technical drafting instead, such as LibreCAD or QCad.
</translate>
<translate>
The image shows the grid aligned with the XY plane.
On the left, in white, several planar objects.
On the right a non-planar Draft Wire used as the Path Object of a Draft PathArray.
The Draft snap toolbar allows selecting the active snap options. The buttons belonging to active options stay depressed. For general information about snapping see: Draft Snap.
The Draft → Utilities menu contains several tools. Most of them can also be accessed from toolbars or the Draft Tray and have already been mentioned above. For the following tools this is not the case:
Apply current style: applies the current style settings to selected objects.
For a Draft Text and a Draft Label that contains one or more hyperlinks, to a local or remote file or an URL, this additional option is available:
Open hyperlinks: the hyperlinks are opened in the appropriate application (as defined by the OS). There is a warning in the case of multiple hyperlinks. introduced in version 0.22
Array: creates an orthogonal array from a selected object. The created array can be turned into a polar array or a circular array by changing its DataArray Type property. Not available in version 0.21 and above.
Drawing: inserts views of selected objects into a drawing page. Not available in version 0.21 and above.
Toggle continue mode: switches continue mode on or off. Not available in version 0.22 and above.
Preferences
Preferences: general preferences for the Draft Workbench.
Import Export Preferences: preferences available for importing from and exporting to different file formats.
File formats
The Draft Workbench provides FreeCAD with importers and exporters for several file formats. These are used by the Std Import and Std Export commands.
Macros are a convenient way to reproduce complex actions in FreeCAD. You simply record actions as you do them, then save those actions 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.
While Python scripts normally have the .py extension, FreeCAD macros should have the .FCMacro extension. A collection of macros written by experienced users is found in the macros recipes page.
See the Power users hub to learn more about the Python programming language, and about writing macros. In particular, you should start with these pages:
Enable the console output in the menu Edit → Preferences → Python → Macro → 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. Those commands are what can be recorded in a macro. The main tool for making macros is the macros toolbar: . On it you have 4 buttons: Record, stop recording, edit and play the current macro.
It is very simple to use: Press the record button, you will be asked to give a name to your macro, then perform some actions. When you are done, click the stop recording button, and your actions will be saved. You can now access the macro dialog with the edit button.
Macro dialog, listing the macros available in the system
There you can manage your macros, delete, edit, duplicate, install 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. New macros can be installed using the Addons... button, which links to the Addon Manager.
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.
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.
You can also directly copy/paste python code into a macro, without recording GUI action. Simply create a new macro, edit it, and paste your code. You can then save your macro the same way as you save a FreeCAD document. Next time you start FreeCAD, the macro will appear under the "Installed Macros" item of the Macro menu.
There are two main places for macros. The first one is the official peer-reviewed macro repository on GitHub. The second one is the Macros recipes page from which you can pick some useful macros to add to your FreeCAD installation. Macros from both repositories can be installed via the Addon Manager directly from FreeCAD.
FreeCAD is built from scratch to be totally controlled by Python scripts. Almost all parts of FreeCAD, such as the interface, the scene contents, and even the representation of this content in the 3D views, are accessible from the built-in Python interpreter or from your own scripts. As a result, FreeCAD is probably one of the most deeply customizable engineering applications available today.
If you are not familiar with Python, we recommend you search for tutorials on the internet and have a quick look at its structure. Python is a very easy language to learn, especially because it can be run inside an interpreter, where simple commands, right up to complete programs, can be executed on the fly without the need to compile anything. FreeCAD has a built-in Python interpreter. If you don't see the window labeled Python console as shown below, you can activate it under the View → Panels → Python console.
The interpreter
From the interpreter, you can access all your system-installed Python modules, as well as the built-in FreeCAD modules, and all additional FreeCAD modules you installed later. The screenshot below shows the Python interpreter:
From the interpreter, you can execute Python code and browse through the available classes and functions. FreeCAD provides a very handy class browser for exploration of the FreeCAD world: When you type the name of a known class followed by a period (meaning you want to add something from that class), a class browser window opens, where you can navigate between available subclasses and methods. When you select something, an associated help text (if it exists) is displayed:
So, start here by typing App. or Gui. and see what happens. Another more generic Python way of exploring the content of modules and classes is to use the print(dir()) command. For example, typing print(dir()) will list all modules currently loaded in FreeCAD. print(dir(App)) will show you everything inside the App module, etc.
Another useful feature of the interpreter is the possibility to go back through the command history and retrieve a line of code that you already typed earlier. To navigate through the command history, just use Up arrow or Down arrow.
By right-clicking in the interpreter window, you also have several other options, such as copy the entire history (useful when you want to experiment with things before making a full script of them), or insert a filename with complete path.
In the FreeCAD Help menu, you'll find an entry labeled Automatic python modules documentation, which will open a browser window containing a complete, realtime-generated documentation of all Python modules available to the FreeCAD interpreter, including Python and FreeCAD built-in modules, system-installed modules, and FreeCAD additional modules. The documentation available there depends on how much effort each module developer put into documenting his code, but Python modules have a reputation for being fairly well documented. Your FreeCAD window must stay open for this documentation system to work.
The entry Python scripting documentation will give you a quick link to the Power users hub wiki section.
Since FreeCAD is designed so that it can also be run without a Graphical User Interface (GUI), almost all its functionality is separated into two groups: Core functionality, named App, and GUI functionality, named Gui. These two modules can also be accessed from scripts outside of the interpreter, by the names FreeCAD and FreeCADGui respectively.
In the App module you'll find everything related to the application itself, like methods for opening or closing files, and to the documents, like setting the active document or listing their contents.
In the Gui module, you'll find tools for accessing and managing Gui elements, like the workbenches and their toolbars, and, more interestingly, the graphical representation of all FreeCAD content.
Listing the content of these modules is not very useful because they grow quite fast as FreeCAD develops. But the two browsing tools provided (the class browser and the Python help) should give you complete and up-to-date documentation at any moment.
As already mentioned, in FreeCAD everything is separated into core and representation. This includes the 3D objects. You can access defining properties of objects (called features in FreeCAD) via the App module, and change the way they are represented on screen via the Gui module. For example, a cube has properties that define it (like width, length, height) that are stored in an App object, and representation properties (like faces color, drawing mode) that are stored in a corresponding Gui object.
This way of doing things allows a very wide range of uses, like having algorithms work only on the definition part of features, without the need to care about any visual part, or even redirect the content of the document to non-graphical application, such as lists, spreadsheets, or element analysis.
For every App object in your document, there exists a corresponding Gui object. In fact the document itself has both an App and a Gui object. This, of course, only applies when you run FreeCAD with its full interface. In the command-line version no GUI exists, so only App objects are available. Note that the Gui part of objects is re-generated every time an App object is marked as 'to be recomputed' (for example when one of its parameters changes), so any changes made directly to the Gui object may be lost.
In FreeCAD all your work resides inside documents. A document contains your geometry and can be saved to a file. Several documents can be opened at the same time. The document, like the geometry contained inside, has App and Gui objects. The App object contains your actual geometry definitions, while the Gui object contains the different views of your document. You can open several windows, each one viewing your work with a different zoom factor or from a different direction. These views are all part of your document's Gui object.
To access the App part of the currently open (active) document, you type:
</translate>
myDocument=App.ActiveDocument
<translate>
To create a new document, type:
</translate>
myDocument=App.newDocument("Document Name")
<translate>
To access the Gui part of the currently open (active) document, you type:
The FreeCAD and FreeCADGui modules are only responsible for creating and managing objects in the FreeCAD document. They don't actually do anything more such as creating or modifying geometry. This is because that geometry can be of several types, and therefore requires additional modules, each responsible for managing a certain geometry type. For example, the Part Workbench, using the OpenCascade kernel, is able to create and manipulate BRep type geometry. Whereas the Mesh Workbench is able to build and modify mesh objects. In this manner FreeCAD is able to handle a wide variety of object types, that can all coexist in the same document, and new types can easily be added in the future.
Each module has its own way of dealing with geometry, but one thing they usually all can do is create objects in the document. But the FreeCAD document is also aware of the available object types provided by the modules:
</translate>
FreeCAD.ActiveDocument.supportedTypes()
<translate>
will list all possible objects you can create. For example, let's create a mesh (handled by the Mesh module) and a part (handled by the Part module):
The first argument is the object type, the second the name of the object. Our two objects look almost the same: They don't contain any geometry yet, and most of their properties are the same when you inspect them with dir(myMesh) and dir(myPart). Except for one thing, myMesh has a Mesh property and myPart has a Shape property. That is where the Mesh and Part data are stored. For example, let's create a Part cube and store it in our myPart object:
You could try storing the cube inside the Mesh property of the myMesh object, but it will return an error. That is because each properties is made to store only a certain type. In a Mesh property, you can only save stuff created with the Mesh module. Note that most modules also have a shortcut to add their geometry to the document:
To create regular geometries you can use one of the create*() methods. A torus, for instance, can be created as follows:
</translate>
m=Mesh.createTorus(8.0,2.0,50)Mesh.show(m)
<translate>
The first two parameters define the radii of the torus and the third parameter is a sub-sampling factor for how many triangles are created. The higher this value the smoother the mesh.
The Mesh module also provides three Boolean methods: union(), intersection() and difference():
</translate>
m1,m2# are the input mesh objectsm3=Mesh.Mesh(m1)# create a copy of m1m3.unite(m2)# union of m1 and m2, the result is stored in m3m4=Mesh.Mesh(m1)m4.intersect(m2)# intersection of m1 and m2m5=Mesh.Mesh(m1)m5.difference(m2)# the difference of m1 and m2m6=Mesh.Mesh(m2)m6.difference(m1)# the difference of m2 and m1, usually the result is different to m5
<translate>
Here is an example that creates a pipe using the difference() method:
</translate>
importFreeCAD,MeshcylA=Mesh.createCylinder(2.0,10.0,True,1.0,36)cylB=Mesh.createCylinder(1.0,12.0,True,1.0,36)cylB.Placement.Base=(FreeCAD.Vector(-1,0,0))# move cylB to avoid co-planar facespipe=cylApipe=pipe.difference(cylB)pipe.flipNormals()# somehow requireddoc=FreeCAD.ActiveDocumentobj=d.addObject("Mesh::Feature","Pipe")obj.Mesh=pipedoc.recompute()
An extensive, though hard to use, source of mesh related scripting are the unit test scripts of the Mesh module.
In these unit tests literally all methods are called and all properties/attributes are tweaked.
So if you are bold enough, take a look at the Unit Test module.
Here we will explain to you how to control the Part module directly from the FreeCAD Python interpreter, or from any external script. 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. If you are new to Python, it is a good idea to first read the Introduction to Python.
We will now create a topology by constructing it out of simpler geometry. As a case study we will use a part as seen in the picture which consists of four vertices, two arcs and two lines.
Vectors are one of the most important pieces of information when building shapes. They usually contain three numbers (but not necessarily always): the X, Y and Z cartesian coordinates. You create a vector like this:
</translate>
myVector=App.Vector(3,2,0)
<translate>
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 simply a container for a vector. You access the vector of a vertex like this:
So far we created an edge object, but it doesn't appear anywhere on the screen. This is because the FreeCAD 3D scene only displays what you tell it to display. To do that, we use this simple
method:
</translate>
Part.show(edge)
<translate>
The show function creates an object in our FreeCAD document and assigns our "edge" shape to it. Use this whenever it is time to display your creation on screen.
ccircle will be created at distance 10 from the X origin and will be facing outwards along the X axis. Note: makeCircle() only accepts App.Vector() for the position and normal parameters, not tuples. You can also create part of the circle by giving a start and an end angle:
Angles should be provided in degrees. If you have radians simply convert them using the formula:
degrees = radians * 180/pi or by using Python's math module:
Unfortunately there is no makeArc() function, but we have the Part.Arc() function to create an arc through three points. It creates an arc object joining the start point to the end point through the middle point. The arc object's toShape() function must be called to get an edge object, the same as when using Part.LineSegment instead of Part.makeLine.
Bézier curves are used to model smooth curves using a series of poles (points) and optional weights. The function below makes a Part.BezierCurve() from a series of FreeCAD.Vector() points. Note: when "getting" and "setting" a single pole or weight, indices start at 1, not 0.
A Plane is a flat rectangular surface. The method used to create one is 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 in the positive Z axis direction, while dir_normal = Vector(1, 0, 0) will create the plane facing in the positive X axis direction:
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 along the Y axis is zero, since our shape is totally flat.
Note: makePlane() only accepts App.Vector() for start_pnt and dir_normal and not tuples.
Creates an ellipse with major radius 2 and minor radius 1 with the center at (0, 0, 0).
</translate>
Part.Ellipse(Ellipse)
<translate>
Creates a copy of the given ellipse.
</translate>
Part.Ellipse(S1,S2,Center)
<translate>
Creates an ellipse centered on the point Center, where the plane of the ellipse is defined by Center, S1 and S2, its major axis is defined by Center and S1, its major radius is the distance between Center and S1, and its minor radius is the distance between S2 and the major axis.
</translate>
Part.Ellipse(Center,MajorRadius,MinorRadius)
<translate>
Creates an ellipse with major and minor radii MajorRadius and MinorRadius, located in the plane defined by Center and the normal (0, 0, 1)
In the above code we have passed S1, S2 and center. Similar to Arc, Ellipse creates an ellipse object not an edge, so we need to convert it into an edge using toShape() for display.
Note: Ellipse() only accepts App.Vector() for points and not tuples.
Using 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 the big circle, radius2 is the radius of the small circle, pnt is the center of the torus and dir is the normal direction. angle1 and angle2 are angles in degrees for the small circle; the last angle parameter is to make a section of the torus:
</translate>
torus=Part.makeTorus(10,2)
<translate>
The above code will create a torus with diameter 20 (radius 10) and thickness 4 (small circle radius 2)
The above code will create a semi torus; only the last parameter is changed. i.e the remaining angles are defaults. Giving the angle 180 will create the torus from 0 to 180, that is, a half torus.
Using makeSphere(radius, [pnt, dir, angle1, angle2, angle3]). By default pnt = Vector(0, 0, 0), dir = Vector(0, 0, 1), angle1 = -90, angle2 = 90 and angle3 = 360. Angle1 and angle2 are the vertical minimum and maximum of the sphere, angle3 is the sphere diameter.
There are several ways to modify shapes. Some are simple transformation operations such as moving or rotating shapes, others are more complex, such as unioning and subtracting one shape from another.
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:
Note: FreeCAD matrixes work in radians. Also, almost all matrix operations that take a vector can also take three numbers, so these two lines do the same thing:
Once our matrix is set, we can apply it to our shape. FreeCAD provides two methods for doing that: transformShape() and transformGeometry(). The difference is that with the first one, you are sure that no deformations will occur (see Scaling a shape below). We can apply our transformation like this:
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 differently. For scaling, we cannot use the transformShape(), we must use transformGeometry():
Extrusion is the act of "pushing" a flat shape in a certain direction, resulting in a solid body. Think of a circle becoming a tube by "pushing it out":
</translate>
circle = Part.makeCircle(10)
tube = circle.extrude(App.Vector(0, 0, 2))
<translate>
If your circle is hollow, you will obtain a hollow tube. If your circle is actually a disc with a filled face, you will obtain a solid cylinder:
You can easily explore the topological data structure:
</translate>
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
<translate>
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 vertices. Straight edges have only two vertices, obviously.
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:
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.
</translate>
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)
Here we see now how we can use a selection the user did in the viewer. First of all we create a box and show it in the viewer.
</translate>
import Part
Part.show(Part.makeBox(100, 100, 100))
Gui.SendMsgToActiveView("ViewFit")
<translate>
Now select some faces or edges. With this script you can iterate over all selected objects and their sub elements:
</translate>
for o in Gui.Selection.getSelectionEx():
print(o.ObjectName)
for s in o.SubElementNames:
print("name: ", s)
for s in o.SubObjects:
print("object: ", s)
<translate>
Select some edges and this script will calculate the length:
</translate>
length = 0.0
for o in Gui.Selection.getSelectionEx():
for s in o.SubObjects:
length += s.Length
print("Length of the selected edges: ", length)
A typical example found on the OpenCasCade Technology website is how to build a bottle. This is a good exercise for FreeCAD too. In fact, if you follow our example below and the OCC page simultaneously, you will see how well OCC structures are implemented in FreeCAD. The script is included in the FreeCAD installation (inside the Mod/Part folder) and can be called from the Python interpreter by typing:
</translate>
import Part
import MakeBottle
bottle = MakeBottle.makeBottle()
Part.show(bottle)
For the purpose of this tutorial we will consider a reduced version of the script. In this version the bottle will not be hollowed out, and the neck of the bottle will not be threaded.
Here we define our makeBottleTut 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.
Remember the difference between geometry and shapes? Here we build shapes out of our construction geometry. Three edges (edges can be straight or curved), then a wire made of those three edges.
</translate>
...
aTrsf=App.Matrix()
aTrsf.rotateZ(math.pi) # rotate around the z-axis
aMirroredWire=aWire.copy()
aMirroredWire.transformShape(aTrsf)
myWireProfile=Part.Wire([aWire, aMirroredWire])
<translate>
So far we have built only a half profile. Instead of building the whole profile the same way, we can just mirror what we did and glue both halves together. 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 undergo (move, rotate and scale). After we create the matrix we mirror it, then we create a copy of our wire and apply the transformation matrix to it. We now have two wires, and we can make a third wire out of them, since wires are actually lists of edges.
Now that we have a closed wire, it can be turned into a face. Once we have a face, we can extrude it. In doing so, we make a solid. Then we apply a nice little fillet to our object because we care about good design, don't we?
There are several ways to save your work. You can of course save your FreeCAD document, but you can also save Part objects directly to common CAD formats, such as BREP, IGS, STEP and STL.
Saving a shape to a file is easy. There are exportBrep(), exportIges(), exportStep() and exportStl() methods available for all shape objects. So, doing:
</translate>
import Part
s = Part.makeBox(10, 10, 10)
s.exportStep("test.stp")
<translate>
will save our box into a STEP file. To load a BREP, IGES or STEP file:
</translate>
import Part
s = Part.Shape()
s.read("test.stp")
<translate>
To convert a STEP file to an IGS file:
</translate>
import Part
s = Part.Shape()
s.read("file.stp") # incoming file igs, stp, stl, brep
s.exportIges("file.igs") # outbound file igs
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...
Snippets
A typical InitGui.py file
Every module must contain, besides your main module file, an InitGui.py file, responsible for inserting the module in the main Gui. This is an example of a simple one.
</translate>
class ScriptWorkbench (Workbench):
MenuText = "Scripts"
def Initialize(self):
import Scripts # assuming Scripts.py is your module
list = ["Script_Cmd"] # That list must contain command names, that can be defined in Scripts.py
self.appendToolbar("My Scripts",list)
Gui.addWorkbench(ScriptWorkbench())
This is an example of a main module file, containing everything your module does. It is the Scripts.py file invoked by the previous example. You can have all your custom commands here.
</translate>
import FreeCAD, FreeCADGui
class ScriptCmd:
def Activated(self):
# Here your write what your ScriptCmd does...
FreeCAD.Console.PrintMessage('Hello, World!')
def GetResources(self):
return {'Pixmap' : 'path_to_an_icon/myicon.png', 'MenuText': 'Short text', 'ToolTip': 'More detailed text'}
FreeCADGui.addCommand('Script_Cmd', ScriptCmd())
Making an importer for a new filetype in FreeCAD is easy. FreeCAD doesn't consider that you import data in an opened document, but rather that you simply can directly open the new filetype. So what you need to do is to add the new file extension to FreeCAD's list of known extensions, and write the code that will read the file and create the FreeCAD objects you want:
This line must be added to the InitGui.py file to add the new file extension to the list:
</translate>
# Assumes Import_Ext.py is the file that has the code for opening and reading .ext files
FreeCAD.addImportType("Your new File Type (*.ext)","Import_Ext")
<translate>
Then in the Import_Ext.py file:
</translate>
def open(filename):
doc=App.newDocument()
# here you do all what is needed with filename, read, classify data, create corresponding FreeCAD objects
doc.recompute()
<translate>
To export your document to some new filetype works the same way, except that you use:
FreeCAD.addExportType("Your new File Type (*.ext)","Export_Ext")
import Part,PartGui
doc=App.activeDocument()
# add a line element to the document and set its points
l=Part.LineSegment()
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()
A polygon is simply a set of connected line segments (a polyline in AutoCAD). It doesn't need to be closed.
</translate>
import Part, PartGui
doc = App.activeDocument()
n = list()
# create a 3D vector, set its coordinates and add it to the list
v = App.Vector(0,0,0)
n.append(v)
v = App.Vector(10,0,0)
n.append(v)
#... repeat for all nodes
# Create a polygon object and set its nodes
p = doc.addObject("Part::Polygon","Polygon")
p.Nodes = n
doc.recompute()
doc=App.activeDocument()
grp=doc.addObject("App::DocumentObjectGroup", "Group")
lin=doc.addObject("Part::Feature", "Line")
grp.addObject(lin) # adds the lin object to the group grp
grp.removeObject(lin) # removes the lin object from the group grp
import Part
doc = App.activeDocument()
c = Part.Circle()
c.Radius=10.0
f = doc.addObject("Part::Feature", "Circle") # create a document with a circle feature
f.Shape = c.toShape() # Assign the circle shape to the shape property
doc.recompute()
Each object in a FreeCAD document has an associated view representation object that stores all the parameters that define how that object appears: i.e. color, linewidth, etc... See also List the components of an object snippet below
</translate>
gad = Gui.activeDocument() # access the active document containing all
# view representations of the features in the
# corresponding App document
v = gad.getObject("Cube") # access the view representation to the Mesh feature 'Cube'
v.ShapeColor # prints the color to the console
v.ShapeColor=(1.0,1.0,1.0) # sets the shape color to white
The Inventor framework allows to add one or more callback nodes to the scenegraph of the viewer. By default in FreeCAD one callback node is installed per viewer which allows to add global or static C++ functions. In the appropriate Python binding some methods are provided to make use of this technique from within Python code.
</translate>
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)
<translate>
Now, pick somewhere on the area in the 3D viewer and observe the messages in the output window. To finish the observation just call
</translate>
v.removeEventCallback("SoMouseButtonEvent",c)
<translate>
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
This macro displays in the report view the keys pressed and all events command
</translate>
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
It is also possible to get and change the scenegraph in Python, with the 'pivy' module -- a Python binding for Coin.
</translate>
from pivy.coin import * # load the pivy module
view = Gui.ActiveDocument.ActiveView # get the active viewer
root = view.getSceneGraph() # the root is an SoSeparator node
root.addChild(SoCube())
view.fitAll()
<translate>
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
</translate>
type = SoType.fromName("SoFCSelection")
node = type.createInstance()
Adding new nodes to the scenegraph can be done this way. Take care of always adding a SoSeparator to contain the geometry, coordinates and material info of a same object. The following example adds a red line from (0,0,0) to (10,0,0):
</translate>
from pivy import coin
sg = Gui.ActiveDocument.ActiveView.getSceneGraph()
co = coin.SoCoordinate3()
pts = [[0,0,0],[10,0,0]]
co.point.setValues(0,len(pts),pts)
ma = coin.SoBaseColor()
ma.rgb = (1,0,0)
li = coin.SoLineSet()
li.numVertices.setValue(2)
no = coin.SoSeparator()
no.addChild(co)
no.addChild(ma)
no.addChild(li)
sg.addChild(no)
import math
import time
from FreeCAD import Base
from pivy import coin
size=(1000,1000)
dirname = "C:/Temp/animation/"
steps=36
angle=2*math.pi/steps
matX=Base.Matrix()
matX.rotateX(angle)
stepsX=Base.Placement(matX).Rotation
matY=Base.Matrix()
matY.rotateY(angle)
stepsY=Base.Placement(matY).Rotation
matZ=Base.Matrix()
matZ.rotateZ(angle)
stepsZ=Base.Placement(matZ).Rotation
view=Gui.ActiveDocument.ActiveView
cam=view.getCameraNode()
rotCamera=Base.Rotation(*cam.orientation.getValue().getValue())
# this sets the lookat point to the center of circumsphere of the global bounding box
view.fitAll()
# the camera's position, i.e. the user's eye point
position=Base.Vector(*cam.position.getValue().getValue())
distance=cam.focalDistance.getValue()
# view direction
vec=rotCamera.multVec(Base.Vector(0,0,-1))
# this is the point on the screen the camera looks at
# when rotating the camera we should make this point fix
lookat=position+vec*distance
# around x axis
for i in range(steps):
rotCamera=stepsX.multiply(rotCamera)
cam.orientation.setValue(*rotCamera.Q)
vec=rotCamera.multVec(Base.Vector(0,0,-1))
pos=lookat-vec*distance
cam.position.setValue(pos.x,pos.y,pos.z)
Gui.updateGui()
time.sleep(0.3)
view.saveImage(dirname+"x-%d.png" % i,*size)
# around y axis
for i in range(steps):
rotCamera=stepsY.multiply(rotCamera)
cam.orientation.setValue(*rotCamera.Q)
vec=rotCamera.multVec(Base.Vector(0,0,-1))
pos=lookat-vec*distance
cam.position.setValue(pos.x,pos.y,pos.z)
Gui.updateGui()
time.sleep(0.3)
view.saveImage(dirname+"y-%d.png" % i,*size)
# around z axis
for i in range(steps):
rotCamera=stepsZ.multiply(rotCamera)
cam.orientation.setValue(*rotCamera.Q)
vec=rotCamera.multVec(Base.Vector(0,0,-1))
pos=lookat-vec*distance
cam.position.setValue(pos.x,pos.y,pos.z)
Gui.updateGui()
time.sleep(0.3)
view.saveImage(dirname+"z-%d.png" % i,*size)
You can create custom widgets with Qt designer, transform them into a python script, and then load them into the FreeCAD interface with PySide.
The python code produced by the Ui python compiler (the tool that converts qt-designer .ui files into python code) generally looks like this (it is simple, you can also code it directly in python):
</translate>
class myWidget_Ui(object):
def setupUi(self, myWidget):
myWidget.setObjectName("my Nice New Widget")
myWidget.resize(QtCore.QSize(QtCore.QRect(0,0,300,100).size()).expandedTo(myWidget.minimumSizeHint())) # sets size of the widget
self.label = QtGui.QLabel(myWidget) # creates a label
self.label.setGeometry(QtCore.QRect(50,50,200,24)) # sets its size
self.label.setObjectName("label") # sets its name, so it can be found by name
def retranslateUi(self, draftToolbar): # built-in QT function that manages translations of widgets
myWidget.setWindowTitle(QtGui.QApplication.translate("myWidget", "My Widget", None, QtGui.QApplication.UnicodeUTF8))
self.label.setText(QtGui.QApplication.translate("myWidget", "Welcome to my new widget!", None, QtGui.QApplication.UnicodeUTF8))
<translate>
Then, all you need to do is to create a reference to the FreeCAD Qt window, insert a custom widget into it, and "transform" this widget into yours with the Ui code we just made:
</translate>
app = QtGui.qApp
FCmw = app.activeWindow() # the active qt window, = the freecad window since we are inside it
# FCmw = FreeCADGui.getMainWindow() # use this line if the 'addDockWidget' error is declared
myNewFreeCADWidget = QtGui.QDockWidget() # create a new dckwidget
myNewFreeCADWidget.ui = myWidget_Ui() # load the Ui script
myNewFreeCADWidget.ui.setupUi(myNewFreeCADWidget) # setup the ui
FCmw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myNewFreeCADWidget) # add the widget to the main window
The following code allows you to add a tab to the Combo view, separate from the preexisting "Model" and "Tasks" tabs. It also uses the uic module to load an UI file directly in that tab.
</translate>
# create new Tab in ComboView
from PySide import QtGui,QtCore
#from PySide import uic
def getMainWindow():
"returns the main window"
# using QtGui.qApp.activeWindow() isn't very reliable because if another
# widget than the mainwindow is active (e.g. a dialog) the wrong widget is
# returned
toplevel = QtGui.qApp.topLevelWidgets()
for i in toplevel:
if i.metaObject().className() == "Gui::MainWindow":
return i
raise Exception("No main window found")
def getComboView(mw):
dw=mw.findChildren(QtGui.QDockWidget)
for i in dw:
if str(i.objectName()) == "Combo View":
return i.findChild(QtGui.QTabWidget)
elif str(i.objectName()) == "Python Console":
return i.findChild(QtGui.QTabWidget)
raise Exception ("No tab widget found")
mw = getMainWindow()
tab = getComboView(getMainWindow())
tab2=QtGui.QDialog()
tab.addTab(tab2,"A Special Tab")
#uic.loadUi("/myTaskPanelforTabs.ui",tab2)
tab2.show()
#tab.removeTab(2)
Retrieve the coordinates of 3 selected points or objects
</translate>
# -*- coding: utf-8 -*-
# the line above to put the accentuated in the remarks
# If this line is missing, an error will be returned
# extract and use the coordinates of 3 objects selected
import Part, FreeCAD, math, PartGui, FreeCADGui
from FreeCAD import Base, Console
sel = FreeCADGui.Selection.getSelection() # " sel " contains the items selected
if len(sel)!=3 :
# If there are no 3 objects selected, an error is displayed in the report view
# The \r and \n at the end of line mean return and the newline CR + LF.
Console.PrintError("Select 3 points exactly\r\n")
else :
points=[]
for obj in sel:
points.append(obj.Shape.BoundBox.Center)
for pt in points:
# display of the coordinates in the report view
Console.PrintMessage(str(pt.x)+"\r\n")
Console.PrintMessage(str(pt.y)+"\r\n")
Console.PrintMessage(str(pt.z)+"\r\n")
Console.PrintMessage(str(pt[1]) + "\r\n")
# -*- coding: utf-8 -*-
import FreeCAD,Draft
# List all objects of the document
doc = FreeCAD.ActiveDocument
objs = FreeCAD.ActiveDocument.Objects
#App.Console.PrintMessage(str(objs) + "\n")
#App.Console.PrintMessage(str(len(FreeCAD.ActiveDocument.Objects)) + " Objects" + "\n")
for obj in objs:
a = obj.Name # list the Name of the object (not modifiable)
b = obj.Label # list the Label of the object (modifiable)
try:
c = obj.LabelText # list the LabeText of the text (modifiable)
App.Console.PrintMessage(str(a) +" "+ str(b) +" "+ str(c) + "\n") # Displays the Name the Label and the text
except:
App.Console.PrintMessage(str(a) +" "+ str(b) + "\n") # Displays the Name and the Label of the object
#doc.removeObject("Box") # Clears the designated object
# -*- coding: utf-8 -*-
# causes an action to the mouse click on an object
# This function remains resident (in memory) with the function "addObserver(s)"
# "removeObserver(s) # Uninstalls the resident function
class SelObserver:
def setPreselection(self,doc,obj,sub): # Preselection object
App.Console.PrintMessage(str(sub)+ "\n") # The part of the object name
def addSelection(self,doc,obj,sub,pnt): # Selection object
App.Console.PrintMessage("addSelection"+ "\n")
App.Console.PrintMessage(str(doc)+ "\n") # Name of the document
App.Console.PrintMessage(str(obj)+ "\n") # Name of the object
App.Console.PrintMessage(str(sub)+ "\n") # The part of the object name
App.Console.PrintMessage(str(pnt)+ "\n") # Coordinates of the object
App.Console.PrintMessage("______"+ "\n")
def removeSelection(self,doc,obj,sub): # Remove the selection
App.Console.PrintMessage("removeSelection"+ "\n")
def setSelection(self,doc): # Set selection
App.Console.PrintMessage("setSelection"+ "\n")
def clearSelection(self,doc): # If click on the screen, clear the selection
App.Console.PrintMessage("clearSelection"+ "\n") # If click on another object, clear the previous object
s =SelObserver()
FreeCADGui.Selection.addObserver(s) # install the function mode resident
#FreeCADGui.Selection.removeObserver(s) # Uninstall the resident function
<translate>
Other example with ViewObserver on a object select or view
</translate>
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)
from pivy import coin
import FreeCADGui
def mouse_over_cb( event_callback):
event = event_callback.getEvent()
pos = event.getPosition().getValue()
listObjects = FreeCADGui.ActiveDocument.ActiveView.getObjectsInfo((int(pos[0]),int(pos[1])))
obj = []
if listObjects:
FreeCAD.Console.PrintMessage("\n *** Objects under mouse pointer ***")
for o in listObjects:
label = str(o["Object"])
if not label in obj:
obj.append(label)
FreeCAD.Console.PrintMessage("\n"+str(obj))
view = FreeCADGui.ActiveDocument.ActiveView
mouse_over = view.addEventCallbackPivy( coin.SoLocation2Event.getClassTypeId(), mouse_over_cb )
# to remove Callback :
#view.removeEventCallbackPivy( coin.SoLocation2Event.getClassTypeId(), mouse_over)
####
#The easy way is probably to use FreeCAD's selection.
#FreeCADGui.ActiveDocument.ActiveView.getObjectsInfo(mouse_coords)
####
#you get that kind of result :
#'Document': 'Unnamed', 'Object': 'Box', 'Component': 'Face2', 'y': 8.604081153869629, 'x': 21.0, 'z': 8.553047180175781
####
#You can use this data to add your element to FreeCAD's selection :
#FreeCADGui.Selection.addSelection(FreeCAD.ActiveDocument.Box,'Face2',21.0,8.604081153869629,8.553047180175781)
This function list the components of an object and extracts:
this object its XYZ coordinates,
its edges and their lengths center of mass and coordinates
its faces and their center of mass
its faces and their surfaces and coordinates
</translate>
<translate>
</translate>
# -*- coding: utf-8 -*-
# This function list the components of an object
# and extract this object its XYZ coordinates,
# its edges and their lengths center of mass and coordinates
# its faces and their center of mass
# its faces and their surfaces and coordinates
# 8/05/2014
import Draft,Part
def detail():
sel = FreeCADGui.Selection.getSelection() # Select an object
if len(sel) != 0: # If there is a selection then
Vertx=[]
Edges=[]
Faces=[]
compt_V=0
compt_E=0
compt_F=0
pas =0
perimetre = 0.0
EdgesLong = []
# Displays the "Name" and the "Label" of the selection
App.Console.PrintMessage("Selection > " + str(sel[0].Name) + " " + str(sel[0].Label) +"\n"+"\n")
for j in enumerate(sel[0].Shape.Edges): # Search the "Edges" and their lengths
compt_E+=1
Edges.append("Edge%d" % (j[0]+1))
EdgesLong.append(str(sel[0].Shape.Edges[compt_E-1].Length))
perimetre += (sel[0].Shape.Edges[compt_E-1].Length) # calculates the perimeter
# Displays the "Edge" and its length
App.Console.PrintMessage("Edge"+str(compt_E)+" Length > "+str(sel[0].Shape.Edges[compt_E-1].Length)+"\n")
# Displays the "Edge" and its center mass
App.Console.PrintMessage("Edge"+str(compt_E)+" Center > "+str(sel[0].Shape.Edges[compt_E-1].CenterOfMass)+"\n")
num = sel[0].Shape.Edges[compt_E-1].Vertexes[0]
Vertx.append("X1: "+str(num.Point.x))
Vertx.append("Y1: "+str(num.Point.y))
Vertx.append("Z1: "+str(num.Point.z))
# Displays the coordinates 1
App.Console.PrintMessage("X1: "+str(num.Point[0])+" Y1: "+str(num.Point[1])+" Z1: "+str(num.Point[2])+"\n")
try:
num = sel[0].Shape.Edges[compt_E-1].Vertexes[1]
Vertx.append("X2: "+str(num.Point.x))
Vertx.append("Y2: "+str(num.Point.y))
Vertx.append("Z2: "+str(num.Point.z))
except:
Vertx.append("-")
Vertx.append("-")
Vertx.append("-")
# Displays the coordinates 2
App.Console.PrintMessage("X2: "+str(num.Point[0])+" Y2: "+str(num.Point[1])+" Z2: "+str(num.Point[2])+"\n")
App.Console.PrintMessage("\n")
App.Console.PrintMessage("Perimeter of the form : "+str(perimetre)+"\n")
App.Console.PrintMessage("\n")
FacesSurf = []
for j in enumerate(sel[0].Shape.Faces): # Search the "Faces" and their surface
compt_F+=1
Faces.append("Face%d" % (j[0]+1))
FacesSurf.append(str(sel[0].Shape.Faces[compt_F-1].Area))
# Displays 'Face' and its surface
App.Console.PrintMessage("Face"+str(compt_F)+" > Surface "+str(sel[0].Shape.Faces[compt_F-1].Area)+"\n")
# Displays 'Face' and its CenterOfMass
App.Console.PrintMessage("Face"+str(compt_F)+" > Center "+str(sel[0].Shape.Faces[compt_F-1].CenterOfMass)+"\n")
# Displays 'Face' and its Coordinates
FacesCoor = []
fco = 0
for f0 in sel[0].Shape.Faces[compt_F-1].Vertexes: # Search the Vertexes of the face
fco += 1
FacesCoor.append("X"+str(fco)+": "+str(f0.Point.x))
FacesCoor.append("Y"+str(fco)+": "+str(f0.Point.y))
FacesCoor.append("Z"+str(fco)+": "+str(f0.Point.z))
# Displays 'Face' and its Coordinates
App.Console.PrintMessage("Face"+str(compt_F)+" > Coordinate"+str(FacesCoor)+"\n")
# Displays 'Face' and its Volume
App.Console.PrintMessage("Face"+str(compt_F)+" > Volume "+str(sel[0].Shape.Faces[compt_F-1].Volume)+"\n")
App.Console.PrintMessage("\n")
# Displays the total surface of the form
App.Console.PrintMessage("Surface of the form : "+str(sel[0].Shape.Area)+"\n")
# Displays the total Volume of the form
App.Console.PrintMessage("Volume of the form : "+str(sel[0].Shape.Volume)+"\n")
detail()
import FreeCADGui
from FreeCAD import Console
o = App.ActiveDocument.ActiveObject
op = o.PropertiesList
for p in op:
Console.PrintMessage("Property: "+ str(p)+ " Value: " + str(o.getPropertyByName(p))+"\r\n")
Examples of research and decoding information on an object.
Each section is independently and is separated by "############" can be copied directly into the Python console, or in a macro or use this macro. The description of the macro in the commentary.
Displaying it in the "Report View" window (View > Views > Report view)
</translate>
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
# Exemples de recherche et de decodage d'informations sur un objet
# Chaque section peut etre copiee directement dans la console Python ou dans une macro ou utilisez la macro tel quel
# Certaines commandes se repetent seul l'approche est differente
# L'affichage se fait dans la Vue rapport : Menu Affichage > Vues > Vue rapport
#
# Examples of research and decoding information on an object
# Each section can be copied directly into the Python console, or in a macro or uses this macro
# Certain commands as repeat alone approach is different
# Displayed in Report view: View > Views > report view
#
# rev:30/08/2014:29/09/2014:17/09/2015 22/11/2019 30/12/2022
from FreeCAD import Base
import DraftVecUtils, Draft, Part
##################################################################################
# info in the object
box = App.ActiveDocument.getObject('Box') # object
####
print(dir(box)) # all options disponible in the object
####
print(box.Name) # object name
####
print(box.Content) # content of the object in XML format
##################################################################################
#
# example of using the information listed
#
# search the name of the active document
mydoc = FreeCAD.activeDocument().Name # Name of active Document
App.Console.PrintMessage("Active docu : "+(mydoc)+"\n")
##################################################################################
# search the document name and the name of the object selected
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
object_FullName = sel[0].FullName # file Name and Name of the object selected
App.Console.PrintMessage("object_FullName: "+(object_FullName)+"\n")
##################################################################################
# search the label of the object selected
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")
##################################################################################
#TypeID object FreeCAD selected
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
App.Console.PrintMessage("sel : "+str(sel[0])+"\n\n") # sel[0] first object selected
##################################################################################
# search the Name of the 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")
##################################################################################
# search the Sub Element Name of the sub object selected
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")
##################################################################################
# give the length of the subObject selected
SubElementLength = Gui.Selection.getSelectionEx()[0].SubObjects[0].Length # sub element or element name with getSelectionEx()
App.Console.PrintMessage("SubElement length: "+str(SubElementLength)+"\n")# length
##################################################################################
# list the edges and the coordinates of the object[0] selected
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")
##################################################################################
# give the sub element name, length, coordinates, BoundBox, BoundBox.Center, Area of the SubObjects selected
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")
try:
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")
except:
App.Console.PrintMessage("Oups"+"\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")
##################################################################################
# give the area of the object
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
surface = sel[0].Shape.Area # Area object complete
App.Console.PrintMessage("surfaceObjet : "+str(surface)+"\n\n")
##################################################################################
# give the Center Of Mass and coordinates of the object
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") # or CenterOfMass.x, CenterOfMass.y, CenterOfMass.z
App.Console.PrintMessage("CenterOfMassZ : "+str(CenterOfMass[2])+"\n\n")
##################################################################################
# list the all faces of the object selected
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")
##################################################################################
# give the volume of the object selected
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")
##################################################################################
# give the BoundBox of the oject selected all type
objs = FreeCADGui.Selection.getSelection() # select object with getSelection()
if len(objs) >= 1: # serch the object type
if hasattr(objs[0], "Shape"):
s = objs[0].Shape
elif hasattr(objs[0], "Mesh"): # upgrade with wmayer thanks #http://forum.freecadweb.org/viewtopic.php?f=13&t=22331
s = objs[0].Mesh
elif hasattr(objs[0], "Points"):
s = objs[0].Points
boundBox_= s.BoundBox # BoundBox of the object
App.Console.PrintMessage("boundBox_ : "+str(boundBox_)+"\n") #
boundBoxLX = boundBox_.XLength # Length x boundBox rectangle
boundBoxLY = boundBox_.YLength # Length y boundBox rectangle
boundBoxLZ = boundBox_.ZLength # Length z boundBox rectangle
boundBoxXMin = boundBox_.XMin # coordonate XMin
boundBoxYMin = boundBox_.YMin # coordonate YMin
boundBoxZMin = boundBox_.ZMin # coordonate ZMin
boundBoxXMax = boundBox_.XMax # coordonate XMax
boundBoxYMax = boundBox_.YMax # coordonate YMax
boundBoxZMax = boundBox_.ZMax # coordonate ZMax
boundBoxDiag= boundBox_.DiagonalLength # Diagonal Length boundBox rectangle
boundBoxCenter = boundBox_.Center # BoundBox Center
boundBoxCenterOfGravity = boundBox_.CenterOfGravity # BoundBox CenterOfGravity
App.Console.PrintMessage("boundBoxLX : "+str(boundBoxLX)+"\n")
App.Console.PrintMessage("boundBoxLY : "+str(boundBoxLY)+"\n")
App.Console.PrintMessage("boundBoxLZ : "+str(boundBoxLZ)+"\n\n")
App.Console.PrintMessage("boundBoxXMin : "+str(boundBoxXMin)+"\n")
App.Console.PrintMessage("boundBoxYMin : "+str(boundBoxYMin)+"\n")
App.Console.PrintMessage("boundBoxZMin : "+str(boundBoxZMin)+"\n")
App.Console.PrintMessage("boundBoxXMax : "+str(boundBoxXMax)+"\n")
App.Console.PrintMessage("boundBoxYMax : "+str(boundBoxYMax)+"\n")
App.Console.PrintMessage("boundBoxZMax : "+str(boundBoxZMax)+"\n\n")
App.Console.PrintMessage("boundBoxDiag : "+str(boundBoxDiag)+"\n")
App.Console.PrintMessage("boundBoxCenter : "+str(boundBoxCenter)+"\n")
App.Console.PrintMessage("boundBox Center of Gravity : "+str(boundBoxCenterOfGravity )+"\n\n")
##################################################################################
# give the complete placement of the object selected
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")
##################################################################################
# give the placement Base (xyz) of the object selected
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")
##################################################################################
# give the placement Base (xyz) of the object selected
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
oripl_X = sel[0].Placement.Base[0] # decode Placement X
oripl_Y = sel[0].Placement.Base[1] # decode Placement Y
oripl_Z = sel[0].Placement.Base[2] # decode Placement Z
# same
#oripl_X = sel[0].Placement.Base.x # decode Placement X
#oripl_Y = sel[0].Placement.Base.y # decode Placement Y
#oripl_Z = sel[0].Placement.Base.z # decode Placement Z
App.Console.PrintMessage("oripl_X : "+str(oripl_X)+"\n")
App.Console.PrintMessage("oripl_Y : "+str(oripl_Y)+"\n")
App.Console.PrintMessage("oripl_Z : "+str(oripl_Z)+"\n\n")
##################################################################################
# give the placement rotation of the object selected (x, y, z, angle rotation)
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
rotation = sel[0].Placement.Rotation # decode Placement Rotation
App.Console.PrintMessage("rotation : "+str(rotation)+"\n\n")
##################################################################################
# give the placement rotation of the object selected (x, y, z, angle rotation)
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")
##################################################################################
# give the rotation of the object selected (angle rotation)
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")
##################################################################################
# give the rotation.Q of the object selected (angle rotation in Radian) for convert: math.degrees(angleInRadian)
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
Rot = sel[0].Placement.Rotation.Q # Placement Rotation Q
App.Console.PrintMessage("Rot : "+str(Rot)+ "\n")
Rot_0 = sel[0].Placement.Rotation.Q[0] # decode Placement Rotation Q
App.Console.PrintMessage("Rot_0 : "+str(Rot_0)+ " rad , "+str(180 * Rot_0 / 3.1416)+" deg "+"\n") # or math.degrees(angle)
Rot_1 = sel[0].Placement.Rotation.Q[1] # decode Placement Rotation 1
App.Console.PrintMessage("Rot_1 : "+str(Rot_1)+ " rad , "+str(180 * Rot_1 / 3.1416)+" deg "+"\n") # or math.degrees(angle)
Rot_2 = sel[0].Placement.Rotation.Q[2] # decode Placement Rotation 2
App.Console.PrintMessage("Rot_2 : "+str(Rot_2)+ " rad , "+str(180 * Rot_2 / 3.1416)+" deg "+"\n") # or math.degrees(angle)
Rot_3 = sel[0].Placement.Rotation.Q[3] # decode Placement Rotation 3
App.Console.PrintMessage("Rot_3 : "+str(Rot_3)+"\n\n")
Rot_Axis = sel[0].Placement.Rotation.Axis # Placement Rotation .Axis
App.Console.PrintMessage("Rot_Axis : "+str(Rot_Axis)+ "\n")
Rot_Angle = sel[0].Placement.Rotation.Angle # Placement Rotation .Angle
App.Console.PrintMessage("Rot_Angle : "+str(Rot_Angle)+ "\n\n")
##################################################################################
# give the rotation of the object selected toEuler (angle rotation in degrees)
sel = FreeCADGui.Selection.getSelection() # select object with getSelection()
angle = sel[0].Shape.Placement.Rotation.toEuler() # angle Euler
App.Console.PrintMessage("Angle : "+str(angle)+"\n")
Yaw = sel[0].Shape.Placement.Rotation.toEuler()[0] # decode angle Euler Yaw (Z) lacet (alpha)
App.Console.PrintMessage("Yaw : "+str(Yaw)+"\n")
Pitch = sel[0].Shape.Placement.Rotation.toEuler()[1] # decode angle Euler Pitch (Y) tangage (beta)
App.Console.PrintMessage("Pitch : "+str(Pitch)+"\n")
Roll = sel[0].Shape.Placement.Rotation.toEuler()[2] # decode angle Euler Roll (X) roulis (gamma)
App.Console.PrintMessage("Roll : "+str(Roll)+"\n\n")
rot = App.Rotation()
rot.setYawPitchRoll(45,45,0)
print("Angle: ", rot.Angle)
print("Axis: ", rot.Axis)
print("RawAxis: ", rot.RawAxis)
print("YawPitchRoll: ", rot.getYawPitchRoll())
print("Rotation: ", rot)
print("Quaternion: ", rot.Q)
##################################################################################
# find Midpoint of the selected line
import Draft, DraftGeomUtils
sel = FreeCADGui.Selection.getSelection()
vecteur = DraftGeomUtils.findMidpoint(sel[0].Shape.Edges[0]) # find Midpoint
App.Console.PrintMessage(vecteur)
Draft.makePoint(vecteur)
##################################################################################
This code displays the Cartesian coordinates of the selected item.
Change the value of "numberOfPoints" if you want a different number of points (precision)
</translate>
numberOfPoints = 100 # Decomposition number (or precision you can change)
selectedEdge = FreeCADGui.Selection.getSelectionEx()[0].SubObjects[0].copy() # select one element
points = selectedEdge.discretize(numberOfPoints) # discretize the element
i=0
for p in points: # list and display the coordinates
i+=1
print( i, " X", p.x, " Y", p.y, " Z", p.z)
<translate>
Other method display on "Int" and "Float"
</translate>
import Part
from FreeCAD import Base
c=Part.makeCylinder(2,10) # create the circle
Part.show(c) # display the shape
# slice accepts two arguments:
#+ the normal of the cross section plane
#+ the distance from the origin to the cross section plane. Here you have to find a value so that the plane intersects your object
s=c.slice(Base.Vector(0,1,0),0) #
# here the result is a single wire
# depending on the source object this can be several wires
s=s[0]
# if you only need the vertexes of the shape you can use
v=[]
for i in s.Vertexes:
v.append(i.Point)
# but you can also sub-sample the section to have a certain number of points (int) ...
p1=s.discretize(20)
ii=0
for i in p1:
ii+=1
print( i ) # Vector()
print( ii, ": X:", i.x, " Y:", i.y, " Z:", i.z ) # Vector decode
Draft.makeWire(p1,closed=False,face=False,support=None) # to see the difference accuracy (20)
## uncomment to use
#import Draft
#Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # first transform the DWire in Wire "downgrade"
#Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # second split the Wire in single objects "downgrade"
#
##Draft.upgrade(FreeCADGui.Selection.getSelection(),delete=True) # to attach lines contiguous SELECTED use "upgrade"
# ... or define a sampling distance (float)
p2=s.discretize(0.5)
ii=0
for i in p2:
ii+=1
print( i ) # Vector()
print( ii, ": X:", i.x, " Y:", i.y, " Z:", i.z ) # Vector decode
Draft.makeWire(p2,closed=False,face=False,support=None) # to see the difference accuracy (0.5)
## uncomment to use
#import Draft
#Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # first transform the DWire in Wire "downgrade"
#Draft.downgrade(App.ActiveDocument.ActiveObject,delete=True) # second split the Wire in single objects "downgrade"
#
##Draft.upgrade(FreeCADGui.Selection.getSelection(),delete=True) # to attach lines contiguous SELECTED use "upgrade"
import FreeCAD
for obj in FreeCAD.ActiveDocument.Objects:
print( obj.Name ) # display the object Name
objName = obj.Name
obj = App.ActiveDocument.getObject(objName)
Gui.Selection.addSelection(obj) # select the object
Select a face of an object by Name object and Face number
</translate>
# select one face of the object
import FreeCAD, Draft
App=FreeCAD
nameObject = "Box" # objet
faceSelect = "Face3" # face to selection
loch=App.ActiveDocument.getObject(nameObject) # objet
Gui.Selection.clearSelection() # clear all selection
Gui.Selection.addSelection(loch,faceSelect) # select the face specified
s = Gui.Selection.getSelectionEx()
#Draft.makeFacebinder(s) #
Get the normal vector of a face of an object by Name object and number Face (r.Q)
</translate>
## normal of a face by giving the number of the face and the name of the object (rotation Q with yL, uV) = (App.Vector (x, y, z), angle))
## normal d'une face en donnant le numero de la face et le nom de l'objet (rotation Q avec yL, uV) = (App.Vector(x, y, z),angle))
from FreeCAD import Vector
numero_Face = 2 # number of the face searched (begin 0, 1, 2, 3 .....)
nomObjet = "Box" # object name
yL = Gui.ActiveDocument.getObject(nomObjet).Object.Shape.Faces[numero_Face].CenterOfMass
uv = Gui.ActiveDocument.getObject(nomObjet).Object.Shape.Faces[numero_Face].Surface.parameter(yL)
nv = Gui.ActiveDocument.getObject(nomObjet).Object.Shape.Faces[numero_Face].normalAt(uv[0], uv[1])
direction = yL.sub(nv + yL)
print("Direction : ",direction)
r = App.Rotation(App.Vector(0,0,1),direction)
print("Rotation : ", r)
print("Rotation Q : ", r.Q)
Get the normal vector of a face of an object by Name object and number of Face
</translate>
numero_Face = 2 # number of the face searched (begin 0, 1, 2, 3 .....)
nomObjet = "Box" # object name
normal = Gui.ActiveDocument.getObject(nomObjet).Object.Shape.Faces[numero_Face].normalAt(0,0)
print("Face"+str(numero_Face), " : ", normal)
Get the normal vector of an object selected and number of Face
</translate>
## normal of a face by giving the number of the face of the selected object
selectionObjects = FreeCADGui.Selection.getSelection()
numero_Face = 3 # numero de la face recherchee
normal = selectionObjects[0].Shape.Faces[numero_Face].normalAt(0,0)
print(normal)
# selectionne la face numerotee
Gui.Selection.clearSelection()
Gui.Selection.addSelection(selectionObjects[0],"Face"+str(numero_Face))
This example show how to find normal vector on the surface by find the u,v parameters of one point on the surface and use u,v parameters to find normal vector
</translate>
def normal(self):
ss=FreeCADGui.Selection.getSelectionEx()[0].SubObjects[0].copy()#SubObjects[0] is the edge list
points = ss.discretize(3.0)#points on the surface edge,
#this example just use points on the edge for example.
#However point is not necessary on the edge, it can be anywhere on the surface.
face=FreeCADGui.Selection.getSelectionEx()[0].SubObjects[1]
for pp in points:
pt=FreeCAD.Base.Vector(pp.x,pp.y,pp.z)#a point on the surface edge
uv=face.Surface.parameter(pt)# find the surface u,v parameter of a point on the surface edge
u=uv[0]
v=uv[1]
normal=face.normalAt(u,v)#use u,v to find normal vector
print( normal)
line=Part.makeLine((pp.x,pp.y,pp.z), (normal.x,normal.y,normal.z))
Part.show(line)
# create one object of the position to camera with "getCameraOrientation()"
# the object is still facing the screen
import Draft
plan = FreeCADGui.ActiveDocument.ActiveView.getCameraOrientation()
plan = str(plan)
###### extract data
a = ""
for i in plan:
if i in ("0123456789e.- "):
a+=i
a = a.strip(" ")
a = a.split(" ")
####### extract data
#print( a)
#print( a[0])
#print( a[1])
#print( a[2])
#print( a[3])
xP = float(a[0])
yP = float(a[1])
zP = float(a[2])
qP = float(a[3])
pl = FreeCAD.Placement()
pl.Rotation.Q = (xP,yP,zP,qP) # rotation of object
pl.Base = FreeCAD.Vector(0.0,0.0,0.0) # here coordinates XYZ of Object
rec = Draft.makeRectangle(length=10.0,height=10.0,placement=pl,face=False,support=None) # create rectangle
#rec = Draft.makeCircle(radius=5,placement=pl,face=False,support=None) # create circle
print( rec.Name)
import Draft
doc = FreeCAD.ActiveDocument
pl=FreeCAD.Placement()
pl.Rotation.Q=(0.0,-0.0,-0.0,1.0)
pl.Base=FreeCAD.Vector(0.0,0.0,0.0)
obj = Draft.makeCircle(radius=1.0,placement=pl,face=False,support=None) # create circle
print( obj.PropertiesList ) # properties disponible in the obj
doc.getObject(obj.Name).setExpression('Radius', u'2mm') # modify the radius
doc.getObject(obj.Name).setExpression('Placement.Base.x', u'10mm') # modify the placement
doc.getObject(obj.Name).setExpression('FirstAngle', u'90') # modify the first angle
doc.recompute()
expressions = obj.ExpressionEngine # read the expression list
print( expressions)
for i in expressions: # list and separate the data expression
print( i[0]," = ",i[1])
This snippet can be useful, if you want to create a sketch on a surface in PartDesign from inside a macro.
Note, that body might be None, if no active body is selected and that the Selection might be empty.
This snippet demonstrates how to create a face with internal holes through the Python API. See forum thread.
</translate>
import FreeCAD, Part
# Create poles that will define the Face
pts = [(-2, 2, 0),
(0, 2, 1),
(2, 2, 0),
(2, -2, 0),
(0, -2, 1),
(-2, -2, 0)]
bs = Part.BSplineCurve()
bs.buildFromPoles(pts, True) # True makes this periodic/closed
# Make the Face from the curve
myFace = Part.makeFilledFace([bs.toShape()])
# Create geometry for holes that will be cut in the surface
hole0 = Part.Geom2d.Circle2d(FreeCAD.Base.Vector2d(0,0), 1.0)
hole1 = Part.Geom2d.Circle2d(FreeCAD.Base.Vector2d(0,1.5), 0.1)
edge0 = hole0.toShape(myFace)
edge1 = hole1.toShape(myFace)
wireb = Part.Wire(bs.toShape())
wire0 = Part.Wire(edge0)
wire1 = Part.Wire(edge1)
# Cut holes in the face
myFace.cutHoles([wire0])
myFace.validate() # This is required
myFace.cutHoles([wire1])
myFace.validate()
Part.show(myFace)
This page shows how advanced functionality can easily be created in Python. In this exercise, we will build a new tool that draws a line. This tool can then be linked to a FreeCAD command, and that command can be called by any element in the interface, like a menu item or a toolbar button.
The main script
First we will write a script containing all our functionality. Then we will save this in a file and import it in FreeCAD to make all its classes and functions available. Launch your favorite code editor and type the following lines:
</translate>
import FreeCADGui, Part
from pivy.coin import *
class line:
"""This class will create a line after the user clicked 2 points on the screen"""
def __init__(self):
self.view = FreeCADGui.ActiveDocument.ActiveView
self.stack = []
self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(), self.getpoint)
def getpoint(self, event_cb):
event = event_cb.getEvent()
if event.getState() == SoMouseButtonEvent.DOWN:
pos = event.getPosition()
point = self.view.getPoint(pos[0], pos[1])
self.stack.append(point)
if len(self.stack) == 2:
l = Part.LineSegment(self.stack[0], self.stack[1])
shape = l.toShape()
Part.show(shape)
self.view.removeEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(), self.callback)
In Python when you want to use functions from another module you need to import it. In our case we will need functions from the Part module, for creating the line, and from the Gui module FreeCADGui, for accessing the 3D view. We also need the complete contents of the Coin library so we can directly use all Coin objects like SoMouseButtonEvent, etc.
</translate>
class line:
<translate>
Here we define our main class. Why do we use a class and not a function? The reason is that we need our tool to stay "alive" while we are waiting for the user to click on the screen. A function ends when its task has been done, but an object (a class defines an object) stays alive until it is destroyed.
</translate>
"""This class will create a line after the user clicked 2 points on the screen"""
<translate>
In Python, every class or function can have a documentation string (docstring). This is particularly useful in FreeCAD, because when you call that class in the interpreter, the description string will be displayed as a tooltip.
</translate>
def __init__(self):
<translate>
Python classes can always contain an __init__ function, which is executed when the class is called to create an object. Here we will put everything we want to happen when our line tool begins.
</translate>
self.view = FreeCADGui.ActiveDocument.ActiveView
<translate>
In a class you usually want to prepend self. to variable names to make the variables easily accessible to all functions inside and outside the class. Here we will use self.view to access and manipulate the active 3D view.
</translate>
self.stack = []
<translate>
Here we create an empty list that will contain the 3D points sent by the getpoint() function.
This is the important part. Since we are dealing with a Coin3D scene, we use a Coin callback mechanism that allows a function to be called every time a certain scene event happens. In our case we are creating a callback for SoMouseButtonEvent events, and we bind it to the getpoint() function. Now every time a mouse button is pressed or released the getpoint() function will be executed.
Note that there is also an alternative to addEventCallbackPivy() called addEventCallback() which does not rely on pivy. But since pivy is a very efficient and natural way to access any part of a Coin scene, it is the better choice.
Now we define the getpoint() function that will be executed when a mouse button is pressed in a 3D view. This function will receive an argument that we will call event_cb. From this event callback we can access the event object, which contains several pieces of information (more info here).
</translate>
if event.getState() == SoMouseButtonEvent.DOWN:
<translate>
The getpoint() function will be called when a mouse button is pressed or released. But we only want to pick a 3D point when a button is pressed, otherwise we would end up with two 3D points very close together. So we must check for that here.
</translate>
pos = event.getPosition()
<translate>
Here we get the screen coordinates of the mouse cursor.
</translate>
point = self.view.getPoint(pos[0], pos[1])
<translate>
This function gives us a FreeCAD vector (x,y,z) containing the 3D point that lies on the focal plane, just under our mouse cursor. If you are in camera view, imagine a ray coming from the camera, passing through the mouse cursor, and hitting the focal plane. That is the location of our 3D point. If we are in orthogonal view, the ray is parallel to the view direction.
</translate>
self.stack.append(point)
<translate>
We add our new point to the stack.
</translate>
if len(self.stack) == 2:
<translate>
Do we have enough points already? if yes, then let's draw the line!
</translate>
l = Part.LineSegment(self.stack[0], self.stack[1])
<translate>
Here we use the LineSegment() function from the Part module that creates a line from two FreeCAD vectors. The line is not bound to any object in our active document, so nothing appears on the screen.
</translate>
shape = l.toShape()
<translate>
The FreeCAD document can only accept shapes from the Part module. Shapes are the most generic type of the Part module. So we must convert our line to a shape before adding it to the document.
</translate>
Part.show(shape)
<translate>
The Part module has a very handy show() function that creates a new object in the document and binds a shape to it. We could also have created a new object in the document first and then bound the shape to it manually.
Now let's save our script in a folder where the FreeCAD Python interpreter can find it. When importing modules, the interpreter will look in the following places: the Python installation paths, the FreeCAD bin folder, and all FreeCAD Mod (module) folders. So the best solution is to create a new folder in one of the Mod folders. Let's create a MyScripts folder there and save our script in it as exercise.py.
Now everything is ready. Let's start FreeCAD, create a new document, and in the Python interpreter issue:
</translate>
import exercise
<translate>
If no error message appears our exercise script has been loaded successfully. We can now check its contents with:
</translate>
dir(exercise)
<translate>
The command dir() is a built-in Python command that lists the contents of a module. We can check that our line() class is there with:
</translate>
'line' in dir(exercise)
<translate>
Now let's test it:
</translate>
exercise.line()
<translate>
Click two times in the 3D view and bingo: here is our line! To repeat it just type exercise.line() again.
For our new line tool to be really useful, and to avoid having to type all that stuff, it should have a button in the interface. One way to do this is to transform our new MyScripts folder into a full FreeCAD workbench. This is easy, all that is needed is to put a file called InitGui.py inside the MyScripts folder. InitGui.py will contain the instructions to create a new workbench, and add our new tool to it. Besides that we will also need to change our exercise code a bit, so the line() tool is recognized as an official FreeCAD command. Let's start by creating an InitGui.py file, and writing the following code in it:
By now you probably understand the above script. We create a new class that we call MyWorkbench, we give it a title MenuText, and we define an Initialize() function that will be executed when the workbench is loaded into FreeCAD. In that function, we load the contents of our exercise file, and append the FreeCAD commands found inside to a command list. Then, we make a toolbar called "My Scripts" and we assign our command list to it. Currently, of course, we only have one tool, so our command list contains only one element. Then, once our workbench is ready, we add it to the main interface.
But this still won't work because a FreeCAD command must be formatted in a certain manner to work, we will need to change our line() tool. Our new exercise.py script should look like this:
</translate>
import FreeCADGui, Part
from pivy.coin import *
class line:
"""This class will create a line after the user clicked 2 points on the screen"""
def Activated(self):
self.view = FreeCADGui.ActiveDocument.ActiveView
self.stack = []
self.callback = self.view.addEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(), self.getpoint)
def getpoint(self, event_cb):
event = event_cb.getEvent()
if event.getState() == SoMouseButtonEvent.DOWN:
pos = event.getPosition()
point = self.view.getPoint(pos[0], pos[1])
self.stack.append(point)
if len(self.stack) == 2:
l = Part.LineSegment(self.stack[0], self.stack[1])
shape = l.toShape()
Part.show(shape)
self.view.removeEventCallbackPivy(SoMouseButtonEvent.getClassTypeId(), self.callback)
def GetResources(self):
return {'Pixmap': 'path_to_an_icon/line_icon.png', 'MenuText': 'Line', 'ToolTip': 'Creates a line by clicking 2 points on the screen'}
FreeCADGui.addCommand('line', line())
<translate>
What we did here is transform our __init__() function into an Activated() function. When FreeCAD commands are run, they automatically execute the Activated() function. We also added a GetResources() function, that informs FreeCAD where it can find the icon for the tool, and what will be the name and tooltip of our tool. Any jpg, png or svg image will work as an icon, it can be any size, but it is best to use a size that is close to the final aspect, like 16x16, 24x24 or 32x32.
Then we add the line() class as an official FreeCAD command with the addCommand() method.
That's it, now we just need to restart FreeCAD and we'll have a nice new workbench with our brand new line tool!
If you liked this exercise, why not try to improve this little tool? There are many things that can be done, for example:
Add user feedback: until now we did a very bare tool, the user might be a bit lost when using it. So we could add some feedback, telling the user what to do next. You could issue messages to the FreeCAD console. Have a look in the FreeCAD.Console module.
Add a possibility to type the 3D points coordinates manually. Look at the Python input() function for example.
Add the possibility to add more than 2 points.
Add events for other things: Now we just check for Mouse button events, what if we would also do something when the mouse is moved, like displaying current coordinates?
Give a name to the created object.
Don't hesitate to ask questions or share ideas on the forum!
In this page we will show how to build a simple graphical interface with Qt Designer, Qt's official tool for designing interfaces; the dialog will be converted to Python code, then it will be used inside FreeCAD. We'll assume that the user knows how to edit and run Python generally.
In this example, the entire interface is defined in Python. Although this is possible for small interfaces, for larger interfaces the recommendation is to load the created .ui files directly into the program.
Two general methods to create interfaces, by including the interface in the Python file, or by using .ui files.
Designing the dialog
In CAD applications, designing a good UI (User Interface) is very important. About everything the user will do will be through some piece of interface: reading dialog boxes, pressing buttons, choosing between icons, etc. So it is very important to think carefully to what you want to do, how you want the user to behave, and how will be the workflow of your action.
There are a couple of concepts to know when designing interface:
Modal/non-modal dialogs: A modal dialog appears in front of your screen, stopping the action of the main window, forcing the user to respond to the dialog, while a non-modal dialog doesn't stop you from working on the main window. In some case the first is better, in other cases not.
Identifying what is required and what is optional: Make sure the user knows what he must do. Label everything with proper description, use tooltips, etc.
Separating commands from parameters: This is usually done with buttons and text input fields. The user knows that clicking a button will produce an action while changing a value inside a text field will change a parameter somewhere. Nowadays, though, users usually know well what is a button, what is an input field, etc. The interface toolkit we are using, Qt, is a state-of-the-art toolkit, and we won't have to worry much about making things clear, since they will already be very clear by themselves.
So, now that we have well defined what we will do, it's time to open the qt designer. Let's design a very simple dialog, like this:
We will then use this dialog in FreeCAD to produce a nice rectangular plane. You might find it not very useful to produce nice rectangular planes, but it will be easy to change it later to do more complex things. When you open it, Qt Designer looks like this:
Creating the dialog
Qt Designer is very simple to use. On the left bar you have elements that can be dragged on your widget. On the right side you have properties panels displaying all kinds of editable properties of selected elements. So, begin with creating a new widget.
Select "Dialog without buttons", since we don't want the default OK/Cancel buttons.
We need 'Labels. Labels are simple text strings that appear on your widget to inform the end user. If you select a label, notice that on the right side there will appear several properties that you can modify such as: font style, height, etc... So lets drag 3 separate labels on to our widget:
One label for the title
Another label for writing "Height"
Another label for writing "Width"
We now need LineEdits (2 of them actually). Drag two of them on to the widget. LineEdits are text fields that the end user can fill in. So we need one LineEdit for the Height and one for the Width. Here too, we can edit properties. For example, why not set a default value say for example: 1.00 for each. This way, when the user will see the dialog, both values will be filled already. If the end user is satisfied, they can directly press the button, saving precious time.
Next lets add a PushButton. This is the button the end user will need to press after they've filled both fields.
Note: that we chose very simple controls here. Qt has many more options, for example one could use Spinboxes instead of LineEdits, etc... Have a look at what is available, explore...you will surely have other ideas.
That's about all we need to do in Qt Designer. One last thing, though, let's rename all our elements with simpler names, so it will be easier to identify them in our scripts:
</translate>
<translate>
Converting our dialog to python
</translate>
<translate>
Now, let's save our widget somewhere. It will be saved as an .ui file, that we will easily convert to python script with pyuic. On windows, the pyuic program is bundled with pyqt (to be verified), on linux you probably will need to install it separately from your package manager (on debian-based systems, it is part of the pyqt4-dev-tools package). To do the conversion, you'll need to open a terminal window (or a command prompt window on windows), navigate to where you saved your .ui file, and issue:
</translate>
pyuic mywidget.ui > mywidget.py
<translate>
In Windows pyuic.py is located in "C:\Python27\Lib\site-packages\PyQt4\uic\pyuic.py"
For conversion create a batch file called "compQt4.bat:
</translate>
<translate>
In the DOS console type without extension
</translate>
compQt4 myUiFile
<translate>
In macOS, you can retrieve the appropriate version (the same that is used internally in FreeCAD 0.19) of QT and Pyside with these commands (pip required)
</translate>
<translate>
This will install uic in the folder "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/PySide2/uic", and Designer in "/Library/Frameworks/Python.framework/Versions/3.7/lib/python3.7/site-packages/PySide2/Designer.app".
For convenience you can create a link of uic in /usr/local/bin to be able to call it simply with uic -g python ... instead of typing the whole path of the program, and a link to Designer to retrieve it in the mac's Applications folder with
</translate>
<translate>
Since FreeCAD progressively moved away from PyQt after version 0.13, in favour of PySide (Choose your PySide install building PySide), to make the file based on PySide now you have to use:
</translate>
pyside-uic mywidget.ui -o mywidget.py
<translate>
In Windows uic.py are located in "C:\Python27\Lib\site-packages\PySide\scripts\uic.py"
For create batch file "compSide.bat":
</translate>
<translate>
In the DOS console type without extension
</translate>
compSide myUiFile
<translate>
Into Linux : to do
On some systems the program is called pyuic4 instead of pyuic. This will simply convert the .ui file into a python script. If we open the mywidget.py file, its contents is very easy to understand:
</translate>
<translate>
As you see it has a very simple structure: a class named Ui_Dialog is created, that stores the interface elements of our widget. That class has two methods, one for setting up the widget, and one for translating its contents, which is part of the general Qt mechanism for translating interface elements. The setup method simply creates, one by one, the widgets as we defined them in Qt Designer, and sets their options as we decided earlier. Then, the whole interface gets translated, and finally, the slots get connected (we'll talk about that later).
We can now create a new widget and use this class to create its interface. We can already see our widget in action, by putting our mywidget.py file in a place where FreeCAD will find it (in the FreeCAD bin directory, or in any of the Mod subdirectories), and, in the FreeCAD python interpreter, issue:
</translate>
from PySide import QtGui
import mywidget
d = QtGui.QWidget()
d.ui = mywidget.Ui_Dialog()
d.ui.setupUi(d)
d.show()
<translate>
And our dialog will appear! Note that our Python interpreter is still working, we have a non-modal dialog. So, to close it, we can (apart from clicking its close icon, of course) issue:
</translate>
d.hide()
<translate>
Making our dialog do something
Now that we can show and hide our dialog, we just need to add one last part: To make it do something! If you play a bit with Qt designer, you'll quickly discover a whole section called "signals and slots". Basically, it works like this: elements on your widgets (in Qt terminology, those elements are themselves widgets) can send signals. Those signals differ according to the widget type. For example, a button can send a signal when it is pressed and when it is released. Those signals can be connected to slots, which can be special functionality of other widgets (for example a dialog has a "close" slot to which you can connect the signal from a close button), or can be custom functions. The PyQt Reference Documentation lists all the qt widgets, what they can do, what signals they can send, etc...
What we will do here, is to create a new function that will create a plane based on height and width, and to connect that function to the pressed signal emitted by our "Create!" button. So, let's begin with importing our FreeCAD modules, by putting the following line at the top of the script, where we already import QtCore and QtGui:
</translate>
import FreeCAD, Part
<translate>
Then, let's add a new function to our Ui_Dialog class:
</translate>
def createPlane(self):
try:
# first we check if valid numbers have been entered
w = float(self.width.text())
h = float(self.height.text())
except ValueError:
print("Error! Width and Height values must be valid numbers!")
else:
# create a face from 4 points
p1 = FreeCAD.Vector(0,0,0)
p2 = FreeCAD.Vector(w,0,0)
p3 = FreeCAD.Vector(w,h,0)
p4 = FreeCAD.Vector(0,h,0)
pointslist = [p1,p2,p3,p4,p1]
mywire = Part.makePolygon(pointslist)
myface = Part.Face(mywire)
Part.show(myface)
self.hide()
<translate>
Then, we need to inform Qt to connect the button to the function, by placing the following line just before QtCore.QMetaObject.connectSlotsByName(Dialog):
</translate>
<translate>
This, as you see, connects the pressed() signal of our create object (the "Create!" button), to a slot named createPlane, which we just defined. That's it! Now, as a final touch, we can add a little function to create the dialog, it will be easier to call. Outside the Ui_Dialog class, let's add this code:
</translate>
<translate>
(Python reminder: the __init__ method of a class is automatically executed whenever a new object is created!)
Then, from FreeCAD, we only need to do:
</translate>
import mywidget
myDialog = mywidget.plane()
<translate>
That's all Folks... Now you can try all kinds of things, like for example inserting your widget in the FreeCAD interface (see the Code snippets page), or making much more advanced custom tools, by using other elements on your widget.
The complete script
This is the complete script, for reference:
</translate>
# Form implementation generated from reading ui file 'mywidget.ui'
#
# Created: Mon Jun 1 19:09:10 2009
# by: PyQt4 UI code generator 4.4.4
# Modified for PySide 16:02:2015
# WARNING! All changes made in this file will be lost!
from PySide import QtCore, QtGui
import FreeCAD, Part
class Ui_Dialog(object):
def setupUi(self, Dialog):
Dialog.setObjectName("Dialog")
Dialog.resize(187, 178)
self.title = QtGui.QLabel(Dialog)
self.title.setGeometry(QtCore.QRect(10, 10, 271, 16))
self.title.setObjectName("title")
self.label_width = QtGui.QLabel(Dialog)
self.label_width.setGeometry(QtCore.QRect(10, 50, 57, 16))
self.label_width.setObjectName("label_width")
self.label_height = QtGui.QLabel(Dialog)
self.label_height.setGeometry(QtCore.QRect(10, 90, 57, 16))
self.label_height.setObjectName("label_height")
self.width = QtGui.QLineEdit(Dialog)
self.width.setGeometry(QtCore.QRect(60, 40, 111, 26))
self.width.setObjectName("width")
self.height = QtGui.QLineEdit(Dialog)
self.height.setGeometry(QtCore.QRect(60, 80, 111, 26))
self.height.setObjectName("height")
self.create = QtGui.QPushButton(Dialog)
self.create.setGeometry(QtCore.QRect(50, 140, 83, 26))
self.create.setObjectName("create")
self.retranslateUi(Dialog)
QtCore.QObject.connect(self.create,QtCore.SIGNAL("pressed()"),self.createPlane)
QtCore.QMetaObject.connectSlotsByName(Dialog)
def retranslateUi(self, Dialog):
Dialog.setWindowTitle("Dialog")
self.title.setText("Plane-O-Matic")
self.label_width.setText("Width")
self.label_height.setText("Height")
self.create.setText("Create!")
print("tyty")
def createPlane(self):
try:
# first we check if valid numbers have been entered
w = float(self.width.text())
h = float(self.height.text())
except ValueError:
print("Error! Width and Height values must be valid numbers!")
else:
# create a face from 4 points
p1 = FreeCAD.Vector(0,0,0)
p2 = FreeCAD.Vector(w,0,0)
p3 = FreeCAD.Vector(w,h,0)
p4 = FreeCAD.Vector(0,h,0)
pointslist = [p1,p2,p3,p4,p1]
mywire = Part.makePolygon(pointslist)
myface = Part.Face(mywire)
Part.show(myface)
class plane():
def __init__(self):
self.d = QtGui.QWidget()
self.ui = Ui_Dialog()
self.ui.setupUi(self.d)
self.d.show()
The FreeCAD BugTracker is the place toː report bugs, submit feature requests, patches, or request to merge your branch if you developed something using Git. The tracker is divided into 'Workbenches', so please be specific and file your request in the appropriate subsection. In case of doubt, leave it in the "FreeCAD" section.
Recommended Workflow
As shown in the above flowchart, before creating tickets, please always first search the forums and bugtracker to discover if your issue is a known issue. This saves a lot of time/work for developers and volunteers that could be spending said time making FreeCAD even more awesome.
Reporting bugs
If you think you might have found a bug, you are welcome to report it as long as you have followed our step-by-step guidelinesː
Make sure you're using the most up to date version of FreeCAD. NOTEː your bug may be fixed in the Development (unstable) version. The average user runs the stable version of FC.
Make sure your bug is really a bug, that is, something that should be working but isn't. Make sure the same bug hasn't been reported before by first searching the bugtracker and forum.
Rememberː if you aren't sure, please don't hesitate to explain your problem/bug in the Help forum and ask what to do.
Noteː before posting to the forum please read the Forum Guidelines.
Describe as clearly as possible the problem, and how it can be reproduced. If we can not verify the bug, we might not be able to fix it.
This means reporting in a clear, well-formatted, step-by-step fashion so even an amateur user could reproduce.
Recommendedː Screenshots of the bug are also very helpful to include. Windows users: please do not attach screen captures in Word or PDF format. Use the Windows Snipping tool to save your capture as a PNG image.
Recommendedː Even better, an Animated gif or Screencast would also increase the likelihood of reproducing the issue.
Add an example FreeCAD file (.FCStd file) so devs/testers can quickly reproduce the bug.
Please don't zip your *.FCStd file, it is already zipped.
File attachments are limited in size. If your *.FCStd file is too big to attach, you can use an online storage service (many are free like Google Drive, Microsoft OneDrive, Dropbox).
Include all the information from the "Copy to Clipboard" button in the Help (menu) -> About FreeCAD dialogue. Make sure your data includes your OCC or OCE version.
Please file one separate report for each bug.
If your bug causes a crash in FreeCAD and you're on a system that supports it you can try running a debug backtrace and attach said trace to the ticket. This can save devs a lot of time pinpointing the source of the crash. See Debugging for more details.
Requesting features
If you want something to appear in FreeCAD that is not implemented yet, it is not a bug but a feature request.
IMPORTANTː Before requesting a potential Feature Request please be certain that you are the first one doing so by searching the forums and the bugtracker. If you have concluded that there are no pre-existing tickets/discussions the next step is toː
Start a forum thread to discuss your feature request with the community via the Open Discussion forum.
Once the community agrees that this is a valid Feature, you then can open a ticket on the tracker (file it under feature request instead of bug).
NOTE #1 To keep things organized please remember to link the forum thread URL into the ticket and the ticket number (as a link) in to the forum thread.
NOTE #2 Keep in mind there are no guarantees that your wish will be fulfilled.
FreeCAD Bugtracker report page - use the dropdown to correctly designate what the ticket is
Submitting patches
In case you have programmed a bug fix, an extension or something else that can be of public use in FreeCAD, submit your patch as a "Pull Request" at GitHub.
For a large, complex, or behavior-changing submission, open a forum thread in the Developer subforum to announce and discuss your patch. For small bugfixes this is not necessary.
Submit your Pull Request (PR) to the FreeCAD GitHub repo. The PR submission message will be pre-filled with a checklist for you to follow to ensure that your submission has the best chance at speedy acceptance. If you haven't worked with git before or are unfamiliar with submitting a PR to github, please read our introduction to github wiki page.
Be present for the discussion, both in the forum and in the GitHub pull request, so that your code can potentially be merged more effectively.
If you have created a git branch containing changes that you would like to see merged into the FreeCAD code, you can ask there to have your branch reviewed and merged if the FreeCAD developers are OK with it. You must first publish your branch to a public git repository (github, gitlab, bitbucket, sourceforge etc...) and then give the URL of your branch in your merge request.
MantisBT Tips and Tricks
MantisBT Markup
MantisBT (Mantis Bug Tracker) has it's own unique markup.
@mention - works just like on GitHub where if you prepend '@' to someone's username they will receive an email that they have been 'mentioned' in a ticket thread
#1234 - By adding a hash tag in front of a number a shortcut to link to another ticket within MantisBT will present.
Note: if you hover over a ticket it will show you the summary + if the ticket is closed, it will be struck-through like #1234.
~5678 - a shortcut that links to a bug note within a ticket. This can be used to reference someone's response within the thread. Each person that posts will show a unique ~#### number next to their username. If you look at the image in the example, you see that the shortcut is referencing the ticket number:comment number of said ticket
<del></del> - Using these tags will strikeout text.
<code></code> - To present a line or block of code, use this tag and it will colorize and differentiate it elegantly.
MantisBT BBCode
In addition to the above MantisBT Markup one also has the possibility to use BBCode format. For a comprehensive list see the BBCode plus plugin page. Here is a list of supported BBCode tagsː
[img][/img] - Images
[url][/url] - Links
[email][/email] - Email addresses
[color=red][/color] - Colored text
[highlight=yellow][/highlight] - Highlighted text
[size][/size] - Font size
[list][/list] - Lists
[list=1][/list] - Numbered lists (number is starting number)
[*] - List items
[b][/b] - Bold
[u][/u] - underline
[i][/i] - Italic
[s][/s] - Strikethrough
[left][/left] - Left align
[center][/center] - Center
[right][/right] - Right align
[justify][/justify] - Justify
[hr] - Horizontal rule
[sub][/sub] - Subscript
[sup][/sup] - Superscript
[table][/table] - Table
[table=1][/table] - Table with border of specified width
[tr][/tr] - Table row
[td][/td] - Table column
[code][/code] - Code block
[code=sql][/code] - Code block with language definition
[code start=3][/code] - Code block with line numbers starting at number
[quote][/quote] - Quote by *someone* (no name)
[quote=name][/quote] - Quote by *name*
MantisBT <=> GitHub Markup
Below are special MantisBT Source-Integration plugin keywords which will link to the FreeCAD GitHub repo. See GitHub and MantisBT.
c:FreeCAD:git commit hash: - c stands for 'commit'. FreeCAD stands for the FreeCAD GitHub repo. 'git commit hash' is the specific git commit hash to reference. Note: the trailing colon is necessary. Exampleː cːFreeCADː709d2f325db0490016807b8fa6f49d1c867b6bd8ː
d:FreeCAD:git commit hash: - similar to the above, d stands for 'diff' which will provide a Diff view of the commit. Exampleː dːFreeCADː709d2f325db0490016807b8fa6f49d1c867b6bd8ː
p:FreeCAD:pullrequest: - similar to the above, p stands for Pull Request. Exampleː pːFreeCADː498ː
GitHub and MantisBT
The FreeCAD bugtracker has a plug-in called Source Integration which essentially ties both the FreeCAD GitHub repo to our MantisBT tracker. It makes it easier to track and associate git commits with their respective MantisBT tickets. The Source Integration plugin scans the git commit messages for specific keywords in order to execute the following actions:
Note The below keywords need to be added in the git commit message and not the PR subject
Remotely referencing a ticket
Using this pattern will automagically associate a git commit to a ticket (Note: this will not close the ticket.)
The format MantisBT will recognize:
bug #1234
bugs #1234, #5678
issue #1234
issues #1234, #5678
report #1234
reports #1234, #5678
For the inquisitive here is the regex MantisBT uses for this operation: /(?:bugs?|issues?|reports?)+\s*:?\s+(?:#(?:\d+)[,\.\s]*)+/i
Remotely resolving a ticket
The format MantisBT will recognize:
fix #1234
fixed #1234
fixes #1234
fixed #1234, #5678
fixes #1234, #5678
resolve #1234
resolved #1234
resolves #1234
resolved #1234, #5678
resolves #1234, #5678
For the inquisitive here is the regex MantisBT uses for this operation: /(?:fixe?d?s?|resolved?s?)+\s*:?\s+(?:#(?:\d+)[,\.\s]*)+/i
This page explains step by step how to compile FreeCAD 0.19 or newer on Windows using Microsoft's MSVC compiler. For information on using MSYS2/MinGW see Compile on MinGW. For other platforms see Compiling.
Prerequisites
Compiling FreeCAD on Windows requires several tools and libraries.
Required
A compiler. FreeCAD is tested with Visual Studio (MSVC)—other compilers may work, but instructions for use are not included here. Fore more details, see the section Compiler below.
Git (There are also GUI frontends available for Git, see the next section.)
CMake version 3.11.x or newer. Hint: Choosing the option Add CMake to the system PATH for all users when installing CMake will make CMake accessible from the Windows command prompt, which can be useful.
The LibPack. This is a single package containing all of the libraries necessary to compile FreeCAD on Windows. Download the version of the LibPack that corresponds to the version of FreeCAD you want to compile. To compile FreeCAD 0.20 download the LibPack version 2.6, for FreeCAD 0.19 download the LibPack version 1.0. Extract the LibPack to a convenient location. (If your computer does not recognize the .7z extension, you must install the program 7-zip.) Note: It is highly recommended to compile FreeCAD with the compiler version the LibPack is designed for. For example, you might run into problems compiling FreeCAD 0.20 using MSVC 2017 because the LibPack is designed to be built with MSVC 2019 or newer. To update your LibPack later, see the section Updating the LibPack.
Optional programs
A GUI frontend for Git. There are several frontends available, see this list. The main benefit of a frontend is that you don't have to learn the Git commands to get the source code of FreeCAD or to send patches to the GitHub repository of FreeCAD.
In the following we describe source code handling using the TortoiseGit frontend. This frontend integrates directly into Windows file explorer and has a large user community to get help in case you have problems.
NSIS is used to generate the FreeCAD Windows installer.
The latest source code will be downloaded from the FreeCAD Git repository and the folder will be tracked by Git.
Using the command line
To create a local tracking branch and download the source code, open a terminal (command prompt) and switch there to the directory you want the source, then type:
</translate>
git clone https://github.com/FreeCAD/FreeCAD.git
<translate>
Compiler
The default (recommended) compiler is MS Visual Studio (MSVC). Though it may be possible to use other compilers, for example gcc via Cygwin or MinGW, it is not tested or covered here.
Note: Although the Community edition of MSVC is free, to use the IDE for more than a 30-day trial period you must create a Microsoft account. If you will only compile using the command line, you don't need the IDE and thus no Microsoft account.
As a free and OpenSource alternative IDE you can use KDevelop. You can use KDevelop to modify and write C++ code but must use the command line to compile.
Optional system path configuration
Optionally you can include the paths to some folders to the system PATH variable. This is helpful if you want to access programs in these folders from the command line/powershell or if you want special programs to be found by the compiler or CMake. Besides this, adding folders to the PATH might be necessary if you did not use the corresponding options when installing the program.
You can include the folder of your LibPack in your system PATH variable. This is useful if you plan to build multiple configurations/versions of FreeCAD.
If you did not use the option to add CMake to the PATH while installing it, add its installation folder
C:\Program Files\CMake\bin to the PATH.
If you did not use the option to add TortoiseGit to the PATH while installing it, add its installation folder
C:\Program Files\TortoiseGit\bin to the PATH.
To add folder paths to the PATH variable:
In the Windows Start menu Right click on Computer and choose Properties.
In the appearing dialog click on Advanced system settings.
Another dialog will open. Click there in the tab Advanced on Environment Variables.
Again another dialog will open. Select then the variable Path and click on Edit.
And again another dialog will open. Click there on New and add to path to the folder of Git or the LibPack.
Finally press OK and close all dialogs by pressing OK as well.
Configuration
Once you have all of the necessary tools, libraries, and FreeCAD source code, you are ready to begin the configuration and compilation process. This process will proceed in five steps:
Run CMake once to examine your system and begin the configuration progress (this will report that it failed).
Adjust necessary CMake settings to set the locations of the LibPack and enable Qt5.
Re-run CMake to finalize the configuration (this time it should succeed).
Use CMake to generate the Visual Studio build system.
Use Visual Studio to build FreeCAD.
CMake
First, configure the build environment using CMake:
Open the CMake GUI
Specify the source folder of FreeCAD.
Specify a build folder. This can be build in the folder you cloned the repo because this path is ignored by git. Do not use the source folder. CMake will create this folder if it does not exist.
Click Configure.
In the dialog that appears specify the generator you want to use: in most cases you will use the defaults in this dialog. For the standard MS Visual Studio use Visual Studio xx 2yyy where xx is the compiler version and 2yyy the year of its release. It is recommended to use the default option Use default native compilers.
Note: It is important to specify the correct bit variant. If you have the 64-bit variant of the LibPack you must also use the x64 compiler.
This will begin the configuration and will fail because of missing settings. This is normal, you have not yet specified the location of the LibPack. However, there are other failures that might occur that require some further action on your part.
If it fails with the message that Visual Studio could not be found, the CMake support in MSVC is not yet installed. To do this:
Open the MSVC IDE
Use the menu Tools → Get Tools and Features
In the Workloads tab enable Desktop development with C++
On the right side you should now see that the component Visual C++ tools for CMake will be installed.
Install it.
If it fails with a message about the wrong Python version or missing Python, then:
Use the "Search:" box in CMake to search for the string "Python"
If you see there a path like C:/Program Files/Python38/python.exe, CMake recognized the Python that is already installed on your PC, but that version is not compatible with the LibPack. Since the LibPack includes a compatible version of Python, modify the following Python settings in CMake to its paths (assuming the LibPack is in the folder D:/FreeCAD-build/FreeCADLibs_2_8_x64_VC2019):
If there is no error about Visual Studio or Python, everything is fine, but CMake does not yet know all necessary settings. Therefore now:
Search in CMake for the variable FREECAD_LIBPACK_DIR and specify the location of the LibPack folder you downloaded earlier.
(If building FreeCAD 0.19) Search for the variable BUILD_QT5 and enable this option.
(If planning on running directly from the build folder such as for debugging) Search for and enable the following options:
FREECAD_COPY_DEPEND_DIRS_TO_BUILD
FREECAD_COPY_LIBPACK_BIN_TO_BUILD
FREECAD_COPY_PLUGINS_BIN_TO_BUILD
Click Configure again.
There should now be no errors. If you continue to encounter errors that you cannot diagnose, visit the Install/Compile forum on the FreeCAD forum website. If CMake proceeded correctly, click on Generate. After this is done you can close CMake and start the compilation of FreeCAD using Visual Studio. However, for the first compilation keep it open in case you want or need to change some options for the build process.
Options for the build process
The CMake build system gives you control over some aspects of the build process. In particular, you can switch on and off some features or modules using CMake variables.
Here is a description of some of these variables:
Variable name
Description
Default
BUILD_XXX
Build FreeCAD with the component XXX. If you don't want/need to compile e.g. the workbench OpenSCAD, disable the variable BUILD_OPENSCAD. FreeCAD will then not have this workbench.
Note: Some components are required for other components. If you for example uncheck BUILD_ROBOT CMake will inform you that then the component Path cannot be compiled correctly. Therefore check the CMake output after you changed a BUILD_XXX option!
depends
BUILD_ENABLE_CXX_STD
The version of the C++ language standard. C++14 is the highest possible for FreeCAD 0.19 while at least C++17 is required for FreeCAD 0.20. See also the note in the section Building with Visual Studio 15 (2017) and 16 (2019)
Copies depending libraries needed to execute the FreeCAD.exe to the build folder. See also the section Running and installing FreeCAD. Note: the options FREECAD_COPY_XXX only appear if the libraries were not already copied. If you only need to upgrade/change to another LibPack version, see the section Updating the LibPack. If you want to bring back the options for some reason, you need to delete all folders in your build folder, except for the LibPack folder. In CMake delete the cache and start as if you compile for the first time.
OFF
FREECAD_COPY_LIBPACK_BIN_TO_BUILD
Copies the LibPack binaries needed to execute the FreeCAD.exe to the build folder. See also the section Running and installing FreeCAD.
OFF
FREECAD_COPY_PLUGINS_BIN_TO_BUILD
Copies Qt's plugin files needed to execute the FreeCAD.exe to the build folder. See also the section Running and installing FreeCAD.
OFF
FREECAD_LIBPACK_USE
Switch the usage of the FreeCAD LibPack on or off
ON
FREECAD_LIBPACK_DIR
Directory where the LibPack is
FreeCAD's source code folder
FREECAD_RELEASE_PDB
Create debug libraries (*.pdb) also for release builds. It doesn't affect the speed (like a real debug build would do) and can be very useful to locate crashes in FreeCAD code. In case FreeCAD crashes a crash.dmp file will be created that can be loaded with MSVC and if you have the corresponding PDB files plus the source code of that version you can debug through the code. Without the PDB files it's not possible to debug the code and all what the debugger shows is the name of the DLL where the crash has occurred.
ON
FREECAD_USE_MP_COMPILE_FLAG
Adds the /MP (multiprocessor) option to the Visual Studio projects, enabling speedups on multi-core CPUs. This can greatly accelerate builds on modern processors. Note: If you turn off FREECAD_USE_PCH, the compilation can quickly overload your heap space, even if you have 16 GB RAM.
Includes the PyBind11 library. Necessary to have a build that includes the CreateFlatMesh feature. Note: after turning it on you might get a configuration error. Just configure again and the problem should go away.
OFF
Building FreeCAD
Depending on your compiler, the process for building FreeCAD will be slightly different. In the following sections known workflows are described. If you are building with Qt Creator, jump to Building with Qt Creator (outdated), otherwise proceed directly:
</translate>
<translate>
Building with Visual Studio 15 (2017) or newer
</translate>
<translate>
Release Build
Start the Visual Studio IDE. This can either be done by pressing the button Open Project in the CMake GUI or by double-clicking on the file FreeCAD.sln that you find in your build folder.
In the toolbar of the MSVC IDE assure that you use for the first compilation Release.
There is a window called Solution Explorer. It lists all possible compilation targets. To start a full compilation, right-click on the target ALL_BUILD and then choose Build.
If you don't get any errors you are done. Congratulations! You can exit MSVC or keep it open.
Important: Since Visual Studio 17.4 you cannot use the code optimization that is on by default for the target SketcherGui. If you do, angle constraints will be misplaced in sketches. To fix this, right-click on this target in the MSVC solution explorer and select the last entry Properties in the context menu. In the appearing dialog go to C/C++ → Optimization and there disable the setting Optimization. Finally build the target ALL_BUILD again.
Debug Build
For a debug build it is necessary that the Python is used that is included in the LibPack. To assure this:
Search in the CMake GUI for "Python"
If you see there a path like C:/Program Files/Python38/python.exe, CMake recognized the Python that is installed on your PC and not the one of the LibPack. In this case adapt these different Python settings in CMake to this (assuming the LibPack is in the folder D:\FreeCAD-build\FreeCADLibs_12.5.2_x64_VC17):
As prerequisite for the debug build, you need to do this:
Copy the content of the LibPack folder bind to the bin folder of the FreeCAD build folder (overwrite the existing files).
Copy the content of the LibPack folder libd to the lib folder of the FreeCAD build folder.
Now you can compile:
Start the Visual Studio IDE. This can either be done by pressing the button Open Project in the CMake GUI or by double-clicking on the file FreeCAD.sln that you find in your build folder.
In the toolbar of the MSVC IDE assure that you use for the first compilation Debug.
There is a window called Solution Explorer. It lists all possible compilation targets. To start a full compilation, right-click on the target ALL_BUILD and then choose Build in the context menu.
This will now take quite a long time.
If there were no compilation errors, and if the FREECAD_COPY_* options mentioned in the CMake Configuration step above were enabled, you can start the debug build:
Right-click on the target FreeCADMain and then choose Set as Startup Project in the context menu.
Finally click in the toolbar on the button with the green triangle named Local Windows Debugger.
This will start the debug build of FreeCAD and you can use the MSVC IDE to debug it.
Video Resource
An English language tutorial that begins with configuration in CMake Gui and continues to the `Build` command in Visual Studio 16 2019 is available unlisted on YouTube at Tutorial: Build FreeCAD from source on Windows 10.
</translate>
In Windows file explorer Shift+Right-click on your build folder and use from the context menu Command prompt here.
Execute the command
</translate>
compile-FC install
<translate>
Instead of calling compile-FC with the option install you can also use debug or release:
debug - compile FreeCAD in debug configuration
release - compile FreeCAD in release configuration
install - compile FreeCAD in release configuration and create an install setup
</translate>
<translate>
Running and installing FreeCAD
There are 2 methods to run the compiled FreeCAD:
Method 1: You execute the FreeCAD.exe that you find in your build folder in the subfolder bin
Method 2: You build the target INSTALL
Method 2 is the simpler one because it automatically assures that all libraries needed to run the FreeCAD.exe are in the correct folder. The FreeCAD.exe and the libraries will be output in the folder you specified in the CMake variable CMAKE_INSTALL_PREFIX.
For Method 1 you need to enable the FREECAD_COPY_* options mentioned in the CMake Configuration step above.
Troubleshooting
When running FreeCAD you may encounter missing DLLs when using certain workbenches or features of workbenches. The error message in FreeCAD's console will not tell you what DLL is missing. To find this out you must use an external tool:
Note: Instead of the ~ you must specify the full path to the DependenciesGui.exe on your system.
Now drag in the *.pyd file of the workbench with which you get missing DLLs reported.
Updating the build
FreeCAD is very actively developed. Therefore its source code changes almost daily. New features are added and bugs are fixed. To benefit from these source code changes, you must rebuild your FreeCAD. This is done in two steps:
Right-click on your FreeCAD source code folder in the Windows file explorer and select Pull in the context menu.
A dialog will appear. Select there what development branch you want to get. master is the main branch. Therefore use this unless you want to compile a special new feature from a branch that has not yet been merged to master. (For more about Git branches, see Git development process.)
Finally click OK.
Using the command line
Open a terminal (command prompt) and switch there to your source directory. Then type:
If a new major version of a third-party dependency like Open Cascade is released, or if a third-party dependency has important bug fixes, a new LibPack is released. You can find the latest version here.
To update your LibPack the following recipe is best practice:
Delete the bin folder in your build folder.
Switch to your local LibPack folder and delete everything there.
Extract the content of the new LibPack ZIP file into the existing, but now empty, local LibPack folder.
Open CMake and there press the button Configure and then the button Generate. This recreates the bin folder you just deleted and also copies the new LibPack files into it.
In CMake click the button Open Project and the MSVC IDE will open.
In the MSVC IDE build the target INSTALL.
Tools
In order to join the FreeCAD development you should compile and install the following tools:
Qt Designer plugin
FreeCAD uses Qt as toolkit for its user interface. All dialogs are setup in UI-files that can be edited using the program Qt Designer that is part of any Qt installation and also included in the LibPack. FreeCAD has its own set of Qt widgets to provide special features like adding a unit to input fields and to set preferences properties.
Compilation
The plugin cannot be loaded by the Qt Designer if it was compiled using another Qt version than the one your Qt Designer/Qt Creator is based on. Therefore the plugin must be compiled together with FreeCAD:
In the CMake options (see this section above) enable the option BUILD_DESIGNER_PLUGIN and reconfigure.
open MSVC and build the target FreeCAD_widgets
As result you will get the plugin file 'FreeCAD_widgets.dll in the folder ~\src\Tools\plugins\widget\Release
Installation
To install the plugin, copy the DLL either to:
If you use the LibPack: to the folder ~\FreeCADLibs_2_8_x64_VC2019\plugins\designer
If you have a full Qt installation: you can choose between the folder C:\Qt\5.15.2\msvc2019_64\plugins\designer or C:\Qt\5.15.2\msvc2019_64\bin\designer (you must first create the designer subfolder.) (adapt the paths to your installation!).
Finally (re)start Qt Designer and check its menu Help → Plugins. If the plugin FreeCAD_widgets.dll is listed as being loaded, you can now design and change FreeCAD's .ui files. If not, you must compile the DLL by yourself.
If you prefer using Qt Creator instead of Qt Designer, the plugin file must be placed in this folder: C:\Qt\Qt5.15.2\Tools\QtCreator\bin\plugins\designer Then (re)start Qt Creator, switch to the mode Design and then check the menu Tools → Form Editor → About Qt Designer Plugins. If the plugin FreeCAD_widgets.dll is listed as being loaded, you can now design and change FreeCAD's .ui files. If not, you must compile the DLL by yourself.
Thumbnail Provider
FreeCAD has the feature to provide preview thumbnails for *.FCStd files. That means that in the Windows file explorer *.FCStd files are shown with a screenshot of the model it contains. To provide this feature, FreeCAD needs to have the file FCStdThumbnail.dll installed to Windows.
Open a Windows command prompt with administrator privileges (these privileges are a requirement).
Change to the folder where the DLL is.
Execute this command
regsvr32 FCStdThumbnail.dll
So check if it works, assure that in FreeCAD the preferences option Save thumbnail into project file when saving document is enabled and save a model. Then view in Windows Explorer the folder of the saved model using a symbol view. You should now see a screenshot of the model in the folder view.
Compilation
To compile the FCStdThumbnail.dll
Change to the FreeCAD source folder ~\src\Tools\thumbs\ThumbnailProvider
Open the CMake GUI
Specify there as source folder the one you are currently in.
Use the same folder as build folder.
Click Configure
In the appearing dialog, specify the generator according to the one you want to use. For the standard MS Visual Studio use Visual Studio xx 2yyy where xx is the compiler version and 2yyy the year of its release. It is recommended to use the default option Use default native compilers. Note: It is important to specify the correct bit variant. If you have the 64bit variant of LibPack you must also use the x64 compiler.
Click on Generate.
You should now have the file ALL_BUILD.vcxproj in the folder ~\src\Tools\thumbs\ThumbnailProvider. Double-click on it and the MSVC IDE will open.
In the toolbar of the MSVC IDE assure that you use the compilation target Release.
There is a window called Solution Explorer. Right-click there on ALL_BUILD and then choose Build.
As result you should now have a FCStdThumbnail.dll in the folder ~\src\Tools\thumbs\ThumbnailProvider\release that you can install as described above.
Compiling Open Cascade
The LibPack comes with a version of Open Cascade that is suitable for general use. However, under some circumstances you may wish to compile against an alternate version of Open Cascade, such as one of their official releases, or a patched fork.
When compiling Open Cascade for FreeCAD note that there is no guarantee that FreeCAD will work with all versions of Open Cascade. Note also that when you are using the Netgen library, you must use the a NetGen version that it approved to compile with the Open Cascade version you like to compile.
Then open the CMake GUI to configure the build system in a similar manner to building FreeCAD. These CMake options have to be set (or explicitly not set):
Variable name
Description
Default
3RDPARTY_DIR
The path to 3rdparty components. It is recommended to use the folder as input where your used LibPack is. Explicitly leave this field empty.
empty
3RDPARTY_DOXYGEN_EXECUTABLE
The path to the executable of the 3rdparty component Doxygen. It is recommended to install Doxygen. CMake will then find it automatically.
empty
3RDPARTY_FREETYPE_DIR
The path to the necessary 3rdparty component Freetype. It is recommended to use the folder as input where your used LibPack is.
empty
3RDPARTY_RAPIDJSON_DIR
Only available if USE_RAPIDJSON is used. The path to the 3rdparty component RapidJSON. It is recommended NOT to use an existing LibPack folder as input. You can use the RapidJSOn folder from a LibPack, but copy it to a new folder and use this new folder as input.
empty
3RDPARTY_TCL_DIR
The path to the necessary 3rdparty component TCL. It is recommended NOT to use an existing LibPack folder as input. Take for example one of these releases, extract it and take this as input folder for CMake.
empty
3RDPARTY_TK_DIR
The path to the necessary 3rdparty component TK. It is recommended NOT to use an existing LibPack folder as input. Take for example one of these releases, extract it and take this as input folder for CMake.
empty
3RDPARTY_VTK_DIR
Only available if USE_VTK is used. The path to the necessary 3rdparty component VTK. It is recommended to use the folder as input where your used LibPack is. If you use another folder please assure that you don't use VTK 9.x or newer.
empty
BUILD_RELEASE_DISABLE_EXCEPTIONS
Disables exception handling for release builds. For FreeCAD you must set it to OFF.
ON
INSTALL_DIR
The output folder when building the target INSTALL. If the build was successful, take the files from this folder to update your LibPack.
Windows default program installation folder
INSTALL_DIR_BIN
The output subfolder for the DLL when building the target INSTALL. You must change it to bin
win64/vc14/bin
INSTALL_DIR_LIB
The output subfolder for the .lib files when building the target INSTALL. You must change it to lib
win64/vc14/lib
USE_RAPIDJSON
To compile Open Cascade with support for RapidJSON. Enabling this is mandatory in order to get support for the file format glTF.
OFF
USE_VTK
To compile Open Cascade with support for VTK. Enabling this is optimal. You can use this to build Open Cascade's VTK bridge.
OFF
Open the project in Visual Studio and first build the ALL_BUILD and then INSTALL targets in the Release mode.
Repeat building the two targets in the Debug mode.
To build FreeCAD using the self-compiled Open Cascade, you must do the following:
Copy all folders from the INSTALL_DIR to your LibPack folder (overwrite the existing files)
Switch to the LibPack folder and go there to the subfolder cmake
Open there the file OpenCASCADEDrawTargets.cmake with a text editor
Search there for absolute paths to your LibPack folder and remove them. So e.g. the absolute path D:/FreeCADLibs_12.5.4_x64_VC17/lib/freetype.lib becomes just freetype.lib
Do the same for the file OpenCASCADEVisualizationTargets.cmake
Compiling Netgen
The LibPack comes with a version of Netgen that will was tested to be build with the Open Cascade version of the LibPack. The problem is that every new release of Netgen changes the API. Also every new release of Open Cascade does the same. Therefore one cannot just easily change the Netgen version.
However, you might build Netgen nevertheless. This is an easy task:
Then open the CMake GUI to configure the build system in a similar manner to building FreeCAD. These CMake options have to be set:
Variable name
Description
Default
CMAKE_INSTALL_PREFIX
The output folder when building the target INSTALL. If the build was successful, take the files from this folder to update your LibPack.
C:/netgen
OpenCasCade_DIR
The path to the CMake files of Open Cascade. If you built Open Cascade as described in the section Compiling Open Cascade you can use the subfolder cmake of there folder you used as INSTALL_DIR. If not, use the subfolder cmake of your LibPack. Note hereby that the LibPack must then already contain a proper Open Cascade build. Independent what folder you use, you must now also create there a subfolder lib and copy in the files freetype.lib and freetyped.lib from your LibPack.
empty
USE_GUI
set it to OFF
ON
USE_NATIVE_ARCH
set it to OFF; this is only necessary important to support older CPU that don't have the AVX2 instruction set
ON
USE_OCC
set it to ON
OFF
USE_PYTHON
set it to OFF
ON
USE_SUPERBUILD
set it to OFF
ON
ZLIB_INCLUDE_DIR
The path to the necessary 3rdparty component zlib. It is recommended to use the folder as input where your used LibPack is.
empty
ZLIB_LIBRARY_DEBUG
The path to the ZLib file zlibd.lib. It is located in the subfolder lib of your LibPack folder.
empty
ZLIB_LIBRARY_RELEASE
The path to the ZLib file zlib.lib. It is located in the subfolder lib of your LibPack folder.
empty
Additionally you need to add a new CMake entry:
name: CMAKE_DEBUG_POSTFIX, type: string, content: _d
This assures that he file names of the debug libraries get another name than the release libraries and can later not be accidentally exchanged.
Press the Configure button in CMake to generate the *.cmake files.
Only necessary if older CPU should be supported that don't have the AVX2 instruction set:
Search your Netgen build folder for the file netgen-targets.cmake and open it with a text editor. Remove the setting ;/arch:AVX2 in the Option INTERFACE_COMPILE_OPTIONS.
Press the Configure button in CMake again.
Press the Generate button in CMake.
Open the project in Visual Studio and first build the ALL_BUILD and then INSTALL targets in the Release mode.
Repeat building the two targets in the Debug mode.
To build FreeCAD using the self-compiled Netgen, you must do the following:
Copy all folders from the CMAKE_INSTALL_PREFIX to your LibPack folder (overwrite the existing files)
These are libraries which FreeCAD uses as third party dependencies during compilation. They are usually dynamically linked libraries and have an extension .so in Linux/MacOS and .dll in Windows, and are accompanied by their header files .h or .hpp or similar. If a modified library is necessary, or a wrapper class is needed, the code of the modified library, or the wrapper, has to become part of the FreeCAD source code, and compiled together with it.
Python 2 became obsolete in 2019. Further development of FreeCAD will use exclusively Python 3; compatibility with Python 2 won't be tested, so old workbenches and macros that use this version will have to be updated or they may stop working. Please post on the FreeCAD forum if you encounter problems with Python 3.
Python is a popular all-purpose scripting language that is widely used in Linux and open source software. In FreeCAD, Python is used during compilation and also at runtime in different ways. It is used
to write test scripts to test for different conditions, such as memory leaks, to ensure functionality of the software after changes, for post build checks, and test coverage tests,
to implement application logic for standard packages,
to implement auxiliary tools such as the Addon Manager,
to implement entire workbenches like Draft and Arch,
to dynamically load packages,
to implement rules for design (knowledge engineering),
to do fancy Internet interactions like work groups and PDM
On Linux, Python is usually already installed in your distribution. For Windows you can get a precompiled binary from Python.org or use ActiveState Python, though it is harder to get the debug libraries from the latter one.
Python was chosen as the scripting language for FreeCAD for different reasons:
It is more object oriented than Perl and Tcl.
The code is more readable than Perl and Visual Basic.
It is easier to embed in another application, unlike, say, Java.
In summary, Python is well documented, and it's easy to embed and extend in a C++ application. It is also well tested and has strong support from the open source community. Read more about Python and browse the official documentation at Python.org.
Boost
Version: 1.33 or higher
License: Boost Software License - Version 1.0
The Boost C++ libraries are collections of peer-reviewed, open source libraries that extend the functionality of C++. They are intended to be widely useful across a broad spectrum of applications, and to work well with the C++ Standard Library. The Boost license is designed to encourage their use in both open source and closed source projects.
Due to their popularity and stability, many Boost libraries have been accepted for incorporation into the C++11 standard, and more are planned for inclusion in subsequent C++ standards.
In order to ensure efficiency and flexibility, Boost makes extensive use of templates. Boost has been a source of extensive work and research into generic programming and meta-programming in C++. Read more about Boost by visiting the Boost homepage.
OpenCASCADE Technology (OCCT) is a full-featured, professional grade CAD kernel. It was developed in 1993 and originally called CAS.CADE, by Matra Datavision in France for the Strim (Styler) and Euclid Quantum applications. In 1999 it was released as open source software, and since then it's been called OpenCASCADE.
OCCT is a big and complex set of C++ libraries that provide functionality required by a CAD application:
A complete STEP compliant geometry kernel.
A topological data model and needed functions to work with shapes (cut, fuse, extrude, and many others).
Standard import and export processors for files like STEP, IGES, VRML.
A 2D and 3D viewer with selection support.
A document and project data structure with support for save and restore, external linking of documents, recalculation of design history (parametric modeling) and a facility to load new data types as an extension package dynamically.
There are two main versions of OpenCASCADE in existence in different Linux distributions. One is distributed by the original developers; it is known as OCCT, and is packaged under the names occ or occt. The other version is the "community edition", abbreviated OCE, and is normally found with the oce name. FreeCAD can compile against either version, however, since 2016 FreeCAD recommends compiling against the official OCCT libraries rather than the OCE ones. The reason is that the community edition lacks important bug fixes and functions that make using FreeCAD better.
License: GPL v2.0/v3.0 or Commercial; from version 4.5 on also LPGL v2.1.
Qt is one of the most popular graphical user interface (GUI) toolkits available in the open source world. FreeCAD uses this toolkit to draw the interface of the program. For this, the Qt Designer application is very useful as it allows developers to quickly draw the dialogs and windows, export them as XML resource files, and then load these interfaces at runtime.
Further information about Qt libraries and their programming documentation are available at Qt Documentation.
Shiboken2 and Pyside2
Shiboken is the Python binding generator that Qt for Python uses to create the PySide module, in other words, it is the system that is used to expose the Qt C++ API to the Python language.
The original Shiboken and PySide packages were meant to be used with Python 2 and Qt4; since these two versions are considered obsolete in 2019, please use Shiboken2 and PySide2, which work with Python 3 and Qt5. New development of FreeCAD is done with Python 3 and Qt5, so compatibility with Python 2 and Qt4 is not guaranteed after FreeCAD 0.18.
Read more about Shiboken and Pyside on Qt for Python.
Coin3D
Version: 3.0 or higher
License: BSD 3-clause license
Coin3D is a high-level 3D graphics library with a C++ application programming interface. It uses scenegraph data structures to render real-time graphics suitable for all kinds of scientific and engineering visualization applications.
Coin3D is built on the industry-standard OpenGL immediate mode rendering library, and adds abstractions for higher-level primitives, provides 3D interactivity, and contains many complex optimization features for fast rendering that are transparent for the application programmer.
Coin3D is compatible with SGI's Open Inventor 2.1 API. This API has become the de facto standard graphics interface for 3D visualization in the scientific and engineering community. It has proved its worth since the year 2000 as a major building block in thousands of engineering applications around the world.
Coin3D (Open Inventor) is used as the 3D viewer in FreeCAD because the OpenCASCADE viewer (AIS and Graphics3D) has limitations and performance bottlenecks, especially with large-scale engineering rendering; other things like textures or volumetric rendering are not entirely supported by the OpenCASCADE viewer.
Coin3D is portable over a wide range of platforms: UNIX, Linux, BSD, macOS, and Microsoft Windows operating systems. To read more about this library visit Coin3D homepage.
SoQt (deprecated)
Version: 1.2.0 or higher
License: BSD 3-clause license
SoQt is the Coin3D (Open Inventor) binding to the Qt GUI toolkit.
SoQt is no longer used in FreeCAD, it was replaced by Quarter which is a more recent Qt binding.
Quarter
Version: 1.0 or higher
License: BSD 3-clause license
Quarter is a newer Coin3D binding to the Qt toolkit. A version of it is included in the source code of FreeCAD so it is compiled together with it.
Pivy
Version: 0.6.3 or higher
License: BSD 3-clause license
Pivy is a library that wraps the Coin3d library for use in Python. It is not needed to build FreeCAD or to start it, but it is needed as a runtime dependency by the Draft Workbench, and by other workbenches that use it internally, like Arch and BIM.
If you are not going to use these workbenches, you won't need Pivy.
Ply
Version: 3.11 or higher
License: BSD 3-clause license
Ply is the Python-Lex-Yacc parser. It is used as a runtime dependency by the OpenSCAD Workbench. If you don't use this workbench, you may not need this package.
Xerces-C++ is a validating XML parser written in a portable subset of C++. Xerces-C++ makes it easy to give your application the ability to read and write XML data. A shared library is provided for parsing, generating, manipulating, and validating XML documents. Xerces-C++ is faithful to the XML 1.0 recommendation and associated standards.
The parser is used for saving and restoring parameters in FreeCAD. For more information see Xerces-C++ homepage.
Eigen is a C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms.
If you just want to use Eigen, you can use the header files right away. There is no binary library to link to, and no configured header file. Eigen is a pure template library defined in the headers.
Eigen is used in FreeCAD for many vector operations in 3D space. To learn more, visit Eigen homepage.
Zipios++
Version: 0.1.5 or higher
License: GNU Lesser General Public License 2.1
Zipios++ is a C++ library for reading and writing .zip files. Access to individual entries is provided through standard C++ iostreams. A simple read-only virtual file system that mounts regular directories and .zip files is also provided. The structure and public interface of Zipios++ are loosely based on the java.util.zip package of Java.
FreeCAD's native file format .FCstd is in reality a .zip file that stores and compresses other types of data within it, such as BREP and XML files. Therefore, Zipios++ is used to save and open compressed archives, including FreeCAD files.
A copy of Zipios++ is included in the source code of FreeCAD so it is compiled together with it. If you want to use an external Zipios++ library, provided by your operating system, you may set -DFREECAD_USE_EXTERNAL_ZIPIOS=ON with cmake.
Zipios++ uses the Zlib library to perform the actual decompression of files.
Zlib
Version: 1.0 or higher
License: zlib license
Zlib is designed to be a free, general-purpose, lossless data-compression library for use on any computer hardware and operating system. It implements the DEFLATE compression algorithm commonly used in .zip and .gzip files.
A copy of this library is included in the source code of FreeCAD so it is compiled together with it.
libarea
Version: 0.0.20140514-1 or higher
License: BSD 3-clause license
Libarea is a software library to compute profile and pocket operations which are used in computer aided manufacturing (CAM) software. It was created by Dan Heeks for his HeeksCNC project.
A copy of the library is included with the source code of the Path Workbench, so it is compiled together with it.
LibPack
LibPack is a convenient package with FreeCAD's build dependencies collected together. It is only needed if you are compiling FreeCAD on Windows with Visual Studio 2015 and above. You can find the latest LibPack on the releases page.
If you're working under Linux, you don't need the LibPack, as you can get the dependencies from your distribution's repositories as mentioned in the compile on Linux page.
For every serious software development you need tools. Here is a list of tools we use to develop FreeCAD:
Platform independent tools
Qt-Toolkit
The Qt-toolkit is a state of the art, platform independent user interface design tool. It is contained in the LibPack of FreeCAD, but can also be downloaded at Qt project.
Inkscape
This is a great vector drawing program. It adheres to the SVG standard and is used to draw Icons and Pictures. Inkscape is Free and Open Source Software licensed under the GPL. Get it at www.inkscape.org.
Doxygen
A very good and stable tool to generate source documentation from the .h and .cpp files.
Gimp
Not much to say about the GNU Image Manipulation Program. It can manipulate .xpm files which is a very convenient way to handle Icons in QT programs. XPM is basically C-Code which can be compiled into a program. Gimp supports the free .png file format used in the wiki.
This is a proprietary git GUI that is very helpful to learn how git works if you're interested in wanting to contribute to FreeCAD. Relevant pages to research:
Free and open source software for video recording and live streaming. More details on official website: obsproject.com
OpenCamLib
OpenCamLib (OCL) is an open source library aiming to provide computer aided manufacturing (CAM) algorithms. FreeCAD uses OCL in the experimental 3D surface path operations and other experimental features.
StarUML
A full featured but proprietary UML program. It has a lot of major features, including reverse engineering C++ source code.
Visual Studio Community is free for open source projects and small structures. Installation is modular. You can add support for a large number of languages including C++ and Python.
Is an Open Source tool to record Screen-casts (Webcasts). It is a very good tool to create tutorials by recording them. Its far not so boring as writing documentation.
In FreeCAD version 0.20 the default location of the program's configuration, data and cache files was changed for Linux.
See Release notes 0.20 for more information. This page has not yet been updated accordingly.
</translate>
<translate>
Overview
This page shows the different ways to start FreeCAD and the most important configuration features.
Starting FreeCAD from the Command line
FreeCAD can be started normally by double-clicking on its desktop icon or selecting it from the start menu, but it can also be started directly from the command line. This allows you to change some of the default startup options.
Using command line options without a command line shell
On Ubuntu you can create a desktop icon and edit its properties. Add the command line options separated by spaces behind the program name in the "Command" field.
On Windows create a shortcut and edit the properties. Add the command line options separated by spaces to "Target" field.
Command line options
The command line options are subject to frequent changes.Therefore, it is a good idea to check the current options by typing:
</translate>
FreeCAD --help
<translate>
From the response you can read the possible parameters:
</translate>
Usage: FreeCAD [options] File1 File2 ...
Allowed options:
Generic options:
-v [ --version ] Prints version string
-h [ --help ] Prints help message
-c [ --console ] Starts in console mode
--response-file arg Can be specified with '@name', too
--dump-config Dumps configuration
--get-config arg Prints the value of the requested configuration key
Configuration:
-l [ --write-log ] Writes a log file to:
/home/username/.FreeCAD/FreeCAD.log
--log-file arg Unlike --write-log this allows logging to an
arbitrary file
-u [ --user-cfg ] arg User config file to load/save user settings
-s [ --system-cfg ] arg System config file to load/save system settings
-t [ --run-test ] arg Test case - or 0 for all
-M [ --module-path ] arg Additional module paths
-P [ --python-path ] arg Additional python paths
--single-instance Allow to run a single instance of the application
<translate>
In the following table, selected options are described in more detail:
Filename or relative path that ends with a filename. Defaults to user.cfg.
--module-path <dir>
Prepends to AdditionalModulePaths
Directory that contains modules. This option can be given repeatedly to specify multiple directories.
--get-config <config-var-name>
most
Outputs the requested value in a popup dialog. Exits upon confirmation with OK. Cannot be used repeatedly. If an unknown/illegal variable name is used, the response is empty. The --console flag is not honored.
Options can written in two forms: --long-option arg and --long-option=arg.
Response and config files
FreeCAD can read some of these options from a config file. This file must be in the bin path and must be named FreeCAD.cfg. Be aware that options specified in the command line override the config file!
Some operating systems have a very low limit of characters on the command line. The common way to work around those limitations is using response files. A response file is just a configuration file which uses the same syntax as the command line. If the command line specifies a response file, it's loaded and parsed in addition to the command line:
</translate>
FreeCAD @ResponseFile.txt
<translate>
or:
</translate>
FreeCAD --response-file=ResponseFile.txt
<translate>
or:
</translate>
FreeCAD --response-file ResponseFile.txt
<translate>
Hidden options
There are a couple of options not visible to the user. These options are e.g. the X-Window parameters parsed by the Windows system:
-display - Sets the X display (default is $DISPLAY).
-geometry - Sets the client geometry of the first window that is shown.
-fn or -font - Defines the application font. The font should be specified using an X logical font description.
-bg or -background - Sets the default background color and an application palette (light and dark shades are calculated).
-fg or -foreground - Sets the default foreground color.
-btn or -button - Sets the default button color.
-name - Sets the application name.
-title - Sets the application title.
-visual - Forces the application to use a TrueColor visual on an 8-bit display.
-ncols - Limits the number of colors allocated in the color cube on an 8-bit display, if the application is using the QApplication::ManyColor color specification. If count is 216 then a 6x6x6 color cube is used (i.e. 6 levels of red, 6 of green, and 6 of blue); for other values, a cube approximately proportional to a 2x3x1 cube is used.
-cmap - Causes the application to install a private color map on an 8-bit display.
Running FreeCAD without GUI (headless)
FreeCAD is usually built with two executables: a GUI-capable one called FreeCAD or freecad, and a headless one, called FreeCADCmd or freecadcmd.
FreeCAD can be used in console mode using the --console switch (which is the default behavior of FreeCADCmd):
</translate>
FreeCAD --console
<translate>
In console mode, no graphical user interface will be displayed, and you will be presented with a Python interpreter prompt: >>>. From that prompt, you have the same functionality as the Python interpreter that runs inside the FreeCAD GUI, and access to all modules and plugins of FreeCAD, except the FreeCADGui module. Be aware that modules that depend on FreeCADGui might also be unavailable.
To read more about console or headless mode, refer to Headless FreeCAD.
FreeCAD's "base" directory for keeping local user data.
FREECAD_USER_DATA
UserAppData
If not set, defaults to FREECAD_USER_HOME/.FreeCAD, but only if FREECAD_USER_HOME is set.
FREECAD_USER_TEMP
AppTempPath
If not set, defaults to FREECAD_USER_HOME/temp, but only if FREECAD_USER_HOME is set.
If the specified path does not exist, the setting is ignored!
The above environment variables are meant to be used to realize a portable FreeCAD environment. For an example how environment variables can be used from the command line on Linux refer to the notes for Linux users on the downloads page.
HOME
FreeCAD uses Qt, which does honor the HOME environmental variable. Thus, setting HOME can be used to specify the base directory of Qt-related configuration files (.config/FreeCAD/FreeCAD.conf).
FreeCad itself does not honor the HOME environmental variable (because it determines the user's home directory from a lower-level system API). Use FREECAD_USER_HOME for this pupose.
TMPDIR
The default temporary directory is /tmp/. The TMPDIR environmental variable can be used to override the default. (Editor: precedence?).
Libraries
Some libraries need to call system environment variables. Sometimes when there is a problem with a FreeCAD installation, it is because some environment variable is absent or incorrect. Therefore, some important variables get duplicated in the Config and saved in the log file.
Python
</translate>
PYTHONPATH
PYTHONHOME
TCL_LIBRARY
TCLLIBPATH
<translate>
OpenCascade
</translate>
CSF_MDTVFontDirectory
CSF_MDTVTexturesDirectory
CSF_UnitsDefinition
CSF_UnitsLexicon
CSF_StandardDefaults
CSF_PluginDefaults
CSF_LANGUAGE
CSF_SHMessage
CSF_XCAFDefaults
CSF_GraphicShr
CSF_IGESDefaults
CSF_STEPDefaults
<translate>
Configuration set
On every startup FreeCAD examines its surrounding and the command line parameters. It builds up a configuration set which holds the essence of the runtime information. This information is later used to determine the place where to save user data or log files. It is also very important for postmortem analyzes. Therefore it is saved in the log file.
User related information
Config var name
Synopsis
Example Windows
Example Linux
UserAppData
Path where FreeCAD stores User Related application data.
C:\Documents and Settings\username\AppData\FreeCADShort path : %APPDATA%\FreeCAD
/home/username/.FreeCADShort path : ~/.FreeCAD
UserParameter
File where FreeCAD stores User Related application data.
C:\Documents and Settings\username\AppData\FreeCAD\user.cfgShort path : %APPDATA%\FreeCAD\user.cfg
/home/username/.config/FreeCAD/user.cfgShort path : ~/.config/FreeCAD/user.cfg or $HOME/.config/FreeCAD/user.cfg
SystemParameter
File where FreeCAD stores Application Related data.
C:\Documents and Settings\username\AppData\FreeCAD\system.cfgShort path : %APPDATA%\FreeCAD\system.cfg
/home/username/.config/FreeCAD/system.cfgShort path : ~/.FreeCAD/system.cfg or $HOME/.FreeCAD/system.cfg
UserHomePath
Home path of the current user
C:\Documents and Settings\usernameShort path : %USERPROFILE%
/home/usernameShort path : ~
Note: For Linux distributions, an additional configuration file that relates to Qt may exist at path /home/username/.config/FreeCAD/FreeCAD.conf.
Command line arguments
Config var name
Synopsis
Example
LoggingFile
1 if the logging is switched on
1
LoggingFileName
File name where the log is placed
C:\Documents and Settings\username\AppData\FreeCAD\FreeCAD.log
RunMode
This indicates how the main loop will work. "Script" means that the given script is called and then exit. "Cmd" runs the command line interpreter. "Internal" runs an internal script. "Gui" enters the Gui event loop. "Module" loads a given python module.
"Cmd"
FileName
Meaning depends on the RunMode
ScriptFileName
Meaning depends on the RunMode
Verbose
Verbosity level of FreeCAD
"" or "strict"
OpenFileCount
Holds the number of files opened through command line arguments
"12"
AdditionalModulePaths
Holds the additional Module paths given in the cmd line
"extraModules/"
System related
Config var name
Synopsis
Example Windows
Example Linux
AppHomePath
Path where FreeCAD is installed
c:/Progam Files/FreeCAD_0.19
/user/local/FreeCAD_0.19
PythonSearchPath
Holds a list of paths which python search modules. This is at startup can change during execution
AppTempPath
Path of the temporary directory. Can be given with TMPDIR environment variable, or with the Parameter Editor: Tools → Edit parameters... → BaseApp → Preferences → General → TempPath
/tmp/ (default)
Build related information
The table below shows the available information about the Build version. Most of it comes from the Subversion repository. This stuff is needed to exactly rebuild a version!
Config var name
Synopsis
Example
BuildVersionMajor
Major Version number of the Build. Defined in src/Build/Version.h.in
0
BuildVersionMinor
Minor Version number of the Build. Defined in src/Build/Version.h.in
7
BuildRevision
SVN Repository Revision number of the src in the Build. Generated by SVN
The following assumes that your desktop is configured such that you can launch FreeCAD from it. Depending on your Linux distribution and desktop environment, you may have to adapt the following steps:
Copy the freedesktop entry file for FreeCAD from /usr/share/applications/freecad.desktop to ~/.local/share/applications.
Change the name from freecad.desktop to something else (e.g. MyFreeCADConfig.desktop).
Open the file with a text editor and change how FreeCAD is invoked by modifying the line starting with Exec.
As a result, an additional entry in your start menu/application launcher is available. This way, you can have multiple FreeCAD entries with various launch options.
Starting FreeCAD from a portable USB medium
Windows
Put the FreeCAD executable, FreeCAD.exe, on the USB medium. Create a batch file, FreeCAD.bat, and put it into the same directory as FreeCAD.exe. Inside the batch file write:
</translate>
set CURRENTDIR=%cd%
set FREECAD_USER_HOME=%CURRENTDIR%
start FreeCAD.exe -u FreeCAD/user.cfg -s FreeCAD/system.cfg --write-log
set CURRENTDIR="%cd%"
set FREECAD_USER_DATA=%CURRENTDIR%/..
start FreeCAD.exe -u %FREECAD_USER_DATA%/user.cfg -s %FREECAD_USER_DATA%/system.cfg
<translate>
With the batch in the root of the USB medium:
</translate>
set CURRENTDIR=%cd%
set FREECAD_USER_DATA=%CURRENTDIR%FreeCAD\
start %cd%FreeCAD\bin\FreeCAD.exe -u %FREECAD_USER_DATA%user.cfg -s %FREECAD_USER_DATA%system.cfg
<translate>
Now double-click the batch file to start FreeCAD. (see)
The FreeCAD build tool or fcbt is a python script located at
</translate>
trunc/src/Tools/fcbt.py
<translate>
It can be used to simplify some frequent tasks in building, distributing and extending FreeCAD.
Usage
With Python correctly installed, fcbt can be invoked by the command
</translate>
python fbct.py
<translate>
It displays a menu, where you can select the task you want to use it for:
</translate>
FreeCAD Build Tool
Usage:
fcbt <command name> [command parameter]
possible commands are:
- DistSrc (DS) Build a source Distr. of the current source tree
- DistBin (DB) Build a binary Distr. of the current source tree
- DistSetup (DI) Build a Setup Distr. of the current source tree
- DistSetup (DUI) Build a User Setup Distr. of the current source tree
- DistAll (DA) Run all three above modules
- NextBuildNumber (NBN) Increase the Build Number of this Version
- CreateModule (CM) Insert a new FreeCAD Module (Workbench) in the module directory
For help on the modules type:
fcbt <command name> ?
<translate>
At the input prompt enter the abbreviated command you want to call. For example type "CM" for creating a module.
DistSrc
The command "DS" creates a source distribution of the current source tree.
DistBin
The command "DB" creates a binary distribution of the current source tree.
DistSetup
The command "DI" creates a setup distribution of the current source tree.
DistSetup
The command "DUI" creates a user setup distribution of the current source tree.
DistAll
The command "DA" executes "DS", "DB" and "DI" in sequence.
NextBuildNumber
The "NBN" command increments the build number to create a new release version of FreeCAD.
This page will show you how to add a new workbench to the FreeCAD interface. Workbenches are containers for FreeCAD commands. They can be coded in Python, in C++, or in a mix of both, which has the advantage to ally the speed of C++ to the flexibility of Python. In all cases, though, your workbench will be launched by a set of two Python files. They can be "internal" workbenches, included with FreeCAD's distribution, or "external" workbenches, distributed via the Addon Manager or installed manually by downloading from some online repository. Internal workbenches may be coded in either C++, Python, or a combination of the two, whereas external workbenches must be Python-only.
The workbench structure
You need a folder, with any name you like, placed in the user Mod directory, with an Init.py file, and, optionally an InitGui.py file. The Init file is executed when FreeCAD starts, and the InitGui.py file is executed immediately after, but only when FreeCAD starts in GUI mode. That's all it needs for FreeCAD to find your workbench at startup and add it to its interface.
The user Mod directory is a sub-directory of the user application data directory (you can find the latter by typing App.getUserAppDataDir() in the Python console):
On Linux it is usually /home/<username>/.local/share/FreeCAD/Mod/ (version 0.20 and above) or /home/<username>/.FreeCAD/Mod/ (version 0.19 and below).
On Windows it is %APPDATA%\FreeCAD\Mod\, which is usually C:\Users\<username>\Appdata\Roaming\FreeCAD\Mod\.
On macOS it is usually /Users/<username>/Library/Application Support/FreeCAD/Mod/.
The Mod directory should look like this:
</translate>
/Mod/
+-- MyWorkbench/
+-- Init.py
+-- InitGui.py
<translate>
Inside those files you can do whatever you want. Usually they are used like this:
In the Init.py file you just add a couple of things used even when FreeCAD works in console mode, for example the file importers and exporters
In the InitGui.py file you usually define a workbench, which contains a name, an icon, and a series of FreeCAD commands (see below). That python file also defines functions that are executed when FreeCAD loads (you try to do as little as possible there, so you don't slow down the startup), another that gets executed when the workbench is activated (that's where you'll do most of the work), and a third one when the workbench is deactivated (so you can remove things if needed).
The structure and file content for a workbench described here is the classic way of creating a new workbench. One can use a slight variation in the structure of files when making a new Python workbench, that alternative way is best described as a "namespaced workbench", opening up the possibility to use pip to install the workbench. Both structures work, so it is more a question of preference when creating a new workbench. The style and structure for workbenches presented here are available in the global namespace of FreeCAD, whereas for the alternative style and structure the workbench resides in a dedicated namespace. For further readings on the topic see Related.
C++ workbench structure
If you are going to code your workbench in python, you don't need to take special care, and can simply place your other python files together with your Init.py and InitGui.py files. When working with C++, however, you should take greater care, and start with respecting one fundamental rule of FreeCAD: The separation of your workbench between an App part (that can run in console mode, without any GUI element), and a Gui part, which will only be loaded when FreeCAD runs with its full GUI environment. So when developing a C++ workbench, you will actually most likely create two modules, an App and a Gui. These two modules must of course be callable from python. Any FreeCAD module (App or Gui) consists, at the very least, of a module init file. This is a typical AppMyModuleGui.cpp file:
</translate>
extern "C" {
void MyModuleGuiExport initMyModuleGui()
{
if (!Gui::Application::Instance) {
PyErr_SetString(PyExc_ImportError, "Cannot load Gui module in console application.");
return;
}
try {
// import other modules this one depends on
Base::Interpreter().runString("import PartGui");
// run some python code in the console
Base::Interpreter().runString("print('welcome to my module!')");
}
catch(const Base::Exception& e) {
PyErr_SetString(PyExc_ImportError, e.what());
return;
}
(void) Py_InitModule("MyModuleGui", MyModuleGui_Import_methods); /* mod name, table ptr */
Base::Console().Log("Loading GUI of MyModule... done\n");
// initializes the FreeCAD commands (in another cpp file)
CreateMyModuleCommands();
// initializes workbench and object definitions
MyModuleGui::Workbench::init();
MyModuleGui::ViewProviderSomeCustomObject::init();
// add resources and reloads the translators
loadMyModuleResource();
}
}
<translate>
The Init.py file
</translate>
"""FreeCAD init script of XXX module"""
# ***************************************************************************
# * Copyright (c) 2015 John Doe john@doe.com *
# * *
# * This file is part of the FreeCAD CAx development system. *
# * *
# * This program is free software; you can redistribute it and/or modify *
# * it under the terms of the GNU Lesser General Public License (LGPL) *
# * as published by the Free Software Foundation; either version 2 of *
# * the License, or (at your option) any later version. *
# * for detail see the LICENSE text file. *
# * *
# * FreeCAD is distributed in the hope that it will be useful, *
# * but WITHOUT ANY WARRANTY; without even the implied warranty of *
# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
# * GNU Lesser General Public License for more details. *
# * *
# * You should have received a copy of the GNU Library General Public *
# * License along with FreeCAD; if not, write to the Free Software *
# * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
# * USA *
# * *
# ***************************************************************************/
FreeCAD.addImportType("My own format (*.own)", "importOwn")
FreeCAD.addExportType("My own format (*.own)", "exportOwn")
print("I am executing some stuff here when FreeCAD starts!")
<translate>
You can choose any license you like for your workbench, but be aware that if you wish to see your workbench integrated into and distributed with the FreeCAD source code at some point, it needs to be LGPL2+ like the example above. See License.
The FreeCAD.addImportType() and addEXportType() functions allow you to give the name and extension of a file type, and a Python module responsible for its import. In the example above, an importOwn.py module will handle .own files. See Code snippets for more examples.
Python workbenches
This is the InitGui.py file:
</translate>
class MyWorkbench (Workbench):
MenuText = "My Workbench"
ToolTip = "A description of my workbench"
Icon = """paste here the contents of a 16x16 xpm icon"""
def Initialize(self):
"""This function is executed when the workbench is first activated.
It is executed once in a FreeCAD session followed by the Activated function.
"""
import MyModuleA, MyModuleB # import here all the needed files that create your FreeCAD commands
self.list = ["MyCommand1", "MyCommand2"] # a list of command names created in the line above
self.appendToolbar("My Commands", self.list) # creates a new toolbar with your commands
self.appendMenu("My New Menu", self.list) # creates a new menu
self.appendMenu(["An existing Menu", "My submenu"], self.list) # appends a submenu to an existing menu
def Activated(self):
"""This function is executed whenever the workbench is activated"""
return
def Deactivated(self):
"""This function is executed whenever the workbench is deactivated"""
return
def ContextMenu(self, recipient):
"""This function is executed whenever the user right-clicks on screen"""
# "recipient" will be either "view" or "tree"
self.appendContextMenu("My commands", self.list) # add commands to the context menu
def GetClassName(self):
# This function is mandatory if this is a full Python workbench
# This is not a template, the returned string should be exactly "Gui::PythonWorkbench"
return "Gui::PythonWorkbench"
Gui.addWorkbench(MyWorkbench())
<translate>
Other than that, you can do anything you want: you could put your whole workbench code inside the InitGui.py if you want, but it is usually more convenient to place the different functions of your workbench in separate files. So those files are smaller and easier to read. Then you import those files into your InitGui.py file. You can organize those files the way you want, a good example is one for each FreeCAD command you add.
Preferences
You can add a Preferences page for your Python workbench. The Preferences pages look for a preference icon with a specific name in the Qt Resource system. If your icon isn't in the resource system or doesn't have the correct name, your icon won't appear on the Preferences page.
Adding your workbench icon:
the preferences icon needs to be named "preferences-" + "modulename" + ".svg" (all lowercase)
make a qrc file containing all icon names
in the main *.py directory, run pyside-rcc -o myResources.py myqrc.qrc
in InitGui.py, add import myResource(.py)
update your repository(git) with myResources.py and myqrc.qrc
You'll need to redo the steps if you add/change icons.
@kbwbe has created a nice script to compile resources for the A2Plus workbench. See below.
Adding your preference page(s):
You need to compile the Qt designer plugin that allows you to add preference settings with Qt Designer
Create a blank widget in Qt Designer (no buttons or anything)
Design your preference page, any setting that must be saved (preferences) must be one of the Gui::Pref* widgets that were added by the plugin)
In any of those, make sure you fill the PrefName (the name of your preference value) and PrefPath (ex: Mod/MyWorkbenchName), which will save your value under BaseApp/Preferences/Mod/MyWorkbenchName
Save the ui file in your workbench, make sure it's handled by cmake
In your workbench, for ex. inside the InitGui file, inside the Initialize method (but any other place works too), add: FreeCADGui.addPreferencePage("/path/to/myUiFile.ui","MyGroup"), "MyGroup" being one of the preferences groups on the left. FreeCAD will automatically look for a "preferences-mygroup.svg" file in its known locations (which you can extend with FreeCADGui.addIconPath())
Make sure the addPreferencePage() method is called only once, otherwise your pref page will be added several times
Distribution
To distribute your Python workbench, you may either simply host the files in some location and instruct your users to download them and place them in their Mod directory manually, or you may host them in an online git repository (GitHub, GitLab, Framagit, and Debian Salsa are currently supported locations) and configure them for the Addon Manager to install. Instructions for inclusion on FreeCAD's official Addons list can be found on the FreeCAD Addons GitHub repository. To use the Addon Manager, a package.xml metadata file should be included, which instructs the Addon Manager how to find your workbench's icon, and allows display of a description, version number, etc. It can also be used to specify other workbenches or Python packages that your Workbench either depends on, is blocked by, or is intended to replace.
Optionally, you can include a separate metadata file describing your Python dependencies. This may be either a file called metadata.txt describing your workbench's external dependencies (on either other Addons, Workbenches, or Python modules), or a requirements.txt describing your Python dependencies. Note that if using a requirements.txt file, only the names of the specified packages are used for dependency resolution: pip command options, include options and version information are not supported by the Addon Manager. Users may manually run the requirements file using pip if those features are required.
The format of the metadata.txt file is plain text, with three optional lines:
</translate>
workbenches=
pylibs=
optionalpylibs=
<translate>
Each line should consist of a comma-separated list of items your Workbench depends on. Workbenches may be either an internal FreeCAD Workbench, e.g. "FEM", or an external Addon, for example "Curves". The required and optional Python libraries should be specified with their canonical Python names, such as you would use with pip install. For example:
You may also include a script that is run when your package is uninstalled. This is a file called "uninstall.py" located at the top level of your Addon. It is executed when a user uninstalls your Addon using the Addon Manager. Use it to clean up anything your Addon may have done to the users system that should not persist when the Addon is gone (e.g. removing cache files, etc.).
To ensure that your addon is being read correctly by the Addon Manager, you can enable a "developer mode" in which the Addon Manager examines all available addons and ensures their metadata contains the required elements. To enable this mode select: Edit → Preferences... → Addon Manager → Addon manager options → Addon developer mode, see Preferences Editor.
C++ workbenches
If you are going to code your workbench in C++, you will probably want to code the workbench definition itself in C++ too (although it is not necessary: you could also code only the tools in C++, and leave the workbench definition in Python). In that case, the InitGui.py file becomes very simple: It might contain just one line:
</translate>
import MyModuleGui
<translate>
where MyModule is your complete C++ workbench, including the commands and workbench definition.
Coding C++ workbenches works in a pretty similar way. This is a typical Workbench.cpp file to include in the Gui part of your module:
You can add a Preferences page for C++ workbenches too. The steps are similar to those for Python.
Distribution
There are two options to distribute a C++ workbench, you can either host precompiled versions for the different operating systems yourself, or you can request for your code to be merged into the FreeCAD source code. As mentioned above this requires a LGPL2+ license, and you must first present your workbench to the community in the FreeCAD forum for review.
FreeCAD commands
FreeCAD commands are the basic building block of the FreeCAD interface. They can appear as a button on toolbars, and as a menu entry in menus. But it is the same command. A command is a simple Python class, that must contain a couple of predefined attributes and functions, that define the name of the command, its icon, and what to do when the command is activated.
Python command definition
</translate>
class My_Command_Class():
"""My new command"""
def GetResources(self):
return {"Pixmap" : "My_Command_Icon", # the name of a svg file available in the resources
"Accel" : "Shift+S", # a default shortcut (optional)
"MenuText": "My New Command",
"ToolTip" : "What my new command does"}
def Activated(self):
"""Do something here"""
return
def IsActive(self):
"""Here you can define if the command must be active or not (greyed) if certain conditions
are met or not. This function is optional."""
return True
FreeCADGui.addCommand("My_Command", My_Command_Class())
<translate>
C++ command definition
Similarly, you can code your commands in C++, typically in a Commands.cpp file in your Gui module. This is a typical Commands.cpp file:
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#***************************************************************************
#* *
#* Copyright (c) 2019 kbwbe *
#* *
#* Portions of code based on hamish's assembly 2 *
#* *
#* This program is free software; you can redistribute it and/or modify *
#* it under the terms of the GNU Lesser General Public License (LGPL) *
#* as published by the Free Software Foundation; either version 2 of *
#* the License, or (at your option) any later version. *
#* for detail see the LICENSE text file. *
#* *
#* This program is distributed in the hope that it will be useful, *
#* but WITHOUT ANY WARRANTY; without even the implied warranty of *
#* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
#* GNU Library General Public License for more details. *
#* *
#* You should have received a copy of the GNU Library General Public *
#* License along with this program; if not, write to the Free Software *
#* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
#* USA *
#* *
#***************************************************************************
# This script compiles the A2plus icons for py2 and py3
# For Linux only
# Start this file in A2plus main directory
# Make sure pyside-rcc is installed
import os, glob
qrc_filename = 'temp.qrc'
if os.path.exists(qrc_filename):
os.remove(qrc_filename)
qrc = '''<RCC>
\t<qresource prefix="/">'''
for fn in glob.glob('./icons/*.svg'):
qrc = qrc + '\n\t\t<file>%s</file>' % fn
qrc = qrc + '''\n\t</qresource>
</RCC>'''
print(qrc)
f = open(qrc_filename,'w')
f.write(qrc)
f.close()
os.system(
'pyside-rcc -o a2p_Resources2.py {}'.format(qrc_filename))
os.system(
'pyside-rcc -py3 -o a2p_Resources3.py {}'.format(qrc_filename))
os.remove(qrc_filename)
Before you go through the pain of debugging use the Test framework to check if the standard tests work properly. If they do not run complete there is possibly a broken installation.
Command Line
The debugging of FreeCAD is supported by a few internal mechanisms. The command line version of FreeCAD provides some options for debugging support.
These are the currently recognized options in FreeCAD 0.19:
Generic options:
-v [ --version ] Prints version string
-h [ --help ] Prints help message
-c [ --console ] Starts in console mode
--response-file arg Can be specified with '@name', too
--dump-config Dumps configuration
--get-config arg Prints the value of the requested configuration key
Configuration:
-l [ --write-log ] Writes a log file to:
$HOME/.local/share/FreeCAD/FreeCAD.log (Linux)
$HOME/Library/Application\ Support/FreeCAD/FreeCAD.log (macOS)
%APPDATA%\FreeCAD\FreeCAD.log (Windows)
--log-file arg Unlike to --write-log this allows to log to an
arbitrary file
-u [ --user-cfg ] arg User config file to load/save user settings
-s [ --system-cfg ] arg System config file to load/save system settings
-t [ --run-test ] arg Test case - or 0 for all
-M [ --module-path ] arg Additional module paths
-P [ --python-path ] arg Additional Python paths
--single-instance Allow to run a single instance of the application
Generating a Backtrace
If you are running a version of FreeCAD from the bleeding edge of the development curve, it may "crash". You can help solve such problems by providing the developers with a "backtrace". To do this, you need to be running a "debug build" of the software. "Debug build" is a parameter that is set at compile time, so you'll either need to compile FreeCAD yourself, or obtain a pre-compiled "debug" version.
Steps:
Enter the following in your terminal window:
Find FreeCAD binary on your system:
</translate>
$ whereis freecad
freecad: /usr/local/freecad <--- for example
$ cd /usr/local/freecad/bin
$ gdb FreeCAD
<translate>
GNUdebugger will output some initializing information. The (gdb) shows GNUDebugger is running in the terminal, now input:
</translate>
(gdb) handle SIG33 noprint nostop
(gdb) run
<translate>
FreeCAD will now start up. Perform the steps that cause FreeCAD to crash or freeze, then enter in the terminal window:
</translate>
(gdb) bt
<translate>
This will generate a lengthy listing of exactly what the program was doing when it crashed or froze. Include this with your problem report.
</translate>
(gdb) bt full
<translate>
Print the values of the local variables also. This can be combined with a number to limit the number of frames shown.
</translate>
<translate>
For macOS
</translate>
<translate>
macOS Debugging →
</translate>
<translate>
Prerequisites:
software package lldb installed
a debug build of FreeCAD
a FreeCAD model that causes a crash
Steps:
Enter the following in your terminal window:
</translate>
$ cd FreeCAD/bin
$ lldb FreeCAD
<translate>
LLDB will output some initializing information. The (lldb) shows the debugger is running in the terminal, now input:
</translate>
(lldb) run
<translate>
FreeCAD will now start up. Perform the steps that cause FreeCAD to crash or freeze, then enter in the terminal window:
</translate>
(lldb) bt
<translate>
This will generate a lengthy listing of exactly what the program was doing when it crashed or froze. Include this with your problem report.
</translate>
<translate>
List Libraries Loaded by FreeCAD
(Applicable to Linux and macOS)
Sometimes it's helpful to understand what libraries FreeCAD is loading, specifically if there are multiple libraries being loaded of the same name but different versions (version collision). In order to see which libraries are loaded by FreeCAD when it crashes you should open a terminal and run it in the debugger. In a second terminal window, find out the process id of FreeCAD:
ps -A | grep FreeCAD
Use the returned id and pass it to lsof:
lsof -p process_id
This prints a long list of loaded resources. So for example, if trying to ascertain if more than one Coin3d library versions is loaded, scroll through the list or search directly for Coin in the output:
lsof -p process_id | grep Coin
Python Debugging
For a more modern approach to debugging Python, see these posts:
Start FreeCAD and load the above file into FreeCAD
Press F6 to execute it
Now FreeCAD will become unresponsive because the Python debugger is waiting
Switch to the Windpdb GUI and click on "Attach". After a few seconds an item "<Input>" appears where you have to double-click
Now the currently executed script appears in Winpdb.
Set a break at the last line and press F5
Now press F7 to step into the Python code of Draft.makeWire
</translate>
<translate>
Visual Studio Code (VS Code)
</translate>
<translate>
VS Code Debugging →
</translate>
<translate>
Prerequisites:
The ptvsd package needs to be installed in a Python 3 outside of FreeCAD, then the module must be copied to FreeCAD's Python library folder.
</translate>
# In a cmd window that has a path to you local Python 3:
pip install ptvsd
# Then if your Python is installed in C:\Users\<userid>\AppData\Local\Programs\Python\Python37
# and your FreeCAD is installed in C:\freecad\bin
xcopy "C:\Users\<userid>\AppData\Local\Programs\Python\Python37\Lib\site-packages\ptvsd" "C:\freecad\bin\Lib\site-packages\ptvsd"
Add following code at the beginning of your script
</translate>
import ptvsd
print("Waiting for debugger attach")
# 5678 is the default attach port in the VS Code debug configurations
ptvsd.enable_attach(address=('localhost', 5678), redirect_output=True)
ptvsd.wait_for_attach()
<translate>
Add a debug configuration in Visual Studio Code Debug → Add Configurations….
Comes ready with pydev and has installers for all platforms.
For linux it is just to extract (to any location) and run.
Configure liclipse for debugging.
Right-click pydev icon (upper right corner) and choose customize.
Activate "PyDev Debug" (through checkbox, or it might be needed to go to tab "Action Set Availability" and activate there first).
In the pydev menu you can now choose "start debug server".
Use menu window/open perspective/other > debug.
Right-click debug icon (upper right corner) and choose customize.
Checking "Debug" brings the debugging navigation tools to the toolbar.
Open preferences through menu window/preferences.
In PyDev/Interpreters add "new Interpreter by browsing".
The added interpreter should be: your loc/squashfs-root/usr/bin/python.
If you are only using this for fc, you can add AddOn workbench folders as well, or do that in a pydev-project later on.
Find path to pydevd.py in your liclipse installation.
Something along the lines of: your location/liclipse/plugins/org.python.pydev.xx/pysrc.
Create a regular pydev-project in liclipse.
Import external sources, for example a macro that you want to debug, or an external workbench.
In that macro (or workbench .py file) add the code lines:
</translate>
import sys; sys.path.append("path ending with /pysrc")
import pydevd; pydevd.settrace()
<translate>
This is where the execution will halt when the macro is run.
Start the liclipse debug server (menu pydev).
Start FreeCAD.
</translate>
squashfs-root> ./usr/bin/freecad
<translate>
Run the macro (or any other file with a pydevd.settrace() trigger) from within freecad, as you would normally do.
Happy debugging.
The use of LiClipse for remote debugging, and the steps described here related to liclipse, should work on any platform. The parts related to AppImage is for linux only.
The Test Framework Workbench is not really a modelling workbench, but it contains a set of Python scripts to perform different tests on the core components of FreeCAD, in order to debug problems. See also debugging.
You can run the tests from the command line, by using the -t or --run-test options.
Run all tests:
</translate>
freecad --run-test 0
<translate>
Run only some the specified unit test, for example:
</translate>
freecad -t TestDraft
<translate>
If a test does not need the GUI, it can also be executed in console mode by setting the -c or --console option in addition. This usually results in much faster startup time as the GUI is not loaded. For example:
</translate>
freecad -c -t TestPartDesignApp
<translate>
Test menu
Each top level directory in FreeCAD should have a file with the tests that can be run for that particular workbench or module. The file usually starts with the word Test.
To run a test from within FreeCAD, switch to the Test Workbench, then Test commands → TestToolsGui → Self test → Select test name, then enter the name of the Python file with the tests; for example, for the Draft Workbench, this would be TestDraft, then press Start.
Test functions
This is the list of test apps as of 0.15 git 4207:
TestAPP.All
Add test function
BaseTests
Add test function
UnitTests
Add test function
Document
Add test function
UnicodeTests
Add test function
MeshTestsApp
Add test function
TestDraft
Add test function
TestSketcherApp
Add test function
TestPartApp
Add test function
TestPartDesignApp
Add test function
TestPathApp
Path workbench test cases:
depthTestCases:
PathTestUtils:
TestDressupDogbone: Test functionality of Dogbone dressup.
TestHoldingTags: Test functionality of Holding Tags dressup.
TestPathAdaptive: Test selection capability of Adaptive operation.
TestPathCore: Test core functionality of Path workbench.
TestPathDeburr: Test general functionality of Deburr operation.
TestPathGeom: Test various functions available in the PathGeom module.
TestPathHelix: Test general functionality of Helix operation.
TestPathLog: Test various functions available in the PathLog debugging and feedback module.
TestPathOpTools:
TestPathPreferences: Test various functions available in the PathPreferences module.
TestPathPropertyBag:
TestPathSetupSheet:
TestPathStock:
TestPathThreadMilling:
TestPathTool:
TestPathToolBit:
TestPathToolController:
TestPathTooltable:
TestPathUtil: Test various functions available in the PathUtil module.
TestPathVcarve: Test general functionality of Vcarve operation.
Note that the test modules returned here depend on whether a GUI available or not. I.e. when executed in console mode, various tests ending in "Gui" are missing.
Run specific tests
There are various ways of running tests using Python's unittest library. FreeCAD's test framework removes some of the boiler plate for the most common cases.
Run all tests defined in a Python module:
</translate>
Within the Python Console of FreeCAD, the following code format may be used to run built-in tests. Replace the red "TestFem" text in the code below with the desired module test name.
For example, use "TestPathApp" to run all unit tests for the Path workbench unit test framework.
Submodules are available using dot notation, like "TestPathApp.TestPathAdaptive" to only run the Adaptive unit tests within the greater Path workbench test framework.
Multiple test modules or submodules may be combined by adding another `suite.addTest(...)` method call just like the one in the code below, but with a different module or submodule reference.
Output for the code below will be in the Report View panel within the FreeCAD GUI.
Code source is copied from post by FreeCAD forum user, sgrogan, in the unit tests per python topic, with credit there given to forum user, wmayer.
</translate>
import unittest
suite = unittest.TestSuite()
suite.addTest(unittest.defaultTestLoader.loadTestsFromName("TestFem"))
r = unittest.TextTestRunner()
r.run(suite)
This article describes the Branding of FreeCAD. Branding means to create your own application based on FreeCAD. That can be only your own executable or splash screen till a complete reworked program. On base of the flexible architecture of FreeCAD it's easy to use it as base for your own special purpose program.
Warning
Although FreeCAD is offered to you free of charge, and the FreeCAD community is happy to see other applications emerging, that are based on FreeCAD, we have on the other hand seen a lot of unfair use of the information contained on this page by people who simply rebranded FreeCAD into a closed-source application to make profit from it.
Although the LGPL license allows to use the FreeCAD source code in closed-source applications, it also gives strict rules to do so, and does not allow simply taking FreeCAD, renaming it and stripping it of its license.
Would you be interested in using FreeCAD in a closed-source application, be sure to check thoroughly the implications of the LGPL license, and, even better, contact any FreeCAD developer, administrator or moderator before doing so.
General
Most of the branding is done in the MainCmd.cpp or MainGui.cpp. These Projects generate the executable files of FreeCAD. To make your own Brand just copy the Main or MainGui projects and give the executable its own name, e.g. FooApp.exe.
The most important settings for a new look are made in one place in the main() function. Here is the code section that controls the branding:
</translate>
int main( int argc, char ** argv )
{
// Name and Version of the Application
App::Application::Config()["ExeName"] = "FooApp";
App::Application::Config()["ExeVersion"] = "0.7";
// set the banner (for loging and console)
App::Application::Config()["CopyrightInfo"] = sBanner;
App::Application::Config()["AppIcon"] = "FooAppIcon";
App::Application::Config()["SplashScreen"] = "FooAppSplasher";
App::Application::Config()["StartWorkbench"] = "Part design";
App::Application::Config()["HiddenDockWindow"] = "Property editor";
App::Application::Config()["SplashAlignment" ] = "Bottom|Left";
App::Application::Config()["SplashTextColor" ] = "#000000"; // black
// Inits the Application
App::Application::Config()["RunMode"] = "Gui";
App::Application::init(argc,argv);
Gui::BitmapFactory().addXPM("FooAppSplasher", ( const char** ) splash_screen);
Gui::Application::initApplication();
Gui::Application::runApplication();
App::Application::destruct();
return 0;
}
<translate>
The first Config entry defines the program name. This is not the executable name, which can be changed by renaming or by compiler settings, but the name that is displayed in the task bar on windows or in the program list on Unix systems.
The next lines define the Config entries of your FooApp Application. A description of the Config and its entries you find in Start up and Configuration.
Images
Image resources are compiled into FreeCAD using Qt's resource system. Therefore you have to write a .qrc file, an XML-based file format that lists image files on the disk but also any other kind of resource files. To load the compiled resources inside the application you have to add a line
</translate>
Q_INIT_RESOURCE(FooApp);
<translate>
into the main() function. Alternatively, if you have an image in XPM format you can directly include it into your main.cpp and add the following line to register it:
In FreeCAD there is also a method supported without writing a customized main() function. For this method you must write a file name called branding.xml and put it into the installation directory of FreeCAD. Here is an example with all supported tags:
</translate>
<?xml version="1.0" encoding="utf-8"?>
<Branding>
<Application>FooApp</Application>
<WindowTitle>Foo App in title bar</WindowTitle>
<BuildVersionMajor>1</BuildVersionMajor>
<BuildVersionMinor>0</BuildVersionMinor>
<BuildRevision>1234</BuildRevision>
<BuildRevisionDate>2014/1/1</BuildRevisionDate>
<CopyrightInfo>(c) My copyright</CopyrightInfo>
<MaintainerUrl>Foo App URL</MaintainerUrl>
<ProgramLogo>Path to logo (appears in bottom right corner)</ProgramLogo>
<WindowIcon>Path to icon file</WindowIcon>
<ProgramIcons>Path to program icons</ProgramIcons>
<SplashScreen>splashscreen.png</SplashScreen>
<SplashAlignment>Bottom|Left</SplashAlignment>
<SplashTextColor>#ffffff</SplashTextColor>
<SplashInfoColor>#c8c8c8</SplashInfoColor>
<StartWorkbench>PartDesignWorkbench</StartWorkbench>
</Branding>
Localisation is in general the process of providing a Software with a multiple language user interface. In FreeCAD you can set the language of the user interface under Edit → Preferences → General. FreeCAD uses Qt to enable multiple language support. On Unix/Linux systems, FreeCAD uses the current locale settings of your system by default.
Helping to translate FreeCAD
One of the very important things users can contribute to FreeCAD (if for example they don't have programming skills) is to help translate its different aspects (source code, wiki, website, documentation etc...) in to another language. Here are the ways to do that.
Translate the FreeCAD source code
FreeCAD utilizes a third party collaborative on-line translation system called Crowdin.
It is proprietary software but free to FOSS projects. Below are instructions on how to use it:
Login by creating a new profile, or using a third-party account (GitHub, GitLab, GMail etc...)
Click on the language you wish to translate
Start translating by clicking on the Translate button next to one of the files. For example, FreeCAD.ts contains the text strings for the FreeCAD main GUI.
You can vote for existing translations, or you can create your own.
If you are actively taking part in translating FreeCAD and want to be informed before next release is ready to be launched, so there is time to review your translation, please subscribe to one of the Crowdin FreeCAD translation teams.
Starting with FreeCAD 0.20, the following variables can be manually added to the BaseApp/Preferences/General section of the user.cfg file to assist with the development of new translations:
AdditionalLanguageDomainEntries - to add entirely new languages to FreeCAD that are not currently supported by the source code, you can use this user preference to add to the list of available languages. The format of the languages is "Language Name"="code"; for example:
AdditionalTranslationsDirectory - add an additional directory for FreeCAD to search for *.qm files. This location will take precedence over $userAppDataDir/translations and $resourceDir/translations. For example:
This wiki hosts a lot of contents, the majority of which build up the manual. You can browse the documentation starting from the Main Page, or have a look at the user's manual Online Help Toc.
You should also have enough knowledge of wiki markup and follow the general styling guidelines described on WikiPages.
Mediawiki Translation Extension
When the wiki moved away from SourceForge, Yorik installed MediaWiki's Translation extension which facilitates translating pages. Advantages of the translation extension are that the page title can now be translated, it keeps track of translations, it notifies if the original page has been updated, and it maintains translations in sync with the original English page.
To quickly get started on preparing a page for translation, please read the Page translation example.
Essentially, a pair of
</translate>
<translate> ... </translate>
<translate>
tags need to surround the entire page to activate the translation system, and the page needs to be marked for translation.
To see an example of how the translation tool works, visit the Main Page. You will see an automatically generated language bar at the top. Click on Deutsch (German), it will get you to Main Page/de. Right under the title, "Hauptseite" (in English "Main Page"), you can read This page is a translated version of the page Main Page and the translation is XX% complete, XX being the current percentage of translation. Click on "Translate" at the top of the page to start the translation utility to update, correct and review the existing translation.
If you go to Main Page, you will notice that you cannot edit the page directly anymore by clicking the [Edit] tags, and the top link "Edit" has been substituted by the "Translate" link that opens the translation utility.
When adding new content, the English page should be created first, then translated into another language. If someone wants to change or add content in a page, the English page should be modified first.
Every wiki user that has "Editor" permissions is able to launch the translate utility to write, save and review translations.
However, only users with "Administrator" permissions are able to mark pages for translation. A page that is not marked for translation won't make use of the translation extension and won't be correctly synchronized to the English information.
The left sidebar is also translatable, but only Administrators can modify this element of the site. Please follow the dedicated instructions on Localisation Sidebar.
The first time you switch a page to the new translation system, it loses all its old "manual" translations. To recover a translation, you should save an offline copy of the old text before the switch. Then you can use this old translated text to fill in the translation units in the new system. You can also open an earlier version from the history, and get the old text in this way. This has to be done for every language that had a translated page.
Translate the FreeCAD documentation
As per general consensus, the reference page in the wiki is the English page, which should be created first. If you want to change or add content to a page, you should do it to the English page first, and only once the update is completed, port the modification to the translated page.
Old translation instructions
These instructions are for historical background only. Translations should use the new system with the #Mediawiki Translation Extension described above.
So the first step is to check if the manual translation has already been started for your language (look in the left sidebar, under "manual").
If not, head to the forum and say that you want to start a new translation, we'll create the basic setup for the language you want to work on.
You must then gain wiki edit permission.
If your language is already listed, see what pages are still missing a translation (they will be listed in red). The technique is simple: go into a red page, and copy/paste the contents of the corresponding English page, and start translating.
Do not forget to include all the tags and templates from the original English page. Some of those templates will have an equivalent in your language (for example, there is a French Docnav template called Docnav/fr). You should use a slash and your language code in almost all the links. Look at other already translated pages to see how they did it.
Add a slash and your language code in the categories, like [[Category:Developer Documentation/fr]]
And if you are unsure, head to the forums and ask people to check what you did and tell you if it's right or not.
Four templates are commonly used in manual pages. These 4 templates have localized versions (Template:Docnav/fr, Template:fr, etc...)
Template:GuiCommand : is the Gui Command information block in upper-right of command documentation.
Template:Docnav : it is the navigation bar at the bottom of the pages, showing previous and next pages.
Page Naming Convention
Please take note that, due to limitations in the Sourceforge implementation of the MediaWiki engine, we require that your pages all keep their original English counterpart's name, appending a slash and your language code. For example, the translated page for About FreeCAD should be About Freecad/es for Spanish, About FreeCAD/pl for polish, etc. The reason is simple: so that if translators go away, the wiki's administrators, who do not speak all languages, will know what these pages are for. This will facilitate maintenance and avoid lost pages.
If you want the Docnav template to show linked pages in your language, you can use redirect pages. They are basically shortcut links to the actual page. Here is an example with the French page for About FreeCAD.
The page About FreeCAD/fr is the page with content
The page À propos de FreeCAD contains this code:
#REDIRECT [[About_FreeCAD/fr]]
In the About FreeCAD/fr page, the Docnav code will look like this:
{{docnav/fr|[[Online_Help_Startpage/fr|Bienvenue dans l'aide en ligne de FreeCAD]]|[[Feature_list/fr|Fonctionnalités]]}}
The page "Bienvenue dans l'aide en ligne de FreeCAD" redirects to Online_Help_Startpage/fr, and the page "Fonctionnalités" redirects to Feature_list/fr.
Translate the FreeCAD website
Translation of the FreeCAD website is now done through Crowdin. The file is named homepage.po.
Development - How to Add Localisation
This section is for developers who want to add localisation to their code.
Preparing your FreeCAD/master modules for translation
These are the parts to the FreeCAD translation process:
extract text strings from source code into *.ts files
convert *.ts files into *.qm files and update each module's *.qrc file
update FreeCAD master
All of the above steps are performed by the "translation scripts" which are run by an administrator periodically.
Preparing your module for translation is quite easy. First, you need to ensure that you have a "translations" directory in myModule/Gui/Resources. Then open a terminal window (or Windows/OSX equivalent) in your "translations" directory and enter the following command:
lupdate -ts myModule.ts
This creates an empty translation file. Once this is done, you need to ensure that the translation scripts are updated as in this pull request.
Everything after this is automatic as far as a developer is concerned. The administrator will extract the text strings, the translators will translate them, then the administrator will extract the translations and update FreeCAD/master.
Preparing your 3rd party module or macro for translation
3rd party modules or macros are translated in much the same fashion, except that you must do some of the work yourself.
This forum discussion describes the details.
Localization Older Methods describes the use of translation tools such as Qt Linguist, lupdate, lrelease, pylupdate4, etc in detail. Most of this is no longer required for FreeCAD/master modules, but may be helpful preparing and updating 3rd party modules.
Automating Crowdin Translation Updates
Currently FreeCAD maintainers use the Crowdin API via Crowdin Scripts to pull and push translations in to Crowdin and back in to the Github repo. The Crowdin API gives FreeCAD maintainers the ability to automate aspects of the project's translation workflow, for more info refer to the Crowdin API documentation.
This page lists several additional Python modules or other pieces of software that can be downloaded freely from the internet, and add functionality to your FreeCAD installation.
optional, but needed by several modules: Draft, Arch, Ship, Plot, OpenSCAD, Spreadsheet
PySide (previously PyQt) is required by several modules of FreeCAD to access FreeCAD's Qt interface. It is already bundled in the windows verison of FreeCAD, and is usually installed automatically by FreeCAD on Linux, when installing from official repositories. If those modules (Draft, Arch, etc) are enabled after FreeCAD is installed, it means PySide (previously PyQt) is already there, and you don't need to do anything more.
Note: FreeCAD progressively moved away from PyQt after version 0.13, in favour of PySide, which does exactly the same job but has a license (LGPL) more compatible with FreeCAD.
Installation
Linux
The simplest way to install PySide is through your distribution's package manager. On Debian/Ubuntu systems, the package name is generally python-PySide, while on RPM-based systems it is named pyside. The necessary dependencies (Qt and SIP) will be taken care of automatically.
PS: these examples of errors were found in the transition from PyQt4 to PySide and these corrections were made, other solutions are certainly available with the examples above
</translate>
try:
import PyQt4 # PyQt4
from PyQt4 import QtGui ,QtCore # PyQt4
from PyQt4.QtGui import QComboBox # PyQt4
from PyQt4.QtGui import QMessageBox # PyQt4
from PyQt4.QtGui import QTableWidget, QApplication # PyQt4
from PyQt4.QtGui import * # PyQt4
from PyQt4.QtCore import * # PyQt4
except Exception:
import PySide # PySide
from PySide import QtGui ,QtCore # PySide
from PySide.QtGui import QComboBox # PySide
from PySide.QtGui import QMessageBox # PySide
from PySide.QtGui import QTableWidget, QApplication # PySide
from PySide.QtGui import * # PySide
from PySide.QtCore import * # PySide
<translate>
To access the FreeCAD interface, type:
You can add new elements, like a custom widget, with commands like:
</translate>
myNewFreeCADWidget = QtGui.QDockWidget() # create a new dockwidget
myNewFreeCADWidget.ui = Ui_MainWindow() # myWidget_Ui() # load the Ui script
myNewFreeCADWidget.ui.setupUi(myNewFreeCADWidget) # setup the ui
try:
app = QtGui.qApp # PyQt4 # the active qt window, = the freecad window since we are inside it
FCmw = app.activeWindow() # PyQt4 # the active qt window, = the freecad window since we are inside it
FCmw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myNewFreeCADWidget) # add the widget to the main window
except Exception:
FCmw = FreeCADGui.getMainWindow() # PySide # the active qt window, = the freecad window since we are inside it
FCmw.addDockWidget(QtCore.Qt.RightDockWidgetArea,myNewFreeCADWidget) # add the widget to the main window
<translate>
Working with Unicode:
</translate>
try:
text = unicode(text, 'ISO-8859-1').encode('UTF-8') # PyQt4
except Exception:
text = text.encode('utf-8') # PySide
<translate>
Working with QFileDialog and OpenFileName:
</translate>
OpenName = ""
try:
OpenName = QFileDialog.getOpenFileName(None,QString.fromLocal8Bit("Lire un fichier FCInfo ou txt"),path,"*.FCInfo *.txt") # PyQt4
except Exception:
OpenName, Filter = PySide.QtGui.QFileDialog.getOpenFileName(None, "Lire un fichier FCInfo ou txt", path, "*.FCInfo *.txt")#PySide
def errorDialog(msg):
diag = QtGui.QMessageBox(QtGui.QMessageBox.Critical,u"Error Message",msg )
try:
diag.setWindowFlags(PyQt4.QtCore.Qt.WindowStaysOnTopHint) # PyQt4 # this function sets the window before
except Exception:
diag.setWindowFlags(PySide.QtCore.Qt.WindowStaysOnTopHint)# PySide # this function sets the window before
# diag.setWindowModality(QtCore.Qt.ApplicationModal) # function has been disabled to promote "WindowStaysOnTopHint"
diag.exec_()
<translate>
Working with setProperty (PyQt4) and setValue (PySide)
optional, but needed by several modules of FreeCAD: Draft, Arch
Pivy is a needed by several modules to access the 3D view of FreeCAD. On windows, Pivy is already bundled inside the FreeCAD installer, and on Linux it is usually automatically installed when you install FreeCAD from an official repository. On macOS, unfortunately, you will need to compile pivy yourself.
Installation
Prerequisites
I believe before compiling Pivy you will want to have Coin and SoQt installed.
I found for building on Mac it was sufficient to install the Coin3 binary package. Attempting to install coin from MacPorts was problematic: tried to add a lot of X Windows packages and ultimately crashed with a script error.
Starting with Debian Squeeze and Ubuntu Lucid, pivy will be available directly from the official repositories, saving us a lot of hassle. In the meantime, you can either download one of the packages we made (for debian and ubuntu karmic) availables on the Download pages, or compile it yourself.
The best way to compile pivy easily is to grab the debian source package for pivy and make a package with debuild. It is the same source code from the official pivy site, but the debian people made several bug-fixing additions. It also compiles fine on ubuntu karmic: http://packages.debian.org/squeeze/python-pivy download the .orig.gz and the .diff.gz file, then unzip both, then apply the .diff to the source: go to the unzipped pivy source folder, and apply the .diff patch:
</translate>
patch -p1 < ../pivy_0.5.0~svn765-2.diff
<translate>
then
</translate>
debuild
<translate>
to have pivy properly built into an official installable package. Then, just install the package with gdebi.
Then you need a tool called SWIG to generate the C++ code for the Python bindings. Pivy-0.5 reports that it has only been tested with SWIG 1.3.31, 1.3.33, 1.3.35, and 1.3.40. So you can download a source tarball for one of these old versions from http://www.swig.org. Then unpack it and from a command line do (as root):
</translate>
./configure
make
make install (or checkinstall if you use it)
<translate>
It takes just a few seconds to build.
Alternatively, you can try building with a more recent SWIG. As of March 2012, a typical repository version is 2.0.4. Pivy has a minor compile problem with SWIG 2.0.4 on macOS (see below) but seems to build fine on Fedora Core 15.
After that go to the pivy sources and call
</translate>
python setup.py build
<translate>
which creates the source files. Note that build can produce thousands of warnings, but hopefully there will be no errors.
This is probably obsolete, but you may run into a compiler error where a 'const char*' cannot be converted in a 'char*'. To fix that you just need to write a 'const' before in the appropriate lines. There are six lines to fix.
These instructions may not be complete. Something close to this worked for OS 10.7 as of March 2012. I use MacPorts for repositories, but other options should also work.
As for linux, get the latest source:
</translate>
hg clone http://hg.sim.no/Pivy/default Pivy
<translate>
If you don't have hg, you can get it from MacPorts:
</translate>
port install mercurial
<translate>
Then, as above you need SWIG. It should be a matter of:
</translate>
port install swig
<translate>
I found I needed also:
</translate>
port install swig-python
<translate>
As of March 2012, MacPorts SWIG is version 2.0.4. As noted above for linux, you might be better off downloading an older version. SWIG 2.0.4 seems to have a bug that stops Pivy building. See first message in this digest
This can be corrected by editing the 2 source locations to add dereferences: *arg4, *arg5 in place of arg4, arg5. Now Pivy should build:
Assuming you are using Visual Studio 2005 or later you should open a command prompt with 'Visual Studio 2005 Command prompt' from the Tools menu.
If the Python interpreter is not yet in the system path do
</translate>
set PATH=path_to_python_2.5;%PATH%
<translate>
To get pivy working you should get the latest sources from the project's repository:
</translate>
svn co https://svn.coin3d.org/repos/Pivy/trunk Pivy
<translate>
Then you need a tool called SWIG to generate the C++ code for the Python bindings. It is recommended to use version 1.3.25 of SWIG, not the latest version, because at the moment pivy will only function correctly with 1.3.25. Download the binaries for 1.3.25 from http://www.swig.org. Then unpack it and from the command line add it to the system path
</translate>
set PATH=path_to_swig_1.3.25;%PATH%
<translate>
and set COINDIR to the appropriate path
</translate>
set COINDIR=path_to_coin
<translate>
On Windows the pivy config file expects SoWin instead of SoQt as default. I didn't find an obvious way to build with SoQt, so I modified the file setup.py directly.
In line 200 just remove the part 'sowin': ('gui._sowin', 'sowin-config', 'pivy.gui.') (do not remove the closing parenthesis).
After that go to the pivy sources and call
</translate>
python setup.py build
<translate>
which creates the source files. You may run into a compiler error several header files couldn't be found. In this case adjust the INCLUDE variable
</translate>
set INCLUDE=%INCLUDE%;path_to_coin_include_dir
<translate>
and if the SoQt headers are not in the same place as the Coin headers also
</translate>
set INCLUDE=%INCLUDE%;path_to_soqt_include_dir
<translate>
and finally the Qt headers
</translate>
set INCLUDE=%INCLUDE%;path_to_qt4\include\Qt
<translate>
If you are using the Express Edition of Visual Studio you may get a Python keyerror exception. In this case you have to modify a few things in msvccompiler.py located in your Python installation.
Go to line 122 and replace the line
</translate>
vsbase = r"Software\Microsoft\VisualStudio\%0.1f" % version
<translate>
with
</translate>
vsbase = r"Software\Microsoft\VCExpress\%0.1f" % version
<translate>
Then retry again. If you get a second error like
</translate>
error: Python was built with Visual Studio 2003;...
error: Python was built with Visual Studio version 8.0, and extensions need to be built with the same version of the compiler, but it isn't installed.
<translate>
then you should check the environment variables DISTUTILS_USE_SDK and MSSDK with
</translate>
echo %DISTUTILS_USE_SDK%
echo %MSSDK%
<translate>
If not yet set then just set it e.g. to 1
</translate>
set DISTUTILS_USE_SDK=1
set MSSDK=1
<translate>
Now, you may run into a compiler error where a 'const char*' cannot be converted in a 'char*'. To fix that you just need to write a 'const' before in the appropriate lines. There are six lines to fix. After that copy the generated pivy directory to a place where the Python interpreter in FreeCAD can find it.
Usage
To check if Pivy is correctly installed:
</translate>
import pivy
<translate>
To have Pivy access the FreeCAD scenegraph do the following:
</translate>
from pivy import coin
App.newDocument() # Open a document and a view
view = Gui.ActiveDocument.ActiveView
FCSceneGraph = view.getSceneGraph() # returns a pivy Python object that holds a SoSeparator, the main "container" of the Coin scenegraph
FCSceneGraph.addChild(coin.SoCube()) # add a box to scene
<translate>
You can now explore the FCSceneGraph with the dir() command.
Additonal Documentation
Unfortunately documentation about pivy is still almost nonexistant on the net. But you might find Coin documentation useful, since pivy simply translate Coin functions, nodes and methods in Python, everything keeps the same name and properties, keeping in mind the difference of syntax between C and Python:
optional, needed to enable import and export of Collada (.DAE) files
pyCollada is a Python library that allow programs to read and write Collada (*.DAE) files. When pyCollada is installed on your system, FreeCAD will be able to handle importing and exporting in the Collada file format.
Installation
Linux
</translate>
sudo apt-get install python3-collada
<translate>
You can check if pycollada was correctly installed by issuing in a Python console:
</translate>
import collada
<translate>
If it returns nothing (no error message), then all is OK
Windows
On Windows since 0.15 pycollada is included in both the FreeCAD release and developer builds so no additional steps are necessary.
MacOS
If you are using the Homebrew build of FreeCAD you can install pycollada into your system Python using pip.
If you need to install pip:
</translate>
$ sudo easy_install pip
<translate>
Install pycollada:
</translate>
$ sudo pip install pycollada
<translate>
If you are using a binary version of FreeCAD, you can tell pip to install pycollada into the site-packages inside FreeCAD.app:
optional, needed to extend import abilities of IFC files
IFCOpenShell is a library currently in development, that allows to import (and soon export) Industry foundation Classes (*.IFC) files. IFC is an extension to the STEP format, and is becoming the standard in BIM workflows. When ifcopenshell is correctly installed on your system, the FreeCAD Arch Workbench will detect it and use it to import IFC files, instead of its built-in rudimentary importer. Since ifcopenshell is based on OpenCasCade, like FreeCAD, the quality of the import is very high, producing high-quality solid geometry.
Installation
Since ifcopenshell is pretty new, you'll likely need to compile it yourself.
Linux
You will need a couple of development packages installed on your system in order to compile ifcopenshell:
</translate>
liboce-*-dev
python-dev
swig
<translate>
but since FreeCAD requires all of them too, if you can compile FreeCAD, you won't need any extra dependency to compile IfcOpenShell.
Since ifcopenshell is made primarily for Blender, it uses Python3 by default. To use it inside FreeCAD, you need to compile it against the same version of Python that is used by FreeCAD. So you might need to force the Python version with additional cmake parameters (adjust the Python version to yours):
You can check that ifcopenshell was correctly installed by issuing in a Python console:
</translate>
import ifcopenshell
<translate>
If it returns nothing (no error message), then all is OK
Windows
Note: Official FreeCAD installers obtained from the FreeCAD website/github page now contain ifcopenshell already.
Copied from the IfcOpenShell README file
Users are advised to use the Visual Studio .sln file in the win/ folder. For Windows users a prebuilt Open CASCADE version is available from the opencascade website. Download and install this version and provide the paths to the Open CASCADE header and library files to MS Visual Studio C++.
For building the IfcPython wrapper, SWIG needs to be installed. Please download the latest swigwin version from swig website. After extracting the .zip file, please add the extracted folder to the PATH environment variable. Python needs to be installed, please provide the include and library paths to Visual Studio.
LazyLoader is a Python module that allows deferred loading, while still importing at the top of the script. This is useful if you are importing another module that is slow, and it is used several times throughout the script. Using LazyLoader can improve workbench startup times, but the module will still need to be loaded on first use.
Installation
LazyLoader is included with FreeCAD v0.19
Usage
You will need to import LazyLoader, then change the import of whatever module you want to be deferred.
from lazy_loader.lazy_loader import LazyLoader
Part = LazyLoader('Part', globals(), 'Part')
The variable Part is how the module is named in your script. You can replicate "import Part as P" by changing the variable.
FreeCAD would not be what it is without the generous contributions of many people. Here's an overview of the people and companies who contributed to FreeCAD over time. For credits for the third party libraries see the Third Party Libraries page.
People from the community who put a lot of efforts in helping the FreeCAD project either by being active on the forum, keeping a blog about FreeCAD, making video tutorials, packaging FreeCAD for Windows/Linux/macOS, writing a FreeCAD book... (listed by alphabetical order) (retrieved from http://forum.freecadweb.org/memberlist.php?mode=&sk=d&sd=d#memberlist).
User documentation
button in the Status bar or by right-clicking an empty area of the 3D view.
<translate>
<translate>
button in the Status bar.
groups, move objects to groups, delete objects or groups, by right-clicking in the tree view or on an object, rename objects by double-clicking on their names, or possibly other operations, depending on the current workbench.
Mesh Workbench creates mesh objects, the 
Part Workbench create Part objects, the 
Draft Workbench also creates Part objects, etc.
will be added to the thumbnail.
button (introduced in version 0.21) to switch the top and bottom colors.
<translate>
Std DlgCustomize command:
Std WhatsThis command.
<translate>
button.
button.
button or the 
button.
<translate>
Addon Manager are set up automatically, and added to a 
Std DlgMacroExecute command to find this folder on your system.
Power user documentation
Std Base. This is not really a workbench, but rather a category of 'standard' commands and tools that can be used in all workbenches.
The Arch Workbench for working with architectural elements.
The Assembly Workbench for building and solving mechanical assemblies. introduced in version 0.22
The CAM Workbench is used to produce G-Code instructions. This workbench was called "Path Workbench" in version 0.21 and below.
The Draft Workbench contains 2D tools and basic 2D and 3D CAD operations.
The FEM Workbench provides Finite Element Analysis (FEA) workflow.
The Inspection Workbench is made to give you specific tools for examination of shapes. Still in the early stages of development.
The Mesh Workbench for working with triangulated meshes.
The OpenSCAD Workbench for interoperability with OpenSCAD and repairing constructive solid geometry (CSG) model history.
The Part Workbench for working with geometric primitives and boolean operations.
The Part Design Workbench for building Part shapes from sketches.
The Points Workbench for working with point clouds.
The Reverse Engineering Workbench is intended to provide specific tools to convert shapes/solids/meshes into parametric FreeCAD-compatible features.
The Robot Workbench for studying robot movements. Currently unmaintained.
The Sketcher Workbench for working with geometry-constrained sketches.
The Spreadsheet Workbench for creating and manipulating spreadsheet data.
The Start Workbench allows you to quickly jump to one of the most common workbenches.
The Surface Workbench provides tools to create and modify surfaces. It is similar to the Part Builder Face from edges option.
The TechDraw Workbench for producing technical drawings from 3D models. It is the successor of the Drawing Workbench.
The Test Framework Workbench is for debugging FreeCAD.
The Web Workbench provides you with a browser window instead of the 3D view within FreeCAD.
The Drawing Workbench was used for producing technical drawings. The TechDraw Workbench is its more advanced replacement.
The Image Workbench was used for working with bitmap images. Its functionality has been integrated in Std Base. See Std Import and Std ViewLoadImage.
The Raytracing Workbench was used for ray-tracing (rendering). The external Render Workbench should be used instead.
PartDesign Workbench.
<translate>
Import mesh...: Imports a mesh object from a file.
Export mesh...: Exports a mesh object to a file.
Create mesh from shape...: Creates mesh objects from shape objects.
Refinement...: Remeshes a mesh object.
Evaluate and repair mesh...: Evaluates and repairs a mesh object.
Face info: Shows information about faces of mesh objects.
Curvature info: Shows the absolute curvature of curvature objects at selected points.
Check solid mesh: Checks if a mesh object is solid.
Boundings info...: Shows the bounding box coordinates of a mesh object.
Curvature plot: Creates Mesh Curvature objects for mesh objects.
Harmonize normals: Harmonizes the normals of mesh objects.
Flip normals: Flips the normals of mesh objects.
Fill holes...: Fills holes in mesh objects.
Close hole: Fills selected holes in mesh objects.
Add triangle: Adds faces along a boundary of an open mesh object.
Remove components...: Removes faces from mesh objects.
Remove components by hand...: Removes components from mesh objects.
Create mesh segments...: Creates separate mesh segments for specified surface types of a mesh object.
Create mesh segments from best-fit surfaces...: Creates separate mesh segments for specified surface types of a mesh object, and can identify their parameters.
Smooth...: Smooths mesh objects.
Decimation...: Reduces the number of faces in mesh objects.
Scale...: Scales mesh objects.
Regular solid...: Creates a regular parametric solid mesh object.
Union: Creates a mesh object that is the union of two mesh objects.
Intersection: Creates a mesh object that is the intersection of two mesh objects.
Difference: Creates a mesh object that is the difference of two mesh objects.
Cut mesh: Cuts whole faces from mesh objects.
Trim mesh: Trims faces and parts of faces from mesh objects.
Trim mesh with a plane: Trims faces and parts of faces on one side of a plane from a mesh object.
Create section from mesh and plane: Creates a cross section across a mesh object.
Cross-sections...: Creates multiple cross sections across mesh objects.
Merge: Creates a mesh object by combining the meshes of two or more mesh objects.
Split by components: Splits a mesh object into its components.
Unwrap mesh: Creates a flat representation of a mesh object.
Unwrap face: Creates a flat representation of a face of a shape object.
Display: On the Mesh view tab several preferences can be set.
OpenSCAD: The Mesh Union, Mesh Intersection and Mesh Difference commands require OpenSCAD and use the OpenSCAD executable preference to find its executable.
Sketcher, 
<translate>
Box: Creates a box.
Cylinder: Creates a cylinder.
Sphere: Creates a sphere.
Cone: Creates a cone.
Torus: Creates a torus.
Tube: Creates a tube.
Create primitives...: A tool to create one of the following primitives:
Plane: Creates a plane.
Box: Creates a box. This object can also be created with the 
Cylinder: Creates a cylinder. This object can also be created with the 
Cone: Creates a cone. This object can also be created with the 
Sphere: Creates a sphere. This object can also be created with the 
Ellipsoid: Creates a ellipsoid.
Torus: Creates a torus. This object can also be created with the 
Prism: Creates a prism.
Wedge: Creates a wedge.
Helix: Creates a helix.
Spiral: Creates a spiral.
Circle: Creates a circular arc.
Ellipse: Creates an elliptical arc.
Point: Creates a point.
Line: Creates a line.
Regular polygon: Creates a regular polygon.
Shape builder...: Creates shapes from various primitives.
Extrude: Extrudes planar faces.
Revolve: Creates a solid by revolving an object (not a solid) around an axis.
Mirror: Mirrors the selected object across a mirror plane.
Scale: Scales one or more shapes. introduced in version 0.22
Fillet: Fillets (rounds) edges of an object.
Chamfer: Chamfers edges of an object.
Make face from wires: Makes a face from a set of wires (contours).
Ruled Surface: Creates a ruled surface.
Loft: Lofts from one profile to another.
Sweep: Sweeps one or more profiles along a path.
Section: Creates a section by intersecting an object with a section plane.
Cross sections...: Creates one or more cross-sections through an object.
Thickness: Hollows out a solid.
Projection on surface: Projects a logo, text or any face, wire or edge onto a surface.
Attachment: Attaches an object to another object.
Compound Tools:
Make compound: Creates a compound from the selected objects.
Explode Compound: Splits up compounds.
Compound Filter: Extracts the individual pieces from compounds.
Boolean: Performs boolean operations on objects.
Cut: Cuts (subtracts) one object from another.
Fuse: Fuses (unions) two or more objects.
Common: Extracts the common (intersection) part of two objects.
Splitting tools:
Boolean fragments: Creates all pieces obtained from Boolean operations.
Slice apart: Slices and splits an object by intersecting it with other objects.
Slice: Slices an object by intersecting it with other objects.
XOR: Removes space shared by an even number of objects.
Measure Linear: Creates a linear measurement.
Measure Angular: Creates an angular measurement.
Measure Refresh: Updates all measurements.
Clear All: Clears all measurements.
Toggle All: Shows or hides all measurements.
Toggle 3D: Shows or hides 3D measurements.
Toggle Delta: Shows or hides delta measurements.
Import: Imports from *.IGES, *.STEP, or *.BREP files.
Export: Exports to *.IGES, *.STEP, or *.BREP files.
Box selection: Selects faces from a rectangular area.
Create shape from mesh: Creates a shape object from a mesh object.
Create points object from geometry: Creates a points object from a geometric object.
Convert to solid: Converts a shape object to a solid object.
Reverse shapes: Flips the normals of all faces of selected objects.
Create simple copy: Creates a simple copy of a selected object.
Create transformed copy: Creates a transformed copy of a selected object.
Create shape element copy: Creates a copy from an element (vertex, edge, face) of a selected object.
Refine shape: Cleans faces by removing unnecessary lines.
Check geometry: Checks the geometry of selected objects for errors.
Defeaturing: Removes features from an object.
Appearance: Determines the appearance of a whole object (color, transparency etc.).
Color per face: Assigns colors to individual faces of objects.
Preferences: Preferences available for Part Tools (the Part workbench also uses the PartDesign Preferences).
Import Export Preferences: Preferences available for importing from and exporting to different file formats.
<translate>
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
Macro Automatic drawing: Allows the user to get the view of his object in a drawing with 4 different position (front,top,iso,right). Needs some modification to be perfectly effective.
Macro CartoucheFC: This GUI macro to fill simply all fields of the cartridge of the plan implementation worksheet FreeCAD, the format of the date and the symbol of the projection mode adapt to the EU region or US selected.
Macro CartoucheFC 2: This GUI macro to fill simply all fields of the cartridge model 2 of the plan implementation worksheet FreeCAD.
Macro CartoucheFC Full: This GUI macro to fill simply all fields of the cartridge Misc templates Full of the plan implementation worksheet FreeCAD, the format of the date and the symbol of the projection mode adapt to the EU region or US selected.
Macro Corner shapes wizard/update: Pops up a dialog asking for the dimensions of your corner piece, then creates the object in the document and creates a page view with top, front and lateral views of the piece.
<translate>
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
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
Preferences: Preferences available in for the Raytracing tools.
Open...: open an image on a new viewport.
Create image plane...: import an image to a plane in the 3D view.
Scale image plane: scale an image imported to a plane.
<translate>
Line: creates a straight line.
Polyline: creates a polyline (also called wire), a sequence of several connected line segments.
Fillet: creates a fillet, a rounded corner, or a chamfer, a straight edge, between two Draft Lines.
Arc tools:
Arc by 3 points: creates a circular arc from three points that define its circumference.
Circle: creates a circle from a center and a radius.
Ellipse: creates an ellipse from two points defining a rectangle in which the ellipse will fit.
Rectangle: creates a rectangle from two points.
Polygon: creates a regular polygon from a center and a radius.
B-spline: creates a B-spline curve from several points.
Bézier curve: creates a Bézier curve from several points.
Point: creates a simple point.
Facebinder: creates a surface object from selected faces.
ShapeString: creates a compound shape that represents a text string.
Hatch: creates hatches on the planar faces of a selected object. introduced in version 0.20
Text: creates a multi-line text at a given point.
Dimension: creates a linear dimension, a radial dimension or an angular dimension.
Label: creates a multi-line text with a 2-segment leader line and an arrow.
Annotation styles...: allows you to define styles that affect the visual properties of annotation-like objects.
Move: moves or copies selected objects from one point to another.
Rotate: rotates or copies selected objects around a center point by a given angle.
Scale: scales or copies selected objects around a base point.
Mirror: creates mirrored copies from selected objects.
Offset: offsets each segment of a selected object over a given distance, or creates an offset copy of the selected object.
Trimex: trims or extends a selected object.
Stretch: stretches objects by moving selected points.
Clone: creates linked copies, clones, of selected objects.
Polar array: creates an array from a selected object by placing copies along a circumference. It can optionally create a Link array.
Circular array: creates an array from a selected object by placing copies along concentric circumferences. It can optionally create a Link array.
Path array: creates an array from a selected object by placing copies along a path.
Path link array: idem, but create a Link array instead of a regular array.
Point array: creates an array from a selected object by placing copies at the points from a point compound.
Point link array: idem, but create a Link array instead of a regular array.
Edit: puts selected objects in Draft Edit mode. In this mode the properties of objects can be edited graphically.
Subelement highlight: temporarily highlights selected objects, or the base objects of selected objects.
Join: joins Draft Lines and Draft Wires into a single wire.
Split: splits a Draft Line or Draft Wire at a specified point or edge.
Upgrade: upgrades selected objects.
Downgrade: downgrades selected objects.
Wire to B-spline: converts Draft Wires to Draft BSplines and vice versa.
Draft to sketch: converts Draft objects to Sketcher Sketches and vice versa.
Set slope: slopes selected Draft Lines or Draft Wires by increasing, or decreasing, the Z coordinate of all points after the first one.
Flip dimension: rotates the dimension text of selected Draft Dimensions 180° around the dimension line.
Shape 2D view: creates 2D projections from selected objects.
<translate>
Select plane: defines the current Draft working plane. Also available in the menu: Draft → Utilities → 
Select Plane.
Set style: sets the default style for new objects. Also available in the menu: Draft → Utilities → 
Set style.
Toggle construction mode: switches Draft construction mode on or off. Also available in the menu: Draft → Utilities → 
Toggle construction mode.
AutoGroup: changes the active Draft Layer or, optionally, the active Std Group or group-like Arch object.
<translate>
<translate>
Snap lock: enables or disables snapping globally.
Snap endpoint: snaps to the endpoints of edges.
Snap midpoint: snaps to the midpoint of edges.
Snap center: snaps to the center point of faces and circular edges, and to the DataPlacement point of Draft WorkingPlaneProxies and Arch BuildingParts.
Snap angle: snaps to the special cardinal points on circular edges, at multiples of 30° and 45°.
Snap intersection: snaps to the intersection of two edges.
Snap perpendicular: snaps to the perpendicular points on faces (introduced in version 0.21) and edges.
Snap extension: snaps to an imaginary line that extends beyond the endpoints of straight edges.
Snap parallel: snaps to an imaginary line parallel to straight edges.
Snap special: snaps to special points defined by the object.
Snap near: snaps to the nearest point on faces and edges.
Snap ortho: snaps to imaginary lines that cross the previous point at multiples of 45°.
Snap grid: snaps to the intersections of grid lines.
Snap working plane: projects snap points onto the current working plane.
Snap dimensions: shows temporary X and Y dimensions.
Toggle grid: changes the visibility of the grid.
Manage layers...: allows to manage the layers in a document. introduced in version 0.21
Add a new named group: creates a named Std Group and moves selected objects to that group. introduced in version 0.20
Move to group...: moves objects to a Std Group. It can also ungroup objects.
Select group: selects the contents of Std Groups or group-like Arch objects.
Add to construction group: moves objects to the Draft construction group.
Toggle normal/wireframe display: switches the ViewDisplay Mode property of selected objects between 
Create working plane proxy: creates a working plane proxy to save the current Draft working plane.
Apply current style: applies the current style settings to selected objects.
Layer: creates a Draft Layer. Available in the Draft utility tools toolbar in version 0.20 and below.
Heal: heals problematic Draft objects found in very old files.
Show snap toolbar: shows the Draft snap toolbar.
Add new layer: adds a new layer to the current document.
Array: creates an orthogonal array from a selected object. The created array can be turned into a polar array or a circular array by changing its DataArray Type property. Not available in version 0.21 and above.
Drawing: inserts views of selected objects into a drawing page. Not available in version 0.21 and above.
Toggle continue mode: switches continue mode on or off. Not available in version 0.22 and above.
Preferences: general preferences for the Draft Workbench.
. On it you have 4 buttons: Record, stop recording, edit and play the current macro.
</translate>
<translate>
Parameter Editor: Tools → Edit parameters... → BaseApp → Preferences → General → TempPath
<translate>