Step one : drawing a simple object with libvol

CC=g++

• The vol library has been tested only with g++. It compiles with any version since 2.95. However, there should not have problems with any other C++ compiler that's not too old.

LIB=-lm -L/path/to/libvol/lib -lvol

• You have to link with vol library of course, and with the math lib because the vol library needs it. The vol library that will be used by default on many systems is a dynamic library (.so). You must include /path/to/libvol in your LD_LIBRARY_PATH environment variable if you want te be able to run your executable. Or, you use the -static option of gcc (or equivalent option of your C++ compiler) in order to link with the static version of libvol, but your executable will be bigger.
• The -L/path/to/libvol/lib option is not needed if the vol library has been installed in a directory where the compiler looks for libs, such as /lib or /usr/lib (in this case you also don't need to change your LD_LIBRARY_PATH)

INCLUDE=-I/path/to/libvol/include

• This is perhaps needed in order the C++ compiler can find the vol.h file.

• The end of your makefile may look like this :

hello-vol : hello-vol.o
	$(CC) -o hello-vol hello-vol.o $(LIB) 
hello-vol.o : hello-vol.cc
	$(CC) -c hello-vol.cc $(INCLUDE)

#include <vol.h>

#include <stdio.h>

int main() {

   Vol myvolume( 16, 16, 16, 0 );

• The vol library consists of one class called Vol.
• This code is the easiest way to define a Vol object. The first three arguments are the number of voxel you want in each dimension (X, Y and Z).
• The fourth argument is the value that will represent a transparent voxel. This is useful only for visualization of your work. Every voxel is transparent by default. This value (later called 'alpha') must be between 0 and 255. Every other value in [0, 255] will be a color. Higher is the value, "whiter" is the color.
• 

   printf( "Here are the bounds of my volume object :\n\
            X : [ %d, %d [,\n\
            Y : [ %d, %d [,\n\
            Z : [ %d, %d [.\n",
            myvolume.minX(), myvolume.maxX(),
            myvolume.minY(), myvolume.maxY(),
            myvolume.minZ(), myvolume.maxZ()
         );

• You may be surprised at first by what these lines print :

Here are the bounds of my volume object :
                        X : [ -8, 8 [,
                        Y : [ -8, 8 [,
                        Z : [ -8, 8 [.

• By default, the bounds of a volume object are centered in zero, for each dimension. It makes often the programmer's life easier because equations are less complex.
• At every time, you can know the bounds with the methods minX(), maxX(), minY(), maxY(), minZ() and maxZ() of the class Vol. You'll notice that max bounds are not included.

   // We want to color every voxel of coordinates (x, y, z) where x*y*z >= 0.
   for (int i = myvolume.minX(); i < myvolume.maxX(); ++i) {
      for (int j = myvolume.minY(); j < myvolume.maxY(); ++j) {
         for (int k = myvolume.minZ(); k < myvolume.maxZ(); ++k) {

• This is the easiest way to make a loop that do something for each voxel.

            if (i*j*k >= 0)                    if (i*j*k >= 0)
               myvolume( i, j, k ) = 100;            myvolume.set( i, j, k, 100 );

• To set a color to a voxel, juste use one of these syntax. There's no difference, it's only a matter of taste.
• To get the color of a voxel, there is also two syntax :

  • voxel v = myvolume( i, j, k );

  • voxel v = myvolume.get( i, j, k );

	 
	     }
      }
   }
  
   myvolume.dumpVol( "hello.vol" );

• This is how you can save you Vol object in a .vol file.

   return 0;
}

• Now you may want to visualize your work. To do this, you must first convert the .vol file for geomview.

[user@host ~]$ vol2geom hello