This file gives a short description of the formats
recognized by xgraphic and xd3d. You'll find examples
of most of them in the directory Examples
=============================================================

I. xgraphic file format
=======================

* Ascii file with 2 coordinates x y per line.

* Commentaries can be inserted at the beginning of the file
with a # in first column (as many lines as you need).

* A blank line in the middle of the file means a jump
between 2 consecutives points.

* Multicolumn files (number of columns > 2) "à la gnuplot"
are recognized. If "toto" is the file name,

    xgraphic toto#2#5

will plot column 5 as a function of column 2

* You can also plot the graph of a function given by an equation:
type
    xgraphic #
and answer the questions. The equation must be written in fortran
synthax, i.e. using the following operators. + - * / ** sin cos etc...

Type "xgraphic -h" for more help.

=============================================================

II. xd3d file formats
=====================

1/ Meshes
---------

* Native format is "avoirND" format. The files must have the extension
.avoir2D or .avoir3D according to the space dimension (note that it is
only a facility. The file formats are the same in both dimensions).

"avoirND" files are binary. You can read them through appropriate
programs. The library lib/question_lib.a contains utilities to
read/write meshes (src/qlib/litavoir.f, src/qlib/ecritavoir.f). The
file src/include/com_avoir.f is exceptionnaly widely commented and
provides the description of all the parameters involved in routines
litavoir.f and ecritavoir.f.

In the directory src/various, the source code of clair.f (translation
of a avoirND into an ascii file) and obscur.f (the opposite) show you
how to read/write a complete avoirND. You can also have a look at
src/various/translation.f

If you don't need all the parameters of the avoirND format, but you
rather want to plot simple meshes (nodes, elements and that's all. No
references subdomains, pressures etc...), have a look at
src/various/txt2avoir.f.  It does the translation job between basic
mesh format and avoirND.

The local numbering of nodes in an element is the usual Finite Element
convention (anti-clockwise numbering for 2d P1 or Q1 elements).  The
directory Example provides reference elements for more complex types
of FE. You can visualize the node numbering with xd3d by clicking the
"num" button (menu inside).

* xd3d can also read various file formats used by Modulef (from INRIA)
and FreeFem++ : "nopo", "amdba", "am", "am_fmt", "msh" mesh files. For a 
description of these formats, see the Modulef or the FreeFem++ manual. 
The translation of nopo files into avoirND format is performed by 
the program "nopo_avoir", while the other formats are translated inside
xd3d. The files are recognized through their extension.

* xd3d can plot pgm or pbm files as a 2d grid. The value of
the grey level (pgm) or bitmap (pbm) on each point is plotted as a 
z-displacement field.

2/ Fields associated to the mesh
--------------------------------

For a mesh having N nodes and NEL elements, various scalar/vector
fields are recognized. Data are read in ascii files. The first line
after an eventual commentary line (one line of commentary can be
inserted at the beginning of the file with a # in first column) is an
integer. If it is N, the following datas are attached to the nodes; if
it is NEL, xd3d understands that he reads cell data.  Other values
give an error message.

The remaining of the file is N or NEL lines, with 1 number (scalar
field) or 2 or 3 numbers (vector field in 2d or 3d) attached to each
node (N) or element (NEL).

Discontinuous fields are also recognized. In this case, the first
integer has to be NEL, and for each element you must read NDS values
(on the same line) if NDS is the number of nodes per element.


3/ 3d surfaces
--------------

4 different formats are recognized through their extension

* .c3d format: binary files containing structured data:
    x_i, y_j, z_ij, i={1..n}, j={1..m}
(x,y,z) can be either 
  - cartesian coordinates (x,y,z) or
  - cylindrical coordinates (theta, z, r), theta \in {0..2pi}
  - spherical coordinates (theta, phi, r), theta \in {-pi/2..pi/2}
                                         , phi \in {0..2pi}

* .xyz format: ascii file containing unstructured cartesian data:
 x y z (one triplet / line).

  - If the first 2 characters of the first line are "#+" (like
in the sample file spiral.xyz), the file is supposed to contain
a 1d curve in the 3d space. Successive points are simply connected by
a segment.

  - Otherwise, the file is supposed to represent a surface in 3d passing
through all the given points. A 2d Delaunay mesh is first generated using
the (x,y) coordinates. It implies two important things:

    1/ The (x,y) coordinates must be distinct up to a tolerance
       parameter which depends on the domain size. If two (x,y) points 
       are equal according to this tolerance, you get an error message:
       *** merged points: 3 6
       meaning that the point number 3 and 6 are equal in the (x,y)
       plane, even if their z coordinates are different.

    2/ The Delaunay mesh support is the convex enveloppe of the cloud
       of (x,y) points. Don't expect to draw a star with an .xyz file.

* .pgm and .pbm image formats can also be read. They must be in ascii
format (no raw or binary format).

* In addition, surfaces given by an equation z=f(x,y) can
be plotted without file. The equation must be written in fortran
synthax, i.e. using the following operators. + - * / ** sin cos etc...

The format c3d is completely described by the program 
src/various/create_c3d.f

c3d files can be translated into ascii files by "clairc3d"
The reverse action (ascii -> binary) is done by "obscurc3d"

Scalar and vector nodal data an be associated to 3d surfaces using
the same file format than for meshes.