The nodes in the Geometry Queries category can be used to find and test locations on geometric objects. Locations are "glued" to the surface of a geometry so that they stay in the same relative position even as the geometry transforms and deforms, unless you recompute and reset the locations' values at different frames, for example, setting a new GoalLocation.
After you get locations, you can get other data at those locations as described in Getting Data at the Previous Frame. Alternatively, you can use those locations for other purposes, such as emitting points or setting goals.
Note that the geometry queries ignore the subdivision level, and always work with the unsubdivided surfaces of polygon meshes.
The Get Geometry Sample and Generate Sample Set nodes can be used to generate random locations on geometric objects.
The Get Geometry Sample node generates a single random location on a geometry for each member of a data set. For example, it can be used to create a GoalLocation per particle.
The Generate Sample Set node generates a set of random locations on a geometry. The number of locations is controlled by the rate. This node is typically used to generate locations for emitting particles.
Both the Get Geometry Sample and Generate Sample Set nodes allow you to filter the results. You can filter by any Boolean, integer, or scalar attribute available at the locations. For example, to filter based on cluster membership, use the IsElement attribute of the corresponding cluster.
You must use an existing attribute to filter — you cannot evaluate a tree. If necessary, you can store an attribute to read — you might want to use another tree on the geometry that you are reading from for this. Use the Invert check box to invert the condition used to filter.
In the case of scalars and integers, samples are generated where the attribute is non-zero. Attributes stored on points and nodes are averaged at locations according to the values of the corresponding triangle's points or nodes (integers are averaged and then rounded). If the value for a polygon or triangle value is between 0 and 1, then that value is the proportion of locations that will be kept (compared to the number that would be generated without filtering).
For the Generate Sample Set node, you can select either Exact Rate or Proportional to Filtered Area. For Exact Rate, the number of samples specified by the Rate value will be generated from the area where the filtering condition is satisfied. In the case of Proportional to Filtered Area, the number of locations specified by Rate will be generated across the entire surface or on all points, and then culled by the filtering condition.
The following nodes let you get locations according to specific criteria:
Get Closest Location returns the closest location on the surface of a geometric object.
Raycast returns the intersection of a line with a geometric object. You specify the direction and start position of the line.
Get Closest Points returns the locations of the closest vertices on a polygon mesh, or the closest knots on a curve or surface. The result is an array of locations for each member of the data set. Even if Max Number Points is 1, the result is still a set of arrays with one element per member and you must pop the location from the array before using it as a location, for example, setting it as GoalLocation. See Working with Arrays in ICE Trees.
These nodes can incur high processing costs. If possible, you should enable cutoff distances to reduce processing costs as much as possible.
You cannot set attributes at the locations returned by these nodes. If you want to, for example, set attributes on a mesh's points based on proximity to particles, you should get the mesh's point positions and test for distance to particles instead of the other way around.
There are a couple of nodes that can return a location based on other data:
ID to Location returns a location given a point ID. The ID attribute must have been initialized — see Working with IDs and Indices.
UV to Location returns a location given a 2D vector specifying the NURBS UV parameters. It works with surfaces as well as curves, in which case the V value is ignored. To work with texture UV coordinates rather than NURBS UV parameters, see Texture Maps in ICE.
There are several nodes that you can use to test locations:
Is on Surface tests whether a location is a valid location on a given surface. When a geometric object is connected to the Geometry port, a Geometry Location value of Undefined Location returns false. When no geometric object is connected, Undefined Location returns true and other locations return false.
Is Valid Location is a compound based on Is on Surface. It returns true if a location is valid on any geometric object in the scene.
Point in Volume tests whether a position is inside or outside the volume of a geometric object. When working with a location, you must get PointPosition at the location first.
The Group Geometry node combines several geometric objects. It is especially useful when building compounds because you can use it to create multi-instance ports, for example, for emitting from multiple surfaces.
To work with scene groups, see Setting Data.
The PointNeighbors attribute returns an array with the locations of the points that are connected to the points in the data set. This allows you to get any attribute at those locations.
You cannot get other component types, such as a point's connected edges, polygons, or nodes.
To test whether a location is in a cluster, get the IsElement attribute of the cluster at that location. You can then filter values or perform other actions based on the result.
The subtree above returns the point positions where the closest location on a geometry is in the Polygon cluster. Because the input to the Get Closest Location node is in the point context, any point data could be connected to the Filter node's Value input.
ICE trees cannot access the viewing normals used for shading. The PointNormal attribute represents the smoothed normal, and the NodeNormal attribute represents the unsmoothed normal.
The Undefined Location node returns a location that is undefined. For example, if you are setting locations based on a condition, you can use it to "fill in" values for members of the data set that don't meet the condition, and then elsewhere in the tree you can test for valid locations before using those locations.
Ports of type location that are not connected use a default value of Undefined Location.
