gridtools

A small Python library to convert between maidenhead grid locators and lat/long coördinates.

Installation

gridtools requires Python 3.8 at minimum. Install by running:

$ pip install gridtools

License

Copyright 2020 classabbyamp, 0x5c

Released under the BSD 3-Clause License. See LICENSE for the full license text.

CLI Usage

gridtools has a basic CLI interface, which can be run using:

$ python3 -m gridtools

It can be used with the following arguments:

usage: gridtools [-h] [-g GRID] [-l LATLONG] [-d LOC LOC]

arguments:
  -h, --help            show this help message and exit
  -g GRID, --cg GRID, --convgrid GRID
                        convert a grid locator to a lat/long pair
  -l LATLONG, --cl LATLONG, --convlatlong LATLONG
                        convert a lat/long pair to a grid locator
  -d LOC LOC, --dist LOC LOC, --distance LOC LOC
                        find the distance and bearing from one location to
                        another, specified with grid locator or lat/long
                        pair

Note

if you get an error about expected 1 argument when you give a lat/long pair, try replacing the preceding space with an =. For example: --cl=-12.123,43.21.

API

class gridtools.LatLong(lat, long)

Represents a latitude/longitude pair.

Parameters
  • lat (Union[float, int]) – the latitude

  • long (Union[float, int]) – the longitude

property lat
Getter

gets the latitude of the object

Return type

float

Setter

sets the latitude of the object

Type

Union[float, int]

Raises

ValueError – if given an invalid latitude

property long
Getter

gets the longitude of the object

Return type

float

Setter

sets the longitude of the object

Type

Union[float, int]

Raises

ValueError – if given an invalid longitude

class gridtools.Grid(input)

Represents a maidenhead grid locator.

Parameters

input – the grid locator or a LatLong object

Type

Union[str, LatLong]

property grid
Getter

gets the grid locator of the object

Return type

str

Setter

sets the grid locator of the object

Type

str

Raises

ValueError – if given an invalid grid locator

property elements
Getter

gets the grid locator of the object, divided into each pair.

Return type

Tuple[str, ]

property field
Getter

gets the field of the grid locator of the object, e.g. FN

Return type

str

property square
Getter

gets the square of the grid locator of the object, e.g. FN01

Return type

str

property subsquare
Getter

gets the subsquare of the grid locator of the object, e.g. FN01ce

Return type

str

property extended_square

This is a read-only alias to grid.

Getter

gets the extended square of the grid locator of the object, e.g. FN01ce24

Return type

str

property latlong
Getter

gets the lat/long pair of the center of the grid locator of the object

Return type

LatLong

Setter

sets the lat/long pair of the object

Type

LatLong

property lat
Getter

gets the latitude of the object

Return type

float

Setter

sets the latitude of the object

Type

Union[float, int]

Raises

ValueError – if given an invalid latitude

property long
Getter

gets the longitude of the object

Return type

float

Setter

sets the longitude of the object

Type

Union[float, int]

Raises

ValueError – if given an invalid longitude

gridtools.check_latlong(lat, long)

Check if a pair of 2 float or ints is a valid lat/long pair.

Parameters
  • lat (Union[float, int]) – the latitude value to check

  • long (Union[float, int]) – the longitude value to check

Returns

True if valid, False if not.

Return type

bool

gridtools.check_grid(input)

Check if a string is a valid 2-8 character maidenhead grid.

Parameters

input (str) – the string to check

Returns

True if valid, False if not.

Return type

bool

gridtools.grid_distance(location1, location2)

Finds the great circle distance and bearing between two Grid or LatLong objects.

Parameters
  • location1 (Union[Grid, LatLong]) – the location from which to measure

  • location2 (Union[Grid, LatLong]) – the location to which to measure

Returns

the great circle distance (in kilometres) and the bearing (in degrees) from location1 to location2

Return type

Tuple[float, float]

A Note on Precision

Although this library outputs grid locators in extended square form by default, that is not always the best choice to use. On HF, the most precision needed for most applications is a grid square (e.g. FN01). On VHF and UHF, the most precision needed is usually a subsquare (e.g. FN01ca). On microwave, you might need more precision, so one could use the extended square (FN01ca34).

Choose the format that best suits your needs when using this library. Attributes field, square, subsquare, and extended_square are included to make that easier. If you don’t want to choose right away, grid_elements can give the grid locator in a handy tuple format.

For latitude and longitude, gridtools stores values as floats internally, and when providing strings, uses 6 digits of precision. This is precise enough to recognise individual humans (see here), so it is probably overkill for the scale of a grid locator.