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

# Module dms

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

Classes
| RangeError Error raised for lat- or longitude values outside the clip, clipLat, clipLon or limit range in function clipDMS, parse3llh, parseDMS or parseDMS2.

Functions
bearingDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) Convert bearing to a string. |
clipDMS(deg, limit) Clip a lat- or longitude to the given range. |
compassAngle(lat0, lon0, lat1, lon1) Return the angle from North for the direction vector (lon1 - lon0, lat1 - lat0) between two points. |
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. |
latDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) Convert latitude to a string suffixed with N or S. |
lonDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) Convert longitude to a string suffixed with E or W. |
normDMS(strDMS, norm=`'````'`) Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″. |
parse3llh(strll, height=0, sep=`'``,``'`, clipLat=90, clipLon=180) Parse a string representing lat-, longitude and height point. |
parseDMS(strDMS, suffix=`'``NSEW``'`, sep=`'````'`, clip=0) Parse a string representing deg°min′sec″ to degrees. |
parseDMS2(strLat, strLon, sep=`'````'`, clipLat=90, clipLon=180) Parse lat- and longitude representions. |
precision(form, prec=None) Set the default precison for a given F_ form. |
rangerrors(raiser=None) Gert/set raising of range errors. |
toDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`, ddd=2, neg=`'``-``'`, pos=`'````'`) Convert signed degrees to string, without suffix. |

Variables
| F_D = ``'``d``'`` Format degrees as deg° (string).
| F_DM = ``'``dm``'`` Format degrees as deg°min′ (string).
| F_DMS = ``'``dms``'`` Format degrees as deg°min′sec″ (string).
| F_DEG = ``'``deg``'`` Format degrees as [D]DD without symbol (string).
| F_MIN = ``'``min``'`` Format degrees as [D]DDMM without symbols (string).
| F_SEC = ``'``sec``'`` Format degrees as [D]DDMMSS without symbols (string).
| F_RAD = ``'``rad``'`` Convert degrees to radians and format as RR.r (string).
| S_DEG = ``'``\xc2\xb0``'`` Degrees ° symbol (string).
| S_MIN = ``'``\xe2\x80\xb2``'`` Minutes ′ symbol (string).
| S_SEC = ``'``\xe2\x80\xb3``'`` Seconds ″ symbol (string).
| S_RAD = ``'````'`` Radians symbol (string).
| S_SEP = ``'````'`` Separator between deg, min and sec (string).

Function Details

### bearingDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) |
Convert bearing to a string. Parameters: `bearing` - Bearing from North (compass degrees). `form` - Optional format, F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (string). `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 values. `sep` - Optional separator (string). Returns: Compass degrees per the specified form (string). JS name: toBrng.

### clipDMS(deg, limit) |
Clip a lat- or longitude to the given range. Parameters: `deg` - Unclipped lat- or longitude (degrees). `limit` - Valid -limit..+limit range (degrees). Returns: Clipped value (degrees). Raises: `RangeError` - If deg beyond limit and rangerrors set to True.

### compassAngle(lat0, lon0, lat1, lon1) |
Return the angle from North for the direction vector (lon1 - lon0, lat1 - lat0) between two points. Suitable only for short, non-near-polar vectors up to a few hundred Km or Miles. Use LatLon methods initialBearingTo or forward azimuth for larger distances. Parameters: `lat0` - From latitude (degrees). `lon0` - From longitude (degrees). `lat1` - To latitude (degrees). `lon1` - To longitude (degrees). Returns: Angle from North (degrees360). Note: Courtesy Martin Schultz. See Also: Local, Flat Earth.

### compassDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) |
Convert bearing to a string suffixed with compass point. Parameters: `bearing` - Bearing from North (compass degrees). `form` - Optional format, F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (string). `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 values. `sep` - Optional separator (string). Returns: Compass degrees and point in the specified form (string).

### compassPoint(bearing, prec=3) |
Convert bearing to a compass point. Parameters: `bearing` - Bearing from North (compass degrees). `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 string). Raises: `ValueError` - Invalid prec. See Also: Compass rose Example:
    >>> p = compassPoint(24)     # 'NNE'
    >>> p = compassPoint(24, 1)  # 'N'
    >>> p = compassPoint(24, 2)  # 'NE'
    >>> p = compassPoint(18, 3)  # 'NNE'
    >>> p = compassPoint(12, 4)  # 'NbE'
    >>> p = compassPoint(30, 4)  # 'NEbN'

### latDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) |
Convert latitude to a string suffixed with N or S. Parameters: `deg` - Latitude to be formatted (degrees). `form` - Optional format, F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, DD, DDMM, DDMMSS or radians (string). `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 values. `sep` - Optional separator (string). Returns: Degrees in the specified form (string). JS name: toLat.

### lonDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) |
Convert longitude to a string suffixed with E or W. Parameters: `deg` - Longitude to be formatted (degrees). `form` - Optional format, F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, DDD, DDDMM, DDDMMSS or radians (string). `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 values. `sep` - Optional separator (string). Returns: Degrees in the specified form (string). JS name: toLon.

### normDMS(strDMS, norm=`'````'`) |
Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″. Parameters: `strDMS` - DMS (string). `norm` - Optional replacement symbol, default symbol otherwise (string). Returns: Normalized DMS (string).

### parse3llh(strll, height=0, sep=`'``,``'`, clipLat=90, clipLon=180) |
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. Parameters: `strll` - Latitude, longitude[, height] (string). `height` - Optional, default for missing height (meter). `sep` - Optional separator (string). `clipLat` - Keep latitude in -clipLat..+clipLat (degrees). `clipLon` - Keep longitude in -clipLon..+clipLon range (degrees). Returns: 3-Tuple (lat, lon, height) as (scalars). Raises: `RangeError` - Lat- or longitude value of strll outside valid range and rangerrrors set to True. `ValueError` - Invalid strll. See Also: Functions parseDMS and 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)

### parseDMS(strDMS, suffix=`'``NSEW``'`, sep=`'````'`, clip=0) |
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. Parameters: `strDMS` - Degrees in any of several forms (string or scalar). `suffix` - Optional, valid compass directions (NSEW). `sep` - Optional separator between deg°, min′ and sec″ (''). `clip` - Optionally, limit value to -clip..+clip (degrees). Returns: Degrees (float). Raises: `RangeError` - Value of strDMS outside the valid range and rangerrrors set to True. `ValueError` - Invalid strDMS. See Also: Function parse3llh to parse a string with lat-, longitude and height values.

### parseDMS2(strLat, strLon, sep=`'````'`, clipLat=90, clipLon=180) |
Parse lat- and longitude representions. Parameters: `strLat` - Latitude in any of several forms (string or scalar). `strLon` - Longitude in any of several forms (string or scalar). `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: 2-Tuple (lat, lon) in (degrees, degrees). Raises: `RangeError` - Value of strLat or strLon outside the valid range and rangerrrors set to True. `ValueError` - Invalid strLat or strLon. See Also: Function parse3llh to parse a string with lat-, longitude and height values and function parseDMS to parse individual lat- or longitudes.

### precision(form, prec=None) |
Set the default precison for a given F_ form. Parameters: `form` - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD (string). `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 values. Returns: Previous precision (int). Raises: `ValueError` - If form or prec or beyond valid range.

### rangerrors(raiser=None) |
Gert/set raising of range errors. Parameters: `raiser` - Choose True to raise or False to ignore RangeError exceptions. Use None to leave the setting unchanged. Returns: Previous setting (bool). Note: Out-of-range lat- and longitude values are always clipped to the nearest range limit.

### toDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`, ddd=2, neg=`'``-``'`, pos=`'````'`) |
Convert signed degrees to string, without suffix. Parameters: `deg` - Degrees to be formatted (scalar). `form` - Optional format, F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (string). `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 values. `sep` - Optional separator (string). `ddd` - Optional number of digits for deg° (2 or 3). `neg` - Optional sign for negative degrees ('-'). `pos` - Optional sign for positive degrees (''). Returns: Degrees in the specified form (string).