Finds the closest point to a target point.
Syntax
intl pipObjectFindFirstNearest ( pipObjectFile obj_h, intl lonCenter, intl
latCenter, intl maxHits, pstr name, intl nameSize );
Arguments
obj_h The handle of the opened object file. Input.
lonCenter The longitude (in millionths of degrees) or x coordinate defining the input point. Input.
latCenter The latitude (in millionths of degrees) or y coordinate defining the input point. Input.
maxHits The maximum number of points to find. The maximum number of values you can request is 65,536. Input.
name A pointer to a buffer to be filled with the identifier of the object in which the point is located. Output.
nameSize The size of the buffer that contains the identifier of the object in which the point is located. If the buffer size is smaller than the identifier, the identifier is truncated. Input.
Return Value
PIP_ERROR PIP_NOT_FOUND PIP_OK
Prerequisites
pipObjectFileOpen.
Alternates
pipRadFindFirstNearest.
Notes
pipObjectFindFirstNearest finds the closest point to a target point. This function does the same thing as pipRadFindFirstNearest, except that it does not require that all of the points be loaded into memory. It is somewhat slower than pipRadFindFirstNearest, so use it in situations where you want to minimize the startup time and do not require the fastest possible speed.
The maxHits parameter indicates the total number of points to search for. If this is set to 3, then pipObjectFindFirstNearest and pipObjectFindNext 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 points are found, the function returns PIP_NOT_FOUND.