docs: fix a few typos
[aweather] / docs / userguide.ad
1 AWeather Users Guide
2 ====================
3 :Author:   Jason Holmes
4 :Email:    <Doppler5@aol.com>
5 :Date:     2013-01-28
6 :Revision: 0.8
7 :Website:  http://pileus.org/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 at
20 git://pileus.org/aweather.
21
22 AWeather relies upon the following dependencies: http://www.gtk.org/[gtk+] 2.18
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 two 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 #pileus
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 (NEXRAD)
49 Level II data.  This is the highest resolution form of radar data available in
50 the public domain and consists of multiple tilts of data updated every 5 to 10
51 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 source in
76 order to retrieve, decode and display current or recent radar data.
77
78 The default radar feed is publicly 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 When run under Linux, AWeather can interface with the
85 http://www.catb.org/gpsd/[GPSd] location services to track and display the
86 user's current location.
87
88
89 Program layout
90 --------------
91 AWeather consists of a graphical user interface window that contains a file menu
92 bar, a button bar, a date and time side bar, a large map and data viewing pane
93 and a bottom data status bar.
94
95
96 The file menu commands
97 ----------------------
98 The program file menu consists of 5 entries:
99
100 File
101 ~~~~
102 Offline::     stops the program from downloading data through the internet
103 Refresh::     reloads the current display
104 Auto-update::  automatically refresh the the radar after a certain delay
105 Clean cache:: removes data files from the program's internal cache
106 Quit::        closes the program window and exits from memory
107
108 Edit
109 ~~~~
110 Preferences:: opens the preferences window, which contains the following
111               commands
112
113         General tab:::
114
115 [horizontal]
116                 Offline checkbox::::     if selected keeps the program from connecting
117                                          to the internet
118                 Update Freq::::          sets the timeout value for automatic updating
119                 Initial site listbox:::: allows the user to select a default radar site
120                                          to jump to when the program loads
121                 NEXRAD URL text box::::  allows the user to select a different server to
122                                          download Level-II NEXRAD data from
123                 Debug level text box:::: allows the user to select what level of
124                                          debugging the program should conduct while
125                                          running (7 is recommended only for debugging)
126
127         Plugins tab:::
128
129 [horizontal]
130                 alert checkbox::::       allows the user to toggle the weather alerts
131                 elev checkbox::::        allows the user to toggle terrain rendering
132                 env checkbox::::         allows the user to toggle a blue atmosphere and
133                                          compass rose
134                 gps checkbox::::         allows the user to toggle gps tracking
135                                          [Linux only]
136                 map checkbox::::         allows the user to toggle the map overlays
137                 radar checkbox::::       allows the user to toggle the radar data
138                 sat checkbox::::         allows the user to toggle satellite ground images
139                 test checkbox::::        used by the developers for debugging
140
141 View
142 ~~~~
143 [horizontal]
144 Zoom in::     decreases the viewing area
145 Zoom out::    increases the viewing area
146 Fullscreen::  maximizes the window and only displays the button menu bar along
147               with the map and data viewing pane when the mouse is moved to the
148               edge of the screen
149
150 Radar
151 ~~~~~
152 The radar menu contains list of all the support NEXRAD radar sites sorted by
153 state. Selecting a site will zoom AWeather to that location.
154
155 Help
156 ~~~~
157 [horizontal]
158 User Guide::  displays this documentation of program operation and features
159 Man Page::    displays a HTML version of the UNIX man page
160 About::       contains current program version, copyright, development site,
161               credits and licensing information
162
163
164 The button bar
165 --------------
166 The program button bar contains 6 options:
167
168 [horizontal]
169 Magnifying glass with plus sign::   decreases the viewing area
170 Magnifying glass with minus sign::  increases the viewing area
171 Window icon with expanding arrows:: Toggles between fullscreen and normal viewing modes
172 Plug button::                       toggles between offline and online program mode
173 Circular arrow button::             reloads the current display
174 Wrench and screwdriver button::     Opens the preferences window
175
176
177 The date and time side bar
178 --------------------------
179 The date and time side bar resides on the right side of the program window, it contains:
180
181 * The date button, which reveals a calendar of the current month when clicked
182
183 * The time button, which reveals a list of each hour when clicked
184
185 ** Clicking on an hour will reveal a list of times in 5 minute intervals that
186    the user can select to load radar data from footnote:[Radar data can only be
187    loaded if it has been previously cached or is from a recent enough date and
188    can still be obtained from the NEXRAD server]
189
190
191 The map and data viewing pane
192 -----------------------------
193 On program startup and when zoomed far from the earth's surface AWeather
194 displays a national radar composite image.
195
196 Each available radar site is displayed on the map using the name of a nearby
197 major city. Clicking on the city label will activate the radar site and center
198 it in the viewer.
199
200 As the user zooms closer to the earth AWeather will automatically activate
201 nearby radar sites.
202
203 The radar data will be plotted on the map while the scan and product information
204 will be displayed at the bottom of the program.
205
206 All active radar sites will show as tabs while site's available tilt and product
207 data will display to the right of the tab.
208
209 Simply click on a button to display that product/tilt in the map window.
210
211 An isosurface slider is shown below the product/tilt buttons.  Slide the
212 selector to reveal the rendered isosurface structure of reflectivity data.
213
214 A color scale will automatically appear at the top left corner of the map window
215 corresponding to each available product.
216
217
218 Viewing severe  weather alerts
219 ------------------------------
220 When the alert plugin is enabled, AWeather will automatically shade each county
221 that is under a weather alert in a color corresponding to the type of alert.
222
223 For storm based warnings, AWeather will also draw a polygon representing the
224 warning area.
225
226 Individual alert types can be enabled and disabled by clicking on the toggle
227 button in the alert tab at the bottom of the screen.
228
229 To view more information about a particular alert, click on one the shaded
230 county or inside the polygon warning area in the viewing pane. This will bring
231 up the alert details dialog with a tab for each alert that is active for the
232 location that was clicked.
233
234 The alert dialog displays the alert title and valid time along with the text
235 descriptions provided by the weather service. Clicking the "Full Text" button
236 will open the full text of the alert in a web browser.
237
238
239 Panning, zooming and tilt functions
240 -----------------------------------
241 AWeather supports the use of the mouse and keyboard commands to change the map
242 window settings.
243
244 When the map is rotated, a red and white compass in the top right corner shows
245 the current direction of North. Clicking on the compass will reset the rotation
246 so that north points toward the top of the screen and the viewer is pointed
247 towards the ground.
248
249 Mouse usage::
250 [horizontal]
251         Left click and drag:::    Pan the surface of the earth
252         Middle click and drag:::  Zoom toward or away from the earth
253         Right click and drag:::   Rotate the camera left or right
254
255 Keyboard shortcuts::
256 [horizontal]
257         h:::                  Pan left
258         j:::                  Pan down
259         k:::                  Pan up
260         l:::                  Pan right
261         i, +, Scroll Up:::    Zoom in
262         o, -, Scroll Down:::  Zoom out
263         J:::                  Rotate camera toward earth
264         K:::                  Rotate camera toward sky
265         H:::                  Rotate camera left
266         L:::                  Rotate camera right
267         w:::                  Draw wire frame of the earth (for debugging)
268         q:::                  Exit the program
269         Tab:::                Cycle through available plugins
270         Escape:::             Close the currently active dialog box
271         CTRL+R:::             Refresh the display
272
273
274 Command Line Options
275 --------------------
276 The following command line options can help advanced users take full advantage
277 of the AWeather program:
278
279 aweather [*-hoaf*] [-d 'level'] [-s 'site'] [-t 'time']
280
281 *-h*, *--help*::
282         Show usage.
283
284 *-d*, *--debug*='level'::
285         Change default log level*, a debug level ranges from 0 to 5. A debug
286         level of 5 is recommended only for debugging purposes.
287
288 *-s*, *--site*='site'::
289         Set initial site. The site should be given as a WSR88D site code such
290         as KLSX.
291
292 *-t*, *--time*='time'::
293         Set initial time. The time format should be provided in the
294         *YYYY-MM-DD HH:MM* format.
295
296 *-o*, *--offline*::
297         Run in offline mode, AWeather will not attempt to connect to the
298         internet to download radar files but will show the closest matching
299         cached file.
300
301 *-a*, *--autoupdate*::
302         Run in autoupdate mode, AWeather will periodically poll data servers
303         for updated information.
304
305 *-f*, *--fullscreen*::
306         Run in fullscreen mode, AWeather start up using the entire screen as he
307         main display area. Toolbars and side panels are hidden by default.
308
309
310 Future Features
311 ---------------
312 The author intends to develop additional features in the future as time and
313 conditions allow.
314
315 Some of these enhancements include:
316
317         * Vertical cross sections
318         * Support for derived L3 data (storm relative motion, echo tops, composite
319           reflectivity, etc.)
320         * Additional data sources for surface data, etc.
321         * Animation support
322         * API for radar algorithms
323         * Additional features
324
325 // vim: ft=asciidoc ts=4 tw=80