Home       Trees       Indices       Help   
PyGeodesy
Package pygeodesy :: Module dms
[frames] | no frames]

Module dms

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

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.

Set env variable PYGEODESY_FMT_FORM to any F_... form to override default F_DMS formatting of lat- and longitudes or to an empty string to restore the default.

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

Note: In Python 2-, S_DEG, S_MIN, S_SEC, S_RAD and S_SEP may be multi-byte, non-ascii characters and if so, not unicode.

Version: 24.03.21

Functions
 
bearingDMS(bearing, form='d', prec=None, sep='', **s_D_M_S)
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='', **s_D_M_S)
Convert bearing to a string suffixed with compass point.
 
compassPoint(bearing, prec=3)
Convert a bearing from North 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=None, sep='', **s_D_M_S)
Convert latitude to a string, optionally suffixed with N or S.
 
latlonDMS(lls, **m_form_prec_sep_s_D_M_S)
Convert one or more LatLon instances to strings.
 
latlonDMS_(*lls, **m_form_prec_sep_s_D_M_S)
Convert one or more LatLon instances to strings.
 
lonDMS(deg, form='dms', prec=None, sep='', **s_D_M_S)
Convert longitude to a string, optionally suffixed with E or W.
 
normDMS(strDMS, norm=None, **s_D_M_S)
Normalize all degrees, minutes and seconds (DMS) symbols in a string to the default symbols S_DEG, S_MIN, S_SEC.
 
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, **s_D_M_S)
Parse a lat- or longitude representation in degrees.
 
parseDMS2(strLat, strLon, sep='', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)
Parse a lat- and a longitude representions "lat, lon" in degrees.
 
parse3llh(strllh, height=0, sep=',', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)
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='+', **s_D_M_S)
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 pygeodesy.NN
  S_DMS = True
If True include, otherwise cancel all DMS symbols, default True.
  S_SEP = ''
Separator between deg°|min′|sec″|suffix, default "" aka pygeodesy.NN
  F_D = 'd'
Format degrees as unsigned "deg°" with symbol, plus compass point suffix N, S, E or W (str).
  F_D60 = 'd60'
Format degrees as unsigned "[D]DD.MMSS" sexagecimal without symbols, plus suffix (str).
  F_D60_ = '-d60'
Format degrees as signed "-/[D]DD.MMSS" sexagecimal without symbols, without suffix (str).
  F_D60__ = '+d60'
Format degrees as signed "-/+[D]DD.MMSS" sexagecimal 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='', **s_D_M_S)

 

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

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

See Also: Function pygeodesy.toDMS.

clipDegrees (deg, limit)

 

Clip a lat- or longitude to the given range.

Arguments:
  • deg - Unclipped lat- or longitude (scalar 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='', **s_D_M_S)

 

Convert bearing to a string suffixed with compass point.

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

See Also: Function pygeodesy.toDMS.

compassPoint (bearing, prec=3)

 

Convert a bearing from North to a compass point.

Arguments:
  • bearing - Bearing (compass degrees360).
  • prec - Precision, number of compass point characters: 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 bearing or prec.

See Also: Dms.compassPoint and Compass rose.

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 degrees).
  • prec - 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 - D symbol for degrees (str).
  • s_M - M symbol for minutes (str) or "".
  • s_S - S symbol for seconds (str) or "".
  • neg - Optional sign for negative ('-').
  • pos - Optional sign for positive ('').
Returns:
Either degrees, minutes or seconds (str).

See Also: Function pygeodesy.toDMS.

latDMS (deg, form='dms', prec=None, sep='', **s_D_M_S)

 

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

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

See Also: Functions pygeodesy.toDMS and pygeodesy.lonDMS.

latlonDMS (lls, **m_form_prec_sep_s_D_M_S)

 

Convert one or more LatLon instances to strings.

Arguments:
  • lls - Single (LatLon) or list, sequence, tuple, etc. (LatLons).
  • m_form_prec_sep_s_D_M_S - Optional keyword arguments meter, format, precision, s_D, s_M, s_S, s_DMS and DEPRECATED sep=None, see method LatLon.toStr and functions pygeodesy.latDMS and pygeodesy.lonDMS for more details.
Returns:
A tuple of strs if lls is a list, sequence, tuple, etc. of LatLon instances or a single str if lls is a single LatLon.

See Also: Functions pygeodesy.latlonDMS_, pygeodesy.latDMS, pygeodesy.lonDMS and pygeodesy.toDMS and method LatLon.toStr.

Note: Keyword argument sep=None to join a string from the returned tuple has been DEPRECATED, use sep.join(latlonDMS_(...)) instead.

latlonDMS_ (*lls, **m_form_prec_sep_s_D_M_S)

 

