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: Optional, 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,
LatLon=LatLon, **options):
'''DEPRECATED, use function L{sphericalTrigonometry.nearestOn3}.
@return: ... I{closest} as I{LatLon} or a 2-tuple (lat, lon)
without the height if I{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}}.
@param point: The other, reference point (L{LatLon}).
@param points: The polygon points (L{LatLon}[]).
@keyword closed: Optionally, close the polygon (C{bool}).
@keyword radius: Optional, mean earth radius (C{meter}).
@keyword LatLon: Optional (sub-)class to return the closest
point (L{LatLon}) or C{None}.
@keyword options: Optional keyword arguments for function
L{equirectangular_}.
@return: A L{NearestOn3Tuple}C{(closest, distance, angle)}. The
C{distance} is the L{equirectangular_} distance between
the C{closest} and reference B{C{point}} in C{meter}, same
units as B{C{radius}}. The C{angle} from the reference
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 TypeError: Some I{points} are not C{LatLon}.
@raise ValueError: Insufficient number of B{C{points}}.
@see: Functions L{equirectangular_} and L{nearestOn5}.
'''
a, b, d, c, h = _nearestOn5(point,
points,
closed=closed,
LatLon=None,
**options)
r = LatLon3Tuple(a, b, h) if LatLon is None else \
LatLon(a, b, height=h)
r = NearestOn3Tuple(r, degrees2m(d, radius=radius), c)
return _xnamed(r, nearestOn3.__name__)
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 I{options}.
@param point: The other, reference point (L{LatLon}).
@param points: The polygon points (L{LatLon}[]).
@keyword closed: Optionally, close the polygon (C{bool}).
@keyword radius: Optional, mean earth radius (C{meter}).
@keyword LatLon: Optional (sub-)class to return the closest
point (L{LatLon}) or C{None}.
@keyword options: Optional keyword arguments for function
L{equirectangular_}.
@return: 3-Tuple (I{closest}, I{distance}, I{angle}) of the
closest point (L{LatLon}) on the polygon, the distance
and the compass angle to the I{closest} point. The
I{closest} is an instance of I{LatLon} or a 3-tuple
(lat, lon, I{height}) if I{LatLon} is C{None}. The
I{distance} is the L{equirectangular_} distance between
the I{closest} and reference I{point} in C{meter}, same
units as I{radius}. The I{angle} from the reference
I{point} to the I{closest} is in compass C{degrees360},
like function L{compassAngle}. The I{height} is the
(interpolated) height at the I{closest} point.
@raise LimitError: Lat- and/or longitudinal delta exceeds
I{limit}, see function L{equirectangular_}.
@raise TypeError: Some I{points} are not C{LatLon}.
@raise ValueError: Insufficient number of I{points}.
@see: Functions L{equirectangular_} and L{nearestOn5}.
'''
a, b, d, c, h = _nearestOn5(point, points, closed=closed, **options)
llh = (a, b, h) if LatLon is None else LatLon(a, b, height=h)
return llh, degrees2m(d, radius=radius), c