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

   1 AWeather Users Guide
   2 ====================
   3 :Author:   Jason Holmes
   4 :Email:    <Doppler5@aol.com>
   5 :Date:     2012-01-10
   6 :Revision: 0.6.3
   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 Grits and OpenGL technologies.
  18
  19 The software source code is available for download on the RHLUG server at
  20 git://lug.rose-hulman.edu/proj/aweather.
  21
  22 AWeather relies upon the following dependencies: http://www.gtk.org/[gtk+] 2.16
  23 or later, http://www.gnome.org/[libsoup] 2.26 or later, http://bzip.org/[bzip],
  24 http://trmm-fc.gsfc.nasa.gov/trmm_gv/software/rsl[rsl] 1.42 or later, and
  25 others.
  26
  27 Packaged versions of the software are currently available for Gentoo, Debian,
  28 Ubuntu, Microsoft Windows, and Mac OSX operating systems.
  29
  30 The program currently provides data viewing from the standard one dimensional
  31 plan view to user-defined three-dimensional dynamic views of current and recent
  32 radar data.
  33
  34 The software was developed and is maintained by Andy Spencer. He may be
  35 contacted through e-mail at andy753421@gmail.com and chat through IRC at #rhlug
  36 on irc.freenode.net.
  37
  38
  39 Licensing information
  40 ---------------------
  41 AWeather is provided as free software according to the terms of the GNU General
  42 Public License (version 3 or later) as published by the Free Software Foundation
  43 (http://www.gnu.org/licenses/).
  44
  45
  46 Data types and sources
  47 ----------------------
  48 AWeather displays U.S. National Weather Service NEXt generation RADar data
  49 (NEXRAD) Level II data.  This is the highest resolution form of radar data
  50 available in the public domain and consists of multiple tilts of data updated
  51 every 5 to 10 minutes depending on the current scan mode of each radar.
  52
  53 The following Level II data types are supported by this program:
  54
  55 - Base reflectivity (power return of current precipitation intensity)
  56
  57 - Base velocity (Doppler-derived speed and direction of radar returns)
  58
  59 - Spectrum width (The variation of velocity detected within each radar pixel or
  60   bin)
  61
  62 - Differential Reflectivity (The ratio of the reflected horizontal and vertical
  63   power returns) footnoteref:[dualpol]
  64
  65 - Differential Phase (A comparison of the phase difference between the
  66   horizontal and vertical returns) footnoteref:[dualpol]
  67
  68 - Correlation Coefficient (A statistical correlation between the reflected
  69   horizontal and vertical power returns) footnoteref:[dualpol,Only available at
  70   WSR-88D sites that have been upgraded to support dual-polarization]
  71
  72 Level II data has been available through private weather data vendors for some
  73 time but recently has been generously provided by some universities.
  74
  75 AWeather requires an active internet connection along with a data feed source in
  76 order to retrieve, decode and display current or recent radar data.
  77
  78 The default radar feed is publically accessible thanks to Iowa State University
  79 and is located at: http://mesonet.agron.iastate.edu/data/nexrd2/raw/.
  80
  81 AWeather also displays some severe weather alerts provided by the NOAA weather
  82 alerts http://alerts.weather.gov/[feed].
  83
  84
  85 Program layout
  86 --------------
  87 AWeather consists of a graphical user interface window that contains a file menu
  88 bar, a button bar, a date and time side bar, a large map and data viewing pane
  89 and a bottom data status bar.
  90
  91
  92 The file menu commands
  93 ----------------------
  94 The program file menu consists of 5 entries:
  95
  96 File
  97 ~~~~
  98 Offline::     stops the program from downloading data through the internet
  99 Refresh::     reloads the current display
 100 Auto-updae::  automatically refresh the the radar after a certain delay
 101 Clean cache:: removes data files from the program's internal cache
 102 Quit::        closes the program window and exits from memory
 103
 104 Edit
 105 ~~~~
 106 Preferences:: opens the preferences window, which contains the following
 107               commands
 108
 109         General tab:::
 110
 111 [horizontal]
 112                 Offline checkbox::::     if selected keeps the program from connecting
 113                                          to the internet
 114                 Update Freq::::          sets the timeout value for automatic updating
 115                 Initial site listbox:::: allows the user to select a default radar site
 116                                          to jump to when the program loads
 117                 NEXRAD URL text box::::  allows the user to select a different server to
 118                                          download Level-II NEXRAD data from
 119                 Debug level text box:::: allows the user to select what level of
 120                                          debugging the program should conduct while
 121                                          running (7 is recommended only for debugging)
 122
 123         Plugins tab:::
 124
 125 [horizontal]
 126                 alert checkbox::::       allows the user to toggle the weather alerts
 127                 elev checkbox::::        allows the user to toggle terrain rendering
 128                 env checkbox::::         allows the user to toggle a blue atmosphere
 129                 map checkbox::::         allows the user to toggle the map overlays
 130                 radar checkbox::::       allows the user to toggle the radar data
 131                 sat checkbox::::         allows the user to toggle satellite ground images
 132                 test checkbox::::        used by the developers for debugging
 133
 134 View
 135 ~~~~
 136 [horizontal]
 137 Zoom in::     decreases the viewing area
 138 Zoom out::    increases the viewing area
 139 Fullscreen::  maximizes the window and only displays the button menu bar along
 140               with the map and data viewing pane when the mouse is moved to the
 141               edge of the screen
 142
 143 Radar
 144 ~~~~~
 145 The radar menu contains list of all the support NEXRAD radar sites sorted by
 146 state. Selecting a site will zoom AWeather to that location.
 147
 148 Help
 149 ~~~~
 150 [horizontal]
 151 User Guide::  displays this documentation of program operation and features
 152 Man Page::    displays a HTML version of the UNIX man page
 153 About::       contains current program version, copyright, development site,
 154               credits and licensing information
 155
 156
 157 The button bar
 158 --------------
 159 The program button bar contains 6 options:
 160
 161 [horizontal]
 162 Magnifying glass with plus sign::   decreases the viewing area
 163 Magnifying glass with minus sign::  increases the viewing area
 164 Window icon with expanding arrows:: Toggles between fullscreen and normal viewing modes
 165 Plug button::                       toggles between offline and online program mode
 166 Circular arrow button::             reloads the current display
 167 Wrench and screwdriver button::     Opens the preferences window
 168
 169
 170 The date and time side bar
 171 --------------------------
 172 The date and time side bar resides on the right side of the program window, it contains:
 173
 174 * The date button, which reveals a calendar of the current month when clicked
 175
 176 * The time button, which reveals a list of each hour when clicked
 177
 178 ** Clicking on an hour will reveal a list of times in 5 minute intervals that
 179    the user can select to load radar data from footnote:[Radar data can only be
 180    loaded if it has been previously cached or is from a recent enough date and
 181    can still be obtained from the NEXRAD server]
 182
 183
 184 The map and data viewing pane
 185 -----------------------------
 186 On program startup and when zoomed far from the earth's surface AWeather
 187 displays a national radar composite image.
 188
 189 As the user zooms closer to the earth AWeather will automatically activate
 190 nearby radar sites.
 191
 192 The radar data will be plotted on the map while the scan and product information
 193 will be displayed at the bottom of the program.
 194
 195 All active radar sites will show as tabs while site's available tilt and product
 196 data will display to the right of the tab.
 197
 198 Simply click on a button to display that product/tilt in the map window.
 199
 200 An isosurface slider is shown below the product/tilt buttons.  Slide the
 201 selector to reveal the rendered isosurface structure of reflectivity data.
 202
 203 A color scale will automatically appear at the top left corner of the map window
 204 corresponding to each available product.
 205
 206
 207 Viewing severe  weather alerts
 208 ------------------------------
 209 When the alert plugin is enabled, AWeather will automatically shade each county
 210 that is under a weather alert in a color corresponding to the type of alert.
 211
 212 For storm based warnings, AWeather will also draw a polygon representing the
 213 warning area.
 214
 215 Individual alert types can be enabled and disabled by clicking on the toggle
 216 button in the alert tab at the bottom of the screen.
 217
 218 To view more information about a particular alert, click on one the shaded
 219 county or inside the polygon warning area in the viewing pane. This will bring
 220 up the alert details dialog with a tab for each alert that is active for the
 221 location that was clicked.
 222
 223 The alert dialog displays the alert title and valid time along with the text
 224 descriptions provided by the weather service. Clicking the "Full Text" button
 225 will open the full text of the alert in a web browser.
 226
 227
 228 Panning, zooming and tilt functions
 229 -----------------------------------
 230 AWeather supports the use of the mouse and keyboard commands to change the map
 231 window settings.
 232
 233 Mouse usage::
 234 [horizontal]
 235         Left click and drag:::    Pan the surface of the earth
 236         Middle click and drag:::  Zoom toward or away from the earth
 237         Right click and drag:::   Rotate the camera left or right
 238
 239 Keyboard shortcuts::
 240 [horizontal]
 241         h:::                  Pan left
 242         j:::                  Pan down
 243         k:::                  Pan up
 244         l:::                  Pan right
 245         i, +, Scroll Up:::    Zoom in
 246         o, -, Scroll Down:::  Zoom out
 247         J:::                  Rotate camera toward earth
 248         K:::                  Rotate camera toward sky
 249         H:::                  Rotate camera left
 250         L:::                  Rotate camera right
 251         w:::                  Draw wire frame of the earth (for debugging)
 252         q:::                  Exit the program
 253         Tab:::                Cycle through available plugins
 254         Escape:::             Close the currently active dialog box
 255         CTRL+R:::             Refresh the display
 256
 257
 258 Command Line Options
 259 --------------------
 260 The following command line options can help advanced users take full advantage
 261 of the AWeather program:
 262
 263 aweather [*-hoaf*] [-d 'level'] [-s 'site'] [-t 'time']
 264
 265 *-h*, *--help*::
 266         Show usage.
 267
 268 *-d*, *--debug*='level'::
 269         Change default log level*, a debug level ranges from 0 to 5. A debug
 270         level of 5 is recommended only for debugging purposes.
 271
 272 *-s*, *--site*='site'::
 273         Set initial site. The site should be given as a WSR88D site code such
 274         as KLSX.
 275
 276 *-t*, *--time*='time'::
 277         Set initial time. The time format should be provided in the
 278         *YYYY-MM-DD HH:MM* format.
 279
 280 *-o*, *--offline*::
 281         Run in offline mode, AWeather will not attempt to connect to the
 282         internet to download radar files but will show the closest matching
 283         cached file.
 284
 285 *-a*, *--autoupdate*::
 286         Run in autoupdate mode, AWeather will periodically poll data servers
 287         for updated information.
 288
 289 *-f*, *--fullscreen*::
 290         Run in fullscreen mode, AWeather start up using the entire screen as he
 291         main display area. Toolbars and side panels are hidden by default.
 292
 293
 294 Future Features
 295 ---------------
 296 The author intends to develop additional features in the future as time and
 297 conditions allow.
 298
 299 Some of these enhancements include:
 300
 301         * Vertical cross sections
 302         * Support for derived L3 data (storm relative motion, echo tops, composite
 303           reflectivity, etc)
 304         * Additional data sources for surface data, etc
 305         * Animation support
 306         * API for radar algorithms
 307         * Additional features
 308
 309 // vim: ft=asciidoc ts=4 tw=80