XNECVIEW(1)XNECVIEW(1)NAMExnecview - A program for visualizing NEC2 input and output files
SYNOPSISxnecview [options] filename [filename....]
DESCRIPTION
Xnecview can visualize NEC2 input (structure of the antenna model) and
output data files (gain as a function of direction, gain and impedance
as a function of frequency). Structure and gain are shown as a three-
dimensional picture which can be rotated by the mouse. The program
will determine the type of data (input or output) from the files them‐
selves.
More information and some examples can be found on the web at
http://www.cs.utwente.nl/~ptdeboer/ham/xnecview/
USAGE
On the commandline, the program expects to find one or more filenames,
each containing either NEC2 structure (input) data, or output data (im‐
pedance and radiation pattern). The program will determine the type of
data from the data itself. Depending on the data found in the file(s)
specified, one or two windows are opened. Window 1 shows a 3D plot of
the structure (wires etc.) of the antenna, and/or the spatial distribu‐
tion of the radiation. Window 2 shows a set of graphs of several quan‐
tities (SWR, gain, etc.) as a function of frequency.
Window 1
This window shows the antenna's structure and/or the gain pattern.
Initially, the Z axis points up, the X axis points to lower left, and
the Y axis points to lower right (unless you changed those settings in
the source code).
The view can be manipulated using the mouse as follows:
rotate move mouse while holding left button depressed (additionally,
keep CTRL depressed to drag only a partial picture for higher
speed)
zoom move mouse up/down while holding middle button depressed (addi‐
tionally, keep CTRL depressed to drag only a partial picture for
higher speed); alternatively, click left mouse button for zoom‐
ing in or click right mouse button for zooming out.
move picture
move mouse while holding right button depressed (additionally,
keep CTRL depressed to drag only a partial picture for higher
speed)
go back to original view
click middle mouse button
The view can also be rotated using the arrow keys. The keys PageUp and
PageDown select a different frequency, if radiation data is available
at more than one frequency.
The top of the window contains a set of buttons and other indicators;
from left to right these are:
quit to stop the program; keyboard shortcut: Q
reload to reload the files; keyboard shortcuts: R and .
export for saving the picture as an (encapsulated) PostScript or a PNG
file.
none/struct/+tags/currents/animation
toggles displaying of antenna structure on and off; in '+tags'
mode, segment tag numbers are displayed too (which can be help‐
ful when trying to modify an antenna structure). For display of
currents and animations, see below.
none/slice/frame/opaque/near
toggles display of gain pattern: either none is shown, or only
slices in the coordinate planes, or the entire 3D structure (of
course subject to the availability of data in NEC's output file,
and thus ultimately to the RP cards used in the input file).
The 3D structure can either be shown as a wire mesh (i.e.,
transparent), or as an opaque surface (i.e., with hidden lines
removed); the latter usually gives a clearer picture, but is
often somewhat slower, and is not available if the NEC output
data do not cover a theta range from 0 to 90 or 180 degrees, and
a phi range from 0 to between 270 and 360 degrees; note that the
gain surface is only opaque w.r.t. itself, not to other elements
of the picture such as the antenna structure. For display of
near fields, see under 'animation' below.
lin.P/lin.V/arrl/log
toggles gain scaling (linear in power, linear in voltage, ARRL-
style, or logarithmic with -40 dB at the center).
total/hor./vert./lhcp/rhcp/colour
determines the handling of radiation's polarization: whether the
gain shown is according to the total power regardless of polar‐
ization, or only the horizontal/vertical/left-hand circu‐
lar/right-hand circular component. Choosing "colour" also shows
the total power, but uses colour to show whether the radiation
is mostly linearly polarized, or lhcp or rhcp. This setting
also influences the gain-vs-frequency plots in window 2, and the
currents display in window 1 (see below).
X, Y and Z
rotate view to viewing along X, Y or Z axis respectively. A
gain scale will appear, with lines at several gain levels. All
of these gains are with respect to the maximum gain in the
entire set of output data.
Though xnecview should be quite liberal in accepting output data from
NEC, you might want to start out by using this line (card) in your
input:
RP 0, 37, 72, 1000, 0, 0, 5, 5
This will instruct NEC to calculate the gain at 5 degree intervals.
Window 2:
This window contains plots of several quantities as a function of fre‐
quency, if the NEC output file contains data for several frequencies.
The following quantities can be plotted:
SWR
real and imaginary part of the input impedance
phase and magnitude of the input impedance
If the antenna has multiple sources, SWR and impedance are only
plotted for whichever source's data appears first in the output
file.
maximum gain and corresponding front/back ratio
The gain as plotted is the maximum gain observed over the entire
radiation pattern; this may not be the direction in which the
antenna was supposed to radiate! The front/back ratio is just
the ratio of the maximum observed gain to the gain in the
exactly opposite direction; again, this may not be the
front/back ratio you're interested in, e.g. if the main lobe is
elevated so the 'back' direction points into the ground.
If a specific polarization (rather than total power) has been
chosen (by command-line option or by the button in the top row
of window 1), this also influences the graph. Two gain lines
then appear: a solid line showing the gain in the selected
polarization, and a dashed line showing the total gain (for com‐
parison). Also, two f/b lines appear: for both, the front power
is only the selected polarization component, while the back
power is also the selected polarization (solid line), or the
total power (dashed line).
direction (phi and theta) of maximum gain
vgain and corresponding front/back ratio
This is the gain in the direction towards viewer (as set by
rotating the picture in window 1) and the corresponding
front/back ratio.
The row of buttons at the top have the following functions:
quit to stop the program; keyboard shortcut: Q
reload to reload the files; keyboard shortcuts: R and .
export for saving the picture as an (encapsulated) PostScript or a PNG
file.
Z0=... for setting the reference impedance for SWR calculations; fur‐
thermore, the impedance plots are limited to 20*Z0.
maxgain, vgain, SWR, Re/Im, phi/abs, and dir
for toggling the display of the graphs.
Finally, if radiation pattern data is available, a vertical line over
the entire height of the window shows the frequency at which the radia‐
tion pattern is being shown in the other window. With a mouse click or
drag, or the keys PageUp, PageDown and arrow keys, another frequency
can be chosen.
Display of current distribution:
Window 1 can also be used to display the distribution of the current
flowing in the antenna wires, if this information is available in the
NEC output file(s); by default, it is, but it may be switched off by a
'PT' card in the NEC input. This display is enabled by selecting 'cur‐
rents' in the none/struct/+tags/currents menu. Then the thickness of
each wire segment indicates the magnitude of the current flowing there,
while the colour indicates its phase. At the bottom of the window a
few extra controls appear: two sliders for changing the colours and
scaling the thicknesses, and some buttons which are discussed below.
Contrary to what might be expected, the magnitude and phase of the cur‐
rent as plotted are not necessarily directly the values present in the
NEC output file. Taking that data directly would typically not result
in a meaningful display, since there is a 180 degree phase ambiguity:
if the endpoints of a wire are exchanged, then the 'positive direction'
in that wire is reversed, so the phase calculated by NEC changes by 180
degrees even though the antenna and its properties don't change.
Therefore, it is preferable to project the current in each segment onto
some reference direction, e.g., horizontal. The result of this is a
measure for the contribution of that segment to the horizontally polar‐
ized radiation of the antenna. The polarization actually used, is the
one selected by the polarization button in the top row; choosing
"total" there (default), switches the projection operation off, so
'raw' phases and magnitudes are used. If left- or right-hand circular
polarization is selected, the projection is also not performed, but
every current gets an extra phase shift proportional to the angle its
projection perpendicular to the viewing direction makes with horizon‐
tal.
Actually, the phase displayed as discussed above is still not very
interesting. Consider the following: if one segment is further away
from the target to which the antenna is supposed to radiate than
another segment, then the radiation from the former segment will incur
a larger delay before reaching the target than the radiation from the
latter segment. Effectively, this introduces another phase-shift,
whose value depends on the position of the segments in space. Xnecview
can compensate for this effect, by calculating this additional phase-
shift in the direction toward the viewer (i.e., perpendicular to the
screen); this option can be switched on and off by the first button on
the bottom row.
The second button locks the direction used in the phase-shift calcula‐
tion; its use can best be explained by an example. Consider a yagi
antenna which is aimed along the X axis. Then in order to get the cor‐
rect phase-shift, one needs to rotate the picture such that the X axis
points to the viewer. Unfortunately, in that orientation all elements
are behind each other, so it is impossible to distinguish them in order
to compare their colours. This problem is resolved by pressing the
'lock' button to lock the phase-shift calculation and then rotating the
antenna to an orientation in which the elements are distinguishable.
Animated display of currents, charges and near fields:
Antennas as modeled by NEC are driven by a source (or more than one)
which applies a voltage or current to the antenna, varying sinusoidally
in time. Consequently, the currents in the antenna wires, the charges
on the wires, and also the electric and magnetic field in the surround‐
ing space, vary sinusoidally in time too, at the same frequency as the
driving force, but possibly with a different phase. The display of the
currents as described in the previous section represents these time-
varying currents by their amplitude (thickness in the picture) and
phase w.r.t. the source (colour in the picture).
For some purposes, this is not very intuitive. Therefore, xnecview can
also show the currents (and charges and field strengths) exactly as
they vary in time: an animation. Basically, the process which in real‐
ity happens at a frequency of thousands or more cycles per second is
slowed down to a frequency of about 1 cycle per second, and at that
speed the currents and charges are displayed.
The animated display of currents and charges is enabled by selecting
'animation' from the none/struct/+tags/currents/animation menu. Then
each segment of each wire is replaced by a short blue line, one end of
which is at the center of the wire, while the other end indicates the
direction and (relative) magnitude of the current. Furthermore, around
each segment a square is drawn. This square represents the charge built
up on that segment. The size of the square is proportional to the mag‐
nitude of the charge, while the colour shows the sign: cyan for posi‐
tive charge, magenta for negative.
The animated display of the electric and magnetic field near the
antenna is chosen by selecting 'near' from the none/slice/frame/near
menu. Then at every point for which near field data is found in the
NEC output file, three coloured lines (vectors) are drawn. A red one
indicates the direction and (relative) magnitude of the electric field,
and a green one indicates the direction and (relative) magnitude of the
magnetic field. From the electric and magnetic field vectors, the so-
called Poynting vector is calculated, and displayed in yellow. This
vector can be interpreted as the flow of energy; see a textbook on
electromagnetic theory for details.
When either or both of the animated displays is selected, an additional
set of controls appears at the bottom of the window. The left four of
these are sliders to control the scaling of (from left to right) cur‐
rents, charges, electric and magnetic field strength. To the right of
these, an on/off control labelled 'P' is shown, which controls whether
or not the Poynting vectors are drawn. The rightmost slider controls
the speed of the animation: if your computer is fast enough, the number
at the slider is the number of animated cycles per second. By setting
this slider to 0, or hitting the 'z' key, the animation can be frozen.
Then the phase can be changed back and forth by typing '<' and '>' on
the keyboard.
Obviously, xnecview can only show currents, charges and near fields if
such information is available in the NEC output file being visualized.
As discussed earlier in this manual, the inclusion of currents is con‐
trolled by the PT card in the NEC input. The inclusion of charge
information is controlled by the PQ card, and the calculation of near
electric and magnetic fields is controlled by NE and NH cards, respec‐
tively. Examples are:
PQ 0, 0
NE 0, 1,20,20, 0,0.05,0.05, 0,0.05,0.05
NH 0, 1,20,20, 0,0.05,0.05, 0,0.05,0.05
These instruct NEC to include the charge information, and to calculate
the near fields at 20 x 20 points in a grid with stepsize 0.05, in the
Y-Z-plane. For more information see NEC documentation.
COMMAND-LINE OPTIONS
In normal usage of xnecview, command-line options (other than the names
of the files to be displayed) are rarely needed. However, they can be
useful to bring xnecview quickly in the desired state, or to use
xnecview for non-interactive, automated generation of plots.
Command-line options can not only be given on the command line with
which xnecview is started, but they can also be embedded as a CM card
(line) in the NEC input file to be read. In order for the content of a
CM card to be recognized as xnecview options, the CM card should con‐
tain the word xnecview: (including the colon) before those options.
The following options are available:
-h, --help
show usage information
--struct
set structure view to 'struct'
--tags set structure view to 'struct+tags'
--currents
set structure view to 'currents'
--animation
set structure view to 'animation'
--slice
set radiation view to 'slice'
--frame
set radiation view to 'frame'
--opaque
set radiation view to 'opaque'
--near set radiation view to 'near field'
--linpower
set radiation scale linear in power
--linvoltage
set radiation scale linear in voltage
--arrl set radiation scale to ARRL style
--log set radiation scale to logarithmic
--pol=x
choose polarization; x may be total, hor, vert, lhcp, rhcp or
colour .
--qscale num
set charges scale (animation)
--iscale num
set currents scale (animation)
--escale num
set electric field scale
--hscale num
set magnetic field scale
--hidepoynting
hide Poynting vector in near field display
--afreq num
set animation frequency (Hz)
--aphase num
set animation phase (degrees)
--aupdate num
set animation update interval (milliseconds). Default is 100,
but on a slow computer and/or with a large data set it may be
useful to set the update interval higher. Conversely, on a fast
computer and with a simple data set, a smaller setting provides
smoother movement.
--freq num
set frequency (MHz)
--z0 num
set reference impedance (ohm)
--expeps filename
no X11 display, just export picture to .eps-file
--exppng
no X11 display, just export picture to .png-file (only available
if linked against the libpng library)
--view phi,theta,zoom,trx,try
set viewing direction and zoom
Note: typing 'v' in window 1 writes the current values for all of these
settings to the standard output.
AUTHOR
Pieter-Tjerk de Boer; Internet e-mail: pa3fwm@amsat.org, amateur
packet-radio: PA3FWM @ PI8DAZ.#TWE.NLD.EU.
XNECVIEW(1)
