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

Module dms

Parsers and formatters of angles in degrees, minutes and seconds.

Functions to parse and format bearing, compass, lat- and longitudes in various forms of degrees, minutes and seconds with or without degrees, minute and second symbols plus a compass point suffix, including parsing of decimal and sexagecimal degrees.

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


Version: 21.11.17

Classes
  ParseError
Error parsing degrees, radians or several other formats.
Functions
 
bearingDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string (without compass point suffix).
 
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.
 
latlonDMS_(*lls, **form_prec_sep)
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=None)
Normalize all degree, minute and second DMS symbols in a string to the default DMS symbols '\xc2\xb0', '\xe2\x80\xb2' and '\xe2\x80\xb3'.
 
parseDDDMMSS(strDDDMMSS, suffix='NSEW', sep='', clip=0, sexagecimal=False)
Parse a lat- or longitude represention forms as [D]DDMMSS in degrees.
 
parseDMS(strDMS, suffix='NSEW', sep='', clip=0)
Parse a lat- or longitude representation in degrees.
 
parseDMS2(strLat, strLon, sep='', clipLat=90, clipLon=180)
Parse a lat- and a longitude representions "lat, lon" 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
  S_DEG = '°'
Degrees symbol, default "°"
  S_MIN = '\xe2\x80\xb2'
Minutes symbol, default "′" aka PRIME
  S_SEC = ''
Seconds symbol, default "″" aka DOUBLE PRIME
  S_RAD = ''
Radians symbol, default "" aka NN
  S_SEP = ''
Separator between deg°, min′, sec″ and suffix, default "" aka NN
  F_D = 'd'
Format degrees as unsigned "deg°" with symbol, plus compass point suffix N, S, W or E (str).
  F_D60 = 'd60'
Format degrees as unsigned "[D]DD.MMSS" without symbols plus suffix (str).
  F_D60_ = '-d60'
Format degrees as signed "-/[D]DD.MMSS" without symbols, without suffix (str).
  F_D60__ = '+d60'
Format degrees as signed "-/+[D]DD.MMSS" without symbols, without suffix (str).
  F_DEG = 'deg'
Format degrees as unsigned "[D]DD" without symbol, plus suffix (str).
  F_DEG_ = '-deg'
Format degrees as signed "-/[D]DD" without symbol, without suffix (str).
  F_DEG__ = '+deg'
Format degrees as signed "-/+[D]DD" without symbol, without suffix (str).
  F_DM = 'dm'
Format degrees as unsigned "deg°min′" with symbols, plus suffix (str).
  F_DMS = 'dms'
Format degrees as unsigned "deg°min′sec″" with symbols, plus suffix (str).
  F_DMS_ = '-dms'
Format degrees as signed "-/deg°min′sec″" with symbols, without suffix (str).
  F_DMS__ = '+dms'
Format degrees as signed "-/+deg°min′sec″" with symbols, without suffix (str).
  F_DM_ = '-dm'
Format degrees as signed "-/deg°min′" with symbols, without suffix (str).
  F_DM__ = '+dm'
Format degrees as signed "-/+deg°min′" with symbols, without suffix (str).
  F_D_ = '-d'
Format degrees as signed "-/deg°" with symbol, without suffix (str).
  F_D__ = '+d'
Format degrees as signed "-/+deg°" with symbol, without suffix (str).
  F_MIN = 'min'
Format degrees as unsigned "[D]DDMM" without symbols, plus suffix (str).
  F_MIN_ = '-min'
Format degrees as signed "-/[D]DDMM" without symbols, without suffix (str).
  F_MIN__ = '+min'
Format degrees as signed "-/+[D]DDMM" without symbols, without suffix (str).
  F_RAD = 'rad'
Convert degrees to radians and format as unsigned "RR" with symbol, plus suffix (str).
  F_RAD_ = '-rad'
Convert degrees to radians and format as signed "-/RR" without symbol, without suffix (str).
  F_RAD__ = '+rad'
Convert degrees to radians and format as signed "-/+RR" without symbol, without suffix (str).
  F_SEC = 'sec'
Format degrees as unsigned "[D]DDMMSS" without symbols, plus suffix (str).
  F_SEC_ = '-sec'
