Home

PLEASE NOTE

Documentation on the SourceForge web page is outdated and only valid up to and including release 5. Please visit the new project web page for the most recent information.

Description

COCOLIB is a C++/CUDA library for variational image analysis and continuous global optimization, focusing on the minimization of functionals of the type

E(u) = J(u) + F(u)

where u is an image (i.e. vector-valued function on an interval), J is a convex and closed regularizer, and F a closed and usually also convex data term.

Since release 5, COCOLIB also contains a growing toolkit for light field analysis based on variational methods, which implements many methods from our research papers and has ready-to-use scripts for benchmarking on the HCI light field data base. For further information, see the light field suite documentation.

The complete overview can be found on the project home page.

Requirements and support

All algorithms are implemented in C++ using CUDA. They have been tested on Ubuntu 13.04 and above, Fedora Core 19 and Mac OS X, but should compile and run on many other Debian flavors as well. The code is provided as a service to the image processing community and "as is", without any support beyond the documentation presented here. If you run into a problem, please ask in the forum or via e-Mail for help. If I find the time, I will try to be of assistance.

You will need a CUDA capable graphics card in your system, which supports at least revision 1.3.

The following pre-requisites can usually be installed via the package management system:

• Latest nVidia driver and CUDA toolkit
• Qt library (with development support, Ubuntu package 'libqt4-dev')
• GNU scientific library (with development support, Ubuntu package 'libgsl0-dev')
• For better segmentation data terms, you need the ANN "approximate nearest neighbour" library (Ubuntu: 'libann-dev'). If you don't have it, support for it will be disabled by the configure script.

See below for further instructions and install scripts for Ubuntu.

Downloading the library

Current release tarball:

Note: since it produces an about 30% smaller file than bzip2, the tarball was compressed with lzma2. Please untar using

    tar -xvJf cocolib-release-5.tar.xz

Latest development version via subversion:

svn checkout svn://svn.code.sf.net/p/cocolib/code/trunk cocolib-dev

Building the library and examples

• Download and unpack the desired release of the library
• Change to library base directory
• Make sure pre-requisites are installed (see below)

• To test for the pre-requisites and create the makefile, run

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ./configure.sh
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

• Then, to build the library, type

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  make
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

If everything works fine, the following stuff will be built:

• the library libcocolib.a in the folder cocolib,
• the command line tool coco-ip in the folder examples,
• the command line tool lightfields in the folder lightfields,
• some auxiliary stuff in the folder tools.

In case there were errors, please check out the common build problems here, before reporting the problem on the forum.

Installing pre-requisites

• For Ubuntu-based systems, there are install scripts for some of the pre-requisites in the library base directory.

• In order to install the newest nVidia graphics card driver, use

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ./install_nvidia_driver_ubuntu.sh
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

• In order to install all dependencies available as apt-packages, use

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ./install_dependencies_ubuntu.sh
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

• Note: With release 5, the library does no longer depend on cuDPP, which has not received upgrades for a while does not seem to compile correctly anymore.

Testing the library

In order to test whether the library was built successfully, run the test script:

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    cd examples
    ./test_cocolib_quick.sh
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is the short test script, which only checks fast algorithms (should take around 1-2 minutes). To run all tests (15 minutes), run

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    cd examples
    ./test_cocolib.sh
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The results are automatically compared to reference results provided with the library. Note that there might be slight differences due to rounding errors and different compiler optimizations - if results differ, check if yours looks reasonable close and everything is probably ok.

Getting started with the tool: running the examples

In order to experiment with the command line tool,

• change to the "examples" subdirectory.

• View an example configuration file with

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  cat configs/tv_denoising
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

• Run the command line tool using the example configuration via

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ./coco-ip -config configs/tv_denoising
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

• You can override parameters from the configuration file by specifying them after the filename in the command line

  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ./coco-ip -config configs/tv_denoising -lambda 10.0
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

Running the above example should produce output in the subdirectory "out/tv/denoising/".

For a complete list of the command line options and further examples, please refer on the documentation of the command line tool.

Getting started with the code: library documentation

A brief outline of the library framework is available here, but other than that you will have to look at the code.

Disclaimer

The library is research code. In particular, it has not been tested except for a certain small range of use cases, and might fail spectacularly if provided with unexpected parameters (including completely crashing your system). Do not use in production environments unless you add lots of safeguards, in which case I'm happy if you can contribute back to the repository (contact me for access).