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

Download
libgfp0.1.0.tar.gz.

Unpack it: tar xvzf libgfp0.1.0.tar.gz

Enter the directory: cd Libgfp0.1.0.tar.gz

Build the library: make

Install it (as superuser): make install

Test it: make test. This produces cpmg.ps from the coordinate
file cpmg.txt. The result should look like this:
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 :

radius: in cm, the radius on papier of the projection of
unit cercle that lies in the plane that is pependicular to the view line
and that contains the center of the unit sphere.
The view line joins the eye of the observer and the center
of the unit sphere.

x and y: in cm, the position of the projection of the center of the unit
sphere, relatively to the left bottom corner of the paper.
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 :

theta: in degrees, is 0 if the observer is looking at the sphere from
the North pole. This is the angle between the OZ axis of the absolute
coordinate system and the view line.

phi: when theta is less than 90 degrees and phi is zero, the OX axis
of the absolute coordinate systems points to the bottom of the paper
and the OY axis to the right. When theta is more than 90 degrees and
phi is zero, the OX axis points to the top of the paper. phi is the
angle of the rotation that is made by the observer around the OZ
axis.

distance: in user (absolute) units, the distance between the observer
and the center of the unit sphere. This can be INFTY, as defined in
libgfp.h.
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 TimesBold and
the fourth is Symbol.
The user can define three font sizes : small, medium, big corresponding
to the TimesBold 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 nonparameteric 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

void setgeom(double radius, double x, double y, double distance)
If not called, defaut values are 8.0, 10.5, 14 and INFTY.

void setview(double th, double ph)
Sets theta and phi view angles.
If not called, default values are 70.0 and 20.0. If neither setview
nor init_gfp (see below) are called, results are unpredictible
because the projection matrix that maps 3D coordinates
to 2D coordinates is not initialized. You have been warned.

void setmingrey(double ming)
defines the minimum grey value. Defaut value is 0.1 (nearly white).
The value of ming must be in the 0.01  1 range,
bounds excluded. This is not checked for. You have been warned.

void setfontsizes(int small, int medium, int big)
Default values are 12, 14 and 18 points.

void setgfplinewidth(double thin, double thick)
defines the linewidthes for drawing of coordinate axes.
Default values are 0.25 and 1.0 points and referred to as the
LW1 and LW2 constants. LW3 is also defined as 2 points
and is intended to be used for line drawing.

void setsegment(double segment)
is used for the drawing of straight lines (segments).
This is, in Postscript points, the maximum length of each subsegment
having all its points of the same grey value.
The default value is 10.0.

void setaxisfont(char *c)
the argument is a font name among the 4 possible ones:
"smallfont", "mediumfont", "bigfont" and "bigsymbolfont".
Defaut value is "mediumfont".

void set[xyz]label(char *c, double x, double y, double z)
axis label c will be drawn at the point of (x, y, z) absolute
coordinates. Defaut values are ("X", 1.2, 0.0, 0.0) for setxlabel,
("Y", 0.0, 1.1, 0.0) for setylabel and ("Z", 0.0, 0.0, 1.1)
for setzlabel.

void header()
prints the Postscript header. Must be called before anything if
init_gfp is not called. Otherwise, the output file
will not be recognized as a Postscript one.

void gfp()
draws the four circles of the unit sphere, the axis and axis labels.
Is called by init_gfp.

void init_gfp()
calls header, setview and gfp.
Coordinate transformations

void coor2(double x, double y, double *xp, double *yp)
transforms user space 2D coordinates x and y to paper coordinates
according to setgeom radius, x and y parameters.

void coor3(double x, double y, double z, double *xp, double *yp)
transforms user space 3D coordinates to 2D user space coordinates
according to setgeom radius parameter and setview th and ph
parameters.
Drawing functions

void setlinewidth(double lw)
changes the current linewidth. See setgfplinewidth.
After calling gfp, its value is the thick parameter
or its default value LW2.
If neither gfp nor init_gfp were called, the current linewidth
is the Postscript default one: 1.0.

