This site contains the C source code and the documentation for routines
incorporating the anisotropic nonlinear diffusion for flow visualization.
The gzipped tar file contains all header and source files, a Makefile, a
sample program, sample vectorfield-data and this html file.
Download here: flowVis.tar.gz (ca. 560KB)
 | Getting Started |
| Available Functions |
| The Parameterfile |
| File formats |
| The C Source Code |
Now that you have donwloaded the file flowVis.tar.gz you should unpack this file to some directory using the commands
gzip -d flowVis.tar.gz
tar -xvf flowVis.tar
This will extract all files you need. Next you should compile the package using the given makefile. The compile process will create a sample program which will visualize the sample vectorfield data contained in vect.dat. Start the program using the following syntax:
flowVis sample.par
The program will start and write a lot of messages about what it is doing onto the screen. The output images will be placed in the directory output/ which has been created when unpacking the tar-file. You can use any image viewer, that can read PPM files, e.g. xv, to view the images.
The file diffuse.c implements three functions computing the nonlinear anisotropic diffusion to visualize a vector field given in an (width x height) array. Each function produces a color image, which will be returned or written into files. Available functions are:
int diffuse(double *vx, double *vy, int width,
int height, double ***image,
int numberOfSteps, int verbose);int diffusePF(char *parFileName, double ***image,
int verbose);int diffusePar(double *vx, double *vy, int width,
int height, double ***image,
int numberOfSteps, int verbose,
char *outFileName, int useRed,
int useGreen, int useBlue,
int pixelSize, int pcgSteps,
int sharpen, int normalize,
double sigma, double tau,
double pcgTau, double vThreshold,
double gKval);
Any of the functions returns 0 if it was executed successfully and some value different from 0 else. If the parameter verbose is set error messages and various other information will be printed to stderr.
The easiest to use function of the above ones is the first one. diffuse computes numberOfSteps time steps of the evolution process given the vectorfield data (vx, vy) in an (width X height) array. vx contains the X-values and vy the Y-values of the vectorfield. The evolution will be started using the RGB image given by image . Please note that imagemust be a pointer to a double** array containing for each color channel a double* array of size ( width X height) . I.e. (*image)[0] corresponds to the red channel of the image etc. If image points to a NULL array the evolution will be started on a white noise in the blue/green color space. When the function returns, image will point to memory containing the resulting image.
The functions diffusePFand diffuseParenable you to set much more parameters of the diffusion process. What parameters can be set will be described in the next section. diffusePF reads parameter information from a file specified by parFileName. If not determined in this parameter file the evolution will start with the density imageor with white noise if image points to NULL. However, the resulting density will be returned in image.
When using diffusePar you can specify all parameters without using parameter files. Anything said before about the other functions holds as well for this one.
For parameters not set in the parfile the program will use default values if possible. A warning message will be printed out. The order in wich you specify the parameters does not matter. Don't forget the colon following each parametername.
As seen in the previous section the you can set many parameters for the diffusion process by using diffusePF and parameter files(parfiles). In this section you will learn, how to create such a file for your problems.
If you take a look at the sample parfile, you will see that each line is either a blank line, or has the following type:
<Parametername>: <value>
A parfile must not contain any other lines than lines of the above type. The line above means that the parameter named <Parametername> will be given the value <value>. The following table tells you which parameters can be set. A red font indicates that the parameter must be set, the other parameters are optional. For optional parameters, the number below the expected type of the value tells you the default value.
| GKVAL | FLOAT
0.0 |
The shape of the diffusion coefficient
g(), controlling the Perona Malik diffusion perpendicular to the vectorfield
will be g(s) = 1/(1 + GKVAL . s).
If you want to modify the shape of the function g more than this parameter allows you to, or even if you want to modify the function controlling the linear diffusion along the vectorfield, you have to modify the code directly (see below). |
| INPUT | STRING | If set, the initial density will be the
specified image, wich has to be a PPM image of size (2SIZE+1)
X (2SIZE+1) pixels. See parameters USE_XXXX
for more information.
If the parameter is not set the initial image will be a white noise created by the program itself. |
| NORMALIZE | 0 or 1
1 |
If this parameter is equal to 1 the vectorfield will be normalized before visualizing it. I.e. the vectors will be scaled such that they have all length 1. |
| NUMSTEPS | INT | Determines the number of time steps the program will perform. Each time step of the anisotropic diffusion will have length TAU. |
| OFF_X
OFF_Y |
INT
0
|
These parameters enable you to visualize just a part of the vectorfield contained in the file specified by VECTORFIELD. If set, the program will visualize the vectorfield in the rectangle starting at (OFF_X, OFF_Y) and of the corresponding size. |
| OUTPUT | STRING | The names of files containing output images will be the value of this parameter plus the suffix "_X.ppm", where X is the time step number. The output files will be in PPM format (see below). |
| PCGSTEPS | INT
20 |
Determines the maximum number of iteration steps of the CG solver. |
| PCGTAU | FLOAT
1e-6 |
Determines the numerical accuracy of the CG solver. |
| PIXEL_SIZE | INT
1 |
This parameter determines the size of the pizels of the white noise initial image. It is only taken into account if the parameter INPUT is not set. |
| SHARPEN | 0 or 1
1 |
If set, the images will be sharpened by a function on the right hand side of the PDE. The use of this parameter is highly recommended, since otherwise the contrast will decrease immensely. The implemented sharpening function pulls the colors along straight lines onto the color sphere. |
| SIGMA | FLOAT
1e-6 |
Specifies the variance of the Gaussian smoothing kernel. Please note that the mesh covering the images has side length 1, or each element of the mesh has length 2-SIZE. Thus, you have to adapt the value of this parameter to the value of the parameter SIZE. E.g. for images of width 257 the value 0.000001 is recommended. |
| SIZE | INT | The width and height of the output images will be (2SIZE+1) X (2SIZE+1) pixels. Since the program is working with hierarchical grids the width and height of images must be a power of 2 plus 1. |
| TAU | FLOAT
1e-4 |
Determines the length of one single time step of the anisotropic diffusion. This parameter too must be adapted to the value of the parameter SIZE. E.g. for images of width 257 the value 0.0001 is recommended. |
| USE_RED USE_GREEN USE_BLUE | 0 or 1 | These three parameters determine the dimension of the vector valued anisotropic diffusion. You should set any of the parameters equal to 1, if you want the corresponding color channel to be used. Any combination is allowed. Whether you indicate an initial image (see parameter INPUT) or not, in either case the program considers only the specified color channels. |
| VECTORFIELD | STRING | This parameter determines the file containing
the vectorfield data. Please see below for detailed information on the
file format.
If not specified the program will create a sample vectorfield itself. |
| VTHRESHOLD | FLOAT
0.0 |
All the vectors of the vectorfield with length less than this parameter will not be considered in the calculation, i.e. the resulting images will be light gray at pixels where the length of the corresponding vector is less than VTHRESHOLD. |
This section describes the format of files containing vector field data. For detailed information on the PPM file format please refer to the man page on your system.
Vectorfield data must be given on a rectangular grid consisting of <width> X <height> cells. For each cell a 2 dimensional vector, i.e. 2 floating point numbers, must be given. In general the file format used for vectorfield data is similar to the PPM file format. Any file consists of a header followed by data. The definition of the header is as follows:
|
A magic number for identifying the file type. The magic number is the two characters "V2" (Upper case V). |
|
Whitespace (blanks, tabs, carriage returns,linefeeds). |
|
The width of the grid on which vectorfield data is given, formatted as ASCII integer. |
|
Whitespace. |
|
The height of the grid on which the vectorfield is given, again formatted in ASCII integer. |
This header is followed immediately by <width> X <height> vectors, each 2 floating point numbers, formatted as ASCII decimals, starting at the top-left corner of the grid and proceeding in normal English reading order from left to right and from top to bottom. The following is a small example of a file of the above type:
V2
3 3
1.000 0.223 2.345 0.247 1.201 -0.750
5.600 -0.229 2.326 0.213 1.232 0.740
8.234 0.245 -2.345 0.289 1.223 -0.400
Please note that no comments are allowed in vectorfield data files.
There is an alternative file format which stores the vectors as plain bytes instead of ASCII floating point numbers. The differences are:
|
The magic number is "V5" instead of "V2". |
|
Only one single character of whitespace (typically a newline) is allowed after the header. |
|
The data section again contains a number of vectors, but this time stored as binary data, each floating point number 8 bytes long. This corresponds to the byte length of the internal data type D_TYPE of the program. If you want to use 4 byte floating point numbers, you have to modify the source code. See next section for details. |
|
The files are in general smaller and faster to read.
|
Although a lot of functionality of the diffuseXXX functions can be controlled via parfiles, some features must be modified directly in the source code:
|
Data types. The data type used by flowVis is fixed through the definition of D_TYPE. Per default the definition equals to the use of double as standard type. However, if your computer suffers from lack of memory you can switch to float and recompile the code. You will also have to modify the setting of D_TYPE, if you want to read in vectorfield data in 4 bytes format. |
|
Linear diffusion coefficient. The linear diffusion coefficient controls the diffusion along the vectorfield. This value may depend on the velocity (the length of the vectorfield) and is represented by the macro linDiff (cf. file Diffuse.h). Per default this function returns a constant value, but you may change the function and recompile the code. |
|
Nonlinear diffusion coefficient. Diffusion perpendicular to the vectorfield is controlled by the nonlinear Diffusion coefficient g, implemented in computeGValues (file Diffuse.c, Mesh.c). The shape of the default coefficient is g(s) = 1/(1 + GKVAL . s), but you can implement some other function here. |
|
Contrast enhancing function. The scalar contrast enhancing function FV_sharpenRGBData is defined in Source.c. Per default it just pulls a color value up by multiplying it with some constant greater than 1. You can implement some more sophisticated function and recompile the code. |