Create custom geometry queries

You can use the basic building blocks in the Geometry::Query namespace to create custom queries for special purposes. Custom queries involve three steps: first build an accelerator, then sample the accelerator, and finally sample the values of properties.

You can reuse the same acceleration structure to be more efficient in situations such as the following:

• Performing multiple queries on the same geometry, rather than simply sampling the same locations for multiple properties. For example, you can use multiple sets of positions with any query, as well as different directions for raycast queries.
• Getting locations inside a programming loop, such as when performing calculations for each point of an object. You can build the acceleration structure once outside the loop, instead than building it again and again inside the loop.

Look inside the high-level queries such as get_points_in_radius to get an idea of how the building blocks fit together. Here is a rough overview:

1. Build the appropriate acceleration structure. This should normally be done outside any programming loop such as a for_each compound. It can even be done outside a simulation loop, if the geometry is not moving or changing in any way during the simulation.

   • Use build_closest_accelerator for the closest location, closest point, or all points in a radius.
   • Use build_raycast_accelerator for raycasting.

2. Connect the object that you want to query into the geometry input.

3. Set geo_component to the appropriate value:

   • For locations on the surface of a mesh, set it to face_component or leave it blank. This is the only valid option for raycasting.
   • For locations along the length of strands, set it to strand_component or leave it blank.
   • For points on a points object, set it to point_component or leave it blank.
   • For points on a mesh or strands object, set it to point_component.

4. Connect the accelerator output to one or more of the following basic queries. Depending on the situation, the query might be inside a loop.

   • sample_raycast_accelerator for ray intersections.
   • sample_closest_accelerator for the closest locations.
   • sample_closest_point_accelerator for the closest points.
   • sample_closest_in_radius_accelerator for all points in a radius.

5. Set the other inputs of the query nodes as desired. They work in the same way as on the high-level queries.

6. Use the outputs of the query nodes to access the values of properties on the geometry:

   • You can connect the location output into one or more sample_property nodes to sample geo properties immediately (see Sample geo properties at locations). In these cases, you typically sample on the same geometry you connected to the get_closest_point node.
   • You can use the point_index output to access the data arrays of geo properties on the geometry (see Getting and setting properties of geometric objects).
   • Remember that the point_index output of sample_closest_in_radius_accelerator is a 2D array, and may require extra looping.
   • You can use the found output with if nodes to control what happens next in the graph on a per-position basis, including whether or not to sample properties. This is especially important when using the point_index output, because it will contain the index 0 or an empty array for positions that could not be successfully queried.
   • If the input positions correspond to the points of another geometric object, you can store the outputs as geo properties on that object to use them elsewhere. You can also cache them and use them for future frames in a simulation (see Create custom simulations).