Writing and loading data files with Mplot++

Now you should know that Mplot++ allows you to visualize on the
screen of your machine bi- and tridimensional curves and surfaces described
by a set of parametric equations.
To reach this goal Mplot++ must do "some" calculations; in many situations
you could need to know the results of this calculations rather than to
visualize a graphic; in all this situations you have to write a data file.
The data files of Mplot++ are simple ASCII texts: you can open and modify
them using any editor ( editor = program to process text files, like Emacs,
Vi, gedit, kedit, jed, pico, or the Notepad of Windows. But I have a Mac, so
what must I use ? Sorry, I do not know. It is a personal problem of yours
if you can not distinguish between an editor and a word processor, i.e.
something like Microsoft Word(R) or Corel Wordperfect(R) ).
Naturally, you must know exactly what you are about to do if you decide
to modify a data file created by Mplot++; that is why you will find
below a description of the format of the data files of Mplot++.
However, I think that you will never need to modify a file created by
Mplot++ ( You are very glad of this, are not you ? ).
The data files used by Mplot++ should have the extension .mpp even if
they are simple ASCII texts; when you decide to write a data file
you may choose to give any name with any extension to the file you are
going to write; for example you may call it "test.txt".
In fact, Mplot++ lets the user try to open any file ( i.e. a regular
file, not directories or folders or links; if you are using Mplot++
under Unix it will allow you to open any file having the permission mask
set to 644 ) even if it do not load files having an unagreable format; so,
Mplot++ will not load binary files ( For Windows(R) users: a binary
file is a .exe or .com file ) or text files having a wrong format:
nobody may use Mplot++ to read or write a letter, or a presentation
or the first thing imagined by his/her brain.
Let us suppose that some data files have been already created by Mplot++
and that the user wants to load one of them because he wishes to visualize
the corresponding graphic.
In the Start window of Mplot++ there are four big buttons; one of them
has the label "Load" and this is the button that must be pressed if one wants
to visualize on the screen a graphic previous saved in the form of
ASCII data file.
After pressing this button, the Load window appears on the screen.
In this window the user must specify some parameters that will be used
by the program to rebuild the graphic. The requested informations deal with
the `framed region' of the graphic ( if you do not know what this expression
means perhaps you need to read the introductive part of the guide :) );
in fact the user must supply the coordinates of the center of the framed
region and its dimensions. It is a good idea to remark that the aspect
of the Load window depends on the chooses that the user did before
to press the "Load" button into the Start window: in the Start window
the user must tell to the program if he wants to plot a bidimensional
curve, a tridimensional curve or a surface. If he chose
to plot a 2D curve then he must specify, into the Load window, the
2 coordinates of the center of the `framed region' ( 'x0' and 'y0' ),
its width ( 'w' ) and its height ( 'h' ). Else the coordinates
of the center of the `framed region' to be specified are 3 ('x0', 'y0'
and 'z0' ) and the dimensions of the `framed region' are fixed by
setting its radius 'R' ( in 3D graphic the `framed region' is a sphere ).
The Load window supplies, at this purpose, some lines of text just
as the Form window. The limitations on the values that the parameters
'x0', 'y0', 'z0', 'w', 'h' and 'R' can assume are the same valid
for the Form window ( see the corresponding part of this guide ).
Even the keys that must be used to move the cursor between the different
lines of text and inside each of them are the same.
When the user has specified the position and the dimension of the `framed
region' he can load the file containing the informations about the graphic
he wants to plot. At this end he needs to press the "Open" button inside
the Load window. Into this window there are other 2 buttons.

The "Close" button, if it is pressed, closes the Load window and
makes active the Start window. The "Pref" button, when it is pressed,
displays the Preferences window into which the user can set the plot style
for each curve must be visualized. I have already described the Preferences
window in the precedent section of the guide ( see 'Mplot++ in practice' ),
so you can see there if you want to have more infos about that window.
Be careful ! The settings of the Preferences window affect only
the way to represent the different curves plotted in a 2D graphic.
Remember that you may visualize only a 3D curve or surface at time
while you may visualize up to 10 curves at time if you are working in
'bidimensional graphic' mode. This means that you may save in a single
data file a bidimensional graphic where are represented up to 10 curves.

The "Open..." button, when is pressed, causes the visualization of a File
Chooser, i.e. a window that is designed to let the user choose the data
file he wants to load. Because the data files of Mplot++ have, by
default, the extension .mpp, in the list of the File Chooser you
can see, besides of the subdirectories ( or folders if you prefer to call them
in this way ) of the working directory, only the files contained
inside the working directory that have the .mpp extension ( something
like 'test.mpp' or 'circle.mpp' and so on ). For working directory
or working folder I want to mean the directory or folder where stays
the executable file of Mplot++. This directory is fixed when Mplot++
is installed on your machine.
The File Chooser has many features, the major one being that the Tab key
completes filenames like it does in Emacs or tcsh, and the list always
shows all possible completions. Moreover, the File Chooser permits:
1) To choose a file by picking its name in the list or by typing the name
   into an input line provided to this end;
