Tutorial

This short tutorial explains how to use libcp. Let's start off with a simple example. The "Hello World" of libcp, if you want ;-)
It basicly just converts a color image to a grayscaled image.

#include "<cp.h>"
#include "<imageio.h>"

using namespace LIBCP;

int main( int argc, char** argv )
{
   if( argc < 2 ){
      cerr << "Usage: " << argv[0] << " <image>" << endl;
      exit( -1 );
   }

   //load the image from disk, and create an Image object
   Image* source = ImageIO::loadImage( argv[1] ); //(A)
			
   //create an empty Image object, with the save size as the
   //source image, and a depth of 8bit
   Image* destination = Image::createImage( source->width(),
                                            source->height(),
                                            BaseImage::GRAY ); //(B)
                                            
   //convert the color input image to grayscale image													  
   int ret = Conversions::grayScale( destination, source ); //(C)
			
   if( ret != 0 ){
      cerr << "Could not grayscale the imgage: " << ret << endl;
      return -1;
   }
   else{
      ImageIO::saveImage( "gray.png", destination ); //(D)
   }
   return 0;
}

What happens here? on line (A) the given image is loaded from disk. By using the ImageIO module. If you don't have this module compiled into libcp, then you have to load the image in some other way. For example you could use the SDL_image library.
The ImageIO module creates an Image instance and returns a pointer to it.
On line (B) an empty image is created, which has the same widht and height as the input image. But has a depth of 1 byte. (specified with BaseImage::GRAY).
The conversion of the color image to the gray image is done on line (C). The source image is converted, and the output is saved to the destination image. If the return value is different from 0, the something went wrong. (we'll se later, what can go wrong. If this happens, then you probably tried to convert a non color image to grayscale, and this is not possible thou).
Finaly, the result is stored in a file called gray.png on line (D).

Now as it comes to compilation, it is best writing a Makefile as follows:

If you installed the library regularly like this:

$ ./configure --prefix=/usr
$ make
$ su
$ make install

then your Makefile will be some thing similar to

include /usr/share/libcp/platform-settings
all:
        g++ -o testlib testlib.cpp -L/usr/lib/libcp $(INCDIRS) -I/usr/include/libcp -lcp

The platform-settings file makes sure, that the compiled modules are found and linked correctly.

But if you installed VENAE into a different location:

$su
$make DESTDIR=/tmp install

then the Makefile can be written like this:

VENAE_DESTDIR=/tmp
include $(VENAE_DESTDIR)/usr/share/libcp/platform-settings
all:
        g++ -o testlib testlib.cpp -L$(VENAE_DESTDIR)/usr/lib/libcp $(INCDIRS) -I$(VENAE_DESTD
IR)/usr/include/libcp -L$(VENAE_DESTDIR)/usr/lib -lcp

Important: the variable must be called VENAE_DESTDIR, becuase the plattform-settings file that is included uses it as well.

You can use all the functions in exactely the same way. (Consistency in function calls was very important to us :-). If you want to make a wavelet transformation for example, you just do as follows:

#include "<cp.h>"
#include "<imageio.h>"

using namespace LIBCP;

int main( int argc, char** argv )
{
   if( argc < 2 ){
      cerr << "Usage: " << argv[0] << " <image>" << endl;
      exit( -1 );
   }

   //load the image from disk, and create an Image object
   Image* source = ImageIO::loadImage( argv[1] );
			
	Image* destination = Image::createImage( source->width(),
                                            source->height(),
                                            source->type() );
			
   //create two empty DoubleImage object, with the save size and type as the
   //input image.
   Image* wavelet1 = Image::createImage( source->width(),
                                         source->height(),
                                         source->type() ); // (A)
                                            
   Image* wavelet2 = Image::createImage( source->width(),
                                         source->height(),
                                         source->type() ); //(A)
                                            
                                            
   //Perform the Haar wavelet transformation
   int ret = Wavelet::fastWaveletTransformation( wavelet1, source ); //(B)
   
   //limit the coefficients to the top most 40x40 region
   ret += Wavelet::limitCoefficients( wavelet2, wavelet1, 40 ); //(C)
   
   //invert the wavelet tranformation
   ret += Wavelet::inverseFastWaveletTransformation( destination, wavelet2 ); //(D)
			
   if( ret != 0 ){
      cerr << "Could not wavelet transform the imgage: " << ret << endl;
      return -1;
   }
   else{
      ImageIO::saveImage( "gray.png", destination );
   }
   return 0;
}

Whee... Now it starts to get interesting, doesn't it?
This example just works with input images with equal width and height. Furthermore the width and height must be a value that is a power of two.
Step (A) creates two empty new DoubleImage instances. We need them, because the result of a wavelet transformation is an image with double values.
On line (B) we perform the wavelet transformation from the source image to the first double image. The limitCoefficients function on line (C) sets all pixels, except those in the upper left corner (40x40) to black. After the wavelet back transformation (D) we can save the image, again by using the ImageIO module.
Try this example and experiment with the limitCoefficients function with other values than 40.

The VENAE library gets really usefull, if you "connect" several functions together. This can be done by using the output image of one function as the input of another one.

back to top

Code Examples

Event thought VENAE is not an image library, you still can use it to convert file formats. In the current release just png and tiff image format are supportet. This example shows how to convert a png image to a tiff image.

#include "<cp.h>"
#include "<imageio.h>"

using namespace LIBCP;

int main( int argc, char** argv )
{
   if( argc < 2 ){
      cerr << "Usage: " << argv[0] << " <png - image> " << endl;
      exit( -1 );
   }

   //load the image from disk, and create an Image object
   if( !ImageIO::isPNG( argv[1] ) ){
   	cerr << "Usage: " << argv[0] << " <png - image>" << endl;
      exit( -1 );
   }
   
   Image* img = ImageIO::loadImage( argv[1] );
			
   if( ret != 0 ){
      cerr << "Could not grayscale the imgage: " << ret << endl;
      return -1;
   }
   else{
      ImageIO::saveImage( "output.tiff", img ); //(D)
   }
   return 0;
}

FAQ

Why do I have to provide a source and a destination image. Couldn't VENAE create the destination image?
Why is the image loading/saving swapped out from the "core" library?

Image creation

Why do I always have to provide a source and a destination image. Couldn't VENAE create the destination image?

Because like this, the user of the library is responsable of deleting all the created images. If VENAE would create those destination images by itself, the user could forget to delete it, because she did not create it by herself.

Image loading/saving

Why is the image loading/saving swapped out from the "core" library?

The "core" VENAE library called libcp is completely platform independent and strictely written in standart c++. Image loading and saving quickly gets annoying if you want to have it plattform independant. Therefore we decided to make this feature a module which then can be implemented seperatly for each platform.

Documentation

Tutorial

Code Examples

FAQ