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

Module dms

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

After (C) Chris Veness 2011-2015 published under the same MIT Licence**, see Latitude/Longitude and Vector-based geodesy.


Version: 19.09.07

Classes
  RangeError
Error raised for lat- or longitude values outside the clip, clipLat, clipLon or limit range in function clipDMS, parse3llh, parseDMS or parseDMS2.
Functions
 
bearingDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string.
 
clipDMS(deg, limit)
Clip a lat- or longitude to the given range.
 
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.
 
degDMS(deg, prec=6, s_D='°', s_M='', s_S='', neg='-', pos='')
Convert degrees to a string in degrees, minutes or seconds.
 
latDMS(deg, form='dms', prec=2, sep='')
Convert latitude to a string, optionally suffixed with N or S.
 
lonDMS(deg, form='dms', prec=2, sep='')
Convert longitude to a string, optionally 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=',', clipLat=90, clipLon=180)
Parse a string representing lat-, longitude and height point.
 
parseDMS(strDMS, suffix='NSEW', sep='', clip=0)
Parse a string representing deg°min′sec″ to degrees.
 
parseDMS2(strLat, strLon, sep='', clipLat=90, clipLon=180)
Parse lat- and longitude representions.
 
precision(form, prec=None)
Set the default precison for a given F_ form.
 
rangerrors(raiser=None)
Gert/set raising of range errors.
 
toDMS(deg, form='dms', prec=2, sep='', ddd=2, neg='-', pos='')
Convert signed degrees to string, without suffix.
Variables
  __all__ = _ALL_LAZY.dms
  F_D = 'd'
Format degrees as unsigned "deg°" plus suffix (str).
  F_DM = 'dm'
Format degrees as unsigned "deg°min′" plus suffix (str).
  F_DMS = 'dms'
Format degrees as unsigned "deg°min′sec″" plus suffix (str).
  F_DEG = 'deg'
Format degrees as unsigned "[D]DD" plus suffix without symbol (str).
  F_MIN = 'min'
Format degrees as unsigned "[D]DDMM" plus suffix without symbols (str).
  F_SEC = 'sec'
Format degrees as unsigned "[D]DDMMSS" plus suffix without symbols (str).
  F_RAD = 'rad'
Convert degrees to radians and format as unsigned "RR" plus suffix (str).
  F_D_ = '-d'
Format degrees as signed "-/deg°" without suffix (str).
  F_DM_ = '-dm'
Format degrees as signed "-/deg°min′" without suffix (str).
  F_DMS_ = '-dms'
Format degrees as signed "-/deg°min′sec″" without suffix (str).
  F_DEG_ = '-deg'
Format degrees as signed "-/[D]DD" without suffix and symbol (str).
  F_MIN_ = '-min'
Format degrees as signed "-/[D]DDMM" without suffix and symbols (str).
  F_SEC_ = '-sec'
Format degrees as signed "-/[D]DDMMSS" without suffix and symbols (str).
  F_RAD_ = '-rad'
Convert degrees to radians and format as signed "-/RR" without suffix (str).
  F_D__ = '+d'
Format degrees as signed "-/+deg°" without suffix (str).
  F_DM__ = '+dm'
Format degrees as signed "-/+deg°min′" without suffix (str).
  F_DMS__ = '+dms'
Format degrees as signed "-/+deg°min′sec″" without suffix (str).
  F_DEG__ = '+deg'
Format degrees as signed "-/+[D]DD" without suffix and symbol (str).
  F_MIN__ = '+min'
Format degrees as signed "-/+[D]DDMM" without suffix and symbols (str).
  F_SEC__ = '+sec'
Format degrees as signed "-/+[D]DDMMSS" without suffix and symbols (str).
  F_RAD__ = '+rad'
Convert degrees to radians and format as signed "-/+RR" without suffix (str).
  S_DEG = '°'
Degrees "°" symbol (str).
  S_MIN = ''
Minutes "′" symbol (str).
  S_SEC = ''
Seconds "″" symbol (str).
  S_RAD = ''
Radians symbol "" (str).
  S_SEP = ''
Separator between deg, min and sec "" (str).
Function Details

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

 

Convert bearing to a string.

Parameters:
Returns:
Compass degrees per the specified form (str).

JS name: toBrng.

clipDMS(deg, limit)

 

Clip a lat- or longitude to the given range.

Parameters:
  • deg - Unclipped lat- or longitude (degrees).
  • limit - Valid -limit..+limit range (degrees).
Returns:
Clipped value (degrees).
Raises:

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

 

Convert bearing to a string suffixed with compass point.

Parameters:
Returns:
Compass degrees and point in the specified form (str).

compassPoint(bearing, prec=3)

 

Convert bearing to a compass point.

Parameters:
  • bearing - Bearing from North (compass degrees360).
  • 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 str).
Raises:
  • ValueError - Invalid prec.

