Click or drag to resize

IMcLinesPointClosestToPoint Method

Finds the feature point that is closest to a given point

Namespace:  MediaCy.IQL.Features
Assembly:  MediaCy.IQL.Features (in MediaCy.IQL.Features.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function PointClosestToPoint ( 
	TestX As Single,
	TestY As Single,
	<OutAttribute> ByRef ClosestDistance As Double,
	<OutAttribute> ByRef ClosestX As Single,
	<OutAttribute> ByRef ClosestY As Single,
	<OutAttribute> ByRef ClosestVertexIndex As Integer,
	<OutAttribute> ByRef DirectHit As Boolean,
	<OptionalAttribute> Selector As Object,
	Optional CalibratedDistance As Boolean = true
) As Integer

Parameters

TestX
Type: SystemSingle
Given test X pixel coordinate
TestY
Type: SystemSingle
Given test Y pixel coordinate
ClosestDistance
Type: SystemDouble
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
Type: SystemSingle
Returned closest feature X pixel coordinate. The PointClosestToPoint return value indicates which feature this point resides on.
ClosestY
Type: SystemSingle
Returned closest feature Y pixel coordinate. The PointClosestToPoint return value indicates which feature this point resides on.
ClosestVertexIndex
Type: SystemInt32
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
Type: SystemBoolean
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)
Type: SystemObject
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. If the argument is a McFeatures (i.e., McPoints, McLines or McRegions) or a McBitMask, then features that intersersect the selector's bit mask are selected as if an array of index values were supplied. If the OptionFlags mcofFullCoverageIntersectionTest bit is set, then the test is more stringent and a feature must be fully covered by the selector's bit mask in order to be included in the selection.
CalibratedDistance (Optional)
Type: SystemBoolean
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 ClosestX and ClosestY results are always in pixel coordinates, irrespective of the state of this argument.

Return Value

Type: Int32
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).

Implements

IMcFeaturesPointClosestToPoint(Single, Single, Double, Single, Single, Int32, Boolean, Object, Boolean)
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 a McProfileEdges object.
Examples
VB
Copy
Sub ReportClosestPointToFeature(fX As Single, fY As Single, ftToTest As McFeatures, _
Optional Selector As Variant = Empty, Optional bCalibrated As Boolean = True)
Dim lClosestFeature As Long, fCX As Single, fCY As Single
Dim lVertex As Long, dDistance As Double, bDirectHit As Boolean
lClosestFeature = ftToTest.PointClosestToPoint(fX, fY, dDistance, fCX, fCY, _
lVertex, bDirectHit, Selector, bCalibrated)
Debug.Print "TestX/Y= " & McToText(Array(fX, fY)) & ", Feat= " & lClosestFeature _
& ", ClosestX/Y= " & McToText(Array(fCX, fCY)) _
& ", Dist= " & McToText(dDistance, "%g") _
& ", Vertex= " & lVertex & ", Hit: " & bDirectHit
'Now check out the distance along the feature to the hit point
Dim dAlongLineToClosestPoint As Double
dAlongLineToClosestPoint = _
ftToTest.DistanceToFeaturePoint(fCX, fCY, lClosestFeature, lVertex, bCalibrated)
'Test the round trip using FeaturePointAtDistanceFromStart
Dim bOnLine As Boolean, lDistVertex As Long, AtDistX As Single, AtDistY As Single
bOnLine = ftToTest.FeaturePointAtDistanceFromStart(dAlongLineToClosestPoint, lClosestFeature, _
AtDistX, AtDistY, lDistVertex, bCalibrated)
Dim bRoundTripOK As Boolean
bRoundTripOK = (bOnLine And lDistVertex = lVertex And AtDistX = fCX And AtDistY = fCY)
Debug.Print "Dist to closest pt= " & McToText(dAlongLineToClosestPoint, "%g") _
& ", Roundtrip OK= " & bRoundTripOK
End Sub 'ReportClosestPointToFeature
Sub TestClosestPointToFeatureStuff()
'Create 2 region features
Dim strXY As String
strXY = InputBox("Input test X,Y")
Dim varXY As Variant
McFromText strXY, varXY, , 2
Dim fX As Single, fY As Single
fX = varXY(0)
fY = varXY(1)
'Test McRegions
With ThisApplication.ActiveImage.RegionFeatures
.Reset
.SetBox 0, 10, 10, 30, 30
.SetFeaturePoints 1, Array(60, 10, 30, 50, 90, 50) 'triangle
Debug.Print "McRegions"
ReportClosestPointToFeature fX, fY, ThisApplication.ActiveImage.RegionFeatures
End With 'ActiveImage.RegionFeatures
'Test McLines
With ThisApplication.ActiveImage.LineFeatures
.Reset
.SetFeaturePoints 0, Array(10, 100, 40, 140, 40, 100)
.SetFeaturePoints 1, Array(100, 100, 60, 130, 140, 130, 180, 100)
Debug.Print "McLines"
ReportClosestPointToFeature fX, fY, ThisApplication.ActiveImage.LineFeatures
End With 'ActiveImage.LineFeatures
'Test McPoints
With ThisApplication.ActiveImage.PointFeatures
.Reset
.SetFeaturePoints -1, Array(10, 200, 20, 215, 30, 225, 40, 225, 50, 215, 60, 200)
Debug.Print "McPoints"
ReportClosestPointToFeature fX, fY, ThisApplication.ActiveImage.PointFeatures
End With 'ActiveImage.PointFeatures
End Sub 'TestClosestPointToFeatureStuff
See Also