Creating an Imalab Module - Unix Commands in Detail

This page further explains Ravi module generation. All examples refer to directories in the directory MyImalab/examples.

A basic module: modhisto

Example: directory Histo with a histogram computation module.

Source Code

The source code is in the files histo.h, histo.c; the principal functions here compute a histogram, represented as a 2D array, from a color image, or a region in an image. These functions have numerous parameters. theb File histo.scm contains additional code, written in Scheme, to simplify interactive experimentation with the C++ functions; for instance, the function click-histo() makes you mouse-click to define an image rectangle, and displays the histogram as a 2D surface with geomview.

Module generation steps

From the source files histo.h, histo.c we want to generate the files modhisto.so and modhisto.x.scm. This is done in the three classical steps:

1. generate the module file
2. compile the module file
3. link-edit the module file

As our source code uses several classes defined in the libvision library, we have to indicate, at each step, where this information is to be found.

Basic commands

The three steps are carried out by the following Unix commands:

ravi -mod r-ig -I /home/naiad/lux/Soft2/include -r modBitmap -r modArray -r modaaregion -i histob.c -o modhistob.cc histob.h
g++ -c  -O4 -I/home/naiad/lux/Soft2/include/Ravi -I/home/naiad/lux/Soft2/include -o modhistob.o
modhistob.cc
g++ -shared -L/home/naiad/lux/Soft2/lib/Vision -lbitmap -o modhistob.so modhistob.o

Explaining the commands

1 Generation is carried out callling the ravi module r-ig (ravi interface generator):

ravi -mod r-ig -I /home/naiad/lux/Soft2/include -r modBitmap -r modArray -r modaaregion -i histob.c -o modhistob.cc histob.h

• -I /home/naiad/lux/Soft2/include : similar to the -I parameter for gcc - the space after -I is mandatory!
• -r modBitmap : The module modBitmap is required for this module. From this module, the generator extracts information on how the Bitmap classes (image classes) are handled inside the ravi system (i.e. using reference counters).
• -i histob.c : the generated file must include the source file ... the source code must be defined somewhere! If the source code is not included in this fashion, then it has been compiled in a library (see later on this page).
• histob.h : The header file is the "real input" to the interface generator.

2 Compilation with g++

g++ -c  -O4 -I/home/naiad/lux/Soft2/include/Ravi -I/home/naiad/lux/Soft2/include -o modhistob.o
modhistob.cc

• -c : compile only (no linking)
• -O4 : optimization level
• -I/home/naiad/lux/Soft2/include/Ravi to find Ravi specific includes
• -I/home/naiad/lux/Soft2/include to find the libVision includes

3 Linking with g++

g++ -shared -L/home/naiad/lux/Soft2/lib/Vision -lbitmap -o modhistob.so modhistob.o

• -shared : create a shared object file
• -L/home/naiad/lux/Soft2/lib/Vision : where to search for libraries
• -lbitmap Library used for linking

Elementary Makefile

The ravitool command provides installation dependent parameters for the three steps, so we can write the following parameterless Makefile:

modhisto: histo.h histo.c
	  ravitool --generate -I /home/naiad/lux/Soft2/include -r modBitmap -r modArray -r modaaregion -i histob.c -o modhistob.cc histob.h
	  ravitool --compile -I/home/naiad/lux/Soft2/include -o modhistob.o
	  ravitool --link -L/home/naiad/lux/Soft2/lib/Vision -lbitmap -o modhistob.so modhistob.o

Parameterized portable Makefile for simple module

In the above example, there are two parameters specific to my personal implementation. One should define these using a makefile-variable, so you can easily adapt the Makefile on your machine. The whereabouts of the libVision codes are given by the libvision-config command.

VISIONINCDIR=`libvision-config --vision-incdir`
VISIONLIBDIR=`libvision-config --vision-libdir`
modhisto: histo.h histo.c
	  ravitool --generate -I {VISIONINCDIR} -r modBitmap -r modArray -r modaaregion -i histob.c -o modhistob.cc histob.h
	  ravitool --compile -I{VISIONINCDIR} -o modhistob.o
	  ravitool --link -L{VISIONLIBDIR} -lbitmap -o modhistob.so modhistob.o

Fully parameterized Makefile

The Makefile commands can entirely be generated from very few parameters:

# TARGET_MOD name of target module
TARGET_MOD = modcouleur
# header files (typical suffix: .h or .hh) to be interfaced with the module
HEADERS = couleur.hh  Traitement-couleur.hh
# other parameters for generation (-R -r -u etc.)
RIG_PARMS = -r modaaregion -r modCommon -r modBitmap  -r modArray
# library string for module
MODLIBS = -L. -lcouleur

Makefile for Library module

Installing: Directory Organization