2) To move one self quickly between the directories. In particular one can
   quickly return to the home directory or to the current directory 
   ( = working directory/folder ).
The File Chooser has 2 buttons, "Ok" and "Cancel". The last one cancels
the choose done while the first confirms it.
When the user presses the "Ok" button Mplot++ checks for the admissibility
of the path of the file chosen and for its format; if there is something
wrong an error message will appear on the screen with a short description
of the occurred trouble.
In particular, Mplot++ complains if the requested file does not exist.

Maybe now you wish to know how you can write data files.
In the precedent section of the help ( see 'Mplot++ in practice' ) you
learned that the Form window has always a button with the label "Write"
upon. If the user presses this button Mplot++ does not display
any curve, but it downloads on a file the results of the calculations
it would do to draw the objects. The user can choose the path of the
file where this data must be downloaded and he will be advised if a
file existing yet could be overwritten.
In fact, after pressing the "Write" button, the File Chooser appears; and
even if the data files of Mplot++ should have the .mpp extension the
File Chooser lets the user to call a file as he likes more. Anyway it checks
for the existance of a file having yet the specified name and it controls
if the directory/folder where the file is about to be written its a writable
directory, i.e. a directory where the user may save a file. For each error
a message appears with a short description of the occurred problem.

Now I must describe the format of the data files created by Mplot++.
The format of a data file depends on the type of the graphic described by
it. If the file has been obtained by saving a bidimensional graph then
its format is the following:

 I) In the first line are stored, in this order, the lower and the upper limit
    of the interval of variation of the parameter, the number of the nodes of
    interpolation used in plotting each curve of the graph and the number of
    the curves forming the graph; the first 2 values are floating-point
    values while the last 2 are positive integer values. Each of these values
    is separated from the next one by white spaces (i.e. Tabs and blanks).
    After the first line there is an empty line (i.e. a line formed only
    by the '\n' character) and this empty line is mandatory.

II) Then, for each curve of the graph there is a list of couples
    of floating-point values; each of these couples is placed on a line
    and each line of text contains one and only one of these couples of
    numbers. Moreover, the numbers of a same couple are separated by
    tabs and blanks. Every couple of numbers represents a point of the curve
    trough its absolute coordinates x and y; so, every list of couples of
    numbers is a list of points of a curve of the graph.
    Because there is a one-to-one correspondance between the list of the
    points of a curve and the set of the values of the parameter for which
    the parametric equations of the curve are evaluated, every list of points
    is formed by a number of elements equal to the number of the nodes of
    interpolation. Because I want to be more precise, if the parametric
    equations of a curve are
    
			x = x(t)
			y = y(t)
     
    and the lower bound of the interval of variation of 't' is 'a',
    the upper bound is 'b' and 'n' is the number of the interpolating nodes,
    then the curve is described by the list:

			x(a)			y(a)
		x(a + (b-a)/(n-1))	y(a + (b-a)/(n-1))
		x(a+2*(b-a)/(n-1))	y(a+2*(b-a)/(n-1))
		x(a+3*(b-a)/(n-1))	y(a+3*(b-a)/(n-1))
				     .
				     .
				     .

		x(a+(n-2)*(b-a)/(n-1))	y(a+(n-2)*(b-a)/(n-1))
			x(b)			y(b)			.

    I think it is not possible to be more clear.
    Every list of points is separated from the next one by an empty
    line; this empty line is mandatory. In this way the reader can
    easily understand where the list of points of a curve finishes
    and the next one starts. The last list is followed by an empty
    line too, but this empty line is not necessary.
    
If the file has been obtained by saving the graph of a tridimensional
curve then its format is the following one:

 I) The first line contains, in this order, the lower and the upper limit
    of the interval of variation of the curve's parameter and the number
    of the nodes of interpolation used in plotting the curve.
    The first 2 values are floating-point values while the last one is
    a positive integer value. Each of these values is separated from the
    next one by tabs and blanks.
    After the first line there is an empty line (i.e. a line formed only
    by the '\n' character) and this empty line is mandatory.