Convert one or more LatLon instances to strings.

Arguments:
  • lls - The instances (LatLons), all positional arguments.
  • m_form_prec_sep_s_D_M_S - Optional keyword arguments meter, format, precision, s_D, s_M, s_S, s_DMS and DEPRECATED sep=None, see method LatLon.toStr and functions pygeodesy.latDMS and pygeodesy.lonDMS for more details.
Returns:
A tuple of strs if 2 or more LatLon instances or a single str if only a single LatLon instance is given in lls.

See Also: Functions pygeodesy.latlonDMS, pygeodesy.latDMS and pygeodesy.lonDMS and pygeodesy.toDMS and method LatLon.toStr.

Note: Keyword argument sep=None to join a string from the returned tuple has been DEPRECATED, use sep.join(latlonDMS_(...)) instead.

lonDMS (deg, form='dms', prec=None, sep='', **s_D_M_S)

 

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

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

See Also: Functions pygeodesy.toDMS and pygeodesy.latDMS.

normDMS (strDMS, norm=None, **s_D_M_S)

 

Normalize all degrees, minutes and seconds (DMS) symbols in a string to the default symbols S_DEG, S_MIN, S_SEC.

Arguments:
  • strDMS - Original DMS string (str).
  • norm - Optional replacement symbol (str) or None for the default DMS symbols). Use norm="" to remove all DMS symbols.
  • s_D_M_S - Optional, alternate DMS symbols s_D=str, s_M=str, s_S=str and/or s_R=str for radians, each to be replaced by norm.
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", "SS", suffix (S_SEP).
  • 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 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 signed or unsigned, unsuffixed and with keyword argument suffix="NS", suffix="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 the compass point. 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 the keyword argument sexagecimal=True.

See Also: Functions pygeodesy.parseDMS, pygeodesy.parseDMS2 and pygeodesy.parse3llh.

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

 

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′, sec″, suffix ('').
  • clip - Optionally, limit value to range -/+clip (degrees).
  • s_D_M_S - Optional, alternate symbol for degrees s_D=str, minutes s_M=str and/or seconds s_S=str.
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 pygeodesy.parseDDDMMSS, pygeodesy.parseDMS2, pygeodesy.parse3llh and pygeodesy.toDMS.

parseDMS2 (strLat, strLon, sep='', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)

 

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′, sec″, suffix ('').
  • clipLat - Limit latitude to range -/+clipLat (degrees).
  • clipLon - Limit longitude to range -/+clipLon (degrees).
  • wrap - If True, wrap or normalize the lat- and longitude, overriding clipLat and clipLon (bool).
  • s_D_M_S - Optional, alternate symbol for degrees s_D=str, minutes s_M=str and/or seconds s_S=str.
Returns:
A LatLon2Tuple(lat, lon) in degrees.
Raises:

Note: See the Notes at function parseDMS.

See Also: Functions pygeodesy.parseDDDMMSS, pygeodesy.parseDMS, pygeodesy.parse3llh and pygeodesy.toDMS.

parse3llh (strllh, height=0, sep=',', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)

 

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] suffix" (str).
  • clipLat - Limit latitude to range -/+clipLat (degrees).
  • clipLon - Limit longitude to range -/+clipLon (degrees).
  • wrap - If True, wrap or normalize the lat- and longitude, overriding clipLat and clipLon (bool).
  • s_D_M_S - Optional, alternate symbol for degrees s_D=str, minutes s_M=str and/or seconds s_S=str.
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 pygeodesy.parseDDDMMSS, pygeodesy.parseDMS, pygeodesy.parseDMS2 and pygeodesy.toDMS.

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:
Returns:
Previous precision for the form (int).
Raises:
  • ValueError - Invalid form or prec or prec outside range -9..+9.

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

 

Convert signed degrees to string, without suffix.

Arguments:
Returns:
Degrees in the specified form (str).
Notes:
  • The degrees, minutes and seconds (DMS) symbol can be overridden in this and other *DMS functions by using optional keyword argments s_D="d", s_M="'" respectively s_S='"'. Using keyword argument s_DMS=None cancels all DMS symbols to S_NUL=NN.
  • Sexagecimal format F_D60 supports overridable pseudo-DMS symbols positioned at "[D]DD<s_D>MM<s_M>SS<s_S>" with defaults s_D=".", s_M=sep and s_S=pygeodesy.NN.
  • Formats F__E, F__F and F__G can be extended with a D-only symbol if defined with keyword argument s_D=str. Likewise for F_RAD formats with keyword argument s_R=str.

See Also: Function pygeodesy.degDMS


   Home       Trees       Indices       Help   
PyGeodesy
Generated by Epydoc 3.0.1 on Sun May 5 14:46:24 2024 http://epydoc.sourceforge.net