Module developer’s guide to FreeCAD source
code
for FreeCAD version 0.17-dev
1
Module developer’s guide to FreeCAD source code
by Qingfeng Xia http://www.iesensor.com
• 2015-09-18 version 0.1 for FreeCAD version 0.16-dev
• 2016-09-18 version 0.2 for FreeCAD version 0.17-dev
License of this book
This ebook is licensed the same as FreeCAD document license CC-BY 3.0
http://creativecommons.org/licenses/by/3.0/
Acknowledge to developers of FreeCAD
Original/lead developers:
• Jürgen Riegel
• Werner Mayer
• yorik van havre
Add all contributors see http://www.freecadweb.org/wiki/index.php?title=
Contributors
Target audiances: new module developers
Make sure you are familiar with FreeCAD workbench GUI and API as a user:
• Foundamental document on official wiki for FreeCAD
• FreeCAD python API document
• single file PDF user manual for quick start
Doxygen documents links
Doxygen generated online documentation of source for 0.16dev
Why I want to write this book
• Learn the software architecture of FreeCAD: a large open source project
• Learn to use git to contribute to open source projects like FreeCAD
• Save time for new developers to explore the source codde of FreeCAD
• Record personal note and lesson during writing/contributing code to
• Some chapters of this ebook is seeking to be merged into official wiki after
FreeCAD
reviewed as usable
1
Organisation of this book
• Chapters are written in markdown and PDF is generated by pandoc
• Python scripts to link Introduction to header files: *_folder_desc.py
• Python script merge.py merges chapters into single md file then PDF
How to contribute to this ebook
• write on unfinished topics/chapters listed in todo.md fork and pull request
git clone https://github.com/qingfengxia/FreeCAD_Mod_Dev_Guide.git
• file bug for outdated code analysis As this book is about code anlysis while
FreeCAD is under heavy development, source codes quoted may outdated
quickly. Please point out by report bugs in github
Acknowledgement to my family
Thanks for my wife Ms J. Wang, and other family members’ consideration
2
Contents
1 FreeCAD overview and architecture
1.1
Introduction to FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 Key features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3 Software architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.1 Key software libraries
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2 Mixed python and c++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.3 GPL code will not be included into installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4 How 3D model are renderred . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.1
Selection of 3D visualization libarary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.4.2 Discussion of 3D rendering library selection on FreeCAD Forum . . . . . . . . . . . . . . . . . . . . .
1.5 Roadmap of FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.1 Keep updated with main components:
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.2 C++11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.5.3 Pyside 2 project for Qt 5.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 Organisation of FreeCAD source code
2.1 Build system for FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.1.1 Analysis of src/cMake/SMesh.cMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 List of files and folders in FreeCAD source folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 List of modules in FreeCAD Mod folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Learning path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Learning OpenInventor/Coin3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 OpenInventor in FreeCAD’s ViewProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.2
Important classes in OpenInventor/Coin3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.3 Window System integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.4 Pivy: Coin3D ’s Python wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3 Base, App and Main module
3.1 List of header files in Base folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1 Frequently included headers files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.2 Correct way of using Sequencer in try-catch block . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.3
String enconding utf8 and conversion into wchar_t QString . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Type, BaseClass, PyObjectBase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Type system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
src/Base/BaseClass.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2
src/Base/PyObjectBase.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.3
3.2.4
src/Base/Persistence.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.5 GeoFeature: Base class of all geometric document objects . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Unit scheme for physial quantity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
src/Base/Unit.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
src/Base/Quantity.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4 List of header files in App folder
3.5 Property framewrok . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.1 Naming of property and PropertyEditor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.2
src/App/PropertyStandard.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.3 PropertyEnumeration, see src/App/Enumeration.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.4 Geometry related property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.5 File related property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.1
3.3.2
7
7
7
7
7
8
8
8
8
8
9
9
9
9
11
11
11
12
13
14
14
14
15
18
18
19
19
21
21
22
22
22
23
26
26
26
27
27
27
27
29
29
30
30
30
30
1
2
CONTENTS
3.5.6 Links related property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.7 PropertyMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.8 Properties with Units for physical Quantities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.9
src/App/Property.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.10 src/App/PropertyContainer.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5.11 Macro functions for Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Document-View-Observer Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
src/App/Document.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.1
3.6.2
src/App/DocumentObject.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.3 Observer and Subject pattern for documentObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.4 App::DocumentObjectExecReturn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.5 FeaturePython . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.6 FeaturePythonPy template class
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6.7 Extension framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 Startup process of FreeCADCmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.1
skeleton of main() function in src/Main/MainCmd.cpp . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.2
src/Main/MainPy.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.3 App::Application class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7.4 How Python interpreter is integrated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8 FreeCADGui start up process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1 main() in src/Main/MainGui.cpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
runApplication() in src/Gui/Application.cpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.2
3.8.3
src/Main/FreeCADGuiPy.cpp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4 Overview of Gui module
4.4
4.1 List of header files in Gui folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Important classes in Gui namespace
4.2
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.1 Gui::Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.2 Gui::Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.3 GUI components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.4 Gui Services API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.2.5
Selection API in Python and C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3 ViewProvider framework and 3D rederring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.1
Gui::ViewProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.2
Gui::DocumentObjectViewProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.3
Gui::ViewProviderGeometryObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.4
Fem::ViewProviderFemConstraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.5
3D CAD Part rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.6 View3DInventor class
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.7 ViewProivder and 3DViewer
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.8
2D drawing rendering using Qt native QGraphicsView . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.3.9
further reading on ViewProvider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
selection framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
src/Gui/Selection.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.1
src/Gui/SelectionObject.h thin wrapper of DocumentObject pointer . . . . . . . . . . . . . . . . . . .
4.4.2
4.4.3
src/Gui/SelectionView.h show present selection in QListWidget of DockWindow . . . . . . . . . . . .
src/Gui/SelectionFilter.h expression based filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.4
4.4.5
src/Gui/MouseSelection.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.4.6 Example of getSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5 Command framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.1 Overview of command framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.2 Drawbacks of QAction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.3 Way out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.5.4 Boost::signal is used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6 TaskView Framework: UI for interactive design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.1
Important classed related to TaskView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.2 Controller of TaskView and TaskDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.3 TaskDriver
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
preference page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.6.4
4.7 Expression and quantity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
30
31
31
31
32
32
32
33
34
34
34
35
36
36
36
37
37
38
39
39
39
40
43
43
46
46
46
46
46
48
49
49
50
51
51
52
53
53
54
54
54
54
55
55
55
55
55
56
56
56
56
57
57
57
58
59
59
59
CONTENTS
4.8
Internationalization with FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.8.1 Overview of FreeCAD i18n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.8.2
integrate a new language into FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4.8.3 Update of FreeCAD translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5 Introduction to Python Wrapping
5.1 Overview of hybrid cpp and Python programing
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.1 TemplatePyMod as a collection of pure python examples
. . . . . . . . . . . . . . . . . . . . . . . . .
5.1.2 Example of writing Part or Feature in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.3 What is the limitation of pure python module except for performance? . . . . . . . . . . . . . . . . . .
5.1.4 How python object is serialized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.5 DocumentObjectPy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.6 Python 3 support is under way . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1.7 Cheat Sheet: Writing Python 2-3 compatible code . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Python wrapping in FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.1 Options for python wrapping C or cpp code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.2 Choice of python wrapping frameworks in FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.3 How xml file works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.4 Direct usage of C API is NOT recommended . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.5 PyCXX: supporting Python 2 and Python 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.6
other tools to automatically generate wrapping code for Python Scripting . . . . . . . . . . . . . . . .
5.2.7
Simplified wrapping by template FeaturePythonT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2.8 Automatically generate wrapping code in FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 Extending cpp class function in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.1 Proxy relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.2
App::FeaturePythonT in src/App/FeaturePython.h . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.3 Example of aggregation of Fem::FemSolverObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3.4 Gui::ViewProviderPythonFeatureT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4 Advanced topics: GIL and manually wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.1 Example of C API usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.4.2 GIL in src/App/interpreter.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6 Modular Design of FreeCAD (plugin system)
6.2.1
6.2.2 Module Init process
6.1 Workbench framework: key to modular design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.1 Create Workbench step by step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.1.2
pure python module is possible like Plot module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 List of essential files in Module folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
fcbt(FreeCAD build tool) to generate a new module . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Important headers in Part Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.1
src/Mod/Part/App/PartFeature.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.2
6.3.3
Sketcher Module: 2D Geometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.4 PartDesign Module: advanced 3D model buiding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3.5 OpenCasCade Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Extra Addons/Plugins and installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.3 Part Module
7 FEM Module Source Code Analysis
7.1
Introduction of Fem Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2 How is Fem module designed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.1 FemAppPy.cpp: file open and export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.2 AppFemGui.cpp initFemGui() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.3 Communication of App Object and Gui Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.4
Selection, SelectionGate and SelectionFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.2.5 When python scripts should be loaded? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
src/Mod/Fem/App/FemAnalysis.h DocumentObjectGroup . . . . . . . . . . . . . . . . . . . . . . . .
7.3.1
src/Mod/Fem/MechanicalMaterial.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3.2
7.3.3 FemResultObject: a good example to create new object . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Key classes analysis
7.4 FemConstraint
3
59
59
59
61
63
63
63
63
64
64
64
64
65
65
65
66
66
66
67
67
67
67
68
68
69
70
70
71
71
72
75
75
75
78
78
79
80
80
80
81
82
82
82
83
85
85
85
86
86
86
86
86
87
87
88
88
90
4
CONTENTS
7.4.1 FemConstraint: base class for all Constraint Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.2 ViewProviderFemConstraint: drawing in inventor scene . . . . . . . . . . . . . . . . . . . . . . . . . .
7.4.3 TaskFemConstraint
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5 FemMesh, based on Salome SMESH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Import and export mesh formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5.1
7.5.2
src/Mod/Fem/App/FemMesh.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5.3 Mesh generation by Tetgen and GMSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5.4 FemSetObject: base class to group submesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5.5 FemNodeSet as group of element for constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6.1 FemResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6.2 VTK Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.7 PreferencePage for Fem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.8 Qt specific UI design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.8.1 FreeCAD Qt designer plugin installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.8.2 MOC (Qt meta object compiling) ui file compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.6 FemResult and VTK based post-processing pipeline
90
90
91
91
91
91
91
92
92
92
92
92
92
93
93
93
8 Developing CFD Module Based on FemWorkbench
8.1 Design of CFD solver for FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1 Adding CFD analysis to FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.2 Liteautrue review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.3 Roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.4 Python or C++? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.5 Documation and wiki
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 Design of Cfd Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.1
code reusage from FEM workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2 C++ related code are commit directly to Fem module . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.3
Init.py and InitGui.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.4 CfdAnalysis.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.5 CfdTools.py: utility and mesh export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.6 CfdRunnable.py: solver specifc runner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.7 FoamCaseWriter: write OpenFOAM case setting files
. . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.8 FoamCaseBuilder: a python module to build OpenFOAM case . . . . . . . . . . . . . . . . . . . . . .
8.2.9 CfdResult: to view result in FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3 Create FemSovlerObject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.1 Why FemSolverObject is needed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.2 App::DocumentObject derived class: FemSovlerObject.h . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.3 Gui part: ViewProviderSolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.4 Command to add FemSolver to FemWorkbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95
95
95
95
95
96
96
96
96
96
97
97
97
97
97
97
97
98
98
98
99
99
8.4 Boundary condition setings for CFD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.4.1 Design of FemConstraintFluidBoundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.4.2
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.4.3 FemConstraintFluidBoundary.h and FemConstraintFluidBoundary.cpp . . . . . . . . . . . . . . . . . . 101
8.4.4 ViewProviderConstraintFluidBoundary.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.4.5 TaskFemConstraintFluidBoundary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.4.6
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.4.7 GUI menubar and toolbar: Command.cpp and Workbench.cpp . . . . . . . . . . . . . . . . . . . . . . 103
8.5 Example of extending FemSolverObject in python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
code for extending FeaturePythonT object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8.6 Develop a new CFD solver within CFD workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.5.1 Procedure for extending FeaturePythonT object
8.5.2
procedure of adding ConstraintFluidBoundary class
svg icon “fem-fluid-boundary” and update Fem.qrc,
9 Testing and Debugging Module
107
9.0.1 Python and c++ IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.1 Extra tools for module developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9.2 C++ debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
build FreeCAD from source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
reduce compiling time by ccache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
print debug info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
tips for debug cpp code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.2.1
9.2.2
9.2.3
9.2.4
CONTENTS
5
9.3
step-by-step debugging via gdb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.4 Python debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.4.1
tips for developing in Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9.4.2 Where is python’s print message? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
reload edited python module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.4.3
10 Contribute code to FreeCAD
113
10.1 Read first . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
10.1.1 The official guide for developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
. . . . . . . . . . . . . . . . . . . . . . . . . . 113
10.1.2 Read FreeCAD forum and state-of-the-art development
10.2 Develop FreeCAD by git . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
10.2.1 Learn git
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
10.2.2 Setup your git repo and follow official master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
10.2.3 Implement new functionality in branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
10.2.4 Jump between branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
10.2.5 Keep branch updated with official master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
10.2.6 Merge with GUI mergetool meld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
10.2.7 clean branch after failing to rebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
10.2.8 git setup for FreeCAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
10.2.9 useful tips for git users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
10.2.10 Testing feature or bugfix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
10.2.11 Procedure for user without a online forked repo (not tested ,not recommended) . . . . . . . . . . . . . 117
10.2.12 Pull request and check feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
10.2.13 example of pull request for bugfix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
10.3 Code review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
10.3.1 Travis-ci auto compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
10.3.2 code review tool and process
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
11 FreeCAD coding style
11.3 Python coding style
121
11.1 text encoding and spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
11.2 Qt style C++ coding style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
11.2.1 Fifference from Qt style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
11.3.1 Disccusion on Python coding standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
11.3.2 style checker
11.4 Inconsistent of naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
11.4.1 Inconsistent API for getter
12 Cmake cheat sheet
125
12.1 quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
12.2 cmake language syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
12.3 important commands and variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
12.3.1 1.commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
12.3.2 2. location variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
12.3.3 3. compiler control variables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
12.3.4 4. predefined platform and compiler detection varibles . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
12.3.5 5. command line help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
12.4 Why cmake?
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
12.5 what I do not like . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127