gridtools¶
A small Python library to convert between maidenhead grid locators and lat/long coördinates.
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.
-
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
¶
-
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
-
property
-
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.
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.