netsse.tools.misc_func.find_nearest_gridpoint
=============================================

.. py:function:: netsse.tools.misc_func.find_nearest_gridpoint(lat_wps, lon_wps, lat_grid, lon_grid, interv=0.01)

   Finds the nearest neighbours to a series of waypoints within a grid
   of points.

   .. note::
       The grid points do `not` need to be uniformly spaced in any direction.
       The grid can also have been rotated of any angle about the
       vertical direction (e.g., to be aligned with some shoreline).

   For a given waypoint at ``(lat_wp,lon_wp)``, the nearest-neighbour
   candidates are first selected within the gridpoints that fall in the
   geographical area delimited by ``lat_wp*[1-interv,1+interv]`` in latitude
   and ``lon_wp*[1-interv,1+interv]`` in longitude. Then, the distance between
   the waypoint and the nearest-neighbour candidates is computed. The output
   neighbour is found as the candidate that minimises this distance.

   :param lat_wps: Vector of waypoint latitudes [deg].
   :type lat_wps: float, or 1d-array of shape (Nwp,)
   :param lon_wps: Vector of waypoint longitudes [deg].
   :type lon_wps: float, or 1d-array of shape (Nwp,)
   :param lat_grid: Matrix defining the latitudes of the grid points [deg].
   :type lat_grid: 2d-array
   :param lon_grid: Matrix defining the longitudes of the grid points [deg].
   :type lon_grid: 2d-array
   :param interv: Half-width [-] of the interval band fraction in latitude and longitude,
                  used for screening the potential nearest-neighbour candidates.
   :type interv: float, default 0.01

   :returns: * **index_nearest** (*numpy.array of shape (Nwp,2)*) -- The coordinates in `(latitude,longitude)` of the nearest gridpoints
               to the waypoints [deg].
             * **dist_nearest** (*numpy.array of shape (Nwp,)*) -- The distance between the nearest gridpoints and the waypoints [km].

   .. rubric:: Example

   >>> index_nearest, dist_nearest =
   ...     find_nearest_gridpoint(lat_wps, lon_wps, lat_grid, lon_grid, interv=0.01)