A tutorial for Researchers interested in Approximation Theory, Computer-Aided Geometric Design, Isogeometric and Numerical Analysis
An OpenGL- and C++-based function library for curve and surface modeling in a large class of extended Chebyshev spaces
ACM Transactions on Mathematical Software, Vol. 45, No. 1, Article 13, 2019
@ Publisher | @ Authorized ACM link | @ CALGO
Always use the latest version of the library. Last update: February 10, 2021.
The latest version of the proposed function library can be downloaded by accessing this link. After extracting the provided zip file, the obtained folder structure should consist of the following items:
992
| readme.txt
|
+---00_Dependencies
| | readme.txt
| |
| +---Include
| | +---GL
| | readme.txt
| |
| +---Lib
| | +---GL
| | +---x64
| | | readme.txt
| | |
| | +---x86
| | readme.txt
| |
| +---Models
| | cone.off
| | sphere.off
| |
| +---Shaders
| color.frag
| color.vert
| reflection_lines.frag
| reflection_lines.vert
| two_sided_lighting.frag
| two_sided_lighting.vert
|
+---01_Library
| | Makefile.Linux.Debug
| | Makefile.Linux.Release
| | Makefile.Mac.Debug
| | Makefile.Mac.Release
| | Makefile.Windows.Debug.x64
| | Makefile.Windows.Debug.x86
| | Makefile.Windows.Release.x64
| | Makefile.Windows.Release.x86
| | readme.txt
| |
| +---cagd
| | cagd.pro
| |
| +---Core
| | | Exceptions.h
| | | Utilities.cpp
| | | Utilities.h
| | |
| | +---Geometry
| | | +---Coordinates
| | | | Cartesians3.h
| | | | Colors4.h
| | | | Homogeneous3.h
| | | | TCoordinates4.h
| | | |
| | | +---Curves
| | | | GenericCurves3.cpp
| | | | GenericCurves3.h
| | | | LinearCombinations3.cpp
| | | | LinearCombinations3.h
| | | |
| | | +---Surfaces
| | | Lights.cpp
| | | Lights.h
| | | Materials.cpp
| | | Materials.h
| | | TensorProductSurfaces3.cpp
| | | TensorProductSurfaces3.h
| | | TriangleMeshes3.cpp
| | | TriangleMeshes3.h
| | | TriangularFaces.h
| | |
| | +---Math
| | | Constants.h
| | | GenericGLTransformations.cpp
| | | GenericGLTransformations.h
| | | Matrices.h
| | | PascalTriangles.cpp
| | | PascalTriangles.h
| | | RealMatrices.cpp
| | | RealMatrices.h
| | | RealMatrixDecompositions.cpp
| | | RealMatrixDecompositions.h
| | | SpecialGLTransformations.cpp
| | | SpecialGLTransformations.h
| | |
| | +---Shaders
| | | ShaderPrograms.cpp
| | | ShaderPrograms.h
| | |
| | +---SmartPointers
| | CheckingPolicies.h
| | ImplicitConversionPolicies.h
| | OwnershipPolicies.h
| | SmartPointers.h
| | SpecializedSmartPointers.h
| | StaticChecks.h
| | StoragePolicies.h
| | TypeSelectors.h
| |
| +---EC
| BCurves3.cpp
| BCurves3.h
| BSurfaces3.cpp
| BSurfaces3.h
| CharacteristicPolynomials.cpp
| CharacteristicPolynomials.h
| ECSpaces.cpp
| ECSpaces.h
|
+---02_User_manual
| readme.txt
| User_manual.pdf
|
+---03_Examples
| readme.txt
|
+---Example_01
| | Example_01.pro
| | Example_01.pro.user
| | main.cpp
| |
| +---GUI
| | GLWidget.cpp
| | GLWidget.h
| | MainWindow.cpp
| | MainWindow.h
| | MainWindow.ui
| | SideWidget.cpp
| | SideWidget.h
| | SideWidget.ui
| |
| +---Spaces
| SpecializedECSpaces.cpp
| SpecializedECSpaces.h
|
+---Example_02
| | Example_02.pro
| | main.cpp
| |
| +---GUI
| | GLWidget.cpp
| | GLWidget.h
| | MainWindow.cpp
| | MainWindow.h
| | MainWindow.ui
| | SideWidget.cpp
| | SideWidget.h
| | SideWidget.ui
| |
| +---Spaces
| SpecializedECSpaces.cpp
| SpecializedECSpaces.h
|
+---Example_03
| | Example_03.pro
| | main.cpp
| |
| +---GUI
| | GLWidget.cpp
| | GLWidget.h
| | MainWindow.cpp
| | MainWindow.h
| | MainWindow.ui
| | SideWidget.cpp
| | SideWidget.h
| | SideWidget.ui
| |
| +---Spaces
| SpecializedECSpaces.cpp
| SpecializedECSpaces.h
|
+---Example_04
| | Example_04.pro
| | main.cpp
| |
| +---GUI
| | GLWidget.cpp
| | GLWidget.h
| | MainWindow.cpp
| | MainWindow.h
| | MainWindow.ui
| | SideWidget.cpp
| | SideWidget.h
| | SideWidget.ui
| |
| +---Spaces
| SpecializedECSpaces.cpp
| SpecializedECSpaces.h
|
+---Example_05
| | Example_05.pro
| | main.cpp
| |
| +---GUI
| | GLWidget.cpp
| | GLWidget.h
| | MainWindow.cpp
| | MainWindow.h
| | MainWindow.ui
| | SideWidget.cpp
| | SideWidget.h
| | SideWidget.ui
| |
| +---Spaces
| SpecializedECSpaces.cpp
| SpecializedECSpaces.h
|
+---png
Example_01.png
Example_02.png
Example_03.png
Example_04_a.png
Example_04_b.png
Example_04_c.png
Example_04_d.png
Example_04_e.png
Example_04_f.png
Example_05.png
We assume that the user has a multi-core CPU and a graphics adapter managed by a driver that supports at least OpenGL 3.0. In order to render the geometry, we use vertex buffer and shader objects through the OpenGL Extension Wrangler Library (GLEW), and for multi-threading we rely on a C++ compiler that supports at least OpenMP 2.0 and which is compatible at least with the standard C++ 11. Please verify that your compiler is compatible with C++ 11, otherwise the compilation of the source files will fail.
Apart from GLEW no other external dependencies are used. The source (for all platforms) and the zipped Windows-binaries of the library GLEW can be downloaded from this link. Moreover, the following three subsections also provide terminal commands for installing GLEW under different platforms.
In case of Ubuntu, one can install the library GLEW either by following the instructions of this link, or simply by calling (as a super user) the next commands in a terminal:
sudo apt update
sudo apt install libglew-dev
In case of success, the release build of the library GLEW and its header file will be installed to the folders /usr/lib and /usr/include/GL, respectively.
On Mac Os X 10.10+ one can install the library GLEW by running (as a super user) the following commands in a terminal:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install glew
The first of these two commands installs the package manager Homebrew, while the second one installs the library GLEW by means of Homebrew. If your system already has Homebrew, skip the first command.
In case of success, the release build of the library GLEW and its header file will be installed to the folders and
/usr/local/Cellar/glew/x.y.z/lib
and
/usr/local/Cellar/glew/x.y.z/include/GL,
respectively, where x.y.z denotes the version number of the installed library GLEW. Later these paths will be important, e.g., they should appear (with the correct version number) in the Macintosh platform-related scope mac{...} of any Qt-based project (*.pro) file:
mac {
message("Macintosh platform...")
INCLUDEPATH += "/usr/local/Cellar/glew/x.y.z/include/"
LIBS += -L"/usr/local/Cellar/glew/x.y.z/lib/" -lGLEW
...
}
Note that, the version number x.y.z of the library GLEW will change over the years.
This link also provides the pre-compiled 32- and 64-bit release binaries glew32.{lib|dll} together with their common include file (glew.h) in a zipped file that is named similarly to glew-x.y.z-win32.zip, where x.y.z denotes the current version number of the library GLEW. We assume that the user has downloaded, extracted and copied the previously mentioned files as follows:
glew-x.y.z/bin/Release/Win32/glew32.dll --> 992/00_Dependencies/Lib/GL/x86/glew32.dll
glew-x.y.z/bin/Release/x64/glew32.dll --> 992/00_Dependencies/Lib/GL/x64/glew32.dll
glew-x.y.z/lib/Release/Win32/glew32.lib --> 992/00_Dependencies/Lib/GL/x86/glew32.lib
glew-x.y.z/lib/Release/x64/glew32.lib --> 992/00_Dependencies/Lib/GL/x64/glew32.lib
glew-x.y.z/include/GL/glew.h --> 992/00_Dependencies/Include/GL/glew.h
In order to compile, build and install the proposed function library (CAGD), we provide two possibilities. The first of these is based on the usage of command prompts and traditional make-files, while the other one relies on a (configurable) Qt-based project. The following three subsections detail the first possibility on different platforms. The second possibility assumes that one tries to load/compile/build the Qt-project 992/01_Library/cagd/cagd.pro, by installing/using the Qt Software Development Kit 5.4+ (Qt SDK). Although the proposed library does not depend on the internal libraries of the Qt SDK, the five examples provided in the folder 992/03_Examples/ are based on Qt-widgets in order to handle the graphical user interface (GUI) of the cross-platform test applications. At the end of this webpage, one can also find instructions for both the installation of the Qt SDK and for the testing of the provided examples.
One should open a terminal and navigate into the folder 992/01_Library, then to call the commands:
make -f Makefile.Linux.Debug
make -f Makefile.Linux.Release
sudo make -f Makefile.Linux.Debug install
sudo make -f Makefile.Linux.Release install
In case of success, these commands will install the obtained debug and release builds of the function library and the contents of their common include folder CAGD to the directories
/usr/local/bin
and
/usr/local/include/CAGD,
respectively. (Both in debug and release modes, all Qt-based test applications assume the latter library and include paths.)
The 32- and 64-bit debug builds will be named as libcagd32d.a and libcagd64d.a, respectively. The 32- and 64-bit release builds will be named as libcagd32.a and libcagd64.a, respectively.
If one modifies the variables PREFIX and INSTALL_DESTINATION_DIR of the makefiles specified above, one can also install these libraries and include files into different folders, but in this case one has to manually modify the variables INCLUDEPATH and LIBS of the .pro files of all examples as well. (The test applications can be found in the folder 992/03_Examples.)
If the debug/release libraries and their common include files are not required anymore, one can also uninstall them, by invoking the commands:
sudo make -f Makefile.Linux.Debug uninstall
sudo make -f Makefile.Linux.Release uninstall
It may happen that you need to update the compiler gcc. This can be done by means of the package manager Homebrew. If you do not already have Homebrew, you can install it by calling (as a super user) the command
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
in a terminal. After this, you can update your compiler by running the command
brew install gcc
as a super user.
In order to avoid conflicts with already existing compilers, Homebrew usually installs the updated compiler to the path
/usr/local/opt/gcc/bin/gcc-x
where x denotes the newly downloaded version number of gcc (e.g., when this tutorial was created, the number 9 appeared instead of the letter x). If you have updated the compiler gcc, then you will also need to edit the value of the variable CXX in both make-files Makefile.Mac.Debug and Makefile.Mac.Release appearing in the current folder. By default, the variable CXX is set to gcc (i.e., to your old compiler) in these files. You will have to change the line
CXX = gcc
to
CXX = /usr/local/opt/gcc/bin/gcc-x
in both of these files, where the letter x depends on the version number of the new compiler gcc.
After this, one should open a terminal and navigate into the folder 992/01_Library and call the commands:
make -f Makefile.Mac.Debug
make -f Makefile.Mac.Release
sudo make -f Makefile.Mac.Debug install
sudo make -f Makefile.Mac.Release install
In case of success, these commands will install the obtained debug and release builds of the function library and the contents of their common include folder CAGD to the directories
/usr/local/bin
and
/usr/local/include/CAGD,
respectively. (Both in debug and release modes, all Qt-based test applications assume the latter library and include paths.)
The 32- and 64-bit debug builds will be named as libcagd32d.a and libcagd64d.a, respectively. The 32- and 64-bit release builds will be named as libcagd32.a and libcagd64.a, respectively.
If one modifies the variables PREFIX and INSTALL_DESTINATION_DIR of the makefiles specified above, one can also install these libraries and include files into different folders, but in this case one has to manually modify the variables INCLUDEPATH and LIBS of the .pro files of all examples as well. (The test applications can be found in the folder 992/03_Examples.)
If the debug/release libraries and their common include files are not required anymore, one can also uninstall them, by invoking the commands:
sudo make -f Makefile.Mac.Debug uninstall
sudo make -f Makefile.Mac.Release uninstall
We assume that the user:
has already installed the community edition of the Microsoft Visual Studio C++ (release year 2015 or above);
has launched both the x86 and x64 Native Tools Command Prompts for Visual Studio and has navigated in both command prompts into the folder 992/01_Library (if you do not know where these command prompts are on your system, the links
https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019
https://docs.microsoft.com/en-us/dotnet/framework/tools/developer-command-prompt-for-vs
may be helpful).
In order to obtain both the debug and release builds of the 32-bit variant of the proposed function library, one should call the commands
nmake -f Makefile.Windows.Debug.x86
nmake -f Makefile.Windows.Release.x86
in the x86 Native Tools Command Prompt for Visual Studio.
In order to obtain both the debug and release builds of the 64-bit variant of the proposed function library, one should call the commands
nmake -f Makefile.Windows.Debug.x64
nmake -f Makefile.Windows.Release.x64
in the x64 Native Tools Command Prompt for Visual Studio.
In case of success:
the 32- and 64-bit debug builds will be named as cagd32d.lib and cagd64d.lib, respectively;
the 32- and 64-bit release builds will be named as cagd32.lib and cagd64.lib, respectively.
These files will be copied to the folder 992/00_Dependencies/Lib/CAGD. The include folder CAGD will be copied into the directory 992/00_Dependencies/Include.
On Windows platforms, all examples in 992/03_Examples rely on the previously mentioned two directories.
Naturally, you can copy/move these libraries and include files into different folders, but in this case one has to manually modify the variables INCLUDEPATH and LIBS of the .pro files of all examples as well.
The proposed function library assumes that each translation-invariant EC space Sn ∈ Cⁿ([α, β]; ℝ) of dimension n + 1 that has to be constructed fulfills the following conditions:
it can be identified with the solution space of a constant-coefficient homogeneous linear differential equation
γn+1 ⋅ v(n+1)(u) + γn ⋅ v(n)(u) + ... + γ1 ⋅ v(1)(u) + γ0 ⋅ v(0)(u) = 0, γi ∈ ℝ, u ∈ [α, β]
of order n + 1;
it comprises the constants (i.e., 1 ∈ Sn, or equivalently, the number z = 0 is at least a first-order zero of the characteristic polynomial
p(z) = γn+1 ⋅ zn+1 + γn ⋅ zn + ... + γ1 ⋅ z + γ0 , z ∈ ℂ
that is associated with the previously mentioned differential equation);
the derivative DSn = {f (1) : f ∈ Sn} of the EC space Sn is also EC on the definition domain [α, β].
These conditions have to be ensured by the user of the proposed function library, otherwise the functionalities of the library will generate theoretically unexpected results, since in such ill-parametrized cases the given space will not provide shape-preserving representations for curve- and surface-modeling.
Remark. Since the proposed function library is designed for constant-comprising translation-invariant solution spaces of constant-coefficient homogeneous linear differential equations, by means of [Carnicer, Mainer, Peña, 2004, Proposition 3.1/(iii), Theorems 2.4, and Corollary 4.1] there always exist sufficiently small intervals for which the considered vector spaces of functions are EC and possess unique normalized B-basis.
Naturally, there are some types of translation-invariant EC spaces for which we know the permissible values of the interval length β – α ∈ (0, ℓ(DSn)), where ℓ(DSn) denotes the critical length of the derivative space DSn, i.e., the supremum of the lengths of the intervals on which the derivative space DSn is also EC. Since there are infinitely many translation-invariant EC spaces with a vast possibility of inner structure, in general we cannot give a recipe for:
the theoretical value of the critical length ℓ(DSn) (in general, the exact value of ℓ(DSn) also depends on the real and imaginary parts of the zeros of the characteristic polynomial);
the critical maximal dimension dim Sn = n + 1 for which the outputs of the proposed algorithms are numerically stable.
Remark. In order to numerically approximate the critical length ℓ(DSn), we propose to use the numerical procedures published in [Beccari, Casciola, Mazure, 2020]. Since the proposed function library was written before the appearance of this article, these procedures were not incorporated into the function library.
Therefore, the proposed function library always assumes that the permissible values of α, β and n were already determined theoretically/numerically/empirically beforehand by the user. Moreover, whenever it is possible, the verification of these conditions should be incorporated in the constructor of the class that describes the EC space Sn ∈ Cⁿ([α, β]; ℝ) that has to be constructed.
The attached file 992/02_User_manual/User_manual.pdf consists of three chapters:
the first one provides a brief theoretical introduction by repeating some parts of the article [Róth, 2019] (the proofs of the theoretical results are deliberately omitted);
the entire implementation of the proposed function library is explained in the exhaustively commented listings of the second chapter, by using cross references to the theoretical parts detailed in the first chapter;
the last chapter provides several examples for creating and interactively manipulating EC space objects, B-curves and B-surfaces (these examples are formulated in a general context, while their special Qt-based implementations can be found in the folder 992/03_Examples).
The last/third chapter of the user manual provides examples for:
defining and using classes that represent pure {polynomial|trigonometric|hyperbolic} and mixed exponential-trigonometric or algebraic-{trigonometric|hyperbolic|exponential-trigonometric} translation-invariant EC spaces; these classes can be used to evaluate, differentiate and render both the ordinary basis and the normalized B-basis of the underlying translation-invariant EC-spaces (for more details study Sections 3.1–3.3);
different shader programs that can be used to render basis functions, generic curve objects, triangle meshes, B-curves and B-surfaces; for convenience the function library provides shader programs for simple (flat) color shading, for two-sided per pixel lighting (that is able to handle user-defined directional, point and spotlights with uniform front and back materials) and for reflection lines that are combined with two-sided per pixel lighting (for more details study Sections 3.2–3.5);
generating B-curves/surfaces and performing order elevation and subdivision operations on them (for more details study Sections 3.4–3.5).
Remark. Naturally, the proposed function library also provides data structures (handling different types of coordinates, colors, materials, shader programs, generic curves, abstract linear combinations, triangle meshes, abstract tensor product surfaces, either rectangular or triangular matrix templates, real matrices, transformations, decomposition algorithms for square real matrices, different types of smart pointers) that can be used for general programming purposes.
Example_01. Illustrates the creation of different types of EC space objects, differentiates and renders the unique normalized B-bases of the constructed spaces.
Example_02. Generates different types of B-curves, and performs order elevation division on them.
Example_03. Illustrates the B-representation (i.e., the control point exact description) of several arcs of a logarithmic spiral given in traditional parametric form. Note that this exponential-trigonometric curve can be approximated but cannot be exactly described by means of the standard (rational) Bézier and non-uniform B-spline curve modeling tools.
Example_04. Randomly generates a B-surface by using different types of normalized B-bases in directions u and v, then performs order elevation and subdivision on it.
Example_05. Illustrates the B-representation (i.e., the control point based exact description) of several patches of an exponential-trigonometric transcendental surface given in traditional parametric form that can be approximated but cannot be exactly represented by the standard (rational) Bézier and non-uniform B-spline surface modeling tools.
Although the proposed library does not depend on the internal libraries of the Qt Software Development Kit (Qt SDK), the five examples provided in the folder 992/03_Examples are based on Qt-widgets in order to handle the graphical user interface (GUI) of the cross-platform test applications. The essential parts of the source codes of these test applications are also described in Chapter 3 of the User manual without assuming Qt-based software development.
Remark. The folder 992/01_Library/cagd contains the Qt-based project file cagd.pro that can also be used to compile and build both the 32- and 64-bit variants of the proposed static function library. This project file does not use Qt-specific (internal) libraries, i.e., the Qt Creator is only used as an Integrated Development Environment (IDE) that can be installed on Unix/Linux, Macintosh and Windows.
In order to test the Qt-based implementations of the provided examples, at first one has to install the community edition of the Qt SDK 5.4+, then to load, configure (by using either 64- or 32-bit compilers) and run the project files:
992/03_Examples/Example_01/Example_01.pro
992/03_Examples/Example_02/Example_02.pro
992/03_Examples/Example_03/Example_03.pro
992/03_Examples/Example_04/Example_04.pro
992/03_Examples/Example_05/Example_05.pro
The following collapsible panels provide unified installation instructions for the Qt SDK and the GLEW library under different platforms. (Naturally, if you have already installed the GLEW library, you do not have to reinstall it.)
