Object Model: Geometry.GetClosestLocationsWithinRadius

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