plot-antenna 2.0__tar.gz → 2.2__tar.gz

{plot_antenna-2.0 → plot_antenna-2.2}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (C) 2022-23 Dr. Ralf Schlatterbeck Open Source Consulting.
+Copyright (C) 2022-25 Dr. Ralf Schlatterbeck Open Source Consulting.
 Reichergasse 131, A-3411 Weidling.
 Web: http://www.runtux.com Email: office@runtux.com
 All rights reserved

{plot_antenna-2.0/plot_antenna.egg-info → plot_antenna-2.2}/PKG-INFO

@@ -1,16 +1,15 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: plot-antenna
-Version: 2.0
+Version: 2.2
 Summary: Antenna plotting program for plotting antenna simulation results
 Home-page: https://github.com/schlatterbeck/plot-antenna
 Author: Ralf Schlatterbeck
 Author-email: Ralf Schlatterbeck <rsc@runtux.com>
-License: MIT License
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/schlatterbeck/plot-antenna
 Project-URL: Bug Tracker, https://github.com/schlatterbeck/plot-antenna/issues
 Platform: Any
 Classifier: Development Status :: 5 - Production/Stable
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Intended Audience :: Science/Research
@@ -25,6 +24,11 @@ Requires-Dist: plotly
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: kaleido; extra == "test"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: platform
+Dynamic: requires-python
 
 Antenna Plotting Program
 ========================
@@ -84,6 +88,31 @@ above. The pattern look smoother but a 3D-view in matplotlib_ will be
 very slow due to the large number of points. This problem does not occur
 when using the plotly_ backend.
 
+Sometimes we do not want the azimuth plot at the maximum elevation angle
+or the elevation plot at the maximum azimuth angle. You can specify the
+elevation angle for the azimuth plot with the ``--angle-elevation``
+option and the azimuth angle for the elevation plot with
+``--angle-azimuth``. An example azimuth plot of the same antenna at an
+elevation angle of 15° can be plotted with::
+
+    plot-antenna --azimuth --angle-elevation=15 test/12-el-1deg.pout
+
+.. figure:: https://raw.githubusercontent.com/schlatterbeck/plot-antenna/master/test/12-el-azi-angle-ele15.png
+    :align: center
+
+As you can see, the azimuth-plot is scaled to the maximum gain of the
+antenna. Sometimes we want to scale the gain to the maximum *at that
+elevation (or azimuth) angle*. This can be achieved with the
+``--scale-by-angle`` option::
+
+    plot-antenna --azi --angle-ele=15 --scale-by-angle test/12-el-1deg.pout
+
+.. figure:: https://raw.githubusercontent.com/schlatterbeck/plot-antenna/master/test/12-el-azi-angle-e15-sc.png
+    :align: center
+
+You can see that now the pattern is scaled to the maximum *at that
+elevation angle*. The outer ring now has 12.92 dBi instead of 14.50 dBi.
+
 The plot program also has a ``--help``
 option for further information. In particular the scaling of the antenna
 plot can be selected using the ``--scaling-method`` option with an
@@ -198,30 +227,107 @@ Note that for the measurement-data the unit of the data is not in dBi
 but (because it was measured and not calibrated to dBi) in dBm. The
 measurements were separate for horizontal and vertical polarization.
 
