.\"
.de Id
..
.de Sp
.if n .sp
.if t .sp 0.4
..
.TH field 1rheolef "rheolef-6.5" "rheolef-6.5" "rheolef-6.5"
.\" label: /*Prog:field
.SH NAME
\fBfield\fP -- plot a field
.\" skip: @pindex field
.\" skip: @cindex plotting
.\" skip: @cindex plotting data
.\" skip: @fiindex @file{.field} field
.PP
.SH SYNOPSIS

.\" begin_example
.Sp
.nf
        field \fIoptions\fP \fIfilename\fP[.field[.gz]]
.Sp
.fi
.\" end_example
.SH DESCRIPTION

Read and output a finite element field from file.
.SH EXAMPLE

.\" begin_example
.Sp
.nf
        field square.field
        field square.field -bw
        field box.field
.Sp
.fi
.\" end_example
.SH INPUT FILE SPECIFICATION

.\" begin table

.\" start item
.TP
.B \fIfilename\fP
specifies the name of the file containing
the input field.

.\" start item
.TP
.B -
read field on standard input instead on a file.

.\" skip: @cindex RHEOPATH environment variable
.\" start item
.TP
.B -I\fIdir\fP
.\" start item
.TP
.B -I \fIdir\fP
Add \fIdir\fP to the rheolef file search path.
This option is usefull e.g. when the mesh .geo and the .field fikes are in
different directories.
This mechanism initializes a search path given by the environment variable `\fBRHEOPATH'\fP.
If the environment variable `\fBRHEOPATH'\fP is not set, the default value is the current directory.


