Name

vfplot — plot vector fields with curved arrows.

Synopsis

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

DESCRIPTION

The vfplot utility creates PostScript plots of two-dimensional vector fields using curved arrows or other symbols.

Fields can be built-in (see --test) or specified by data (see --format 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.

General

-h --help

Brief help.

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

-L --log-path path

Write run-time information to the specified path. If the file does not exist then it will be created. If the file does exist then it will be appended.

See also the --log-level option.

--log-level level

Log at the specified level, one of trace, debug, info, warn, error or fatal; with their usual meanings. If the --log-path option has not been specified then this option has no effect.

-v --verbose

Verbose operation.

-V --version

Version information.

Plot tyoe, input, output

-F --format type

Give the format of the data-files to be used as input. See the INPUT FORMATS section below.

--grid-range floats

When input data lacks x-y information (as with CSV input), specify the x-y extent of the input grid as x miumum/maximum then y minimum/maximum, joined with slashes.

Example: --grid-range 0/5/0/1.

--grid-size ints

When the input grid uses explicit indices (as with CSV input) specify the size of the grid with a pair of integers: the number in each dimension joined with slashes.

Example: --grid-size 32/128. In this case (31, 127) will be the maximal index in the grid.

Note that for some (most) input formats the grid size cannot be modified; for those formats this option will cause the program to error.

-o --output path

Plot output to path 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.

-p --placement strategy

Specify the symbol placement strategy:

hedgehog

The symbols are placed on a regular rectangular grid;

adaptive

The symbols are placed with a molecular dynamics (Lennard-Jones) simulation of their bounding ellipses.

-t --test field

Plot a test-field rather than data. Use the value list to see the fields available.

Plot features

-c --crop lengths

Crop the final image by the specified lengths.

In many cases (in particular, in fluid dynamics), one has an infinite or near infinite field in mind when plotting, so the edge effects (whereby the arrows will be aligned with the boundary) are undesirable. Then the --crop option is useful to generate a plot without those effects, giving the impression of boundlessness.

The lengths give the amount to crop from each edge: the values are with respect to the plot output and have optional units. If four values are given (as in W/E/S/N) then these are used for each of the left, right, bottom and upper parts of the plot, if two then these are applied to the vertical sides (East and West) and the horizontal sides (South and North) respectively. If a single value, that is applied to all sides.

Note that cropping will reduce the size of the plot, so one should increase the --height or --width values by the amount cropped to recover a plot of the desired size.

Note also that cropping is not implemented for POV-Ray output, the three-dimensionality makes the effect look unnatural and increases rendering time enormously; better to use the rendering window for this purpose.

-d --domain path

Read the function's domain (boundary) from the specified path. The domain file is useful when the vector field is not defined on the whole of a rectangle. See vfplot-geojson (5) for details on the file format.

If this option is not given then built-in plots will use their default domain; for data plots a domain will be built and can be output with the --dump-domain option.

-D --domain-pen pen

Draw the function's domain using the specified pen.

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

Symbols

The type and appearance of the plotted symbols.

-a --aspect value

Specify the symbol aspect: the ratio of its length to width. For the arrow symbol try a value around 8.0, for the triangle symbol try around 4.0.

-f --fill fill

Specify the symbol fill.

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

-l --length min/max

Specify bounds on the symbol lengths with an optional unit. Symbols outside this range will not be drawn.

-n --number num

The number of symbols to be used in the plot (roughly).

The interaction with the --scale option (which controls the arrow size) depends on the plotting mode:

hedgehog

There is no restriction: either, both or none may be specified, but having both large may result in arrow collisions.

adaptive

The --number option cannot be used with the --scale option. The reason is that the --number value is used to calculate a value for --scale.

-P --pen pen

Specify the pen used to draw the symbol outlines.

-s --scale factor

Scale symbol size by the specified factor.

-S --symbol type

Select the symbol 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;

--sort type

Sort the symbols before plotting (to have the largest on top, etc). Use the value list to see the sort-types available.

Hedgehog mode

Arrow placement on a regular grid. There are no options specific to this mode.

Adaptive mode

Arrow placement by a packing of the bounding ellipses.

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

-i --iterations outer/inner

Specify the number of iterations in the Lennard-Jones simulation.

--overfill factor

The initial number of symbols 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.

-k --ke-drop dB

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.

-m --margin major/minor/rate

Give the margin to pad the symbols. The major and minor are the margins of a zero-sized symbol (with optional units) and rate is the rate at which the margins increase with respect to the symbol'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 symbols are at different sizes. With rate > 1, large symbols are sparse, small symbols dense, for rate < 1, large symbols are dense, small symbols 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 symbols are sparse, large symbols congested.

Small values of major and minor will lead to a large numbers of small symbols (and a long execution time).

Try -m 3m/3m/0.5 as a starting point for experimentation.

--network-pen pen

Specify the pen used to draw the neighbours network in adaptive mode. For debugging.

--timestep dt

Set the timestep for the Lennard-Jones simulation. Mainly for debugging and development.

Advanced

Mainly for development.

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

Converting these plots to an animation is outside the scope of this program, typically one would convert each plot to the PNG format with convert (1) and then convert those files to an animation with ffmpeg (1) . See src/misc/animation in the source of the package for an example of this approach.

--animate-dir directory

As for the --animate option, but use the passed directory as the location into which to write the animation files. The specified directory should already exist.

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

--dump-domain path

Write the domain to the specified path.

--dump-vectors path

Write the vector field to the specified path, useful in exporting to other formats. The format is described in vfplot-csv (5) .

Note that the output is pixel-aligned, in other words the samples are at the centres of pixels.

-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 symbols being straight.

-G --graphic-state path

Use specified path 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, symbol type, and so on.

The file format is JSON and contains an object with an array of arrows objects and an array of neighbours. These should be self-explanatory.

--histogram path

Adaptive mode. Write data for a histogram of Perram-Wertheim distances of near neighbours to the specified path.

--statistics path

Write statistics on the processing to the specified path; the format is JSON and should be self-explanatory.

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.

csv

A simple CSV grid format described in vfplot-csv (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.

One can add extra characters to the unit if that makes it easier to read (in, mm and so on), those will be ignored.

PENS

A pen is given in the form width/colour where the width is a floating point value (with optional unit) and the optional colour is as described in the fill section below, default black.

For example, 1 is a black pen with width one PostScript point; 1pt/0 is exactly the same; 0.2mm/red is a 0.2 mm red pen.

FILLS

A fill is:

  • A single integer in the range 0–255, for greyscale

  • A red/green/blue triple of 0–255 values, for colour, or

  • A named colour: "red", "beige" and so-on, as used commonly on the web, the full list of names can be found in Section 4.4 of the SVG-11 specification.

RUNTIME INFORMATION

In verbose operation (with the --verbose 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).

symbol

The number of symbols remaining in the simulation. This value is reduced as symbols 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 symbols which are overclose to their neighbours are removed from the simulation. This column shows the number of symbols which have been removed in this way. This will result in a decrease in the symbol value.

edge

The calculation of inter-symbol 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 symbols.

ke

The logarithm (base 10) of the kinetic energy of the simulation.

prop

The ratio of the combined area of the ellipses bounding the symbols 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 -m2/5/0.25 -D2 -P0.5 -n300 -t cylinder -p adaptive -o cylinder.ps

AUTHOR

J.J. Green ()

SEE ALSO

vfplot-csv (5) , vfplot-geojson (5) , convert (1) , GMT (1) .