IMcRegions2GetFeaturePointsEx Method

Get a list of coordinate points that describe some aspect of a feature.

Namespace: MediaCy.IQL.Features
Assembly: MediaCy.IQL.Features (in MediaCy.IQL.Features.dll) Version: 10.0.6912.0

Syntax

Copy

Function GetFeaturePointsEx ( 
	Optional FeatureIndex As Integer = 0,
	<OptionalAttribute> <OutAttribute> ByRef PointsResults As Object,
	Optional ResultType As mcOutlineType = mcOutlineType.mcotNoGaps,
	<OptionalAttribute> OperationValue As Object,
	Optional Flags As mcGetFeaturePointsExFlags = mcGetFeaturePointsExFlags.gfpxDefault
) As Integer

Parameters

FeatureIndex (Optional): Type: SystemInt32
The index of the feature. Otherwise this must be a feature index value between 0 and Count minus 1. This argument is ignored for McPoints, where the coordinates of all points are always transformed.
PointsResults (Optional): Type: SystemObject
If missing, then only the count is returned. If an Empty Variant, then it is filled with an array of SINGLEPOINT records containing X,Y pairs of points. Otherwise PointsResults must be a variant containing a safearray or records of the proper type and size. Allowed types are Single, SINGLEPOINT, Long, LONGPOINT, Double or DOUBLEPOINT. A non-emtpy variant of the right size and type will be filled with x,y pixel coordinate values (one XXXPOINT record per point or two Long/Single/Double values per point)
ResultType (Optional): Type: MediaCy.IQL.FeaturesmcOutlineType
The type of points wanted. The ResultType mcotNoGaps and the Flag gfpxAdjacentPixels are illegal for for McPoints. The mcotConvex operation (the convex hull) are forces on the gfpxClosedBoundary flag, so that McPoints or McLines are treated as describing a closed boundary.
OperationValue (Optional): Type: SystemObject
A parameter dependent on the type argument (see above)
Flags (Optional): Type: MediaCy.IQL.FeaturesmcGetFeaturePointsExFlags
Flag bits that control aspects of how the coordinates are computed.

Return Value

Type: Int32
The number of points needed in PointsResults or the number of points filled into that variant. If PointsResults contains a safearray of Long/Single/Double, then the returned value will be equal to half the size of that safearray since there are two values per point.

Implements

IMcRegionsGetFeaturePointsEx(Int32, Object, mcOutlineType, Object, mcGetFeaturePointsExFlags)

Remarks

This method is similar to GetFeaturePoints but offers added functionality as to the type of coordinate information returned. The feature, and its basic descriptive coordinates (as returned by GetFeaturePoints) are not affected by this call. Coordinates are returned into an array of values, SINGLEPOINT or RECT structs supplied by the caller (see Example). The type of the returned result depends on the type of array that the caller supplies. If the caller does not supply a PointsResults results variant (or it is VT_ERROR), then just the number of points required to hold the returned array will be returned. If the caller supplies an Empty PointsResults result variant, then that variant is filled with an array of SINGLEPOINT X,Y results. For McPoints all feature points are treated as as an ordered array. This cannot be done for McLines or McRegions, where the coordinates of only one feature at a time may be retrieved. If only a basic description of feature coordinates is desired, use GetFeaturePoints. As illustrated in the example, unless passing the ResultsPointer as an Empty Variant, you should make sure that a first call with the PointsResults argument missing (to determine the number of points that will be returned) has the same arguments as the call that actually gets the points. This is both for safety (to make sure that the receiving array is large enough) and also for efficiency (the results are cached between the two calls as long as the arguments are the same).

Examples

Copy

'This is GetFeaturePointsExSamples.bas
Option Explicit

'**** Utility Sub's and Function's ****

    'Run this to clear all standard McFeatures
Sub ResetTheStandardMcFeatures()
    If ActiveImage Is Nothing Then Exit Sub
    With ActiveImage
        .PointFeatures.Reset 'clear any existing standard features
        .LineFeatures.Reset
        .RegionFeatures.Reset
    End With 'ActiveImage
End Sub 'ResetTheStandardMcFeatures

Sub LetUserCreateSomeFeature(theMcFeatures As McFeatures, graphObjType As String)
    If theMcFeatures Is Nothing Then Exit Sub
    ResetTheStandardMcFeatures 'clear any existing standard features
    theMcFeatures.AutoDisplay = True
    theMcFeatures.AutoDisplayOverlay.SelectTool , graphObjType, mcgtStandardAutoDisplay
End Sub 'LetUserCreateRegionFeature

    'Run this to let the user create a polygon RegionFeatures feature
Sub LetUserCreateRegionFeature()
    If ActiveImage Is Nothing Then Exit Sub
    LetUserCreateSomeFeature ActiveImage.RegionFeatures, "McGraphObjPoly"
End Sub 'LetUserCreateRegionFeature