+The program for plotting the measurements is in
+``plot_antenna/contrib.py``. It can serve as an example of how to plot
+your own data with `plot-antenna`_. The eznec program in
+``plot_antenna/eznec.py`` might even be better in this regard. See the
+next section on documentation of the `plot-antenna`_ API.
+
+Plot-Antenna API
+----------------
+
+The main class to plot things is the ``Gain_Plot`` class. It gets the
+command-line arguments and the gain data to plot. Note that the class is
+a little mis-named now because it can also do all the other plots (e.g.
+standing wave ratio, SWR). The gain data passed to the constructor of
+``Gain_Plot`` gets a dictionary of ``Gain_Data`` objects. The keys of
+the dictionary are tuples ``(frequency, string)`` where the frequency is
+the frequency of the ``Gain_Data`` and the string is used for describing
+what is plotted. Since `plot-antenna`_ can have traces for the different
+polarizations in the same plot, usually the string is one of ``H`` for
+horizontal polarization, ``V`` for vertical polarization and ``sum`` for
+the sum of all polarizations. Of course only the sum can be provided if
+we do not want multiple polarizations.
+
+If you are not plotting gain but, say, only SWR data, the gain data
+object passed to the ``Gain_Plot`` constructor may be ``None``.
+
+The ``Gain_Data`` object gets a list of frequencies in the constructor.
+It has an internal ``pattern`` dictionary which stores the gain values
+by a tuple of ``(theta, phi)`` where ``theta`` is the elevation angle
+(measured from the zenith=0 degrees) and the azimuth angle phi measured
+from the positive X-axis. The gain values in this data structure are in
+dBi (Decibel over an isotropic radiator). There is currently no way to
+directly pass a numpy array with the gains. A simple program to
+construct an azimuth plot of an antenna that has the same pattern in all
+directions (gain=0dB) would be::
+
+    import numpy as np
+    from plot_antenna import plot_antenna
+
+    frequency = 430.0
+    polarization = 'sum'
+    key = (frequency, polarization)
+    gdict = {key: plot_antenna.Gain_Data ([frequency])}
+    data = gdict [key].pattern
+    for azi in np.arange (0, 361, 10):
+        data [(90.0, azi)] = 0.0
+    gp = plot_antenna.Gain_Plot (args, gdict)
+    gp.compute ()
+    gp.plot ()
+
+The parsed arguments can typically be constructed by calling one of the
+argument parsing functions. These need not be given the real command
+line arguments but can be called with an empty string list, e.g.::
+
+    # Initialize command options with general options
+    cmd = plot_antenna.options_general ()
+    # Add gain options
+    plot_antenna.options_gain (cmd)
+    # Parse empty arguments resulting in default args
+    args = plot_antenna.process_args (cmd, [])
+    # The filename is needed internally for computing default title
+    args.filename = ''
+    # Title
+    args.title = 'My Title'
+    # We want an azimuth plot
+    args.azimuth = True
+    # We might want to ship result to running browser with plotly
+    # args.show_in_browser = True
+
+The ``cmd`` variable is a python ``ArgumentParser`` object. So if you
+are parsing command line arguments you can add your own options before
+calling ``process_args``
+
+If not parsing argument from the command line and arguments should be
+changed this can be done by directly modifying args, e.g.::
+
+    args.title = 'This is the title of my plot'
+
+A full but short implementation of a usage of this API can be found in
+the companion program for reading EZNEC data in
+``plot_antenna/eznec.py``. This example can be found in ``example.py``.
+
+
 .. [1] L. B. Cebik. Radiation plots: Polar or rectangular; log or linear.
     In Antenna Modeling Notes [2], chapter 48, pages 366–379. Available
