Description
Finds the feature point that is closest to a given point
-
Return Type
-
A Long value.
The index of the feature on which the returned closest point lies, or -1 if there are no features (that is, if Count is zero or the Selector argument is a zero-length array).
-
Syntax
-
object.PointClosestToPoint (TestX, TestY, ClosestDistance, ClosestX, ClosestY, ClosestVertexIndex, DirectHit, [Selector], [CalibratedDistance])
The PointClosestToPoint Method syntax has these parts: |
| object | An expression evaluating to an object of type McFeatures. | | TestX | Required. A Single value. Given test X pixel coordinate
| | TestY | Required. A Single value. Given test Y pixel coordinate
| | ClosestDistance | Required. A Double value. Returned distance between the test point and the closest feature point. This will be given in calibrated units if the CalibratedDistance argument is True and the SpatialCalibration property is not Nothing.
| | ClosestX | Required. A Single value. and ClosestY results are always in pixel coordinates, irrespective of the state of this argument.
| | ClosestY | Required. A Single value. Returned closest feature Y pixel coordinate. The PointClosestToPoint return value indicates which feature this point resides on.
| | ClosestVertexIndex | Required. A Long value. Returned index of the vertex at or beyond which the ClosestX/Y point was found. Note that for McRegions or McLines, the returned closest point may fall on the line segment joining two vertices; for a McRegions if this index is that of the last vertex, then the closest point is either it or on the closing segment (back to the zero'th vertex). Use the GetFeaturePoints method to retrieve the points associated with all vertices for a feature.
| | DirectHit | Required. A Boolean value. Returned as True for McRegions if TestX/Y is interior to or on the boundary. For McLines, returned as True if TestX/Y falls exactly on a feature line segment or vertex. For McPoints returned as True if TestX/Y is is exactly equal to one of the selected point features.
| | Selector | Optional. A Variant value. An optional selector, giving the feature(s) to include in the test.
If the Selector argument is a non-negative scalar value, then only the indicated feature is included in the closest point test. In this case, the returned ClosestX/Y point will be on this feature.
If the Selector argument is missing or any negative scalar value, then all features are included in the closest point test. The returned index value will indicate which feature was found closest to the given test point.
If Selector is an array, then zero or positive values are treated as indices into the features collection, negative values are legal but ignored. In this case, only the indicated features are included in the closest point test, and the returned index will be one of these.
| | CalibratedDistance | Optional. A Boolean value. If True (the default) and the SpatialCalibration property is not Nothing, then the closest point and the ClosestDistance is based on calibrated coordinates. Note that the closest point results will depend on the calibration only for calibrations with a McSpatialCalib.AspectRatio of other than 1. If False, then the computed distance is given in pixel units. The TestX and TextY arguments and the
|
Remarks
For selected features, the feature and feature point closest to a given test point are returned. From among the selected features (all of them by default), the feature with the closest point is identified. The point index (line or boundary segment) where the closest point is found is also returned along with the distance from the test point to the closest point. In addition, a direct hit to a feature is noted (a direct hit to a region is one that is on or interior to its boundary).
The major use for the PointClosestToPoint method is for figuring out where user placed mouse clicks approximately “touch” a feature. This method does everything needed for this job. Note that the simpler FeatureFromPoint method can be used if you are only interested in finding which feature is directly under a test point.
The PointClosestToPoint method identifies which feature is closest to the test point and also computes the point on that feature closest to the given test point and the distance between these points. An optional Selector argument allows the closest feature search to be restricted to one or a sub-set of all of the features, so this method may also be used to find the closest point on a given feature.
For McRegions the closest point is always on the boundary of the feature, though it is not necessarily on a vertex of the boundary polygon. The returned DirectHit argument is True if the test point is on or interior to the boundary. If the point is on the boundary, then the test point and the returned closest point will be the same, so the returned ClosestDistance will be zero.
For McLines, the closest point will be on a feature line segment or vertex. For McPoints, the closest point will be one of the feature points, that is it will be exactly equal to the feature point always. In these cases, the returned DirectHit argument will be True only if the returned ClosestDistance is zero.
The DistanceToFeaturePoint method can use the results from this method to determine the optionally calibrated distance from the start of the feature line or boundary to the detected closest point. This may be useful when adding or removing edges for an McProfileEdges object.
|
PointClosestToPoint Method (McFeatures)
