Gridsquare (gridsquare v0.2.0)

GridSquare calculator for encoding/decoding between latitude/longitude and Maidenhead Locator System grid references.

The Maidenhead Locator System is used by ham radio operators to exchange approximate locations. It uses a base conversion system with changing radix:

First pair: base 18 (A-R) for 10° lat × 20° lon fields
Second pair: base 10 (0-9) for 1° lat × 2° lon squares
Third pair: base 24 (A-X) for 2.5' lat × 5' lon subsquares
Fourth pair: base 10 (0-9) for extended subsquares
Can be extended indefinitely with alternating base 10/base 24 pairs

Summary

Types

base18_char()

Base18 char (A-R)

base24_char()

Base24 char (A-X)

coordinates()

Internal coordinates for extended precision

decode_result()

distance_result()

encode_result()

field_index()

Field index (0-17)

grid_height()

Height of grid square in degrees

grid_reference()

Maidenhead grid reference string (uppercase/lowercase, 6-20 chars)

grid_square()

grid_width()

Width of grid square in degrees

latitude()

Latitude in degrees (-90.0 to 90.0)

longitude()

Longitude in degrees (-180.0 to 180.0)

normalized_latitude()

Latitude normalized to -90.0 <= x < 90.0

normalized_longitude()

Longitude normalized to -180.0 <= x < 180.0

precision()

Precision (number of characters in grid reference, 6 to 20)

square_index()

Square index (0-9)

subsquare()

Subsquare string (lowercase, 6 chars)

subsquare_index()

Subsquare index (0-23)

Functions

decode(grid_reference)

Decodes a grid square reference to latitude and longitude.

distance_between(grid_ref1, grid_ref2)

Calculates the distance and direction between two grid squares.

encode(lon, lat, precision \\ 6)

Encodes latitude and longitude to a grid square reference.

new(grid_reference)

Creates a new GridSquare struct from a grid reference.

Types

base18_char()

@type base18_char() :: String.t()

Base18 char (A-R)

base24_char()

@type base24_char() :: String.t()

Base24 char (A-X)

coordinates()

@type coordinates() :: %{
  lon: longitude(),
  lat: latitude(),
  field_lon: field_index(),
  field_lat: field_index(),
  square_lon: square_index(),
  square_lat: square_index(),
  subsquare_lon: subsquare_index(),
  subsquare_lat: subsquare_index()
}

Internal coordinates for extended precision

decode_result()

@type decode_result() :: Gridsquare.DecodeResult.t()

distance_result()

@type distance_result() :: Gridsquare.DistanceResult.t()

encode_result()

@type encode_result() :: Gridsquare.EncodeResult.t()

field_index()

@type field_index() :: 0..17

Field index (0-17)

grid_height()

@type grid_height() :: float()

Height of grid square in degrees

grid_reference()

@type grid_reference() :: <<_::48, _::_*8>>

Maidenhead grid reference string (uppercase/lowercase, 6-20 chars)

grid_square()

@type grid_square() :: Gridsquare.GridSquare.t()

grid_width()

@type grid_width() :: float()

Width of grid square in degrees

latitude()

@type latitude() :: float()

Latitude in degrees (-90.0 to 90.0)

longitude()

@type longitude() :: float()

Longitude in degrees (-180.0 to 180.0)

normalized_latitude()

@type normalized_latitude() :: float()

Latitude normalized to -90.0 <= x < 90.0

normalized_longitude()

@type normalized_longitude() :: float()

Longitude normalized to -180.0 <= x < 180.0

precision()

@type precision() :: 6..20

Precision (number of characters in grid reference, 6 to 20)

square_index()

@type square_index() :: 0..9

Square index (0-9)

subsquare()

@type subsquare() :: <<_::48>>

Subsquare string (lowercase, 6 chars)

subsquare_index()

@type subsquare_index() :: 0..23

Subsquare index (0-23)

Functions

decode(grid_reference)

@spec decode(grid_reference()) :: decode_result()

Decodes a grid square reference to latitude and longitude.

Examples

iex> Gridsquare.decode("DN40bi")
%Gridsquare.DecodeResult{latitude: 40.35416666666667, longitude: -111.875, width: 0.08333333333333333, height: 0.041666666666666664}

distance_between(grid_ref1, grid_ref2)

@spec distance_between(grid_reference(), grid_reference()) :: distance_result()

Calculates the distance and direction between two grid squares.

Returns a struct with:

distance_km: Distance in kilometers
distance_mi: Distance in miles
bearing_degrees: Bearing in degrees (0-360)

Examples

iex> result = Gridsquare.distance_between("DN40bi", "DN40bj")
iex> %Gridsquare.DistanceResult{distance_km: distance_km, distance_mi: distance_mi, bearing_degrees: bearing_degrees} = result
iex> distance_km > 0
true
iex> distance_mi > 0
true
iex> bearing_degrees >= 0 and bearing_degrees <= 360
true

iex> result = Gridsquare.distance_between("DN40bi", "DN40ci")
iex> %Gridsquare.DistanceResult{distance_km: distance_km, distance_mi: distance_mi, bearing_degrees: bearing_degrees} = result
iex> distance_km > 0
true
iex> distance_mi > 0
true
iex> bearing_degrees >= 0 and bearing_degrees <= 360
true

iex> result = Gridsquare.distance_between("DN40bi", "DN40cj")
iex> %Gridsquare.DistanceResult{distance_km: distance_km, distance_mi: distance_mi, bearing_degrees: bearing_degrees} = result
iex> distance_km > 0
true
iex> distance_mi > 0
true
iex> bearing_degrees >= 0 and bearing_degrees <= 360
true

encode(lon, lat, precision \\ 6)

@spec encode(longitude(), latitude(), precision()) :: encode_result()

Encodes latitude and longitude to a grid square reference.

Examples

iex> Gridsquare.encode(-111.866785, 40.363840)
%Gridsquare.EncodeResult{grid_reference: "DN40bi", subsquare: "dn40bi"}

iex> Gridsquare.encode(-111.866785, 40.363840, 10)
%Gridsquare.EncodeResult{grid_reference: "DN40BI00OR", subsquare: "dn40bi"}

new(grid_reference)

@spec new(grid_reference()) :: grid_square()

Creates a new GridSquare struct from a grid reference.

Examples

iex> grid = Gridsquare.new("DN40bi")
iex> grid.center
%{latitude: 40.35416666666667, longitude: -111.875}
iex> grid.width
0.08333333333333333
iex> grid.height
0.041666666666666664