def nearestOn3(self, points, closed=False, radius=R_M, **options):
'''Locate the point on a polygon closest to this point.
Distances are approximated by function L{equirectangular_},
subject to the supplied B{C{options}}.
@param points: The polygon points (L{LatLon}[]).
@keyword closed: Optionally, close the polygon (C{bool}).
@keyword radius: Mean earth radius (C{meter}).
@keyword options: Optional keyword arguments for function
L{equirectangular_}.
@return: A L{NearestOn3Tuple}C{(closest, distance, angle)}
where C{distance} is the L{equirectangular_} distance
between this and the C{closest} point in C{meter},
same units as B{C{radius}}. The C{angle} from this to
the C{closest} point is in compass C{degrees360},
like function L{compassAngle}.
@raise LimitError: Lat- and/or longitudinal delta exceeds
B{C{limit}}, see function L{equirectangular_}.
@raise TypeError: Some B{C{points}} are not C{LatLon}.
@raise ValueError: Insufficient number of B{C{points}}.
@see: Functions L{compassAngle}, L{equirectangular_} and
L{nearestOn5}.
'''
a, b, d, c, h = _nearestOn5(self, points, closed=closed, **options)
return NearestOn3Tuple(self.classof(a, b, height=h),
degrees2m(d, radius=radius), c)
def nearestOn2(point, points, closed=False, radius=R_M, # PYCHOK no cover
LatLon=LatLon, **options): # PYCHOK no cover
'''DEPRECATED, use function L{sphericalTrigonometry.nearestOn3}.
@return: ... C{closest} as B{C{LatLon}} or a 2-tuple C{(lat, lon)}
without the height if B{C{LatLon}} is C{None} ...
'''
a, b, d, _, h = _nearestOn5(point, points, closed=closed, **options)
ll = (a, b) if LatLon is None else LatLon(a, b, height=h)
return ll, degrees2m(d, radius=radius)
def nearestOn3(point,
points,
closed=False,
radius=R_M,
LatLon=LatLon,
**options):
'''Locate the point on a polygon closest to an other, reference point.
Distances are approximated by function L{equirectangular_},
subject to the supplied B{C{options}}.
@arg point: The other, reference point (L{LatLon}).
@arg points: The polygon points (L{LatLon}[]).
@kwarg closed: Optionally, close the polygon (C{bool}).
@kwarg radius: Mean earth radius (C{meter}).
@kwarg LatLon: Optional class to return the closest point
(L{LatLon}) or C{None}.
@kwarg options: Optional keyword arguments for function
L{equirectangular_}.
@return: A L{NearestOn3Tuple}C{(closest, distance, angle)} with the
C{closest} point as B{L{LatLon}} or L{LatLon3Tuple}C{(lat,
lon, height)} if B{C{LatLon}} is C{None}. The C{distance}
is the L{equirectangular_} distance between the C{closest}
and the given B{C{point}} in C{meter}, same units as
B{C{radius}}. The C{angle} from the given B{C{point}}
to the C{closest} is in compass C{degrees360}, like function
L{compassAngle}. The C{height} is the (interpolated) height
at the C{closest} point.
@raise LimitError: Lat- and/or longitudinal delta exceeds the
B{C{limit}}, see function L{equirectangular_}.
@raise PointsError: Insufficient number of B{C{points}}.
@raise TypeError: Some B{C{points}} are not C{LatLon}.
@raise ValueError: Invalid B{C{radius}}.
@see: Functions L{equirectangular_} and L{nearestOn5}.
'''
lat, lon, d, c, h = _nearestOn5(point,
points,
closed=closed,
LatLon=None,
**options)
r = LatLon3Tuple(lat, lon, h) if LatLon is None else \
LatLon(lat, lon, height=h)
r = NearestOn3Tuple(r, degrees2m(d, radius=radius), c)
return _xnamed(r, nearestOn3.__name__)