Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Some english language enhancements #23

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Some english language enhancements #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aa9d168
Some english language enhancements
raffael-mnhn Feb 17, 2022
d717087
Some language improvements
raffael-mnhn Feb 18, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 29 additions & 31 deletions chapters/1.FreeCAD_overview_architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@

# FreeCAD overview and architecture

First of all, thanks to the original developers (**Jürgen Riegel, Werner Mayer, Yorik van Havre**), for sharing this great artwork freely. FreeCAD is released under LGPL license, free for commercial usage with dynamic linkage.
First of all, thanks to the original developers (**Jürgen Riegel, Werner Mayer, Yorik van Havre**), for sharing this great artwork freely. FreeCAD is released under the LGPL license, free for commercial usage with dynamic linkage.

## Introduction to FreeCAD

The birth of FreeCAD: version 0.0.1 uploaded by [Jürgen Riegel](https://wiki.freecadweb.org/User:Jriegel) October 29, 2002 Initial Upload
The birth of FreeCAD is marked by the release of version 0.0.1 by [Jürgen Riegel](https://wiki.freecadweb.org/User:Jriegel) on October 29, 2002.

The FreeCAD [Wikipedia](https://en.wikipedia.org/wiki/FreeCAD) page.

Expand Down Expand Up @@ -36,52 +36,49 @@ https://github.com/joelgraff/pivy-trackers

### Key software libraries

see FreeCAD source code structure in [Chapter 2](2.FreeCAD_source_code_structure.md)
See FreeCAD source code structure in [Chapter 2](2.FreeCAD_source_code_structure.md)

*standing on giant's shoulder*

- OpenCASCADE as CAD kernel
- OpenInventor/Coin3D/pivy for 3D scene rendering
- Qt and 'Qt for Python' (aka PySide2) for GUI
- Qt and 'Qt for Python' (aka PySide2) for the graphical user interface (GUI)
- Python scripting and wrapping: PyCXX, swig, boost.python
- Other powerful software libraries like Xerces XML, boost

The geometry algorithm using OpenCASCADE will be discussed in [Chapter 7](7.FreeCAD_CAD_modules.md).
The geometry algorithms using OpenCASCADE will be discussed in [Chapter 7](7.FreeCAD_CAD_modules.md).


### Mixed Python and c++

* Python scripting in console mode and python-based macro recording in GUI mode
* All FreeCAD class is derived from this *BaseClass*, connected with *BaseClassPy*
* All FreeCAD classes are derived from this *BaseClass*, connected with *BaseClassPy*
* c++11 is not extensively used before 0.17
* c++ template is not heavily used, but `FeatureT<>` make `DocumentObject, ViewProvider` extensible in Python
* FreeCAD not tied to Qt system until GUI, `Boost::signal` is used in command line mode: FreeCADCmd
* `std::string`(UTF8) is used internally, using `QString getString(){QString.fromUtf8(s.c_str())}`
* c++ for most of time consuming task (threading model), to avoid bottleneck of Global Interpreter Lock
* c++ templates are not heavily used, but `FeatureT<>` make `DocumentObject, ViewProvider` extensible in Python
* FreeCAD not tied to Qt system unless GUI is used, `Boost::signal` is used in command line mode: FreeCADCmd
* `std::string`(UTF8) is used internally, using `QString getString(){QString.fromUtf8(s.c_str())}`. This removes unnecessary coupling to Qt.
* c++ is used for most of time consuming task (threading model) and to avoid bottleneck of Global Interpreter Lock

Mixing c++ and Python in module development will be discussed in [Chapter 5](5.FreeCAD_Python_wrapping.md).

### GPL code will not be included into installer

<https://github.com/yorikvanhavre/Draft-dxf-importer>

Current FreeCAD policy is to include only LGPL software and no GPL by default. Mentioned DXF import-export libraries were downloaded by default. On DXF import-export operation in the past but Debian didn't like that and FreeCAD changed in a way user has to manually enable (Opt-In) the download.

Open **Draft** workbench and after that select *Edit -> Preferences*. Under *Import-Export -> DXF / DWG* tab, enable *Automatic update*. After that FreeCAD will download mentioned libraries on first DXF import-export operation and it should work. If it does not work restart FreeCAD and try again.

Current FreeCAD policy is to include only LGPL software and no GPL by default. Mentioned DXF import-export libraries were downloaded by default. On DXF import-export operation in the past but Debian didn't like that and FreeCAD changed in a way that the user has to manually enable (Opt-In) the download.

Open **Draft** workbench and after that select *Edit -> Preferences*. Under *Import-Export -> DXF / DWG* tab, enable *Automatic update*. After that FreeCAD will download mentioned libraries on first DXF import-export operation and it should work. If it does not work, restart FreeCAD and try again.

### Funding condition

It is still unofficially driven by community, developed by developers in free time, yet any foundation established.


It is still unofficially driven by community, developed by developers in free time. A foundation is being setup as of 2022.


## How 3D model are rendered

The geometry that appears in the 3D views of FreeCAD are rendered by the Coin3D library. Coin3D is an implementation of the OpenInventor standard, which exempt you from OpenGL coding.
see [FreeCAD wiki on OpenInventor Scenegraph](https://www.freecadweb.org/wiki/Scenegraph). Some other examples of 3D rendering:
The geometry that appears in the 3D views of FreeCAD are rendered by the Coin3D library. Coin3D is an implementation of the OpenInventor standard, which relieves the developer of manually using the low-level OpenGL API.

See [FreeCAD wiki on OpenInventor Scenegraph](https://www.freecadweb.org/wiki/Scenegraph). Some other examples of 3D rendering:

[Civil engineering feature implementation (Transportation Engineering)](https://www.forum.freecadweb.org/viewtopic.php?f=8&t=22277&p=332557#p332557)

Expand All @@ -97,26 +94,27 @@ print viewprovider.toString()

### Pivy: Coin3D's Python wrapping

**pivy** is Python wrapper of Coin3D C++ lib, via SWIG
A new `SoPyScript` Node is added to include Python script directly
**pivy** is Python wrapper of Coin3D C++ lib, via SWIG. A new `SoPyScript` Node is added to include Python script directly

[pivy trackers](https://github.com/joelgraff/pivy-trackers) - A small python library of pivy/coin3D-based objects for rendering lines / nodes at the scenegraph level for user interface feedback. Implemented originally as a part of the FreeCAD Trails Workbench.

### Selection of 3D visualization library
### Selection of 3D visualization libraries

OpenCASCADE, as a CAD kernel, did not render 3D object to screen (when FreeCAD was born in 2002) until recently release. Currently, there are several 3D lib based on OpenGL, see a list that works with QT <https://wiki.qt.io/Using_3D_engines_with_Qt>. 3D gaming engines can also been used to render 3D objects, such as OGRE(Object-Oriented Graphics Rendering Engine), Unreal, Unity.
OpenCASCADE, FreeCAD's CAD kernel, did not render 3D object to screen until recently. Since FreeCAD was born in 2002, it had to come with its own rendering code. Currently, there are several 3D rendering libraries based on OpenGL. For a list of Qt compatible ones, c.f. <https://wiki.qt.io/Using_3D_engines_with_Qt>. 3D gaming engines could also be used to render 3D objects, examples are OGRE(Object-Oriented Graphics Rendering Engine), Unreal or Unity.

Selection of Open Inventor to render FreeCAD is based on software license and performance consideration. Open Inventor, originally IRIS Inventor, is a C++ object oriented retained mode 3D graphics API designed by SGI to provide a higher layer of programming for OpenGL. Its main goals are better programmer convenience and efficiency. Open Inventor is free and open-source software, subject to the requirements of the GNU Lesser General Public License (LGPL), version 2.1, in Aug 2000.
The choice of Open Inventor as FreeCAD's rendering engine is based on software license and performance consideration. Open Inventor, originally IRIS Inventor, is a C++ object oriented, retained mode, 3D graphics API designed by SGI to provide a higher layer of programming for OpenGL. Its main goals are better programmer convenience and efficiency. Open Inventor is free and open-source software, subject to the requirements of the GNU Lesser General Public License (LGPL), version 2.1, in Aug 2000.

Coin3D implements the same API but not source code with Open Inventor, via clean room implementation compatible Stable release Open Inventor v2.1. Kongsberg ended development of Coin3D in 2011 and released the code under the BSD 3-clause license. It is possible to draw object in OpenInventor Scene by Python, via Coin3D's python wrapper *pivy* , see <https://www.freecadweb.org/wiki/Pivy>
Coin3D implements the same API but does not share source code with Open Inventor. It is a clean room implementation compatible with the Open Inventor v2.1 API. The company Kongsberg ended development of Coin3D in 2011 and released the code under the BSD 3-clause license. It is possible to draw object in OpenInventor Scene from Python, via Coin3D's python wrapper *pivy*, see <https://www.freecadweb.org/wiki/Pivy>.

VTK, is another open source and cross-platform visualization library, which ParaView is based on. Interoperation is possible, see
[Method for converting output from the VTK pipeline into Inventor nodes](https://www.evl.uic.edu/scharver/vtkoiv.html). From 0.17 and beyond, VTK pipeline is added to Fem m[pivy trackers](https://github.com/joelgraff/pivy-trackers) - A small python library of pivy/coin3D-based objects for rendering lines / nodes at the scenegraph level for user interface feedback. Implemented originally as a part of the FreeCAD Trails Workbench.
[Method for converting output from the VTK pipeline into Inventor nodes](https://www.evl.uic.edu/scharver/vtkoiv.html). From 0.17 and beyond, VTK pipeline is added to the FEM workbench.

[pivy trackers](https://github.com/joelgraff/pivy-trackers) - A small python library of pivy/coin3D-based objects for rendering lines / nodes at the scenegraph level for user interface feedback. Implemented originally as a part of the FreeCAD Trails Workbench.


### Discussion of 3D rendering library selection on FreeCAD Forum

Here are my questions on 3D rendering library selection, I posted on FreeCAD Forum:
The author's questions on 3D rendering library selection posted on the FreeCAD Forum:

> I browse OpenCASCADE doc[1], showing graph of OpenCASCADE source code architecture. It is similar with FreeCAD. Why FreeCAD develops its own Foundation Class, Document controller, Object Tree Structure, etc. There are lot of overlapping.

Expand Down Expand Up @@ -157,14 +155,14 @@ Transitioning from OpenGL to Vulkan will not happen in the future, while OpenGL

### C++11

C++ is NOT a easy language but targeting at high performance, you need to manage memory manually and there are a lot of pitfalls, see <http://horstmann.com/cpp/pitfalls.html>. Even experienced C++ programmer will find himself/herself has not fully master C++. Exception safety will be beyond layman's brain.
C++ is NOT an easy language but targeting high performance, you need to manage memory manually and there are a lot of pitfalls, see <http://horstmann.com/cpp/pitfalls.html>. Even experienced C++ programmer will find themselves not mastering C++ fully. Exception safety is an especially difficult concept to grasp.

Common pitfalls for c++ are exampled in appendix.
Some common pitfalls of C++ are listed in the appendix.

Nevertheless, c++11 is almost a branch new language, or next generation c++. c++11 add some extra keywords like "explicit, overload/final, noexcept" to avoid some unintended mistakes, also introduce new features and extra STL functions like lambda and std::function, constexpr, enum class, smart pointer, auto type derivation, std::thread, atomic, regex etc.
C++11 is almost a brad new language, or next generation c++. It added some extra keywords like "explicit, overload/final, noexcept" to avoid some unintended mistakes and also introduce new features and extra STL functionality like lambda and std::function, constexpr, enum class, smart pointer, auto type derivation, std::thread, atomic, regex etc.

### Pyside 2 project for Qt 5.x

Official LGPL python wrapping for Qt 5.x, pyside2, or Qt for Python, has been released with Qt 5.12.
Official LGPL python wrappers for Qt 5.x, called pyside2 or Qt for Python have been released with Qt 5.12.

> The Pyside 2 project aims to provide a complete port of PySide to Qt 5.x. The development started on GitHub in May 2015. The project managed to port Pyside to Qt 5.3, 5.4 & 5.5. During April 2016 The Qt Company decided to properly support the port (see details).
Loading