Libpiv API documentation

 Search for 

Documentation of Libgpiv API

0.5.0

Introduction

LIBGPIV is a software library for the so-called Digital Particle Image Velocimetry (DPIV). It contains the core functions for image recording, image processing, image interrogation (resulting into estimators of particle image displacements, i.e. PIV data), validation of PIV data (on peak-locking effects, erroneous vectors (outliers), velocity gradient), post-processing (functions for calculating (scalar) derivatives of the PIV data, like vorticity and strain), input/output functions, memory allocation etc.

The library has been implemented in several command-line driven programs that can be found in the GPIVTOOLS distribution. A Graphic User Interface (GPIV) is available as well, that controls all processes and its parameters and displays its results graphically in a more advanced way. GPIV has been implemented with the Gtk/GNOME libraries and resides in GPIV package. Also a python module PYGPIV has been written that allows the use of this library functionalities within Python scripts.

This library has been written in ANSI-C and has been developed on a GNU/LINUX box and should work on any UNIX-like system. The main web page can be found at: http://gpiv.sourceforge.net/

License

LIBGPIV is Free Software licensed under the GNU Public license terms. See the COPYING file for the license.

Installation

Unpacking and compilation:

gzip -d libgpiv-*.tar.gz
tar -xvf libgpiv-*.tar
./configure
make
make install

Some features will only work when they are enabled before the building process. An IEEE1394 (Firewire) camera, using the IIDC specifications protocol, is enabled with:

./configure --enable-cam

Triggering, currently only with RealTime Linux (RTA) and RealTime Aplication Interface (RTAI), is enabled with:

./configure --enable-dac

Libgpiv is included in the GNU/Debian system for most of the supported (currently 11) CPU architectures and is probably also included in Linux distro's that have been derived from GNU/Debian, like Ubuntu and Knoppix. This may drasticly ease the installation, as one has not to be bothered about library dependencies etc.

Interface naming and some policy rules

It has been tried to write a simple and systematic API as possible with mnemo-syntactic naming to the variables, functions and constants. But, as you probably know, its hard to be consistent. Anyhow, here follow some general API policy rules.

Structures are named following: "GpivNameAnothername" convention, while variables and parameters using that structure are mostly named as: "name_anothername", or have been named different for clarity.

Macros start with: "GPIV_" and public functions with: "gpiv_", in general following their module name:

"img_" for image functions,

"imgproc_" for image processing,

"piv_" for image (PIV) interrogation,

"valid_" for (PIV) data validation,

"post_" for data post-processing,

and / or following their functionality, like:

"(f)read_" and "(f)write_" for in and output,

"(free_)vector_" or "(free_)matrix_" for memory (de)allocation,

(Ending on "_index" may be used for arbitrary starting and ending indices.)

In general, a function will return NULL on success or an error message will be returned if the function fails.

To create a structure (and fill it with data) is done following:

struct = gpiv_* ()

or the function will return NULL if it fails. To read data from a file into a structure is done following:

struct = gpiv_read_* (FILE *fp, ..)

or if a file name is used:

struct = gpiv_fread_* (gchar *filename, ..)

Writing / storing the data of a structure to a file is done with:

gpiv_write_* (FILE *fp, struct, .., gboolean BOOLEAN)

or with:

gpiv_fwrite_* (gchar *filename, struct, ..., gboolean BOOLEAN)

where BOOLEAN determines whether the memory of the structure will be made free (TRUE) or not (FALSE).

To use an existing structure while calling a libgpiv function is done as:

gpiv_* (pointer to struct, ...)

Final remarks

We hope that the software will work fine and that you'll enjoy it during using and developing. Remarks, suggestions and patches for improvements/additions are welcome.

---