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-2024 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.10.18

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) symbol suffixes 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:
  • bearing - Bearing from North (compass degrees360).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes, see function pygeodesy.toDMS.
Returns:
Compass degrees per the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

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:
  • bearing - Bearing from North (compass degrees360).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes, see function pygeodesy.toDMS.
Returns:
Compass degrees and point in the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

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=1 and above, but kept for negative prec.
  • s_D - D symbol for degrees (str).
  • s_M - M symbol for minutes (str) or "" aka pygeodesy.NN.
  • s_S - S symbol for seconds (str) or "" aka pygeodesy.NN.
  • neg - Optional sign for negative ('-').
  • pos - Optional sign for positive ("") aka pygeodesy.NN.
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:
  • deg - Latitude to be formatted (scalar degrees).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes, see function pygeodesy.toDMS.
Returns:
Degrees in the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

latlonDMS (lls, **m_form_prec_sep_s_D_M_S)

 

Convert one or more LatLon instances to strings.

Arguments:
  • lls - Single (LatLon) or an iterable (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 function pygeodesy.toDMS and method LatLon.toStr for more details.
Returns:
A tuple of strs if lls is a list, sequence, tuple, etc. of LatLons 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 the resturned 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 function pygeodesy.toDMS and method LatLon.toStr 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 the resturned 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:
  • deg - Longitude to be formatted (scalar degrees).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes.
Returns:
Degrees in the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

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

 

Normalize all degrees, minutes and seconds (DMS) symbol suffixes 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 symbol). Use norm="" to remove all DMS symbols.
  • s_D_M_S - Optional, alternate DMS symbol suffixes s_D=S_DEG, s_M=S_MIN, s_S=S_SEC and s_R=S_RAD 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 compass points (str), valid in strDDDMMSS.
  • sep - Optional separator between "[D]DD", "MM", "SS", suffix (S_SEP) in strDDDMMSS.
  • 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 or invalid for the given suffix compass point(s).
  • RangeError - Value of strDDDMMSS outside the valid -/+clip range and rangerrors is 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 DMS symbol suffixes for degrees s_D=S_DEG, minutes s_M=S_MIN and seconds s_S=S_SEC, see function pygeodesy.toDMS.
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 DMS symbol suffixes for degrees s_D=S_DEG, minutes s_M=S_MIN and seconds s_S=S_SEC, see function pygeodesy.toDMS.
Returns:
A LatLon2Tuple(lat, lon) in degrees.
Raises:
  • ParseError - Invalid strLat or strLon.
  • RangeError - Value of strLat or strLon outside the valid -/+clipLat or -/+clipLon range and rangerrors is True.

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 DMS symbol suffixes for degrees s_D=S_DEG, minutes s_M=S_MIN and seconds s_S=S_SEC, see function pygeodesy.toDMS.
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 rangerrors is 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 s_DMS=None cancels all DMS symbols to "" aka pygeodesy.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 is extended with a D-only symbol suffix if defined with keyword argument s_D=pygeodesy.NN. Likewise for F_RAD forms with keyword argument s_R=S_RAD.

See Also: Function pygeodesy.degDMS


   Home       Trees       Indices       Help   
PyGeodesy
Generated by Epydoc 3.0.1 on Tue Oct 22 17:06:19 2024 http://epydoc.sourceforge.net