## Geometry.GetClosestLocationsWithinRadius

### Introduced

v5.0

### Description

Returns a PointLocatorData containing closest surface locations from the input position within a search sphere of a specific radius. By default, the input positions have to be defined in the object's local space reference. Optionally, the search can be restricted to return a maximum number of locations. In order to avoid volumetric restrictions, simply specify a very large radius.
Some aspects of the closest locations's computation such as the reference pose or the method (closest surface, closest vertex or knot, ...) can be set up using Geometry.SetupPointLocatorQueries. This setup will affect all subsequent calls to GetClosestLocationsWithinRadius and to Geometry.GetClosestLocations.
If the search was set up with Geometry.SetupPointLocatorQueries to be a closest surface or smoothed closest surface search, then it returns one point locator per connected island for PolygonMeshes. Such connected islands are defined so that you cannot walk between 2 returned point locators without leaving the search radius (this walking is through polygon adjacency, not vertex adjacency). For NurbsSurfaceMeshes, it returns at most one point locator.
When you call this method an acceleration cache is automatically created. See Geometry.SetupPointLocatorQueries for more information.
Notice that the "closest distance" relationship may change relative to the spatial reference of the geometry and the input positions. See Geometry.SetupPointLocatorQueries for more information.
Notice that the returned point locators can be evaluated on any Geometry instance having the same topology.

### C# Syntax

    PointLocatorData Geometry.GetClosestLocationsWithinRadius( Object in_PositionToSearchFrom, Double in_dRadius, Int32 in_lNbToSearch );

### Scripting Syntax

    oReturn = Geometry.GetClosestLocationsWithinRadius( Position, Radius, [MaxNbToFind] );

### Return Value

PointLocatorData

### Parameters

Parameter | Type | Description
--- | --- | ---
Position | 1D Array or SIVector3 | The position to search from, either a vector or an XYZ array.
Radius | Double | Radius defining a spherical restriction volume for the search.
MaxNbToFind | Long | Maximum point locations to find (no limit if value is -1). Default Value: -1

### Examples

#### VBScript Example

    '
    ' This example uses PointLocatorData to find closest vertices on a polygon mesh
    ' within a specific radius, and then creates a cluster on these points.
    '
    NewScene , false
    set root = Application.ActiveSceneRoot
    set GridObj = root.AddGeometry("Grid", "MeshSurface")
    set GridGeom = GridObj.ActivePrimitive.Geometry
    Translate GridObj, 0, 0, -2.0, siRelative, siView, siObj, siXYZ
    ' Set up to closest vertex search
    GridGeom.SetupPointLocatorQueries siClosestVertexOrKnot, GridObj.Kinematics.Global.Transform, null, -1
    ' Get all vertices within a radius of 2 units relatively to the world center
    set PositionToQuery = XSIMath.CreateVector3()
    PositionToQuery.Set 0,0,0
    set PointLocatorsWithinTwoUnits = GridGeom.GetClosestLocationsWithinRadius(PositionToQuery, 2.0)
    VerticesString = " "
    Dim PtLocIndexToQuery(0)
    Dim ClosestVerticesArray()
    ReDim ClosestVerticesArray(PointLocatorsWithinTwoUnits.Count-1)
    for i = 0 to PointLocatorsWithinTwoUnits.Count-1
            ' Even though the point locators have be defined to exactly match the vertex
            ' positions, the search data is returned as a position on a specific triangle,
            ' just as any other use of the Point Locator.  However the vertex that matches
            ' can be determined because it will be weighted at 100%.
            PtLocIndexToQuery(0) = i
            SubTriangleVertices = GridGeom.GetTriangleVertexIndexArray(PointLocatorsWithinTwoUnits, PtLocIndexToQuery)
            SubTriangleWeights = GridGeom.GetTriangleWeightArray(PointLocatorsWithinTwoUnits, PtLocIndexToQuery)
            for ctr = 0 to UBound(SubTriangleVertices,2)
                    VtxIdx = SubTriangleVertices(0,ctr)
                    if SubTriangleWeights(1,ctr) > SubTriangleWeights(0,ctr) & SubTriangleWeights(1,ctr) > SubTriangleWeights(2,ctr) then
                            VtxIdx = SubTriangleVertices(1,ctr)
                    elseif SubTriangleWeights(2,ctr) > SubTriangleWeights(0,ctr) & SubTriangleWeights(2,ctr) > SubTriangleWeights(1,ctr) then
                            VtxIdx = SubTriangleVertices(2,ctr)
                    end if
                    ClosestVerticesArray(i) = VtxIdx
                    VerticesString = VerticesString & VtxIdx
                    if i <> PointLocatorsWithinTwoUnits.Count - 1 then
                            VerticesString = VerticesString & ", "
                    end if
            next
    next
    ' Create a cluster on these vertices
    GridGeom.AddCluster siVertexCluster, "ClosestVertices", ClosestVerticesArray
    Application.LogMessage "There are " & PointLocatorsWithinTwoUnits.Count & " grid vertices in the 2 unit sphere located at the world center."
    Application.LogMessage "These vertices are (ordered by proximity):"
    Application.LogMessage VerticesString
    ' Expected results:
    'INFO : There are 13 grid vertices in the 2 unit sphere located at the world center.
    'INFO : These vertices are (ordered by proximity):
    'INFO :  42, 51, 41, 33, 43, 52, 32, 50, 34, 24, 60, 40, 44

### See Also

PointLocatorData Geometry Geometry.GetClosestLocations Geometry.GetRaycastIntersections Geometry.SetupPointLocatorQueries Geometry.GetSurfacePointLocatorsFromPoints Geometry.EvaluatePositions Geometry.EvaluateNormals Geometry.EvaluateClusterProperty PolygonMesh.GetPolygonIndexArray PolygonMesh.GetTriangleVertexIndexArray PolygonMesh.GetTriangleNodeIndexArray PolygonMesh.GetTriangleWeightArray PolygonMesh.ConstructPointLocators NurbsSurfaceMesh.GetSubSurfaceIndexArray NurbsSurfaceMesh.GetNormalizedUVArray NurbsSurfaceMesh.ConstructPointLocators