.\" skip: @clindex catchmark
.\" start item
.TP
.B -catchmark \fIlabel\fP
Jump accross the file to the specifield label.
Label start at the begining of a line, preceded by a `\fB#'\fP mark (see see catchmark(4)).
.\" end table
.PP
.SH OUTPUT FILE FORMAT OPTIONS

.\" begin table
.\" start item
.TP
.B -field
output field on standard output stream in field text file format.
.\" skip: @toindex @code{gmsh}
.\" skip: @fiindex @file{.gmsh} mesh file
.\" skip: @fiindex @file{.gmsh_pos} data file
.\" start item
.TP
.B -gmsh
output field on standard output stream in gmsh text file format.
.\" start item
.TP
.B -gmsh-pos
output field on standard output stream in gmsh-pos text file format,
suitable for mesh adaptation purpose.
.\" skip: @toindex @code{bamg}
.\" skip: @fiindex @file{.bamg} mesh file
.\" skip: @fiindex @file{.bamg_bb} data file
.\" start item
.TP
.B -bamg-bb
output field on standard output stream in bamg-bb text file format,
suitable for mesh adaptation purpose.
.\" skip: @cindex graphic render
.\" skip: @cindex image file format
.\" skip: @cindex graphic render
.\" skip: @fiindex @file{.png} image
.\" skip: @fiindex @file{.gif} image
.\" skip: @fiindex @file{.jpg} image
.\" skip: @fiindex @file{.ps} image
.\" skip: @fiindex @file{.pdf} image
.\" start item
.TP
.B -image-format \fBstring\fP
The argument is any valid image format, such as
bitmap \fBpng\fP, \fBjpg\fP, \fBgif\fP or vectorial \fBps\fP or \fBpdf\fP
image file formats, and that could be handled by the corresponding render.
The output file is e.g. \fIbasename\fP.\fBpng\fP when \fIbasename\fP
is the name of the mesh, or can be set with the \fB-name\fP option.

.\" end table
.PP
.SH GETTING INFORMATION

.\" begin table
.\" start item
.TP
.B -min
.\" start item
.TP
.B -max
print the min (resp. max) value of the scalar field and then exit.
.\" end table
.PP
.SH RENDER OPTIONS

.\" begin table

.\" skip: @toindex @code{gnuplot}
.\" start item
.TP
.B -gnuplot
use \fBgnuplot\fP tool.
This is the default in one and two dimension.
.\" skip: @toindex @code{mayavi}
.\" start item
.TP
.B -mayavi
use \fBmayavi\fP tool.
This is the default for tridimensional geometries.
.\" end table
.PP
.SH RENDERING OPTIONS

.\" begin table
.\" start item
.TP
.B -color
.\" start item
.TP
.B -gray
.\" start item
.TP
.B -black-and-white
.\" start item
.TP
.B -bw
Use (color/gray scale/black and white) rendering.
Color rendering is the default.
.\" start item
.TP
.B -elevation
.\" start item
.TP
.B -noelevation
For two dimensional field, represent values as elevation
in the third dimension.
The default is no evelation.
.\" start item
.TP
.B -scale \fIfloat\fP
applies a multiplicative factor to the field.
This is useful e.g. in conjonction with the \fBelevation\fP option.
The default value is 1.
.\" start item
.TP
.B -stereo
.\" start item
.TP
.B -nostereo
Rendering mode suitable for red-blue anaglyph 3D stereoscopic glasses.
This option is only available with \fBmayavi\fP.
.\" start item
.TP
.B -fill
isoline intervals are filled with color.
This is the default.
.\" start item
.TP
.B -nofill
draw isolines by using lines.
.\" start item
.TP
.B -cut
.\" start item
.TP
.B -nocut
Cut by a specified plane.
The cutting plane is specified by its origin point and normal vector.
This option requires the \fBmayavi\fP code.
.\" start item
.TP
.B -origin \fIfloat\fP [\fIfloat\fP [\fIfloat\fP]]
set the origin of the cutting plane.
Default is (0.5, 0.5, 0.5).
.\" start item
.TP
.B -normal \fIfloat\fP [\fIfloat\fP [\fIfloat\fP]]
set the normal of the cutting plane.
Default is (1, 0, 0).
.\" start item
.TP
.B -iso [\fIfloat\fP]
do draw 3d isosurface. When the optional float is not provided,
a median value is used.
This option requires the \fBmayavi\fP code.
.\" start item
.TP
.B -noiso
do not draw isosurface.
.\" start item
.TP
.B -n-iso \fIint\fP
For 2D visualizations, the isovalue table contains
regularly spaced values from fmin to fmax, the bounds
of the field.
.\" skip: @cindex projection
.\" start item
.TP
.B -proj
Convert all selected fields to Pk-continuous approximation by using a L2 projection.
.\" start item
.TP
.B -round [\fIfloat\fP]
Round the input up to the specifiexd precision.
This option, combined with \fB-field\fP, leads to a round filter.
Usefull for non-regression test purpose, in order
to compare numerical results between files with a limited precision,
since the full double precision is machine-dependent.

.\" skip: @cindex vorticity
.\" skip: @cindex stream function
.\" start item
.TP
.B -n-iso-negative \fIint\fP
The isovalue table is splitted into negatives and positives values.
Assume there is n_iso=15 isolines: if 4 is requested by this option,
then, there will be 4 negatives isolines, regularly spaced
from fmin to 0 and 11=15-4 positive isolines, regularly spaced
from 0 to fmax.
This option is usefull when plotting e.g. vorticity or stream
functions, where the sign of the field is representative.
.\" start item
.TP
.B -subdivide int
When using a high order geometry, the number of points per edge used to draw
a curved element. Default value is the mesh order.

.\" start item
.TP
.B -deformation
Render vector-valued fields as deformed mesh
using \fBmayavi\fP or \fBgnuplot\fP.
This is the default vector field representation.

.\" start item
.TP
.B -velocity
Render vector-valued fields as arrows using \fBmayavi\fP.

.\" end table
.SH COMPONENT EXTRACTION AND DOMAIN REDUCTION

.\" begin table
.\" start item
.TP
.B -comp \fIint\fP
.\" start item
.TP
.B -comp \fIstring\fP
Extract the i-th component of a vector-valued field.
For a tensor-valued field, indexing components as "00", "01", "11"... is supported.
.\" start item
.TP
.B -domain \fIname\fP
Reduce the visualization to the specified domain.
.\" end table
.PP
.SH OTHERS OPTIONS

.\" begin table
.\" start item
.TP
.B -verbose
print messages related to graphic files created and
command system calls (this is the default).

.\" start item
.TP
.B -noverbose
does not print previous messages.

.\" start item
.TP
.B -clean
clear temporary graphic files (this is the default).

.\" start item
.TP
.B -noclean
does not clear temporary graphic files.

.\" start item
.TP
.B -execute
execute graphic command (this is the default).

.\" start item
.TP
.B -noexecute
does not execute graphic command. Generates only
graphic files. This is usefull in conjuction with the
\fB-noclean\fP command.
.\" end table
.SH FIELD FILE FORMAT

It contains a header and a list values at degrees of freedom.
The header contains the \fBfield\fP
keyword followed by a line containing a format version number (presently 1),
the number of degrees of freedom (i.e. the number of values listed),
the mesh file name without the `\fB.geo'\fP extension
the approximation (e.g. P1, P2, etc), and finaly the list of values:
A sample field file (compatible with the sample mesh example presented in
command manual; see geo(1)) writes:
.\" begin_example
.Sp
.nf
        field
        1 4
        square
        P1
        0.0
        1.0
        2.0
        3.0
.Sp
.fi
.\" end_example
.SH EXAMPLES

.\" begin_example
.Sp
.nf
    field cube.field -cut -normal 0 1 0 -origin 0.5 0.5 0.5 -vtk
.Sp
.fi
.\" end_example
This command send to \fBvtk\fP the cutted 2d plane of the 3d field.
.\" begin_example
.Sp
.nf
    field cube.field -cut -normal 0 1 0 -origin 0.5 0.5 0.5 -text > cube-cut.field
.Sp
.fi
.\" end_example
This command generates the cutted 2d field and its associated mesh.
.\" begin_example
.Sp
.nf
    field cube.field -iso 0.5 -plotmtv
.Sp
.fi
.\" end_example
This command draws the isosurface.
.\" begin_example
.Sp
.nf
    field cube.field -iso 0.5 -text > isosurf.geo
.Sp
.fi
.\" end_example
This command generates the isosurface as a 3d surface mesh in
`\fB.geo'\fP format. This is suitable for others treatments.
.PP
.SH INPUT FILE FORMAT OPTIONS

TODO
.PP
.SH FILE FORMAT CONVERSIONS

 TODO
.PP
.SH GETTING INFORMATION

 TODO
.PP
.\" skip start:AUTHOR:
.\" skip start:DATE:

.\" END

.\" LENGTH = 2
.SH SEE ALSO
catchmark(4), geo(1)