void setfont(char *font)
changes the name of the current font.
For valid font names, see setaxisfont.
If neither gfp nor init_gfp were called, the current font
is undefined (Postscript default ?).

void newline()
sets up a new line.

void endline()
ends the current line.

void papermove(double xp, double yp)
moves the pen to the indicated (xp, yp) paper position.
Uses the current grey value.
This is the lowest level drawing function.

void draw2(double x, double y)
is like papermove but with user space 2D coordinates.

void draw3(double x, double y, double z)
Parameters are user space 3D coordinates.
Sets the current grey value.

void segment(double x1, double y1, double z1,
double x2, double y2, double z2)
Draws a segment between points of absolute coordinates
(x1,y1,z1) and (x2,y2,z2).
Calls newline, the draw3 as many times as possible so that
the length of subsegments is less than segment
(argument to setsegment) and finally calls endline.
This is the high level way of drawing straight lines.

void curve(trajfunc f, double from, double to, int n)
draws the parametric curve defined by the f function, with n
segments corresponding to the parameter value varying from from to to.
Calls newline, (n+1) times draw3, and endline.
This is the high level way of drawing a curve.

void text3(char *c, double x, double y, double z)
prints the character string c at absolute coordinates (x,y,z).
Uses the current font and the current grey value.

void arrowhead2(double xp, double yp, double xp1,
double yp1, double xp2, double yp2, double l, double th)
is the paper space arrowhead drawing function.
The head is located at (xp,yp).
The direction to which the arrowhead points to is the direction
of a vector that would lead from (xp1,yp1) to (xp2,yp2).
An arrowhead is made of two line segments.
Their length is l in the 3D user coordinate space
and the angle between them is 2*th.
Uses the current linewidth and current grey value.

void text3vec(char *c, double x, double y, double z,
double dxp, double dyp, double l, double th)
prints the character string c at absolute coordinates (x,y,z).
An arrow of length dxp points is written dyp points
above the string baseline.
Parameters l and th are those of arrowhead2.
Uses the current font, the current linewidth and the current
grey value.

void arrowhead3(double x, double y, double z, double x1, double y1,
double z1, double x2, double y2, double z2, double l, double th)
works like arrowhead2 but in the absolute coordinate space.

void trajarrow(double t, double dt1, double dt2,
trajfunc f, double l, double th)
draws an arrowhead along a parametric curve.
The arrowhead is located at the point defined by the t parameter.
The direction of the arrow is the one of the vector that joins
the points defined by parameters t+dt1 and t+dt2.
Parameters l and th are identical to those to arrowhead2.

void centerarrow_bw(double t, trajfunc f, double l, double th)
draws an arrow that joins the center of the absolute coordinate
system and the point defined by the parametric function f and
its parameter t.
Parameters l and th are identical to those to arrowhead2.
Black and white drawing
The functions:

void newline_bw()

void endline_bw()

void coor3_bw(double x, double y, double z, double *xp, double *yp)

void draw3_bw(double x, double y, double z)

void segment_bw(double x1, double y1, double z1, double x2,
double y2, double z2)

void curve_bw(trajfunc f, double from, double to, int n)

void text3_bw(char *c, double x, double y, double z)

void arrowhead2_bw(double xp, double yp, double xp1, double yp1, double xp2,
double yp2, double l, double th)

void text3vec_bw(char *c, double x, double y, double z,
double dxp, double dyp, double l, double th)

void arrowhead3_bw(double x, double y, double z, double x1, double y1, double z1,
double x2, double y2, double z2, double l, double th)

void trajarrow_bw(double t, double dt1, double dt2, trajfunc f,
double l, double th)

void centerarrow_bw(double t, trajfunc f, double l, double th)
work like their non _bw counterparts, but draw
in full black rather than in grey.
JeanMarc Nuzillard
jm.nuzillard@univreims.fr
March 15^{th} 2006