                                                                             + + +
AERPLOT - plotfile visualization program
=============================================

This program is written in a combination of Python 2.7 and Fortran.
This program is designed to run on Microsoft Windows.

Integration with Google Earth
-----------------------------

The program is designed to take a .PLT plotfile and produce a .KMZ
file suitable for display in an 'earth browser'.  It was developed
with the Google Earth earth browser in mind.


Format of the .PLT file
-----------------------

The program is designed to work with .PLT (plot files) generated by
AERMOD. It will work with any file that matches the AERMOD plot file 
format, in these particulars:

   The data must be present in the first three columns, that match AERMOD's
   in column number placement and width. These are X, Y, and the 
   concentration values.

   The X and Y must be in meters, else the placements will be wrong.

   The third value should be concentration and should be non-negative.

   If a LOG (logarithmic) binning technique is used, please realize that negative
   and zero values have no "correct" place in that scheme.  The program will 
   ignore non-positive values for creating the color scale and all values that
   are less than the lowest value in the scale will be binned into the bottom 
   bin.

   In the file header, the two lines with column headers and their underscores
   (starting with the "#" sign) must be present.


Warning for LOG binning
-----------------------

Non-positive values are ignored for contour purposes and the behavior
of the contours should be considered undefined. An effort has been
made to just bin them into the very smallest of the positive bins, but
negative values will still affect the "averaging" and "interpolating"
operations and will possibly shift lines around.


Credits in Software Used
------------------------

IECapt.exe

A program named "IECapt.exe" is used to convert HTML into a PNG image.

It is available at http://sourceforge.net/projects/iecapt
www.sourceforge.net/iecapt.


ApproxEqual.py

A python module named "ApproxEqual" is used during development of
"AERPLOT". It was written by Steven D'Aprano .

"ApproxEqual" is not part of the code that runs in "AERPLOT"; however, it is used
to very good advantage for testing purposes, and references to it appear in the
documentation for a good many modules in this package.

"ApproxEqual" was retrieved from 
http://code.activestate.com/recipes/577124-approximately-equal/
 .
Its content is part of this package.

After retrieval, the EPA programmer added three routines.  "list_approx_equal()"
will compare lists to see if the floating point values within are almost equal.

"utmApproxEqual()" and "latlonApproxEqual()" will do the same for
geographic coordinates.  Both were written at EPA.


=============================================================================
Version 13329
----------------------------------

Enhancements included
---------------------

   Contours lines are now added to the display.

   Progress meter for long operations (presently for contour calculations).

   The name of the folder for the receptor dots changed from
   the name of the whole plot to the name "Receptor_Placemark_Dots".
   This matches the name given to the folder containing the
   contour lines, making a more intelligible set of names for
   viewing in Google Earth's "Places" panel.

   The legend's html file is now stored in the .KMZ zip archive. It 
   is not used. However, if the end user should wish to display it in 
   an html browser, it can be extracted with most zip tools.

   Warnings are given when Min and/or Max are set incorrectly for 
   Logarithmic binning, or if Min and Max are equal.

   Warnings are given if concentrations of zero are found while using 
   Lorgarithmic binning.

Bug Fixes
---------

   A "Camera" item has been added to counter the behavior 
   of Google Earth to providing a tilted view of the plot for the 
   initial viewing of the plot.  "Camera" forces the default plot 
   viewing angle to be from directly above.

Known Issues
------------

   The program uses temporary files in the local folder named:

      coordinates.txt  latlon_utm.txt

   If there are existing files with those names in the local folder, they 
   will be overwritten.

   -----

   While producing the .KMZ file with the name specified in the 
   AERPLOT.inp file, the program will use temporary files with the same 
   file name but different suffixes.

      While producing a XYZ.kmz file,
      the program will produce and then remove:  XYZ.kml XYZ_legend.png

   If there are existing files with those names in the local folder, they 
   will be overwritten.

   -----

   When the information balloon is opened for an icon, the line/arrow
   from the balloon back to the icon is anchored to the icon's bottom 
   edge, and that suggests to some that the "hot spot" on the icon is there.

   Actually, the hot spot is defined as the place on the icon at which 
   the icon is "attached" to the landscape.  Experimentation indicates it 
   actually is near the center of each circle icon, but also that it is 
   dependent on the update status of the earth browser.

   -----

   Receptors on the equator, or just on either side of it, can be shown with 
   the wrong altitude. So if a plot spans the equator, the northern half might 
   be shown higher than the southern half, while receptors exactly at 0.0 
   degrees might be on a third level.