Libgfp

This is the GFP Library version 0.1.0

GFP stands for GrapeFruit Plot (not for Green Fluorescent Protein)

The "grapefruit plot" term most probably comes from Ray Freeman's NMR laboratory in Cambridge, UK. Please mail me if you have more info about this.

A grapefruit plot shows the trajectory of the sample's magnetization vector during the course of an NMR experiment. This is nothing else than a 2D projection of a 3D line that is enclosed inside of a sphere of unit radius.

User space 3D (absolute) coordinates (usually in the [-1 +1] range) are first converted to user space 2D coordinates (in the same range) and then to "paper" coordinates.

The Gfplib produces a very naive Postscript® script. This is a C API. The user has to write a C program to use it. A simple executable program named ngfp can be built from the distribution file. It converts "x y z" coordinate files to Postscript® plot files.


Installation


The ngfp program

ngfp stands for new grapefruit plot, thus suggesting that there were an older version.

Usage:
ngfp [[theta] phi]

ngfp reads a text file from standard input and writes a Postscript script file to standard output. Optional arguments theta and phi define the direction of the viewing line (see below). A "x y z" line in the input file so that x is bigger than 10 is interpreted as the beginning of a new line.

The ngfp.c file should be considered more as an example of the use of the libgfp library than as the source code of a true application.

See relax.c, as another example.


The libgfp API

Features

The user space 2D coordinates are mapped to the paper coordinates according to three geometry parameters : The user space 3D coordinates are mapped to the 2D user space coordinates according to three parameters that define the relative position of the viewer and the unit sphere coordinate system :

The grey shading is controled by a grey value that is 0 for white and 1 for black, a convention that is opposite to the one of Postscript®. The grey value of the point that is the closest of the sphere relatively to the observer is 1. The grey value of the most distant one is mingrey.

There are four predefined fonts. Three of them are Times-Bold and the fourth is Symbol. The user can define three font sizes : small, medium, big corresponding to the Times-Bold characters. The size of the Symbol font is big. Of course, a lot of improvement has to be made here.

Axis labels can be defined individually, as well as the label position in the user space.

Linewidthes and font sizes are given in Postcript points: there are 72 points per inch (2.54 cm).

A grapefruit plot contains at least the drawing of the external trace line of the unit sphere, the unit circles in the XOY, YOZ, ZOX planes and the part of the axis that lies inside of the sphere. Two linewidths can be defined, one for the part of the axis that corresponds to the positive coordinates (thick line), and another one for the negative coordinates (thin line).

Plotting a curve in space requires the user to define the way 3D coordinates are calculated from a single parameter (parametric plot). The type definition of such a point trajectory function is void trajfunc(double t, double &x, double &y, double &z). Lower level functions are available for non-parameteric curve drawing, as in ngfp.c for coordinate file reading.

Most of the drawing functions in the Libgfp API are available in grey scale mode or in monochrome mode (functions with _bw suffix).

Configuration fonctions

Coordinate transformations

Drawing functions

Black and white drawing

The functions:

work like their non- _bw counterparts, but draw in full black rather than in grey.


Jean-Marc Nuzillard
jm.nuzillard@univ-reims.fr

March 15th 2006