Package pygeodesy :: Module dms
[frames] | no frames]

Module dms

Functions to parse and format bearing, lat- and longitudes in various forms of degrees, minutes and seconds.

After (C) Chris Veness 2011-2015 published under the same MIT Licence**, see http://www.movable-type.co.uk/scripts/latlong.html and http://www.movable-type.co.uk/scripts/latlong-vectors.html.


Version: 17.05.29

Functions
 
bearingDMS(bearing, form='d', prec=None)
Converts bearing to string.
 
compassDMS(bearing, form='d', prec=None)
Converts bearing to string suffixed with compass point.
 
compassPoint(bearing, prec=3)
Converts bearing to compass point.
 
latDMS(deg, form='dms', prec=2)
Converts latitude to string suffixed with N or S.
 
lonDMS(deg, form='dms', prec=2)
Converts longitude to string suffixed with E or W.
 
normDMS(strDMS, norm='')
Normalizes all degrees ˚, minutes ' and seconds " symbols in a string to the defaults °, ′ and ″.
 
parse3llh(strll, height=0, sep=',')
Parses a string representing lat-, longitude and height point.
 
parseDMS(strDMS, suffix='NSEW', sep='')
Parses a string representing deg°min′sec″ to degrees.
 
precision(form, prec=None)
Sets the default precison for a given F_ form.
 
toDMS(deg, form='dms', prec=2, ddd=2, neg='-', pos='')
Converts signed degrees to string, without suffix.
Variables
  F_D = 'd'
Format degrees as deg° (string).
  F_DM = 'dm'
Format degrees as deg°min′ (string).
  F_DMS = 'dms'
Format degrees as deg°min′sec″ (string).
  F_DEG = 'deg'
Format degrees as degrees without symbol (string).
  F_RAD = 'rad'
Convert degrees to radians and format (string).
  S_DEG = '\xc2\xb0'
Degrees ° symbol (string).
  S_MIN = '\xe2\x80\xb2'
Minutes ′ symbol (string).
  S_SEC = '\xe2\x80\xb3'
Seconds ″ symbol (string).
  S_RAD = ''
Radians symbol (string).
  S_SEP = ''
Separator between deg, min and sec (string).
Function Details

bearingDMS(bearing, form='d', prec=None)

 

Converts bearing to string.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • form - Use F_D, F_DM, F_DMS, F_DEG or F_RAD for deg°, deg°min′, deg°min′sec″ or degrees or radians.
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
Returns:
Compass degrees per the specified form (string).

JS name: toBrng.

compassDMS(bearing, form='d', prec=None)

 

Converts bearing to string suffixed with compass point.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • form - Use F_D, F_DM, F_DMS, F_DEG or F_RAD for deg°, deg°min′, deg°min′sec″ or degrees or radians.
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
Returns:
Compass degrees and point per the specified form (string).

compassPoint(bearing, prec=3)

 

Converts bearing to compass point.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • prec - Optional precision (1 for cardinal, 2 for intercardinal or 3 for secondary-intercardinal).
Returns:
Compass point (1-, 2- or 3-letter string).
Raises:
  • ValueError - Invalid prec.

Example:

>>> p = compass(24)     # 'NNE'
>>> p = compass(24, 1)  # 'N'

latDMS(deg, form='dms', prec=2)

 

Converts latitude to string suffixed with N or S.

Parameters:
  • deg - Latitude to be formatted (degrees).
  • form - Use F_D, F_DM, F_DMS, F_DEG or F_RAD for deg°, deg°min′, deg°min′sec″ or degrees or radians.
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
Returns:
Degrees per the specified form (string).

JS name: toLat.

lonDMS(deg, form='dms', prec=2)

 

Converts longitude to string suffixed with E or W.

Parameters:
  • deg - Longitude to be formatted (degrees).
  • form - Use F_D, F_DM, F_DMS, F_DEG or F_RAD for deg°, deg°min′, deg°min′sec″ or degrees or radians.
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
Returns:
Degrees per the specified form (string).

JS name: toLon.

normDMS(strDMS, norm='')

 

Normalizes all degrees ˚, minutes ' and seconds " symbols in a string to the defaults °, ′ and ″.

Parameters:
  • strDMS - DMS (string).
  • norm - Replacement, default symbol otherwise (string).
Returns:
Normalized DMS (string).

parse3llh(strll, height=0, sep=',')

 

Parses a string representing lat-, longitude and height point.

The lat- and longitude value must be separated by a separator character. If height is present it must follow, separated by another separator.

The lat- and longitude values may be swapped, provided at least one ends with the proper compass direction.

See function parseDMS for more details on the forms and symbols accepted.

Parameters:
  • strll - Lat, lon[, height] (string).
  • height - Default for missing height (meter).
  • sep - Optional, separator (string).
Returns:
3-Tuple (lat, lon, height) as (scalars).
Raises:
  • ValueError - Invalid strll.

Example:

>>> t = parse3llh('000°00′05.31″W, 51° 28′ 40.12″ N')  # (51.4778°N, 000.0015°W, 0)

parseDMS(strDMS, suffix='NSEW', sep='')

 

Parses a string representing deg°min′sec″ to degrees.

This is very flexible on formats, allowing signed decimal degrees, degrees and minutes or degrees minutes and seconds optionally suffixed by compass direction NSEW.

A variety of symbols, separators and suffixes are accepted, for example 3° 37′ 09″W. Minutes and seconds may be omitted.

Parameters:
  • strDMS - Degrees in any of several forms (string).
  • suffix - Optional, valid compass directions (NSEW).
  • sep - Optional separator between deg°, min′ and sec″ ('').
Returns:
Degrees (float).
Raises:
  • ValueError - Invalid strDMS.

precision(form, prec=None)

 

Sets the default precison for a given F_ form.

Parameters:
  • form - F_D, F_DM, F_DMS, F_DEG or F_RAD (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
Returns:
Previous precision (int).
Raises:
  • ValueError - Invalid precision.

toDMS(deg, form='dms', prec=2, ddd=2, neg='-', pos='')

 

Converts signed degrees to string, without suffix.

Parameters:
  • deg - Degrees to be formatted (scalar).
  • form - F_D, F_DM, F_DMS, F_DEG or F_RAD for deg°, deg°min′, deg°min′sec″ or degrees or radians.
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • ddd - Optional, number of digits for deg° (2 or 3).
  • neg - Optional, sign for negative degrees ('-').
  • pos - Optional, sign for positive degrees ('').
Returns:
Degrees per the specified form (string).