See Also: Dms.compassPoint and Compass rose.

Example:

>>> p = compassPoint(24, 1)  # 'N'
>>> p = compassPoint(24, 2)  # 'NE'
>>> p = compassPoint(24, 3)  # 'NNE'
>>> p = compassPoint(24)     # 'NNE'
>>> p = compassPoint(11, 4)  # 'NbE'
>>> p = compassPoint(30, 4)  # 'NEbN'
>>> p = compassPoint(11.249)  # 'N'
>>> p = compassPoint(11.25)   # 'NNE'
>>> p = compassPoint(-11.25)  # 'N'
>>> p = compassPoint(348.749) # 'NNW'

degDMS(deg, prec=6, s_D='°', s_M='', s_S='', neg='-', pos='')

 

Convert degrees to a string in degrees, minutes or seconds.

Parameters:
  • deg - Value in degrees (scalar).
  • 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.
  • s_D - Symbol for degrees (str).
  • s_M - Symbol for minutes (str) or "".
  • s_S - Symbol for seconds (str) or "".
  • neg - Optional sign for negative ('-').
  • pos - Optional sign for positive ('').
Returns:
Either degrees, minutes or seconds (str).

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

 

Convert latitude to a string, optionally suffixed with N or S.

Parameters:
Returns:
Degrees in the specified form (str).

JS name: toLat.

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

 

Convert longitude to a string, optionally suffixed with E or W.

Parameters:
Returns:
Degrees in the specified form (str).

JS name: toLon.

normDMS(strDMS, norm='')

 

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

Parameters:
  • strDMS - DMS (str).
  • norm - Optional replacement symbol, default symbol otherwise (str).
Returns:
Normalized DMS (str).

parse3llh(strll, height=0, sep=',', clipLat=90, clipLon=180)

 

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

Parameters:
  • strll - Latitude, longitude[, height] (str, ...).
  • height - Optional, default height (meter).
  • sep - Optional separator (str).
  • clipLat - Keep latitude in -clipLat..+clipLat (degrees).
  • clipLon - Keep longitude in -clipLon..+clipLon range (degrees).
Returns:
A LatLon3Tuple(lat, lon, height) in degrees, degrees and float.
Raises:
  • RangeError - Lat- or longitude value of strll outside valid range and rangerrors set to True.
  • ValueError - Invalid strll.

See Also: Functions parseDMS and parseDMS2 for more details on the forms and symbols accepted.

Example:

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

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

 

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 (str or degrees).
  • suffix - Optional, valid compass directions (NSEW).
  • sep - Optional separator between deg°, min′ and sec″ ('').
  • clip - Optionally, limit value to -clip..+clip (degrees).
Returns:
Degrees (float).
Raises:
  • RangeError - Value of strDMS outside the valid range and rangerrors set to True.
  • ValueError - Invalid strDMS.

See Also: Function parse3llh to parse a string with lat-, longitude and height values.

parseDMS2(strLat, strLon, sep='', clipLat=90, clipLon=180)

 

Parse lat- and longitude representions.

Parameters:
  • strLat - Latitude in any of several forms (str or degrees).
  • strLon - Longitude in any of several forms (str or degrees).
  • sep - Optional separator between deg°, min′ and sec″ ('').
  • clipLat - Keep latitude in -clipLat..+clipLat range (degrees).
  • clipLon - Keep longitude in -clipLon..+clipLon range (degrees).
Returns:
A LatLon2Tuple(lat, lon) in degrees.
Raises:
  • RangeError - Value of strLat or strLon outside the valid range and rangerrors set to True.
  • ValueError - Invalid strLat or strLon.

See Also: Function parse3llh to parse a string with lat-, longitude and height values and function parseDMS to parse individual lat- or longitudes.

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 (str).
  • 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.
Returns:
Previous precision (int).
Raises:
  • ValueError - Invalid form or prec or beyond valid range.

rangerrors(raiser=None)

 

Gert/set raising of range errors.

Parameters:
  • raiser - Choose True to raise or False to ignore RangeError exceptions. Use None to leave the setting unchanged.
Returns:
Previous setting (bool).

Note: Out-of-range lat- and longitude values are always clipped to the nearest range limit.

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

 

Convert signed degrees to string, without suffix.

Parameters:
  • deg - Degrees to be formatted (degrees).
  • form - Optional deg format (str or F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F_RAD without suffix, F_D_, F_DM_, F_DMS_, F_DEG_, F_MIN_, F_SEC_, F_RAD_, F_D__, F_DM__, F_DMS__, F_DEG__, F_MIN__, F_SEC__ or F_RAD__).
  • 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.
  • sep - Optional separator (str).
  • ddd - Optional number of digits for deg° (2 or 3).
  • neg - Optional sign for negative degrees ('-').
  • pos - Optional sign for positive degrees ('').
Returns:
Degrees in the specified form (str).