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.06.04

Functions
 
bearingDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string.
 
compassDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string suffixed with compass point.
 
compassPoint(bearing, prec=3)
Convert bearing to a compass point.
 
latDMS(deg, form='dms', prec=2, sep='')
Convert latitude to a string suffixed with N or S.
 
lonDMS(deg, form='dms', prec=2, sep='')
Convert longitude to a string suffixed with E or W.
 
normDMS(strDMS, norm='')
Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″.
 
parse3llh(strll, height=0, sep=',')
Parse a string representing lat-, longitude and height point.
 
parseDMS(strDMS, suffix='NSEW', sep='')
Parse a string representing deg°min′sec″ to degrees.
 
precision(form, prec=None)
Set the default precison for a given F_ form.
 
toDMS(deg, form='dms', prec=2, sep='', ddd=2, neg='-', pos='')
Convert 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 [D]DD without symbol (string).
  F_MIN = 'min'
Format degrees as [D]DDMM without symbols (string).
  F_SEC = 'sec'
Format degrees as [D]DDMMSS without symbols (string).
  F_RAD = 'rad'
Convert degrees to radians and format as RR.r (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, sep='')

 

Convert bearing to a string.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (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.
  • sep - Optional, separator (string).
Returns:
Compass degrees per the specified form (string).

JS name: toBrng.

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

 

Convert bearing to a string suffixed with compass point.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (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.
  • sep - Optional, separator (string).
Returns:
Compass degrees and point per the specified form (string).

compassPoint(bearing, prec=3)

 

Convert bearing to a compass point.

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

See Also: Compass rose

Example:

>>> p = compassPoint(24)     # 'NNE'
>>> p = compassPoint(24, 1)  # 'N'
>>> p = compassPoint(24, 2)  # 'NE'
>>> p = compassPoint(18, 3)  # 'NNE'
>>> p = compassPoint(12, 4)  # 'NbE'
>>> p = compassPoint(30, 4)  # 'NEbN'

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

 

Convert latitude to a string suffixed with N or S.

Parameters:
  • deg - Latitude to be formatted (degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, DD, DDMM, DDMMSS or radians (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.
  • sep - Optional, separator (string).
Returns:
Degrees per the specified form (string).

JS name: toLat.

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

 

Convert longitude to a string suffixed with E or W.

Parameters:
  • deg - Longitude to be formatted (degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, DDD, DDDMM, DDDMMSS or radians (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.
  • sep - Optional, separator (string).
Returns:
Degrees per the specified form (string).

JS name: toLon.

normDMS(strDMS, norm='')

 

Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″.

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

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

 

Parse 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='')

 

Parse 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)

 

Set the default precison for a given F_ form.

Parameters:
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC 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, sep='', ddd=2, neg='-', pos='')

 

Convert signed degrees to string, without suffix.

Parameters:
  • deg - Degrees to be formatted (scalar).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (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.
  • sep - Optional, separator (string).
  • 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).