Main Documentation

License

golib is put under the GNU General Public License. It can be found in the source directory in the file COPYING or at http://www.gnu.org/licenses/gpl

How to contact the author

You can contact me at golib at goschs dot de, with the usual replacements to form a valid email address.

What it is

Introduction

goLib is a C++ class library written by Christian Gosch. It contains some classes which have proven useful to me and has grown gradually. Some parts are better maintained and better written than others, that depends completely on how much I have used them.

I have also started to rename some things to use a bunch of namespaces (such as goMath), but that has only been done in a few places. If the library turns out to be used out there somewhere, I will rework the naming to be more consistent if that is what is needed.

Some of the things golib includes are:

• Arrays, strings, lists, hashtables, binary trees, heaps and so forth
• Multithreading wrappers (goThreadObject and related)
• A class for grabbing frames from a video4linux device (recent, goVideoCapture) including some small matlab mex modules to use v4l under matlab
• Classes for image processing, like container classes for 3D grid data which supports multi-channel data (source tree under src/signal), wrapper for writing and reading images (goFileIO) which rely on libdevil
• A file system interface in goFileIO to do some basic tasks like reading/writing ASCII files, checking for file existance, making directories, and so on.
• Some matrix and vector classes, and a sparse matrix class that acts mainly as a golib-side representation of sparse matrices for the Matlab interface
• A few numerical linear algebra routines, using BLAS/LAPACK/ATLAS, and some parts from the free TNT library (incorporated in the code and marked as such). They include the standard conjugate gradients method for sparse matrices, Eigenvalue and Singular Value decompositions, LU decomposition for solving linear systems, Eigenvalues of complex Hermitian matrices (the latter from SEISPACK).
• Some optimisation classes, see the "math and numerics" module.
• An interface to run gnuplot (goPlotter, goMultiPlotter) comfortably from C++, e.g. to plot a goVector
• A process interface for external program calls (goProcess)
• Some classes for factor graphs and message passing algorithms
• Function-like objects (often called "Functors" in the C++ world), see goFunctorBase, goFunction(), and goMemberFunction().
• A few networking classes (not well tested)
• ... it's slowly growing as I find use for more stuff :)

Check out the modules section to get another overview.

There are also additional libraries which use golib and are all included:

• A matlab interface wrapper
  to use matlab engines from C++ and swap data between golib and matlab (you need matlab for this, of course)
• A GUI base library using gtkmm, a (very good) C++ wrapper for gtk+
  • http://www.gtkmm.org
  You need version 2.4 of gtkmm for the GUI library.
• A small OpenGL helper library. You need OpenGL libraries to use this.
• A library helping to use embedded Python with the Swig-generated wrappers for golib classes (good for application scripting)

All additional libraries can be selected to be built from the ccmake interface.

Important notice: All of this was made because I had a use for it. If you want to make your own contributions, please see further below!
golib does contain some deprecated classes and functions, which will be removed in the future. I can not guarantee perfect suitability for any purpose. However, the signal related stuff seems to work quite fine (and surely still has bugs). Also, the classes in src/data seem to work ok (the basic arrays, fixed arrays, strings, lists, hashtables and goSignal3DBase-based classes are used by me a lot and therefore get more bug fixing than other classes like the network server or similar).

Scripting using SWiG

Python

I have tried Python for scripting and prototyping and it fits quite well into my programming habits and environment. Therefore, I will continue work on the Python interface for golib and neglect other interpreted languages. The Python module can be selected in the ccmake interface. The matlab and OpenGL modules also provide for a Python interface, which will automatically be built if you additionally select to build the Python and the Matlab interface in cmake/ccmake. You should also select the install directory for your Python modules in cmake/ccmake (the directory where the environment variable PYTHONPATH points to). You do need SWiG >= 1.3.29 and Python >= 2.4 for this. It might work with different versions, but was tried only with these.

• http://www.swig.org
• http://www.python.org

Guile Scheme (not recommended, discontinued)

Work on the scheme module is discontinued.

How to build and use

Prerequisites

You will definitely need:

