Pileus Git - aweather/blob - docs/userguide.ad

   1 AWeather Users Guide
   2 ====================
   3 :Author:   Jason Holmes
   4 :Email:    <Doppler5@aol.com>
   5 :Date:     2011-12-27
   6 :Revision: 0.6.1
   7 :Website:  http://lug.rose-hulman.edu/proj/aweather/
   8
   9 About and contact information
  10 -----------------------------
  11 AWeather was created in the summer of 2008 and functions as a NEXRAD Level II
  12 radar display program. The goal of this application is to fulfill a need through
  13 providing ample weather information without excessive cost and size that is not
  14 limited to the Linux operating system.
  15
  16 It is written in a standard GTK+/GObject architecture and features an
  17 interactive display utilizing libgis and OpenGL technologies.
  18
  19 The software source code for Ubuntu and other operating systems is available for
  20 download on the RHLUG server at git://lug.rose-hulman.edu/proj/aweather.
  21
  22 AWeather relies upon the following dependencies: http://www.ijg.org/[jpeg],
  23 http://hdf.ncsa.uiuc.edu/hdf4.html[hdf4], http://www.gnome.org/[libsoup] 2.26 or
  24 later and http://www.gtk.org/[gtk+] 2.16 or later
  25
  26 Compiled packages of the software are currently available for the Gentoo,
  27 Debian, and Microsoft Windows operating systems.
  28
  29 The program currently provides data viewing from the standard one dimensional
  30 plan view to user-defined three-dimensional dynamic views of current and recent
  31 radar data.
  32
  33 The software was developed and is maintained by Andy Spencer.  He may be
  34 contacted through e-mail at andy753421@gmail.com and chat through IRC at #rhlug
  35 on irc.freenode.net.
  36
  37
  38 Licensing information
  39 ---------------------
  40 AWeather is provided as free software according to the terms of the GNU General
  41 Public License (version 3 or later) as published by the Free Software Foundation
  42 (http://www.gnu.org/licenses/).
  43
  44
  45 Data types and sources
  46 ----------------------
  47 AWeather displays U.S. National Weather Service NEXt generation RADar data
  48 (NEXRAD) Level II data.  This is the highest resolution form of radar data
  49 available in the public domain and consists of multiple tilts of data updated
  50 every 5 to 10 minutes depending on the current scan mode of each radar.
  51
  52 The following Level II data types are supported by this program:
  53
  54 Base reflectivity (power return of current precipitation intensity)
  55
  56 Base velocity (Doppler-derived speed and direction of radar returns)
  57
  58 Spectrum width (The variation of velocity detected within each radar pixel or
  59 bin)
  60
  61
  62 Level II data has been available through private weather data vendors for some
  63 time but recently has been generously provided by some universities.
  64
  65 AWeather requires an active internet connection along with a data feed source in
  66 order to retrieve, decode and display current or recent radar data.
  67
  68 The default radar feed is publically accessible thanks to Iowa State University
  69 and is located at: http://mesonet.agron.iastate.edu/data/nexrd2/raw/.
  70
  71
  72 Program layout
  73 --------------
  74 AWeather consists of a graphical user interface window that contains a file menu
  75 bar, a button bar, a date and time side bar, a large map and data viewing pane
  76 and a bottom data status bar.
  77
  78
  79 The file menu commands
  80 ----------------------
  81 The program file nenu consists of 3 entries:
  82
  83 File
  84 ~~~~
  85 Offline::     stops the program from downloading data through the internet
  86 Preferences:: opens the preferences window, which contains the following
  87               commands
  88
  89         General tab:::
  90
  91 [horizontal]
  92                 Offline checkbox::::     if selected keeps the program from connecting
  93                                          to the internet
  94                 Initial site listbox:::: allows the user to select a default radar site
  95                                          to jump to when the program loads
  96                 Debug level text box:::: allows the user to select what level of
  97                                          debugging the program should conduct while
  98                                          running (7 is recommended only for debugging)
  99
 100         Plugins tab:::
 101
 102 [horizontal]
 103                 elev checkbox::::        ???
 104                 env checkbox::::         ???
 105                 map checkbox::::         allows the user to toggle the map overlays
 106                 radar checkbox::::       allows the user to toggle the radar data
 107                 sat checkbox::::         allows the user to toggle satellite data
 108                 test checkbox::::        ???
 109
 110 Clean cache:: removes data files from the program's internal cache
 111 Quit::        closes the program window and exits from memory
 112
 113 View
 114 ~~~~
 115 [horizontal]
 116 Zoom in::     decreases the viewing area
 117 Zoom out::    increases the viewing area
 118 Fullscreen::  maximizes the window and only displays the button menu bar along
 119               with the map and data viewing pane
 120 Refresh::     reloads the current display
 121
 122 Help
 123 ~~~~
 124 [horizontal]
 125 Contents::    displays this documentation of program operation and features
 126 About::       contains current program version, copyright, development site,
 127               credits and licensing information
 128
 129
 130 The button bar
 131 --------------
 132 The program button bar contains 6 options:
 133
 134 [horizontal]
 135 Magnifying glass with plus sign::   decreases the viewing area
 136 Magnifying glass with minus sign::  increases the viewing area
 137 Window icon with expanding arrows:: Toggles between fullscreen and normal viewing modes
 138 Plug button::                       toggles between offline and online program mode
 139 Circular arrow button::             reloads the current display
 140 Wrench and screwdriver button::     Opens the preferences window
 141
 142
 143 The date and time side bar
 144 --------------------------
 145 The date and time side bar resides on the right side of the program window, it contains:
 146
 147 * The date button, which reveals a calendar of the current month when clicked
 148
 149 * The time button, which reveals a list of each hour when clicked
 150
 151 ** Clicking on an hour will reveal a list of times in 5 minute intervals that
 152    the user can select to load radar data from
 153
 154
 155 The map and data viewing pane
 156 -----------------------------
 157 On program startup and when zoomed far from the earth's surface AWeather
 158 displays a national radar composite image.
 159
 160 As the user zooms closer to the earth AWeather will automatically activate
 161 nearby radar sites.
 162
 163 The radar data will be plotted on the map while the scan and product information
 164 will be displayed at the bottom of the program.
 165
 166 All active radar sites will show as tabs while site's available tilt and product
 167 data will display to the right of the tab.
 168
 169 Simply click on a button to display that product/tilt in the map window.
 170
 171 An isosurface slider is shown below the product/tilt buttons.  Slide the
 172 selector to reveal the rendered isosurface structure of the selected
 173 product/tilt.
 174
 175 A color scale will automatically appear at the top left corner of the map window
 176 corresponding to each available product.
 177
 178
 179 Panning, zooming and tilt functions
 180 -----------------------------------
 181 AWeather supports the use of the mouse and keyboard commands to change the map
 182 window settings.
 183
 184 Mouse usage::
 185 [horizontal]
 186         Left click and drag:::    Pan the surface of the earth
 187         Middle click and drag:::  Zoom toward or away from the earth
 188         Right click and drag:::   Rotate the camera left or right
 189
 190 Keyboard shortcuts::
 191 [horizontal]
 192         h:::                  Pan left
 193         j:::                  Pan down
 194         k:::                  Pan up
 195         l:::                  Pan right
 196         i, +, Scroll Up:::    Zoom in
 197         o, -, Scroll Down:::  Zoom out
 198         J:::                  Rotate camera toward earth
 199         K:::                  Rotate camera toward sky
 200         H:::                  Rotate camera left
 201         L:::                  Rotate camera right
 202         w:::                  Draw wire frame of the earth (for debugging)
 203         q:::                  Exit the program
 204         Tab:::                Cycle through available plugins
 205         CTRL+R:::             Refresh the display
 206
 207
 208 Command Line Options
 209 --------------------
 210 The following commands can help advanced users take full advantage of the
 211 AWeather program:
 212
 213 aweather [*-hoaf*] [-d 'level'] [-s 'site'] [-t 'time']
 214
 215 *-h*, *--help*::
 216         Show usage.
 217
 218 *-d*, *--debug*='level'::
 219         Change default log level*, a debug level ranges from 0 to 5. A debug
 220         level of 5 is recommended only for debugging purposes.
 221
 222 *-s*, *--site*='site'::
 223         Set initial site. The site should be given as a WSR88D site code such
 224         as KLSX.
 225
 226 *-t*, *--time*='time'::
 227         Set initial time. The time format should be provided in the
 228         *YYYY-MM-DD HH:MM* format.
 229
 230 *-o*, *--offline*::
 231         Run in offline mode, AWeather will not attempt to connect to the
 232         internet to download radar files but will show the closest matching
 233         cached file.
 234
 235 *-a*, *--autoupdate*::
 236         Run in autoupdate mode, AWeather will periodically poll data servers
 237         for updated information.
 238
 239 *-f*, *--fullscreen*::
 240         Run in fullscreen mode, AWeather start up using the entire screen as he
 241         main display area. Toolbars and side panels are hidden by default and
 242
 243
 244 Future Features
 245 ---------------
 246 The author intends to develop additional features in the future as time and
 247 conditions allow.
 248
 249 Some of these enhancements include:
 250
 251         * Vertical cross sections, volume display
 252         * Support for derived L3 data (storm relative motion, echo tops, composite
 253           reflectivity, etc)
 254         * Additional data sources for watches, warnings, surface data, etc
 255         * Auto-updating of data
 256         * Animation support
 257         * A 3D volume browser
 258         * API for radar algorithms
 259         * Additional features
 260
 261 // vim: ft=asciidoc ts=4 tw=80