II) Then, there is a list of sets of 3 floating-point values; each of these
    sets is placed on a line and each line of text contains one and only one
    of these sets of numbers. Moreover, the numbers of a same set are
    separated by tabs and blanks.
    Every set of numbers represents a point of the curve trough its absolute
    coordinates x, y and z; so, the list of these sets is a list of
    points of the curve of the graph.
    Because there is a one-to-one correspondance between the list
    and the set of the values of the parameter for which the parametric
    equations of the curve are evaluated, the list of points
    is formed by a number of elements equal to the number of the nodes of
    interpolation. Thus, if the parametric equations of the curve are
    
			x = x(t)
			y = y(t)
			z = z(t)
     
    and the lower bound of the interval of variation of 't' is 'a',
    the upper bound is 'b' and 'n' is the number of the interpolating nodes,
    then the curve is described by the list:

		x(a)			y(a)			z(a)
	x(a + (b-a)/(n-1))	y(a + (b-a)/(n-1))	z(a + (b-a)/(n-1))
	x(a+2*(b-a)/(n-1))	y(a+2*(b-a)/(n-1))	z(a+2*(b-a)/(n-1))
	x(a+3*(b-a)/(n-1))	y(a+3*(b-a)/(n-1))	z(a+3*(b-a)/(n-1))
			     .			     .
			     .			     .
			     .			     .

    x(a+(n-2)*(b-a)/(n-1))    y(a+(n-2)*(b-a)/(n-1))    z(a+(n-2)*(b-a)/(n-1))
		x(b)			y(b)			z(b)	     .

    This list is followed by an empty line, but this empty line is not
    necessary.

Finally, if a data file has been obtained by saving the graph of a
surface then it has the following structure:

 I) The first line contains, in this order, the lower bound of
    the interval of variation of the parameter '?', the upper bound
    of the same interval and the number of the nodes of interpolation
    to put on this interval.
    The second line contains the same informations but referred 
    to the '!' parameter. Remember that Mplot++ uses the symbols '?'
    and '!' to denote the parameters in the parametric equations
    of a surface. 
    The first 2 values of both lines are floating-point values while the
    last one is a positive integer value. Each of these values is separated
    from the next one by tabs and blanks.

II) Then, there are some lists of sets of 3 floating-point values; each of
    these sets is placed on a line and each line of text contains one
    and only one of these sets of numbers. Moreover, the elements of a
    same set are separated by tabs and blanks.
    Every set of numbers represents a point of a curve trough its absolute
    coordinates x, y and z; so, every list of these sets is a list of
    points of a curve on the surface.
    You must remember that, given the surface with parametric equations:

		      x = x(?,!)
		      y = y(?,!)
		      z = z(?,!),

    where '?' goes from 'a' to 'b' and '!' goes from 'c' to 'd', this surface
    is drawn by plotting the curves having equations:

		      x = x(?,t)
		      y = y(?,t)
		      z = z(?.t)	a <= ? <= b

    and

		      x = x(s,!)
		      y = y(s,!)
		      z = z(s,!)	c <= ! <= d,

    where t and s are constants which takes, time after time, the values
    a, a + (b-a)/(n-1), a + 2*(b-a)/(n-1), ..., b   and
    c, c + (d-c)/(n-1), c + 2*(d-c)/(n-1), ..., d   respectively.
    For every value of s = a, a + (b-a)/(n-1), a + 2*(b-a)/(n-1), ..., b
    there is, into the data file, a list of points corresponding to the curve
    whose parametric equations are given by
    
                      x = x(s,!)
		      y = y(s,!)
		      z = z(s,!)	c <= ! <= d	.

    Each of these lists is separated from the next one by an empty line
    and this empty line is mandatory.
    The last list is followed by an empty line too, but this empty line
    is not necessary.

Uuuhh ! This section of the guide is finally finished.

However, you could wish to know HOW YOU CAN MAKE A DATA FILE OF MATHPLOT++
READABLE BY GNUPLOT. It is very simple: YOU HAVE TO COMMENT, STARTING
FROM THE FIRST ONE, ALL THE LINES OF THE FILE ( BY INSERTING A SINGLE '#'
AT THE BEGIN OF EACH LINE ) UP TO THE FIRST EMPTY LINE INCLUSIVE.
After making this, a data file may be visualized with Gnuplot by using
the 'plot' command for the bidimensional graphs and the 'splot' command for
the others (see the help online of Gnuplot).  
The next version of Mplot++ will permit you to save directly the graphs
in a format understandable to Gnuplot as well as in the native format
of Mplot++.