• A recent cmake: http://www.cmake.org
• GNU compiler collection (gcc) with C++ – other compilers may work but were not tested.
• ATLAS generated CBLAS library: http://math-atlas.sourceforge.net/ for some matrix and vector operations
• ATLAS's LAPACK C implementation.
• An f2c translated or compatible LAPACK, like the reference implementation from www.netlib.org. (ATLAS's LAPACK only implements a subset of LAPACK). Many Linux distributors provide for this library, just as for ATLAS. You will also need the header files cblas.h and clapack.h from ATLAS.
  • video4linux header files and library You may replace ATLAS's CBLAS with another CBLAS implementation. In that case, you have to remove the ATLAS library from CMakeFiles.txt and only leave CBLAS. You will be on your own since I haven't tried that.

Optional, but very highly recommended:

• Developer's Image Library: http://openil.sourceforge.net
  You need this in order to load and store image files with goFileIO:: methods.

Completely optional:

• SWiG: http://www.swig.org
• Python 2.4: http://www.python.org These are both needed for the Python modules for golib.

You will always need the pthread library. It is available in many modern Unix environments. golib has in an early version also been compiled on Windows, and there are Windows implementations for the multithreading classes too. However, many other things will probably not compile anymore in Windows. Depending on the version you are compiling, libSDL might also be necessary (only for golib 0.2). You can get it at http://www.libsdl.org.

Package Dependencies in Ubuntu

This holds also possibly for other Debian based GNU/Linux distributions.

• Necessary:
  • libatlas-base-dev (lapack, blas, atlas)
  • libf2c2-dev (lapack)
  • libv4l-dev (for govideocapture.cpp)
• Recommended:
  • libdevil-dev
• GUI:
  • libgtkmm-2.4-dev
  • libgtkglext1-dev
• GL:
• Python:
  • python-dev

Environment variables

You need to set:

• MATLAB should point to your Matlab installation path, if you want to build the Matlab module. E.g.,
  setenv MATLAB /usr/opt/matlab
• PYTHONPATH after installing the Python language modules in order to use the modules from Python.

You may have to set:

• For some of the examples in the examples/ subdirectory, you may need to set the GOPATH environment variable to point to the base directory of golib.

LD_LIBRARY_PATH accordingly, depending on where you install golib

• LDFLAGS for any non standard library directories

• Add any non standard include directories to CPPFLAGS.
  If you don't know what the latter two are, you probably don't need them.

  To be able to run programs linked to golib, add the path to the shared library to your LD_LIBRARY_PATH environment variable. It would also be wise to set the environment variable GOPATH to the root path of the golib distribution, for example to /home/myUserName/golib. The example programs in the distribution need this variable to be set.

Compilation

Using CMake:

• If you don't have it, get it at http://www.cmake.org
• I recommend using the newest version, as of now that is 2.4
• In the main distribution directory, say, ~/golib, do
  • mkdir build
  • cd build
  • cmake .. or ccmake ..
  • --> select whichever modules you need, and configure/generate
  • Notice you may have to turn LINK_GFORTRAN to OFF in ccmake, depending on whether the linker complains about it.
  • make
  • make install

Examples

There are several little example programs in /examples. For more recent examples, there is a subdirectory for each example. Makefiles are provided but may need small modifications (like -L linker options). Just try them, if they don't work, you need to modify them. They are very small and easy to understand. For very old example programs, there should be a makefile called Makefile.NAME_OF_THE_EXAMPLE_PROGRAM. Use these makefiles to compile the examples. Be sure to have the environment variables mentioned above set correctly.

State of development

Development has started some time in 1996/97. Some of this is work in progress. Note that I am currently not working very much on golib, since I have a day job, a non-virtual life, and other projects which have precedence. The current version number is 0.5. Some significant changes are always imminent (;-)). Some of the basic features are not very well documented, but I will fix that in the future. Particularly, "how-to-use" sections are missing in the documentation, even though many classes are straight forward to use. I plan to write some introductory documentation which explains some concepts.
You should also be aware that this library was created over a long time in small parts, some of which I used more than others. The parts I used more are likely to be better documented, better maintained, and generally in better shape.
I remove bugs as soon as I find them. As I only used to use parts of the library very often, these parts will probably contain less bugs than others. If you find a bug or think you found a bug, please do not hesitate to send me an email to golib at goschs __ de.

How to get the source

A current version is not available online. If you are really interested in trying the library, please drop me a line.

Warranty

No warranty at all.