Finds the closest point to a given point.
Syntax
intl pipRadFindFirstNearest ( pipRadial rad_h, intl lonCenter, intl
latCenter, intl maxHits, intl *lon, intl *lat, pstr name, intl nameSize );
Arguments
rad_h The handle returned by pipRadInit for the current radial analysis. Input.
lonCenter The x coordinate or longitude of the base point to search from.
Input.
latCenter The y coordinate or latitude of the base point to search from. Input. maxHits The total number of points to return using
pipRadFindFirstNearest and pipRadFindNext. Input.
*lon A pointer to the x coordinate or longitude of the located point.
Output.
*lat A pointer to the y coordinate or latitude of the located point.
Output.
name A pointer to a buffer to be filled with the name of the located point.
Output.
nameSize The size, in bytes, of the name buffer. Input.
Return Value
PIP_OK PIP_NOT_FOUND PIP_ERROR
Prerequisites
pipRadInsertPoint or pipRadLoadPoints.
Alternates
None.
Notes
This function returns the closest point from the base point described by lonCenter, latCenter.
The maxHits parameter indicates the total number of points to search for. If this is set to 3, then pipRadFindFirstNearest and pipRadFindNext will not find more than 3 points, regardless of how many points are in the search tree. It is important to set this number carefully; setting too high a number may drastically increase the search time.
To get distance and bearing to the returned point, use pipDistance. If no point is found, the function returns PIP_NOT_FOUND.
Example
// load points into a search tree and find 3 nearest
pipRadial rad_h;
char Name[MAX_NAME];
intl lat, lon, dist, xBase, yBase, x, y; intl radStat;
pipRadInit( h, &rad_h );
// GetPoint is a function that gets the next point
// from your site file...
Have_More_Points = GetPoint( &lon, &lat, Name ); while ( Have_More_Points == TRUE )
{
pipRadInsertPoint( rad_h, lon, lat, Name );
Have_More_Points = GetPoint( &lon, &lat, Name );
}
// now search for three nearest points
radStat = pipRadFindFirstNearest( rad_h, xBase, yBase, 3, y, Name, sizeof(Name) );
while ( radStat == PIP_OK )
{
// do something with the found point...,
//then find the next
radStat = pipRadFindNext( rad_h, x, y, Name, sizeof(Name));
}