Format degrees as signed "-/[D]DDMMSS" without symbols, without suffix (str).
  F_SEC__ = '+sec'
Format degrees as signed "-/+[D]DDMMSS" without symbols, without suffix (str).
  F__E = 'e'
Format degrees as unsigned "%E" without symbols, plus suffix (str).
  F__E_ = '-e'
Format degrees as signed "-/%E" without symbols, without suffix (str).
  F__E__ = '+e'
Format degrees as signed "-/+%E" without symbols, without suffix (str).
  F__F = 'f'
Format degrees as unsigned "%F" without symbols, plus suffix (str).
  F__F_ = '-f'
Format degrees as signed "-/%F" without symbols, without suffix (str).
  F__F__ = '+f'
Format degrees as signed "-/+%F" without symbols, without suffix (str).
  F__G = 'g'
Format degrees as unsigned "%G" without symbols, plus suffix (str).
  F__G_ = '-g'
Format degrees as signed "-/%G" without symbols, without suffix (str).
  F__G__ = '+g'
Format degrees as signed "-/+%G" without symbols, without suffix (str).
Function Details

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

 

Convert bearing to a string (without compass point suffix).

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 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 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 if sep=None or NN and if lls is a list, sequence, tuple, etc.

See Also: Function latlonDMS_.

latlonDMS_ (*lls, **form_prec_sep)

 

Convert one or more LatLon instances to strings.

Arguments:
  • lls - The instances, all positional arguments (LatLons).
  • form_prec_sep - Optional format, precision and separator keyword arguments, see function latlonDMS.
Returns:
A str or tuple if sep=None or NN and if more than one lls is given.

See Also: Function latlonDMS.

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=None)

 

Normalize all degree, minute and second DMS symbols in a string to the default DMS symbols '\xc2\xb0', '\xe2\x80\xb2' and '\xe2\x80\xb3'.

Arguments:
  • strDMS - DMS (str).
  • norm - Optional replacement symbol (str) or None for the default DMS symbols. Use norm="" or norm=pygeodesy.NN to remove all DMS symbols.
Returns:
Normalized DMS (str).

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

 

Parse a lat- or longitude represention forms as [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 range -/+clip (degrees).
  • sexagecimal - If True, convert "D.MMSS" or float(D.MMSS) to base-60 "MM" and "SS" digits. See also forms F_D60, F_D60_ and F_D60__.
Returns:
Degrees (float).
Raises:
  • ParseError - Invalid strDDDMMSS or clip or the form of strDDDMMSS is incompatible with the suffixed or suffix compass point.
  • RangeError - Value of strDDDMMSS outside the valid -/+clip range and pygeodesy.rangerrors set to True.
Notes:
  • Type str values "[D]DD", "[D]DDMM", "[D]DDMMSS" and "[D]DD.MMSS" 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 as form [D]DDMMSS or [D]DD.MMSS. 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'. Also, float(15.0523) is returned as 15.0523 decimal degrees and not 15°5′23″ sexagecimal. To consider the latter, use float(15.0523) or "15.0523" and specify keyword argument sexagecimal=True.

See Also: Functions parseDMS, parseDMS2 and parse3llh.

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

 

Parse a lat- or longitude representation 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 range -/+clip (degrees).
Returns:
Degrees (float).
Raises:

Note: Unlike function parseDDDMMSS, type float, int and other non-str strDMS values are considered decimal (and not sexagecimal) 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 "lat, lon" 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 - Limit latitude to range -/+clipLat (degrees).
  • clipLon - Limit longitude to range -/+clipLon (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 between "lat lon [h]" (str).
  • clipLat - Limit latitude to range -/+clipLat (degrees).
  • clipLon - Limit longitude to range -/+clipLon (degrees).
Returns:
A LatLon3Tuple(lat, lon, height) in degrees, degrees and float.
Raises:
  • RangeError - Lat- or longitude value of strllh outside the valid -/+clipLat or -/+clipLon range and pygeodesy.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 range -/+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_D60, 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 for the form (int).
Raises:
  • ValueError - Invalid form or prec or prec outside the valid range -/+9.

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