 |
GCGlib
0.04.228
GCG Graphics Engine
|
|
GCGlib
0.04.228
GCG Graphics Engine
|
GCGlib cross-platform library concentrates all methods and algorithms developed by GCG researchers and students since 2007. It is a software repository intended to be used in all GCG projects and researches. Our library is also applied in the development of technological products for commercial and industrial purposes.
The library provides robust and reliable code for Linux and Microsoft Windows systems. For Linux, a Shared Object library is provided and runs in 32 bits and 64 bits platforms. Under Microsoft Windows, the GCGlib is provided as a DLL (Dynamic Linked Library) for MinGW using GNU C/C++. DLL libraries with 32 bits and 64 bits for Microsoft Studio Visual C/C++ are also available.
Most implemented algorithms are versions of well-known, public domain, methods. As GCGlib is being developed, algorithms can be adapted and enhanced to support our projects needs. Theoretical and technical knowledge in computer graphics, signal processing and computer vision is accumulated along this process. GCGlib includes functions and classes for:
GCGlib is deployed in a single library, along with the header gcg.h for developments, as a Shared Object (.so) in Linux and Dynamic Linked Library (.dll) in Windows. Potential users or developers are encouraged to download (www.gcg.ufjf.br) a package or installer containing GCGlib binaries and header, its examples and, for Windows systems, its dependencies. Packages for 32 bits and 64 bits are available for Windows (MSVC and MinGW versions) and Ubuntu Linux distributions.
In Windows, the dynamic library is a link free object. This means that no library must be linked to your project in order to satisfy GCGlib dependencies. In runtime, however, GCGlib depends upon several DLLs that must be installed in your system. All dependencies are provided to ease the task of GCGlib building. Some of them are automatically compiled along with GCGlib in Windows: jpeg library, glui (only for some examples). During GCGlib building, the CMake tool searches for dependencies like pthread, opengl, glu, and freeglut (only for some examples). If pthread or freeglut are not found, a binary copy of them are automatically copied to the GCGlib folder. If using MSVC compiler, it is mandatory to have a Windows SDK compatible with your platform installed. In summary, you must have installed (or put in the same directory of GCGlib) glu32.dll, pthreadGC2.dll (MinGW projects) or pthreadVC2.dll (Visual C++ projects). Other DLLs (opengl32.dll and glu32.dll for instance) are needed but they are usually distributed by default in Windows. Furthermore, for MinGW compilation, a specially designed vapiwin.dll is provided for video and camera interface.
The use of GCGlib in Linux is straightforward since all dependencies are easily obtained from package managers of most distributions. Most of them are installed by default when using GNU compilers (librt for example) or common applications. Make sure the proper development packages for glu, opengl and jpeg are available. For building and using one of the GCGlib examples, the freeglut and glui libraries are needed. Since Shared Objects are libraries that are linked upon execution, all you need is to keep dependencies updated.
Versions of GCGlib have the form: major.minor.revision
Original Version New Version Compatible? 2.20.5 2.20.9 Yes Compatibility across revision/patch versions is guaranteed. 2.20.5 2.20.1 Yes Compatibility across revision/patch versions is guaranteed. 2.20.5 2.21.2 Possibly Compatibility with different minor versions is not guaranteed but is probable. 2.20.5 3.0.0 No Compatibility with different major versions is not guaranteed.
While some of the cells say "no", it is possible that the versions may be compatible, depending upon the particular functionalities used by the application.
Revision numbers are sequential. But the evolution of major and minor depends on how many or how much changes have occurred.
GCGlib was developed using CMake tool to automate building, installation and packaging. These steps are handled without any supervision provided that all needed software and GCGlib dependencies are correctly configured.
The first step is to install CMake in your platform. After that, run
cmake --help
to check the available generators. Install the C/C++ compiler or/and the IDE of your preference that matches one of the available generators. Some GCGlib features, like video capture for instance, will only work in Windows and Unix based systems. CMake will automatically find all libraries and software needed to build, install and pack GCGlib features: binaries, documentation and examples.
For correct version handling during compilation, you will need GIT client installed. This distributed version control tool retrieves the tags and logs from the GCGlib repository. CMake will search for GIT and, if it is not installed, the correct version numbers will not be inserted in the library, documentation and packages. We strongly recommend to install GIT and get the GCGlib sources from our online repository (see instructions below). Installing incorrect library versions can potentially lead to problems and instabilities.
In any platform, you should install Doxygen to automatically generate documentation. If Doxygen tool is not found while building, the HTML documentation quietly will not be generated.
In Windows, GCGlib can be compiled for MinGW and Visual C++. The Windows SDK is needed for MSVC compilers: install the version that best matches your platform and your MSVC version. Make sure that OpenGL and GLU development files are available (headers and linking libraries) in the expected folders (include and lib) of your compiler or SDK. You should install jpeglib and pthread for your compiler/platform but it is not mandatory. If jpeglib is not found, it is compiled (version 6b sources are available if needed) and linked to GCGlib quietly. Also, a generic version of pthread headers, libraries and binaries are provided with GCGlib sources. Its configuration is handled automatically by CMake. If you intend to build the examples, you also should install GLUI and GLUT. This is also not mandatory. The libglui is compiled if any example that includes it as dependency is built (i.e. its sources are available if needed) and the headers, libraries and binaries of freeglut are automatically included. If one of your purposes it to generate a GCGlib installer, you will need to install WIX (recommended) or NSIS software. They are naturally integrated to the CPack tool of CMake.
In Linux, all GCGlib dependencies are open-source and available in most distributions. You must install g++ and build-essential packages in most systems. Install the compatible libraries and development packages of: jpeg (libjpeg-dev), pthread (libpthread-stubs0-dev), glut (freeglut3, freeglut3-dev), glui (libglui-dev), opengl (binutils-gold, libglew-dev, mesa-common-dev) and glu (libglu1-mesa). Note that the package names, versions and dependencies vary among distributions. If you need to build using a specific compiler (MinGW 32 bits under a x86_64 system, for instance), check if the there are compatible packages for the target platform.
GCGlib GIT repository is hosted at https://www.gcg.ufjf.br/git/gcglib. If you are using the command line for cloning, GIT will launch the default SSH password dialog (normally a graphical tool) for user authentication. To use the terminal to enter the password, first set SSH_ASKPASS empty as follows
export SSH_ASKPASS=
The GCG website currently is not certified since it imply in costs. We however need encryption for obvious security reasons in our services, including GIT, which needs password transmissions. Trying to clone a repository directly will result in an verification error by the underlying OpenSSL. In order to use SSL protocol with a security certificate not issued by a "Certification Authority", execute the following command to disable the global SSL verification:
export GIT_SSL_NO_VERIFY=true
Everything is ready to download the head version or, more specifically for GIT, to clone the repository with:
git clone https://www.gcg.ufjf.br/git/gcglib
or
git clone https://user_name@www.gcg.ufjf.br/git/gcglib
With the repository cloned, go inside one of its folders and execute the following command to disable SSL verification permanently for it:
git config http.sslVerify false
This command allows push and pull operations over https protocol. GIT will use the SSL protocol for encrypted communication regardless the server certificate is trusted by "someone". Note that "Certification Authorities" have the role of making sure that someone is really who he says. GCG is not intended to get any user information except its username and password previously registered in our server. Thus, this is a safe site.
CMake tool generates targets in a two step process. The first one is to configure the generation tools. During configuration, the CMake cache is populated and makefiles (or IDE projects) are created by the execution of the scripts called CMakeLists.txt provided in the source tree. The user can change default options programmed into CMakeLists.txt scripts to control the makefile generation. The most important options for GCGlib are:
CMake generates all makefiles, binaries and extra sources in the current directory. Consequently, you must execute CMake inside an empty folder (or previously used to configure with the same options). A common approach is to create a folder called "build" inside gcglib source folder (containing the topmost CMakeLists.txt). Execute the appropriate configuration command inside "gcglib/build/" folder passing the desired generator with the parameter -G "Generator Name". See CMake documentation for further explanations.
Some configuration examples varying the compiler name, the IDE project, 32 bits or 64 bits compiler, optimization or debug information, the destination folder for "install" target:
Build example (after configuration):
Install example (after configuration):
or (after building)
Create package (after configuration):
or (after building)
Copyright © 2007-2016 Group for Computer Graphics, Image and Vision - UFJF - Brazil.
Permission is hereby granted, free of charge, to any researcher, student, professor or collaborator, provided that is officially affiliated or in cooperation with the GCG, that obtain a copy of this software and associated documentation and example files (the "Software"), to deal in the Software for research or educational purposes except for commercial, industrial and other profit activity, without limitation to use, copy, modify and merge, subject to the following conditions:
GCGlib is based in part on the following works, standard algorithms, publications, softwares and methods, whose authorship, copyrights and trademarks are exclusively owned by their respective authors and/or companies:
1.8.13