Function CheckForNoRegionFeature() As Boolean
    CheckForNoRegionFeature = True 'assume no feature
    If ActiveImage Is Nothing Then Exit Function
    If ActiveImage.RegionFeatures.Count = 0 Then
        MsgBox "You need to create a closed region."
        LetUserCreateRegionFeature
        Exit Function
    End If 'no features
    'ELSE we have at least one feature
    CheckForNoRegionFeature = False 'we have a feature
End Function 'CheckForNoRegionFeature

    'Run this to let the user create an open polyline LineFeatures feature
Sub LetUserCreatePolyLineFeature()
    If ActiveImage Is Nothing Then Exit Sub
    LetUserCreateSomeFeature ActiveImage.LineFeatures, "McGraphObjPoly"
End Sub 'LetUserCreatePolyLineFeature

Function CheckForNoLineFeature() As Boolean
    CheckForNoLineFeature = True 'assume no feature
    If ActiveImage Is Nothing Then Exit Function
    If ActiveImage.LineFeatures.Count = 0 Then
        MsgBox "You need to create a polyline."
        LetUserCreatePolyLineFeature
        Exit Function
    End If 'no features
    'ELSE we have at least one feature
    CheckForNoLineFeature = False 'we have a feature
End Function 'CheckForNoLineFeature

    'Run this to let the user create a set of PointFeatures feature
Sub LetUserCreatePointFeatures()
    If ActiveImage Is Nothing Then Exit Sub
    LetUserCreateSomeFeature ActiveImage.PointFeatures, "McGraphObjPoint"
End Sub 'LetUserCreatePointFeatures

Function CheckForNoPoints(Optional nNeeded As Long = 2) As Boolean
    CheckForNoPoints = True 'assume no feature
    If ActiveImage Is Nothing Then Exit Function
    If ActiveImage.PointFeatures.Count < nNeeded Then
        MsgBox "You need to create a at least " & nNeeded & " points."
        LetUserCreatePointFeatures
        Exit Function
    End If 'no features
    'ELSE we have at least 3 points
    CheckForNoPoints = False 'we have a feature
