Name

vfplot — plot vector fields with curved arrows.

Synopsis

vfplot [-a aspect] [-d file] [-D pen] [-e epsilon] [-E ellipse] [-f fill] [-F format] [-g glyph] [-G file] [-h ] [-i iter] [-j threads] [-H head] [-k dB] [-l length] [-L ] [-m margin] [-n num] [-o file] [-O format] [-p placement] [-P pen] [-s scale] [-S sort] [-t field] [-v ] [-w width] [-W height] file file...

DESCRIPTION

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).

OPTIONS

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 function's 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 function's 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 specified 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 detruncation (about 4/5ths 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 glyph's 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 encapsulated 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.

INPUT FORMATS

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.

UNITS

Options of length take units specified by appending a unit: p for PostScript points, P for printer's points, i for inches, m for millimetres, c for centimetres.

PENS

A pen is given in the form width/grey where the grey is a value between 0 and 255.

FILLS

A fill is either a single integer in the range 0-255 for greyscale, or a red/green/blue triple for colour.

RUNTIME INFORMATION

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 escapees 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.

EXAMPLES

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

To produce an adaptive test-plot of inviscid flow around a cylinder, try

vfplot -v -f150 -D2 -s0.5 -t cylinder -p adaptive -o cylinder.ps

AUTHOR

J.J. Green ()

SEE ALSO

sag(5), dom(5), vgs(5), convert(1), GMT(1).