.ds Aq ’
The vfplot utility creates PostScript plots of two-dimensional vector fields using curved arrows or other glyphs.
Fields can be built-in (see -t) or specified by data (see -F and the section on input formats below).
All options have a long version and most have a short version; those without are intended mainly for development purposes.
See the note below for details on unit, pen and fill specification.
--animate
Adaptive mode. Create an output file for each step of the dimension two iteration, the files named anim.n.m.eps where n and m are the main and inner iteration numbers.
-a --aspect value
Specify the glyph aspect: the ratio of its length to width. For the arrow glyph try a value around 8.0, for the wedge and triangle glyphs try around 4.0.
--break break
Adaptive mode. Break off processing early. Use the a value of list to see possible break types.
--cache n
Adaptive mode. Cache the metric tensor on an n x n grid. On a rectangle n is the smaller of dimensions of the grid.
--decimate-contact value
Specify the contact value of intersection, as used in the decimation: after decimation there will be no ellipses a contact distance of less than value between them. A value of 1.0 correspond to the usual intersection, 0.8 will allow ellipses to intersect slightly, 1.2 will give no intersection and a small margin.
-d --domain file
Read the functionAqs domain from the specified file. The domain file is useful when the vector field is not defined on the whole of a rectangle. See dom(5) for details on the file format.
-D --domain-pen pen
Draw the functionAqs domain using the specified pen.
--dump-domain file
Write the domain to the specified file.
--dump-vectors file
Write the vector field to the specified file, useful in exporting to other formats. The format is described in sag(5) .
-e --epsilon eps
In parts of the field where the curvature is small the difference between a curved and a straight arrow of the same length is small. If it is less than epsilon then a straight arrow will be drawn.The author cannot tell the difference between values less than 0.5 points, -e 0.5p, which is the default. A value of 0.1 points corresponds to 1 pixel on a 600 dpi printer and there is no sense in a value less than 0.01 points due to floating point truncation in the PostScript output. Choosing a large value results in all glyphs being straight.
-E --ellipse
Draw the bounding ellipses.
--ellipse-pen pen
Use the specified pen for the bounding ellipses.
--ellipse-fill fill
Use the specified fill for the bounding ellipses.
-f --fill fill
Specify the glyph fill.
-F --format type
Give the format of the data-files to be used as input. See the INPUT FORMATS section below.
-g --glyph type
Select the glyph to draw:arrow
An arrow with a curved shaft of uniform width and a (uncurved) triangular head;triangle
A circularly curved triangle with the sharp end in the direction of the field;wedge
A circularly curved triangle with the blunt end in the direction of the field: the triangle glyph reversed.
-G --graphic-state file
Use specified file for the graphic state. If the file does not exist then the graphic state will be written to it. If the file does exist then it is read and the state used for the plot (rather than calculating it anew).The point is to cache the results of expensive processing so that one can adjust the final image appearance: the line thicknesses, fill colours, glyph type, and so on.
The file format is described in vgs(5) .
-h --help
Brief help.
-H --head length/width
Specify the arrowhead geometry where the length and width values are relative to the shaft width. A reasonable value might be 2.2/1.7. Note that the values are ratios and so dimensionless, units will be ignored.
--histogram file
Adaptive mode. Write data for a histogram of Perram-Wertheim distances of near neighbours to the specified file.
-i --iterations outer/inner
Adaptive mode. Specify the number of iterations in the Lennard-Jones simulation.
-j --threads num
Use the specified number of threads in CPU-intensive operations like the force accumulation. For multi-CPU hardware this option can increase execution speed substantially.The default behaviour is to use as many threads as there are CPUs found on the system, if it is possible to determine this number. Otherwise one thread is used.
This option is only available if pthread (POSIX thread) support was found during compilation (and if the --disable-pthread option was not specfied in configuration).
-k --ke-drop dB
Adaptive mode. Delay termination of the dynamic until the kinetic energy has dropped from the value at the end of detrucation (about 4/5-ths of the way through) by the specified decibels. Try a value of around 5.
-l --length min/max
Specify bounds on the glyph lengths with an optional unit. Glyphs outside this range will not be drawn.
-L --decimate-late
Adaptive mode. Decimate the boundary ellipses after edges have been added, not before. This may result in better boundaries for complex domains.Use of this option can lead to holes in the boundary near corners: the --decimate-contact option can be employed to reduce these effects.
-m --margin major/minor/rate
Adaptive mode. Give the margin to pad the glyphs. The major and minor are the margins of a zero-sized glyph (with optional units) and rate is the rate at which the margins increase with respect to the glyphAqs size. In other words, the margin used along the major axis is major + rate x length.The rate determines how sparse or dense the glyphs are at different sizes. With rate > 1, large glyphs are sparse, small glyphs dense, for rate < 1, large glyphs are dense, small glyphs sparse. A negative value of rate is accepted, the margins decrease from major and minor until they are zero and then remains zero. The visual result is that small glyphs are sparse, large glyphs congested.
Small values of major and minor will lead to a large numbers of small glyphs (and a long execution time).
Try -m 3m/3m/0.5 as a starting point for experimentation.
-n --numarrows num
Hedgehog mode. The number of glyphs to be used in the plot (roughly).
--network pen
Adaptive mode. Specify the pen used to draw the neighbours network in adaptive mode. For debugging.
-o --output file
Plot output to file rather than standard output.
-O --output-format format
Output is in the specified format:eps
the encapulated PostScript format (the default);povray
a scene description in the POV-Ray rendering format.
--overfill factor
Adaptive mode, the initial number of glyphs is factor times the estimated optimal packing number. Useful when there is a singularity in the field which can cause the optimal packing number to be underestimated. Try a value of 2.5 or 3, increasing it until the plots become filled.
-p --placement strategy
Specify the glyph placement strategy:hedgehog
The glyphs are placed on a regular rectangular grid;adaptive
The glyphs are placed with a molecular dynamics (Lennard-Jones) simulation of their bounding ellipses.
-P --pen pen
Specify the pen used to draw the glyph outlines.
-s --scale factor
Scale glyph size by the specified factor.
-S --sort type
Sort the glyphs before plotting (to have the largest on top, etc). Use the value list to see the sort-types available.
-t --test field
Plot a test-field rather than data. Use the value list to see the fields available.
--timestep dt
Adaptive mode. Set the timestep for the Lennard-Jones simulation. Mainly for debugging and development.
-v --verbose
Verbose operation.
-V --version
Version information.
-w --width val
The width of the output image with an optional unit.
-W --height val
The height of the output image with an optional unit. The odd choice of character for this option is due to scarcity, and the fact that one does not often need to specify the height.Note that width and height cannot be specified together, the aspect-ratio of the field is preserved by this program for deep mathematical reasons. Actually laziness.
Several input formats can be used to pass vector fields to vfplot. Usually the file format will be autodetected, but if this fails one can use the -F option to specify the format.
sag
A simple ASCII grid format described in sag(5) , intended to be easy to write.
mat
Matlab binary format, as produced by the Matlab save command (with Octave add the -mat-binary option). The file should contain matrices u and v (which must be of the same size) interpreted as the components of the field. The file may optionally contain 2x1 matrices xrange and yrange which will be interpreted as the minimum and maximum x and y values (if not present the matrix indices will be taken as the x and y values).
grd2
A pair of GMT(1) grd (netCDF) files representing the components of the vector field. This is the recommended data format since it is compact, portable and the GMT package provides excellent support for smoothing and clipping the data grids (as is often needed by vfplot).
gfs
A simulation file from the Gerris flow solver.
Options of length take units specified by appending a unit: p for PostScript points, P for printerAqs points, i for inches, m for millimetres, c for centimetres.
A pen is given in the form width/grey where the grey is a value between 0 and 255.
A fill is either a single integer in the range 0-255 for greyscale, or a red/green/blue triple for colour.
In verbose operation (with the -v option), the program prints information of the progress of the Lennard-Jones annealing with columns of numbers. These indicate:
n
The number of the outer iteration (see -i option).
glyph
The number of glyphs remaining in the simulation. This value is reduced as glyphs escape from the domain during the course of the simulation, or as a result of decimation (see the ocl data below).
ocl
During the decimation phase of the simulation those glyphs which are overclose to their neighbours are removed from the simulation. This column shows the number of glyphs which have been removed in this way. This will result in a decrease in the glyph value.A reduction in the glyph value in excess of the value in the ocl value indicates that a glyph has escaped from the simulation domain. This is quite normal (and even desirable) but excessive amounts of excapees can indicate that the boundary of the domain is badly filled with glyphs, leaving a hole through which others can escape.
edge
The calculation of inter-glyph forces only needs to be performed for near neighbours, and towards this end a graph of near neighbours is created for each outer iteration. The value in this column shows the number of edges in this graph.
e/g
The number of edges divided by the number of glyphs.
ke
The logarithm (base 10) of the kinetic energy of the simulation.
prop
The ratio of the combined area of the ellipses bounding the glyphs to the total area of the domain. Typically at the start of the simulation the value will be larger than one (since the domain is overfilled with ellipses), it will decrease to around one during the decimation phase, then decrease slowly to pi divided by the square root of 12 (around 0.9) at the end of the simulation.Note that with a complex boundary the final value may be larger than 0.9, but in general a value which is smaller indicates an underfilled plot.
For a hedgehog plot of a 3 point electrostatic test field
vfplot -v -f255 -D2 -s0.3 -n300 -t electro3 -p hedgehog -o electro3.eps-f255 -D2 -s0.3 -n300 -t electro3 -p hedgehog -o electro3.eps
To produce an adaptive test-plot of inviscid flow around a cylinder, try
an adaptive test-plot of inviscid flow around a cylinder, try
vfplot -v -f150 -D2 -s0.5 -t cylinder -p adaptive -o cylinder.ps-f150 -D2 -s0.5 -t cylinder -p adaptive -o cylinder.ps
J.J. Green (j.j.green@gmx.fr)
sag(5) , dom(5) , vgs(5) , convert(1) , GMT(1) .