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

Module dms

Parsers and formatters of degrees, minutes and seconds.

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: 21.06.23

Classes
  ParseError
Error parsing degrees, radians or several other formats.
Functions
 
bearingDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string.
 
clipDegrees(deg, limit)
Clip a lat- or longitude to the given range.
 
clipRadians(rad, 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='\xe2\x80\xb2', 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.
 
latlonDMS(lls, form='dms', prec=None, sep=None)
Convert one or more LatLon instances to strings.
 
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 %s, %s and %s.
 
parseDDDMMSS(strDDDMMSS, suffix='NSEW', sep='', clip=0)
Parse a lat- or longitude represention form [D]DDMMSS in degrees.
 
parseDMS(strDMS, suffix='NSEW', sep='', clip=0)
Parse a lat- or longitude representation "lat, lon" in degrees.
 
parseDMS2(strLat, strLon, sep='', clipLat=90, clipLon=180)
Parse a lat- and a longitude representions in degrees.
 
parse3llh(strllh, height=0, sep=',', clipLat=90, clipLon=180)
Parse a string "lat lon [h]" representing lat-, longitude in degrees and optional height in meter.
 
parseRad(strRad, suffix='NSEW', clip=0)
Parse a string representing angle in radians.
 
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
  __all__ = _ALL_LAZY.dms
  F_D = 'd'
  F_DM = 'dm'
  F_DMS = 'dms'
  F_DEG = 'deg'
  F_MIN = 'min'
  F_SEC = 'sec'
  F__E = 'e'
  F__F = 'f'
  F__G = 'g'
  F_RAD = 'rad'
  F_D_ = '-d'
  F_DM_ = '-dm'
  F_DMS_ = '-dms'
  F_DEG_ = '-deg'
  F_MIN_ = '-min'
  F_SEC_ = '-sec'
  F__E_ = '-e'
  F__F_ = '-f'
  F__G_ = '-g'
  F_RAD_ = '-rad'
  F_D__ = '+d'
  F_DM__ = '+dm'
  F_DMS__ = '+dms'
  F_DEG__ = '+deg'
  F_MIN__ = '+min'
  F_SEC__ = '+sec'
  F__E__ = '+e'
  F__F__ = '+f'
  F__G__ = '+g'
  F_RAD__ = '+rad'
  S_DEG = '°'
  S_MIN = '\xe2\x80\xb2'
  S_SEC = ''
  S_RAD = ''
  S_SEP = ''
Function Details

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

 

Convert bearing to a string.

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

JS name: toBrng.

clipDegrees (deg, limit)

 

Clip a lat- or longitude to the given range.

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

clipRadians (rad, limit)

 

Clip a lat- or longitude to the given range.

Arguments:
  • rad - Unclipped lat- or longitude (radians).
  • limit - Valid -limit..+limit range (radians).
Returns:
Clipped value (radians).
Raises:

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

 

Convert bearing to a string suffixed with compass point.

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

compassPoint (bearing, prec=3)

 

Convert bearing to a compass point.

Arguments:
  • 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='\xe2\x80\xb2', s_S='', neg='-', pos='')

 

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

Arguments:
  • 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.

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

JS name: toLat.

latlonDMS (lls, form='dms', prec=None, sep=None)

 

Convert one or more LatLon instances to strings.

Arguments:
Returns:
A str or tuple of sep is None or NN.

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

 

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

Arguments:
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 %s, %s and %s.

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

parseDDDMMSS (strDDDMMSS, suffix='NSEW', sep='', clip=0)

 

Parse a lat- or longitude represention form [D]DDMMSS in degrees.

Arguments:
  • strDDDMMSS - Degrees in any of several forms (str) and types (float, int, other).
  • suffix - Optional, valid compass points (str, tuple).
  • sep - Optional separator between "[D]DD", "MM" and "SS" ('').
  • clip - Optionally, limit value to -clip..+clip (degrees).
Returns:
Degrees (float).
Raises:
  • ParseError - Invalid strDDDMMSS or clip or the strDDDMMSS form is incompatible with the suffixed or suffix compass point.
  • RangeError - Value of strDDDMMSS outside the valid range and rangerrors set to True.
Notes:
  • Type str values "[D]DD", "[D]DDMM" and "[D]DDMMSS" for strDDDMMSS are parsed properly only if either unsigned and suffixed with a valid, compatible, cardinal compassPoint or if unsigned or signed, unsuffixed and with keyword argument suffix set to 'NS', 'EW' or a compatible compassPoint.
  • Unlike function parseDMS, type float, int and other non-str strDDDMMSS values are interpreted form [D]DDMMSS. For example, int(1230) is returned as 12.5 and not 1230.0 degrees. However, int(345) is considered form "DDD" 345 and not "DDMM" 0345, unless suffix specifies compass point 'NS'.

See Also: Functions parseDMS, parseDMS2 and parse3llh.

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

 

Parse a lat- or longitude representation "lat, lon" in degrees.

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

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

Arguments:
  • strDMS - Degrees in any of several forms (str) and types (float, int, other).
  • suffix - Optional, valid compass points (str, tuple).
  • sep - Optional separator between deg°, min′ and sec″ ("''").
  • clip - Optionally, limit value to -clip..+clip (degrees).
Returns:
Degrees (float).
Raises:

Note: Inlike function parseDDDMMSS, type float, int and other non-str strDMS values are considered as decimal degrees. For example, int(1230) is returned as 1230.0 and not as 12.5 degrees and float(345) as 345.0 and not as 3.75 degrees!

See Also: Functions parseDDDMMSS, parseDMS2 and parse3llh.

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

 

Parse a lat- and a longitude representions in degrees.

Arguments:
  • 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:

Note: See the Notes at function parseDMS.

See Also: Functions parseDDDMMSS, parseDMS and parse3llh.

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

 

Parse a string "lat lon [h]" representing lat-, longitude in degrees and optional height in meter.

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.

Arguments:
  • strllh - Latitude, longitude[, height] (str, ...).
  • height - Optional, default height (meter) or None.
  • 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 strllh outside valid range and rangerrors set to True.
  • ValueError - Invalid strllh or height.

Note: See the Notes at function parseDMS.

See Also: Functions parseDDDMMSS, parseDMS and parseDMS2.

Example:

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

parseRad (strRad, suffix='NSEW', clip=0)

 

Parse a string representing angle in radians.

Arguments:
  • strRad - Degrees in any of several forms (str or radians).
  • suffix - Optional, valid compass points (str, tuple).
  • clip - Optionally, limit value to -clip..+clip (radians).
Returns:
Radians (float).
Raises:

precision (form, prec=None)

 

Set the default precison for a given F_ form.

Arguments:
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F__E, F__F, F__G 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 prec outside valid range.

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

 

Convert signed degrees to string, without suffix.

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