1.
Introduction
gridloc is a ncurses-based console application that accepts as
input the Longitude and Latitude of a 'home' position on earth and
calculates its Maidenhead Grid Locator, or given the Grid Locator
of a position, calculates the Longitude and Latitude. It can also
accept the position or grid locator of a second remote point on
earth and calculate the bearing and distance from the home
location.
If invoked from an X terminal and xplanet is installed, it can
also display the position of home/remote locations and the great
circle path graphically, overlayed on the earth's map.
gridloc is a software package released under the GNU General Public License and in the form of source-code files in the C programming language, developed on a UP1000 Alpha computer with SuSE Linux 7.0 installed.
Customization
gridloc is a simple application and it is customized by editing a
few entries in the gridloc.h header file. In previous versions, the
'Home' location's position and name were #define'd in the header
file but now they have been moved to a configuration file
(~/.gridlocrc). Now only some #define's for the color scheme of the
window remain in the header file but these can be left alone.
Compilation
To compile just type make in the gridloc source directory. To test
run, type ./gridloc in the gridloc directory to run the binary.
Type make install to copy the gridloc binary to /usr/local/bin,
this gridloc.html manual to /usr/local/doc and the config file
.gridlocrc to the home directory. Type make uninstall to remove
these files. Type make clean to remove object files from the source
directory and make distclean to remove all but the files included
in the source package.
3. Operation
NOTE: The run time config file ~/.gridlocrc has to be edited before
running gridloc! This can be done in you favorite editor and only
requires two entries, the 'Home' location's position and its name.
Please see the default/.gridlocrc file for more details.
Start gridloc and enter a position as longitude/latitude in degrees, minutes and seconds of arc, then type 'g' to calculate the grid locator. You may type 'd' to enter the default HOME position from the configuration file. Please note that blank position fields are read as a zero value by default. The 'return' key toggles the East/West and North/South flags ahead of longitude and latitude entries.
Enter a Maidenhead grid locator (all six characters) and type 'p' or RETURN to calculate the longitude/latitude of the position. Please note that blank or lower case characters in the locator field will produce erroneous results.
To calculate bearing and distance to a second 'remote' point, enter the longitude/latitude or the grid locator and type 'b'. Both short path and long path bearings (in degrees) and distances (in km) are calculated along a great circle path. If running gridloc in a terminal in X, the 'X' key enables plotting of the home and Remote positions and great circle arc between them using xplanet.
Navigation between the data entry fields: The TAB key moves input focus to the next (right) field. The 'left' and 'right' arrow keys move the cursor to the previous or next character in a field. Additionally, the 'left' arrow moves the input focus to the Locator field when the cursor is in the Longitude Direction (East/West) field. The 'up' and 'down' arrows move the cursor from the 'Home' row to the 'Remote' row and vice-versa. ESC or 'q' quits gridloc.
4. Keystroke
Commands
<d> Enter the default 'Home' position parameters as specified
in the ~/.gridlocrc file into the top row.
<g> Calculate the Maidenhead Grid Locator of a position, given longitude and latitude.
<p> Calculate a position's longitude and latitude given a Maidenhead Grid Locator.
<b> Calculate the bearing and distance to a remote position given its longitude/latitude or grid locator.
<x> Enable the display of home/remote positions and a Great Circle arc using xplanet. This works if gridloc is started from an X terminal.
<q> or ESC Quit gridloc.
Please note that only lower case characters are accepted, to avoid mis-operation when entering grid locator characters in uppercase.
5. Known bugs and
annoyances
I have fixed all bugs I have found. However the validation of input
data is not reliable, because of the way ncurses checks entries,
for example integer ranges and regular expressions are checked at
exit from a field. It is then possible to enter invalid data in a
field and do a calculation with erroneous input and output. To be
safer, type return after entering data to activate the ncurses
validation functions.
6. Files
gridloc is built from three C source files, a header file and a
simple Makefile. Each file is written, as far as I could, so as to
be reusable and limited to functions of similar or related
functionality. All New Curses display functions are in ncscreen.c.
All position/locator calculations are in calculate.c. The main()
function and some flag and signal handling functions are in main.c.
Some customizable color definitions are in gridloc.h. The 'Home'
location's position and name are entered in the ~/.gridlocrc config
file, which should be edited by the user.
7. Version History
Version 0.1_beta is the first public beta release of gridloc
after bug-fixing and testing locally.
Version 0.2_beta incorporates a fix for a silly bug that should have been obvious but got away - keystroke command characters typed in the Grid Locator fields would launch the commands, stopping data entry.
Version 0.3 has targets in the Makefile to support make install, uninstall, clean and distclean and it also has this HTML format manual.
Version 0.4 incorporates a fix for a bug that caused incorrect bearing and distance calculations for certain grid locator pairs.
Version 0.5 From this version on, the 'Home' location's position (Longitude and Latitude) are entered in a run time config file, ~/.gridlocrc. This file must be edited by the user in a text editor to include his location's data.
Version 0.6 After a bug report from Juha Vierinen regarding seg faulting of xnec2c, my graphical adaptation of NEC2, I changed all "sprintf" commands to "snprintf" to avoid buffer overruns. Following on the above changes, I revised all similar situations in gridloc source code and changed all "sprintf" commands to "snprintf" just in case. While going through the gridloc source code, I also fixed some minor bugs like typos and tidied error messages.
Version 0.7 Made a few changes in the source code mainly to improve style and checked the source with cppcheck.
8. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details:
Last modified: Fri Feb 7 16:15:49 EET 2003