Coverage for pygeodesy/namedTuples.py : 99%

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 -*-
Tuples returned by C{pygeodesy} functions and class methods are all instances of some C{Named...Tuple} class, all sub-classes of C{_NamedTuple} defined in C{pygeodesy.named}. '''
_convergence_, _datum_, _distance_, _E_, \ _easting_, _end_, _epoch_, _fi_, _j_, _h_, \ _height_, _hemipole_, _lam_, _lat_, _lon_, \ _n_, _northing_, _number_, _outside_, _phi_, \ _point_, _points_, _precision_, _radius_, \ _reframe_, _scale_, _start_, _x_, _y_, _z_, \ _zone_, _1_, _2_ FIx, Height, Int, Lam, Lat, Lon, Meter, \ Meter2, Northing, Number_, Phi, Precision_, \ Radians, Radius, Scalar, Str
# __DUNDER gets mangled in class
'''2-Tuple C{(initial, final)} bearings, both in compass C{degrees360}. '''
'''2-Tuple C{(latlonSW, latlonNE)} with the bounds' lower-left and upper-right corner as C{LatLon} instance. '''
'''4-Tuple C{(latS, lonW, latN, lonE)} with the bounds' lower-left C{(LatS, LowW)} and upper-right C{(latN, lonE)} corner lat- and longitudes. '''
'''Get the enclosures of this around an other L{Bounds4Tuple}.
@arg S_other: Bottom C{latS} (C{scalar}) or an other L{Bounds4Tuple} instance. @arg W_N_E: Left C{lonW}, top C{latN} and right C{lonE}, each a (C{scalar}) for C{scalar B{S_other}}.
@return: A L{Bounds4Tuple} with the I{margin} at each of the 4 sides, positive if this side I{encloses} (is on the I{outside} of) the other, negative if not or zero if abutting. '''
'''Intersect this with an other L{Bounds4Tuple}.
@arg S_other: Bottom C{latS} (C{scalar}) or an other L{Bounds4Tuple} instance. @arg W_N_E: Left C{lonW}, top C{latN} and right C{lonE}, each a (C{scalar}) for C{scalar B{S_other}}.
@return: C{None} if the bounds do not overlap, otherwise the intersection of both as a L{Bounds4Tuple}. ''' Bounds4Tuple(max(s, S), max(w, W), min(n, N), min(e, E))
'''2-Tuple C{(destination, final)}, C{destination} in C{LatLon} and C{final} bearing in compass C{degrees360}. '''
'''3-Tuple C{(lat, lon, final)}, destination C{lat}, C{lon} in C{degrees90} respectively C{degrees180} and C{final} bearing in compass C{degrees360}. '''
'''2-Tuple C{(distance, initial)}, C{distance} in C{meter} and C{initial} bearing in compass C{degrees360}. '''
'''3-Tuple C{(distance, initial, final)}, C{distance} in C{meter} and C{initial} and C{final} bearing, both in compass C{degrees360}. '''
'''4-Tuple C{(distance2, delta_lat, delta_lon, unroll_lon2)} with the distance in C{degrees squared}, the latitudinal C{delta_lat = B{lat2} - B{lat1}}, the wrapped, unrolled and adjusted longitudinal C{delta_lon = B{lon2} - B{lon1}} and C{unroll_lon2}, the unrolled or original B{C{lon2}}.
@note: Use Function L{pygeodesy.degrees2m} to convert C{degrees squared} to C{meter} as M{degrees2m(sqrt(distance2), ...)} or M{degrees2m(hypot(delta_lat, delta_lon), ...)}. '''
'''2-Tuple C{(easting, northing)}, both in C{meter}, conventionally. '''
'''3-Tuple C{(easting, northing, height)}, all in C{meter}, conventionally. '''
'''3-Tuple C{(point, outside1, outside2)} of an intersection C{point} and C{outside1}, the position of the C{point}, C{-1} if before the start, C{+1} if after the end and C{0} if on or between the start and end point of the first line. Similarly, C{outside2} is C{-2}, C{+2} or C{0} to indicate the position of C{point} on the second line or path. If a path was specified with an initial bearing instead of an end point, C{outside1} and/or C{outside2} will be C{0} if the intersection C{point} is on the start point or C{+1} respectively C{+2} if the intersection C{point} is after the start point, in the direction of the bearing. '''
'''2-Tuple C{(lat, lon)} in C{degrees90} and C{degrees180}. '''
'''Extend this L{LatLon2Tuple} to a L{LatLon3Tuple}.
@arg height: The height to add (C{scalar}).
@return: A L{LatLon3Tuple}C{(lat, lon, height)}.
@raise ValueError: Invalid B{C{height}}. '''
'''Extend this L{LatLon2Tuple} to a L{LatLon4Tuple}.
@arg height: The height to add (C{scalar}). @arg datum: The datum to add (C{Datum}).
@return: A L{LatLon4Tuple}C{(lat, lon, height, datum)}.
@raise TypeError: If B{C{datum}} not a C{Datum}.
@raise ValueError: Invalid B{C{height}}. '''
'''3-Tuple C{(lat, lon, height)} in C{degrees90}, C{degrees180} and C{meter}, conventionally. '''
'''Extend this L{LatLon3Tuple} to a L{LatLon4Tuple}.
@arg datum: The datum to add (C{Datum}).
@return: A L{LatLon4Tuple}C{(lat, lon, height, datum)}.
@raise TypeError: If B{C{datum}} not a C{Datum}. '''
'''4-Tuple C{(lat, lon, height, datum)} in C{degrees90}, C{degrees180}, C{meter} and L{Datum}. '''
'''(INTERNAL) Return a L{LatLon4Tuple} or an B{C{LatLon}} instance. ''' else: # datum=getattr(inst, _datum_, None), epoch=getattr(inst, _epoch_, None), reframe=getattr(inst, _reframe_, None)) # PYCHOK indent
'''3-Tuple C{(lat, lon, datum)} in C{degrees90}, C{degrees180} and L{Datum}. '''
'''5-Tuple C{(lat, lon, datum, convergence, scale)} in C{degrees90}, C{degrees180}, L{Datum}, C{degrees} and C{float}. '''
'''3-Tuple C{(lat, lon, precision)} in C{degrees}, C{degrees} and C{int}. '''
'''Extend this L{LatLonPrec3Tuple} to a L{LatLonPrec5Tuple}.
@arg height: The height to add (C{float} or C{None}). @arg radius: The radius to add (C{float} or C{None}).
@return: A L{LatLonPrec5Tuple}C{(lat, lon, precision, height, radius)}. '''
'''5-Tuple C{(lat, lon, precision, height, radius)} in C{degrees}, C{degrees}, C{int} and C{height} or C{radius} in C{meter} (or C{None} if missing). '''
'''2-Tuple C{(closest, fraction)} of the C{closest} point on and C{fraction} along a line (segment) between two points. The C{fraction} is C{0} if the closest point is the first or C{1} the second of the two points. Negative C{fraction}s indicate the closest point is C{before} the first point. For C{fraction > 1.0} the closest point is after the second point. '''
'''3-Tuple C{(closest, distance, angle)} of the C{closest} point on the polygon, either a C{LatLon} instance or a L{LatLon3Tuple}C{(lat, lon, height)} and the C{distance} and C{angle} to the C{closest} point are in C{meter} respectively compass C{degrees360}. '''
'''5-Tuple C{(lat, lon, distance, angle, height)} all in C{degrees}, except C{height}. The C{distance} is the L{pygeodesy.equirectangular} distance between the closest and the reference B{C{point}} in C{degrees}. The C{angle} from the reference B{C{point}} to the closest point is in compass C{degrees360}, see function L{pygeodesy.compassAngle}. The C{height} is the (interpolated) height at the closest point in C{meter} or C{0}. '''
'''6-Tuple C{(closest, distance, fi, j, start, end)} with the C{closest} point, the C{distance} in C{meter}, conventionally and the C{start} and C{end} point of the path or polygon edge. Fractional index C{fi} (an L{FIx} instance) and index C{j} indicate the path or polygon edge and the fraction along that edge with the C{closest} point. The C{start} and C{end} points may differ from the given path or polygon points at indices C{fi} respectively C{j}, when unrolled (C{wrap} is C{True}). Also, the C{start} and/or C{end} point may be the same instance as the C{closest} point, for example when the very first path or polygon point is the nearest. '''
'''8-Tuple C{(closest, distance, fi, j, start, end, initial, final)}, like L{NearestOn6Tuple} but extended with the C{initial} and the C{final} bearing at the reference respectively the C{closest} point, both in compass C{degrees}. '''
'''2-Tuple C{(phi, lam)} with latitude C{phi} in C{radians[PI_2]} and longitude C{lam} in C{radians[PI]}.
@note: Using C{phi/lambda} for lat-/longitude in C{radians} follows Chris Veness' U{convention <https://www.Movable-Type.co.UK/scripts/latlong.html>}. '''
'''Extend this L{PhiLam2Tuple} to a L{PhiLam3Tuple}.
@arg height: The height to add (C{scalar}).
@return: A L{PhiLam3Tuple}C{(phi, lam, height)}.
@raise ValueError: Invalid B{C{height}}. '''
'''Extend this L{PhiLam2Tuple} to a L{PhiLam4Tuple}.
@arg height: The height to add (C{scalar}). @arg datum: The datum to add (C{Datum}).
@return: A L{PhiLam4Tuple}C{(phi, lam, height, datum)}.
@raise TypeError: If B{C{datum}} not a C{Datum}.
@raise ValueError: Invalid B{C{height}}. ''' return self.to3Tuple(height).to4Tuple(datum)
'''3-Tuple C{(phi, lam, height)} with latitude C{phi} in C{radians[PI_2]}, longitude C{lam} in C{radians[PI]} and C{height} in C{meter}.
@note: Using C{phi/lambda} for lat-/longitude in C{radians} follows Chris Veness' U{convention <https://www.Movable-Type.co.UK/scripts/latlong.html>}. '''
'''Extend this L{PhiLam3Tuple} to a L{PhiLam4Tuple}.
@arg datum: The datum to add (C{Datum}).
@return: A L{PhiLam4Tuple}C{(phi, lam, height, datum)}.
@raise TypeError: If B{C{datum}} not a C{Datum}. '''
'''4-Tuple C{(phi, lam, height, datum)} with latitude C{phi} in C{radians[PI_2]}, longitude C{lam} in C{radians[PI]}, C{height} in C{meter} and L{Datum}.
@note: Using C{phi/lambda} for lat-/longitude in C{radians} follows Chris Veness' U{convention <https://www.Movable-Type.co.UK/scripts/latlong.html>}. '''
'''3-Tuple C{(x, y, ll)} in C{meter}, C{meter} and C{LatLon}. '''
'''2-Tuple C{(number, points)} with the C{number} of points and -possible reduced- C{list} or C{tuple} of C{points}. '''
'''7-Tuple C{(A, a, B, b, C, c, area)} with interior angles C{A}, C{B} and C{C} in C{degrees}, spherical sides C{a}, C{b} and C{c} in C{meter} and the C{area} of a spherical triangle in I{square} C{meter}. '''
'''8-Tuple C{(A, a, B, b, C, c, D, E)} with interior angles C{A}, C{B} and C{C}, spherical sides C{a}, C{b} and C{c}, I{spherical deficit} C{D} and I{spherical excess} C{E} of a spherical triangle, all in C{radians}. '''
'''5-Tuple C{(min, minPoint, max, maxPoint, n)} with C{min} and C{max} in C{meter}, the corresponding trilaterated C{minPoint} and C{maxPoint} as C{LatLon} and the number C{n}. For area overlap, C{min} and C{max} are the smallest respectively largest overlap found. For perimeter intersection, C{min} and C{max} represent the closest respectively farthest intersection margin. Count C{n} is the total number of trilaterated overlaps or intersections found, C{0, 1, 2...6} with C{0} meaning concentric.
@see: The C{ellipsoidalKarney-}, C{ellipsoidalVincenty-} and C{sphericalTrigonometry.LatLon.trilaterate5} method for further details on corner cases, like concentric or single trilaterated results. '''
'''2-Tuple C{(zone, hemipole)} as C{int} and C{str}, where C{zone} is C{1..60} for UTM or C{0} for UPS and C{hemipole} C{'N'|'S'} is the UTM hemisphere or the UPS pole. '''
'''5-Tuple C{(zone, hemipole, easting, northing, band)} as C{int}, C{str}, C{meter}, C{meter} and C{band} letter, where C{zone} is C{1..60} for UTM or C{0} for UPS, C{hemipole} C{'N'|'S'} is the UTM hemisphere or the UPS pole and C{band} is C{""} or the I{longitudinal} UTM band C{'C'|'D'|..|'W'|'X'} or I{polar} UPS band C{'A'|'B'|'Y'|'Z'}. '''
'''8-Tuple C{(zone, hemipole, easting, northing, band, datum, convergence, scale)} as C{int}, C{str}, C{meter}, C{meter}, C{band} letter, C{Datum}, C{degrees} and C{scalar}, where C{zone} is C{1..60} for UTM or C{0} for UPS, C{hemipole} C{'N'|'S'} is the UTM hemisphere or the UPS pole and C{band} is C{""} or the I{longitudinal} UTM band C{'C'|'D'|..|'W'|'X'} or I{polar} UPS band C{'A'|'B'|'Y'|'Z'}. ''' _band_, _datum_, _convergence_, _scale_) Band, _Pass, Degrees, Scalar)
'''5-Tuple C{(zone, band, hemipole, lat, lon)} as C{int}, C{str}, C{str}, C{degrees90} and C{degrees180}, where C{zone} is C{1..60} for UTM or C{0} for UPS, C{band} is C{""} or the I{longitudinal} UTM band C{'C'|'D'|..|'W'|'X'} or I{polar} UPS band C{'A'|'B'|'Y'|'Z'} and C{hemipole} C{'N'|'S'} is the UTM hemisphere or the UPS pole. '''
'''2-Tuple C{(x, y)} of (geocentric) components, both in C{meter} or C{units}. '''
'''Extend this L{Vector2Tuple} to a L{Vector3Tuple}.
@arg z: The Z component add (C{scalar}).
@return: A L{Vector3Tuple}C{(x, y, z)}.
@raise ValueError: Invalid B{C{z}}. ''' return self._xtend(Vector3Tuple, z)
'''3-Tuple C{(x, y, z)} of (geocentric) components, all in C{meter} or C{units}. '''
'''Extend this L{Vector3Tuple} to a L{Vector4Tuple}.
@arg h: The height to add (C{scalar}).
@return: A L{Vector4Tuple}C{(x, y, z, h)}.
@raise ValueError: Invalid B{C{h}}. '''
'''4-Tuple C{(x, y, z, h)} of (geocentric) components, all in C{meter} or C{units}. '''
# **) MIT License # # Copyright (C) 2016-2022 -- 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.
# % env PYGEODESY_FOR_DOCS=1 python -m pygeodesy.named # all 71 locals OK |