My Maidenhead Calculator: IO91pm

• "IO91pm" was intended as the working-title for the development of my Maidenhead-calculator, but I got used to it. I found a a pleasing, somewhat recursive name; so I decided to keep it. See, however, below for other names.
• This web-site was the place to document early development.
  • Now the program has reached "Version 1" release, I moved further development to a more public repository.
• But, there are a few points that are easier to document here.

• For another little project, I wanted a QTH-Locator calculator for the UNIX (-look-a-likes, GNU/Linux, bash) command-line.
• There are many, some very good, online QTH resources, but I wanted something that would also work off-line.
• There also several GUI- (X11-) based calculators, but I wanted something for the command-line, something that could also be used in (bash-)scripts.
• The software-repository for my (Ubuntu-derived) Linux distro has only one such a QTH-calculator, but
  • This program has a few issues (I would probably have accepted)
  • Made worse by the adaption for Ubuntu, that removed half of its functionality
• So, I had to make my own. (Which I enjoyed anyhow.)

• Proper support for 2, 4, 6, 8 or 10 character locators.
  A 10 character locator specifies a cell of more-or-less the size of a house.
• Distance and bearing calculations are based on the algorithms presented in the book: "Amateur Radio Software" by John Morris (GM4ANB) published: RSGB, Potters Bar, UK, 1985.
• The calculations are done from and to cell-centers (instead of south-west corner, as some programs do).
  This is especially better when computing between locators of different resolutions (locators with different number of characters). But also close to the poles can the difference be significant.
• Distance calculations are based on the best of GM4ANB's algorithms (instead of the simplest, as some programs do).
  
  • The simplest algorithm can introduce an error of up-to a hundred meters within a relatively small, flat and low-lying, mid-latitude area such as the Netherlands.
    
  • The best of GM4ANB's algorithms computes distances that fit, within a few meter, to the Dutch national grid reference system, the "Rijksdriehoekscoördinaten" system.
• This program reports an estimate of the error range.
• By renaming the program (or creating a (soft-) link to it) with as new name a valid QTH locator, then distance calculations will be done from that locator.
• Most of this software will be published under the GPLv3 license.
  Except for two clearly indicated cases that use more relax licenses:
  • optparse.h is public-domain software from github/skeeto/optparse,
  • rounding.[ch] is 3-clause-BSD licensed: See here.
• The program uses, for some math-symbols etc., UTF-8, when the environment seems to be able to handle UTF-8.
• And, lastly, the code uses τ (tau) instead of π (math pi).

The program obviously requires, for distance and bearing calculations, two locators: the base-location and the target-location. The base-locator is typically the location of the user; is therefore often the same between different runs of this program. The program uses some mechanisms to determine this base-locator:

• The base-locator can be given on he command-line, as in the explanations above. It is either the first locator-string or the locator-string explicitly indicated with --baseLocation (or -b).
  A base-locator given on the command-line takes precedence over the following mechanisms.
• If the environment-variable BASE_LOCATOR is set to a valid locator, then that is used as the base-locator when no base-locator is given on the command-line. This might be a useful approach when calling the program from a script. This environment-variable takes precedence over the following mechanism.
• if the program is renamed, or a (soft-) link to it is created, with as new name a valid locator, then this locator is used as the default base-locator.
  • For example: to create a program that computes, by default, distances from the Dutch/German/Belgian tripoint at JO30as21ma:

$ ln -s $(BIN?)/IO91pm $(BIN?)/JO30as21ma
$ JO30as21ma -d JO33il91ms
305.75 ± 0.32 km
$ JO30as21ma -d "JO11qi48fv Most westerly point in European Netherland"
198.17 ± 0.24 km
$ JO30as21ma -b JO11qi48fv -d JO33il91ms 
327.29 ± 0.35 km

The released versions of the C source files, C header files and a minimal makefile can be downloaded from the SourceForce repository.

Below are some development versions.
Compressed tar (tgz) archives can be unpacked it with one of these programs.
I also have a full set of tests, but these are not yet "publication-ready".

Be careful when including these versions in other scripts, details of the behaviour of these development programs might still change.

$ ls -lr *.tgz
-rw-r–r– 1 pe1aqp pe1aqp 21566 Apr 3 19:46 io91pm-20230403.tgz
-rw-r–r– 1 pe1aqp pe1aqp 20290 Mar 20 17:38 io91pm-20230320.tgz
$

• my software page
• my home page