Provided by: xnecview_1.35-7.1_amd64 bug

NAME

       xnecview - A program for visualizing NEC2 input and output files

SYNOPSIS

       xnecview [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
       themselves.

       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 (impedance 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 distribution of the radiation.
       Window 2 shows a set of graphs of several quantities (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 (additionally,  keep  CTRL
              depressed  to  drag  only a partial picture for higher speed); alternatively, click
              left mouse button for zooming 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 helpful 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   polarization,   or   only   the
              horizontal/vertical/left-hand  circular/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 frequency,  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 comparison).  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;  furthermore,  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 radiation 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 'currents' 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 current 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
       polarized 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-hand 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 horizontal.

       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 calculation; 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 correct 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  surrounding  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 reality 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 magnitude of the charge,  while  the  colour
       shows the sign: cyan for positive 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) currents, 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 controlled 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, respectively.  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 contain 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)