End Function 'CheckForNoPoints

    'The following routine executes GetFeaturePointsEx on the zero'th feature (or all
    'features for a McPoints) and displays the results overlying the orignal display.
Sub DoGetFeaturePointsEx(theMcFeatures As McFeatures, ResultType As mcOutlineType, _
        Optional OpValue As Variant, Optional Flags As mcGetFeaturePointsExFlags = gfpxDefault)
    Dim lNpts As Long, ptsResult As Variant
    ptsResult = Empty
    lNpts = theMcFeatures.GetFeaturePointsEx(0, ptsResult, ResultType, OpValue, Flags)
        'We display the result as a McPoints, McRegions or as a McLines, depending on the source and Flags
    Dim bResultIsClosed As Boolean, mcfeaturesResults As McFeatures
    bResultIsClosed = ((theMcFeatures.Type(-1) And mcftEmptyRegions) <> 0) Or _
        ((Flags And gfpxClosedBoundary) <> 0) Or (ResultType = mcotConvex)
        'For the interpolation tests show results as points
    Dim lResultFeature As Long
    lResultFeature = 0 'for McLines or McRegions
    If ResultType = mcotSetNumbers Or ResultType = mcotSetSpacing Then
        Set mcfeaturesResults = CreateOperator("McPoints", theMcFeatures)
        lResultFeature = -1 'result is all features of this McPoints
        'Else we create either a McRegions or McLines as a child of theMcFeatures
    ElseIf bResultIsClosed Then 'result points are a closed polygon?
        Set mcfeaturesResults = CreateOperator("McRegions", theMcFeatures)
    Else 'result points are an open polyline
        Set mcfeaturesResults = CreateOperator("McLines", theMcFeatures)
    End If 'fi result points an open polyline
    mcfeaturesResults.AutoDisplay = True
    mcfeaturesResults.SetFeaturePoints lResultFeature, ptsResult
    mcfeaturesResults.DisplayedObjects.SetColors &HFFFF&    'make the overlay yellow
    If lResultFeature = -1 Then
        MsgBox "The interpolated points show in yellow." & vbCrLf & "They will disappear when you press OK."
    Else
        MsgBox "The transformed line shows in yellow." & vbCrLf & "It will disappear when you press OK."
    End If
End Sub 'DoGetFeaturePointsEx

'***** Here are the test Sub's ******

'Convex hull
Sub DoConvexHull()
    If CheckForNoRegionFeature Then Exit Sub
    DoGetFeaturePointsEx ActiveImage.RegionFeatures, mcotConvex, 0, gfpxConstantArea
End Sub 'DoConvexHull

Sub DoConvexHullOnPoints()
    If CheckForNoPoints(3) Then Exit Sub
    DoGetFeaturePointsEx ActiveImage.PointFeatures, mcotConvex, 0, gfpxConstantArea
End Sub 'DoConvexHullOnPoints

'Filtering
Sub DoSmoothBoundary()
    If CheckForNoRegionFeature Then Exit Sub
        'smooth over 10 pixels
    DoGetFeaturePointsEx ActiveImage.RegionFeatures, mcotFilter, 10, gfpxConstantArea
End Sub 'DoSmoothBoundary

Sub DoSmoothPolyline()
    If CheckForNoLineFeature Then Exit Sub
        'smooth the polyline over 12 pixels
    DoGetFeaturePointsEx ActiveImage.LineFeatures, mcotFilter, 12
End Sub 'DoSmoothPolyline

'Interpolation
Sub DoSetNumbersOfVertices()
    If CheckForNoRegionFeature Then Exit Sub
        'Break boundary into 5 vertices
    DoGetFeaturePointsEx ActiveImage.RegionFeatures, mcotSetNumbers, 5
End Sub 'DoSetNumbersOfVertices

Sub DoSetSpacingOfLineVertices()
    If CheckForNoLineFeature Then Exit Sub
        'Break polyline into vertices 20 units apart
    DoGetFeaturePointsEx ActiveImage.LineFeatures, mcotSetSpacing, 20
End Sub 'DoSetSpacingOfLineVertices

'Fill gaps
Sub DoBoundaryFillGaps()
    If CheckForNoRegionFeature Then Exit Sub
        'convert boundary into 1-pixel steps
    DoGetFeaturePointsEx ActiveImage.RegionFeatures, mcotNoGaps
End Sub 'DoBoundaryFillGaps

'Getting LONGPOINT results and 4-connected mcotNoGaps results on a McLines
Sub NoGapsLineWithAndWithout8Connect()
    With ActiveImage.LineFeatures
        .Reset
        ActiveImage.RegionFeatures.Reset
        ActiveImage.PointFeatures.Reset
        .SetFeaturePoints 0, Array(1, 1, 10, 10) 'line at 45 degrees
        .OptionFlags(mcofConnect8) = mcofConnect8 'make sure it's 8-connected
            'First, show the original vertices on a zoomed display
        ActiveWindow.View.Magnification = 16#  ' magnify the display
        Dim varPtsOriginal As Variant
        .GetFeaturePoints 0, varPtsOriginal
        ActiveImage.PointFeatures.SetFeaturePoints -1, varPtsOriginal
        MsgBox "The display shows the two original vertices of the 45 degree line segment"
            'Do the no-gaps Get the number of result points first
        Dim nPts As Long
        nPts = .GetFeaturePointsEx(0, , mcotNoGaps)
        ReDim ptsNoGaps(nPts - 1) As LONGPOINT
        .GetFeaturePointsEx 0, ptsNoGaps, mcotNoGaps
            'show the result
         ActiveImage.PointFeatures.SetFeaturePoints -1, ptsNoGaps
        MsgBox "The display shows the 8-connected no-gap vertices of the 45 degree line segment"
             'repeat no-gaps with the McLines 4-connected
        .OptionFlags(mcofConnect8) = mcofNoFlags 'make it 4-connected
        nPts = .GetFeaturePointsEx(0, , mcotNoGaps)
        ReDim ptsNoGaps(nPts - 1) As LONGPOINT
        .GetFeaturePointsEx 0, ptsNoGaps, mcotNoGaps
            'now show the result
         ActiveImage.PointFeatures.SetFeaturePoints -1, ptsNoGaps
        MsgBox "The display shows the 4-connected no-gap vertices of the 45 degree line segment"
            'restore the default 8-connected state,
        .OptionFlags(mcofConnect8) = mcofConnect8 'which is 8-connected
    End With 'ActiveImage.LineFeatures
End Sub 'NoGapsLineWithAndWithout8Connect

Examples

Copy

'Get convex hull of RegionFeatures feature zero
'get the convex hull of feature 0 as an array of SINGLEPOINT
Dim varConvexHull As Variant
varConvexHull = Empty
Dim lNumPoints As long
lNumPoints = ThisApplication.ActiveImage.RegionFeatures.GetFeaturePoints(0, varConvexHull, mcotConvex, , gfpxConstantArea)
'Or get the convex hull of feature 0 as an array of LONGPOINT
' get number of points
lNumPoints = ThisApplication.ActiveImage.RegionFeatures.GetFeaturePointsEx( 0, , mcotConvex, , gfpxConstantArea)
' get the points result as integral points
ReDim ptsConvex( lNumPoints-1) As LONGPOINT
ThisApplication.ActiveImage.RegionFeatures.GetFeaturePoints(0, ptsConvex, mcotConvex, , gfpxConstantArea)

Reference

IMcRegions2 Interface

MediaCy.IQL.Features Namespace

IMcRegions2GetFeaturePoints(Int32, Object)

IMcRegions2AddLanguageSpecificTextSet("LSTD5C1AB53_0?cpp=::|nu=.");GetFeaturePointsEx Method

Parameters

Return Value

Implements

Reference

IMcRegions2GetFeaturePointsEx Method