-    in Cebik's `Antenna modelling notes episode 48`_
+    in Cebik's `Antenna modelling notes episode 48`_ or `from web
+    archive`_
 .. [2] L. B. Cebik. Antenna Modeling Notes, volume 2. antenneX Online
-    Magazine, 2003. Available with antenna models from the `Cebik
-    collection`_.
-
-.. _`Cebik collection`:
-    http://on5au.be/Books/allmodnotes.zip
-.. _`Antenna modelling notes episode 48`:
-    http://on5au.be/content/amod/amod48.html
-.. _nec2c: https://packages.debian.org/stable/hamradio/nec2c
-.. _pymininec: https://github.com/schlatterbeck/pymininec
-.. _matplotlib: https://matplotlib.org/
-.. _plotly: https://github.com/plotly/plotly.py
-.. _pandas: https://pandas.pydata.org/
-.. _Mininec: https://github.com/Kees-PA3KJ/MiniNec
-.. _ASAP: http://raylcross.net/asap/index.html
-.. _EZNEC: https://eznec.com/
-.. _plot-antenna: https://github.com/schlatterbeck/plot-antenna
+    Magazine, 2003. Available `Cebik collection`_
 
 Release Notes
 -------------
 
+v2.1: Scale by angle
+
+- New option ``--scale-by-angle`` that allows to scale the azimuth or
+  elevation pattern to the maximum at the current elevation- or azimuth
+  angle instead of the global maximum, thanks to Daniel Bruschinski for
+  suggesting this
+- Add a little documentation how to use the API, thanks to Alex, VE3NEA
+  for suggesting this in a github issue.
+
 v2.0: More input formats
 
 - Import from EZNEC_ exported pattern data
@@ -329,3 +435,17 @@ v1.1: Specification of azimuth / elevation angle
 v1.0: Initial Release
 
 .. _`patched pySmithPlot`: https://github.com/schlatterbeck/pySmithPlot
+.. _`Cebik collection`:
+    https://q82.uk/projects/cebik/modelling/W4RNL%20Antenna%20Modelling%20Notes%20Volume%202.pdf
+.. _`from web archive`: https://web.archive.org/web/20230816222342/http://on5au.be/content/amod/amod48.html
+.. _`Antenna modelling notes episode 48`:
+    https://q82.uk/projects/cebik/modelling/48.%20Radiation%20Plots%20%20-%20Polar%20or%20Rectangular.%20Log%20or%20Linear.pdf
+.. _nec2c: https://packages.debian.org/stable/hamradio/nec2c
+.. _pymininec: https://github.com/schlatterbeck/pymininec
+.. _matplotlib: https://matplotlib.org/
+.. _plotly: https://github.com/plotly/plotly.py
+.. _Mininec: https://github.com/Kees-PA3KJ/MiniNec
+.. _ASAP: http://raylcross.net/asap/index.html
+.. _EZNEC: https://eznec.com/
+.. _plot-antenna: https://github.com/schlatterbeck/plot-antenna
+

{plot_antenna-2.0 → plot_antenna-2.2}/README.rst

@@ -56,6 +56,31 @@ above. The pattern look smoother but a 3D-view in matplotlib_ will be
 very slow due to the large number of points. This problem does not occur
 when using the plotly_ backend.
 
+Sometimes we do not want the azimuth plot at the maximum elevation angle
+or the elevation plot at the maximum azimuth angle. You can specify the
+elevation angle for the azimuth plot with the ``--angle-elevation``
+option and the azimuth angle for the elevation plot with
+``--angle-azimuth``. An example azimuth plot of the same antenna at an
+elevation angle of 15° can be plotted with::
+
+    plot-antenna --azimuth --angle-elevation=15 test/12-el-1deg.pout
+
+.. figure:: https://raw.githubusercontent.com/schlatterbeck/plot-antenna/master/test/12-el-azi-angle-ele15.png
+    :align: center
+
+As you can see, the azimuth-plot is scaled to the maximum gain of the
+antenna. Sometimes we want to scale the gain to the maximum *at that
+elevation (or azimuth) angle*. This can be achieved with the
+``--scale-by-angle`` option::
+
+    plot-antenna --azi --angle-ele=15 --scale-by-angle test/12-el-1deg.pout
+
+.. figure:: https://raw.githubusercontent.com/schlatterbeck/plot-antenna/master/test/12-el-azi-angle-e15-sc.png
+    :align: center
+
+You can see that now the pattern is scaled to the maximum *at that
+elevation angle*. The outer ring now has 12.92 dBi instead of 14.50 dBi.
+
 The plot program also has a ``--help``
 option for further information. In particular the scaling of the antenna
 plot can be selected using the ``--scaling-method`` option with an
@@ -170,30 +195,107 @@ Note that for the measurement-data the unit of the data is not in dBi
 but (because it was measured and not calibrated to dBi) in dBm. The
 measurements were separate for horizontal and vertical polarization.
 
+The program for plotting the measurements is in
+``plot_antenna/contrib.py``. It can serve as an example of how to plot
+your own data with `plot-antenna`_. The eznec program in
+``plot_antenna/eznec.py`` might even be better in this regard. See the
+next section on documentation of the `plot-antenna`_ API.
+
+Plot-Antenna API
+----------------
+
+The main class to plot things is the ``Gain_Plot`` class. It gets the
+command-line arguments and the gain data to plot. Note that the class is
+a little mis-named now because it can also do all the other plots (e.g.
+standing wave ratio, SWR). The gain data passed to the constructor of
+``Gain_Plot`` gets a dictionary of ``Gain_Data`` objects. The keys of
+the dictionary are tuples ``(frequency, string)`` where the frequency is
+the frequency of the ``Gain_Data`` and the string is used for describing
+what is plotted. Since `plot-antenna`_ can have traces for the different
+polarizations in the same plot, usually the string is one of ``H`` for
+horizontal polarization, ``V`` for vertical polarization and ``sum`` for
+the sum of all polarizations. Of course only the sum can be provided if
+we do not want multiple polarizations.
+
+If you are not plotting gain but, say, only SWR data, the gain data
+object passed to the ``Gain_Plot`` constructor may be ``None``.
+
+The ``Gain_Data`` object gets a list of frequencies in the constructor.
+It has an internal ``pattern`` dictionary which stores the gain values
+by a tuple of ``(theta, phi)`` where ``theta`` is the elevation angle
+(measured from the zenith=0 degrees) and the azimuth angle phi measured
+from the positive X-axis. The gain values in this data structure are in
+dBi (Decibel over an isotropic radiator). There is currently no way to
+directly pass a numpy array with the gains. A simple program to
+construct an azimuth plot of an antenna that has the same pattern in all
+directions (gain=0dB) would be::
+
+    import numpy as np
+    from plot_antenna import plot_antenna
+
+    frequency = 430.0
+    polarization = 'sum'
+    key = (frequency, polarization)
+    gdict = {key: plot_antenna.Gain_Data ([frequency])}
+    data = gdict [key].pattern
+    for azi in np.arange (0, 361, 10):
+        data [(90.0, azi)] = 0.0
+    gp = plot_antenna.Gain_Plot (args, gdict)
+    gp.compute ()
+    gp.plot ()
+
+The parsed arguments can typically be constructed by calling one of the
+argument parsing functions. These need not be given the real command
+line arguments but can be called with an empty string list, e.g.::
+
+    # Initialize command options with general options
+    cmd = plot_antenna.options_general ()
+    # Add gain options
+    plot_antenna.options_gain (cmd)
+    # Parse empty arguments resulting in default args
+    args = plot_antenna.process_args (cmd, [])
+    # The filename is needed internally for computing default title
+    args.filename = ''
+    # Title
+    args.title = 'My Title'
+    # We want an azimuth plot
+    args.azimuth = True
+    # We might want to ship result to running browser with plotly
+    # args.show_in_browser = True
+
+The ``cmd`` variable is a python ``ArgumentParser`` object. So if you
+are parsing command line arguments you can add your own options before
+calling ``process_args``
+
+If not parsing argument from the command line and arguments should be
+changed this can be done by directly modifying args, e.g.::
+
+    args.title = 'This is the title of my plot'
+
+A full but short implementation of a usage of this API can be found in
+the companion program for reading EZNEC data in
+``plot_antenna/eznec.py``. This example can be found in ``example.py``.
+
+
 .. [1] L. B. Cebik. Radiation plots: Polar or rectangular; log or linear.
     In Antenna Modeling Notes [2], chapter 48, pages 366–379. Available
-    in Cebik's `Antenna modelling notes episode 48`_
+    in Cebik's `Antenna modelling notes episode 48`_ or `from web
+    archive`_
 .. [2] L. B. Cebik. Antenna Modeling Notes, volume 2. antenneX Online
-    Magazine, 2003. Available with antenna models from the `Cebik
-    collection`_.
-
-.. _`Cebik collection`:
-    http://on5au.be/Books/allmodnotes.zip
-.. _`Antenna modelling notes episode 48`:
-    http://on5au.be/content/amod/amod48.html
-.. _nec2c: https://packages.debian.org/stable/hamradio/nec2c
-.. _pymininec: https://github.com/schlatterbeck/pymininec
-.. _matplotlib: https://matplotlib.org/
-.. _plotly: https://github.com/plotly/plotly.py
-.. _pandas: https://pandas.pydata.org/
-.. _Mininec: https://github.com/Kees-PA3KJ/MiniNec
-.. _ASAP: http://raylcross.net/asap/index.html
-.. _EZNEC: https://eznec.com/
-.. _plot-antenna: https://github.com/schlatterbeck/plot-antenna
+    Magazine, 2003. Available `Cebik collection`_
 
 Release Notes
 -------------
 
+v2.1: Scale by angle
+
+- New option ``--scale-by-angle`` that allows to scale the azimuth or
+  elevation pattern to the maximum at the current elevation- or azimuth
+  angle instead of the global maximum, thanks to Daniel Bruschinski for
+  suggesting this
+- Add a little documentation how to use the API, thanks to Alex, VE3NEA
+  for suggesting this in a github issue.
+
 v2.0: More input formats
 
 - Import from EZNEC_ exported pattern data
@@ -301,3 +403,17 @@ v1.1: Specification of azimuth / elevation angle
 v1.0: Initial Release
 
 .. _`patched pySmithPlot`: https://github.com/schlatterbeck/pySmithPlot
+.. _`Cebik collection`:
+    https://q82.uk/projects/cebik/modelling/W4RNL%20Antenna%20Modelling%20Notes%20Volume%202.pdf
+.. _`from web archive`: https://web.archive.org/web/20230816222342/http://on5au.be/content/amod/amod48.html
+.. _`Antenna modelling notes episode 48`:
+    https://q82.uk/projects/cebik/modelling/48.%20Radiation%20Plots%20%20-%20Polar%20or%20Rectangular.%20Log%20or%20Linear.pdf
+.. _nec2c: https://packages.debian.org/stable/hamradio/nec2c
+.. _pymininec: https://github.com/schlatterbeck/pymininec
+.. _matplotlib: https://matplotlib.org/
+.. _plotly: https://github.com/plotly/plotly.py
+.. _Mininec: https://github.com/Kees-PA3KJ/MiniNec
+.. _ASAP: http://raylcross.net/asap/index.html
+.. _EZNEC: https://eznec.com/
+.. _plot-antenna: https://github.com/schlatterbeck/plot-antenna
+

plot_antenna-2.2/VERSION

@@ -0,0 +1 @@
+2.2

plot_antenna-2.2/plot_antenna/Version.py

@@ -0,0 +1 @@
+VERSION="2.2"

{plot_antenna-2.0 → plot_antenna-2.2}/plot_antenna/eznec.py

@@ -3,6 +3,7 @@
 import sys
 from csv import DictReader
 from . import plot_antenna as aplot
+from .plot_antenna import Impedance_Data
 
 def parse_eznec_data (args):
     """ Parses eznec date exported with 'FF Tab'
@@ -15,12 +16,13 @@ def parse_eznec_data (args):
     state      = 'start'
     head_seen  = False
     gdata_dict = {}
+    impedance  = None
     with open (args.filename, 'r') as rfile:
         for line in rfile:
             line = line.strip ()
             if state == 'start':
-                line = line.replace (',', '.')
                 if line.startswith ('Frequency'):
+                    line = line.replace (',', '.')
                     if not line.endswith ('MHz'):
                         raise ValueError \
                             ('Unsupported frequency format: %s' % line)
@@ -43,7 +45,12 @@ def parse_eznec_data (args):
                         angle += 90
                     head_seen = False
                     continue
+                if line.startswith ('"Freq MHz","Src #","R","X"'):
+                    state = 'impedance'
+                    impedance = {}
+                    continue
             if state in ('azi', 'ele'):
+                line = line.replace (',', '.')
                 if not head_seen:
                     l = ' '.join (line.split ())
                     if l != 'Deg V dB H dB Tot dB V Pha H Pha':
@@ -78,21 +85,38 @@ def parse_eznec_data (args):
                         azi = angle
                     #print (ele, azi, pol, gain)
                     gdata.pattern [(ele, azi)] = gain
-    return gdata_dict
-# end def parse_csv_measurement_data
+                continue
+            if state == 'impedance':
+                f,src,r,x,swr1,swr2 = (float (x) for x in line.split (','))
+                z = r + 1j * x
+                impedance [f] = Impedance_Data (f, z)
+    return gdata_dict, impedance
+# end def parse_eznec_data
 
 def main_eznec (argv = sys.argv [1:], pic_io = None):
     """ Parse eznec far field data.
     """
     cmd = aplot.options_general ()
     aplot.options_gain (cmd)
+    aplot.options_swr  (cmd)
     cmd.add_argument ('filename', help = 'EZNEC far field data to plot')
     args = aplot.process_args (cmd, argv)
     if pic_io is not None:
         args.output_file = pic_io
         args.save_format = 'png'
-    gdata = parse_eznec_data (args)
+    gdata, idata = parse_eznec_data (args)
+    if idata and not args.plot_vswr:
+        args.plot_vswr = True
+    if gdata and not args.elevation and not args.azimuth and not args.plot3d:
+        args.plot3d = True
+    if not gdata:
+        args.plot3d    = False
+        args.elevation = False
+        args.azimuth   = False
+    if not idata:
+        args.plot_vswr = False
     gp = aplot.Gain_Plot (args, gdata)
+    gp.idata = idata
     gp.compute ()
     gp.plot ()
 # end def main_eznec