Coverage for pygeodesy/dms.py : 92%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -*-
in various forms of degrees, minutes and seconds.
After I{(C) Chris Veness 2011-2015} published under the same MIT Licence**, see U{Latitude/Longitude<https://www.Movable-Type.co.UK/scripts/latlong.html>} and U{Vector-based geodesy<https://www.Movable-Type.co.UK/scripts/latlong-vectors.html>}.
@newfield example: Example, Examples '''
# all public contants, classes and functions
F_DEG: 6, F_MIN: 4, F_SEC: 2, F_RAD: 5}
"'": S_MIN, '’': S_MIN, '′': S_MIN, '"': S_SEC, '″': S_SEC, '”': S_SEC}
'''Error raised for lat- or longitude values outside the B{C{clip}}, B{C{clipLat}}, B{C{clipLon}} or B{C{limit}} range in function L{clipDMS}, L{parse3llh}, L{parseDMS} or L{parseDMS2}.
@see: Function L{rangerrors}. '''
'''(INTERNAL) Convert degrees to C{str}, with/-out sign and/or suffix. ''' except ValueError: raise ValueError('%s invalid: %r' % ('deg', deg))
else:
else:
else:
else: # F_DMS, F_SEC, 'deg+min+sec' int(m),s_min, sep, w+2,p,s)
'''Convert bearing to a string.
@param bearing: Bearing from North (compass C{degrees360}). @keyword form: Optional B{C{bearing}} format (C{str} or L{F_D}, L{F_DM}, L{F_DMS}, L{F_DEG}, L{F_MIN}, L{F_SEC}, L{F_RAD}, L{F_D_}, L{F_DM_}, L{F_DMS_}, L{F_DEG_}, L{F_MIN_}, L{F_SEC_}, L{F_RAD_}, L{F_D__}, L{F_DM__}, L{F_DMS__}, L{F_DEG__}, L{F_MIN__}, L{F_SEC__} or L{F_RAD__}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}. @keyword sep: Optional separator (C{str}).
@return: Compass degrees per the specified B{C{form}} (C{str}).
@JSname: I{toBrng}. '''
'''Clip a lat- or longitude to the given range.
@param deg: Unclipped lat- or longitude (C{degrees}). @param limit: Valid B{C{-limit..+limit}} range (C{degrees}).
@return: Clipped value (C{degrees}).
@raise RangeError: If B{C{abs(deg)}} beyond B{C{limit}} and L{rangerrors} set to C{True}. ''' raise RangeError('%s beyond %s degrees' % (fStr(deg, prec=6), fStr(copysign(limit, deg), prec=3, ints=True)))
'''Convert bearing to a string suffixed with compass point.
@param bearing: Bearing from North (compass C{degrees360}). @keyword form: Optional B{C{bearing}} format (C{str} or L{F_D}, L{F_DM}, L{F_DMS}, L{F_DEG}, L{F_MIN}, L{F_SEC}, L{F_RAD}, L{F_D_}, L{F_DM_}, L{F_DMS_}, L{F_DEG_}, L{F_MIN_}, L{F_SEC_}, L{F_RAD_}, L{F_D__}, L{F_DM__}, L{F_DMS__}, L{F_DEG__}, L{F_MIN__}, L{F_SEC__} or L{F_RAD__}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}. @keyword sep: Optional separator (C{str}).
@return: Compass degrees and point in the specified form (C{str}). '''
'''Convert bearing to a compass point.
@param bearing: Bearing from North (compass C{degrees360}). @keyword 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).
@return: Compass point (1-, 2-, 3- or 4-letter C{str}).
@raise ValueError: Invalid B{C{prec}}.
@see: U{Dms.compassPoint <https://GitHub.com/chrisveness/geodesy/blob/master/dms.js>} and U{Compass rose<https://WikiPedia.org/wiki/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' ''' except KeyError: raise ValueError('%s invalid: %r' % ('prec', prec)) # not round(), i.e. half-even rounding in Python 3, # but round-away-from-zero as int(b + 0.5) iff b is # non-negative, otherwise int(b + copysign(0.5, b))
'E', 'EbS', 'ESE', 'SEbE', 'SE', 'SEbS', 'SSE', 'SbE', 'S', 'SbW', 'SSW', 'SWbS', 'SW', 'SWbW', 'WSW', 'WbS', 'W', 'WbN', 'WNW', 'NWbW', 'NW', 'NWbN', 'NNW', 'NbW') #: (INTERNAL) cardinals
'''Convert degrees to a string in degrees, minutes I{or} seconds.
@param deg: Value in degrees (C{scalar}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}. @keyword s_D: Symbol for degrees (C{str}). @keyword s_M: Symbol for minutes (C{str}) or C{""}. @keyword s_S: Symbol for seconds (C{str}) or C{""}. @keyword neg: Optional sign for negative ('-'). @keyword pos: Optional sign for positive ('').
@return: I{Either} degrees, minutes I{or} seconds (C{str}). ''' else: elif s_S: d *= 3600 s = s_S
'''Convert latitude to a string, optionally suffixed with N or S.
@param deg: Latitude to be formatted (C{degrees}). @keyword form: Optional B{C{deg}} format (C{str} or L{F_D}, L{F_DM}, L{F_DMS}, L{F_DEG}, L{F_MIN}, L{F_SEC}, L{F_RAD}, L{F_D_}, L{F_DM_}, L{F_DMS_}, L{F_DEG_}, L{F_MIN_}, L{F_SEC_}, L{F_RAD_}, L{F_D__}, L{F_DM__}, L{F_DMS__}, L{F_DEG__}, L{F_MIN__}, L{F_SEC__} or L{F_RAD__}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}. @keyword sep: Optional separator (C{str}).
@return: Degrees in the specified form (C{str}).
@JSname: I{toLat}. '''
'''Convert longitude to a string, optionally suffixed with E or W.
@param deg: Longitude to be formatted (C{degrees}). @keyword form: Optional B{C{deg}} format (C{str} or L{F_D}, L{F_DM}, L{F_DMS}, L{F_DEG}, L{F_MIN}, L{F_SEC}, L{F_RAD}, L{F_D_}, L{F_DM_}, L{F_DMS_}, L{F_DEG_}, L{F_MIN_}, L{F_SEC_}, L{F_RAD_}, L{F_D__}, L{F_DM__}, L{F_DMS__}, L{F_DEG__}, L{F_MIN__}, L{F_SEC__} or L{F_RAD__}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}. @keyword sep: Optional separator (C{str}).
@return: Degrees in the specified form (C{str}).
@JSname: I{toLon}. '''
'''Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols %s, %s and %s.
@param strDMS: DMS (C{str}). @keyword norm: Optional replacement symbol, default symbol otherwise (C{str}).
@return: Normalized DMS (C{str}). ''' else:
if __debug__: # no __doc__ at -O and -OO
'''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.
@param strll: Latitude, longitude[, height] (C{str}, ...). @keyword height: Optional, default height (C{meter}). @keyword sep: Optional separator (C{str}). @keyword clipLat: Keep latitude in B{C{-clipLat..+clipLat}} (C{degrees}). @keyword clipLon: Keep longitude in B{C{-clipLon..+clipLon}} range (C{degrees}).
@return: A L{LatLon3Tuple}C{(lat, lon, height)} in C{degrees}, C{degrees} and C{float}.
@raise RangeError: Lat- or longitude value of B{C{strll}} outside valid range and L{rangerrors} set to C{True}.
@raise ValueError: Invalid B{C{strll}}.
@see: Functions L{parseDMS} and L{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) ''' else: raise ValueError except (AttributeError, TypeError, ValueError): return ValueError('parsing %r failed' % (strll,))
'''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.
@param strDMS: Degrees in any of several forms (C{str} or C{degrees}). @keyword suffix: Optional, valid compass directions (NSEW). @keyword sep: Optional separator between deg°, min′ and sec″ (''). @keyword clip: Optionally, limit value to -clip..+clip (C{degrees}).
@return: Degrees (C{float}).
@raise RangeError: Value of B{C{strDMS}} outside the valid range and L{rangerrors} set to C{True}.
@raise ValueError: Invalid B{C{strDMS}}.
@see: Function L{parse3llh} to parse a string with lat-, longitude and height values. '''
t = t.replace(sep, ' ') for s in _S_ALL: t = t.replace(s, '') else:
except (AttributeError, IndexError, TypeError, ValueError): raise ValueError('parsing %r failed' % (strDMS,))
'''Parse lat- and longitude representions.
@param strLat: Latitude in any of several forms (C{str} or C{degrees}). @param strLon: Longitude in any of several forms (C{str} or C{degrees}). @keyword sep: Optional separator between deg°, min′ and sec″ (''). @keyword clipLat: Keep latitude in B{C{-clipLat..+clipLat}} range (C{degrees}). @keyword clipLon: Keep longitude in B{C{-clipLon..+clipLon}} range (C{degrees}).
@return: A L{LatLon2Tuple}C{(lat, lon)} in C{degrees}.
@raise RangeError: Value of B{C{strLat}} or B{C{strLon}} outside the valid range and L{rangerrors} set to C{True}.
@raise ValueError: Invalid B{C{strLat}} or B{C{strLon}}.
@see: Function L{parse3llh} to parse a string with lat-, longitude and height values and function L{parseDMS} to parse individual lat- or longitudes. ''' parseDMS(strLon, suffix='EW', sep=sep, clip=clipLon))
'''(INTERNAL) Parse a string representing a UTM or UPS coordinate consisting of C{"zone[band] hemisphere/pole easting northing"}.
@param strUTMUPS: A UTM or UPS coordinate (C{str}). @keyword band: Optional, default Band letter (C{str}).
@return: 5-Tuple (C{zone, hemisphere/pole, easting, northing, band}).
@raise Value: Invalid B{C{strUTMUPS}}. ''' raise ValueError
raise ValueError
else: for i in range(len(z)): if not z[i].isdigit(): # int('') raises ValueError z, B = int(z[:i]), z[i:] break else: raise ValueError
except (AttributeError, TypeError, ValueError): raise ValueError('%s invalid: %r' % ('strUTMUPS', strUTMUPS))
'''Set the default precison for a given F_ form.
@param form: L{F_D}, L{F_DM}, L{F_DMS}, L{F_DEG}, L{F_MIN}, L{F_SEC} or L{F_RAD} (C{str}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}.
@return: Previous precision (C{int}).
@raise ValueError: Invalid B{C{form}} or B{C{prec}} or beyond valid range. ''' except KeyError: raise ValueError('%s invalid: %s' % ('form', form)) raise ValueError('%s invalid: %s' % ('prec', prec))
'''Gert/set raising of range errors.
@keyword raiser: Choose C{True} to raise or C{False} to ignore L{RangeError} exceptions. Use C{None} to leave the setting unchanged.
@return: Previous setting (C{bool}).
@note: Out-of-range lat- and longitude values are always clipped to the nearest range limit. ''' global _rangerrors
'''Convert signed degrees to string, without suffix.
@param deg: Degrees to be formatted (C{degrees}). @keyword form: Optional B{C{deg}} format (C{str} or L{F_D}, L{F_DM}, L{F_DMS}, L{F_DEG}, L{F_MIN}, L{F_SEC}, L{F_RAD} without suffix, L{F_D_}, L{F_DM_}, L{F_DMS_}, L{F_DEG_}, L{F_MIN_}, L{F_SEC_}, L{F_RAD_}, L{F_D__}, L{F_DM__}, L{F_DMS__}, L{F_DEG__}, L{F_MIN__}, L{F_SEC__} or L{F_RAD__}). @keyword prec: Optional number of decimal digits (0..9 or C{None} for default). Trailing zero decimals are stripped for B{C{prec}} values of 1 and above, but kept for negative B{C{prec}}. @keyword sep: Optional separator (C{str}). @keyword ddd: Optional number of digits for deg° (2 or 3). @keyword neg: Optional sign for negative degrees ('-'). @keyword pos: Optional sign for positive degrees ('').
@return: Degrees in the specified form (C{str}). '''
# **) MIT License # # Copyright (C) 2016-2020 -- mrJean1 at Gmail -- All Rights Reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR # OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. |